@astryxdesign/core 0.5.0 → 0.5.1-canary.046f6ea

package/src/HoverCard/HoverCard.test.tsx

@@ -365,7 +365,94 @@ describe('HoverCard', () => {
     );
   });
 
-  it('injects aria-describedby on trigger', () => {
+  it('advertises a dialog popup on the trigger when labelled', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+    // While closed, the layer is not in the DOM, so aria-controls must not
+    // point at a missing id (see DateInput). It is set once the card opens.
+    expect(trigger).not.toHaveAttribute('aria-controls');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(trigger).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('merges existing popup attributes on the trigger when labelled', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
+        <button
+          type="button"
+          aria-haspopup="menu"
+          aria-controls="menu-id"
+          aria-expanded="true">
+          Trigger
+        </button>
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    // The hover card's dialog popup is advertised, but the trigger's own
+    // popup semantics are preserved rather than overwritten.
+    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+    expect(trigger.getAttribute('aria-controls')).toContain('menu-id');
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('omits aria-expanded on a trigger whose role does not support it', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Timestamp details">
+        <time dateTime="2026-08-25" tabIndex={0}>
+          2 hours ago
+        </time>
+      </HoverCard>,
+    );
+    const trigger = screen.getByText('2 hours ago');
+    expect(trigger.tagName).toBe('TIME');
+    // Global attributes are valid on any element, so the popup relationship is
+    // still advertised.
+    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+    // aria-expanded is not: <time> has no role that supports it, and emitting
+    // it is a critical axe aria-allowed-attr violation.
+    expect(trigger).not.toHaveAttribute('aria-expanded');
+  });
+
+  it('keeps aria-expanded on a role-less trigger that declares a supporting role', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
+        <span role="button" tabIndex={0}>
+          Trigger
+        </span>
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+  });
+
+  it('leaves a role-less trigger own aria-expanded untouched', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
+        <span aria-expanded="true">Trigger</span>
+      </HoverCard>,
+    );
+    const trigger = screen.getByText('Trigger');
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('keeps aria-expanded on triggers whose implicit role supports it', () => {
+    render(
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
+        <input type="button" value="Trigger" />
+      </HoverCard>,
+    );
+    expect(screen.getByRole('button')).toHaveAttribute(
+      'aria-expanded',
+      'false',
+    );
+  });
+
+  it('keeps aria-describedby on the trigger when no label is provided', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button">Trigger</button>
@@ -373,9 +460,10 @@ describe('HoverCard', () => {
     );
     const trigger = screen.getByRole('button', {name: 'Trigger'});
     expect(trigger).toHaveAttribute('aria-describedby');
+    expect(trigger).not.toHaveAttribute('aria-haspopup');
   });
 
-  it('merges existing aria-describedby', () => {
+  it('preserves existing aria-describedby when no label is provided', () => {
     render(
       <HoverCard content={<span>Card content</span>}>
         <button type="button" aria-describedby="existing-id">
@@ -388,6 +476,34 @@ describe('HoverCard', () => {
     expect(describedBy).toContain('existing-id');
   });
 
+  it('updates aria-expanded when the labelled hover card opens and closes', async () => {
+    render(
+      <HoverCard
+        content={<span>Card content</span>}
+        label="Profile actions"
+        delay={0}>
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    const trigger = screen.getByRole('button', {name: 'Trigger'});
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    expect(trigger).not.toHaveAttribute('aria-controls');
+
+    fireEvent.mouseEnter(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      // The layer is in the DOM now, so aria-controls points at it.
+      expect(trigger).toHaveAttribute('aria-controls');
+    });
+
+    fireEvent.mouseLeave(trigger);
+    await waitFor(() => {
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      // The layer is gone from the DOM, so aria-controls is cleared.
+      expect(trigger).not.toHaveAttribute('aria-controls');
+    });
+  });
+
   it('calls onOpenChange(true) when shown', async () => {
     const onOpenChange = vi.fn();
     render(
@@ -429,16 +545,33 @@ describe('HoverCard', () => {
 
   it('supports text-only children with inline wrapper', () => {
     render(
-      <HoverCard content={<span>Card content</span>}>
+      <HoverCard content={<span>Card content</span>} label="Profile actions">
         Just text, no element
       </HoverCard>,
     );
     // Text should be rendered
     expect(screen.getByText('Just text, no element')).toBeInTheDocument();
-    // Should have aria-describedby on the wrapper span
+    // When labelled, the wrapper advertises a dialog popup.
+    const wrapper = screen.getByText('Just text, no element');
+    expect(wrapper.tagName).toBe('SPAN');
+    expect(wrapper).toHaveAttribute('aria-haspopup', 'dialog');
+    // The wrapper is a role-less <span>; aria-expanded is invalid there.
+    expect(wrapper).not.toHaveAttribute('aria-expanded');
+    // While closed, the layer is not in the DOM, so aria-controls is unset.
+    expect(wrapper).not.toHaveAttribute('aria-controls');
+    expect(wrapper).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('keeps aria-describedby on text-only children when no label is provided', () => {
+    render(
+      <HoverCard content={<span>Card content</span>}>
+        Just text, no element
+      </HoverCard>,
+    );
     const wrapper = screen.getByText('Just text, no element');
     expect(wrapper.tagName).toBe('SPAN');
     expect(wrapper).toHaveAttribute('aria-describedby');
+    expect(wrapper).not.toHaveAttribute('aria-haspopup');
   });
 
   describe('isDefaultOpen', () => {
@@ -994,3 +1127,20 @@ describe('HoverCard', () => {
     });
   });
 });
+
+describe('HoverCard theme target names', () => {
+  it('renders the deprecated class beside the current one on the card surface', async () => {
+    render(
+      <HoverCard content={<span>Card content</span>} delay={0}>
+        <button type="button">Trigger</button>
+      </HoverCard>,
+    );
+    fireEvent.mouseEnter(screen.getByRole('button', {name: 'Trigger'}));
+
+    await waitFor(() => {
+      const layer = screen.getByText('Card content').closest('[popover]');
+      expect(layer).toHaveClass('astryx-hover-card');
+      expect(layer).toHaveClass('astryx-hovercard');
+    });
+  });
+});

package/src/HoverCard/HoverCard.tsx

@@ -32,6 +32,66 @@ export type {
   HoverCardTouchTrigger,
 } from './useHoverCard';
 
+// `aria-haspopup` and `aria-controls` are global, so any trigger may carry
+// them. `aria-expanded` is not. This is the ARIA 1.2 "Supported States and
+// Properties" list for it — deliberately the narrow reading: axe accepts the
+// attribute on rather more roles, since it also allows every subclass of these,
+// so a role outside this set is not necessarily a violation. Widening it is
+// safe; the set is a floor, not the spec's ceiling. The same rule is applied in
+// Chat/useTriggerMenu.tsx, which only emits the combobox attributes once the
+// element is actually a combobox.
+const EXPANDABLE_ROLES = new Set([
+  'application',
+  'button',
+  'checkbox',
+  'columnheader',
+  'combobox',
+  'gridcell',
+  'link',
+  'listbox',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'row',
+  'rowheader',
+  'switch',
+  'tab',
+  'treeitem',
+]);
+
+const BUTTON_INPUT_TYPES = new Set(['button', 'submit', 'reset', 'image']);
+
+// Deliberately partial, and unlisted elements are read as role-less: dropping
+// aria-expanded where it might have been legal costs an AT user a state they
+// can still infer, whereas emitting it where it is illegal is a critical
+// aria-allowed-attr defect.
+function supportsAriaExpanded(el: HTMLElement): boolean {
+  const explicit = el.getAttribute('role')?.trim().split(/\s+/)[0];
+  if (explicit) {
+    return EXPANDABLE_ROLES.has(explicit);
+  }
+  switch (el.tagName) {
+    case 'BUTTON':
+    case 'SUMMARY':
+      return true;
+    case 'A':
+    case 'AREA':
+      return el.hasAttribute('href');
+    case 'INPUT':
+      // The button-flavoured input types map to role="button"; every other
+      // type maps to a textbox-family role, which does not take it.
+      return BUTTON_INPUT_TYPES.has(
+        (el as HTMLInputElement).type?.toLowerCase(),
+      );
+    case 'SELECT':
+      // combobox when it is a single-line picker, listbox otherwise; both
+      // support aria-expanded.
+      return true;
+    default:
+      return false;
+  }
+}
+
 const styles = stylex.create({
   wrapperContents: {
     display: 'contents',
@@ -259,7 +319,70 @@ export function HoverCard({
     // Use combined ref for position + interaction
     hoverCard.ref(firstChild);
 
-    // Set aria-describedby, merging with existing
+    if (label) {
+      // When named, the hover card is a dialog. The trigger should advertise the
+      // popup relationship with aria-haspopup/aria-expanded, not describe the
+      // trigger with the dialog's content (aria-describedby is for plain-text
+      // descriptions, not navigable regions). See #5049.
+      //
+      // aria-expanded only goes on a trigger whose role permits it. A role-less
+      // trigger (Timestamp's <time>/<span>) gets haspopup + controls, which are
+      // global, and no expanded state.
+      //
+      // Merge rather than overwrite: the trigger may already carry its own
+      // popup semantics (e.g. a menu button wrapped in a labelled HoverCard),
+      // so preserve the existing values and restore them on cleanup.
+      const existingHaspopup = firstChild.getAttribute('aria-haspopup');
+      const existingControls = firstChild.getAttribute('aria-controls');
+      const existingExpanded = firstChild.getAttribute('aria-expanded');
+      const canExpand = supportsAriaExpanded(firstChild);
+
+      firstChild.setAttribute('aria-haspopup', 'dialog');
+      // Only point aria-controls at the layer while it is open and in the DOM.
+      // While closed, useLayer leaves only an inert <template> marker, so the
+      // id would reference nothing. DateInput gates it the same way. The
+      // trigger's own aria-controls (if any) is preserved either way.
+      if (hoverCard.isOpen) {
+        firstChild.setAttribute(
+          'aria-controls',
+          mergeIds(existingControls, hoverCard.id) ?? '',
+        );
+      } else if (existingControls) {
+        firstChild.setAttribute('aria-controls', existingControls);
+      } else {
+        firstChild.removeAttribute('aria-controls');
+      }
+      if (canExpand) {
+        firstChild.setAttribute('aria-expanded', String(hoverCard.isOpen));
+      } else if (existingExpanded) {
+        firstChild.setAttribute('aria-expanded', existingExpanded);
+      } else {
+        firstChild.removeAttribute('aria-expanded');
+      }
+
+      return () => {
+        hoverCard.ref(null);
+        if (existingHaspopup) {
+          firstChild.setAttribute('aria-haspopup', existingHaspopup);
+        } else {
+          firstChild.removeAttribute('aria-haspopup');
+        }
+        if (existingControls) {
+          firstChild.setAttribute('aria-controls', existingControls);
+        } else {
+          firstChild.removeAttribute('aria-controls');
+        }
+        if (existingExpanded) {
+          firstChild.setAttribute('aria-expanded', existingExpanded);
+        } else {
+          firstChild.removeAttribute('aria-expanded');
+        }
+      };
+    }
+
+    // Unnamed fallback: the popup remains role="group", which is not a dialog,
+    // so keep the previous description relationship until a naming decision is
+    // made for the no-label case (tracked in #5049).
     const existingDescribedBy = firstChild.getAttribute('aria-describedby');
     firstChild.setAttribute(
       'aria-describedby',
@@ -274,7 +397,14 @@ export function HoverCard({
         firstChild.removeAttribute('aria-describedby');
       }
     };
-  }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
+  }, [
+    textOnly,
+    label,
+    hoverCard.ref,
+    hoverCard.id,
+    hoverCard.isOpen,
+    hoverCard.describedBy,
+  ]);
 
   // While closed, useLayer leaves only an inert <template> marker at this JSX
   // position. When the card needs to open, it uses that marker to keep the
@@ -293,7 +423,11 @@ export function HoverCard({
         <span
           ref={hoverCard.ref}
           tabIndex={0}
-          aria-describedby={hoverCard.describedBy}
+          aria-haspopup={label ? 'dialog' : undefined}
+          aria-controls={label && hoverCard.isOpen ? hoverCard.id : undefined}
+          // No aria-expanded: this wrapper is a role-less <span>, and
+          // aria-expanded is invalid on it (see EXPANDABLE_ROLES above).
+          aria-describedby={label ? undefined : hoverCard.describedBy}
           {...stylex.props(
             styles.wrapperInline,
             showHoverIndication && styles.hoverIndication,

package/src/HoverCard/useHoverCard.tsx

@@ -190,11 +190,25 @@ export interface HoverCardReturn {
   anchorId: string;
 
   /**
-   * ID for aria-describedby on the trigger element.
-   * Caller should compose with other IDs using mergeIds utility.
+   * Unique ID for the hover card container.
+   * Useful for `aria-controls` or `aria-owns` on the trigger.
+   */
+  id: string;
+
+  /**
+   * Deprecated alias of `id`. Kept for backwards compatibility; prefer `id`.
    */
   describedBy: string;
 
+  /**
+   * Whether the hover card is currently open.
+   * Useful for driving `aria-expanded` on the trigger — but only when the
+   * trigger's role permits it (`button`, `link`, `combobox`, …). On a role-less
+   * trigger `aria-expanded` is invalid; use `aria-haspopup`/`aria-controls`
+   * alone there.
+   */
+  isOpen: boolean;
+
   /**
    * Render function for hover card content.
    * Returns anchor-positioned popover element.
@@ -594,7 +608,11 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       props?: Omit<ContextRenderProps, 'positioning'>,
     ): ReactNode => {
       const renderPlacement = props?.placement ?? placement;
-      const themeClassName = themeProps('hovercard').className;
+      const themeClassName = themeProps('hover-card', undefined, {
+        // `hovercard` ran the compound name together; themes styling it keep
+        // working until the next major.
+        legacyNames: ['hovercard'],
+      }).className;
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
@@ -681,7 +699,9 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     positionRef: layer.ref,
     interactionRef,
     anchorId: layer.anchorId,
+    id: layer.id,
     describedBy: layer.id,
+    isOpen: layer.isOpen,
     renderHoverCard,
     show: layer.show,
     hide: layer.hide,

package/src/Icon/Icon.test.tsx

@@ -17,7 +17,7 @@ import {Theme} from '../theme/Theme';
 import {defineTheme} from '../theme/defineTheme';
 import {resetThemes} from '../theme/themeRegistry';
 import {Icon} from './Icon';
-import {resetIcons} from './globalIconRegistry';
+import {registerIcons, resetIcons} from './globalIconRegistry';
 
 describe('Icon', () => {
   it('renders the icon component', () => {
@@ -192,6 +192,60 @@ describe('Icon', () => {
     expect(screen.getByTestId('inner')).toHaveTextContent('inner-check');
   });
 
+  describe('namespaced extension keys', () => {
+    it('renders a theme-registered namespaced key with size and color applied', () => {
+      resetIcons();
+      resetThemes();
+      const theme = defineTheme({
+        name: 'ns-theme',
+        icons: {'numberInput:stepperDown': 'themed-stepper'},
+      });
+
+      render(
+        <Theme theme={theme}>
+          <Icon icon="numberInput:stepperDown" size="xsm" data-testid="icon" />
+        </Theme>,
+      );
+
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveTextContent('themed-stepper');
+      expect(icon).toHaveAttribute('aria-hidden', 'true');
+      expect(icon.className).not.toBe('');
+    });
+
+    it('resolves a namespaced key registered globally', () => {
+      resetIcons();
+      resetThemes();
+      registerIcons({'numberInput:stepperDown': 'global-stepper'});
+
+      render(<Icon icon="numberInput:stepperDown" data-testid="icon" />);
+
+      expect(screen.getByTestId('icon')).toHaveTextContent('global-stepper');
+    });
+
+    it('still rejects a misspelled built-in name', () => {
+      render(
+        // @ts-expect-error — the prop takes built-in names and namespaced
+        // keys, not any string, so a typo is still a compile error.
+        <Icon icon="chevrondown" data-testid="icon" />,
+      );
+
+      expect(screen.queryByTestId('icon')).not.toBeInTheDocument();
+    });
+
+    it('renders nothing when a namespaced key resolves to nothing', () => {
+      resetIcons();
+      resetThemes();
+
+      const {container} = render(
+        <Icon icon="numberInput:missing" data-testid="icon" />,
+      );
+
+      expect(screen.queryByTestId('icon')).not.toBeInTheDocument();
+      expect(container).toBeEmptyDOMElement();
+    });
+  });
+
   it('lets a string-mode icon be made meaningful by overriding aria-hidden', () => {
     render(
       <Icon

package/src/Icon/Icon.tsx

@@ -28,7 +28,7 @@ import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {useThemeName} from '../theme/useTheme';
 import {getIcon} from './globalIconRegistry';
-import type {IconName} from './globalIconRegistry';
+import type {IconName, NamespacedIconName} from './globalIconRegistry';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
@@ -199,9 +199,11 @@ export interface IconProps extends Omit<
   /**
    * Icon to render. Can be:
    * - A semantic name string (e.g. 'close', 'chevronDown') — resolved from theme or built-in fallback
+   * - A namespaced extension key (e.g. 'richtext:bold') for a glyph owned by
+   *   one component or library — resolved the same way, themeable by key
    * - An SVG icon component (e.g. from @heroicons/react) — rendered directly
    */
-  icon: IconType | IconName;
+  icon: IconType | IconName | NamespacedIconName;
   /**
    * The color variant of the icon.
    * @default 'inherit'
@@ -371,7 +373,7 @@ function IconFromRegistry({
   xstyle,
   spanProps,
 }: {
-  name: IconName;
+  name: IconName | NamespacedIconName;
   color: IconColor;
   size: IconSize;
   a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};

package/src/Icon/defaultIcons.tsx

@@ -23,7 +23,8 @@
  * - /packages/core/src/Icon/Icon.doc.mjs (fallback icon documentation)
  */
 
-import type {IconRegistry} from './globalIconRegistry';
+import type {ReactNode} from 'react';
+import type {IconRegistry, NamespacedIconName} from './globalIconRegistry';
 
 const svgProps = {
   xmlns: 'http://www.w3.org/2000/svg',
@@ -53,7 +54,8 @@ const solidSvgProps = {
   'aria-hidden': true as const,
 };
 
-export const defaultIcons: IconRegistry = {
+export const defaultIcons: IconRegistry &
+  Partial<Record<NamespacedIconName, ReactNode>> = {
   /** ✕ — two diagonal lines */
   close: (
     <svg {...svgProps}>
@@ -68,6 +70,13 @@ export const defaultIcons: IconRegistry = {
     </svg>
   ),
 
+  /** ⌄ — compact NumberInput stepper chevron */
+  'numberInput:stepperDown': (
+    <svg {...svgProps}>
+      <path d="M7.5 9.75l4.5 4.5 4.5-4.5" />
+    </svg>
+  ),
+
   /** ‹ — left chevron */
   chevronLeft: (
     <svg {...svgProps}>

package/src/Icon/globalIconRegistry.test.tsx

@@ -27,12 +27,22 @@ describe('iconRegistry (global, RSC-compatible)', () => {
 
   it('returns a default icon registry snapshot', () => {
     const registry = getIconRegistry();
+    const builtInDefaults = Object.fromEntries(
+      Object.entries(defaultIcons).filter(([name]) => !name.includes(':')),
+    );
 
-    expect(Object.keys(registry)).toEqual(Object.keys(defaultIcons));
-    expect(registry).toEqual(defaultIcons);
+    expect(registry).toEqual(builtInDefaults);
     expect(registry).not.toBe(defaultIcons);
   });
 
+  it('provides a distinct default for the NumberInput stepper icon', () => {
+    const icon = getIcon('numberInput:stepperDown');
+
+    expect(icon).toBe(defaultIcons['numberInput:stepperDown']);
+    expect(icon).toBeDefined();
+    expect(icon).not.toBe(defaultIcons.chevronDown);
+  });
+
   it('returns default icons when nothing is registered', () => {
     const icon = getIcon('close');
     expect(icon).toBeDefined();
@@ -149,7 +159,10 @@ describe('iconRegistry (global, RSC-compatible)', () => {
       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));
+      expect(Object.keys(getIconRegistry())).not.toContain('richtext:bold');
+      expect(Object.keys(getIconRegistry())).not.toContain(
+        'numberInput:stepperDown',
+      );
     });
 
     it('extension keys are cleared by resetIcons', () => {

package/src/Icon/globalIconRegistry.tsx

@@ -57,6 +57,20 @@ export type IconName =
   | 'stop'
   | 'microphone';
 
+/**
+ * A namespaced extension key, `'<namespace>:<name>'`.
+ *
+ * This is the tier for a glyph that belongs to one component or library rather
+ * than to the system: `'richtext:bold'`, `'numberInput:stepperDown'`. A theme
+ * overrides it by key through `registerIcons` or `defineTheme({icons})`,
+ * exactly as it overrides a built-in name, and the core {@link IconName} union
+ * stays reserved for glyphs the whole system shares.
+ *
+ * Accepted anywhere a built-in name is, including `<Icon icon>` — which is
+ * what lets a namespaced glyph keep `size`, `color` and `xstyle`.
+ */
+export type NamespacedIconName = `${string}:${string}`;
+
 /**
  * A semantic icon name — either one of the built-in {@link IconName}s or an
  * arbitrary string key contributed by a library/app.
@@ -81,9 +95,19 @@ export type IconRegistrySource = DefinedTheme | string | null | undefined;
 
 let globalRegistry: Record<string, ReactNode> = {};
 
+/**
+ * A key is namespaced when it carries a `<namespace>:` prefix — the runtime
+ * form of {@link NamespacedIconName}, which is how the typed
+ * {@link getIconRegistry} snapshot tells a built-in name from a component- or
+ * library-owned one.
+ */
+function isNamespacedKey(name: string): boolean {
+  return name.includes(':');
+}
+
 function getThemeIconOverrides(
   source: IconRegistrySource,
-): Partial<IconRegistry> | null {
+): Partial<Record<IconName | NamespacedIconName, ReactNode>> | null {
   if (source == null) {
     return null;
   }
@@ -140,23 +164,30 @@ export function registerIcons(
 export function getIconRegistry(
   source?: IconRegistrySource,
 ): Readonly<IconRegistry> {
-  const registry = {...defaultIcons};
+  const registry: Record<string, ReactNode> = {};
 
-  // 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.
+  // Only surface built-in IconName keys here — namespaced keys, whether
+  // contributed by a library or shipped as a component's own default, are
+  // resolved via getIcon/getExtendedIcon and intentionally kept out of the
+  // typed IconRegistry snapshot.
   for (const name of Object.keys(defaultIcons) as IconName[]) {
+    if (isNamespacedKey(name)) {
+      continue;
+    }
     registry[name] = globalRegistry[name] ?? defaultIcons[name];
   }
 
   const themeIcons = getThemeIconOverrides(source);
   if (themeIcons != null) {
     for (const name of Object.keys(themeIcons) as IconName[]) {
+      if (isNamespacedKey(name)) {
+        continue;
+      }
       registry[name] = themeIcons[name] ?? registry[name];
     }
   }
 
-  return registry;
+  return registry as IconRegistry;
 }
 
 /**

package/src/Icon/index.ts

@@ -26,6 +26,7 @@ export {
 export type {
   IconName,
   ExtendedIconName,
+  NamespacedIconName,
   IconRegistry,
   IconRegistrySource,
 } from './globalIconRegistry';