Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(useClickableContainer): add a clickable project card example block (#9596)

Parman Mohammadalizadehf9ba0f03be22
diff --git a/.changeset/use-clickable-container-project-card-example.md b/.changeset/use-clickable-container-project-card-example.md
new file mode 100644
index 0000000000..e93ddebf4d
--- /dev/null
+++ b/.changeset/use-clickable-container-project-card-example.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[docs] A new `useClickableContainer — Clickable Project Card` example block makes a project card clickable anywhere with `useClickableContainer`: a click on the card follows its title link, while the Star button, the owner link and a text selection keep their own behavior, and Ctrl/Cmd+click or middle-click opens the project in a new tab. Copy it with `astryx template useClickableContainerHookUsage <path>`.
+
+@MannXo
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 7660143cab..c0fcdf2226 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -784,6 +784,7 @@
"/templates/table/",
"/templates/theme-showcase/",
"/templates/useAnnounceHookUsage/",
+ "/templates/useClickableContainerHookUsage/",
"/templates/useClipboardHookUsage/",
"/templates/useCollatorHookUsage/",
"/templates/useComboboxHookUsage/",
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index 22178c1ee5..91fafc7483 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3651,6 +3651,11 @@
"path": "examples/use-app-shell-mobile/custom-mobile-trigger",
"aliases": []
},
+ {
+ "name": "example-use-clickable-container-clickable-project-card",
+ "path": "examples/use-clickable-container/clickable-project-card",
+ "aliases": []
+ },
{
"name": "example-use-clipboard-share-link",
"path": "examples/use-clipboard/share-link",
diff --git a/packages/cli/api/template/use-clickable-container-hook-usage.test.tsx b/packages/cli/api/template/use-clickable-container-hook-usage.test.tsx
new file mode 100644
index 0000000000..5dff7a7afa
--- /dev/null
+++ b/packages/cli/api/template/use-clickable-container-hook-usage.test.tsx
@@ -0,0 +1,104 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @vitest-environment jsdom
+
+/**
+ * The useClickableContainer example opens its project from anywhere on the
+ * card, while the Star button, the owner link and a text selection keep their
+ * own behavior. Modifier and middle clicks open the project in a new tab.
+ */
+
+import {act} from 'react';
+import {createRoot, type Root} from 'react-dom/client';
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import UseClickableContainerHookUsage from '../../assets/templates/blocks/components/Hooks/useClickableContainerHookUsage';
+
+(globalThis as {IS_REACT_ACT_ENVIRONMENT?: boolean}).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+const PROJECT_HREF = '#project-design-tokens';
+
+let root: Root | null = null;
+let container: HTMLElement;
+
+function renderExample(): void {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ act(() => {
+ root = createRoot(container);
+ root.render(<UseClickableContainerHookUsage />);
+ });
+}
+
+function byText(text: string): HTMLElement {
+ const match = Array.from(container.querySelectorAll<HTMLElement>('*')).find(
+ element =>
+ element.children.length === 0 && element.textContent?.includes(text),
+ );
+ if (match == null) {
+ throw new Error(`nothing rendered "${text}"`);
+ }
+ return match;
+}
+
+function description(): HTMLElement {
+ return byText('Color, spacing and type tokens');
+}
+
+function press(
+ target: Element,
+ type: 'click' | 'mouseup',
+ init: MouseEventInit = {},
+): void {
+ act(() => {
+ target.dispatchEvent(
+ new MouseEvent(type, {bubbles: true, cancelable: true, ...init}),
+ );
+ });
+}
+
+function openedText(): string {
+ return byText('Project opened').textContent ?? '';
+}
+
+afterEach(() => {
+ act(() => root?.unmount());
+ root = null;
+ container.remove();
+ document.getSelection()?.removeAllRanges();
+ vi.restoreAllMocks();
+});
+
+describe('useClickableContainer example', () => {
+ it('opens the project from a click anywhere on the card', () => {
+ renderExample();
+ press(description(), 'click');
+ expect(openedText()).toBe('Project opened 1 time');
+ });
+
+ it('lets the Star button and the owner link keep their own behavior', () => {
+ renderExample();
+ press(byText('Star'), 'click');
+ expect(byText('Starred')).toBeTruthy();
+
+ press(byText('Design Systems'), 'click');
+ expect(openedText()).toBe('Project opened 0 times');
+ });
+
+ it('does not open the project when the click ends a text selection', () => {
+ renderExample();
+ document.getSelection()?.selectAllChildren(description());
+ press(description(), 'click');
+ expect(openedText()).toBe('Project opened 0 times');
+ });
+
+ it('opens the project in a new tab on Ctrl/Cmd+click and middle-click', () => {
+ const open = vi.spyOn(window, 'open').mockImplementation(() => null);
+ renderExample();
+ press(description(), 'click', {ctrlKey: true});
+ press(description(), 'click', {metaKey: true});
+ press(description(), 'mouseup', {button: 1});
+ expect(open).toHaveBeenCalledTimes(3);
+ expect(open).toHaveBeenCalledWith(PROJECT_HREF, '_blank', 'noopener');
+ expect(openedText()).toBe('Project opened 0 times');
+ });
+});
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useClickableContainerHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Hooks/useClickableContainerHookUsage.doc.mjs
new file mode 100644
index 0000000000..67a3224c31
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useClickableContainerHookUsage.doc.mjs
@@ -0,0 +1,14 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useClickableContainer',
+ name: 'useClickableContainer — Clickable Project Card',
+ displayName: 'useClickableContainer — Clickable Project Card',
+ description:
+ 'A project card that useClickableContainer makes clickable anywhere: a click on the card follows its title link, while the Star button, the owner link and a text selection keep their own behavior, and Ctrl/Cmd+click or middle-click opens the project in a new tab.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Card', 'Button', 'Link', 'Text', 'Layout'],
+};
diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useClickableContainerHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Hooks/useClickableContainerHookUsage.tsx
new file mode 100644
index 0000000000..3feb69582c
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Hooks/useClickableContainerHookUsage.tsx
@@ -0,0 +1,67 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {useRef, useState} from 'react';
+import {Button} from '@astryxdesign/core/Button';
+import {Card} from '@astryxdesign/core/Card';
+import {useClickableContainer} from '@astryxdesign/core/hooks';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Link} from '@astryxdesign/core/Link';
+import {Heading, Text} from '@astryxdesign/core/Text';
+
+const PROJECT_HREF = '#project-design-tokens';
+
+export default function UseClickableContainerHookUsage() {
+ const containerRef = useRef<HTMLDivElement>(null);
+ const projectLinkRef = useRef<HTMLAnchorElement | HTMLButtonElement>(null);
+ const [openCount, setOpenCount] = useState(0);
+ const [isStarred, setIsStarred] = useState(false);
+ const {onClick, onMouseUp} = useClickableContainer({
+ containerRef,
+ interactiveRef: projectLinkRef,
+ href: PROJECT_HREF,
+ });
+
+ return (
+ <VStack gap={3}>
+ <Card
+ ref={containerRef}
+ onClick={onClick}
+ onMouseUp={onMouseUp}
+ width={360}
+ padding={4}>
+ <VStack gap={2}>
+ <HStack gap={2} justify="between" vAlign="center">
+ <Heading level={4}>
+ <Link
+ ref={projectLinkRef}
+ href={PROJECT_HREF}
+ type="inherit"
+ onClick={() => setOpenCount(count => count + 1)}>
+ Design tokens
+ </Link>
+ </Heading>
+ <Button
+ label={isStarred ? 'Starred' : 'Star'}
+ variant="secondary"
+ onClick={() => setIsStarred(starred => !starred)}
+ />
+ </HStack>
+ <Text type="body" color="secondary">
+ Color, spacing and type tokens shared by every product surface.
+ </Text>
+ <Text type="supporting" color="secondary">
+ Owned by{' '}
+ <Link href="#team-design-systems" type="inherit">
+ Design Systems
+ </Link>
+ </Text>
+ </VStack>
+ </Card>
+ <Text type="supporting">
+ Project opened {openCount} {openCount === 1 ? 'time' : 'times'}
+ </Text>
+ </VStack>
+ );
+}