@astryxdesign/core 0.1.1 → 0.1.2-canary.04e71b2

package/dist/TreeList/TreeList.js

@@ -4,7 +4,7 @@
 
 /**
  * @file TreeList.tsx
- * @input Uses React, StyleX, theme tokens, TreeListItem, TreeListTypes
+ * @input Uses React, StyleX, theme tokens, TreeListItem, TreeListTypes, useTreeFocus
  * @output Exports TreeList component, TreeListProps type
  * @position Core implementation; consumed by index.ts
  *
@@ -21,6 +21,7 @@ import { spacingVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
 import { TreeListItem } from "./TreeListItem.js";
 import { themeProps } from "../utils/themeProps.js";
+import { useTreeFocus } from "../hooks/useTreeFocus.js";
 
 // =============================================================================
 // Types
@@ -55,6 +56,35 @@ function collectExpandedKeys(items) {
   return keys;
 }
 
+/**
+ * Compute the initial roving-tabindex seed: the first selected enabled item in
+ * document order, else the first enabled item, else the first item. The hook
+ * (useTreeFocus with hasRovingTabIndex) takes ownership after mount — it
+ * preserves this seeded `tabindex="0"` on its repair pass and moves the stop
+ * with keyboard navigation.
+ */
+function findInitialTabbableId(items) {
+  let firstEnabled;
+  const walk = list => {
+    for (const item of list) {
+      if (item.isSelected && item.isDisabled !== true) {
+        return item.id;
+      }
+      if (firstEnabled == null && item.isDisabled !== true) {
+        firstEnabled = item.id;
+      }
+      if (item.children != null && item.children.length > 0) {
+        const selected = walk(item.children);
+        if (selected != null) {
+          return selected;
+        }
+      }
+    }
+    return undefined;
+  };
+  return walk(items) ?? firstEnabled ?? items[0]?.id;
+}
+
 // =============================================================================
 // Component
 // =============================================================================
@@ -106,6 +136,40 @@ export function TreeList({
       return next;
     });
   }, [expandedKeysFromProps]);
+
+  // ---------------------------------------------------------------------------
+  // Roving tabindex + APG tree keyboard model (via useTreeFocus)
+  // ---------------------------------------------------------------------------
+
+  // The hook (hasRovingTabIndex) owns the tree's single tab stop: it repairs
+  // the stop on mount and moves it with keyboard navigation. We only seed the
+  // initially-tabbable treeitem in the render (selected item or first enabled);
+  // the hook's repair pass preserves that seeded `tabindex="0"`.
+  const initialTabbableId = useMemo(() => findInitialTabbableId(items), [items]);
+
+  // Enter/Space activation: prefer the treeitem's own inner action (link or
+  // button); return true when handled so the hook does not also toggle. Scoped
+  // to this treeitem's own row — never a descendant treeitem's action inside an
+  // expanded group.
+  const activateItem = useCallback(current => {
+    const candidates = current.querySelectorAll('a[href], button:not([aria-label="Toggle children"])');
+    for (const candidate of candidates) {
+      if (candidate.closest('[role="treeitem"]') === current) {
+        candidate.click();
+        return true;
+      }
+    }
+    return false;
+  }, []);
+  const {
+    treeRef,
+    handleKeyDown,
+    handleFocus
+  } = useTreeFocus({
+    onToggleExpand: handleToggle,
+    onActivate: activateItem,
+    hasRovingTabIndex: true
+  });
   function renderItems(items, nestedLevel, ancestorsIsLast) {
     return items.map((item, index) => {
       const isLast = index === items.length - 1;
@@ -131,7 +195,10 @@ export function TreeList({
         isExpanded: isExpanded,
         onToggle: handleToggle,
         density: density,
-        renderedChildren: renderedChildren
+        renderedChildren: renderedChildren,
+        posInSet: index + 1,
+        setSize: items.length,
+        isTabbable: item.id === initialTabbableId
       }, item.id);
     });
   }
