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.mdnew file mode 100644index 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>`.++@MannXodiff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.jsonindex 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.jsonindex 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.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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>+ );+}