An open source design system that's fully customizable and agent ready
TypeScript
docs(useHotkeys): add a search and help shortcuts example block (#9508)
Parman Mohammadalizadeh721bba9d6da4
diff --git a/.changeset/use-hotkeys-search-help-example.md b/.changeset/use-hotkeys-search-help-example.mdnew file mode 100644index 0000000000..d160c1bb80--- /dev/null+++ b/.changeset/use-hotkeys-search-help-example.md@@ -0,0 +1,7 @@+---+'@astryxdesign/cli': patch+---++[docs] A new `useHotkeys — Search and Help Shortcuts` example block shows the hook on a page header: "/" focuses the search field and "?" opens the shortcut help, typing either character in the field does not trigger them, and a switch turns the single-key shortcuts off through `isDisabled`. Copy it with `astryx template useHotkeysHookUsage <path>`.++@MannXodiff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.jsonindex dbf3d77330..537c1e3094 100644--- a/apps/sandbox/scripts/next-export-routes.json+++ b/apps/sandbox/scripts/next-export-routes.json@@ -789,6 +789,7 @@"/templates/useContainerRevealHookUsage/","/templates/useFocusTrapHookUsage/","/templates/useGridFocusHookUsage/",+ "/templates/useHotkeysHookUsage/","/templates/useKeyboardHintHookUsage/","/templates/useListFocusHookUsage/","/templates/useLocaleHookUsage/",diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.jsonindex 92b00463a1..73fd3c33ee 100644--- a/internal/shadcn-registry/routes.lock.json+++ b/internal/shadcn-registry/routes.lock.json@@ -3681,6 +3681,11 @@"path": "examples/use-grid-focus/color-swatch-grid","aliases": []},+ {+ "name": "example-use-hotkeys-search-and-help-shortcuts",+ "path": "examples/use-hotkeys/search-and-help-shortcuts",+ "aliases": []+ },{"name": "example-use-hover-card-profile-preview","path": "examples/use-hover-card/profile-preview",diff --git a/packages/cli/api/template/use-hotkeys-hook-usage.test.tsx b/packages/cli/api/template/use-hotkeys-hook-usage.test.tsxnew file mode 100644index 0000000000..aa94b4c5c6--- /dev/null+++ b/packages/cli/api/template/use-hotkeys-hook-usage.test.tsx@@ -0,0 +1,111 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @vitest-environment jsdom++/**+ * The useHotkeys example registers "/" and "?" on the window: "/" focuses+ * the search field and "?" opens the help dialog, typing either one in the+ * field does not trigger them, and the switch turns both off.+ */++import {act} from 'react';+import {createRoot, type Root} from 'react-dom/client';+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import UseHotkeysHookUsage from '../../assets/templates/blocks/components/Hooks/useHotkeysHookUsage';++(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(<UseHotkeysHookUsage />);+ });+}++function searchInput(): HTMLInputElement {+ const input = container.querySelector<HTMLInputElement>('input[type="text"]');+ if (input == null) {+ throw new Error('no search field rendered');+ }+ return input;+}++function press(+ key: string,+ target: EventTarget = document.body,+): KeyboardEvent {+ const event = new KeyboardEvent('keydown', {+ key,+ bubbles: true,+ cancelable: true,+ });+ act(() => {+ target.dispatchEvent(event);+ });+ return event;+}++function isHelpOpen(): boolean {+ return document.querySelector('dialog[open]') != null;+}++beforeEach(() => {+ // This jsdom has no CSS.escape, which Dialog uses to find its title.+ vi.stubGlobal('CSS', {+ escape: (value: string) =>+ value.replace(/[^\w-]/gu, character => `\\${character}`),+ });+ // jsdom does not implement the modal dialog methods.+ HTMLDialogElement.prototype.showModal = vi.fn(function (+ this: HTMLDialogElement,+ ) {+ this.setAttribute('open', '');+ });+ HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {+ this.removeAttribute('open');+ });+});++afterEach(() => {+ act(() => root?.unmount());+ root = null;+ container.remove();+ vi.unstubAllGlobals();+});++describe('useHotkeys example', () => {+ it('focuses search on "/" and opens the help on "?"', () => {+ renderExample();+ press('/');+ expect(document.activeElement).toBe(searchInput());+ act(() => searchInput().blur());+ press('?');+ expect(isHelpOpen()).toBe(true);+ });++ it('ignores both keys while typing in the search field', () => {+ renderExample();+ act(() => searchInput().focus());+ expect(press('/', searchInput()).defaultPrevented).toBe(false);+ press('?', searchInput());+ expect(isHelpOpen()).toBe(false);+ });++ it('turns both shortcuts off with the switch', () => {+ renderExample();+ const toggle = container.querySelector<HTMLInputElement>(+ 'input[role="switch"], input[type="checkbox"]',+ );+ expect(toggle).not.toBeNull();+ act(() => toggle?.click());+ press('/');+ expect(document.activeElement).not.toBe(searchInput());+ press('?');+ expect(isHelpOpen()).toBe(false);+ });+});diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useHotkeysHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Hooks/useHotkeysHookUsage.doc.mjsnew file mode 100644index 0000000000..e320f96d9e--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/Hooks/useHotkeysHookUsage.doc.mjs@@ -0,0 +1,23 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */+export const doc = {+ type: 'block',+ exampleFor: 'useHotkeys',+ name: 'useHotkeys — Search and Help Shortcuts',+ displayName: 'useHotkeys — Search and Help Shortcuts',+ description:+ 'Page shortcuts registered with useHotkeys: "/" focuses the search field and "?" opens the shortcut help, while typing either character in the field just types it. A switch turns the single-key shortcuts off through isDisabled.',+ isReady: true,+ aspectRatio: 4 / 3,+ componentsUsed: [+ 'Card',+ 'TextInput',+ 'Button',+ 'Switch',+ 'Dialog',+ 'Kbd',+ 'Text',+ 'Layout',+ ],+};diff --git a/packages/cli/assets/templates/blocks/components/Hooks/useHotkeysHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Hooks/useHotkeysHookUsage.tsxnew file mode 100644index 0000000000..7c4ee3f9ab--- /dev/null+++ b/packages/cli/assets/templates/blocks/components/Hooks/useHotkeysHookUsage.tsx@@ -0,0 +1,90 @@+// 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 {Dialog, DialogHeader} from '@astryxdesign/core/Dialog';+import {useHotkeys} from '@astryxdesign/core/hooks';+import {Kbd} from '@astryxdesign/core/Kbd';+import {+ HStack,+ Layout,+ LayoutContent,+ StackItem,+ VStack,+} from '@astryxdesign/core/Layout';+import {Switch} from '@astryxdesign/core/Switch';+import {Text} from '@astryxdesign/core/Text';+import {TextInput} from '@astryxdesign/core/TextInput';++export default function UseHotkeysHookUsage() {+ const searchRef = useRef<HTMLInputElement>(null);+ const [query, setQuery] = useState('');+ const [isHelpOpen, setIsHelpOpen] = useState(false);+ // Single-character shortcuts need an off switch (WCAG 2.1.4).+ const [hasShortcuts, setHasShortcuts] = useState(true);++ useHotkeys([+ {+ keys: '/',+ onPress: () => searchRef.current?.focus(),+ isDisabled: !hasShortcuts,+ },+ {+ keys: '?',+ onPress: () => setIsHelpOpen(true),+ isDisabled: !hasShortcuts,+ },+ ]);++ return (+ <Card width={480} padding={4}>+ <VStack gap={3}>+ <HStack gap={2} vAlign="center">+ <StackItem size="fill">+ <TextInput+ ref={searchRef}+ label="Search"+ isLabelHidden+ placeholder="Search projects"+ value={query}+ onChange={setQuery}+ />+ </StackItem>+ <Button label="Shortcuts" onClick={() => setIsHelpOpen(true)} />+ </HStack>+ <Switch+ label="Single-key shortcuts"+ value={hasShortcuts}+ onChange={setHasShortcuts}+ />+ </VStack>+ <Dialog isOpen={isHelpOpen} onOpenChange={setIsHelpOpen}>+ <Layout+ header={+ <DialogHeader+ title="Keyboard shortcuts"+ onOpenChange={setIsHelpOpen}+ />+ }+ content={+ <LayoutContent>+ <VStack gap={2}>+ <HStack gap={2} vAlign="center">+ <Kbd keys="/" />+ <Text type="body">Focus search</Text>+ </HStack>+ <HStack gap={2} vAlign="center">+ <Kbd keys="?" />+ <Text type="body">Show this help</Text>+ </HStack>+ </VStack>+ </LayoutContent>+ }+ />+ </Dialog>+ </Card>+ );+}diff --git a/packages/cli/test/__golden__/no-icon-set/search-search.json b/packages/cli/test/__golden__/no-icon-set/search-search.jsonindex c3e974f297..f5663523c8 100644--- a/packages/cli/test/__golden__/no-icon-set/search-search.json+++ b/packages/cli/test/__golden__/no-icon-set/search-search.json@@ -3,7 +3,7 @@"type": "search","data": {"query": "search",- "matchCount": 114,+ "matchCount": 115,"results": [{"domain": "doc",diff --git a/packages/cli/test/__golden__/no-icon-set/search-search.txt b/packages/cli/test/__golden__/no-icon-set/search-search.txtindex 180a04f4d9..bde7338d7d 100644--- a/packages/cli/test/__golden__/no-icon-set/search-search.txt+++ b/packages/cli/test/__golden__/no-icon-set/search-search.txt@@ -1,4 +1,4 @@-Results for "search" (20 of 114)+Results for "search" (20 of 115)name: cli/api/functions/searchdomain: docpackage: @astryxdesign/cli