@astryxdesign/core 0.6.0 → 0.6.1

package/src/TextInput/TextInput.test.tsx

@@ -560,6 +560,51 @@ describe('TextInput', () => {
       expect(handleEnter).toHaveBeenCalledTimes(1);
     });
 
+    it('does not call onEnter when Enter commits an IME conversion', () => {
+      // The browser fires this composing keydown for the Enter that commits an
+      // IME candidate (isComposing: true, or the legacy keyCode 229) before
+      // compositionend writes the conversion. It must NOT trigger onEnter —
+      // submit/save actions would fire before the user intends to submit.
+      // See utils/ime.ts and #6082.
+      const handleEnter = vi.fn();
+      const {container} = render(
+        <TextInput
+          label="Name"
+          value="にほんご"
+          onChange={() => {}}
+          onEnter={handleEnter}
+        />,
+      );
+      const input = container.querySelector('input')!;
+      fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
+      expect(handleEnter).not.toHaveBeenCalled();
+      fireEvent.keyDown(input, {key: 'Enter', keyCode: 229});
+      expect(handleEnter).not.toHaveBeenCalled();
+
+      // A real, non-composing Enter after composition ends still submits.
+      fireEvent.keyDown(input, {key: 'Enter'});
+      expect(handleEnter).toHaveBeenCalledTimes(1);
+    });
+
+    it('still calls onKeyDown for composing keydowns', () => {
+      // onKeyDown is the raw escape hatch: it keeps receiving IME keydowns so
+      // consumers with custom composition handling are unaffected by the
+      // onEnter guard.
+      const handleKeyDown = vi.fn();
+      const {container} = render(
+        <TextInput
+          label="Name"
+          value="にほんご"
+          onChange={() => {}}
+          onKeyDown={handleKeyDown}
+          onEnter={() => {}}
+        />,
+      );
+      const input = container.querySelector('input')!;
+      fireEvent.keyDown(input, {key: 'Enter', isComposing: true});
+      expect(handleKeyDown).toHaveBeenCalledTimes(1);
+    });
+
     it('does not call onEnter for other keys', async () => {
       const user = userEvent.setup();
       const handleEnter = vi.fn();
@@ -1019,3 +1064,52 @@ describe('TextInput readonly theme state', () => {
     expect(root).not.toHaveAttribute('data-readonly');
   });
 });
+
+describe('TextInput clear button focus behavior', () => {
+  it('synchronously restores focus to the input on keyboard activation (detail === 0)', () => {
+    const handleChange = vi.fn();
+    render(
+      <TextInput
+        label="Search"
+        value="test"
+        hasClear
+        onChange={handleChange}
+      />,
+    );
+
+    const input = screen.getByRole('textbox');
+    const clearButton = screen.getByRole('button', {name: /clear/i});
+
+    clearButton.focus();
+    expect(document.activeElement).toBe(clearButton);
+
+    // Keyboard activation (e.g. Enter / Space on focused button yields detail 0)
+    fireEvent.click(clearButton, {detail: 0});
+
+    expect(handleChange).toHaveBeenCalledWith('', expect.any(Object));
+    // Must be synchronously focused without waiting for animation frames
+    expect(document.activeElement).toBe(input);
+  });
+
+  it('defers focus restoration via requestAnimationFrame on pointer activation', () => {
+    const handleChange = vi.fn();
+    const rafSpy = vi.spyOn(window, 'requestAnimationFrame');
+    render(
+      <TextInput
+        label="Search"
+        value="test"
+        hasClear
+        onChange={handleChange}
+      />,
+    );
+
+    const clearButton = screen.getByRole('button', {name: /clear/i});
+
+    // Pointer activation (detail > 0)
+    fireEvent.click(clearButton, {detail: 1});
+
+    expect(handleChange).toHaveBeenCalledWith('', expect.any(Object));
+    expect(rafSpy).toHaveBeenCalled();
+    rafSpy.mockRestore();
+  });
+});

package/src/TextInput/TextInput.tsx

