@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/src/FileInput/FileInput.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file FileInput.tsx
- * @input Uses React, useId, Field, Icon, Spinner
+ * @input Uses React, useId, Field, Icon, Spinner, VisuallyHidden
  * @output Exports FileInput component, FileInputProps, FileInputStatus
  * @position Core implementation; consumed by index.ts, tested by FileInput.test.tsx
  *
@@ -40,11 +40,14 @@ import {
   Field,
   InputClearButton,
   type InputStatus,
-  type InputStatusType,
+  type FieldStatusVariant,
 } from '../Field';
-import {Icon, type IconName} from '../Icon';
+import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
+import {VisuallyHidden} from '../VisuallyHidden';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useInputStatusIcon} from '../hooks/useInputStatusIcon';
+import {useClickableContainer} from '../hooks/useClickableContainer';
 import {useTooltip} from '../Tooltip';
 
 export type {
@@ -246,17 +249,6 @@ const styles = stylex.create({
     flex: 1,
     minWidth: 0,
   },
-  liveRegion: {
-    position: 'absolute',
-    width: 1,
-    height: 1,
-    padding: 0,
-    margin: -1,
-    overflow: 'hidden',
-    clip: 'rect(0, 0, 0, 0)',
-    whiteSpace: 'nowrap',
-    borderWidth: 0,
-  },
 });
 
 const statusBorderStyles = stylex.create({
@@ -358,6 +350,14 @@ export interface FileInputProps extends Omit<
    * Validation status for the input.
    */
   status?: InputStatus;
+  /**
+   * How the status message is placed relative to the input.
+   * - 'attached': message overlaps directly below the input (bordered treatment)
+   * - 'detached': message floats below as a separate element with spacing
+   * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
+   * @default 'attached'
+   */
+  statusVariant?: FieldStatusVariant;
   /**
    * Description text displayed below the label.
    */
@@ -414,6 +414,7 @@ export function FileInput({
   isRequired = false,
   isLoading = false,
   status: statusProp,
+  statusVariant = 'attached',
   description,
   placeholder,
   mode = 'input',
@@ -430,22 +431,24 @@ export function FileInput({
   const id = useId();
   const descriptionID = useId();
   const statusMessageID = useId();
-  const liveRegionID = useId();
+  const requiredID = useId();
   const inputRef = useRef<HTMLInputElement | null>(null);
+  const containerRef = useRef<HTMLDivElement | null>(null);
   const [isDragOver, setIsDragOver] = useState(false);
   const [validationError, setValidationError] = useState<string | null>(null);
   const [, startTransition] = useTransition();
 
   // Announce successful file selection to screen readers via a persistent
-  // live region (forms-17). The component's own role="status" region only
-  // carries validation errors, so a successful attach was previously silent.
+  // live region (forms-17). Validation errors are announced (assertively) by
+  // the FieldStatus that the derived error status mounts, so only the
+  // successful attach needs an explicit announcement here.
   const announce = useAnnounce();
 
   // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the role="button" trigger (which already
-  // exists) and the trigger stays perceivable via aria-disabled instead of the
-  // native disabled attribute. Opening the picker is blocked by the isDisabled
-  // guards in handleClick / handleKeyDown / handleFiles.
+  // tooltip listeners attach to the visible container (which stays hoverable)
+  // and the trigger stays perceivable via aria-disabled instead of the native
+  // disabled attribute. Opening the picker is blocked by the isDisabled guards
+  // in the handlers.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -459,25 +462,27 @@ export function FileInput({
       ? {type: 'error' as const, message: validationError}
       : undefined);
 
-  const statusIconMap: Record<InputStatusType, IconName> = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  const {statusIcon, describedBy: statusTooltipDescribedBy} =
+    useInputStatusIcon({
+      status,
+      statusVariant,
+    });
 
-  const statusIconColorMap: Record<
-    InputStatusType,
-    'warning' | 'error' | 'success'
-  > = {
-    warning: 'warning',
-    error: 'error',
-    success: 'success',
-  };
+  // Required state. The trigger is a real button, but AT does not reliably
+  // announce aria-required, so the trigger instead points its aria-describedby
+  // at a visually hidden "Required" span — mirroring the Field label's visible
+  // indicator (where isOptional takes precedence) and the pattern Slider uses
+  // for its thumbs.
+  const conveysRequired = isRequired && !isOptional;
 
   const ariaDescribedBy =
     [
       description ? descriptionID : null,
-      status?.message ? statusMessageID : null,
+      statusVariant !== 'tooltip' && status?.message ? statusMessageID : null,
+      // The tooltip variant renders no message box; describe the input by the
+      // tooltip's content instead so the status is still announced.
+      statusTooltipDescribedBy,
+      conveysRequired ? requiredID : null,
       showsDisabledMessage ? disabledMessageTooltip.describedBy : null,
     ]
       .filter(Boolean)
@@ -515,8 +520,9 @@ export function FileInput({
       onChange(result);
 
       // Announce the successful selection politely. Validation errors are
-      // handled by the role="status" region below, so only announce the
-      // attach here (do not double-announce errors).
+      // announced assertively by the FieldStatus that the derived error
+      // status mounts, so only announce the attach here (do not
+      // double-announce errors).
       if (errors.length === 0) {
         announce(
           valid.length === 1
@@ -574,6 +580,9 @@ export function FileInput({
     }
   }, [isDisabled]);
 
+  // Explicit keyboard activation so Enter/Space open the picker even where a
+  // synthetic keydown does not raise a native click. The isDisabled guard
+  // blocks activation while focusable-disabled.
   const handleKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
       if ((e.key === 'Enter' || e.key === ' ') && !isDisabled) {
@@ -584,6 +593,16 @@ export function FileInput({
     [isDisabled],
   );
 
+  // Make the surface clickable without giving it an interactive role. Clicks on
+  // the nested clear/status controls are ignored by the hook, so those buttons
+  // are plain siblings — no nested-interactive violation.
+  const {onClick: onContainerClick, onMouseUp: onContainerMouseUp} =
+    useClickableContainer({
+      containerRef,
+      onClick: handleClick,
+      disabled: isDisabled,
+    });
+
   const handleDragEnter = useCallback(
     (e: DragEvent) => {
       e.preventDefault();
@@ -687,13 +706,7 @@ export function FileInput({
           )}>
           {fileNames ?? displayPlaceholder}
         </span>
-        {status && (
-          <Icon
-            icon={statusIconMap[status.type]}
-            size="md"
-            color={statusIconColorMap[status.type]}
-          />
-        )}
+        {statusIcon}
       </>
     );
   };
@@ -728,39 +741,21 @@ export function FileInput({
             }
           : undefined
       }
+      statusVariant={statusVariant}
       labelTooltip={labelTooltip}
       width={width}>
       <div
         ref={el => {
-          // Anchor + hover/focus listeners for the disabled-message tooltip.
-          // Handlers are gated internally by isEnabled, and anchor names
-          // compose, so attaching unconditionally is safe.
+          containerRef.current = el;
+          // Anchor + hover/focus listeners for the disabled-message tooltip on
+          // the visible container (the focusable trigger is visually hidden, so
+          // anchoring there would place the tooltip at a 1px box). focusin
+          // bubbles from the trigger button, so the tooltip still opens on
+          // keyboard focus. Handlers are gated internally by isEnabled.
           disabledMessageTooltip.ref(el);
         }}
-        role="button"
-        // With a disabledMessage the trigger keeps focusability via
-        // aria-disabled so the reason is focus-discoverable; opening the picker
-        // is still blocked by the isDisabled guards in the handlers.
-        tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
-        aria-disabled={showsDisabledMessage ? 'true' : undefined}
-        onClick={handleClick}
-        onKeyDown={handleKeyDown}
-        // aria-label suppresses child content from the accessible name, so
-        // compose the selected filenames into it — otherwise a screen-reader
-        // user refocusing the control hears only the field label and cannot
-        // tell what (if anything) is attached.
-        aria-label={
-          hasFiles && fileNames
-            ? t('@astryx.fileInput.triggerWithFiles', {label, fileNames})
-            : label
-        }
-        aria-busy={isLoading || undefined}
-        // These describe the operable control, so they belong on the focusable
-        // role="button" wrapper — not the hidden tabIndex={-1} file input the
-        // user never focuses (forms-6).
-        aria-describedby={ariaDescribedBy}
-        aria-required={isRequired ? 'true' : undefined}
-        aria-invalid={status?.type === 'error' ? 'true' : undefined}
+        onClick={!isDisabled ? onContainerClick : undefined}
+        onMouseUp={!isDisabled ? onContainerMouseUp : undefined}
         {...dragDropProps}
         {...mergeProps(
           themeProps('file-input', {mode, status: status?.type ?? null}),
@@ -776,6 +771,40 @@ export function FileInput({
           className,
           style,
         )}>
+        {/* Visually hidden real button carrying the accessible role, name, and
+            ARIA. Kept as a sibling of the clear/status controls inside a
+            non-interactive container, so no interactive element nests inside
+            another (WCAG 4.1.2). The visible focus feedback is the container's
+            :focus-within border; the surface click is handled by the container
+            (VisuallyHidden disables the button's own pointer events), and
+            keyboard activation still fires here. */}
+        <VisuallyHidden>
+          <button
+            type="button"
+            // With a disabledMessage the trigger keeps focusability via
+            // aria-disabled so the reason is focus-discoverable; opening the
+            // picker is still blocked by the isDisabled guards in the handlers.
+            // Otherwise the native disabled attribute removes it from the tab
+            // order.
+            disabled={isDisabled && !showsDisabledMessage}
+            tabIndex={isDisabled && !showsDisabledMessage ? -1 : 0}
+            aria-disabled={showsDisabledMessage ? 'true' : undefined}
+            onClick={handleClick}
+            onKeyDown={handleKeyDown}
+            // aria-label suppresses child content from the accessible name, so
+            // compose the selected filenames into it — otherwise a
+            // screen-reader user refocusing the control hears only the field
+            // label and cannot tell what (if anything) is attached.
+            aria-label={
+              hasFiles && fileNames
+                ? t('@astryx.fileInput.triggerWithFiles', {label, fileNames})
+                : label
+            }
+            aria-busy={isLoading || undefined}
+            aria-describedby={ariaDescribedBy}
+            aria-invalid={status?.type === 'error' ? 'true' : undefined}
+          />
+        </VisuallyHidden>
         <input
           {...rest}
           ref={mergeRefs(ref, inputRef)}
@@ -786,7 +815,7 @@ export function FileInput({
           disabled={isDisabled}
           onChange={handleInputChange}
           // The visually-hidden native input is never focused (tabIndex={-1});
-          // its describedby/required/invalid live on the role="button" wrapper.
+          // its describedby/required/invalid live on the trigger button.
           aria-hidden="true"
           tabIndex={-1}
           {...stylex.props(styles.hiddenInput)}
@@ -799,13 +828,11 @@ export function FileInput({
           />
         )}
       </div>
-      <div
-        id={liveRegionID}
-        role="status"
-        aria-live="polite"
-        {...stylex.props(styles.liveRegion)}>
-        {validationError}
-      </div>
+      {conveysRequired && (
+        <VisuallyHidden id={requiredID}>
+          {t('@astryx.fileInput.required')}
+        </VisuallyHidden>
+      )}
       {showsDisabledMessage &&
         disabledMessageTooltip.renderTooltip(disabledMessage)}
     </Field>

package/src/HoverCard/useHoverCard.tsx

@@ -34,7 +34,6 @@ import {
   radiusVars,
   spacingVars,
 } from '../theme/tokens.stylex';
-import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
 
 const styles = stylex.create({
@@ -469,6 +468,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
       props?: Omit<ContextRenderProps, 'positioning'>,
     ): ReactNode => {
       const renderPlacement = props?.placement ?? placement;
+      const themeClassName = themeProps('hovercard').className;
       const renderProps = {
         placement: renderPlacement,
         alignment: props?.alignment ?? alignment,
@@ -477,7 +477,19 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
         // are non-modal, so group is honest semantics without a name.
         role: label ? 'dialog' : 'group',
         'aria-label': label || undefined,
-        xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+        // Consumer surface style props land on the layer container — the
+        // themed surface (bg/radius/shadow) where the theme class lives — so
+        // customizing the card targets the same element as the theme. The inner
+        // span keeps `styles.content` for padding.
+        xstyle: [
+          popoverXstyle,
+          layerAnimations[renderPlacement],
+          props?.xstyle,
+        ],
+        className: props?.className
+          ? `${themeClassName} ${props.className}`
+          : themeClassName,
+        style: props?.style,
         // Render the layer as inline-safe phrasing markup so HoverCard stays
         // valid (and hydration-stable) inside inline contexts like a `<p>`.
         as: 'span' as const,
@@ -485,7 +497,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
 
       return layer.render(
         <span
-          {...mergeProps(themeProps('hovercard'), stylex.props(styles.content))}
+          {...stylex.props(styles.content)}
           onMouseEnter={() => {
             isHoveringContentRef.current = true;
             clearTimeouts();

package/src/Icon/Icon.doc.mjs

@@ -39,6 +39,12 @@ export const docs = {
       type: 'string',
       description: 'Accessible name for a MEANINGFUL, standalone icon (a status glyph or icon-only indicator with no adjacent text). Setting it exposes the icon to screen readers as role="img" with this text as the accessible name (aria-label) and removes the default aria-hidden. Omit it (default) for decorative icons and the icon stays hidden from assistive tech (aria-hidden="true"). This is the accessible-name / alt-text prop for icons: one prop instead of manually setting aria-label + role + aria-hidden. An empty string is treated as decorative. Do not set it when an interactive parent (Button, IconButton, link) already names the control.',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      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={{}}.',
+    },
   ],
   theming: {
     targets: [
@@ -90,6 +96,12 @@ export const docsZh = {
       type: 'string',
       description: '有含义的独立图标的可访问名称（无相邻文字的状态图标或纯图标指示器）。设置后会将图标以 role="img" 暴露给辅助技术，并以该文本作为可访问名称（aria-label），同时移除默认的 aria-hidden。省略（默认）用于装饰性图标，图标对辅助技术保持隐藏（aria-hidden="true"）。空字符串按装饰性处理。当交互式父元素（Button、IconButton、链接）已命名该控件时请勿设置。',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        '用于自定义的 StyleX 样式（颜色、尺寸、不透明度）。会并入图标自身的 stylex.props() 调用，从而与基础的颜色/尺寸样式组合。必须是 stylex.create() 的值，而不是像 style={{}} 这样的内联样式对象。',
+    },
   ],
   theming: {
     targets: [
@@ -136,5 +148,6 @@ export const docsDense = {
     color: 'Color variant mapped to Astryx icon color tokens.',
     size: 'Icon size.',
     label: '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.',
   },
 };

package/src/Icon/Icon.test.tsx

@@ -11,6 +11,7 @@
 
 import {describe, it, expect, vi} from 'vitest';
 import {render, screen} from '@testing-library/react';
+import * as stylex from '@stylexjs/stylex';
 import {TestIcon} from '../__tests__/TestIcon';
 import {Icon} from './Icon';
 
@@ -279,4 +280,92 @@ describe('Icon', () => {
       );
     });
   });
+
+  describe('styling prop handling', () => {
+    it('composes a consumer className with the internal classes (string mode)', () => {
+      render(
+        <Icon icon="check" className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      // Consumer className must survive alongside the stable astryx-icon class
+      // and the StyleX classes — previously it was clobbered by the later
+      // internal spread.
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('astryx-icon');
+      // At least one StyleX-generated class is still present.
+      expect(icon.className.split(' ').length).toBeGreaterThan(2);
+    });
+
+    it('forwards a consumer className in component (SVG) mode', () => {
+      render(
+        <Icon icon={TestIcon} className="consumer-target" data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('consumer-target');
+      expect(icon).toHaveClass('astryx-icon');
+    });
+
+    it('merges a consumer style onto the rendered element (string mode)', () => {
+      render(<Icon icon="check" style={{opacity: 0.5}} data-testid="icon" />);
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('merges a consumer style onto the rendered element (component mode)', () => {
+      render(
+        <Icon icon={TestIcon} style={{opacity: 0.5}} data-testid="icon" />,
+      );
+      expect(screen.getByTestId('icon')).toHaveStyle({opacity: '0.5'});
+    });
+
+    it('applies xstyle to the rendered element (string mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(<Icon icon="check" xstyle={overrides.root} data-testid="icon" />);
+      const icon = screen.getByTestId('icon');
+      // xstyle is folded into stylex.props, so it contributes a StyleX class
+      // (and, in jsdom's stylex runtime, an inline style) alongside the base
+      // color/size classes rather than clobbering them.
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('applies xstyle to the rendered element (component mode)', () => {
+      const overrides = stylex.create({root: {opacity: 0.25}});
+      render(
+        <Icon icon={TestIcon} xstyle={overrides.root} data-testid="icon" />,
+      );
+      const icon = screen.getByTestId('icon');
+      expect(icon).toHaveClass('astryx-icon');
+      expect(icon).toHaveStyle({opacity: '0.25'});
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (string mode)', () => {
+      const {container} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.astryx-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon="check" size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+      // Default output is identical to itself — the styling-prop handling adds
+      // nothing (no extra class, no inline style) unless a prop is passed.
+      expect(icon.className).toBe(refIcon.className);
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+
+    it('leaves default rendering unchanged when no styling props are passed (component mode)', () => {
+      const {container} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const icon = container.querySelector('.astryx-icon') as HTMLElement;
+      const {container: refContainer} = render(
+        <Icon icon={TestIcon} size="sm" color="secondary" />,
+      );
+      const refIcon = refContainer.querySelector('.astryx-icon') as HTMLElement;
+      // SVGElement.className is an SVGAnimatedString, so compare the class
+      // attribute string rather than the property object.
+      expect(icon.getAttribute('class')).toBe(refIcon.getAttribute('class'));
+      expect(icon.getAttribute('style')).toBe(refIcon.getAttribute('style'));
+    });
+  });
 });

package/src/Icon/Icon.tsx

@@ -24,6 +24,7 @@
 
 import React, {type ComponentType, type SVGProps} from 'react';
 import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
 import {colorVars} from '../theme/tokens.stylex';
 import {getIcon} from './globalIconRegistry';
 import type {IconName} from './globalIconRegistry';
@@ -244,6 +245,19 @@ export interface IconProps extends Omit<
    * ```
    */
   label?: string;
+  /**
+   * StyleX styles created via `stylex.create()`. Folded into the icon's own
+   * `stylex.props()` call (as the last argument) so it merges with the base
+   * color/size styles for optimal deduplication, matching how other Astryx
+   * components accept `xstyle`.
+   *
+   * @example
+   * ```
+   * const overrides = stylex.create({ root: { opacity: 0.5 } });
+   * <Icon icon="search" xstyle={overrides.root} />
+   * ```
+   */
+  xstyle?: StyleXStyles;
 }
 
 /**
@@ -283,6 +297,9 @@ export function Icon({
   size = 'md',
   label,
   ref,
+  className,
+  style,
+  xstyle,
   ...props
 }: IconProps) {
   // Derive ARIA from `label`: decorative (aria-hidden) by default, or a
@@ -297,6 +314,9 @@ export function Icon({
         color={color}
         size={size}
         a11yProps={a11yProps}
+        className={className}
+        style={style}
+        xstyle={xstyle}
         spanProps={props}
       />
     );
@@ -311,9 +331,16 @@ export function Icon({
       // BEFORE {...props} so an explicit aria-hidden/role/aria-label from the
       // consumer still wins as an escape hatch.
       {...a11yProps}
+      // The styling props (className, style, xstyle) are handled here so they
+      // COMPOSE with the internal classes/styles instead of clobbering them:
+      // xstyle folds into stylex.props, and className/style merge via
+      // mergeProps. The remaining rest props keep their prior last-spread
+      // precedence as escape hatches.
       {...mergeProps(
         themeProps('icon', {size, color}),
-        stylex.props(styles.root, colorStyles[color], sizeStyles[size]),
+        stylex.props(styles.root, colorStyles[color], sizeStyles[size], xstyle),
+        className ?? undefined,
+        style,
       )}
       {...props}
     />
@@ -338,12 +365,18 @@ function IconFromRegistry({
   color,
   size,
   a11yProps,
+  className,
+  style,
+  xstyle,
   spanProps,
 }: {
   name: IconName;
   color: IconColor;
   size: IconSize;
   a11yProps: {role: 'img'; 'aria-label': string} | {'aria-hidden': 'true'};
+  className?: string;
+  style?: React.CSSProperties;
+  xstyle?: StyleXStyles;
   spanProps?: Omit<SVGProps<SVGSVGElement>, 'ref' | 'color'>;
 }) {
   const resolvedIcon = getIcon(name);
@@ -352,6 +385,14 @@ function IconFromRegistry({
     return null;
   }
 
+  // The styling props (className, style, xstyle) are handled here so they
+  // COMPOSE with the internal astryx-icon + StyleX classes/styles instead of
+  // being shadowed by the later spread: xstyle folds into stylex.props, and
+  // className/style merge via mergeProps. Other span props keep their prior
+  // precedence (spread before the internal merge).
+  const restSpanProps =
+    (spanProps as React.HTMLAttributes<HTMLSpanElement>) ?? {};
+
   return (
     <span
       // Derived a11y — decorative (aria-hidden) by default, or a meaningful
@@ -359,10 +400,17 @@ function IconFromRegistry({
       // prop spread so consumers can still override it with explicit
       // aria-hidden/role/aria-label. This mirrors component-mode Icon.
       {...a11yProps}
-      {...(spanProps as React.HTMLAttributes<HTMLSpanElement>)}
+      {...restSpanProps}
       {...mergeProps(
         themeProps('icon', {size, color}),
-        stylex.props(styles.span, colorStyles[color], spanSizeStyles[size]),
+        stylex.props(
+          styles.span,
+          colorStyles[color],
+          spanSizeStyles[size],
+          xstyle,
+        ),
+        className ?? undefined,
+        style,
       )}>
       {resolvedIcon}
     </span>

package/src/Item/Item.doc.mjs

@@ -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".'},
@@ -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。',
@@ -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.',