@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/Typeahead/Typeahead.tsx

@@ -46,7 +46,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {useTooltip} from '../Tooltip';
@@ -76,6 +75,8 @@ import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 export type {
   InputStatus as TypeaheadStatus,
   InputStatusType as TypeaheadStatusType,
@@ -115,7 +116,7 @@ export interface TypeaheadProps<T extends SearchableItem> extends Omit<
    * - 'tooltip': no message box; the status icon becomes a focusable info-tip button that reveals the message on hover, keyboard focus, or tap
    * @default 'attached'
    */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /**
    * Icon to display at the start of the input.
    * Accepts a ReactNode (e.g. `<Icon icon={SearchIcon} />`) or an SVG icon component directly.
@@ -420,6 +421,7 @@ export function Typeahead<T extends SearchableItem>({
   'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TypeaheadProps<T>) {
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Typeahead', restProps, {
     containerXstyle,
     containerClassName,
@@ -431,6 +433,7 @@ export function Typeahead<T extends SearchableItem>({
   const inputId = idProp ?? generatedInputId;
   const inputLabelId = useId();
   const fieldLabelId = useId();
+  const tokenValueId = useId();
   const descriptionId = useId();
   const statusMessageId = useId();
   const inputGroup = useInputGroup();
@@ -663,14 +666,33 @@ export function Typeahead<T extends SearchableItem>({
         <BusyIndicatorLaneProvider value={busyLane}>
           <div {...stylex.props(styles.contentLane)}>
             {showToken && (
-              <Token
-                ref={tokenRef}
-                label={value.label}
-                size={size}
-                onClick={handleEnterEditMode}
-                isDisabled={isDisabled}
-                xstyle={styles.tokenOverlay}
-              />
+              <>
+                {/* The token's button is the field's Tab stop while a value
+                    shows, so it is named as the input is (the field label,
+                    with a caller aria-labelledby) plus the value, and
+                    described like the input (input-fields FR10; WCAG 2.4.6,
+                    4.1.2). */}
+                <span id={tokenValueId} hidden>
+                  {value.label}
+                </span>
+                <Token
+                  ref={tokenRef}
+                  label={value.label}
+                  size={size}
+                  onClick={handleEnterEditMode}
+                  isDisabled={isDisabled}
+                  aria-labelledby={joinAriaIDs(
+                    inputLabelledBy ?? fieldLabelId,
+                    tokenValueId,
+                  )}
+                  aria-describedby={
+                    [ariaDescribedByProp, ariaDescribedBy]
+                      .filter(Boolean)
+                      .join(' ') || undefined
+                  }
+                  xstyle={styles.tokenOverlay}
+                />
+              </>
             )}
             <TrailingKeyDownContext value={onKeyDown}>
               <BaseTypeahead
