@astryxdesign/core 0.2.0 → 0.3.0

package/src/Icon/globalIconRegistry.test.tsx

@@ -1,17 +1,28 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-import {describe, it, expect, beforeEach} from 'vitest';
+import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
+import {defineTheme} from '../theme/defineTheme';
+import {resetThemes} from '../theme/themeRegistry';
+import {__resetDevWarnings} from '../utils/devWarning';
 import {defaultIcons} from './defaultIcons';
 import {
   registerIcons,
   getIconRegistry,
   getIcon,
+  getExtendedIcon,
   resetIcons,
 } from './globalIconRegistry';
 
 describe('iconRegistry (global, RSC-compatible)', () => {
   beforeEach(() => {
     resetIcons();
+    resetThemes();
+    __resetDevWarnings();
+    vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
   });
 
   it('returns a default icon registry snapshot', () => {
@@ -28,6 +39,18 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     expect(icon).not.toBeNull();
   });
 
+  it('warns once that registerIcons applies global overrides', () => {
+    const warnSpy = vi.mocked(console.warn);
+
+    registerIcons({close: 'custom-close'});
+    registerIcons({check: 'custom-check'});
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0]?.[0]).toContain(
+      '`registerIcons()` applies icon overrides globally',
+    );
+  });
+
   it('returns registered icons over defaults', () => {
     const customClose = 'custom-close-icon';
     registerIcons({close: customClose});
@@ -65,6 +88,35 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     expect(getIcon('close')).toBe('close-v2');
   });
 
+  it('resolves icons from an explicit theme object over global registrations', () => {
+    registerIcons({close: 'global-close'});
+    const theme = defineTheme({
+      name: 'brand',
+      icons: {close: 'theme-close'},
+    });
+
+    expect(getIcon('close', theme)).toBe('theme-close');
+    expect(getIconRegistry(theme).close).toBe('theme-close');
+  });
+
+  it('resolves icons from a registered theme name for SSR-friendly lookups', () => {
+    defineTheme({
+      name: 'brand',
+      icons: {close: 'theme-close'},
+    });
+
+    expect(getIcon('close', 'brand')).toBe('theme-close');
+    expect(getIconRegistry('brand').close).toBe('theme-close');
+  });
+
+  it('falls back through global registrations when a theme omits a name', () => {
+    registerIcons({close: 'global-close'});
+    const theme = defineTheme({name: 'brand', icons: {check: 'theme-check'}});
+
+    expect(getIcon('close', theme)).toBe('global-close');
+    expect(getIcon('check', theme)).toBe('theme-check');
+  });
+
   it('resetIcons clears the global registry', () => {
     registerIcons({close: 'custom'});
     expect(getIcon('close')).toBe('custom');
@@ -72,4 +124,38 @@ describe('iconRegistry (global, RSC-compatible)', () => {
     // Should fall back to default
     expect(getIcon('close')).not.toBe('custom');
   });
+
+  describe('extension keys', () => {
+    it('registers and resolves library-contributed keys', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      expect(getIcon('richtext:bold')).toBe('my-bold');
+      expect(getExtendedIcon('richtext:bold')).toBe('my-bold');
+    });
+
+    it('getExtendedIcon returns the caller fallback when unregistered', () => {
+      expect(getExtendedIcon('richtext:bold', 'inline-svg')).toBe('inline-svg');
+    });
+
+    it('getExtendedIcon prefers a registered icon over the fallback', () => {
+      registerIcons({'richtext:bold': 'theme-bold'});
+      expect(getExtendedIcon('richtext:bold', 'inline-svg')).toBe('theme-bold');
+    });
+
+    it('getExtendedIcon still resolves built-in defaults', () => {
+      expect(getExtendedIcon('close', 'fallback')).toBe(defaultIcons.close);
+    });
+
+    it('extension keys do not leak into the built-in registry snapshot', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      // getIconRegistry() is the built-in IconName snapshot; extension keys
+      // are resolved via getIcon/getExtendedIcon, not surfaced here.
+      expect(Object.keys(getIconRegistry())).toEqual(Object.keys(defaultIcons));
+    });
+
+    it('extension keys are cleared by resetIcons', () => {
+      registerIcons({'richtext:bold': 'my-bold'});
+      resetIcons();
+      expect(getExtendedIcon('richtext:bold', 'fallback')).toBe('fallback');
+    });
+  });
 });

