Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(useIcon): add hook docs and a status row example block (#9900)

Parman Mohammadalizadehf384e62f5c46
diff --git a/.changeset/hook-doc-use-icon.md b/.changeset/hook-doc-use-icon.md
new file mode 100644
index 0000000000..15b5f9e0fd
--- /dev/null
+++ b/.changeset/hook-doc-use-icon.md
@@ -0,0 +1,8 @@
+---
+'@astryxdesign/core': patch
+'@astryxdesign/cli': patch
+---
+
+[docs] Hook docs for `useIcon`, so `astryx hook useIcon` and `astryx search` return it, and a `useIcon — Status Row` example block: a custom status row draws the success, warning and error icons with `useIcon`, and under a Theme that overrides those icons the same row draws the theme's icons. Copy it with `astryx template useIconHookUsage <path>`.
+
+@MannXo
diff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.json
index fdd806593e..2e82f3b49d 100644
--- a/apps/sandbox/scripts/next-export-routes.json
+++ b/apps/sandbox/scripts/next-export-routes.json
@@ -795,6 +795,7 @@
"/templates/useFocusTrapHookUsage/",
"/templates/useGridFocusHookUsage/",
"/templates/useHotkeysHookUsage/",
+ "/templates/useIconHookUsage/",
"/templates/useImageModeHookUsage/",
"/templates/useInputStatusIconHookUsage/",
"/templates/useKeyboardHintHookUsage/",
diff --git a/internal/interaction-harness/src/busy.ts b/internal/interaction-harness/src/busy.ts
index 2add207346..d025502b52 100644
--- a/internal/interaction-harness/src/busy.ts
+++ b/internal/interaction-harness/src/busy.ts
@@ -921,7 +921,9 @@ export function busyWindowProof(
// when it and the block's first frame are both within the bound.
let before: (typeof valued)[number] | undefined;
for (const f of valued) {
- if (f.t >= window.from) break;
+ if (f.t >= window.from) {
+ break;
+ }
before = f;
}
const firstInBlock = valued.find(f => f.t >= window.from);
diff --git a/internal/shadcn-registry/routes.lock.json b/internal/shadcn-registry/routes.lock.json
index d934cfc0ca..6f912c9749 100644
--- a/internal/shadcn-registry/routes.lock.json
+++ b/internal/shadcn-registry/routes.lock.json
@@ -3716,6 +3716,11 @@
"path": "examples/use-hover-card/profile-preview",
"aliases": []
},
+ {
+ "name": "example-use-icon-status-row",
+ "path": "examples/use-icon/status-row",
+ "aliases": []
+ },
{
"name": "example-use-image-mode-photo-caption",
"path": "examples/use-image-mode/photo-caption",
@@ -3956,6 +3961,11 @@
"path": "hooks/use-hover-card",
"aliases": []
},
+ {
+ "name": "hook-use-icon",
+ "path": "hooks/use-icon",
+ "aliases": []
+ },
{
"name": "hook-use-image-mode",
"path": "hooks/use-image-mode",
diff --git a/packages/cli/api/component/__fixtures__/resolutions/modules.txt b/packages/cli/api/component/__fixtures__/resolutions/modules.txt
index a1af0d42fe..80d6e95e87 100644
--- a/packages/cli/api/component/__fixtures__/resolutions/modules.txt
+++ b/packages/cli/api/component/__fixtures__/resolutions/modules.txt
@@ -264,7 +264,7 @@ useEndLaneReserve useEndLaneReserve Tokenizer/Tokenizer.doc.mjs Tokenizer/useEnd
useFieldStatusAnnouncement useFieldStatusAnnouncement FieldStatus/FieldStatus.doc.mjs FieldStatus/useFieldStatusAnnouncement.ts
useFocusReturnVisibility useFocusReturnVisibility hooks/useAnimatedLayout.doc.mjs hooks/useFocusReturnVisibility.ts
useHighlightedOptionScroll useHighlightedOptionScroll hooks/useAnimatedLayout.doc.mjs hooks/useHighlightedOptionScroll.ts
-useIcon useIcon Icon/Icon.doc.mjs Icon/useIcon.ts
+useIcon useIcon Icon/useIcon.doc.mjs Icon/useIcon.ts
useIndicator useIndicator Indicator/Indicator.doc.mjs Indicator/useIndicator.ts
useInternalConfig useInternalConfig PowerSearch/PowerSearch.doc.mjs PowerSearch/useInternalConfig.ts
useIsHydrating useIsHydrating hooks/useAnimatedLayout.doc.mjs hooks/useIsHydrating.ts
diff --git a/packages/cli/api/template/use-icon-hook-usage.test.tsx b/packages/cli/api/template/use-icon-hook-usage.test.tsx
new file mode 100644
index 0000000000..46900d975a
--- /dev/null
+++ b/packages/cli/api/template/use-icon-hook-usage.test.tsx
@@ -0,0 +1,88 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+// @vitest-environment jsdom
+
+/**
+ * The useIcon example renders one status row under the current theme and under
+ * a Theme that overrides the success, warning and error icons. The row's icons
+ * follow the theme with no change to the row. It renders under an app's root
+ * Theme, as on the docs site.
+ */
+
+import {act} from 'react';
+import {createRoot, type Root} from 'react-dom/client';
+import {afterEach, beforeEach, describe, expect, it} from 'vitest';
+import {Theme, defineTheme} from '@astryxdesign/core/theme';
+import UseIconHookUsage from '../../assets/templates/blocks/components/Icon/useIconHookUsage';
+
+(globalThis as {IS_REACT_ACT_ENVIRONMENT?: boolean}).IS_REACT_ACT_ENVIRONMENT =
+ true;
+
+const appTheme = defineTheme({name: 'use-icon-test-app'});
+
+let root: Root | null = null;
+let container: HTMLElement;
+
+function rowIcons(caption: string): SVGElement[] {
+ const label = Array.from(container.querySelectorAll('span')).find(
+ span => span.textContent === caption,
+ );
+ const section = label?.parentElement;
+ if (section == null) {
+ throw new Error(`no status row captioned "${caption}"`);
+ }
+ return Array.from(section.querySelectorAll('svg'));
+}
+
+beforeEach(() => {
+ container = document.createElement('div');
+ document.body.appendChild(container);
+ act(() => {
+ root = createRoot(container);
+ root.render(
+ <Theme theme={appTheme}>
+ <UseIconHookUsage />
+ </Theme>,
+ );
+ });
+});
+
+afterEach(() => {
+ act(() => root?.unmount());
+ root = null;
+ container.remove();
+});
+
+describe('useIcon example', () => {
+ it('draws the built-in status icons under the current theme', () => {
+ const icons = rowIcons('Current theme');
+ expect(icons).toHaveLength(3);
+ for (const icon of icons) {
+ expect(icon.getAttribute('data-slot')).toBeNull();
+ }
+ });
+
+ it("draws the overriding Theme's icons in the same row component", () => {
+ const icons = rowIcons('Theme with its own status icons');
+ expect(icons).toHaveLength(3);
+ for (const icon of icons) {
+ expect(icon.getAttribute('data-slot')).toBe('icon');
+ }
+ expect(icons.map(icon => icon.innerHTML)).not.toEqual(
+ rowIcons('Current theme').map(icon => icon.innerHTML),
+ );
+ });
+
+ it("keeps the page's color mode inside the overriding Theme", () => {
+ act(() =>
+ root?.render(
+ <Theme theme={appTheme} mode="dark">
+ <UseIconHookUsage />
+ </Theme>,
+ ),
+ );
+ const nested = container.querySelector(
+ '[data-astryx-theme="status-icons-docs"]',
+ );
+ expect(nested?.getAttribute('data-theme')).toBe('dark');
+ });
+});
diff --git a/packages/cli/assets/templates/blocks/components/Icon/useIconHookUsage.doc.mjs b/packages/cli/assets/templates/blocks/components/Icon/useIconHookUsage.doc.mjs
new file mode 100644
index 0000000000..cd212a6da6
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Icon/useIconHookUsage.doc.mjs
@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').TemplateDoc} */
+export const doc = {
+ type: 'block',
+ exampleFor: 'useIcon',
+ name: 'useIcon — Status Row',
+ displayName: 'useIcon — Status Row',
+ description:
+ 'A custom status row that draws the semantic success, warning and error icons with useIcon. The same row renders under the current theme and under a Theme whose icons override those three, and its icons change with no change to the component.',
+ isReady: true,
+ aspectRatio: 4 / 3,
+ componentsUsed: ['Theme', 'Layout', 'Text'],
+ icons: {
+ CheckBadgeIcon: 'success',
+ ExclamationCircleIcon: 'warning',
+ NoSymbolIcon: 'error',
+ },
+};
diff --git a/packages/cli/assets/templates/blocks/components/Icon/useIconHookUsage.tsx b/packages/cli/assets/templates/blocks/components/Icon/useIconHookUsage.tsx
new file mode 100644
index 0000000000..1acdf81c06
--- /dev/null
+++ b/packages/cli/assets/templates/blocks/components/Icon/useIconHookUsage.tsx
@@ -0,0 +1,68 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+import {
+ CheckBadgeIcon,
+ ExclamationCircleIcon,
+ NoSymbolIcon,
+} from '@heroicons/react/24/solid';
+import {useIcon} from '@astryxdesign/core/Icon';
+import {HStack, VStack} from '@astryxdesign/core/Layout';
+import {Text} from '@astryxdesign/core/Text';
+import {Theme, defineTheme, useTheme} from '@astryxdesign/core/theme';
+
+const statusIconTheme = defineTheme({
+ name: 'status-icons-docs',
+ icons: {
+ success: <CheckBadgeIcon width="1em" height="1em" />,
+ warning: <ExclamationCircleIcon width="1em" height="1em" />,
+ error: <NoSymbolIcon width="1em" height="1em" />,
+ },
+});
+
+function StatusRow() {
+ const success = useIcon('success');
+ const warning = useIcon('warning');
+ const error = useIcon('error');
+
+ return (
+ <HStack gap={4}>
+ <HStack gap={1} vAlign="center">
+ {success}
+ <Text type="body">Passed</Text>
+ </HStack>
+ <HStack gap={1} vAlign="center">
+ {warning}
+ <Text type="body">Flaky</Text>
+ </HStack>
+ <HStack gap={1} vAlign="center">
+ {error}
+ <Text type="body">Failed</Text>
+ </HStack>
+ </HStack>
+ );
+}
+
+export default function UseIconHookUsage() {
+ const {mode} = useTheme();
+
+ return (
+ <VStack gap={4}>
+ <VStack gap={2}>
+ <Text type="supporting" color="secondary">
+ Current theme
+ </Text>
+ <StatusRow />
+ </VStack>
+ <Theme theme={statusIconTheme} mode={mode}>
+ <VStack gap={2}>
+ <Text type="supporting" color="secondary">
+ Theme with its own status icons
+ </Text>
+ <StatusRow />
+ </VStack>
+ </Theme>
+ </VStack>
+ );
+}
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon-set.json b/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
index e6d0b16836..550ae1e9fa 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon-set.json
@@ -3,7 +3,7 @@
"type": "search",
"data": {
"query": "icon set",
- "matchCount": 381,
+ "matchCount": 383,
"results": [
{
"domain": "doc",
@@ -116,6 +116,17 @@
"command": "astryx component InfoTip",
"mentions": []
},
+ {
+ "domain": "hook",
+ "name": "useIcon",
+ "package": "@astryxdesign/core",
+ "score": "<text>",
+ "reason": "<text>",
+ "description": "<text>",
+ "import": "@astryxdesign/core/Icon",
+ "command": "astryx hook useIcon",
+ "mentions": []
+ },
{
"domain": "hook",
"name": "useInputContainer",
@@ -233,18 +244,6 @@
"kind": "block",
"command": "astryx template CenterHorizontal --type block",
"mentions": []
- },
- {
- "domain": "template",
- "name": "CenterInsideACard",
- "package": "@astryxdesign/core",
- "score": "<text>",
- "reason": "<text>",
- "description": "<text>",
- "displayName": "<text>",
- "kind": "block",
- "command": "astryx template CenterInsideACard --type block",
- "mentions": []
}
]
},
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt b/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
index 1ac0496831..a0ab293428 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon-set.txt
@@ -1,4 +1,4 @@
-Results for "icon set" (20 of 381)
+Results for "icon set" (20 of 383)
name: authoring/building-blocks/templates/build-the-template/template-assets/template-icons
section: use-astryx-icon
domain: doc
@@ -47,6 +47,11 @@ domain: component
package: @astryxdesign/core
import: @astryxdesign/core/InfoTip
command: pnpm exec astryx component InfoTip
+name: useIcon
+domain: hook
+package: @astryxdesign/core
+import: @astryxdesign/core/Icon
+command: pnpm exec astryx hook useIcon
name: useInputContainer
domain: hook
package: @astryxdesign/core
@@ -88,8 +93,4 @@ command: pnpm exec astryx template ButtonWithIcon --type block
name: CenterHorizontal
domain: template
package: @astryxdesign/core
-command: pnpm exec astryx template CenterHorizontal --type block
-name: CenterInsideACard
-domain: template
-package: @astryxdesign/core
-command: pnpm exec astryx template CenterInsideACard --type block
\ No newline at end of file
+command: pnpm exec astryx template CenterHorizontal --type block
\ No newline at end of file
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon.json b/packages/cli/test/__golden__/no-icon-set/search-icon.json
index af5b9c62c2..79c33af0d8 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon.json
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon.json
@@ -3,7 +3,7 @@
"type": "search",
"data": {
"query": "icon",
- "matchCount": 226,
+ "matchCount": 228,
"results": [
{
"domain": "component",
@@ -50,6 +50,17 @@
"command": "astryx component InfoTip",
"mentions": []
},
+ {
+ "domain": "hook",
+ "name": "useIcon",
+ "package": "@astryxdesign/core",
+ "score": "<text>",
+ "reason": "<text>",
+ "description": "<text>",
+ "import": "@astryxdesign/core/Icon",
+ "command": "astryx hook useIcon",
+ "mentions": []
+ },
{
"domain": "hook",
"name": "useInputContainer",
@@ -231,18 +242,6 @@
"kind": "block",
"command": "astryx template ChatComposerDrawerWithProgress --type block",
"mentions": []
- },
- {
- "domain": "template",
- "name": "ChatComposerFooterActions",
- "package": "@astryxdesign/core",
- "score": "<text>",
- "reason": "<text>",
- "description": "<text>",
- "displayName": "<text>",
- "kind": "block",
- "command": "astryx template ChatComposerFooterActions --type block",
- "mentions": []
}
]
},
diff --git a/packages/cli/test/__golden__/no-icon-set/search-icon.txt b/packages/cli/test/__golden__/no-icon-set/search-icon.txt
index 5fe6568a56..450ff3f74c 100644
--- a/packages/cli/test/__golden__/no-icon-set/search-icon.txt
+++ b/packages/cli/test/__golden__/no-icon-set/search-icon.txt
@@ -1,4 +1,4 @@
-Results for "icon" (20 of 226)
+Results for "icon" (20 of 228)
name: Icon
domain: component
package: @astryxdesign/core
@@ -19,6 +19,11 @@ domain: component
package: @astryxdesign/core
import: @astryxdesign/core/InfoTip
command: pnpm exec astryx component InfoTip
+name: useIcon
+domain: hook
+package: @astryxdesign/core
+import: @astryxdesign/core/Icon
+command: pnpm exec astryx hook useIcon
name: useInputContainer
domain: hook
package: @astryxdesign/core
@@ -84,8 +89,4 @@ command: pnpm exec astryx template ChatComposerDrawerShowcase --type block
name: ChatComposerDrawerWithProgress
domain: template
package: @astryxdesign/core
-command: pnpm exec astryx template ChatComposerDrawerWithProgress --type block
-name: ChatComposerFooterActions
-domain: template
-package: @astryxdesign/core
-command: pnpm exec astryx template ChatComposerFooterActions --type block
\ No newline at end of file
+command: pnpm exec astryx template ChatComposerDrawerWithProgress --type block
\ No newline at end of file
diff --git a/packages/core/src/Icon/useIcon.doc.mjs b/packages/core/src/Icon/useIcon.doc.mjs
new file mode 100644
index 0000000000..6462b00434
--- /dev/null
+++ b/packages/core/src/Icon/useIcon.doc.mjs
@@ -0,0 +1,94 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
+export const docs = {
+ name: 'useIcon',
+ displayName: 'useIcon',
+ group: 'Icon',
+ keywords: [
+ 'icon',
+ 'semantic icon',
+ 'theme icons',
+ 'icon registry',
+ 'getIcon',
+ 'registerIcons',
+ 'success',
+ 'warning',
+ 'error',
+ ],
+ params: [
+ {
+ name: 'name',
+ type: 'IconName | NamespacedIconName',
+ description:
+ "Semantic icon name, such as 'success', 'warning' or 'close', or a namespaced extension key such as 'richtext:bold'. Both resolve through the same registry.",
+ required: true,
+ },
+ ],
+ returns: [
+ {
+ name: 'icon',
+ type: 'ReactNode',
+ description:
+ "The icon for that name from the nearest Theme's icons (or, outside any Theme, from the registered theme the document root names), else from registerIcons() overrides, else the built-in default. A function entry is read at {size: 'md'}.",
+ },
+ ],
+ usage: {
+ description:
+ "Resolves a semantic icon name to a React node through the nearest Theme, so a custom component draws the same success, warning or error icon that Astryx components draw and follows a theme that overrides it. Resolution reads the nearest Theme's icons (outside any Theme, the registered theme the document root names), then registerIcons() overrides, then the built-in default. The node is returned as is, with no size or color wrapper: the built-in icons are 1em squares in currentColor, so they follow the surrounding text. A function entry is read at {size: 'md'}. Render <Icon icon={name} /> instead when the icon needs another size, a color or a label.",
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use it in a custom component that places a semantic icon itself, so a Theme that overrides the icon changes the component too.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Render <Icon icon={name} /> when the icon needs a size other than md, a color, or an accessible label.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Import a specific icon library glyph for a semantic purpose that a theme should control, such as a success or error state.',
+ },
+ ],
+ },
+ relatedComponents: ['Icon', 'Theme'],
+ relatedHooks: ['useTheme'],
+ importPath: '@astryxdesign/core/Icon',
+ category: 'utilities',
+};
+
+/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
+export const docsDense = {
+ description:
+ "Resolves a semantic icon name to a React node via the nearest Theme, so custom components draw the same icons as Astryx components and follow theme overrides. Fallback: nearest Theme icons (outside any Theme, the root's registered theme), registerIcons() overrides, built-in default. Node returned as is (built-ins are 1em, currentColor). Function entries read at {size: 'md'}. Use <Icon icon={name} /> for another size, a color or a label.",
+ paramDescriptions: {
+ name: "semantic icon name ('success', 'close') or namespaced key ('richtext:bold'); same registry.",
+ },
+ returnDescriptions: {
+ icon: "icon node from nearest Theme (outside any Theme, the root's registered theme), else registerIcons() overrides, else built-in default; function entries read at {size: 'md'}.",
+ },
+ usage: {
+ description:
+ "Semantic icon name to React node via nearest Theme; custom components follow theme icon overrides. Fallback: nearest Theme (or root's registered theme), registerIcons(), built-in. No size/color wrapper; function entries read at {size: 'md'}. Use <Icon icon={name} /> for other sizes, color or a label.",
+ bestPractices: [
+ {
+ guidance: true,
+ description:
+ 'Use in custom components that place a semantic icon, so Theme overrides reach them.',
+ },
+ {
+ guidance: true,
+ description:
+ 'Render <Icon icon={name} /> for a non-md size, a color, or an accessible label.',
+ },
+ {
+ guidance: false,
+ description:
+ 'Import a library glyph for a semantic purpose a theme should control (success, error).',
+ },
+ ],
+ },
+};