@@ -47,7 +47,7 @@ import {renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
 import {useTooltip} from '../Tooltip';
 import {VisuallyHidden} from '../VisuallyHidden';
-import {getInputARIA} from '../utils';
+import {getInputARIA, isImeKeyEvent} from '../utils';
 
 const styles = stylex.create({
   input: {
@@ -381,10 +381,21 @@ export function TextInput({
   };
 
   // Handle clear button click
-  const handleClear = useCallback(() => {
-    onChange?.('', null as unknown as ChangeEvent<HTMLInputElement>);
-    inputRef.current?.focus();
-  }, [onChange]);
+  const handleClear = useCallback(
+    (e?: React.MouseEvent<HTMLButtonElement>) => {
+      onChange?.('', null as unknown as ChangeEvent<HTMLInputElement>);
+      if (!e || e.detail === 0) {
+        inputRef.current?.focus();
+      } else {
+        // Defer focus restoration past the button's unmount task so iOS Safari
+        // and touch browsers don't jump the page scroll to 0 on tap.
+        requestAnimationFrame(() => {
+          inputRef.current?.focus({preventScroll: true});
+        });
+      }
+    },
+    [onChange],
+  );
 
   // Focus input when clicking anywhere on the wrapper (icons, padding, etc.)
   const {onClick: handleWrapperClick, onMouseUp: handleWrapperMouseUp} =
@@ -438,7 +449,12 @@ export function TextInput({
         onKeyDown={
           onEnter || onKeyDown
             ? e => {
-                if (e.key === 'Enter') {
+                // The composing keydown fires before compositionend, so without
+                // this guard pressing Enter to commit a Japanese/Chinese/Korean
+                // IME conversion would trigger onEnter (submit/save actions)
+                // before the user intends to submit. onKeyDown still receives
+                // the raw event. See utils/ime.ts (#6082).
+                if (e.key === 'Enter' && !isImeKeyEvent(e.nativeEvent)) {
                   onEnter?.();
                 }
                 onKeyDown?.(e);

package/src/TimeInput/TimeInput.tsx

@@ -622,13 +622,24 @@ export function TimeInput({
   );
 
   // Handle clear button click
-  const handleClear = useCallback(() => {
-    fireChange(undefined);
-    // Focusing a native time control reopens the OS picker on iOS.
-    if (!usesNativeTimePicker) {
-      inputRef.current?.focus();
-    }
-  }, [fireChange, usesNativeTimePicker]);
+  const handleClear = useCallback(
+    (e?: React.MouseEvent<HTMLButtonElement>) => {
+      fireChange(undefined);
+      // Focusing a native time control reopens the OS picker on iOS.
+      if (!usesNativeTimePicker) {
+        if (!e || e.detail === 0) {
+          inputRef.current?.focus();
+        } else {
+          // Defer focus restoration past the button's unmount task so iOS Safari
+          // and touch browsers don't jump the page scroll to 0 on tap.
+          requestAnimationFrame(() => {
+            inputRef.current?.focus({preventScroll: true});
+          });
+        }
+      }
+    },
+    [fireChange, usesNativeTimePicker],
+  );
 
   // Focus input when clicking anywhere on the wrapper (icons, padding, etc.)
   const {onClick: handleWrapperClick, onMouseUp: handleWrapperMouseUp} =

package/src/Toast/ToastViewport.test.tsx

@@ -34,7 +34,7 @@ import React from 'react';
 import {readFileSync} from 'node:fs';
 import {type AnnounceFn, __resetLiveRegionsForTest} from '../hooks/useAnnounce';
 import {Button} from '../Button';
-import {Toast, type ToastProps} from './Toast';
+import type {ToastProps} from './Toast';
 import {ToastViewport} from './ToastViewport';
 import {useToast} from './useToast';
 import type {ToastOptions} from './types';
@@ -1720,44 +1720,6 @@ describe('Toast swipe dismissal', () => {
   });
 });
 
-describe('Toast live-region fallback semantics', () => {
-  it('keeps standalone info Toast content in a polite status region', () => {
-    render(
-      <Toast
-        type="info"
-        body="Saved"
-        isAutoHide={false}
-        autoHideDuration={5000}
-        onDismiss={() => {}}
-      />,
-    );
-
-    const visualToast = screen.getByText('Saved').closest('[data-type]');
-    expect(visualToast).toHaveAttribute('role', 'status');
-    expect(visualToast).toHaveAttribute('aria-live', 'polite');
-    expect(visualToast).toHaveAttribute('aria-atomic', 'true');
-  });
-
-  it('keeps standalone error Toast content in an assertive alert region', () => {
-    render(
-      <Toast
-        type="error"
-        body="Upload failed"
-        isAutoHide={false}
-        autoHideDuration={5000}
-        onDismiss={() => {}}
-      />,
-    );
-
-    const visualToast = screen
-      .getByText('Upload failed')
-      .closest('[data-type]');
-    expect(visualToast).toHaveAttribute('role', 'alert');
-    expect(visualToast).toHaveAttribute('aria-live', 'assertive');
-    expect(visualToast).toHaveAttribute('aria-atomic', 'true');
-  });
-});
-
 describe('ToastViewport region ARIA', () => {
   it('does not expose an empty notifications landmark', () => {
     renderViewport(<ShowToastButton />);

package/src/Typeahead/BaseTypeahead.doc.mjs

@@ -1,5 +1,62 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Input',
+    required: true,
+    description:
+      'Bare combobox input. The caller supplies its visible field chrome and accessible name.',
+  },
+  {
+    name: 'Loading status',
+    required: false,
+    description:
+      'Named Spinner shown beside the input while an asynchronous source is pending, unless a composed owner takes over the busy indicator lane.',
+  },
+  {
+    name: 'Dropdown',
+    required: false,
+    description:
+      'Anchored listbox surface containing current search or bootstrap results.',
+  },
+  {
+    name: 'Empty state',
+    required: false,
+    description:
+      'Disabled listbox option shown after a completed search returns no results.',
+  },
+  {
+    name: 'Result group heading',
+    required: false,
+    description: 'Visible label for a group of result options.',
+  },
+  {
+    name: 'Result row',
+    required: false,
+    description:
+      'Option wrapper that owns highlight, selection, pointer, and keyboard behavior.',
+  },
+  {
+    name: 'Default item content',
+    required: false,
+    description:
+      'TypeaheadItem label and optional supporting content rendered inside a result row.',
+  },
+  {
+    name: 'Caller-rendered item content',
+    required: false,
+    description:
+      'Caller content supplied through renderItem or item.element inside the stable result row.',
+  },
+  {
+    name: 'Selected result state',
+    required: false,
+    description:
+      'Selected row weight and trailing check shown when a result matches value.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -7,15 +64,43 @@ export const docs = {
   subComponentOf: 'Typeahead',
   displayName: 'Base Typeahead',
   isHiddenFromOverview: true,
-  description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+  description:
+    'Composable combobox engine providing a bare input, search, keyboard navigation, and a styled result dropdown. It renders no input wrapper, border, or selected-value token. Typeahead and Tokenizer compose it for standard fields.',
   usage: {
-    description: 'Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.',
+    anatomy,
+    description:
+      'Composable combobox engine providing a bare input, search, keyboard navigation, and a styled result dropdown. It renders no input wrapper, border, or selected-value token. Typeahead and Tokenizer compose it for standard fields.',
     bestPractices: [
-      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they wrap BaseTypeahead with the wrapper div, border styling, and token rendering it intentionally omits.' },
-      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly, since BaseTypeahead renders no visual chrome of its own.' },
-      { guidance: true, description: 'Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.' },
-      { guidance: false, description: 'Expect a wrapper div, border, or token rendering. BaseTypeahead is an engine only; all visual chrome is the caller\'s responsibility.' },
-      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer would suffice; the extra wrapper and styling work is only justified for truly custom compositions.' },
+      {
+        guidance: true,
+        description:
+          'Use Typeahead or Tokenizer for standard fields; they wrap BaseTypeahead with input chrome and selected-value rendering it intentionally omits.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide your own visible label or aria-label and custom input wrapper so the bare combobox has an accessible name, focus treatment, border, and layout.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass anchorRef pointing to your wrapper so the dropdown positions against your custom input chrome, not just the bare input element.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect input chrome or selected-value rendering. BaseTypeahead is an engine; the caller owns those visible parts.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use BaseTypeahead when Typeahead or Tokenizer would suffice; the extra wrapper and styling work is only justified for truly custom compositions.',
+      },
+      {
+        guidance: false,
+        description:
+          'Treat Escape as cancellation of pending source work. It hides the current popup, but a late response can reopen it.',
+      },
     ],
   },
   props: [
@@ -46,7 +131,7 @@ export const docs = {
       name: 'placeholder',
       type: 'string',
       description: 'Input placeholder text.',
-      default: "'Search...'",
+      default: "'Search…'",
     },
     {
       name: 'hasEntriesOnFocus',
@@ -63,12 +148,14 @@ export const docs = {
     {
       name: 'menuWidth',
       type: 'number',
-      description: 'Fixed dropdown width in pixels. The menu never shrinks below its anchor width.',
+      description:
+        'Requested dropdown width in pixels before viewport clamping.',
     },
     {
       name: 'minQueryLength',
       type: 'number',
-      description: 'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
+      description:
+        'Minimum query length before the search source is queried. Below it no search runs and the menu stays closed.',
       default: '1',
     },
     {
@@ -83,6 +170,13 @@ export const docs = {
       description: 'Whether the input is disabled.',
       default: 'false',
     },
+    {
+      name: 'isFocusableDisabled',
+      type: 'boolean',
+      description:
+        'Keep a disabled input focusable with aria-disabled and readOnly so a caller-owned disabled reason remains discoverable. It blocks text entry, but when applied after results are already open, Enter can still select the highlighted option.',
+      default: 'false',
+    },
     {
       name: 'hasAutoFocus',
       type: 'boolean',
@@ -92,23 +186,44 @@ export const docs = {
     {
       name: 'debounceMs',
       type: 'number',
-      description: 'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+      description:
+        'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
       default: '150',
     },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: 'Size used to scale dropdown option padding.',
+      default: "'md'",
+    },
     {
       name: 'anchorRef',
       type: 'RefObject<HTMLElement | null>',
-      description: 'Ref to the anchor element for dropdown positioning. If not provided, the input itself is used.',
+      description:
+        'Ref to the anchor element for dropdown positioning. If not provided, the input itself is used.',
     },
     {
       name: 'inputXStyle',
       type: 'StyleXStyles',
       description: 'Additional StyleX styles for the input element.',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description:
+        'Standard BaseProps StyleX styles applied to the input. Must be a stylex.create() value, not an inline style object.',
+    },
+    {
+      name: 'inputTabIndex',
+      type: 'number',
+      description:
+        'Legacy input-specific alias for native tabIndex. When provided, it takes precedence; otherwise native tabIndex is preserved.',
+    },
     {
       name: 'onKeyDown',
       type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',
-      description: 'Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.',
+      description:
+        'Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling.',
     },
     {
       name: 'onChangeQuery',
@@ -123,12 +238,20 @@ export const docs = {
     {
       name: 'inputId',
       type: 'string',
-      description: 'ID for the input element (for label association).',
+      description:
+        'Legacy input-specific alias for native id. When provided, it takes precedence; otherwise native id is preserved.',
     },
     {
       name: 'ariaDescribedBy',
       type: 'string',
-      description: 'Additional aria-describedby IDs.',
+      description:
+        'Legacy input-specific alias for native aria-describedby. When provided, it takes precedence; otherwise the native attribute is preserved.',
+    },
+    {
+      name: 'ariaLabelledBy',
+      type: 'string',
+      description:
+        'Legacy input-specific alias for native aria-labelledby. When provided, it takes precedence; otherwise the native attribute is preserved.',
     },
   ],
 };
@@ -137,7 +260,8 @@ export const docsZh = {
   name: 'BaseTypeahead',
   isHiddenFromOverview: true,
   displayName: 'Base Typeahead',
-  description: '无样式的组合框引擎，提供输入、搜索、键盘导航和下拉列表。无包装 div，无边框样式，无标记渲染。由 Typeahead 和 Tokenizer 用于自定义组合。',
+  description:
+    '可组合的组合框引擎，提供裸输入框、搜索、键盘导航和带样式的结果下拉列表。它不渲染输入框包装、边框或已选值标记；Typeahead 和 Tokenizer 将其组合成标准字段。',
   props: [
     {
       name: 'searchSource',
@@ -166,7 +290,7 @@ export const docsZh = {
       name: 'placeholder',
       type: 'string',
       description: '输入框占位文本。',
-      default: "'Search...'",
+      default: "'Search…'",
     },
     {
       name: 'hasEntriesOnFocus',
@@ -183,12 +307,13 @@ export const docsZh = {
     {
       name: 'menuWidth',
       type: 'number',
-      description: '下拉菜单的固定像素宽度。菜单不会小于其锚点宽度。',
+      description: '视口限制前请求的下拉菜单像素宽度。',
     },
     {
       name: 'minQueryLength',
       type: 'number',
-      description: '查询搜索源前的最小查询长度。低于该长度不会发起搜索，菜单保持关闭。',
+      description:
+        '查询搜索源前的最小查询长度。低于该长度不会发起搜索，菜单保持关闭。',
       default: '1',
     },
     {
@@ -203,6 +328,13 @@ export const docsZh = {
       description: '输入框是否被禁用。',
       default: 'false',
     },
+    {
+      name: 'isFocusableDisabled',
+      type: 'boolean',
+      description:
+        '使用 aria-disabled 和只读状态保持禁用输入框可聚焦，以便访问调用方提供的禁用原因。它会阻止文本输入，但如果结果已打开，按 Enter 仍可选择高亮选项。',
+      default: 'false',
+    },
     {
       name: 'hasAutoFocus',
       type: 'boolean',
@@ -215,6 +347,12 @@ export const docsZh = {
       description: '触发搜索前的防抖延迟（毫秒）。同步数据源设置为 0。',
       default: '150',
     },
+    {
+      name: 'size',
+      type: "'sm' | 'md' | 'lg'",
+      description: '用于调整下拉选项内边距的尺寸。',
+      default: "'md'",
+    },
     {
       name: 'anchorRef',
       type: 'RefObject<HTMLElement | null>',
@@ -225,10 +363,22 @@ export const docsZh = {
       type: 'StyleXStyles',
       description: '输入元素的附加 StyleX 样式。',
     },
+    {
+      name: 'xstyle',
+      type: 'StyleXStyles',
+      description: '应用于输入元素的标准 BaseProps StyleX 样式。',
+    },
+    {
+      name: 'inputTabIndex',
+      type: 'number',
+      description:
+        '原生 tabIndex 的旧输入专用别名。提供时优先；未提供时保留原生属性。',
+    },
     {
       name: 'onKeyDown',
       type: '(e: React.KeyboardEvent<HTMLInputElement>) => void',
-      description: '在内部键盘导航之前调用的附加 keydown 处理函数。调用 e.preventDefault() 可跳过内部处理。',
+      description:
+        '在内部键盘导航之前调用的附加 keydown 处理函数。调用 e.preventDefault() 可跳过内部处理。',
     },
     {
       name: 'onChangeQuery',
@@ -243,12 +393,20 @@ export const docsZh = {
     {
       name: 'inputId',
       type: 'string',
-      description: '输入元素的 ID（用于标签关联）。',
+      description:
+        '原生 id 的旧输入专用别名。提供时优先；未提供时保留原生属性。',
     },
     {
       name: 'ariaDescribedBy',
       type: 'string',
-      description: '附加的 aria-describedby ID。',
+      description:
+        '原生 aria-describedby 的旧输入专用别名。提供时优先；未提供时保留原生属性。',
+    },
+    {
+      name: 'ariaLabelledBy',
+      type: 'string',
+      description:
+        '原生 aria-labelledby 的旧输入专用别名。提供时优先；未提供时保留原生属性。',
     },
   ],
 };
@@ -257,14 +415,40 @@ export const docsDense = {
   name: 'BaseTypeahead',
   isHiddenFromOverview: true,
   displayName: 'Base Typeahead',
-  description: 'Unstyled combobox engine; input+search+keyboard nav+dropdown. No wrapper/border/token. Used by Typeahead+Tokenizer.',
+  description:
+    'Composable combobox engine providing a bare input and a styled result dropdown. Callers own input chrome and selected-value presentation.',
   usage: {
     bestPractices: [
-      { guidance: true, description: 'Use Typeahead or Tokenizer for standard fields; they add the wrapper, border, and token rendering BaseTypeahead omits.' },
-      { guidance: true, description: 'Provide your own wrapper div with border and layout when composing directly; BaseTypeahead renders no chrome.' },
-      { guidance: true, description: 'Pass anchorRef to your wrapper so the dropdown positions against your input chrome, not the bare input.' },
-      { guidance: false, description: 'Expect wrapper, border, or token rendering. Engine only; chrome is the caller\'s job.' },
-      { guidance: false, description: 'Use BaseTypeahead when Typeahead or Tokenizer suffice; extra work only pays off for custom compositions.' },
+      {
+        guidance: true,
+        description:
+          'Use Typeahead or Tokenizer for standard fields; they add the input chrome and selected-value rendering BaseTypeahead omits.',
+      },
+      {
+        guidance: true,
+        description:
+          'Provide a visible label or aria-label plus a custom wrapper with focus treatment, border, and layout.',
+      },
+      {
+        guidance: true,
+        description:
+          'Pass anchorRef to your wrapper so the dropdown positions against your input chrome, not the bare input.',
+      },
+      {
+        guidance: false,
+        description:
+          'Expect input chrome or selected-value rendering. The caller owns those visible parts.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use BaseTypeahead when Typeahead or Tokenizer suffice; extra work only pays off for custom compositions.',
+      },
+      {
+        guidance: false,
+        description:
+          'Treat Escape as pending-work cancellation. It hides the popup, but a late response can reopen it.',
+      },
     ],
   },
   propDescriptions: {
@@ -275,18 +459,30 @@ export const docsDense = {
     placeholder: 'Input placeholder.',
     hasEntriesOnFocus: 'Bootstrap results on focus.',
     maxMenuItems: 'Max dropdown items.',
-    menuWidth: 'Fixed dropdown width in pixels.',
-    minQueryLength: 'Min query length before searching. Menu stays closed below it.',
+    menuWidth: 'Requested px width before viewport clamping.',
+    minQueryLength:
+      'Min query length before searching. Menu stays closed below it.',
     emptySearchResultsText: 'Text when no results.',
     isDisabled: 'Whether input disabled.',
+    isFocusableDisabled:
+      'Keeps disabled input focusable and blocks text entry; an already-open highlight can still be selected with Enter.',
     hasAutoFocus: 'Auto-focus on mount.',
     debounceMs: 'Search debounce ms. 0 for sync.',
+    size: 'Dropdown option padding size.',
     anchorRef: 'Anchor for dropdown positioning. Defaults to input.',
     inputXStyle: 'Additional StyleX styles for input.',
-    onKeyDown: 'Keydown before internal nav. preventDefault() skips internal handling.',
+    xstyle: 'Standard BaseProps StyleX styles for input.',
+    inputTabIndex:
+      'Legacy tabIndex alias; defined alias wins, otherwise native tabIndex passes through.',
+    onKeyDown:
+      'Keydown before internal nav. preventDefault() skips internal handling.',
     onChangeQuery: 'Fired on query text change.',
     onOpenChange: 'Fired on dropdown open/close.',
-    inputId: 'Input ID for label association.',
-    ariaDescribedBy: 'Additional aria-describedby IDs.',
+    inputId:
+      'Legacy id alias; defined alias wins, otherwise native id passes through.',
+    ariaDescribedBy:
+      'Legacy aria-describedby alias; defined alias wins, otherwise native attribute passes through.',
+    ariaLabelledBy:
+      'Legacy aria-labelledby alias; defined alias wins, otherwise native attribute passes through.',
   },
 };