Skip to content

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.md
new file mode 100644
index 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-rong
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 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.json
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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>
+ );
+}