@astryxdesign/core 0.1.9-canary.d2d84f8 → 0.1.9-canary.e00a241

package/src/TopNav/TopNavItem.tsx

@@ -131,6 +131,8 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
   isSelected?: boolean;
   /**
    * Whether the nav item is disabled.
+   * A disabled item renders as a plain anchor without an href (and without
+   * target), so it cannot navigate and is removed from the tab order.
    * @default false
    */
   isDisabled?: boolean;
@@ -157,6 +159,15 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
   size?: NavItemSize;
 }
 
+/**
+ * Click handler for disabled items. The disabled anchor renders without an
+ * href, so there is no navigation to block in practice; preventDefault is a
+ * defensive guard against synthetic/programmatic clicks.
+ */
+function preventDefaultClick(event: React.MouseEvent<HTMLAnchorElement>): void {
+  event.preventDefault();
+}
+
 /**
  * A navigation item for use within TopNav startContent.
  *
@@ -178,6 +189,9 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
  */
 export function TopNavItem({
   as,
+  href,
+  target,
+  onClick,
   label,
   isSelected = false,
   isDisabled = false,
@@ -195,22 +209,34 @@ export function TopNavItem({
   const renderMode = useTopNavRenderMode();
   const {closeMobileNav} = useAppShellMobile();
 
+  // A disabled item renders as a plain <a> with no href: an href-less anchor
+  // is not focusable and exposes no link affordance, so programmatic focus +
+  // Enter, AT activation commands, and middle-click cannot navigate or fire
+  // the consumer onClick. The router LinkComponent is deliberately skipped —
+  // a disabled item performs no navigation, and custom router links may
+  // require a live href. target is omitted with the href. (Mirrors the
+  // disabled paths of Link and SideNavItem.)
+  const Root = isDisabled ? 'a' : LinkComponent;
+
   // =========================================================================
   // Drawer mode — render as a SideNavItem-style vertical list element
   // =========================================================================
   if (renderMode === 'drawer') {
-    const handleDrawerClick = (e: React.MouseEvent) => {
+    const handleDrawerClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
       if (isDisabled) {
+        preventDefaultClick(e);
         return;
       }
       // Forward the original onClick if present
-      (props as {onClick?: (e: React.MouseEvent) => void}).onClick?.(e);
+      onClick?.(e);
       closeMobileNav();
     };
 
     return (
-      <LinkComponent
+      <Root
         ref={ref}
+        href={isDisabled ? undefined : href}
+        target={isDisabled ? undefined : target}
         aria-label={isIconOnly ? label : undefined}
         aria-current={isSelected ? 'page' : undefined}
         aria-disabled={isDisabled || undefined}
@@ -235,7 +261,7 @@ export function TopNavItem({
         onClick={handleDrawerClick}>
         {icon}
         {!isIconOnly && (children ?? label)}
-      </LinkComponent>
+      </Root>
     );
   }
 
@@ -244,8 +270,11 @@ export function TopNavItem({
   // =========================================================================
 
   return (
-    <LinkComponent
+    <Root
       ref={ref}
+      href={isDisabled ? undefined : href}
+      target={isDisabled ? undefined : target}
+      onClick={isDisabled ? preventDefaultClick : onClick}
       aria-label={isIconOnly ? label : undefined}
       aria-current={isSelected ? 'page' : undefined}
       aria-disabled={isDisabled || undefined}
@@ -267,7 +296,7 @@ export function TopNavItem({
       {...props}>
       {icon}
       {!isIconOnly && (children ?? label)}
-    </LinkComponent>
+    </Root>
   );
 }
 

package/src/TopNav/TopNavMegaMenuFeaturedCard.doc.mjs

@@ -27,7 +27,7 @@ export const docs = {
     {
       name: 'imageAlt',
       type: 'string',
-      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden) — usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
+      description: 'Alt text for the image. When omitted, the image is explicitly decorative (alt="", role="presentation", aria-hidden), usually correct since the card already has a visible title. Provide it only when the image conveys information beyond the title and description.',
     },
     {
       name: 'linkLabel',

package/src/TreeList/TreeList.doc.mjs

@@ -30,6 +30,9 @@ export const docs = {
       {className: 'astryx-tree-list-item-label', states: ['selected']},
       {className: 'astryx-tree-list-guide'},
     ],
+    vars: [
+      {name: '--tree-list-indent', description: 'Per-level indentation step. Each nesting level indents its rows by this distance, and the guide lines follow it so they stay aligned. Set it on the `tree-list` target to retune the metric (e.g. `var(--spacing-5)` for a wider indent).', default: 'var(--spacing-4)'},
+    ],
   },
   components: [
     {
@@ -104,6 +107,9 @@ export const docsZh = {
       {className: 'astryx-tree-list-item-label', states: ['selected']},
       {className: 'astryx-tree-list-guide'},
     ],
+    vars: [
+      {name: '--tree-list-indent', description: '每级缩进步长。每个嵌套层级的行按此距离缩进，引导线随之对齐。在 `tree-list` 目标上设置以调整该度量（例如用 `var(--spacing-5)` 获得更宽的缩进）。', default: 'var(--spacing-4)'},
+    ],
   },
   components: [
     {

package/src/TreeList/TreeList.test.tsx

@@ -432,25 +432,28 @@ describe('TreeList', () => {
 
     it("variant='noGuides' preserves per-level indentation on the rows", () => {
       // Indentation lives on the row's margin-inline-start (not the guide
-      // element), so it must survive when the connectors are suppressed. A
-      // deeper row is indented more than a shallower one.
+      // element), so it must survive when the connectors are suppressed. The
+      // per-row distance is published as the `--_tree-indent` custom property
+      // (not an inline longhand — see #4308), so the theme layer can override
+      // the `margin-inline-start` declaration. A deeper row is indented more
+      // than a shallower one.
       const {container} = render(
         <TreeList items={deepItems} variant="noGuides" />,
       );
-      const marginOf = (text: string): string => {
+      const indentOf = (text: string): string => {
         const li = screen.getByText(text).closest('li')!;
-        const styled = li.querySelector('[style*="margin-inline-start"]');
+        const styled = li.querySelector('[style*="--_tree-indent"]');
         return styled?.getAttribute('style') ?? '';
       };
       // Guides are gone…
       expect(container.querySelector('.astryx-tree-list-guide')).toBeNull();
-      // …but each level still carries an inline margin-inline-start, and the
-      // level multiplier grows with depth (0, 1, 2).
-      expect(marginOf('Root')).toContain('margin-inline-start');
-      expect(marginOf('Mid')).toContain('margin-inline-start');
-      expect(marginOf('Leaf')).toContain('margin-inline-start');
+      // …but each level still publishes an indent distance, and the level
+      // multiplier grows with depth (0, 1, 2).
+      expect(indentOf('Root')).toContain('--_tree-indent');
+      expect(indentOf('Mid')).toContain('--_tree-indent');
+      expect(indentOf('Leaf')).toContain('--_tree-indent');
       const level = (text: string): number => {
-        const m = /calc\((\d+)/.exec(marginOf(text));
+        const m = /calc\((\d+)/.exec(indentOf(text));
         return m ? Number(m[1]) : NaN;
       };
       expect(level('Mid')).toBeGreaterThan(level('Root'));
@@ -504,6 +507,43 @@ describe('TreeList', () => {
     });
   });
 
+  // ===========================================================================
+  // Indent lever (--tree-list-indent)
+  // ===========================================================================
+
+  describe('indent lever', () => {
+    it('lets a theme retune the indent step via the tree-list target', () => {
+      // The per-level step is a public, themeable var (default --spacing-4) set
+      // on the tree-list root, so a theme can retune the indent metric (e.g. to
+      // --spacing-5) via defineTheme. jsdom cannot resolve the @layer cascade,
+      // so the generated CSS is what proves the override reaches the lever.
+      const theme = defineTheme({
+        name: 'tree-list-indent-test',
+        components: {
+          'tree-list': {
+            base: {'--tree-list-indent': 'var(--spacing-5)'},
+          },
+        },
+      });
+      const css = generateThemeCSSFlat(theme);
+      expect(css).toContain('.astryx-tree-list {');
+      expect(css).toContain('--tree-list-indent: var(--spacing-5)');
+    });
+
+    it('rows consume the indent step in their published indent distance', () => {
+      // Each row's --_tree-indent is calc(level * var(--tree-list-indent)),
+      // so retuning the step scales every level uniformly.
+      render(<TreeList items={deepItems} variant="noGuides" />);
+      const indentOf = (text: string): string => {
+        const li = screen.getByText(text).closest('li')!;
+        const styled = li.querySelector('[style*="--_tree-indent"]');
+        return styled?.getAttribute('style') ?? '';
+      };
+      expect(indentOf('Mid')).toContain('var(--tree-list-indent)');
+      expect(indentOf('Leaf')).toContain('var(--tree-list-indent)');
+    });
+  });
+
   // ===========================================================================
   // xds class name
   // ===========================================================================

package/src/TreeList/TreeList.tsx

@@ -83,6 +83,11 @@ export interface TreeListProps extends BaseProps<HTMLDivElement> {
 const styles = stylex.create({
   root: {
     position: 'relative',
+    // Per-level indentation step. Public, themeable lever: a theme can retune
+    // the tree's indent metric (e.g. to `var(--spacing-5)`) via `defineTheme`
+    // on the `tree-list` target, and both the row margins (TreeListItem) and
+    // the guide-line offsets (TreeListBranches) read it so they stay aligned.
+    '--tree-list-indent': spacingVars['--spacing-4'],
   },
   list: {
     margin: 0,

package/src/TreeList/TreeListBranches.tsx

@@ -26,8 +26,10 @@ const LINE_WIDTH = 1;
  */
 const BRANCH_MARGIN = `calc(${spacingVars['--spacing-2']} + ${spacingVars['--spacing-0-5']})`;
 
-/** Per-level indent width, matching --spacing-4 (16px). */
-const LEVEL_INDENT = spacingVars['--spacing-4'];
+/** Per-level indent width. Reads the public, themeable `--tree-list-indent`
+ * lever set on the tree-list root (default `--spacing-4`, 16px), so the guide
+ * lines stay aligned with the row indent when a theme retunes the step. */
+const LEVEL_INDENT = 'var(--tree-list-indent)';
 
 const styles = stylex.create({
   container: {
@@ -37,10 +39,10 @@ const styles = stylex.create({
   },
   verticalLine: {
     borderRadius: 1,
-    left: 0,
+    insetInlineStart: 0,
     margin: 'auto',
     position: 'absolute',
-    right: 0,
+    insetInlineEnd: 0,
     width: LINE_WIDTH,
     backgroundColor: colorVars['--color-border-emphasized'],
   },
@@ -92,7 +94,7 @@ export function TreeListBranches({
               key={level}
               {...mergeProps(stylex.props(styles.container), {
                 style: {
-                  left: branchOffset,
+                  insetInlineStart: branchOffset,
                 },
               })}>
               <div
@@ -109,7 +111,7 @@ export function TreeListBranches({
         <div
           {...mergeProps(stylex.props(styles.container), {
             style: {
-              left: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
+              insetInlineStart: `calc(${BRANCH_MARGIN} + ${nestedLevel - 1} * ${LEVEL_INDENT})`,
             },
           })}>
           <div

package/src/TreeList/TreeListItem.tsx

@@ -25,7 +25,7 @@ import {
   typeScaleVars,
 } from '../theme/tokens.stylex';
 import {getIcon} from '../Icon/globalIconRegistry';
-import {mergeProps} from '../utils';
+import {mergeProps, rtlStyles} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity, TreeListVariant} from './TreeListTypes';
@@ -82,6 +82,12 @@ const styles = stylex.create({
     position: 'relative',
     boxSizing: 'border-box',
     textAlign: 'start',
+    // Per-level indent. Declared here (not inline) so it lives in
+    // `@layer astryx-base` and the theme layer can override it in normal
+    // cascade order — an inline longhand would outrank every layer. The row
+    // publishes only the computed distance as `--_tree-indent`; the per-level
+    // step is the public `--tree-list-indent` lever (see TreeList `root`).
+    marginInlineStart: 'var(--_tree-indent, 0px)',
   },
   interactive: {
     cursor: 'pointer',
@@ -246,6 +252,11 @@ const descriptionSizeStyles = stylex.create({
   },
 });
 
+// `CSSProperties` has no index signature for custom properties, so the row's
+// inline style — which publishes the computed indent distance as the private
+// `--_tree-indent` — needs this augmentation to typecheck.
+type IndentStyle = React.CSSProperties & Record<'--_tree-indent', string>;
+
 // =============================================================================
 // Types
 // =============================================================================
@@ -353,9 +364,18 @@ export function TreeListItem({
     return undefined;
   }, [onClick, hasChildren, onToggle, id, isDisabled]);
 
-  const computedMarginLeft = hasChildren
-    ? `calc(${nestedLevel} * ${spacingVars['--spacing-4']})`
-    : `calc(${nestedLevel} * ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+  // Per-level indent distance. The per-level step is the public, themeable
+  // `--tree-list-indent` lever (default `--spacing-4`, set on the tree-list
+  // root). Leaves add a fixed chevron-column offset (chevron width + gap) so
+  // their labels line up with sibling parents' labels; that offset is tied to
+  // the chevron's own dimensions, not the indent step, so it does not scale
+  // with the lever. Published as the private `--_tree-indent` and consumed by
+  // `contentWrapper`'s stylesheet `margin-inline-start` (kept out of the inline
+  // style so the theme layer can override it — see #4308).
+  const indentDistance = hasChildren
+    ? `calc(${nestedLevel} * var(--tree-list-indent))`
+    : `calc(${nestedLevel} * var(--tree-list-indent) + ${spacingVars['--spacing-4']} + ${spacingVars['--spacing-2']})`;
+  const indentStyle: IndentStyle = {'--_tree-indent': indentDistance};
 
   const labelAndDescription = (
     <>
@@ -386,12 +406,14 @@ export function TreeListItem({
   );
 
   const chevronIcon = (
-    <span
-      {...stylex.props(
-        styles.chevronSvg,
-        isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
-      )}>
-      {getIcon('chevronRight')}
+    <span {...stylex.props(rtlStyles.mirror)}>
+      <span
+        {...stylex.props(
+          styles.chevronSvg,
+          isExpanded ? styles.chevronExpanded : styles.chevronCollapsed,
+        )}>
+        {getIcon('chevronRight')}
+      </span>
     </span>
   );
 
@@ -527,7 +549,7 @@ export function TreeListItem({
               isSelected && styles.selected,
             ),
           )}
-          style={{marginInlineStart: computedMarginLeft}}
+          style={indentStyle}
           onClick={handleClick}>
           {innerContent}
         </div>

package/src/Typeahead/BaseTypeahead.tsx

@@ -431,7 +431,7 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         resultsGenRef.current = gen;
         const shown = searchResults.slice(0, maxMenuItems);
         setResults(shown);
-        setHighlightedIndex(searchResults.length > 0 ? 0 : -1);
+        setHighlightedIndex(shown.length > 0 ? 0 : -1);
         if (searchResults.length > 0 || searchQuery.length > 0) {
           showLayer();
         }
@@ -469,8 +469,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         return;
       }
       resultsGenRef.current = gen;
-      setResults(bootstrapResults.slice(0, maxMenuItems));
-      setHighlightedIndex(bootstrapResults.length > 0 ? 0 : -1);
+      const shown = bootstrapResults.slice(0, maxMenuItems);
+      setResults(shown);
+      setHighlightedIndex(shown.length > 0 ? 0 : -1);
       if (bootstrapResults.length > 0) {
         showLayer();
       }
@@ -637,15 +638,19 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
       switch (e.key) {
         case 'ArrowDown':
           e.preventDefault();
-          setHighlightedIndex(prev =>
-            prev < results.length - 1 ? prev + 1 : 0,
-          );
+          if (results.length > 0) {
+            setHighlightedIndex(prev =>
+              prev < results.length - 1 ? prev + 1 : 0,
+            );
+          }
           break;
         case 'ArrowUp':
           e.preventDefault();
-          setHighlightedIndex(prev =>
-            prev > 0 ? prev - 1 : results.length - 1,
-          );
+          if (results.length > 0) {
+            setHighlightedIndex(prev =>
+              prev > 0 ? prev - 1 : results.length - 1,
+            );
+          }
           break;
         case 'Enter':
           e.preventDefault();
@@ -660,13 +665,17 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         case 'Home':
           if (popover.isOpen) {
             e.preventDefault();
-            setHighlightedIndex(0);
+            if (results.length > 0) {
+              setHighlightedIndex(0);
+            }
           }
           break;
         case 'End':
           if (popover.isOpen) {
             e.preventDefault();
-            setHighlightedIndex(results.length - 1);
+            if (results.length > 0) {
+              setHighlightedIndex(results.length - 1);
+            }
           }
           break;
       }
@@ -694,13 +703,17 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   // cursor walks off-screen once navigation passes the visible window. Mirrors
   // CommandPaletteItem's scrollIntoView({block: 'nearest'}) behavior.
   useEffect(() => {
-    if (!popover.isOpen || highlightedIndex < 0) {
+    if (
+      !popover.isOpen ||
+      highlightedIndex < 0 ||
+      highlightedIndex >= results.length
+    ) {
       return;
     }
     document
       .getElementById(getItemId(highlightedIndex))
       ?.scrollIntoView?.({block: 'nearest'});
-  }, [popover.isOpen, highlightedIndex, getItemId]);
+  }, [popover.isOpen, highlightedIndex, getItemId, results.length]);
 
   const selectedKey =
     value == null ? null : getKey(value.id, () => results.indexOf(value));
@@ -725,7 +738,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
         aria-expanded={popover.isOpen}
         aria-controls={listboxId}
         aria-activedescendant={
-          popover.isOpen && highlightedIndex >= 0
+          popover.isOpen &&
+          highlightedIndex >= 0 &&
+          highlightedIndex < results.length
             ? getItemId(highlightedIndex)
             : undefined
         }

package/src/Typeahead/Typeahead.doc.mjs

@@ -165,6 +165,12 @@ export const docs = {
       type: '(isOpen: boolean) => void',
       description: 'Callback when the dropdown opens or closes.',
     },
+    {
+      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',

package/src/Typeahead/Typeahead.test.tsx

@@ -171,6 +171,33 @@ describe('BaseTypeahead', () => {
     });
   });
 
+  describe('empty results active descendant (#4059)', () => {
+    it('does not set aria-activedescendant when search has 0 results', async () => {
+      render(
+        <BaseTypeahead
+          searchSource={fruitSource}
+          value={null}
+          onChange={() => {}}
+          debounceMs={0}
+        />,
+      );
+      const input = screen.getByRole('combobox');
+      fireEvent.change(input, {target: {value: 'zzzzz'}});
+
+      await waitFor(() => {
+        expect(input).not.toHaveAttribute('aria-activedescendant');
+      });
+
+      // Press ArrowDown — should NOT set aria-activedescendant to option-0
+      fireEvent.keyDown(input, {key: 'ArrowDown'});
+      expect(input).not.toHaveAttribute('aria-activedescendant');
+
+      // Press Home — should NOT set aria-activedescendant
+      fireEvent.keyDown(input, {key: 'Home'});
+      expect(input).not.toHaveAttribute('aria-activedescendant');
+    });
+  });
+
   it('disables input when isDisabled', () => {
     render(
       <BaseTypeahead

package/src/Typeahead/Typeahead.tsx

@@ -421,7 +421,7 @@ export function Typeahead<T extends SearchableItem>({
             styles.wrapper,
             sizeStyle,
             status && inputStatusBorderStyles[status.type],
-            status && inputStatusHoverShadowStyles[status.type],
+            status && !isDisabled && inputStatusHoverShadowStyles[status.type],
             status && inputStatusFocusWithinStyles[status.type],
             isDisabled && inputWrapperStyles.disabled,
             inputGroup && groupStyles.inGroup,

package/src/Typeahead/TypeaheadItem.tsx

@@ -132,6 +132,7 @@ export function TypeaheadItem<T extends SearchableItem>({
   icon,
   description,
   isDisabled = false,
+  xstyle,
 }: TypeaheadItemProps<T>) {
   // If item has a pre-rendered element, use it
   if (item.element) {
@@ -143,7 +144,7 @@ export function TypeaheadItem<T extends SearchableItem>({
       ref={ref}
       {...mergeProps(
         themeProps('typeahead-item'),
-        stylex.props(styles.container, isDisabled && styles.disabled),
+        stylex.props(styles.container, isDisabled && styles.disabled, xstyle),
       )}>
       {icon}
       <div {...stylex.props(styles.content)}>

package/src/__tests__/inputWidthContract.test.tsx

@@ -0,0 +1,62 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+
+import {docs as CheckboxInputDocs} from '../CheckboxInput/CheckboxInput.doc.mjs';
+import {docs as CheckboxListDocs} from '../CheckboxList/CheckboxList.doc.mjs';
+import {docs as DateInputDocs} from '../DateInput/DateInput.doc.mjs';
+import {docs as DateRangeInputDocs} from '../DateRangeInput/DateRangeInput.doc.mjs';
+import {docs as DateTimeInputDocs} from '../DateTimeInput/DateTimeInput.doc.mjs';
+import {docs as FileInputDocs} from '../FileInput/FileInput.doc.mjs';
+import {docs as MultiSelectorDocs} from '../MultiSelector/MultiSelector.doc.mjs';
+import {docs as NumberInputDocs} from '../NumberInput/NumberInput.doc.mjs';
+import {docs as RadioListDocs} from '../RadioList/RadioList.doc.mjs';
+import {docs as SelectorDocs} from '../Selector/Selector.doc.mjs';
+import {docs as SliderDocs} from '../Slider/Slider.doc.mjs';
+import {docs as SwitchDocs} from '../Switch/Switch.doc.mjs';
+import {docs as TextAreaDocs} from '../TextArea/TextArea.doc.mjs';
+import {docs as TextInputDocs} from '../TextInput/TextInput.doc.mjs';
+import {docs as TimeInputDocs} from '../TimeInput/TimeInput.doc.mjs';
+import {docs as TokenizerDocs} from '../Tokenizer/Tokenizer.doc.mjs';
+import {docs as TypeaheadDocs} from '../Typeahead/Typeahead.doc.mjs';
+
+const inputDocsSuite = [
+  {name: 'CheckboxInput', docs: CheckboxInputDocs},
+  {name: 'CheckboxList', docs: CheckboxListDocs},
+  {name: 'DateInput', docs: DateInputDocs},
+  {name: 'DateRangeInput', docs: DateRangeInputDocs},
+  {name: 'DateTimeInput', docs: DateTimeInputDocs},
+  {name: 'FileInput', docs: FileInputDocs},
+  {name: 'MultiSelector', docs: MultiSelectorDocs},
+  {name: 'NumberInput', docs: NumberInputDocs},
+  {name: 'RadioList', docs: RadioListDocs},
+  {name: 'Selector', docs: SelectorDocs},
+  {name: 'Slider', docs: SliderDocs},
+  {name: 'Switch', docs: SwitchDocs},
+  {name: 'TextArea', docs: TextAreaDocs},
+  {name: 'TextInput', docs: TextInputDocs},
+  {name: 'TimeInput', docs: TimeInputDocs},
+  {name: 'Tokenizer', docs: TokenizerDocs},
+  {name: 'Typeahead', docs: TypeaheadDocs},
+];
+
+describe('Input Family width Prop Contract (#4163)', () => {
+  inputDocsSuite.forEach(({name, docs}) => {
+    it(`documents the width prop for ${name}`, () => {
+      const propsList = (docs.props || docs.components?.[0]?.props) as {
+        name: string;
+        type: string;
+      }[];
+      expect(
+        propsList,
+        `${name}.doc.mjs must expose a props array`,
+      ).toBeDefined();
+      const widthProp = propsList.find(p => p.name === 'width');
+      expect(
+        widthProp,
+        `${name}.doc.mjs must document the width prop`,
+      ).toBeDefined();
+      expect(widthProp?.type).toBe('SizeValue');
+    });
+  });
+});

package/src/doc-mjs.d.ts

@@ -0,0 +1,19 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Ambient module declaration for `*.doc.mjs` imports.
+ *
+ * Component contract tests (packages/core/src/__tests__/*Contract.test.tsx)
+ * import `{Name}.doc.mjs` files directly to assert their documented props
+ * stay in sync with the component's real API. Without this declaration,
+ * TypeScript has no way to type a `.mjs` import and fails with
+ * TS7016 ("Could not find a declaration file for module").
+ */
+
+declare module '*.doc.mjs' {
+  import type {ComponentDoc, TranslationDoc} from './docs-types';
+
+  export const docs: ComponentDoc;
+  export const docsZh: ComponentDoc;
+  export const docsDense: TranslationDoc;
+}

package/src/hooks/index.ts

@@ -76,6 +76,12 @@ export type {
 export {useInputContainer} from './useInputContainer';
 export type {UseInputContainerOptions} from './useInputContainer';
 
+export {useInputStatusIcon} from './useInputStatusIcon';
+export type {
+  UseInputStatusIconOptions,
+  UseInputStatusIconReturn,
+} from './useInputStatusIcon';
+
 export {useInteractiveRole} from './useInteractiveRole';
 export type {
   InteractiveRole,

package/src/hooks/isRtlElement.ts

@@ -0,0 +1,27 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file isRtlElement.ts
+ * @input DOM element (nullable)
+ * @output Exports isRtlElement helper resolving an element's computed text
+ *   direction
+ * @position Internal hook utility; used by useListFocus and useGridFocus to
+ *   auto-detect RTL for arrow-key navigation (same getComputedStyle precedent
+ *   as Resizable's ResizeHandle drag deltas).
+ */
+
+/**
+ * Whether `el` renders right-to-left, per its computed `direction`.
+ *
+ * SSR-safe: returns false when `el` is null or no DOM is available. Callers
+ * should invoke this lazily (on keydown, not on render) so getComputedStyle
+ * runs only when a horizontal arrow key is actually handled.
+ */
+export function isRtlElement(el: HTMLElement | null): boolean {
+  if (!el || typeof window === 'undefined') {
+    return false;
+  }
+  return window.getComputedStyle(el).direction === 'rtl';
+}