package/src/Icon/globalIconRegistry.tsx

@@ -4,14 +4,17 @@
  * @file globalIconRegistry.tsx
  * @input None (pure module-level state)
  * @output Exports registerIcons, getIconRegistry, getIcon, resetIcons, IconName, IconRegistry
- * @position Global icon registry; works in both server and client environments
+ * @position Global and theme-scoped icon registry; works in server and client environments
  *
  * This module has NO 'use client' directive — it's importable from RSC.
- * All components use getIcon() to resolve icons from this global registry.
+ * Components resolve semantic icons through getIcon() or the client useIcon() hook.
  */
 
 import type {ReactNode} from 'react';
 import {defaultIcons} from './defaultIcons';
+import type {DefinedTheme} from '../theme/defineTheme';
+import {getRegisteredTheme} from '../theme/themeRegistry';
+import {warnOnce} from '../utils/devWarning';
 
 // =============================================================================
 // Types
@@ -23,12 +26,14 @@ import {defaultIcons} from './defaultIcons';
  * These represent the functional purpose of each icon, not a specific
  * visual representation. Themes provide the actual icon components.
  */
-// SYNC: packages/cli/docs/icons.doc.mjs — update USAGE_HINTS when adding names
+// SYNC: packages/cli/assets/docs/icons.doc.mjs — update USAGE_HINTS when adding names
 export type IconName =
   | 'close'
   | 'chevronDown'
   | 'chevronLeft'
   | 'chevronRight'
+  | 'chevronsLeft'
+  | 'chevronsRight'
   | 'check'
   | 'success'
   | 'error'
@@ -52,16 +57,43 @@ export type IconName =
   | 'stop'
   | 'microphone';
 
+/**
+ * A semantic icon name — either one of the built-in {@link IconName}s or an
+ * arbitrary string key contributed by a library/app.
+ *
+ * The `(string & {})` intersection keeps the built-in names available for
+ * autocomplete while still allowing any string, so downstream libraries can
+ * register and resolve their own keys (e.g. `'richtext:bold'`) without having
+ * to widen the core `IconName` union.
+ */
+export type ExtendedIconName = IconName | (string & {});
+
 /**
  * Icon registry mapping semantic names to React nodes.
  */
 export type IconRegistry = Record<IconName, ReactNode>;
 
+export type IconRegistrySource = DefinedTheme | string | null | undefined;
+
 // =============================================================================
 // Global Registry
 // =============================================================================
 
-let globalRegistry: Partial<IconRegistry> = {};
+let globalRegistry: Record<string, ReactNode> = {};
+
+function getThemeIconOverrides(
+  source: IconRegistrySource,
+): Partial<IconRegistry> | null {
+  if (source == null) {
+    return null;
+  }
+
+  if (typeof source === 'string') {
+    return getRegisteredTheme(source)?.icons ?? null;
+  }
+
+  return source.icons ?? null;
+}
 
 /**
  * Register icons at the module level. Works in both server and client
@@ -76,8 +108,24 @@ let globalRegistry: Partial<IconRegistry> = {};
  * import { brandIcons } from './brand-icons';
  * registerIcons(brandIcons);
  * ```
+ *
+ * Libraries may also register their own extension keys (any string), so a
+ * theme can override them the same way it overrides built-in icons:
+ * @example
+ * ```
+ * // In a library that ships its own icons:
+ * registerIcons({ 'richtext:bold': <MyBoldIcon /> });
+ * // resolve with getIcon('richtext:bold')
+ * ```
  */
