@astryxdesign/core 0.1.8 → 0.1.9-canary.09e9ddd

package/src/CodeBlock/CodeBlock.test.tsx

@@ -210,6 +210,62 @@ describe('CodeBlock', () => {
     expect(document.getElementById(controlsId as string)).not.toBeNull();
   });
 
+  it('makes the collapsed region inert so the scroll container is unreachable', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const region = document.getElementById(
+      header.getAttribute('aria-controls') as string,
+    )!;
+    // Expanded: the region is not inert and the scroll container is reachable.
+    expect(region).not.toHaveAttribute('inert');
+
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'false');
+    // Collapsed: the wrapper is inert, so the keyboard-focusable scroll
+    // container (tabIndex=0) inside it drops out of the tab order and the
+    // accessibility tree instead of remaining an invisible tab stop.
+    expect(region).toHaveAttribute('inert');
+    const scrollContainer = screen.getByRole('group');
+    expect(scrollContainer.closest('[inert]')).toBe(region);
+  });
+
+  it('restores focusability of the scroll container after expanding again', () => {
+    render(
+      <CodeBlock
+        code={LONG_CODE}
+        language="javascript"
+        title="example"
+        isCollapsible
+      />,
+    );
+    const header = screen
+      .getAllByRole('button')
+      .find(el => el.hasAttribute('aria-expanded'))!;
+    const region = document.getElementById(
+      header.getAttribute('aria-controls') as string,
+    )!;
+    // Collapse, then expand again.
+    fireEvent.click(header);
+    expect(region).toHaveAttribute('inert');
+    fireEvent.click(header);
+    expect(header).toHaveAttribute('aria-expanded', 'true');
+    // Expanded again: inert is removed and the scroll container is a
+    // keyboard-focusable group once more.
+    expect(region).not.toHaveAttribute('inert');
+    const scrollContainer = screen.getByRole('group');
+    expect(scrollContainer.closest('[inert]')).toBeNull();
+    expect(scrollContainer).toHaveAttribute('tabindex', '0');
+  });
+
   it('applies a per-instance syntax theme via the syntaxTheme prop', () => {
     const {container} = render(
       <CodeBlock

package/src/CodeBlock/CodeBlock.tsx

@@ -296,7 +296,7 @@ const styles = stylex.create({
   copyButtonAbsolute: {
     position: 'absolute',
     top: spacingVars['--spacing-2'],
-    right: spacingVars['--spacing-2'],
+    insetInlineEnd: spacingVars['--spacing-2'],
   },
 });
 
@@ -807,7 +807,9 @@ export function CodeBlock({
         e.stopPropagation();
         void handleCopy();
       }}
-      aria-label={copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')}
+      aria-label={
+        copied ? t('@astryx.codeBlock.copied') : t('@astryx.codeBlock.copyCode')
+      }
       {...stylex.props(
         styles.copyButton,
         !showHeader && styles.copyButtonAbsolute,
@@ -923,6 +925,12 @@ export function CodeBlock({
       {canCollapse ? (
         <div
           id={regionId}
+          // While collapsed, the region is only hidden visually (0fr grid
+          // row); inert also removes it from the tab order and accessibility
+          // tree so keyboard users cannot Tab into the invisible scroll
+          // container (tabIndex=0). aria-controls pointing at an inert
+          // element remains a valid, resolvable reference.
+          inert={isCollapsed ? true : undefined}
           {...stylex.props(
             styles.collapseGrid,
             isCollapsed && styles.collapseGridCollapsed,

package/src/CommandPalette/CommandPalette.doc.mjs

@@ -145,6 +145,7 @@ export const docs = {
       {className: 'astryx-command-palette-empty'},
       {className: 'astryx-command-palette-footer'},
       {className: 'astryx-command-palette-group'},
+      {className: 'astryx-command-palette-group-heading'},
       {className: 'astryx-command-palette-input'},
       {className: 'astryx-command-palette-item'},
       {className: 'astryx-command-palette-list'},

package/src/CommandPalette/CommandPalette.tsx

@@ -268,6 +268,7 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
   label: labelFromProps,
   width = 640,
   maxHeight = 480,
+  ...rest
 }: CommandPaletteProps<T>) {
   const t = useTranslator();
   const label = labelFromProps ?? t('@astryx.commandPalette.label');
@@ -527,7 +528,8 @@ export function CommandPalette<T extends SearchableItem = SearchableItem>({
       width={width}
       maxHeight={maxHeight}
       purpose="info"
-      aria-label={label}>
+      aria-label={label}
+      {...rest}>
       <CommandPaletteContext value={contextValue}>
         <Layout
           defaultHasDividers

package/src/CommandPalette/CommandPaletteGroup.test.tsx

@@ -9,6 +9,8 @@
 import {describe, it, expect} from 'vitest';
 import {render, screen} from '@testing-library/react';
 import {CommandPaletteGroup} from './CommandPaletteGroup';
+import {defineTheme} from '../theme/defineTheme';
+import {generateThemeCSSFlat} from '../theme/generateThemeRules';
 
 describe('CommandPaletteGroup', () => {
   it('renders heading', () => {
@@ -51,4 +53,73 @@ describe('CommandPaletteGroup', () => {
       'true',
     );
   });
+
+  // ===========================================================================
+  // Heading theme target
+  // ===========================================================================
+
+  describe('heading theme target', () => {
+    it('renders the astryx-command-palette-group-heading target on the heading', () => {
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      const heading = screen.getByText('Suggestions');
+
+      // The root carries `astryx-command-palette-group`; this is the stable
+      // handle on the heading itself, so a theme can style just the heading
+      // without a fragile structural selector.
+      expect(heading).toHaveClass('astryx-command-palette-group-heading');
+    });
+
+    it('keeps the heading target distinct from the group root target', () => {
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      const root = screen.getByRole('group');
+      const heading = screen.getByText('Suggestions');
+
+      expect(root).toHaveClass('astryx-command-palette-group');
+      expect(root).not.toHaveClass('astryx-command-palette-group-heading');
+      expect(heading).not.toHaveClass('astryx-command-palette-group');
+    });
+
+    it('leaves the heading decorative (additive target only)', () => {
+      // The target adds a class and nothing else — the heading stays
+      // aria-hidden so grouping remains announced via the root's aria-label.
+      render(
+        <CommandPaletteGroup heading="Suggestions">
+          <div>Item</div>
+        </CommandPaletteGroup>,
+      );
+      expect(screen.getByText('Suggestions')).toHaveAttribute(
+        'aria-hidden',
+        'true',
+      );
+    });
+
+    it('exposes command-palette-group-heading as a themeable defineTheme target', () => {
+      // The generated CSS proves the target is reachable by a theme: jsdom
+      // cannot resolve the @layer cascade, so the DOM-class assertions above
+      // and this generation assertion together cover the seam.
+      const theme = defineTheme({
+        name: 'command-palette-group-heading-test',
+        components: {
+          'command-palette-group-heading': {
+            base: {
+              paddingBlock: 'var(--spacing-2)',
+              fontWeight: 'var(--font-weight-bold)',
+            },
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-command-palette-group-heading {');
+      expect(css).toContain('padding-block: var(--spacing-2)');
+      expect(css).toContain('font-weight: var(--font-weight-bold)');
+    });
+  });
 });

package/src/CommandPalette/CommandPaletteGroup.tsx

@@ -90,7 +90,18 @@ export function CommandPaletteGroup({
         style,
       )}
       {...props}>
-      <div aria-hidden="true" {...stylex.props(styles.heading)}>
+      <div
+        aria-hidden="true"
+        {...mergeProps(
+          // Stable theme target for the group heading text. The root carries
+          // `astryx-command-palette-group`, but the heading itself had no
+          // handle, so a theme could only reach it through a fragile structural
+          // selector. This adds an `astryx-command-palette-group-heading` class
+          // so `defineTheme` can scope overrides (e.g. heading typography) to
+          // the heading alone.
+          themeProps('command-palette-group-heading'),
+          stylex.props(styles.heading),
+        )}>
         {heading}
       </div>
       {children}

package/src/CommandPalette/CommandPaletteInput.doc.mjs

@@ -7,7 +7,8 @@ export const docs = {
   subComponentOf: 'CommandPalette',
   displayName: 'Command Palette Input',
   isHiddenFromOverview: true,
-  description: 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
+  description:
+    'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside CommandPalette.',
   props: [
     {
       name: 'placeholder',
@@ -15,16 +16,24 @@ export const docs = {
       description: 'Placeholder text for the input.',
       default: "'Search...'",
     },
+    {
+      name: 'label',
+      type: 'string',
+      description:
+        'Accessible label for the combobox input, announced by screen readers. Falls back to the placeholder text when omitted.',
+    },
     {
       name: 'hasAutoFocus',
       type: 'boolean',
-      description: 'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
+      description:
+        'Auto-focus the input when mounted. Automatically disabled when inside an inline command palette.',
       default: 'true',
     },
     {
       name: 'endContent',
       type: 'ReactNode',
-      description: 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
+      description:
+        'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',
       slotElements: [
         {
           __element: 'Icon',
@@ -44,17 +53,20 @@ export const docs = {
     {
       name: 'value',
       type: 'string',
-      description: 'Search value. When omitted inside CommandPalette, reads from context.',
+      description:
+        'Search value. When omitted inside CommandPalette, reads from context.',
     },
     {
       name: 'onValueChange',
       type: '(value: string) => void',
-      description: 'Called when search value changes. When omitted inside CommandPalette, writes to context.',
+      description:
+        'Called when search value changes. When omitted inside CommandPalette, writes to context.',
     },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for layout customization. Must be a stylex.create() value.',
+      description:
+        'StyleX styles for layout customization. Must be a stylex.create() value.',
     },
   ],
   playground: {
@@ -69,9 +81,11 @@ export const docsZh = {
   name: 'CommandPaletteInput',
   isHiddenFromOverview: true,
   displayName: 'Command Palette Input',
-  description: '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
+  description:
+    '搜索输入插槽。挂载时自动聚焦。在 CommandPalette 内使用时连接到上下文。',
   propDescriptions: {
     placeholder: '输入框的占位文本。',
+    label: '组合框输入的无障碍标签，供屏幕阅读器朗读。省略时回退到占位文本。',
     hasAutoFocus: '挂载时自动聚焦输入框。内联命令面板中自动禁用。',
     endContent: '渲染在输入框末尾的内容，位于加载指示器之后。',
     value: '搜索值。在 CommandPalette 内省略时从上下文读取。',
@@ -84,13 +98,16 @@ export const docsDense = {
   name: 'CommandPaletteInput',
   isHiddenFromOverview: true,
   displayName: 'Command Palette Input',
-  description: 'search input; auto-focus on mount; wires to context inside CommandPalette',
+  description:
+    'search input; auto-focus on mount; wires to context inside CommandPalette',
   propDescriptions: {
     placeholder: 'input placeholder text',
+    label: 'accessible label for the combobox; falls back to placeholder',
     hasAutoFocus: 'auto-focus on mount; auto-disabled in inline mode',
     endContent: 'trailing content after spinner',
     value: 'search value; reads context when omitted inside palette',
-    onValueChange: 'called on change; writes context when omitted inside palette',
+    onValueChange:
+      'called on change; writes context when omitted inside palette',
     xstyle: 'StyleX layout styles; must be stylex.create() value',
   },
 };

package/src/CommandPalette/CommandPaletteInput.test.tsx

@@ -32,6 +32,40 @@ describe('CommandPaletteInput', () => {
     expect(screen.getByRole('combobox')).toBeInTheDocument();
   });
 
+  it('has an accessible name by default', () => {
+    render(<CommandPaletteInput />);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Search…',
+    );
+  });
+
+  it('uses the label prop as the accessible name', () => {
+    render(<CommandPaletteInput label="Search commands" />);
+    const input = screen.getByRole('combobox');
+    expect(input).toHaveAttribute('aria-label', 'Search commands');
+    // The label prop does not affect the visible placeholder
+    expect(input).toHaveAttribute('placeholder', 'Search…');
+  });
+
+  it('falls back to a custom placeholder for the accessible name', () => {
+    render(<CommandPaletteInput placeholder="Type a command..." />);
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Type a command...',
+    );
+  });
+
+  it('lets a consumer-passed aria-label override the default', () => {
+    render(
+      <CommandPaletteInput label="Search commands" aria-label="Custom name" />,
+    );
+    expect(screen.getByRole('combobox')).toHaveAttribute(
+      'aria-label',
+      'Custom name',
+    );
+  });
+
   it('calls onValueChange when typing', () => {
     const handleChange = vi.fn();
     render(<CommandPaletteInput onValueChange={handleChange} />);

package/src/CommandPalette/CommandPaletteInput.tsx

@@ -109,6 +109,13 @@ export interface CommandPaletteInputProps extends Omit<
    */
   placeholder?: string;
 
+  /**
+   * Accessible label for the combobox input, announced by screen readers.
+   * Falls back to the placeholder text (`'Search…'` by default), since a
+   * placeholder alone is not a reliable accessible name.
+   */
+  label?: string;
+
   /**
    * Whether to auto-focus the input when mounted.
    * @default true
@@ -149,6 +156,7 @@ export function CommandPaletteInput({
   value: controlledValue,
   onValueChange,
   placeholder: placeholderFromProps,
+  label,
   hasAutoFocus = true,
   endContent,
   onChange,
@@ -215,6 +223,9 @@ export function CommandPaletteInput({
             ? ctx.getItemId(ctx.highlightedIndex)
             : undefined
         }
+        // A placeholder alone is not a reliable accessible name; give the
+        // combobox an explicit one (consumer aria-label via rest props wins).
+        aria-label={label ?? placeholder}
         placeholder={placeholder}
         value={value}
         data-autofocus={effectiveAutoFocus || undefined}

package/src/CommandPalette/CommandPaletteItem.tsx

@@ -43,7 +43,7 @@ const styles = stylex.create({
     backgroundColor: 'transparent',
     border: 'none',
     cursor: 'pointer',
-    textAlign: 'left' as const,
+    textAlign: 'start' as const,
     outline: 'none',
     userSelect: 'none',
   },

package/src/ContextMenu/ContextMenu.test.tsx

@@ -611,3 +611,196 @@ describe('ContextMenu selectable items', () => {
     expect(onToggle).toHaveBeenCalledWith(true);
   });
 });
+
+describe('ContextMenu keyboard access for menuitemradio/menuitemcheckbox (#3829)', () => {
+  it('arrow navigation reaches consumer-rendered menuitemradio and menuitemcheckbox items', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('activates a focused menuitemradio with Enter and a menuitemcheckbox with Space', () => {
+    const onSelect = vi.fn();
+    const onToggle = vi.fn();
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div
+              role="menuitemradio"
+              tabIndex={-1}
+              aria-checked="false"
+              onClick={onSelect}>
+              Newest
+            </div>
+            <div
+              role="menuitemcheckbox"
+              tabIndex={-1}
+              aria-checked="false"
+              onClick={onToggle}>
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const menu = screen.getByRole('menu', {hidden: true});
+
+    screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}).focus();
+    fireEvent.keyDown(menu, {key: 'Enter'});
+    expect(onSelect).toHaveBeenCalledTimes(1);
+
+    screen
+      .getByRole('menuitemcheckbox', {name: 'Archived', hidden: true})
+      .focus();
+    fireEvent.keyDown(menu, {key: ' '});
+    expect(onToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('typeahead matches a menuitemradio label', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Newest', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead matches a menuitemcheckbox label', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Archived
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'a'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Archived', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('typeahead skips an aria-disabled item and matches the next enabled label', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-checked="false">
+              Nightly
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    // Anchor the search on 'Cut' so typeahead scans forward and meets the
+    // disabled 'Newest' (also an 'n' match) before the enabled 'Nightly'.
+    // This pins the `:not([aria-disabled="true"])` in MENU_ITEM_SELECTOR: the
+    // menus never pass useTypeahead's `isDisabled` option, so that clause is
+    // the only thing keeping disabled rows out of the typeahead list. An
+    // arrow-key test cannot cover it — useListFocus re-filters disabled items
+    // independently, so arrow navigation is guarded twice over.
+    // The disabled row keeps tabIndex={-1} on purpose: it stays focusable, so
+    // the selector clause is the sole reason focus skips it.
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+    fireEvent.keyDown(screen.getByRole('menu', {hidden: true}), {key: 'n'});
+    expect(
+      screen.getByRole('menuitemcheckbox', {name: 'Nightly', hidden: true}),
+    ).toHaveFocus();
+  });
+
+  it('skips aria-disabled menuitemradio and menuitemcheckbox items during arrow navigation', () => {
+    render(
+      <ContextMenu
+        menuContent={
+          <>
+            <DropdownMenuItem label="Cut" onClick={() => {}} />
+            <div role="menuitemradio" tabIndex={-1} aria-disabled="true">
+              Newest
+            </div>
+            <div role="menuitemcheckbox" tabIndex={-1} aria-disabled="true">
+              Archived
+            </div>
+            <div role="menuitemradio" tabIndex={-1} aria-checked="false">
+              Oldest
+            </div>
+          </>
+        }>
+        <div>Right-click me</div>
+      </ContextMenu>,
+    );
+
+    fireEvent.contextMenu(screen.getByText('Right-click me'));
+    const menu = screen.getByRole('menu', {hidden: true});
+    screen.getByRole('menuitem', {name: 'Cut', hidden: true}).focus();
+
+    fireEvent.keyDown(menu, {key: 'ArrowDown'});
+    expect(
+      screen.getByRole('menuitemradio', {name: 'Oldest', hidden: true}),
+    ).toHaveFocus();
+  });
+});

package/src/DateInput/DateInput.doc.mjs

@@ -115,6 +115,13 @@ export const docs = {
       description:
         'Status indicator object for error, warning, or success states with a 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: 'labelTooltip',
       type: 'string',
@@ -135,6 +142,13 @@ export const docs = {
         'Number of months displayed simultaneously in the calendar popover.',
       default: '1',
     },
+    {
+      name: 'format',
+      type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
+      description:
+        "How the committed date value is displayed. Named values are reused from Timestamp's format vocabulary: 'date' shows 'Mar 21, 2026', 'date_long' shows 'March 21, 2026', 'date_weekday' shows 'Wed, Mar 21, 2026', 'system_date' shows '2026-03-21'. A function receives the ISO value and returns a custom string. Applies only to the committed value, never to text being typed.",
+      default: "'date_long'",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -377,6 +391,13 @@ export const docsZh = {
       type: "{type: 'warning' | 'error' | 'success', message?: string}",
       description: '错误、警告或成功状态的状态指示对象，附带消息。',
     },
+    {
+      name: 'statusVariant',
+      type: "'attached' | 'detached'",
+      description:
+        '状态消息相对于输入框的放置方式。attached 直接叠加在输入框下方（带边框处理）；detached 作为独立元素浮于下方并留有间距。',
+      default: "'attached'",
+    },
     {
       name: 'labelTooltip',
       type: 'string',
@@ -388,6 +409,13 @@ export const docsZh = {
       description: '日历弹出层中同时显示的月份数量。',
       default: '1',
     },
+    {
+      name: 'format',
+      type: "'date' | 'date_long' | 'date_weekday' | 'system_date' | ((value: ISODateString) => string)",
+      description:
+        "已选日期的显示格式。命名值复用 Timestamp 的格式词汇：'date' 显示 'Mar 21, 2026'，'date_long' 显示 'March 21, 2026'，'date_weekday' 显示 'Wed, Mar 21, 2026'，'system_date' 显示 '2026-03-21'。函数接收 ISO 值并返回自定义字符串。仅作用于已提交的值，不影响正在输入的文本。",
+      default: "'date_long'",
+    },
     {
       name: 'xstyle',
       type: 'StyleXStyles',
@@ -478,9 +506,12 @@ export const docsDense = {
     placeholder: 'placeholder text in input',
     size: 'input control size',
     status: 'error/warning/success status w/ message',
+    statusVariant: 'How status message is placed: attached overlaps below input; detached floats below w/ spacing.',
     labelTooltip: 'tooltip text via info icon at label end',
     hasClear: 'Shows clear button when date is set. Clears value on click.',
     numberOfMonths: 'months shown simultaneously in calendar popover',
+    format:
+      "committed-value display: 'date_long' (default, March 21, 2026), 'date' (Mar 21, 2026), 'date_weekday' (Wed, Mar 21, 2026), 'system_date' (2026-03-21), or (iso)=>string; reuses Timestamp vocabulary. Committed value only, not while typing.",
     xstyle: 'StyleX styles for layout; must be stylex.create() value',
   },
 };