@@ -148,8 +215,11 @@ export function TreeList({
       },
       children: header
     }), /*#__PURE__*/_jsx("ul", {
+      ref: treeRef,
       role: "tree",
       "aria-labelledby": header != null ? headerId : undefined,
+      onKeyDown: handleKeyDown,
+      onFocus: handleFocus,
       ...{
         className: "x1ghz6dp x1717udv x3ct3a4"
       },

package/dist/TreeList/TreeListItem.d.ts

@@ -31,8 +31,18 @@ export interface TreeListItemInternalProps {
     density: TreeListDensity;
     /** Pre-rendered children subtree (rendered by the parent recursion) */
     renderedChildren?: ReactNode;
+    /** 1-based position of this item among its siblings (aria-posinset). */
+    posInSet: number;
+    /** Number of siblings at this level (aria-setsize). */
+    setSize: number;
+    /**
+     * Whether this treeitem is the initial roving-tabindex seed. Exactly one
+     * treeitem is seeded tabbable at mount; useTreeFocus (hasRovingTabIndex)
+     * then owns the tab stop dynamically.
+     */
+    isTabbable: boolean;
 }
-export declare function TreeListItem({ id, label, description, startContent, endContent, onClick, href, target, isDisabled, isSelected, hasChildren, nestedLevel, isLast, ancestorsIsLast, isExpanded, onToggle, density, renderedChildren, }: TreeListItemInternalProps): import("react").JSX.Element;
+export declare function TreeListItem({ id, label, description, startContent, endContent, onClick, href, target, isDisabled, isSelected, hasChildren, nestedLevel, isLast, ancestorsIsLast, isExpanded, onToggle, density, renderedChildren, posInSet, setSize, isTabbable, }: TreeListItemInternalProps): import("react").JSX.Element;
 export declare namespace TreeListItem {
     var displayName: string;
 }

package/dist/TreeList/TreeListItem.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TreeListItem.d.ts","sourceRoot":"","sources":["../../src/TreeList/TreeListItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAcrD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iBAAiB,CAAC;AA0MrD,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,OAAO,EAAE,eAAe,CAAC;IACzB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,SAAS,CAAC;CAC9B;AAMD,wBAAgB,YAAY,CAAC,EAC3B,EAAE,EACF,KAAK,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,OAAO,EACP,IAAI,EACJ,MAAM,EACN,UAAkB,EAClB,UAAkB,EAClB,WAAW,EACX,WAAW,EACX,MAAM,EACN,eAAe,EACf,UAAU,EACV,QAAQ,EACR,OAAO,EACP,gBAAgB,GACjB,EAAE,yBAAyB,+BAoK3B;yBAvLe,YAAY"}
+{"version":3,"file":"TreeListItem.d.ts","sourceRoot":"","sources":["../../src/TreeList/TreeListItem.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;GAUG;AAEH,OAAO,EAAiB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAcrD,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iBAAiB,CAAC;AAoNrD,MAAM,WAAW,yBAAyB;IACxC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,KAAK,CAAC,SAAS,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC/B,UAAU,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC7B,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,UAAU,KAAK,IAAI,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;IAChB,eAAe,EAAE,aAAa,CAAC,OAAO,CAAC,CAAC;IACxC,UAAU,EAAE,OAAO,CAAC;IACpB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,OAAO,EAAE,eAAe,CAAC;IACzB,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,SAAS,CAAC;IAC7B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,UAAU,EAAE,OAAO,CAAC;CACrB;AAMD,wBAAgB,YAAY,CAAC,EAC3B,EAAE,EACF,KAAK,EACL,WAAW,EACX,YAAY,EACZ,UAAU,EACV,OAAO,EACP,IAAI,EACJ,MAAM,EACN,UAAkB,EAClB,UAAkB,EAClB,WAAW,EACX,WAAW,EACX,MAAM,EACN,eAAe,EACf,UAAU,EACV,QAAQ,EACR,OAAO,EACP,gBAAgB,EAChB,QAAQ,EACR,OAAO,EACP,UAAU,GACX,EAAE,yBAAyB,+BA2L3B;yBAjNe,YAAY"}

package/dist/TreeList/TreeListItem.js

@@ -21,6 +21,8 @@ import { getIcon } from "../Icon/globalIconRegistry.js";
 import { mergeProps } from "../utils/index.js";
 import { useLinkComponent } from "../Link/useLinkComponent.js";
 import { TreeListBranches } from "./TreeListBranches.js";
+import "./treeListItem.markers.stylex.js";
+import { treeItemScope } from "./treeListItem.markers.stylex.js";
 import { themeProps } from "../utils/themeProps.js";
 
 // =============================================================================
@@ -28,6 +30,15 @@ import { themeProps } from "../utils/themeProps.js";
 // =============================================================================
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const styles = {
+  wrapper: {
+    kH6xsr: "x3ct3a4",
+    kogj98: "x1ghz6dp",
+    kmVPX3: "x1717udv",
+    kVAEAm: "x1n2onr6",
+    kzqmXN: "xh8yej3",
+    kI3sdo: "x1a2a7pz",
+    $$css: true
+  },
   contentWrapper: {
     kaIpWk: "xh6dtrn",
     k1xSpc: "x78zum5",
@@ -50,8 +61,8 @@ const styles = {
     $$css: true
   },
   focusVisibleOutline: {
-    kI3sdo: "x1a2a7pz x1irc7jg",
-    kInvED: "x1wfwxd8 xdjuwb3",
+    kI3sdo: "x1a2a7pz xr21g96 x1irc7jg",
+    kInvED: "x1wfwxd8 xs4y3kv xdjuwb3",
     $$css: true
   },
   disabled: {
@@ -133,7 +144,10 @@ export function TreeListItem({
   isExpanded,
   onToggle,
   density,
-  renderedChildren
+  renderedChildren,
+  posInSet,
+  setSize,
+  isTabbable
 }) {
   const labelId = useId();
   const descriptionId = useId();
@@ -187,13 +201,22 @@ export function TreeListItem({
     }[!!isExpanded << 0],
     children: getIcon('chevronRight')
   });
-  const chevron = hasChildren ? handleClick != null && onClick != null ?
+  const chevron = hasChildren ? handleToggle != null ?
   /*#__PURE__*/
-  // Separate toggle button when item has its own onClick
+  // Real toggle button whenever expand/collapse is supported, so the row
+  // can be expanded from the keyboard even when the item has no onClick/href
+  // (row-level onClick is the only click path in that case, but there is no
+  // focusable element to receive Enter/Space). The row's handleClick ignores
+  // clicks originating inside a <button>, so this never double-toggles.
   _jsx("button", {
     type: "button",
     "aria-expanded": isExpanded,
     "aria-label": "Toggle children",
+    disabled: isDisabled
+    // Roving tabindex lives on the treeitem row; the chevron toggle is not
+    // a separate tab stop. Row-level Enter/Space forwards to this button.
+    ,
+    tabIndex: -1,
     onClick: handleToggle,
     ...{
       className: "x78zum5 x6s0dn4 xl56j7k x12xnipv x6b6gus xho7bvi x1ypdohk xv9yike xx3sua9 x11g1kdw xmequkd"
@@ -201,7 +224,7 @@ export function TreeListItem({
     children: chevronIcon
   }) :
   /*#__PURE__*/
-  // Non-interactive chevron when clicking the row toggles
+  // Non-interactive chevron only when toggling is not wired up at all
   _jsx("span", {
     ...{
       className: "x2lah0s x78zum5 x6s0dn4 xl56j7k x12xnipv x6b6gus xho7bvi x1ypdohk x1717udv xv9yike xx3sua9 x11g1kdw xmequkd"
@@ -219,8 +242,11 @@ export function TreeListItem({
       target: target,
       "aria-disabled": isDisabled || undefined,
       "aria-labelledby": labelId,
-      "aria-describedby": description != null ? descriptionId : undefined,
-      tabIndex: isDisabled ? -1 : undefined,
+      "aria-describedby": description != null ? descriptionId : undefined
+      // Roving tabindex lives on the treeitem row; inner action is not a
+      // separate tab stop. Activation is forwarded from the row.
+      ,
+      tabIndex: -1,
       ...{
         className: "xmper1u xln7xf2 x1heor9g x78zum5 xdt5ytf x98rzlu xeuugli x1yc453h x1hl2dhg x1a2a7pz"
       },
@@ -230,7 +256,11 @@ export function TreeListItem({
       onClick: onClick,
       disabled: isDisabled,
       "aria-labelledby": labelId,
-      "aria-describedby": description != null ? descriptionId : undefined,
+      "aria-describedby": description != null ? descriptionId : undefined
+      // Roving tabindex lives on the treeitem row; inner action is not a
+      // separate tab stop. Activation is forwarded from the row.
+      ,
+      tabIndex: -1,
       ...{
         className: "xmper1u xln7xf2 x1heor9g x78zum5 xdt5ytf x98rzlu xeuugli x1yc453h x1a2a7pz"
       },
@@ -252,9 +282,18 @@ export function TreeListItem({
     "aria-expanded": hasChildren ? isExpanded : undefined,
     "aria-selected": isSelected || undefined,
     "aria-disabled": isDisabled || undefined,
-    ...{
-      className: "x3ct3a4 x1ghz6dp x1717udv x1n2onr6 xh8yej3"
-    },
+    "aria-level": nestedLevel + 1,
+    "aria-posinset": posInSet,
+    "aria-setsize": setSize
+    // Roving tabindex: exactly one visible treeitem is tabbable at a time.
+    // Disabled items are skipped by the tree keyboard handler but remain
+    // in the accessibility tree.
+    ,
+    tabIndex: isDisabled ? -1 : isTabbable ? 0 : -1,
+    "data-tree-id": id,
+    "data-tree-level": nestedLevel + 1,
+    "data-tree-disabled": isDisabled || undefined,
+    ...stylex.props(styles.wrapper, treeItemScope),
     children: [/*#__PURE__*/_jsx("div", {
       ...{
         className: "x12gdq22"

package/dist/TreeList/treeListItem.markers.stylex.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file treeListItem.markers.stylex.ts
+ * @input Uses StyleX defineMarker
+ * @output Exports treeItemScope marker
+ * @position Scoped marker; consumed by TreeListItem.tsx
+ *
+ * SYNC: When modified, update /packages/core/src/TreeList/TreeListItem.tsx
+ */
+import * as stylex from '@stylexjs/stylex';
+/**
+ * Scoped marker placed on each treeitem row (`<li role="treeitem">`).
+ * Binds the row's `:focus-visible` outline to its OWN treeitem, so focusing
+ * a parent treeitem does not leak the focus ring onto descendant rows.
+ */
+export declare const treeItemScope: ReturnType<typeof stylex.defineMarker>;
+//# sourceMappingURL=treeListItem.markers.stylex.d.ts.map

package/dist/TreeList/treeListItem.markers.stylex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeListItem.markers.stylex.d.ts","sourceRoot":"","sources":["../../src/TreeList/treeListItem.markers.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAE3C;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,UAAU,CAAC,OAAO,MAAM,CAAC,YAAY,CAC1C,CAAC"}

package/dist/TreeList/treeListItem.markers.stylex.js

@@ -0,0 +1,22 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file treeListItem.markers.stylex.ts
+ * @input Uses StyleX defineMarker
+ * @output Exports treeItemScope marker
+ * @position Scoped marker; consumed by TreeListItem.tsx
+ *
+ * SYNC: When modified, update /packages/core/src/TreeList/TreeListItem.tsx
+ */
+
+import * as stylex from '@stylexjs/stylex';
+
+/**
+ * Scoped marker placed on each treeitem row (`<li role="treeitem">`).
+ * Binds the row's `:focus-visible` outline to its OWN treeitem, so focusing
+ * a parent treeitem does not leak the focus ring onto descendant rows.
+ */
+export const treeItemScope = {
+  x1g2q90y: "x1g2q90y",
+  $$css: true
+};

package/dist/Typeahead/BaseTypeahead.d.ts

@@ -58,6 +58,15 @@ export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<BaseP
      * @default false
      */
     isDisabled?: boolean;
+    /**
+     * When disabled with a reason, keeps the input focusable via `aria-disabled`
+     * (instead of the native `disabled` attribute) and `readOnly` so an
+     * associated disabled-reason tooltip stays discoverable by keyboard and
+     * assistive technology. Value mutation is still blocked by the `isDisabled`
+     * guards. Consumers (Typeahead) own the tooltip and wrapper.
+     * @default false
+     */
+    isFocusableDisabled?: boolean;
     /**
      * Auto-focus on mount.
      * @default false

package/dist/Typeahead/BaseTypeahead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseTypeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/BaseTypeahead.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,EAMZ,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAanD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,cAAc,EAAE,YAAY,EAAC,MAAM,SAAS,CAAC;AAO1D,MAAM,WAAW,kBAAkB,CACjC,CAAC,SAAS,cAAc,CACxB,SAAQ,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,EAAE,UAAU,CAAC;IAChD,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC;IAEpC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;IAE3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAE/D;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CAC3B;AAuGD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,EAqcrB,CAAC,CAAC,SAAS,cAAc,EAC5B,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KACzB,KAAK,CAAC,YAAY,CAAC"}
+{"version":3,"file":"BaseTypeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/BaseTypeahead.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,EAMZ,KAAK,SAAS,EACd,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAEf,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,kBAAkB,CAAC;AAcnD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,cAAc,EAAE,YAAY,EAAC,MAAM,SAAS,CAAC;AAO1D,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,cAAc,CAAE,SAAQ,IAAI,CACxE,SAAS,CAAC,WAAW,CAAC,EACtB,UAAU,CACX;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAClC;;OAEG;IACH,YAAY,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAE9B;;OAEG;IACH,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,KAAK,IAAI,CAAC;IAEnC;;OAEG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC;IAEpC;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAE9B;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB;;OAEG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAExC;;OAEG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;IAE3B;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IAE1C;;;OAGG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,gBAAgB,CAAC,KAAK,IAAI,CAAC;IAE/D;;;;OAIG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;CAC3B;AAuGD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,aAAa,EAsgBrB,CAAC,CAAC,SAAS,cAAc,EAC5B,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KACzB,KAAK,CAAC,YAAY,CAAC"}

package/dist/Typeahead/BaseTypeahead.js

@@ -19,6 +19,7 @@
 import React, { useCallback, useEffect, useId, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { usePopover } from "../Popover/usePopover.js";
+import { useAnnounce } from "../hooks/useAnnounce.js";
 import { TypeaheadItem } from "./TypeaheadItem.js";
 import { Icon } from "../Icon/index.js";
 import "../theme/tokens.stylex.js";
@@ -141,6 +142,7 @@ export const BaseTypeahead = function BaseTypeahead({
   maxMenuItems = 10,
   emptySearchResultsText = 'No results found',
   isDisabled = false,
+  isFocusableDisabled = false,
   hasAutoFocus = false,
   onChangeQuery,
   onOpenChange,
@@ -158,6 +160,11 @@ export const BaseTypeahead = function BaseTypeahead({
   const listboxId = useId();
   const inputRef = useRef(null);
   const fallbackAnchorRef = useRef(null);
+
+  // Announce result counts / "no results" to screen readers via a persistent
+  // live region (comboboxes-6). The combobox's own popup carries no working
+  // live region, so highlight/result changes were previously silent.
+  const announce = useAnnounce();
   const [query, setQuery] = useState('');
   const [results, setResults] = useState([]);
   const [highlightedIndex, setHighlightedIndex] = useState(-1);
@@ -197,7 +204,10 @@ export const BaseTypeahead = function BaseTypeahead({
     onHide: handleLayerHide,
     hasLightDismiss: true,
     hasCloseButton: false,
-    hasAutoFocus: false
+    hasAutoFocus: false,
+    // The popup's own role="listbox" is the exposed semantics; the input keeps
+    // DOM focus, so wrapping it in a modal dialog would misrepresent it.
+    role: 'none'
   });
 
   // Show the layer, deferring past the active click if a pointer is down.
@@ -236,11 +246,17 @@ export const BaseTypeahead = function BaseTypeahead({
         return;
       }
       resultsGenRef.current = gen;
-      setResults(searchResults.slice(0, maxMenuItems));
+      const shown = searchResults.slice(0, maxMenuItems);
+      setResults(shown);
       setHighlightedIndex(searchResults.length > 0 ? 0 : -1);
       if (searchResults.length > 0 || searchQuery.length > 0) {
         showLayer();
       }
+      // Announce the outcome only for an active query (not the initial
+      // focus-open), so screen-reader users hear result counts / no-results.
+      if (searchQuery.length > 0) {
+        announce(shown.length === 0 ? emptySearchResultsText : `${shown.length} ${shown.length === 1 ? 'result' : 'results'}`);
+      }
     } catch {
       if (searchGenRef.current !== gen) {
         return;
@@ -252,7 +268,7 @@ export const BaseTypeahead = function BaseTypeahead({
         setIsLoading(false);
       }
     }
-  }, [searchSource, maxMenuItems, showLayer]);
+  }, [searchSource, maxMenuItems, showLayer, announce, emptySearchResultsText]);
 
   // Perform bootstrap
   const performBootstrap = useCallback(async () => {
@@ -293,6 +309,8 @@ export const BaseTypeahead = function BaseTypeahead({
       searchSource.cancel?.();
       setResults([]);
       setHasSearched(false);
+      // Clear any lingering result-count / no-results announcement.
+      announce('');
       popover.hide();
       return;
     }
@@ -308,7 +326,7 @@ export const BaseTypeahead = function BaseTypeahead({
     } else {
       searchTimeoutRef.current = setTimeout(triggerSearch, debounceMs);
     }
-  }, [onChangeQuery, hasEntriesOnFocus, performSearch, performBootstrap, popover, debounceMs, searchSource]);
+  }, [onChangeQuery, hasEntriesOnFocus, performSearch, performBootstrap, popover, debounceMs, searchSource, announce]);
 
   // Handle input change
   const handleInputChange = useCallback(e => {
@@ -348,6 +366,29 @@ export const BaseTypeahead = function BaseTypeahead({
     }
   }, [isDisabled, hasEntriesOnFocus, results.length, query.length, performBootstrap, showLayer]);
 
+  // Handle blur — close the dropdown when focus leaves the input for an
+  // element that is neither inside the field wrapper (anchor) nor inside the
+  // dropdown popover. The native popover="auto" light-dismiss only fires on
+  // outside pointer clicks and Escape; it does not close when focus moves away
+  // via the keyboard (Tab) or programmatically, which would otherwise leave an
+  // orphaned open menu. Clicking a result moves focus onto the option (it is
+  // tabIndex={-1}, so it lives inside the popover) and selection re-focuses the
+  // input, so this only closes on a genuine focus-out of the whole field.
+  const handleBlur = useCallback(e => {
+    if (!popover.isOpen) {
+      return;
+    }
+    const next = e.relatedTarget;
+    if (next) {
+      const anchorEl = anchorRef?.current ?? fallbackAnchorRef.current;
+      const popoverEl = document.getElementById(popover.id);
+      if (anchorEl?.contains(next) || popoverEl?.contains(next)) {
+        return;
+      }
+    }
+    popover.hide();
+  }, [popover, anchorRef]);
+
   // Keyboard navigation
   const handleKeyDown = useCallback(e => {
     externalOnKeyDown?.(e);
@@ -402,6 +443,19 @@ export const BaseTypeahead = function BaseTypeahead({
 
   // Generate item ID for accessibility
   const getItemId = useCallback(index => `${listboxId}-option-${index}`, [listboxId]);
+
+  // Keep the highlighted option visible during keyboard navigation. The
+  // listbox is a fixed-height scroll container, so without this the virtual
+  // cursor walks off-screen once navigation passes the visible window. Mirrors
+  // CommandPaletteItem's scrollIntoView({block: 'nearest'}) behavior.
+  useEffect(() => {
+    if (!popover.isOpen || highlightedIndex < 0) {
+      return;
+    }
+    document.getElementById(getItemId(highlightedIndex))?.scrollIntoView?.({
+      block: 'nearest'
+    });
+  }, [popover.isOpen, highlightedIndex, getItemId]);
   const selectedKey = value == null ? null : getKey(value.id, () => results.indexOf(value));
 
   // Cleanup timeout and cancel in-flight searches on unmount
@@ -424,6 +478,7 @@ export const BaseTypeahead = function BaseTypeahead({
       "aria-activedescendant": popover.isOpen && highlightedIndex >= 0 ? getItemId(highlightedIndex) : undefined,
       "aria-autocomplete": "list",
       "aria-describedby": ariaDescribedBy,
+      "aria-disabled": isFocusableDisabled ? 'true' : undefined,
       value: query,
       onChange: handleInputChange,
       onPointerDown: () => {
@@ -435,9 +490,15 @@ export const BaseTypeahead = function BaseTypeahead({
         });
       },
       onFocus: handleFocus,
+      onBlur: handleBlur,
       onKeyDown: handleKeyDown,
-      placeholder: placeholder,
-      disabled: isDisabled,
+      placeholder: placeholder
+      // When a disabled-reason tooltip is shown the input keeps focusability
+      // via aria-disabled + readOnly instead of the native disabled
+      // attribute; value mutation stays blocked by the isDisabled guards.
+      ,
+      disabled: isDisabled && !isFocusableDisabled,
+      readOnly: isFocusableDisabled || undefined,
       autoFocus: hasAutoFocus,
       "data-autofocus": hasAutoFocus || undefined,
       autoComplete: "off",

package/dist/Typeahead/Typeahead.d.ts

@@ -66,6 +66,29 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<BaseProps
     emptySearchResultsText?: string;
     /** Whether the input is disabled. @default false */
     isDisabled?: boolean;
+    /**
+     * Explains why the input is disabled. When set together with `isDisabled`,
+     * the input shows a tooltip with this text on hover and keyboard focus, and
+     * the field stays focusable (via `aria-disabled`) so the reason is
+     * discoverable by keyboard and assistive technology. Editing and selection
+     * stay blocked.
+     *
+     * Use this instead of wrapping a disabled input in `Tooltip` — disabled
+     * controls don't emit the pointer events an external tooltip needs.
+     *
+     * @example
+     * ```
+     * <Typeahead
+     *   label="Assignee"
+     *   searchSource={userSource}
+     *   value={assignee}
+     *   onChange={setAssignee}
+     *   isDisabled
+     *   disabledMessage="You need the Editor role to change this"
+     * />
+     * ```
+     */
+    disabledMessage?: string;
     /** Show clear button. @default true */
     hasClear?: boolean;
     /** Auto-focus on mount. @default false */
@@ -104,7 +127,7 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<BaseProps
  * />
  * ```
  */
-export declare function Typeahead<T extends SearchableItem>({ ref, label, isLabelHidden, description, isRequired, isOptional, status, startIcon, labelTooltip, searchSource, value, onChange, renderItem, placeholder, hasEntriesOnFocus, maxMenuItems, emptySearchResultsText, isDisabled, hasClear, hasAutoFocus, size: sizeProp, debounceMs, onChangeQuery, onOpenChange, width, xstyle, className, style, 'data-testid': testId, }: TypeaheadProps<T>): React.JSX.Element;
+export declare function Typeahead<T extends SearchableItem>({ ref, label, isLabelHidden, description, isRequired, isOptional, status, startIcon, labelTooltip, searchSource, value, onChange, renderItem, placeholder, hasEntriesOnFocus, maxMenuItems, emptySearchResultsText, isDisabled, disabledMessage, hasClear, hasAutoFocus, size: sizeProp, debounceMs, onChangeQuery, onOpenChange, width, xstyle, className, style, 'data-testid': testId, }: TypeaheadProps<T>): React.JSX.Element;
 export declare namespace Typeahead {
     var displayName: string;
 }

package/dist/Typeahead/Typeahead.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Typeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/Typeahead.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"Typeahead.d.ts","sourceRoot":"","sources":["../../src/Typeahead/Typeahead.tsx"],"names":[],"mappings":"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"}

package/dist/Typeahead/Typeahead.js

@@ -23,6 +23,7 @@ import { BaseTypeahead } from "./BaseTypeahead.js";
 import { useSize } from "../SizeContext/SizeContext.js";
 import { Field, InputClearButton, inputWrapperStyles, inputStatusBorderStyles, inputStatusHoverShadowStyles, inputStatusFocusWithinStyles } from "../Field/index.js";
 import { Token } from "../Token/index.js";
+import { useTooltip } from "../Tooltip/index.js";
 import { renderIconSlot } from "../Icon/index.js";
 import "../theme/tokens.stylex.js";
 import { spacingVars, sizeVars } from "../theme/tokens.stylex.js";
@@ -127,6 +128,7 @@ export function Typeahead({
   maxMenuItems,
   emptySearchResultsText,
   isDisabled = false,
+  disabledMessage,
   hasClear = true,
   hasAutoFocus,
   size: sizeProp,
@@ -147,6 +149,21 @@ export function Typeahead({
   const inputRef = useRef(null);
   const tokenRef = useRef(null);
 
+  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
+  // tooltip listeners attach to the input wrapper (which already exists) and
+  // the input stays perceivable via aria-disabled + readOnly instead of the
+  // disabled attribute. Editing and selection stay blocked by the isDisabled
+  // guards (handleWrapperClick, handleEnterEditMode, and BaseTypeahead's own
+  // focus/change guards).
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    // The wrapper div is not naturally focusable; focusin bubbles up from the
+    // input, so always attach focus listeners.
+    focusTrigger: 'always',
+    isEnabled: showsDisabledMessage
+  });
+
   // Edit mode: when the user clicks the token to edit the selected value
   const [isEditing, setIsEditing] = useState(false);
   const [editingValue, setEditingValue] = useState(null);
@@ -240,9 +257,9 @@ export function Typeahead({
       inputRef.current?.focus();
     }
   }, [isDisabled, showToken, handleEnterEditMode]);
-  const ariaDescribedBy = [description ? descriptionId : null, status?.message ? statusMessageId : null].filter(Boolean).join(' ') || undefined;
+  const ariaDescribedBy = [description ? descriptionId : null, status?.message ? statusMessageId : null, showsDisabledMessage ? disabledMessageTooltip.describedBy : null].filter(Boolean).join(' ') || undefined;
   const sizeStyle = wrapperSizeStyles[size];
-  return /*#__PURE__*/_jsx(Field, {
+  return /*#__PURE__*/_jsxs(Field, {
     ref: ref,
     label: label,
     isLabelHidden: isLabelHidden,
@@ -262,8 +279,14 @@ export function Typeahead({
     xstyle: xstyle,
     className: className,
     style: style,
-    children: /*#__PURE__*/_jsxs("div", {
-      ref: wrapperRef,
+    children: [/*#__PURE__*/_jsxs("div", {
+      ref: el => {
+        wrapperRef.current = el;
+        // Anchor + hover/focus listeners for the disabled-message tooltip.
+        // Handlers are gated internally by isEnabled, so attaching
+        // unconditionally is safe.
+        disabledMessageTooltip.ref(el);
+      },
       "data-testid": testId,
       onClick: handleWrapperClick,
       onBlur: handleBlur,
@@ -293,6 +316,7 @@ export function Typeahead({
         emptySearchResultsText: emptySearchResultsText,
         isDisabled: isDisabled,
         hasAutoFocus: hasAutoFocus,
+        isFocusableDisabled: showsDisabledMessage,
         inputId: inputId,
         ariaDescribedBy: ariaDescribedBy,
         onChangeQuery: onChangeQuery,
@@ -310,7 +334,7 @@ export function Typeahead({
         },
         xstyle: [styles.clearButton, size === 'sm' && styles.clearButtonSm]
       })]
-    })
+    }), showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
   });
 }
 Typeahead.displayName = 'Typeahead';