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

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)
   // ===========================================================================

package/src/Item/Item.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file Item.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, useClickableContainer
  * @output Exports Item component, ItemProps type
  * @position Core layout primitive; consumed by index.ts, tested by Item.test.tsx
  *
@@ -16,7 +16,7 @@
  * - /packages/cli/templates/blocks/components/Item/ (showcase blocks)
  */
 
-import type {ReactNode} from 'react';
+import {useRef, type ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {
   colorVars,
@@ -27,9 +27,11 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import type {BaseProps} from '../BaseProps';
-import {mergeProps} from '../utils';
+import {mergeProps, mergeRefs} from '../utils';
 import {computeTargetAndRel} from '../Link/computeTargetAndRel';
 import {useLinkComponent} from '../Link/useLinkComponent';
+import {useClickableContainer} from '../hooks/useClickableContainer';
+import {useDevWarning} from '../hooks/useDevWarning';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -108,6 +110,20 @@ export interface ItemProps extends BaseProps<HTMLElement> {
    */
   onClick?: (event: React.MouseEvent) => void;
 
+  /**
+   * Ref to a nested control inside the item (e.g. a checkbox in
+   * `startContent`) that already provides the item's keyboard access and
+   * action. When set, the item becomes an enlarged click/tap target that
+   * delegates surface clicks to that control via the `useClickableContainer`
+   * pattern: it renders no invisible button/anchor, so the row adds no second
+   * tab stop (WCAG 4.1.2 — one focusable control per option). Clicks on the
+   * control itself, and on any other nested interactive element, are left to
+   * that element. Mutually exclusive with `onClick`/`href` — when
+   * `interactiveRef` is set those are ignored (the nested control is the sole
+   * action).
+   */
+  interactiveRef?: React.RefObject<HTMLElement | null>;
+
   /**
    * Link URL. Makes the item a link via an invisible anchor element.
    */
@@ -349,6 +365,7 @@ export function Item({
   labelLines,
   descriptionLines,
   onClick,
+  interactiveRef,
   href,
   target: targetFromProps,
   rel: relFromProps,
@@ -363,7 +380,29 @@ export function Item({
   ...restProps
 }: ItemProps) {
   const LinkComponent = useLinkComponent();
-  const isInteractive = onClick != null || href != null;
+
+  // Delegation mode: the row is an enlarged click/tap target for a nested
+  // control (e.g. a checkbox) that owns the keyboard access and action. The
+  // control is the row's only tab stop; the row proxies surface clicks to it.
+  const isDelegate = interactiveRef != null;
+  const containerRef = useRef<HTMLElement | null>(null);
+  // Only onClick is needed: onMouseUp handles middle-click href navigation,
+  // which delegation mode never has (href is ignored here).
+  const {onClick: delegatedOnClick} = useClickableContainer({
+    containerRef,
+    interactiveRef: interactiveRef ?? undefined,
+    disabled: isDisabled,
+  });
+
+  useDevWarning(
+    'Item',
+    '`interactiveRef` is mutually exclusive with `onClick`/`href`. In ' +
+      'delegation mode the row only forwards clicks to the referenced control, ' +
+      'so `onClick`/`href` are ignored. Drop one of them.',
+    isDelegate && (onClick != null || href != null),
+  );
+
+  const isInteractive = onClick != null || href != null || isDelegate;
   const {target, rel} = computeTargetAndRel(targetFromProps, relFromProps);
   // When a semantic role is provided (e.g. "menuitem"), a parent component
   // handles keyboard access. Skip the invisible button/anchor and put
@@ -441,7 +480,10 @@ export function Item({
         <span {...stylex.props(styles.startContent)}>{startContent}</span>
       )}
 
-      {hasParentRole ? (
+      {hasParentRole || isDelegate ? (
+        // Delegation mode (and parent-role mode) put the label in a plain span:
+        // keyboard access lives on the nested control, so no invisible
+        // button/anchor is rendered and the row adds no second tab stop.
         <span
           {...stylex.props(
             styles.content,
@@ -497,7 +539,9 @@ export function Item({
 
   return (
     <Component
-      ref={ref as React.Ref<never>}
+      ref={
+        (isDelegate ? mergeRefs(ref, containerRef) : ref) as React.Ref<never>
+      }
       {...restProps}
       aria-selected={(allowsAriaSelected && isSelected) || undefined}
       // aria-selected is invalid on roles that don't permit it (listitem, a
@@ -527,11 +571,13 @@ export function Item({
       )}
       role={role}
       onClick={
-        hasParentRole
-          ? onClick
-          : isInteractive
-            ? handleContainerClick
-            : undefined
+        isDelegate
+          ? delegatedOnClick
+          : hasParentRole
+            ? onClick
+            : isInteractive
+              ? handleContainerClick
+              : undefined
       }>
       {innerContent}
     </Component>

package/src/Layer/layerAnimations.stylex.ts

@@ -61,6 +61,27 @@ const enterStart = stylex.keyframes({
   to: {opacity: 1, transform: 'translateX(0) scale(1)'},
 });
 
+// RTL: the horizontal entrance nudge is a physical translateX, so it must
+// mirror under RTL — a layer on the inline-end/start side must slide in from
+// the correct physical side following the reading flow. Only the horizontal
+// (translateX) keyframes need mirroring; the vertical enterAbove/enterBelow
+// (translateY) entrances are direction-neutral and are left as-is.
+const enterEndRtl = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(${spacingVars['--spacing-2']}) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
+const enterStartRtl = stylex.keyframes({
+  from: {
+    opacity: 0,
+    transform: `translateX(calc(-1 * ${spacingVars['--spacing-2']})) scale(0.95)`,
+  },
+  to: {opacity: 1, transform: 'translateX(0) scale(1)'},
+});
+
 const animationBase = {
   animationDuration: durationVars['--duration-fast-max'],
   animationTimingFunction: easeVars['--ease-standard'],
@@ -95,6 +116,7 @@ export const layerAnimations = stylex.create({
   end: {
     animationName: {
       default: enterEnd,
+      ':is([dir="rtl"] *)': enterEndRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
     ...animationBase,
@@ -102,6 +124,7 @@ export const layerAnimations = stylex.create({
   start: {
     animationName: {
       default: enterStart,
+      ':is([dir="rtl"] *)': enterStartRtl,
       '@media (prefers-reduced-motion: reduce)': 'none',
     },
     ...animationBase,

package/src/Lightbox/Lightbox.tsx

@@ -32,7 +32,7 @@ import {IconButton} from '../IconButton';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {useScrollLock} from '../hooks/useScrollLock';
 import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
-import {mergeProps, mergeRefs} from '../utils';
+import {mergeProps, mergeRefs, rtlStyles} from '../utils';
 import type {BaseProps} from '../BaseProps';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
@@ -199,7 +199,7 @@ const styles = stylex.create({
   closeButton: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
     zIndex: 1,
   },
   navButton: {
@@ -209,15 +209,15 @@ const styles = stylex.create({
     zIndex: 1,
   },
   navPrev: {
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
   },
   navNext: {
-    right: spacingVars['--spacing-3'],
+    insetInlineEnd: spacingVars['--spacing-3'],
   },
   counter: {
     position: 'absolute',
     top: spacingVars['--spacing-3'],
-    left: spacingVars['--spacing-3'],
+    insetInlineStart: spacingVars['--spacing-3'],
     color: colorVars['--color-on-dark'],
     fontSize: typeScaleVars['--text-body-size'],
     lineHeight: typeScaleVars['--text-body-leading'],
@@ -532,7 +532,11 @@ export function Lightbox({
         {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navPrev)}>
             <IconButton
-              icon={<Icon icon="chevronLeft" size="sm" color="inherit" />}
+              icon={
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon icon="chevronLeft" size="sm" color="inherit" />
+                </span>
+              }
               label={t('@astryx.lightbox.previous')}
               variant="ghost"
               isDisabled={!canPrev}
@@ -587,7 +591,11 @@ export function Lightbox({
         {isGallery && (
           <div {...stylex.props(styles.navButton, styles.navNext)}>
             <IconButton
-              icon={<Icon icon="chevronRight" size="sm" color="inherit" />}
+              icon={
+                <span {...stylex.props(rtlStyles.mirror)}>
+                  <Icon icon="chevronRight" size="sm" color="inherit" />
+                </span>
+              }
               label={t('@astryx.lightbox.next')}
               variant="ghost"
               isDisabled={!canNext}

package/src/List/List.test.tsx

@@ -136,35 +136,23 @@ describe('List', () => {
     expect(container.querySelector('ul')).toBeInTheDocument();
   });
 
-  it('adds role="list" when listStyle is none (Safari fix)', () => {
-    const {container} = render(
-      <List>
-        <ListItem label="Item" />
-      </List>,
-    );
-    const ul = container.querySelector('ul');
-    expect(ul).toHaveAttribute('role', 'list');
-  });
-
-  it('does not add role="list" when listStyle is disc', () => {
-    const {container} = render(
-      <List listStyle="disc">
-        <ListItem label="Item" />
-      </List>,
-    );
-    const ul = container.querySelector('ul');
-    expect(ul).not.toHaveAttribute('role');
-  });
-
-  it('does not add role="list" when listStyle is decimal', () => {
-    const {container} = render(
-      <List listStyle="decimal">
-        <ListItem label="Item" />
-      </List>,
-    );
-    const ol = container.querySelector('ol');
-    expect(ol).not.toHaveAttribute('role');
-  });
+  it.each(['none', 'disc', 'circle', 'decimal'] as const)(
+    'adds an explicit role="list" when listStyle is %s (Safari fix)',
+    listStyle => {
+      // The base list style always sets list-style-type: none (markers are
+      // custom-rendered by ListItem), so Safari/VoiceOver drops the implicit
+      // list role for EVERY variant — the explicit role must always be there.
+      render(
+        <List listStyle={listStyle}>
+          <ListItem label="Item 1" />
+          <ListItem label="Item 2" />
+        </List>,
+      );
+      const list = screen.getByRole('list');
+      expect(list).toHaveAttribute('role', 'list');
+      expect(screen.getAllByRole('listitem')).toHaveLength(2);
+    },
+  );
 
   it('renders items as <li> elements', () => {
     const {container} = render(

package/src/List/List.tsx

@@ -168,7 +168,12 @@ export function List({
       data-testid={testId}
       aria-labelledby={header != null ? headerId : undefined}
       {...(isOrdered && start != null && start !== 1 ? {start} : {})}
-      {...(listStyle === 'none' && !isOrdered ? {role: 'list'} : {})}
+      // The base list style always sets list-style-type: none (markers are
+      // custom-rendered by ListItem), and Safari/VoiceOver drops implicit
+      // list semantics for lists styled with list-style: none. The explicit
+      // role restores "list, N items" announcements for every listStyle
+      // variant.
+      role="list"
       {...mergeProps(
         themeProps('list', {density, listStyle}),
         stylex.props(

package/src/List/ListItem.doc.mjs

@@ -59,6 +59,11 @@ export const docs = {
       type: '(e: MouseEvent) => void',
       description: 'Click handler; enables the invisible button pattern.',
     },
+    {
+      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',
@@ -121,6 +126,11 @@ export const docsZh = {
       type: '(e: MouseEvent) => void',
       description: '点击处理函数；启用隐形按钮模式。',
     },
+    {
+      name: 'interactiveRef',
+      type: 'RefObject<HTMLElement | null>',
+      description: '指向嵌套控件（如 startContent 中的复选框）的 ref，该控件承载项目的键盘访问和操作。行成为更大的点击/触摸目标，将表面点击委托给该控件（useClickableContainer），且不渲染不可见按钮/锚点，因此行不会增加第二个 Tab 停留点（WCAG 4.1.2）。与 onClick/href 互斥——设置后二者将被忽略。',
+    },
     {
       name: 'href',
       type: 'string',
@@ -162,6 +172,8 @@ export const docsDense = {
     startContent: 'Content before label area (e.g. icon, avatar).',
     endContent: 'Content after label area (e.g. badge, chevron).',
     onClick: 'Click handler; enables invisible button pattern.',
+    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 invisible anchor pattern.',
     target: 'Link target attribute, only when href provided. target="_blank" auto-adds noopener noreferrer.',
     rel: 'Link relationship tokens. noopener noreferrer are merged for target="_blank".',

package/src/List/ListItem.tsx

@@ -75,6 +75,17 @@ export interface ListItemProps extends BaseProps<HTMLLIElement> {
    */
   onClick?: (e: React.MouseEvent) => void;
 
+  /**
+   * Ref to a nested control inside the item (e.g. a checkbox in
+   * `startContent`) that already provides the item's keyboard access and
+   * action. When set, the item becomes an enlarged click/tap target that
+   * delegates surface clicks to that control via the `useClickableContainer`
+   * pattern: it renders no invisible button/anchor, so the row adds no second
+   * tab stop (WCAG 4.1.2 — one focusable control per option). Mutually
+   * exclusive with `onClick`/`href` — when set those are ignored.
+   */
+  interactiveRef?: React.RefObject<HTMLElement | null>;
+
   /**
    * URL for link items. Renders an invisible anchor element.
    * Automatically enables hover/press styles when provided.
@@ -199,6 +210,7 @@ export function ListItem({
   startContent,
   endContent,
   onClick,
+  interactiveRef,
   href,
   target,
   rel,
@@ -239,6 +251,7 @@ export function ListItem({
       description={description}
       endContent={endContent}
       onClick={onClick}
+      interactiveRef={interactiveRef}
       href={href}
       target={target as '_blank' | '_self'}
       rel={rel}

package/src/Markdown/Markdown.test.tsx

@@ -236,6 +236,27 @@ describe('Markdown', () => {
     expect(img!.getAttribute('src')).toBe('image.png');
   });
 
+  it('uses the components.image override for a standalone (block) image', () => {
+    // A standalone image line parses as a block image; its render path must
+    // honor components.image just like the inline image path does.
+    render(
+      <Markdown
+        components={{
+          image: ({src, alt}) => (
+            <span data-testid="custom-image" data-src={src}>
+              {alt}
+            </span>
+          ),
+        }}>
+        {'![alt text](image.png)'}
+      </Markdown>,
+    );
+    expect(document.querySelector('img')).not.toBeInTheDocument();
+    const custom = screen.getByTestId('custom-image');
+    expect(custom).toHaveTextContent('alt text');
+    expect(custom.getAttribute('data-src')).toBe('image.png');
+  });
+
   it('shifts heading levels with headingLevelStart', () => {
     render(<Markdown headingLevelStart={3}>{'# Heading 1'}</Markdown>);
     expect(screen.getByText('Heading 1').tagName).toBe('H3');

package/src/Markdown/Markdown.tsx

@@ -1523,6 +1523,10 @@ function renderBlock(
           </div>
         );
       }
+      const ImageComp = components?.image;
+      if (ImageComp) {
+        return <ImageComp key={index} src={safeSrc} alt={node.alt} />;
+      }
       return (
         <div
           key={index}

package/src/MetadataList/MetadataList.test.tsx

@@ -5,6 +5,7 @@ import {render, screen} from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import {MetadataList} from './MetadataList';
 import {MetadataListItem} from './MetadataListItem';
+import {InternationalizationProvider} from '../i18n';
 
 describe('MetadataList', () => {
   it('renders a description list with items', () => {
@@ -87,6 +88,29 @@ describe('MetadataList', () => {
     expect(screen.queryByText('B')).not.toBeInTheDocument();
   });
 
+  it('localizes the show more / show less labels through the i18n catalog', async () => {
+    const user = userEvent.setup();
+
+    render(
+      <InternationalizationProvider
+        locale="fr"
+        overrides={{
+          fr: {
+            '@astryx.metadataList.showMore': 'Afficher plus',
+            '@astryx.metadataList.showLess': 'Afficher moins',
+          },
+        }}>
+        <MetadataList maxNumOfItems={1}>
+          <MetadataListItem label="A">1</MetadataListItem>
+          <MetadataListItem label="B">2</MetadataListItem>
+        </MetadataList>
+      </InternationalizationProvider>,
+    );
+
+    await user.click(screen.getByText('Afficher plus'));
+    expect(screen.getByText('Afficher moins')).toBeInTheDocument();
+  });
+
   it('does not show toggle in horizontal mode even with maxNumOfItems', () => {
     render(
       <MetadataList orientation="horizontal" maxNumOfItems={1}>

package/src/MetadataList/MetadataList.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file MetadataList.tsx
- * @input Uses React, ReactNode, StyleXStyles, theme tokens, MetadataListContext
+ * @input Uses React, ReactNode, StyleXStyles, theme tokens, MetadataListContext, i18n (useTranslator)
  * @output Exports MetadataList component, MetadataListProps, MetadataListColumns types
  * @position Core implementation; consumed by index.ts, tested by MetadataList.test.tsx
  *
@@ -31,6 +31,7 @@ import {
 import type {BaseProps} from '../BaseProps';
 import {mergeProps} from '../utils';
 import {themeProps} from '../utils/themeProps';
+import {useTranslator} from '../i18n';
 
 // =============================================================================
 // Types
@@ -197,6 +198,7 @@ export function MetadataList({
   const labelConfig = label ?? (isMultiColumn ? LABEL_TOP : LABEL_START);
   const [isShowAll, setIsShowAll] = useState(false);
   const contentId = useId();
+  const t = useTranslator();
 
   const contextValue = useMemo(
     () => ({
@@ -283,7 +285,9 @@ export function MetadataList({
             aria-expanded={isShowAll}
             onClick={() => setIsShowAll(prev => !prev)}
             {...stylex.props(styles.toggleButton)}>
-            {isShowAll ? 'Show less' : 'Show more'}
+            {isShowAll
+              ? t('@astryx.metadataList.showLess')
+              : t('@astryx.metadataList.showMore')}
           </button>
         )}
       </div>

package/src/MultiSelector/MultiSelector.doc.mjs

@@ -21,6 +21,11 @@ export const docs = {
   theming: {
     targets: [
       {className: 'astryx-multi-selector', visualProps: ['size', 'status']},
+      {className: 'astryx-multi-selector-clear-icon'},
+      {
+        className: 'astryx-multi-selector-indicator-icon',
+        states: ['state'],
+      },
     ],
   },
   components: [
@@ -155,12 +160,25 @@ export const docs = {
           type: "{type: 'error' | 'warning' | 'success', message?: string}",
           description: 'Validation status with an optional message.',
         },
+        {
+          name: 'statusVariant',
+          type: "'attached' | 'detached'",
+          description:
+            'How the status message is placed relative to the input. attached overlaps directly below the input (bordered treatment); detached floats below as a separate element with spacing.',
+          default: "'attached'",
+        },
         {
           name: 'renderOption',
           type: '(option: MultiSelectorOptionData) => ReactNode',
           description:
             'Custom render function for each selectable option in the dropdown. Not called for dividers, sections, or the select-all row.',
         },
+        {
+          name: 'width',
+          type: 'SizeValue',
+          description:
+            'Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.',
+        },
         {
           name: 'xstyle',
           type: 'StyleXStyles',
@@ -250,6 +268,7 @@ export const docsZh = {
         isRequired: '将字段标记为必填。',
         isLoading: '在触发器中显示加载旋转器。',
         status: '带可选消息的验证状态。',
+        statusVariant: '状态消息的放置方式：attached 直接叠加在输入框下方；detached 作为独立元素浮于下方并留有间距。',
         renderOption:
           '每个可选选项的自定义渲染函数。不会用于分隔线、分组或全选行。',
         xstyle: '布局自定义的 StyleX 样式，必须是 stylex.create() 值。',
@@ -375,6 +394,7 @@ export const docsDense = {
         isRequired: 'marks required',
         isLoading: 'spinner in trigger',
         status: 'validation status w/ optional message',
+        statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
         renderOption:
           'custom render fn per selectable option; not dividers/sections/select-all',
         xstyle: 'StyleX layout styles; stylex.create() only',