Skip to content

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.md
new file mode 100644
index 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>`.
+
+@MannXo
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index 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.json
index 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.tsx
new file mode 100644
index 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.mjs
new file mode 100644
index 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.tsx
new file mode 100644
index 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.json
index 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.txt
index 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/search
domain: doc
package: @astryxdesign/cli