@@ -695,6 +717,14 @@ export function Typeahead<T extends SearchableItem>({
                     .join(' ') || undefined
                 }
                 ariaLabelledBy={inputLabelledBy}
+                // The resolved required state reaches the combobox, also when a
+                // FormLayout default hides the visible marker (component:FormLayout
+                // FR5, AR2).
+                aria-required={isEffectivelyRequired || rest['aria-required']}
+                // An error status is exposed on the combobox as on every other field
+                // (WCAG 4.1.2; spec:AST-020 FR9). Without one, a caller's own
+                // aria-required / aria-invalid still applies.
+                aria-invalid={status?.type === 'error' || rest['aria-invalid']}
                 onChangeQuery={onChangeQuery}
                 onOpenChange={onOpenChange}
                 debounceMs={debounceMs}
@@ -745,7 +775,8 @@ export function Typeahead<T extends SearchableItem>({
       isLabelHidden={isLabelHidden}
       description={description}
       inputID={inputId}
-      labelID={ariaLabelledByProp != null ? fieldLabelId : undefined}
+      // Always set: the value token's name references the field label.
+      labelID={fieldLabelId}
       descriptionID={description ? descriptionId : undefined}
       isOptional={isOptional}
       isRequired={isRequired}

package/src/Typeahead/TypeaheadItem.doc.mjs

@@ -6,7 +6,8 @@ export const docs = {
   name: 'TypeaheadItem',
   subComponentOf: 'Typeahead',
   displayName: 'Typeahead Item',
-  description: 'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',
+  description:
+    'Default dropdown item renderer for typeahead results. Shows label with optional icon, description, and avatar. Exported for use in custom renderItem implementations.',
   props: [
     {
       name: 'item',
@@ -50,7 +51,8 @@ export const docs = {
 export const docsZh = {
   name: 'TypeaheadItem',
   displayName: 'Typeahead Item',
-  description: '预输入结果的默认下拉项渲染器。显示标签以及可选的图标、描述和头像。导出供自定义 renderItem 实现使用。',
+  description:
+    '预输入结果的默认下拉项渲染器。显示标签以及可选的图标、描述和头像。导出供自定义 renderItem 实现使用。',
   props: [
     {
       name: 'item',
@@ -85,7 +87,8 @@ export const docsZh = {
 export const docsDense = {
   name: 'TypeaheadItem',
   displayName: 'Typeahead Item',
-  description: 'Default dropdown item renderer. Label w/ optional icon, description, avatar. Exported for custom renderItem.',
+  description:
+    'Default dropdown item renderer. Label w/ optional icon, description, avatar. Exported for custom renderItem.',
   propDescriptions: {
     item: 'Search result item to render.',
     icon: 'Icon/avatar before label.',

package/src/Typeahead/index.ts

@@ -12,7 +12,7 @@
  */
 
 // Shared types
-export type {SearchableItem, SearchSource} from './types';
+export type {SearchableItem, SearchContext, SearchSource} from './types';
 
 // Search source utilities
 export {createStaticSource} from './createStaticSource';

package/src/Typeahead/types.ts

@@ -60,6 +60,25 @@ export interface SearchableItem<TAuxData = unknown> {
   auxiliaryData?: TAuxData;
 }
 
+/**
+ * Per-call context a typeahead passes as the second argument of
+ * `SearchSource.search` (`spec:AST-092`).
+ */
+export interface SearchContext<T extends SearchableItem = SearchableItem> {
+  /**
+   * Show a list for this query before `search()` settles, such as matches the
+   * page already holds while the server is still answering.
+   *
+   * Every list is the source's complete answer at that moment. The first list
+   * shown for a query may replace the rows; every later list for the same
+   * query, including the value `search()` returns, keeps the rows already
+   * shown first and in order and adds new rows only after them. An empty list
+   * leaves the shown rows in place. Calls for a query that is no longer
+   * current, or after `search()` settles, are ignored.
+   */
+  update(items: T[]): void;
+}
+
 /**
  * Search source interface for providing items to typeahead components.
  * Supports both synchronous and asynchronous search.
@@ -93,13 +112,18 @@ export interface SearchableItem<TAuxData = unknown> {
  */
 export interface SearchSource<T extends SearchableItem = SearchableItem> {
   /**
-   * Called on query change. Returns matching items.
-   * Can be synchronous or asynchronous.
+   * Called on query change. Returns matching items: the final, complete list
+   * for the query. Can be synchronous or asynchronous.
+   *
+   * A typeahead that can show partial lists passes `context`; call
+   * `context.update(items)` to show a list before returning, for example local
+   * matches first and the server's answer appended after them. Callers that
+   * cannot show partial lists omit `context` and show only the return value.
    *
    * For expensive operations (API calls, large datasets), consider caching
    * results internally to avoid redundant work on repeated queries.
    */
-  search(query: string): Promise<T[]> | T[];
+  search(query: string, context?: SearchContext<T>): Promise<T[]> | T[];
 
   /**
    * Called on init/focus. Returns initial/default items.

package/src/gestures/haptics.ts

@@ -38,6 +38,7 @@ import {
   HAPTIC_VIBRATION_PATTERNS,
   type HapticFeedbackKind,
 } from '../motion/uikit/gestures';
+import {isDisabledControl} from '../utils/pressDisabled';
 
 /** Marks the hidden switch, so click handlers can recognize and ignore it. */
 export const HAPTIC_SWITCH_ATTRIBUTE = 'data-astryx-haptic-switch';
@@ -79,14 +80,6 @@ const VISUALLY_HIDDEN =
 
 let nextLabelId = 0;
 
-/** A native disabled control, or one marked `aria-disabled`. */
-function isDisabledControl(control: HTMLElement): boolean {
-  return (
-    control.matches(':disabled') ||
-    control.getAttribute('aria-disabled') === 'true'
-  );
-}
-
 /** Whether `input` is a switch checkbox, which plays the tap haptic itself. */
 function isSwitch(input: HTMLInputElement): boolean {
   return input.type === 'checkbox' && input.hasAttribute('switch');

package/src/hooks/menuPressMarker.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file menuPressMarker.ts
+ * @input None (a plain attribute-name constant)
+ * @output Exports MENU_PRESS_MARKER
+ * @position Dependency-free home of the public menu-press marker, so the press
+ *   feedback controller (utils/pressFeedback.ts) can read it without loading
+ *   the menu-press hook into every pressable component's bundle.
+ *   useMenuPress.ts re-exports it; the public path stays
+ *   `@astryxdesign/core/hooks`.
+ */
+
+/** Marks a menu root that carries the menu press model (useMenuPress). */
+export const MENU_PRESS_MARKER = 'data-astryx-menu-press';

package/src/hooks/useClickableContainer.ts

@@ -5,7 +5,8 @@
 /**
  * @file useClickableContainer.ts
  * @input Container ref, interactive element ref, click/href handlers
- * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list
+ * @output onClick and onMouseUp handlers for the container; INTERACTIVE_SELECTORS list;
+ *   hasInteractiveAncestor and the shared innermostInteractive walk
  * @position Core hook for clickable containers that safely handle nested interactive elements
  *
  * Solves the "nested interactive elements" problem: when a card is clickable
@@ -23,6 +24,13 @@
 import {useCallback, useEffect, type RefObject, type MouseEvent} from 'react';
 import {isSafeUrl} from '../utils/safeUrl';
 
+/**
+ * The attribute this hook sets on the container it makes clickable. A click
+ * inside a nested marked container belongs to that container (see
+ * INTERACTIVE_SELECTORS).
+ */
+export const PRESSABLE_CONTAINER_ATTRIBUTE = 'data-pressable-container';
+
 /**
  * Canonical list of interactive element selectors — native controls plus
  * role-based interactive elements. Clicks on these (or their descendants)
@@ -52,15 +60,48 @@ export const INTERACTIVE_SELECTORS = [
   '[role="listbox"]',
   '[role="slider"]',
   '[role="spinbutton"]',
-  '[data-pressable-container]',
+  `[${PRESSABLE_CONTAINER_ATTRIBUTE}]`,
 ].join(',');
 
 const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
 
 /**
- * Check whether an element has an interactive ancestor between it and the root.
- * If the click target is inside a nested button/link/etc., we should NOT
- * handle it at the container level.
+ * Whether this element is interactive by INTERACTIVE_SELECTORS: a control,
+ * link, editor, or nested clickable container, and not marked read-only.
+ */
+export function matchesInteractiveSelectors(element: Element): boolean {
+  return (
+    element.matches(INTERACTIVE_SELECTORS) &&
+    !element.matches(NON_INTERACTIVE_SELECTORS)
+  );
+}
+
+/**
+ * The innermost element, from `el` up to (not including) `rootEl` or the
+ * document body, that `isInteractive` accepts: by default the
+ * INTERACTIVE_SELECTORS match. The one walk every "does this event belong
+ * to a control" check shares; a hover layer's tap passes its own test
+ * (useTouchTrigger's `tapLandsOnDisabledControl`).
+ */
+export function innermostInteractive(
+  el: Element,
+  rootEl: Element | null,
+  isInteractive: (element: Element) => boolean = matchesInteractiveSelectors,
+): Element | null {
+  let current: Element | null = el;
+  while (current != null && current !== rootEl && current !== document.body) {
+    if (isInteractive(current)) {
+      return current;
+    }
+    current = current.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Check whether an element has an interactive ancestor between it and the
+ * root (the element itself included). If the click target is inside a nested
+ * button/link/etc., we should NOT handle it at the container level.
  *
  * Exported for containers that cannot use the hook itself — a `<tr>` whose
  * props are assembled inside a Table plugin's `transformBodyRow`, for
@@ -69,17 +110,7 @@ const NON_INTERACTIVE_SELECTORS = '[aria-readonly="true"]';
  * instead of a short hand-rolled selector list per caller.
  */
 export function hasInteractiveAncestor(el: Element, rootEl: Element): boolean {
-  let current: Element | null = el;
-  while (current != null && current !== rootEl && current !== document.body) {
-    if (
-      current.matches(INTERACTIVE_SELECTORS) &&
-      !current.matches(NON_INTERACTIVE_SELECTORS)
-    ) {
-      return true;
-    }
-    current = current.parentElement;
-  }
-  return false;
+  return innermostInteractive(el, rootEl) != null;
 }
 
 /**
@@ -164,7 +195,7 @@ export function useClickableContainer({
   useEffect(() => {
     const el = containerRef.current;
     if (el) {
-      el.setAttribute('data-pressable-container', 'true');
+      el.setAttribute(PRESSABLE_CONTAINER_ATTRIBUTE, 'true');
     }
   }, [containerRef]);
 

package/src/hooks/useFocusReturnVisibility.ts

@@ -4,35 +4,38 @@
 
 /**
  * @file useFocusReturnVisibility.ts
- * @input Uses the shared interaction-modality tracker
+ * @input The component's shared interaction-modality tracking
  * @output Preserves returned focus while suppressing pointer-only focus rings
  * @position Internal focus-return policy for adaptive overlays
  */
 
 import {useCallback, useState} from 'react';
-import {
-  getInteractionModality,
-  useInteractionModalityTracking,
-} from '../utils/interactionModality';
+import type {InteractionModalityTracking} from '../utils/interactionModality';
 
-export function useFocusReturnVisibility() {
+/**
+ * Pass the component's one modality tracking (its `ref` attached to the
+ * overlay's element or trigger) so the ring follows the last input in that
+ * element's own document (a same-origin iframe, a Document Picture-in-Picture
+ * window), not the page's.
+ */
+export function useFocusReturnVisibility({
+  readModality,
+}: Pick<InteractionModalityTracking, 'readModality'>) {
   const [isFocusRingSuppressed, setIsFocusRingSuppressed] = useState(false);
 
-  useInteractionModalityTracking();
-
   const prepareFocusReturn = useCallback(() => {
-    setIsFocusRingSuppressed(getInteractionModality() === 'pointer');
-  }, []);
+    setIsFocusRingSuppressed(readModality() === 'pointer');
+  }, [readModality]);
 
   const resetFocusReturn = useCallback(() => {
     setIsFocusRingSuppressed(false);
   }, []);
 
   const onFocusReturnTargetFocus = useCallback(() => {
-    if (getInteractionModality() === 'keyboard') {
+    if (readModality() === 'keyboard') {
       setIsFocusRingSuppressed(false);
     }
-  }, []);
+  }, [readModality]);
 
   return {
     isFocusRingSuppressed,

package/src/hooks/useInputStatusIcon.tsx

@@ -36,13 +36,13 @@ import {useCallback, useEffect, useState} from 'react';
 import type {ReactNode} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {Icon, type IconName, type IconSize} from '../Icon';
-import type {FieldStatusVariant} from '../FieldStatus/FieldStatus';
 import type {InputStatus, InputStatusType} from '../Field/types';
 import {useTooltip} from '../Tooltip';
 import {useTranslator} from '../i18n';
 import {radiusVars} from '../theme/tokens.stylex';
 import {themeProps} from '../utils/themeProps';
 import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 /**
  * Maps each status type to its glyph. Shared so every input shows the same icon
@@ -104,7 +104,7 @@ export interface UseInputStatusIconOptions {
   /** The input's status, or undefined when there is none. */
   status?: InputStatus;
   /** How the status is presented relative to the input. */
-  statusVariant?: FieldStatusVariant;
+  statusVariant?: FieldStatusPlacement;
   /** Whether the input is inside an InputGroup (which owns status rendering). */
   isInGroup?: boolean;
   /** Size of the on-field icon. @default 'md' */

package/src/hooks/useListFocus.ts

@@ -121,6 +121,21 @@ export interface UseListFocusOptions {
   hasCaretGuard?: boolean;
 }
 
+/**
+ * Options only Core components pass; this module's internal export, not
+ * re-exported from `hooks/index.ts`, so not public API.
+ */
+export interface InternalListFocusOptions extends UseListFocusOptions {
+  /**
+   * With `hasRovingTabIndex`, keeps one tab stop while every item is disabled:
+   * returns the elements that share it, the stop first. The hook gives the
+   * first `tabindex="0"` and the rest `tabindex="-1"`. For a group that stays
+   * focusable while disabled, so its disabled reason is reachable by keyboard.
+   * Unset (the default): no item holds the stop while every item is disabled.
+   */
+  disabledTabStop?: (list: HTMLElement) => ReadonlyArray<HTMLElement>;
+}
+
 /**
  * Return type for useListFocus hook
  */
@@ -325,6 +340,16 @@ function shouldDeferToCaret(target: EventTarget | null, key: string): boolean {
  */
 export function useListFocus<T extends HTMLElement = HTMLElement>(
   options: UseListFocusOptions = {},
+): UseListFocusReturn<T> {
+  return useInternalListFocus<T>(options);
+}
+
+/**
+ * {@link useListFocus} with the Core-only {@link InternalListFocusOptions}.
+ * Not re-exported from `hooks/index.ts`.
+ */
+export function useInternalListFocus<T extends HTMLElement = HTMLElement>(
+  options: InternalListFocusOptions = {},
 ): UseListFocusReturn<T> {
   const {
     itemSelector = '[role="menuitem"]',
@@ -335,6 +360,7 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
     hasHomeEnd = true,
     hasPaging = false,
     hasRovingTabIndex = false,
+    disabledTabStop,
     hasCaretGuard = false,
   } = options;
 
@@ -462,6 +488,17 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
     const items = getItems();
     const enabled = items.filter(el => !isItemDisabled(el));
     if (enabled.length === 0) {
+      const listEl = listRef.current;
+      if (listEl == null || disabledTabStop == null) {
+        return;
+      }
+      const [stop, ...others] = disabledTabStop(listEl);
+      if (stop != null) {
+        setTabIndex(stop, 0);
+      }
+      for (const el of others) {
+        setTabIndex(el, -1);
+      }
       return;
     }
     const current = enabled.find(el => el.getAttribute('tabindex') === '0');
@@ -469,7 +506,7 @@ export function useListFocus<T extends HTMLElement = HTMLElement>(
     for (const el of items) {
       setTabIndex(el, el === tabbable ? 0 : -1);
     }
-  }, [getItems, isItemDisabled, setTabIndex]);
+  }, [getItems, isItemDisabled, setTabIndex, disabledTabStop]);
 
   // Keep the tab stop valid across renders (items added/removed, disabled
   // toggled). Runs after every commit but only when roving tabindex is on.

package/src/hooks/useMenuPress.ts

@@ -66,13 +66,13 @@ import {
   type MenuPressGesture,
   type MenuPressPointerType,
 } from './menuPressGesture';
+import {MENU_PRESS_MARKER} from './menuPressMarker';
 import {useLongPress, type UseLongPressHandlers} from './useLongPress';
 import {edgeAutoscroll} from '../utils/edgeAutoscroll';
 import {focusForLastInput} from '../utils/focusReturn';
-import {useInteractionModalityTracking} from '../utils/interactionModality';
+import {useInteractionModalityTrackingFor} from '../utils/interactionModality';
 
-/** Marks a menu root that carries this press model. */
-export const MENU_PRESS_MARKER = 'data-astryx-menu-press';
+export {MENU_PRESS_MARKER};
 const MENU_PRESS_ROOT_SELECTOR = `[${MENU_PRESS_MARKER}]`;
 /**
  * Carried by a menu root that another root renders beside itself rather than
@@ -340,8 +340,8 @@ export function useMenuPress(options: UseMenuPressOptions): UseMenuPressReturn {
   const optionsRef = useRef(options);
   optionsRef.current = options;
   // The highlight, and the hover focus of the rows in this menu, follow the
-  // last input, which this tracks for the document.
-  useInteractionModalityTracking();
+  // last input, which this tracks for the menu's own document.
+  useInteractionModalityTrackingFor(options.menuRef);
 
   const gestureRef = useRef<MenuPressGesture<HTMLElement>>(IDLE_MENU_PRESS);
   const pointerIdRef = useRef<number | null>(null);

package/src/hooks/useTreeFocus.doc.mjs

@@ -59,7 +59,7 @@ export const docs = {
     {
       name: 'options.typeahead',
       type: 'boolean',
-      description: 'Whether typeahead (jump to next item whose text starts with the typed characters) is enabled.',
+      description: 'Whether typeahead (jump to next item whose text starts with the typed characters, ignoring case, accents, the stroked letters đ ł ø ħ ŧ ƀ and Turkish ı/İ in every locale) is enabled.',
       default: 'true',
       required: false,
     },
@@ -119,7 +119,7 @@ export const docsDense = {
     'options.onActivate': 'called on Enter/Space activation. Return true when handled; else hook falls back to toggling expansion.',
     'options.onActiveChange': 'notified when focus moves to a treeitem. Use to move a single roving tab stop.',
     'options.hasRovingTabIndex': 'hook owns a single roving tab stop (stamps tabindex 0/-1, repairs on mount, moves w/ nav). Preserves an existing tabindex="0" seed. Attach handleFocus to sync after clicks.',
-    'options.typeahead': 'enable typeahead (jump to next item whose text starts with typed chars).',
+    'options.typeahead': 'enable typeahead (jump to next item whose text starts with typed chars, ignoring case, accents, stroked letters + Turkish ı/İ).',
   },
   returnDescriptions: {
     treeRef: 'ref to attach to tree container (role="tree").',

package/src/hooks/useTreeFocus.ts

@@ -17,6 +17,7 @@
 import {useCallback, useRef} from 'react';
 import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
 import {isRtlElement} from './isRtlElement';
+import {findTypeaheadMatch, nextTypeaheadBuffer} from '../utils/typeaheadMatch';
 
 /** Keys handled by the tree keyboard model (used to gate typeahead). */
 const NAVIGATION_KEYS = new Set([
@@ -427,15 +428,16 @@ export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
       currentIndex: number,
     ): void => {
       const state = typeaheadRef.current;
+      // The same buffer step as useTypeahead: a repeat means "next match", and
+      // a lone combining mark typed first is not a letter to jump to.
+      const nextBuffer = nextTypeaheadBuffer(state.buffer, e.key);
+      if (nextBuffer == null) {
+        return;
+      }
       if (state.timer != null) {
         clearTimeout(state.timer);
       }
-      // "aa" would match nothing; a repeat means "next match" (useTypeahead).
-      const char = e.key.toLowerCase();
-      const isRepeatSameChar =
-        state.buffer.length > 0 &&
-        state.buffer.split('').every(c => c === char);
-      state.buffer = isRepeatSameChar ? char : state.buffer + char;
+      state.buffer = nextBuffer;
       state.timer = setTimeout(() => {
         typeaheadRef.current.buffer = '';
       }, typeaheadResetMs) as unknown as number;
@@ -449,11 +451,15 @@ export function useTreeFocusInternal<T extends HTMLElement = HTMLElement>(
         ...items.slice(start + offset),
         ...items.slice(0, start + offset),
       ];
-      const match = ordered.find(
-        item =>
-          !itemDisabled(item) &&
-          itemLabelText(item, matchLabelledBy).toLowerCase().startsWith(query),
+      const enabled = ordered.filter(item => !itemDisabled(item));
+      // INV17: case, accents, stroked letters and Turkish i fold away, and a
+      // typed mark prefers the exact match.
+      const matchIndex = findTypeaheadMatch(
+        enabled.map((_, i) => i),
+        i => itemLabelText(enabled[i], matchLabelledBy),
+        query,
       );
+      const match = matchIndex >= 0 ? enabled[matchIndex] : undefined;
       if (match != null) {
         e.preventDefault();
         focusItem(match);

package/src/hooks/useTypeahead.doc.mjs

@@ -75,7 +75,7 @@ export const docs = {
   ],
   usage: {
     description:
-      "Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.",
+      "Adds APG type-to-focus search to a collection: printable keystrokes are buffered (resetting after a pause), and the first item whose label starts with the buffer (ignoring case, accents, the stroked letters đ ł ø ħ ŧ ƀ and Turkish ı/İ, the same in every locale; a typed accent prefers the exact match) is reported through onMatch. Pressing the same letter repeatedly cycles through the matches rather than filtering deeper. It moves nothing itself; pair it with the collection's own focus management, most often useListFocus or useGridFocus.",
     bestPractices: [
       {
         guidance: true,
@@ -108,7 +108,7 @@ export const docs = {
 /** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
 export const docsDense = {
   description:
-    'APG type-to-focus search for a collection. Buffers printable keys (resets after pause), matches labels by prefix, reports index via onMatch. Same letter pressed repeatedly cycles matches. Moves nothing itself; pair w/ useListFocus / useGridFocus.',
+    'APG type-to-focus search for a collection. Buffers printable keys (resets after pause), matches labels by prefix ignoring case, accents, stroked letters + Turkish ı/İ in every locale (typed accent prefers exact match), reports index via onMatch. Same letter pressed repeatedly cycles matches. Moves nothing itself; pair w/ useListFocus / useGridFocus.',
   paramDescriptions: {
     options: 'config.',
     'options.getItemLabels':