@astryxdesign/core 0.1.2 → 0.1.3

package/src/TreeList/TreeListItem.tsx

@@ -29,6 +29,7 @@ import {mergeProps} from '../utils';
 import {useLinkComponent} from '../Link/useLinkComponent';
 import {TreeListBranches} from './TreeListBranches';
 import type {TreeListDensity} from './TreeListTypes';
+import {treeItemScope} from './treeListItem.markers.stylex';
 import {themeProps} from '../utils/themeProps';
 
 // =============================================================================
@@ -42,6 +43,9 @@ const styles = stylex.create({
     padding: 0,
     position: 'relative',
     width: '100%',
+    // The treeitem row is the roving-tabindex focus owner; suppress the
+    // native focus ring in favor of the row's :focus-visible outline below.
+    outline: 'none',
   },
   childGroup: {
     margin: 0,
@@ -82,10 +86,16 @@ const styles = stylex.create({
   focusVisibleOutline: {
     outline: {
       default: 'none',
+      // Focus lives on the treeitem row (the <li>) via roving tabindex.
+      // Scoped to the row's OWN treeitem so focusing a parent does not leak
+      // the ring onto descendant rows. Also support inner focusable actions.
+      [stylex.when.ancestor(':focus-visible', treeItemScope)]:
+        `2px solid ${colorVars['--color-accent']}`,
       ':has(:focus-visible)': `2px solid ${colorVars['--color-accent']}`,
     },
     outlineOffset: {
       default: '0',
+      [stylex.when.ancestor(':focus-visible', treeItemScope)]: '2px',
       ':has(:focus-visible)': '2px',
     },
   },
@@ -250,6 +260,16 @@ 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;
 }
 
 // =============================================================================
@@ -275,6 +295,9 @@ export function TreeListItem({
   onToggle,
   density,
   renderedChildren,
+  posInSet,
+  setSize,
+  isTabbable,
 }: TreeListItemInternalProps) {
   const labelId = useId();
   const descriptionId = useId();
@@ -342,18 +365,26 @@ export function TreeListItem({
   );
 
   const chevron = hasChildren ? (
-    handleClick != null && onClick != null ? (
-      // Separate toggle button when item has its own onClick
+    handleToggle != null ? (
+      // 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.
       <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}
         {...stylex.props(styles.chevronButton)}>
         {chevronIcon}
       </button>
     ) : (
-      // Non-interactive chevron when clicking the row toggles
+      // Non-interactive chevron only when toggling is not wired up at all
       <span {...stylex.props(styles.chevronContainer)}>{chevronIcon}</span>
     )
   ) : null;
@@ -371,7 +402,9 @@ export function TreeListItem({
           aria-disabled={isDisabled || undefined}
           aria-labelledby={labelId}
           aria-describedby={description != null ? descriptionId : undefined}
-          tabIndex={isDisabled ? -1 : undefined}
+          // Roving tabindex lives on the treeitem row; inner action is not a
+          // separate tab stop. Activation is forwarded from the row.
+          tabIndex={-1}
           {...stylex.props(styles.invisibleAnchor)}>
           {labelAndDescription}
         </LinkComponent>
@@ -382,6 +415,9 @@ export function TreeListItem({
           disabled={isDisabled}
           aria-labelledby={labelId}
           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}
           {...stylex.props(styles.invisibleButton)}>
           {labelAndDescription}
         </button>
@@ -400,7 +436,17 @@ export function TreeListItem({
       aria-expanded={hasChildren ? isExpanded : undefined}
       aria-selected={isSelected || undefined}
       aria-disabled={isDisabled || undefined}
-      {...stylex.props(styles.wrapper)}>
+      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)}>
       <div {...stylex.props(styles.treeBranches)}>
         <TreeListBranches
           ancestorsIsLast={ancestorsIsLast}

package/src/TreeList/treeListItem.markers.stylex.ts

@@ -0,0 +1,20 @@
+// 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: ReturnType<typeof stylex.defineMarker> =
+  stylex.defineMarker();

package/src/Typeahead/BaseTypeahead.tsx

@@ -29,6 +29,7 @@ import React, {
 import * as stylex from '@stylexjs/stylex';
 import type {StyleXStyles} from '@stylexjs/stylex';
 import {usePopover} from '../Popover/usePopover';
+import {useAnnounce} from '../hooks/useAnnounce';
 import {TypeaheadItem} from './TypeaheadItem';
 import {Icon} from '../Icon';
 import {
@@ -48,9 +49,10 @@ import {themeProps} from '../utils/themeProps';
 // Types
 // =============================================================================
 
-export interface BaseTypeaheadProps<
-  T extends SearchableItem,
-> extends Omit<BaseProps<HTMLElement>, 'onChange'> {
+export interface BaseTypeaheadProps<T extends SearchableItem> extends Omit<
+  BaseProps<HTMLElement>,
+  'onChange'
+> {
   ref?: React.Ref<HTMLInputElement>;
   /**
    * Search source providing items.
@@ -101,6 +103,16 @@ export interface BaseTypeaheadProps<
    */
   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
@@ -134,6 +146,11 @@ export interface BaseTypeaheadProps<
    */
   ariaDescribedBy?: string;
 
+  /**
+   * Additional aria-labelledby IDs.
+   */
+  ariaLabelledBy?: string;
+
   /**
    * Additional StyleX styles for the input element.
    */
@@ -280,9 +297,7 @@ const itemSizeStyles = stylex.create({
  * />
  * ```
  */
-export const BaseTypeahead = function BaseTypeahead<
-  T extends SearchableItem,
->({
+export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({
   searchSource,
   value,
   onChange,
@@ -292,11 +307,13 @@ export const BaseTypeahead = function BaseTypeahead<
   maxMenuItems = 10,
   emptySearchResultsText = 'No results found',
   isDisabled = false,
+  isFocusableDisabled = false,
   hasAutoFocus = false,
   onChangeQuery,
   onOpenChange,
   inputId: externalInputId,
   ariaDescribedBy,
+  ariaLabelledBy,
   inputXStyle,
   anchorRef,
   onKeyDown: externalOnKeyDown,
@@ -311,6 +328,11 @@ export const BaseTypeahead = function BaseTypeahead<
   const inputRef = useRef<HTMLInputElement>(null);
   const fallbackAnchorRef = useRef<HTMLInputElement>(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<T[]>([]);
   const [highlightedIndex, setHighlightedIndex] = useState(-1);
@@ -353,6 +375,9 @@ export const BaseTypeahead = function BaseTypeahead<
     hasLightDismiss: true,
     hasCloseButton: 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.
@@ -394,11 +419,21 @@ 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;
@@ -411,7 +446,7 @@ export const BaseTypeahead = function BaseTypeahead<
         }
       }
     },
-    [searchSource, maxMenuItems, showLayer],
+    [searchSource, maxMenuItems, showLayer, announce, emptySearchResultsText],
   );
 
   // Perform bootstrap
@@ -456,6 +491,8 @@ export const BaseTypeahead = function BaseTypeahead<
         searchSource.cancel?.();
         setResults([]);
         setHasSearched(false);
+        // Clear any lingering result-count / no-results announcement.
+        announce('');
         popover.hide();
         return;
       }
@@ -482,6 +519,7 @@ export const BaseTypeahead = function BaseTypeahead<
       popover,
       debounceMs,
       searchSource,
+      announce,
     ],
   );
 
@@ -539,6 +577,32 @@ export const BaseTypeahead = function BaseTypeahead<
     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: React.FocusEvent<HTMLInputElement>) => {
+      if (!popover.isOpen) {
+        return;
+      }
+      const next = e.relatedTarget as Node | null;
+      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: React.KeyboardEvent<HTMLInputElement>) => {
@@ -615,6 +679,19 @@ export const BaseTypeahead = function BaseTypeahead<
     [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));
 
@@ -644,6 +721,8 @@ export const BaseTypeahead = function BaseTypeahead<
         }
         aria-autocomplete="list"
         aria-describedby={ariaDescribedBy}
+        aria-labelledby={ariaLabelledBy}
+        aria-disabled={isFocusableDisabled ? 'true' : undefined}
         value={query}
         onChange={handleInputChange}
         onPointerDown={() => {
@@ -657,9 +736,14 @@ export const BaseTypeahead = function BaseTypeahead<
           );
         }}
         onFocus={handleFocus}
+        onBlur={handleBlur}
         onKeyDown={handleKeyDown}
         placeholder={placeholder}
-        disabled={isDisabled}
+        // 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/src/Typeahead/Typeahead.doc.mjs

@@ -7,8 +7,21 @@ export const docs = {
   displayName: 'Typeahead',
   group: 'Typeahead',
   category: 'Data Input',
-  keywords: ["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],
-  description: 'Styled typeahead with label, description, validation, and all field features. Wraps BaseTypeahead with Field for the primary use case.',
+  keywords: [
+    'typeahead',
+    'autocomplete',
+    'combobox',
+    'searchbox',
+    'autosuggest',
+    'select',
+    'dropdown',
+    'lookup',
+    'searchable',
+    'suggestion',
+    'picker',
+  ],
+  description:
+    'Styled typeahead with label, description, validation, and all field features. Wraps BaseTypeahead with Field for the primary use case.',
   props: [
     {
       name: 'label',
@@ -19,7 +32,8 @@ export const docs = {
     {
       name: 'searchSource',
       type: 'SearchSource<T>',
-      description: 'Data source providing search and bootstrap methods for populating the dropdown.',
+      description:
+        'Data source providing search and bootstrap methods for populating the dropdown.',
       required: true,
     },
     {
@@ -57,6 +71,12 @@ export const docs = {
       description: 'Disables the input.',
       default: 'false',
     },
+    {
+      name: 'disabledMessage',
+      type: 'string',
+      description:
+        'Explains why the input is disabled. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the field focusable via aria-disabled (activation stays blocked). Use this instead of wrapping a disabled Typeahead in Tooltip — disabled controls swallow the hover events an external Tooltip needs.',
+    },
     {
       name: 'maxMenuItems',
       type: 'number',
@@ -66,12 +86,14 @@ export const docs = {
     {
       name: 'status',
       type: 'InputStatus',
-      description: 'Validation status object with type and message for error/warning/success states.',
+      description:
+        'Validation status object with type and message for error/warning/success states.',
     },
     {
       name: 'renderItem',
       type: '(item: T) => ReactNode',
-      description: 'Custom render function for dropdown items. Default renders TypeaheadItem.',
+      description:
+        'Custom render function for dropdown items. Default renders TypeaheadItem.',
     },
     {
       name: 'isLabelHidden',
@@ -122,7 +144,8 @@ 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',
     },
     {
@@ -138,13 +161,11 @@ export const docs = {
     {
       name: 'xstyle',
       type: 'StyleXStyles',
-      description: 'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
+      description:
+        'StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value: not an inline style object like style={{}}.',
     },
   ],
-  components: [
-    {name: 'BaseTypeahead'},
-    {name: 'TypeaheadItem'},
-  ],
+  components: [{name: 'BaseTypeahead'}, {name: 'TypeaheadItem'}],
   theming: {
     targets: [
       {className: 'astryx-typeahead', visualProps: ['status']},
@@ -156,12 +177,45 @@ export const docs = {
     description:
       'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
     bestPractices: [
-      {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
-      {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
-      {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
-      {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},
-      {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},
-      {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
+      {
+        guidance: true,
+        description:
+          'Provide descriptive placeholder text that hints at what users can search for.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show suggestions on focus when users benefit from seeing popular or recent options before typing.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a search delay for remote data sources to avoid excessive network requests.',
+      },
+      {
+        guidance: true,
+        description:
+          'Use inside InputGroup when the typeahead needs a single-line prefix or suffix addon.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for short, static option lists; use Selector for better discoverability.',
+      },
+      {
+        guidance: false,
+        description: 'Use for multi-selection; use Tokenizer instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled Typeahead in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
@@ -172,29 +226,86 @@ export const docsZh = {
     description:
       'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
     bestPractices: [
-      {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
-      {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
-      {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
-      {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},
-      {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},
-      {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
+      {
+        guidance: true,
+        description:
+          'Provide descriptive placeholder text that hints at what users can search for.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show suggestions on focus when users benefit from seeing popular or recent options before typing.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a search delay for remote data sources to avoid excessive network requests.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for short, static option lists; use Selector for better discoverability.',
+      },
+      {
+        guidance: false,
+        description: 'Use for multi-selection; use Tokenizer instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled Typeahead in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };
 
 /** @type {import('../docs-types').TranslationDoc} */
 export const docsDense = {
-  description: 'Searchable dropdown for single-item selection w/ keyboard navigation. Supports async+sync search via searchSource interface.',
+  description:
+    'Searchable dropdown for single-item selection w/ keyboard navigation. Supports async+sync search via searchSource interface.',
   usage: {
     description:
       'A searchable input for selecting a single item from a large or dynamic dataset. Results appear as the user types, with support for async data sources, debounced search, and custom item rendering. Use it when the option list is too large for a Selector dropdown.',
     bestPractices: [
-      {guidance: true, description: 'Provide descriptive placeholder text that hints at what users can search for.'},
-      {guidance: true, description: 'Show suggestions on focus when users benefit from seeing popular or recent options before typing.'},
-      {guidance: true, description: 'Add a search delay for remote data sources to avoid excessive network requests.'},
-      {guidance: false, description: 'Use for short, static option lists; use Selector for better discoverability.'},
-      {guidance: false, description: 'Use for multi-selection; use Tokenizer instead.'},
-      {guidance: false, description: 'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.'},
+      {
+        guidance: true,
+        description:
+          'Provide descriptive placeholder text that hints at what users can search for.',
+      },
+      {
+        guidance: true,
+        description:
+          'Show suggestions on focus when users benefit from seeing popular or recent options before typing.',
+      },
+      {
+        guidance: true,
+        description:
+          'Add a search delay for remote data sources to avoid excessive network requests.',
+      },
+      {
+        guidance: false,
+        description:
+          'Use for short, static option lists; use Selector for better discoverability.',
+      },
+      {
+        guidance: false,
+        description: 'Use for multi-selection; use Tokenizer instead.',
+      },
+      {
+        guidance: false,
+        description:
+          'Place multiple Typeaheads adjacent to each other without clear labels differentiating them.',
+      },
+      {
+        guidance: false,
+        description:
+          'Wrap a disabled Typeahead in Tooltip to explain why it is disabled; disabled triggers swallow the hover events the wrapper needs. Use the disabledMessage prop instead.',
+      },
     ],
   },
 };