An open source design system that's fully customizable and agent ready
TypeScript
docs(useListFocus): add a recent files example block (#9577)
홍규진e0548a6475d7
diff --git a/.changeset/use-list-focus-recent-files-example.md b/.changeset/use-list-focus-recent-files-example.mdnew file mode 100644index 0000000000..5b3c40d144--- /dev/null+++ b/.changeset/use-list-focus-recent-files-example.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] A new `useListFocus — Recent Files` example block gives a list of buttons keyboard navigation from `useListFocus`: ArrowUp and ArrowDown move between rows, Home and End jump to the first and last row, focus wraps at the ends, and only one row is in the tab order. Copy it with `astryx template useListFocusHookUsage <path>`.++@kyu-rongdiff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.jsonindex 244bdcc9f2..37ed6942b0 100644--- a/apps/sandbox/scripts/next-export-routes.json+++ b/apps/sandbox/scripts/next-export-routes.json@@ -783,6 +783,7 @@"/templates/useCollatorHookUsage/","/templates/useContainerRevealHookUsage/","/templates/useKeyboardHintHookUsage/",+ "/templates/useListFocusHookUsage/","/templates/usePressFeedbackHookUsage/","/templates/useStreamingTextHookUsage/","/templates/useThemeHookUsage/",diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.jsonindex 0dd007c6f3..cf8945d5f4 100644--- a/internal/shadcn-registry/routes.lock.json+++ b/internal/shadcn-registry/routes.lock.json@@ -3669,6 +3669,11 @@"path": "examples/use-layer/anchored-layer","aliases": []},+ {+ "name": "example-use-list-focus-recent-files",+ "path": "examples/use-list-focus/recent-files",+ "aliases": []+ },{"name": "example-use-popover-quick-actions","path": "examples/use-popover/quick-actions",diff --git a/packages/cli/api/template/use-list-focus-hook-usage.test.tsx b/packages/cli/api/template/use-list-focus-hook-usage.test.tsxnew file mode 100644index 0000000000..ff5477d33d--- /dev/null+++ b/packages/cli/api/template/use-list-focus-hook-usage.test.tsx@@ -0,0 +1,87 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @vitest-environment jsdom++/**+ * The useListFocus example moves focus between its rows from the keyboard:+ * arrows step and wrap, Home and End jump to the ends, and only one row is in+ * the tab order. Arrow keys move that tab stop with focus.+ */++import {act} from 'react';+import {createRoot, type Root} from 'react-dom/client';+import {afterEach, describe, expect, it} from 'vitest';+import UseListFocusHookUsage from '../../assets/templates/blocks/components/Hooks/useListFocusHookUsage';++(globalThis as {IS_REACT_ACT_ENVIRONMENT?: boolean}).IS_REACT_ACT_ENVIRONMENT =+ true;++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(<UseListFocusHookUsage />);+ });+}++function rows(): HTMLButtonElement[] {+ return Array.from(container.querySelectorAll('button'));+}++function focusedRow(): string | undefined {+ return document.activeElement?.textContent ?? undefined;+}++function tabbableRows(): string[] {+ return rows()+ .filter(row => row.getAttribute('tabindex') !== '-1')+ .map(row => row.textContent ?? '');+}++function press(key: string): void {+ act(() => {+ document.activeElement?.dispatchEvent(+ new KeyboardEvent('keydown', {key, bubbles: true, cancelable: true}),+ );+ });+}++afterEach(() => {+ act(() => root?.unmount());+ root = null;+ container.remove();+});++describe('useListFocus example', () => {+ it('puts only the first row in the tab order', () => {+ renderExample();+ expect(tabbableRows()).toEqual(['Q3 roadmap.pdf']);+ });++ it('moves focus and the tab stop with ArrowDown and ArrowUp', () => {+ renderExample();+ act(() => rows()[0].focus());+ press('ArrowDown');+ expect(focusedRow()).toBe('Budget 2026.xlsx');+ expect(tabbableRows()).toEqual(['Budget 2026.xlsx']);+ press('ArrowUp');+ expect(focusedRow()).toBe('Q3 roadmap.pdf');+ expect(tabbableRows()).toEqual(['Q3 roadmap.pdf']);+ });++ it('jumps with Home and End and wraps at the ends', () => {+ renderExample();+ act(() => rows()[0].focus());+ press('End');+ expect(focusedRow()).toBe('Launch checklist.md');+ press('ArrowDown');+ expect(focusedRow()).toBe('Q3 roadmap.pdf');+ press('ArrowUp');+ expect(focusedRow()).toBe('Launch checklist.md');+ press('Home');+ expect(focusedRow()).toBe('Q3 roadmap.pdf');+ });+});diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useListFocusHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Hooks/useListFocusHookUsage.doc.mjsnew file mode 100644index 0000000000..549237656e--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/Hooks/useListFocusHookUsage.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: 'useListFocus',+ name: 'useListFocus — Recent Files',+ displayName: 'useListFocus — Recent Files',+ description:+ 'A "Recent files" list of buttons with keyboard navigation from useListFocus: ArrowUp and ArrowDown move between rows, Home and End jump to the first and last row, focus wraps at the ends, and only one row is in the tab order.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: ['Card', 'Button', 'Layout'],+};diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useListFocusHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Hooks/useListFocusHookUsage.tsxnew file mode 100644index 0000000000..20d236047b--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/Hooks/useListFocusHookUsage.tsx@@ -0,0 +1,42 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++import {Button} from '@astryxdesign/core/Button';+import {Card} from '@astryxdesign/core/Card';+import {useListFocus} from '@astryxdesign/core/hooks';+import {VStack} from '@astryxdesign/core/Layout';++const RECENT_FILES = [+ 'Q3 roadmap.pdf',+ 'Budget 2026.xlsx',+ 'Offsite notes.docx',+ 'Launch checklist.md',+];++export default function UseListFocusHookUsage() {+ const {listRef, handleKeyDown, handleFocus} = useListFocus({+ itemSelector: 'button',+ orientation: 'vertical',+ wrap: true,+ hasHomeEnd: true,+ hasRovingTabIndex: true,+ });++ return (+ <Card width={320} padding={2}>+ <VStack+ ref={listRef}+ role="toolbar"+ aria-label="Recent files"+ aria-orientation="vertical"+ gap={1}+ onKeyDown={handleKeyDown}+ onFocus={handleFocus}>+ {RECENT_FILES.map(name => (+ <Button key={name} label={name} variant="ghost" />+ ))}+ </VStack>+ </Card>+ );+}