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.mdnew file mode 100644index 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>`.++@MannXodiff --git a/apps/sandbox/scripts/next-export-routes.json b/apps/sandbox/scripts/next-export-routes.jsonindex 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.tsindex 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.jsonindex 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.txtindex 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/useEnduseFieldStatusAnnouncement useFieldStatusAnnouncement FieldStatus/FieldStatus.doc.mjs FieldStatus/useFieldStatusAnnouncement.tsuseFocusReturnVisibility useFocusReturnVisibility hooks/useAnimatedLayout.doc.mjs hooks/useFocusReturnVisibility.tsuseHighlightedOptionScroll 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.tsuseIndicator useIndicator Indicator/Indicator.doc.mjs Indicator/useIndicator.tsuseInternalConfig useInternalConfig PowerSearch/PowerSearch.doc.mjs PowerSearch/useInternalConfig.tsuseIsHydrating useIsHydrating hooks/useAnimatedLayout.doc.mjs hooks/useIsHydrating.tsdiff --git a/packages/cli/api/template/use-icon-hook-usage.test.tsx b/packages/cli/api/template/use-icon-hook-usage.test.tsxnew file mode 100644index 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.mjsnew file mode 100644index 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.tsxnew file mode 100644index 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.jsonindex 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.txtindex 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-iconssection: use-astryx-icondomain: doc@@ -47,6 +47,11 @@ domain: componentpackage: @astryxdesign/coreimport: @astryxdesign/core/InfoTipcommand: pnpm exec astryx component InfoTip+name: useIcon+domain: hook+package: @astryxdesign/core+import: @astryxdesign/core/Icon+command: pnpm exec astryx hook useIconname: useInputContainerdomain: hookpackage: @astryxdesign/core@@ -88,8 +93,4 @@ command: pnpm exec astryx template ButtonWithIcon --type blockname: CenterHorizontaldomain: templatepackage: @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 filediff --git a/packages/cli/test/__golden__/no-icon-set/search-icon.json b/packages/cli/test/__golden__/no-icon-set/search-icon.jsonindex 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.txtindex 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: Icondomain: componentpackage: @astryxdesign/core@@ -19,6 +19,11 @@ domain: componentpackage: @astryxdesign/coreimport: @astryxdesign/core/InfoTipcommand: pnpm exec astryx component InfoTip+name: useIcon+domain: hook+package: @astryxdesign/core+import: @astryxdesign/core/Icon+command: pnpm exec astryx hook useIconname: useInputContainerdomain: hookpackage: @astryxdesign/core@@ -84,8 +89,4 @@ command: pnpm exec astryx template ChatComposerDrawerShowcase --type blockname: ChatComposerDrawerWithProgressdomain: templatepackage: @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 filediff --git a/packages/core/src/Icon/useIcon.doc.mjs b/packages/core/src/Icon/useIcon.doc.mjsnew file mode 100644index 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).',+ },+ ],+ },+};