@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/HoverCard/useHoverCard.doc.mjs

@@ -5,37 +5,159 @@ export const docs = {
   name: 'useHoverCard',
   displayName: 'useHoverCard',
   group: 'HoverCard',
-  keywords: ['hovercard', 'hover', 'preview', 'card', 'tooltip', 'popup', 'floating', 'anchor'],
+  keywords: [
+    'hovercard',
+    'hover',
+    'preview',
+    'card',
+    'tooltip',
+    'popup',
+    'floating',
+    'anchor',
+  ],
   params: [
-    {name: 'placement', type: "'above' | 'below' | 'start' | 'end'", description: "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'above'"},
-    {name: 'alignment', type: "'start' | 'center' | 'end'", description: "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).", default: "'center'"},
-    {name: 'delay', type: 'number', description: 'Delay before showing the hover card on hover, in milliseconds.', default: '300'},
-    {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},
-    {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
-    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens; none never opens on touch.', default: "'auto'"},
-    {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
-    {name: 'label', type: 'string', description: 'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).'},
-    {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
-    {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the hover card should be shown on mount.', default: 'false'},
-    {name: 'onShow', type: '() => void', description: 'Callback fired when the hover card becomes visible.'},
-    {name: 'onHide', type: '() => void', description: 'Callback fired when the hover card is hidden.'},
+    {
+      name: 'placement',
+      type: "'above' | 'below' | 'start' | 'end'",
+      description:
+        "Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'above'",
+    },
+    {
+      name: 'alignment',
+      type: "'start' | 'center' | 'end'",
+      description:
+        "Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
+      default: "'center'",
+    },
+    {
+      name: 'delay',
+      type: 'number',
+      description:
+        'Delay before showing the hover card on hover, in milliseconds.',
+      default: '300',
+    },
+    {
+      name: 'hideDelay',
+      type: 'number',
+      description:
+        'Delay before hiding after mouse or focus leaves, in milliseconds.',
+      default: '200',
+    },
+    {
+      name: 'focusTrigger',
+      type: "'auto' | 'always' | 'never'",
+      description:
+        'When focus should open the hover card. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
+      default: "'auto'",
+    },
+    {
+      name: 'touchTrigger',
+      type: "'auto' | 'tap' | 'none'",
+      description:
+        'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens; none never opens on touch.',
+      default: "'auto'",
+    },
+    {
+      name: 'isEnabled',
+      type: 'boolean',
+      description: 'Whether hover and focus triggers are enabled.',
+      default: 'true',
+    },
+    {
+      name: 'label',
+      type: 'string',
+      description:
+        'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).',
+    },
+    {
+      name: 'isOpen',
+      type: 'boolean',
+      description:
+        'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.',
+    },
+    {
+      name: 'isDefaultOpen',
+      type: 'boolean',
+      description: 'Whether the hover card should be shown on mount.',
+      default: 'false',
+    },
+    {
+      name: 'onShow',
+      type: '() => void',
+      description: 'Callback fired when the hover card becomes visible.',
+    },
+    {
+      name: 'onHide',
+      type: '() => void',
+      description: 'Callback fired when the hover card is hidden.',
+    },
   ],
   returns: [
-    {name: 'ref', type: 'RefCallback<HTMLElement>', description: 'Combined ref that sets both position and interaction on the same trigger element.'},
-    {name: 'positionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the positioning anchor element. Use when position and interaction live on different elements.'},
-    {name: 'interactionRef', type: 'RefCallback<HTMLElement>', description: 'Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns.'},
-    {name: 'anchorId', type: 'string', description: 'CSS anchor name for advanced positioning cases.'},
-    {name: 'describedBy', type: 'string', description: 'ID to compose into aria-describedby on the trigger.'},
-    {name: 'renderHoverCard', type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode", description: 'Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment.'},
-    {name: 'show', type: '() => void', description: 'Imperatively show the hover card immediately.'},
-    {name: 'hide', type: '() => void', description: 'Imperatively hide the hover card immediately.'},
+    {
+      name: 'ref',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Combined ref that sets both position and interaction on the same trigger element.',
+    },
+    {
+      name: 'positionRef',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Ref for the positioning anchor element. Use when position and interaction live on different elements.',
+    },
+    {
+      name: 'interactionRef',
+      type: 'RefCallback<HTMLElement>',
+      description:
+        'Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns.',
+    },
+    {
+      name: 'anchorId',
+      type: 'string',
+      description: 'CSS anchor name for advanced positioning cases.',
+    },
+    {
+      name: 'describedBy',
+      type: 'string',
+      description: 'ID to compose into aria-describedby on the trigger.',
+    },
+    {
+      name: 'renderHoverCard',
+      type: "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
+      description:
+        'Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment.',
+    },
+    {
+      name: 'show',
+      type: '() => void',
+      description: 'Imperatively show the hover card immediately.',
+    },
+    {
+      name: 'hide',
+      type: '() => void',
+      description: 'Imperatively hide the hover card immediately.',
+    },
   ],
   usage: {
-    description: 'Headless hook for hover-triggered floating cards. Builds on useLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.',
+    description:
+      'Headless hook for hover-triggered floating cards. Builds on useLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.',
     bestPractices: [
-      {guidance: true, description: 'Use for rich content previews such as user profiles, entity summaries, and link previews.'},
-      {guidance: true, description: 'Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.'},
-      {guidance: false, description: 'Use for simple text hints: use Tooltip or useTooltip instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for rich content previews such as user profiles, entity summaries, and link previews.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for simple text hints: use Tooltip or useTooltip instead.',
+      },
     ],
   },
   relatedComponents: ['HoverCard', 'Tooltip', 'Popover'],
@@ -46,17 +168,24 @@ export const docs = {
 
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
-  description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
+  description:
+    'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
   paramDescriptions: {
-    placement: 'position relative to trigger. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
-    alignment: 'alignment along placement axis. logical: start/end follow the popover\'s inherited direction (RTL mirrors).',
+    placement:
+      "position relative to trigger. logical: start/end follow the popover's inherited direction (RTL mirrors).",
+    alignment:
+      "alignment along placement axis. logical: start/end follow the popover's inherited direction (RTL mirrors).",
     delay: 'show delay in ms.',
     hideDelay: 'hide delay after mouse/focus leave in ms.',
-    focusTrigger: 'when focus opens hover card; auto = naturally focusable elements only.',
-    touchTrigger: 'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
+    focusTrigger:
+      'when focus opens hover card; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
+    touchTrigger:
+      'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
     isEnabled: 'whether hover/focus triggers are enabled.',
-    label: 'accessible name for popup. with label: named role="dialog"; without: role="group".',
-    isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
+    label:
+      'accessible name for popup. with label: named role="dialog"; without: role="group".',
+    isOpen:
+      'controlled open state: true force-show, false force-hide, undefined unmanaged.',
     isDefaultOpen: 'show on mount.',
     onShow: 'fires when hover card becomes visible.',
     onHide: 'fires when hover card hides.',
@@ -72,11 +201,24 @@ export const docsDense = {
     hide: 'hide immediately.',
   },
   usage: {
-    description: 'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
+    description:
+      'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
     bestPractices: [
-      {guidance: true, description: 'Use for rich previews: profiles, entity summaries, link previews.'},
-      {guidance: true, description: 'Prefer HoverCard for standard trigger-content pairs; use hook for custom trigger patterns.'},
-      {guidance: false, description: 'Use for simple text hints: use Tooltip / useTooltip instead.'},
+      {
+        guidance: true,
+        description:
+          'Use for rich previews: profiles, entity summaries, link previews.',
+      },
+      {
+        guidance: true,
+        description:
+          'Prefer HoverCard for standard trigger-content pairs; use hook for custom trigger patterns.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for simple text hints: use Tooltip / useTooltip instead.',
+      },
     ],
   },
 };

package/src/HoverCard/useHoverCard.tsx

@@ -16,9 +16,11 @@ import {
   useCallback,
   useEffect,
   useRef,
+  useState,
   type ReactNode,
   type RefCallback,
 } from 'react';
+import {createTriggerFocusGate} from '../utils/triggerFocus';
 import * as stylex from '@stylexjs/stylex';
 import {
   useLayer,
@@ -60,7 +62,7 @@ const styles = stylex.create({
 });
 
 /**
- * Focus trigger behavior for hover cards
+ * When focus on the trigger opens the hover card
  */
 export type HoverCardFocusTrigger = 'auto' | 'always' | 'never';
 
@@ -96,9 +98,10 @@ export interface HoverCardOptions {
 
   /**
    * When to trigger on focus:
-   * - `auto`: Only if element is naturally focusable
-   * - `always`: Always attach focus listeners
-   * - `never`: Never attach focus listeners (for composite widgets)
+   * - `auto`: focus on the trigger itself, or within a trigger that is
+   *   focusable when focus arrives
+   * - `always`: focus on the trigger or anything inside it
+   * - `never`: never on focus (for composite widgets)
    *
    * @default 'auto'
    */
@@ -235,29 +238,6 @@ export interface HoverCardReturn {
   hide: () => void;
 }
 
-/**
- * Check if an element is naturally focusable
- */
-function isFocusable(element: HTMLElement): boolean {
-  // Elements with explicit tabindex
-  if (element.hasAttribute('tabindex')) {
-    return element.tabIndex >= 0;
-  }
-
-  // Naturally focusable elements
-  const focusableTags = ['A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA'];
-  if (focusableTags.includes(element.tagName)) {
-    return !(element as HTMLButtonElement).disabled;
-  }
-
-  // Elements with contenteditable
-  if (element.isContentEditable) {
-    return true;
-  }
-
-  return false;
-}
-
 /**
  * Hook for hover card behavior with hover/focus triggers.
  *
@@ -421,32 +401,54 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
   // Tap-to-open on touch; on a mouse this does nothing and hover still rules.
   const handlePointerDown = useCallback(
     (event: PointerEvent) => {
-      handleTouchPointerDown(event);
+      // A pen in range starts the hover show before it lands. Left pending,
+      // that show opens the card during the press. The tap then closes it.
+      if (handleTouchPointerDown(event) && showTimeoutRef.current) {
+        clearTimeout(showTimeoutRef.current);
+        showTimeoutRef.current = null;
+      }
     },
     [handleTouchPointerDown],
   );
 
-  const handleFocusIn = useCallback(() => {
-    if (!isEnabled) {
-      return;
-    }
-    // A tap focuses the trigger it activates. Opening on that focus would
-    // reinstate exactly the behavior the touch path just decided against —
-    // and on an action trigger it covers the thing the user tapped.
-    if (isTouchInteraction()) {
-      return;
-    }
-    // Skip showing if we're in the middle of an Escape dismiss
-    if (isEscapeDismissingRef.current) {
-      isEscapeDismissingRef.current = false;
-      return;
-    }
-    clearTimeouts();
-    showLayer();
-  }, [isEnabled, isTouchInteraction, clearTimeouts, showLayer]);
+  // Under `auto`, whether focus counts is decided when it arrives, and a
+  // focus that counted still hides on blur (utils/triggerFocus.ts).
+  const [focusGate] = useState(createTriggerFocusGate);
+
+  const handleFocusIn = useCallback(
+    (e: Event) => {
+      if (!focusGate.focusIn(e, focusTrigger) || !isEnabled) {
+        return;
+      }
+      // A tap focuses the trigger it activates. Opening on that focus would
+      // reinstate exactly the behavior the touch path just decided against —
+      // and on an action trigger it covers the thing the user tapped.
+      if (isTouchInteraction()) {
+        return;
+      }
+      // Skip showing if we're in the middle of an Escape dismiss
+      if (isEscapeDismissingRef.current) {
+        isEscapeDismissingRef.current = false;
+        return;
+      }
+      clearTimeouts();
+      showLayer();
+    },
+    [
+      focusGate,
+      focusTrigger,
+      isEnabled,
+      isTouchInteraction,
+      clearTimeouts,
+      showLayer,
+    ],
+  );
 
   const handleFocusOut = useCallback(
     (e: FocusEvent) => {
+      if (!focusGate.focusOut(e, focusTrigger)) {
+        return;
+      }
       // Check if focus is moving to the hover card content
       const relatedTarget = e.relatedTarget as HTMLElement | null;
       const popoverElement = document.getElementById(layerId);
@@ -458,7 +460,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
       scheduleHide();
     },
-    [layerId, scheduleHide],
+    [focusGate, focusTrigger, layerId, scheduleHide],
   );
 
   // Escape dismissal (WCAG 1.4.13) goes through the shared layer stack: a
@@ -558,12 +560,9 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         el.addEventListener('mouseleave', handleMouseLeave);
         el.addEventListener('pointerdown', handlePointerDown);
 
-        // Attach focus listeners based on focusTrigger option
-        const shouldAttachFocus =
-          focusTrigger === 'always' ||
-          (focusTrigger === 'auto' && isFocusable(el));
-
-        if (shouldAttachFocus) {
+        // Focus listeners unless focus never opens the card; `auto` decides
+        // per event (utils/triggerFocus.ts).
+        if (focusTrigger !== 'never') {
           el.addEventListener('focusin', handleFocusIn);
           el.addEventListener('focusout', handleFocusOut as EventListener);
         }
@@ -591,7 +590,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     [layerRef, interactionRef],
   );
 
-  // Cleanup on unmount
+  // Releases the hover-card timers on unmount.
   useEffect(() => {
     return () => {
       clearTimeouts();
@@ -606,7 +605,8 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- intentionally only on mount
   }, []);
 
-  // Controlled open state — overrides hover/focus triggers
+  // Syncs the layer with the controlled `isOpen`. A close moves focus back to
+  // the trigger when the card holds it.
   useEffect(() => {
     if (isOpen === undefined) {
       return;

package/src/Icon/Icon.doc.mjs

@@ -71,15 +71,16 @@ export const docs = {
   props: [
     {
       name: 'icon',
-      type: 'IconName | ComponentType<SVGProps>',
+      type: 'IconName | NamespacedIconName | ComponentType<SVGProps>',
       description:
-        'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
+        'Semantic icon name or SVG component. Valid semantic names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. A namespaced key such as `richtext:bold` names a glyph that one component or library registers, and a theme can replace it by key; a namespaced key that nothing registers renders nothing. For any icon not in this list, pass an SVG component directly (e.g. import from lucide-react or @heroicons/react). Note: this prop is called `icon`, not `name`.',
       required: true,
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: 'Color variant mapped to Astryx icon color tokens.',
+      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit' | 'blue' | 'red' | 'green' | 'gray' | 'cyan' | 'teal' | 'yellow' | 'orange' | 'pink' | 'purple'",
+      description:
+        'Color variant mapped to Astryx icon color tokens. Semantic values (primary through warning) follow the role, and inherit uses the surrounding text color. On the web, Icon also accepts the palette values blue, red, green, gray, cyan, teal, yellow, orange, pink, and purple, which pick a non-semantic hue.',
       default: "'inherit'",
     },
     {
@@ -107,6 +108,24 @@ export const docs = {
       description:
         "StyleX styles for customization (color, size, opacity). Folded into the icon's own stylex.props() call so it composes with the base color/size styles. Must be a stylex.create() value, not an inline style object like style={{}}.",
     },
+    {
+      name: 'className',
+      type: 'string',
+      description:
+        'Class name added to the rendered glyph, beside the astryx-icon target class.',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        "Inline styles merged onto the rendered glyph after Icon's own size and color styles.",
+    },
+    {
+      name: 'ref',
+      type: 'Ref<SVGSVGElement>',
+      description:
+        'Ref to the rendered SVG element, for an icon component and for a semantic or namespaced name. For a name, it is the <svg> inside the wrapper, or null when the resolved glyph has no <svg>.',
+    },
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
@@ -207,15 +226,16 @@ export const docsZh = {
   props: [
     {
       name: 'icon',
-      type: 'IconName | ComponentType<SVGProps>',
+      type: 'IconName | NamespacedIconName | ComponentType<SVGProps>',
       description:
-        '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。列表之外的图标请直接传入 SVG 组件。',
+        '语义图标名称或 SVG 组件。有效语义名称：close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone。命名空间键（如 `richtext:bold`）指向某个组件或库注册的图标，主题可以按键替换它；没有注册的命名空间键不渲染任何内容。列表之外的图标请直接传入 SVG 组件。',
       required: true,
     },
     {
       name: 'color',
-      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit'",
-      description: '映射到 Astryx 图标颜色令牌的颜色变体。',
+      type: "'primary' | 'secondary' | 'tertiary' | 'disabled' | 'accent' | 'info' | 'success' | 'error' | 'warning' | 'inherit' | 'blue' | 'red' | 'green' | 'gray' | 'cyan' | 'teal' | 'yellow' | 'orange' | 'pink' | 'purple'",
+      description:
+        '映射到 Astryx 图标颜色令牌的颜色变体。语义值（primary 到 warning）跟随角色，inherit 使用周围文字的颜色。在 Web 上，Icon 还接受调色板值 blue、red、green、gray、cyan、teal、yellow、orange、pink 和 purple，它们选择非语义色相。',
       default: "'inherit'",
     },
     {
@@ -243,6 +263,23 @@ export const docsZh = {
       description:
         '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
     },
+    {
+      name: 'className',
+      type: 'string',
+      description: '添加到渲染图标上的类名，与 astryx-icon 目标类名并列。',
+    },
+    {
+      name: 'style',
+      type: 'CSSProperties',
+      description:
+        '合并到渲染图标上的内联样式，位于 Icon 自身的尺寸和颜色样式之后。',
+    },
+    {
+      name: 'ref',
+      type: 'Ref<SVGSVGElement>',
+      description:
+        '指向渲染的 SVG 元素的 ref，适用于图标组件以及语义名称或命名空间名称。对于名称，它指向包装元素内的 <svg>；若解析出的图形没有 <svg>，则为 null。',
+    },
   ],
   theming: {
     targets: [{className: 'astryx-icon', visualProps: ['color', 'size']}],
@@ -390,8 +427,9 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. For others, pass an SVG component.',
-    color: 'Color variant mapped to Astryx icon color tokens.',
+    icon: 'Semantic icon name or SVG component. Valid names: close, chevronDown, chevronLeft, chevronRight, chevronsLeft, chevronsRight, check, success, error, warning, info, calendar, clock, externalLink, menu, moreHorizontal, search, upload, arrowUp, arrowDown, arrowsUpDown, funnel, eyeSlash, viewColumns, copy, checkDouble, wrench, stop, microphone. A namespaced key (`richtext:bold`) names a glyph a component or library registers; an unregistered one renders nothing. For others, pass an SVG component.',
+    color:
+      'Color variant mapped to Astryx icon color tokens; inherit = surrounding text color. Web also accepts the non-semantic palette: blue, red, green, gray, cyan, teal, yellow, orange, pink, purple.',
     size: "xsm/sm/md/lg = 12/16/20/24px at a 16px root, scale w/ root font size; theme sets a size's glyph dimension via width + height (px or rem) on components.icon['size:sm'] etc. Explicit Icon size; otherwise nearest owning-component default, then 'md' when no contextual default exists",
     variant:
       "Requests the active theme's alternate artwork (e.g. 'filled'); names from augmentable IconVariantMap. Reaches the entry only if the active theme's iconVariants lists it (and an inherited entry's defining theme does too); else normal artwork. Ignored by a directly passed component; never in the DOM; no theming selector.",
@@ -399,5 +437,8 @@ export const docsDense = {
       'Accessible name for a meaningful, standalone icon. Sets role="img" + aria-label and drops the default aria-hidden. Omit (default) for decorative icons (stays aria-hidden). Empty string = decorative. The accessible-name/alt-text prop for icons.',
     xstyle:
       'StyleX styles (color, size, opacity) via stylex.create(); composes with the base color/size styles.',
+    className: 'Class added to the rendered glyph beside astryx-icon.',
+    style: "Inline styles merged after Icon's size and color styles.",
+    ref: 'Reaches the rendered SVG for every icon value; null when a resolved glyph has no <svg>.',
   },
 };

package/src/Icon/Icon.tsx

@@ -30,7 +30,7 @@
  * - /packages/cli/assets/templates/blocks/components/Icon/ (showcase blocks)
  */
 
-import React, {type ComponentType, type SVGProps} from 'react';
+import React, {useCallback, type ComponentType, type SVGProps} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
@@ -39,6 +39,7 @@ import {resolveIcon} from './globalIconRegistry';
 import type {IconName, NamespacedIconName} from './globalIconRegistry';
 import type {IconVariant} from './index';
 import {mergeProps} from '../utils/mergeProps';
+import {mergeRefs} from '../utils/mergeRefs';
 import {themeProps} from '../utils/themeProps';
 import {useIconSize} from './IconDefaultSizeContext';
 import {iconSizeStyles, type IconSize} from './IconSize.stylex';
@@ -176,7 +177,11 @@ export interface IconProps extends Omit<
   SVGProps<SVGSVGElement>,
   'ref' | 'color'
 > {
-  /** Ref forwarded to the root element */
+  /**
+   * Ref to the rendered SVG element. For a semantic or namespaced name it is
+   * the `<svg>` inside Icon's wrapper, or `null` when the resolved glyph has
+   * no `<svg>`.
+   */
   ref?: React.Ref<SVGSVGElement>;
   /**
    * Icon to render. Can be:
@@ -267,22 +272,26 @@ export interface IconProps extends Omit<
   xstyle?: StyleXStyles;
 }
 
+type IconA11yProps =
+  | {role: 'img'; 'aria-label': string; 'aria-hidden': undefined}
+  | {'aria-hidden': 'true'};
+
 /**
  * Derives the ARIA attributes for an icon from its `label` prop.
  *
  * - Non-empty `label` → meaningful image: `role="img"` + `aria-label`, and no
  *   `aria-hidden` (an `aria-hidden` element is removed from the accessibility
- *   tree, so its accessible name would be ignored).
+ *   tree, so its accessible name would be ignored). Icon passes
+ *   `aria-hidden: undefined`. Many icon components, such as Heroicons, write
+ *   `aria-hidden="true"` unless a prop replaces it.
  * - Omitted or empty `label` → decorative default: `aria-hidden="true"`.
  *
  * The result is spread BEFORE `{...props}` in both render modes so an explicit
  * `aria-hidden` / `role` / `aria-label` from the consumer always wins.
  */
-function getIconA11yProps(
-  label: string | undefined,
-): {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'} {
+function getIconA11yProps(label: string | undefined): IconA11yProps {
   return label != null && label !== ''
-    ? {role: 'img', 'aria-label': label}
+    ? {role: 'img', 'aria-label': label, 'aria-hidden': undefined}
     : {'aria-hidden': 'true'};
 }
 
@@ -327,6 +336,7 @@ export function Icon({
         className={className}
         style={style}
         xstyle={xstyle}
+        svgRef={ref}
         spanProps={props}
       />
     );
@@ -386,20 +396,32 @@ function IconFromRegistry({
   className,
   style,
   xstyle,
+  svgRef,
   spanProps,
 }: {
   name: IconName | NamespacedIconName;
   color: IconColor;
   size: IconSize;
   variant: IconVariant | undefined;
-  a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
+  a11yProps: IconA11yProps;
   className?: string;
   style?: React.CSSProperties;
   xstyle?: StyleXStyles;
+  svgRef?: React.Ref<SVGSVGElement>;
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
   const themeName = useThemeName();
   const resolvedIcon = resolveIcon(name, themeName, {size, variant});
+  // The glyph can change while the span stays. Attach the ref again when it
+  // does.
+  const attachSvgRef = useCallback(
+    (span: HTMLSpanElement | null) =>
+      svgRef == null
+        ? undefined
+        : mergeRefs(svgRef)(span?.querySelector('svg') ?? null),
+    // eslint-disable-next-line @eslint-react/exhaustive-deps -- resolveIcon's inputs: a new glyph gets a new attach, and a function entry's new element each render does not.
+    [svgRef, name, themeName, size, variant],
+  );
 
   if (resolvedIcon == null) {
     return null;
@@ -415,6 +437,7 @@ function IconFromRegistry({
 
   return (
     <span
+      ref={svgRef == null ? undefined : attachSvgRef}
       // Derived a11y — decorative (aria-hidden) by default, or a meaningful
       // image (role="img" + aria-label) when `label` is set. Placed BEFORE the
       // prop spread so consumers can still override it with explicit