-export function registerIcons(icons: Partial<IconRegistry>): void {
+export function registerIcons(
+  icons: Partial<Record<ExtendedIconName, ReactNode>>,
+): void {
+  warnOnce(
+    'icon-registry:global-register-icons',
+    'Icon',
+    '`registerIcons()` applies icon overrides globally. Prefer `defineTheme({ icons })` for theme-scoped icon overrides.',
+  );
   globalRegistry = {...globalRegistry, ...icons};
 }
 
@@ -89,13 +137,25 @@ export function registerIcons(icons: Partial<IconRegistry>): void {
  * to derive valid semantic icon-name options from the same registry Icon
  * resolves against.
  */
-export function getIconRegistry(): Readonly<IconRegistry> {
+export function getIconRegistry(
+  source?: IconRegistrySource,
+): Readonly<IconRegistry> {
   const registry = {...defaultIcons};
 
-  for (const name of Object.keys(globalRegistry) as IconName[]) {
+  // Only surface built-in IconName keys here — extension keys registered by
+  // libraries are resolved via getIcon/getExtendedIcon and intentionally kept
+  // out of the typed IconRegistry snapshot.
+  for (const name of Object.keys(defaultIcons) as IconName[]) {
     registry[name] = globalRegistry[name] ?? defaultIcons[name];
   }
 
+  const themeIcons = getThemeIconOverrides(source);
+  if (themeIcons != null) {
+    for (const name of Object.keys(themeIcons) as IconName[]) {
+      registry[name] = themeIcons[name] ?? registry[name];
+    }
+  }
+
   return registry;
 }
 
@@ -104,9 +164,51 @@ export function getIconRegistry(): Readonly<IconRegistry> {
  *
  * Works in both server and client environments.
  * Falls back to built-in default icons when no override is registered.
+ *
+ * Accepts extension keys (any string) in addition to the built-in
+ * {@link IconName}s — useful for library-contributed icons. For a
+ * caller-supplied fallback when a key isn't registered, use
+ * {@link getExtendedIcon}.
+ */
+export function getIcon(
+  name: ExtendedIconName,
+  source?: IconRegistrySource,
+): ReactNode {
+  const themeIcons = getThemeIconOverrides(source);
+  return (
+    themeIcons?.[name as IconName] ??
+    globalRegistry[name] ??
+    defaultIcons[name as IconName]
+  );
+}
+
+/**
+ * Resolve an extension icon by an arbitrary string key, falling back to a
+ * caller-supplied default when nothing is registered.
+ *
+ * This is the seam libraries use to make their own icons themeable: ship the
+ * inline SVG as `fallback`, resolve through this function, and a theme can
+ * override the key via {@link registerIcons} without the library having to
+ * widen the core {@link IconName} union.
+ *
+ * @example
+ * ```
+ * // Library default, overridable by a theme registering 'richtext:bold':
+ * getExtendedIcon('richtext:bold', <BoldGlyph />)
+ * ```
  */
-export function getIcon(name: IconName): ReactNode {
-  return globalRegistry[name] ?? defaultIcons[name];
+export function getExtendedIcon(
+  name: ExtendedIconName,
+  fallback?: ReactNode,
+  source?: IconRegistrySource,
+): ReactNode {
+  const themeIcons = getThemeIconOverrides(source);
+  return (
+    themeIcons?.[name as IconName] ??
+    globalRegistry[name] ??
+    defaultIcons[name as IconName] ??
+    fallback
+  );
 }
 
 /**

package/src/Icon/index.ts

@@ -12,18 +12,20 @@
  */
 
 export {Icon, renderIconSlot} from './Icon';
-export type {
-  IconProps,
-  IconColor,
-  IconSize,
-  IconType,
-} from './Icon';
+export {useIcon} from './useIcon';
+export type {IconProps, IconColor, IconSize, IconType} from './Icon';
 
 // Global registry (RSC-compatible, no 'use client')
 export {
   registerIcons,
   getIconRegistry,
   getIcon,
+  getExtendedIcon,
   resetIcons,
 } from './globalIconRegistry';
-export type {IconName, IconRegistry} from './globalIconRegistry';
+export type {
+  IconName,
+  ExtendedIconName,
+  IconRegistry,
+  IconRegistrySource,
+} from './globalIconRegistry';

package/src/Icon/useIcon.ts

@@ -0,0 +1,23 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useIcon.ts
+ * @input Semantic icon name
+ * @output Exports useIcon hook for theme-aware icon lookup
+ * @position Client hook for components that render registry icons directly
+ */
+
+import type {ReactNode} from 'react';
+import {useThemeName} from '../theme/useTheme';
+import {getIcon, type IconName} from './globalIconRegistry';
+
+/**
+ * Resolve a semantic icon name from the nearest Theme, falling back through
+ * root theme registration, global icon overrides, and built-in defaults.
+ */
+export function useIcon(name: IconName): ReactNode {
+  const themeName = useThemeName();
+  return getIcon(name, themeName);
+}

package/src/IconButton/IconButton.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'IconButton',
@@ -84,7 +84,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'Button showing only an icon, no visible text. Use in toolbars, table rows, compact UI where space is tight + icon universally understood.',
   usage: {

package/src/IconButton/IconButton.tsx

@@ -13,7 +13,7 @@
  * - /packages/core/src/IconButton/IconButton.test.tsx (tests)
  * - /packages/core/src/IconButton/index.ts (exports if types change)
  * - /apps/storybook/stories/IconButton.stories.tsx (storybook stories)
- * - /packages/cli/templates/blocks/components/IconButton/ (showcase blocks)
+ * - /packages/cli/assets/templates/blocks/components/IconButton/ (showcase blocks)
  */
 
 import type {ReactNode} from 'react';

package/src/InputGroup/InputGroup.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'InputGroup',
@@ -163,7 +163,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description:
     'groups input with prefix/suffix addons in a connected container',

package/src/InputGroup/InputGroup.tsx

@@ -18,7 +18,7 @@
  * - /packages/core/src/InputGroup/InputGroup.test.tsx
  * - /packages/core/src/InputGroup/index.ts
  * - /apps/storybook/stories/InputGroup.stories.tsx
- * - /packages/cli/templates/blocks/components/InputGroup/
+ * - /packages/cli/assets/templates/blocks/components/InputGroup/
  */
 
 import {useId, useMemo, type ReactNode} from 'react';

package/src/InputGroup/InputGroupText.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'InputGroupText',

package/src/InputGroup/InputGroupText.tsx

@@ -11,7 +11,7 @@
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/InputGroup/InputGroup.doc.mjs
  * - /packages/core/src/InputGroup/index.ts
- * - /packages/cli/templates/blocks/components/InputGroup/
+ * - /packages/cli/assets/templates/blocks/components/InputGroup/
  */
 
 import React, {type ReactNode} from 'react';

package/src/Item/Item.doc.mjs

@@ -1,6 +1,6 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-/** @type {import('../docs-types').ComponentDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
   name: 'Item',
@@ -37,6 +37,7 @@ export const docs = {
         {name: 'labelLines', type: 'number', description: 'Max lines before label truncates with ellipsis.'},
         {name: 'descriptionLines', type: 'number', description: 'Max lines before description truncates with ellipsis.'},
         {name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler. Makes the item clickable with button semantics.'},
+        {name: 'interactiveRef', type: 'RefObject<HTMLElement | null>', description: 'Ref to a nested control (e.g. a checkbox in startContent) that owns the item\'s keyboard access and action. The row becomes an enlarged click/tap target that delegates surface clicks to it (useClickableContainer) and renders no invisible button/anchor, so the row adds no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href — those are ignored when set.'},
         {name: 'href', type: 'string', description: 'Link URL. Makes the item a link via an invisible anchor element.'},
         {name: 'target', type: "'_blank' | '_self'", description: 'Link target. Only used with href. target="_blank" automatically adds noopener noreferrer.'},
         {name: 'rel', type: 'string', description: 'Link relationship tokens. noopener noreferrer are merged automatically for target="_blank".'},
@@ -71,7 +72,7 @@ export const docs = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsZh = {
   components: [
     {
@@ -90,6 +91,8 @@ export const docsZh = {
         labelLines: '标签截断前的最大行数。',
         descriptionLines: '描述截断前的最大行数。',
         onClick: '点击处理函数。使项目可点击，具有按钮语义。',
+        interactiveRef:
+          '指向嵌套控件（如 startContent 中的复选框）的 ref，该控件承载项目的键盘访问和操作。行成为更大的点击/触摸目标，将表面点击委托给该控件（useClickableContainer），且不渲染不可见按钮/锚点，因此行不会增加第二个 Tab 停留点（WCAG 4.1.2）。与 onClick/href 互斥——设置后二者将被忽略。',
         href: '链接 URL。通过不可见锚点元素使项目成为链接。',
         target: '链接目标。仅与 href 一起使用。target="_blank" 会自动添加 noopener noreferrer。',
         rel: '链接关系标记。target="_blank" 会自动合并 noopener noreferrer。',
@@ -124,7 +127,7 @@ export const docsZh = {
   },
 };
 
-/** @type {import('../docs-types').TranslationDoc} */
+/** @type {import('@astryxdesign/cli/authoring').ComponentTranslationDoc} */
 export const docsDense = {
   description: 'universal item primitive w/ startContent+label+description+endContent layout. building block for list items, menu items, contacts, notifications',
   usage: {
@@ -157,6 +160,8 @@ export const docsDense = {
         labelLines: 'Max label lines before truncation.',
         descriptionLines: 'Max description lines before truncation.',
         onClick: 'Click handler; enables button semantics.',
+        interactiveRef:
+          'Ref to a nested control that owns the item\'s keyboard access/action; row delegates surface clicks to it (useClickableContainer), no invisible button/anchor, no second tab stop (WCAG 4.1.2). Mutually exclusive with onClick/href.',
         href: 'Link URL; enables anchor semantics.',
         target:
           'Link target, only with href. target="_blank" auto-adds noopener noreferrer.',

package/src/Item/Item.test.tsx

@@ -9,11 +9,35 @@
  * SYNC: When Item component changes, update tests to match new behavior
  */
 
+import {useRef} from 'react';
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {Item} from './Item';
 
+/**
+ * Item in delegation mode: `interactiveRef` points at a nested control that
+ * owns the row's keyboard access and action. The row is an enlarged tap target
+ * that forwards surface clicks to that control (useClickableContainer).
+ */
+function DelegatingItem({onToggle}: {onToggle?: () => void}) {
+  const ref = useRef<HTMLInputElement>(null);
+  return (
+    <Item
+      label="Row"
+      interactiveRef={ref}
+      startContent={
+        <input
+          ref={ref}
+          type="checkbox"
+          aria-label="Pick row"
+          onChange={onToggle}
+        />
+      }
+    />
+  );
+}
+
 describe('Item', () => {
   // ===========================================================================
   // Basic rendering
@@ -190,6 +214,70 @@ describe('Item', () => {
     expect(buttons).toHaveLength(1);
   });
 
+  // ===========================================================================
+  // Interactive — interactiveRef (delegation to a nested control)
+  // ===========================================================================
+
+  it('renders no invisible button in interactiveRef (delegation) mode', () => {
+    const {container} = render(<DelegatingItem />);
+    // The nested control provides keyboard access — the row must not add a
+    // second focusable control for the same action (WCAG 4.1.2).
+    expect(container.querySelector('button')).not.toBeInTheDocument();
+  });
+
+  it('keeps the nested control as the only tab stop in interactiveRef mode', async () => {
+    const user = userEvent.setup();
+    render(<DelegatingItem />);
+    await user.tab();
+    expect(screen.getByRole('checkbox')).toHaveFocus();
+    // Next tab leaves the item entirely — the row itself is not focusable.
+    await user.tab();
+    expect(screen.getByRole('checkbox')).not.toHaveFocus();
+    expect(document.body).toHaveFocus();
+  });
+
+  it('delegates a row-surface click to the interactive control', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<DelegatingItem onToggle={onToggle} />);
+    // Clicking the label (row surface) is forwarded to the checkbox.
+    await user.click(screen.getByText('Row'));
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not double-fire when the interactive control itself is clicked', async () => {
+    const user = userEvent.setup();
+    const onToggle = vi.fn();
+    render(<DelegatingItem onToggle={onToggle} />);
+    await user.click(screen.getByRole('checkbox'));
+    // The row must not re-forward the control's own click back to it.
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('ignores onClick when interactiveRef is set (delegation wins, single tab stop)', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    function ItemWithBoth() {
+      const ref = useRef<HTMLInputElement>(null);
+      return (
+        <Item
+          label="Row"
+          onClick={onClick}
+          interactiveRef={ref}
+          startContent={
+            <input ref={ref} type="checkbox" aria-label="Pick row" />
+          }
+        />
+      );
+    }
+    const {container} = render(<ItemWithBoth />);
+    // No invisible button (onClick is ignored in delegation mode)...
+    expect(container.querySelector('button')).not.toBeInTheDocument();
+    // ...and the checkbox is still the sole tab stop.
+    await user.tab();
+    expect(screen.getByRole('checkbox')).toHaveFocus();
+  });
+
   // ===========================================================================
   // Interactive — href (invisible anchor pattern)
   // ===========================================================================