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

package/src/TextArea/TextArea.tsx

@@ -41,7 +41,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Icon, renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -66,6 +65,7 @@ import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 const COUNTER_WARNING_THRESHOLD = 0.8;
 
 const styles = stylex.create({
@@ -304,7 +304,7 @@ export interface TextAreaProps 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;
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is
    * (e.g. `'100%'`). Sizes the whole field (label, control, and status) so they
@@ -691,6 +691,7 @@ export function TextArea({
             {statusIcon}
           </span>
         )}
+        {/* eslint-disable-next-line @astryx/no-nullish-jsx-guard -- `maxLength` is a number; 0 still shows its counter */}
         {maxLength != null && (
           <div
             id={counterID}

package/src/TextInput/TextInput.tsx

@@ -42,7 +42,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {renderIconSlot, type IconType} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -123,6 +122,7 @@ import {useTranslator} from '../i18n';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 export type TextInputType = 'text' | 'password' | 'email';
 
 export interface TextInputProps extends Omit<
@@ -214,7 +214,7 @@ export interface TextInputProps 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;
   /**
    * The size of the input.
    * - 'sm': Compact size (18px height)

package/src/TimeInput/TimeInput.tsx

@@ -45,7 +45,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Icon} from '../Icon';
 import {Spinner} from '../Spinner';
@@ -94,6 +93,7 @@ import {
   type InputPresentation,
 } from '../utils/inputPresentation';
 import {useDevWarning} from '../hooks/useDevWarning';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 const TOUCH_POINTER_QUERY = '(pointer: coarse)';
 
@@ -377,7 +377,7 @@ export interface TimeInputProps 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;
 
   /**
    * Width of the field. Numbers are treated as pixels, strings are used as-is

package/src/Timer/Timer.tsx

@@ -9,7 +9,7 @@
  * @position Core content primitive for elapsed duration in active operations
  *
  * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/Timer/Timer.spec.md
+ * - /docs/specs/components/Timer/Timer.spec.md
  * - /packages/core/src/Timer/Timer.doc.mjs
  * - /packages/core/src/Timer/Timer.test.tsx
  * - /packages/core/src/Timer/index.ts

package/src/Toast/useToast.tsx

@@ -7,6 +7,7 @@ import {createRoot} from 'react-dom/client';
 import {dataAttr} from '../naming';
 import {ToastContext, type ToastContextValue} from './ToastContext';
 import {ToastViewport} from './ToastViewport';
+import {ThemeNestingContext} from '../theme/Theme';
 import {warnOnce} from '../utils/devWarning';
 import type {
   ToastOptions,
@@ -101,10 +102,14 @@ function getFallbackContext(): ToastContextValue {
   };
 
   fallbackRoot = createRoot(container);
+  // This root sits inside the app, so a <Theme> in toast content is nested:
+  // it themes its own subtree and leaves the app's <html> sync alone.
   fallbackRoot.render(
-    <ToastViewport>
-      <FallbackCapture />
-    </ToastViewport>,
+    <ThemeNestingContext value={true}>
+      <ToastViewport>
+        <FallbackCapture />
+      </ToastViewport>
+    </ThemeNestingContext>,
   );
 
   // Proxy that queues calls until real context is captured

package/src/ToggleButton/ToggleButton.tsx

@@ -29,7 +29,7 @@ import {Button, type ButtonSize} from '../Button';
 import type {Elevation} from '../utils/types';
 import {useToggleButtonGroup} from './ToggleButtonGroup';
 import type {BaseProps} from '../BaseProps';
-import {themeProps} from '../utils/themeProps';
+import {themeDataAttributes, themeProps} from '../utils/themeProps';
 import {mergeProps} from '../utils/mergeProps';
 
 // =============================================================================
@@ -319,6 +319,7 @@ export function ToggleButton({
 
   // isIconOnly prop is the source of truth for icon-only rendering.
   const labelContent =
+    // eslint-disable-next-line @astryx/no-nullish-jsx-guard -- switching to isRenderable would show `label` for children of '', false or true, a visible change that needs a decision
     children != null ? (
       <span {...stylex.props(labelStyles.wrapper)}>
         <span {...stylex.props(isPressed && labelStyles.pressed)}>
@@ -352,7 +353,6 @@ export function ToggleButton({
       isLoading={isLoading}
       isInterruptible
       isIconOnly={isIconOnly}
-      aria-pressed={isPressed}
       icon={resolvedIcon}
       tooltip={tooltip}
       {...mergeProps(
@@ -366,7 +366,14 @@ export function ToggleButton({
       style={style}
       onClick={handleClick}
       clickAction={clickAction}
-      {...props}>
+      {...props}
+      // The pressed state this component owns wins over a caller's
+      // same-named attributes (public-component-api INV5).
+      aria-pressed={isPressed}
+      {...themeDataAttributes({
+        isPressed: isPressed ? 'true' : 'false',
+        elevation,
+      })}>
       {labelContent}
     </Button>
   );

package/src/Token/Token.tsx

@@ -299,6 +299,8 @@ export function Token({
   className,
   style,
   'data-testid': testId,
+  'aria-labelledby': ariaLabelledBy,
+  'aria-describedby': ariaDescribedBy,
   ref,
   ...rest
 }: TokenProps) {
@@ -342,6 +344,14 @@ export function Token({
     </>
   );
 
+  // Naming inputs reach the element that owns the token's action: the inner
+  // button of a clickable token, otherwise the root
+  // (architecture:public-component-api INV5).
+  const labellingProps = {
+    'aria-labelledby': ariaLabelledBy,
+    'aria-describedby': ariaDescribedBy,
+  };
+
   const sharedProps = {
     'data-testid': testId,
     ...(isLabelHidden ? {'aria-label': label} : {}),
@@ -380,6 +390,7 @@ export function Token({
           style,
         )}
         {...rest}
+        {...labellingProps}
         {...disabledInteractionProps(rest.onKeyDown)}
         {...sharedProps}>
         {content}
@@ -413,6 +424,7 @@ export function Token({
             style,
           )}
           {...rest}
+          {...labellingProps}
           {...(isDisabled ? {'aria-disabled': true} : {})}
           {...sharedProps}>
           {content}
@@ -466,6 +478,7 @@ export function Token({
           style,
         )}
         {...rest}
+        {...labellingProps}
         {...sharedProps}
       />
     );
@@ -509,6 +522,7 @@ export function Token({
         <button
           type="button"
           onClick={effectiveOnClick}
+          {...labellingProps}
           aria-disabled={isDisabled || undefined}
           {...(isDisabled ? disabledInteractionProps() : null)}
           {...stylex.props(styles.invisibleButton)}>
@@ -546,6 +560,7 @@ export function Token({
         style,
       )}
       {...rest}
+      {...labellingProps}
       {...sharedProps}>
       {content}
     </span>

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -42,7 +42,7 @@ export const docs = {
       name: 'searchSource',
       type: 'SearchSource<T>',
       description:
-        'Data source providing search and bootstrap methods for populating the dropdown.',
+        'Data source providing search and bootstrap methods. `search(query, context)` may call `context.update(items)` to show matches it already has before it returns; the value it returns is the final list, and every list after the first for a query keeps the shown rows first and adds new rows after them.',
       required: true,
     },
     {
@@ -196,7 +196,7 @@ export const docs = {
       name: 'debounceMs',
       type: 'number',
       description:
-        'Debounce delay in ms before triggering search. Set to 0 for synchronous sources.',
+        'Debounce delay in ms before triggering search. Set to 0 for synchronous sources, and for a source that shows local matches through `context.update` and delays its own server request.',
       default: '150',
     },
     {
@@ -266,12 +266,14 @@ export const docs = {
     {
       name: 'containerClassName',
       type: 'string',
-      description: 'Class name for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Class name for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'containerStyle',
       type: 'CSSProperties',
-      description: 'Inline styles for the field container. Same targeting as `containerXstyle`.',
+      description:
+        'Inline styles for the field container. Same targeting as `containerXstyle`.',
     },
     {
       name: 'controlXstyle',
@@ -407,7 +409,7 @@ export const docsZh = {
       name: 'searchSource',
       type: 'SearchSource<T>',
       description:
-        '\u63d0\u4f9b\u641c\u7d22\u548c\u5f15\u5bfc\u65b9\u6cd5\u7684\u6570\u636e\u6e90\uff0c\u7528\u4e8e\u586b\u5145\u4e0b\u62c9\u5217\u8868\u3002',
+        '提供搜索和引导方法的数据源。`search(query, context)` 可调用 `context.update(items)` 先显示已有的匹配项；返回值是最终列表，同一查询在第一个列表之后的每个列表都保留已显示的行，并只在其后追加新行。',
       required: true,
     },
     {
@@ -570,7 +572,7 @@ export const docsZh = {
       name: 'debounceMs',
       type: 'number',
       description:
-        '\u89e6\u53d1\u641c\u7d22\u524d\u7684\u9632\u6296\u5ef6\u8fdf\uff08\u6beb\u79d2\uff09\u3002\u540c\u6b65\u6570\u636e\u6e90\u8bbe\u7f6e\u4e3a 0\u3002',
+        '触发搜索前的防抖延迟（毫秒）。同步数据源，以及通过 `context.update` 显示本地匹配项并自行延迟服务器请求的数据源，设置为 0。',
       default: '150',
     },
     {
@@ -780,10 +782,12 @@ export const docsDense = {
     ],
   },
   propDescriptions: {
-    containerXstyle: 'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
+    containerXstyle:
+      'StyleX styles for the field container; no effect in InputGroup or horizontal-labels FormLayout. No root xstyle/className/style.',
     containerClassName: 'Class name for the field container.',
     containerStyle: 'Inline styles for the field container.',
-    controlXstyle: 'StyleX styles for the visual control box (border, background, icons); not the native input.',
+    controlXstyle:
+      'StyleX styles for the visual control box (border, background, icons); not the native input.',
     controlClassName: 'Class name for the visual control box.',
     controlStyle: 'Inline styles for the visual control box.',
     label: 'Accessible label for input.',

package/src/Tokenizer/Tokenizer.tsx

@@ -69,7 +69,6 @@ import {
   inputStatusBorderStyles,
   inputStatusHoverShadowStyles,
   inputStatusFocusWithinStyles,
-  type FieldStatusVariant,
 } from '../Field';
 import {Token} from '../Token';
 import {Spinner} from '../Spinner';
@@ -85,12 +84,19 @@ import {
   sizeVars,
   typeScaleVars,
 } from '../theme/tokens.stylex';
-import type {SearchableItem, SearchSource} from '../Typeahead/types';
+import type {
+  SearchContext,
+  SearchableItem,
+  SearchSource,
+} from '../Typeahead/types';
 import {composeEventHandlers, mergeProps} from '../utils';
 import {joinAriaIDs} from '../utils/inputAria';
+import {isFocusDetached} from '../utils/focusReturn';
 import {themeProps} from '../utils/themeProps';
 import {useTranslator} from '../i18n';
 import type {TokenizerBottomSheetProps} from './TokenizerBottomSheet';
+import {useResolvedRequired} from '../hooks/useResolvedRequired';
+import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
 
 // Re-export status types for convenience
 export type {
@@ -192,7 +198,7 @@ export interface TokenizerProps<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.
@@ -760,6 +766,7 @@ export function Tokenizer<T extends SearchableItem>({
   'aria-labelledby': ariaLabelledByProp,
   ...restProps
 }: TokenizerWithPresentationProps<T>): React.JSX.Element {
+  const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {
     containerXstyle,
     containerClassName,
@@ -821,14 +828,6 @@ export function Tokenizer<T extends SearchableItem>({
     },
     [onChangeQuery],
   );
-  // Whether the field's control — the inline input or the trigger — holds
-  // focus. Kept in a ref by the focus and blur handlers of both, because a
-  // control unmounted while focused fires no blur: when a presentation swap
-  // removes the focused control (the latch releasing into the popover, or
-  // `adaptive` changing while the sheet is closed), the new presentation's
-  // control takes the focus over once it has mounted, so focus never lands on
-  // the page body (`component:Tokenizer` FR16, `spec:AST-085` FR4).
-  const isControlFocusedRef = useRef(false);
   // Set around a focus move the field makes itself — a presentation swap
   // handing focus from one control to the other — so the receiving control
   // does not report it as focus entering from outside.
@@ -839,38 +838,33 @@ export function Tokenizer<T extends SearchableItem>({
   // entry, and the one focus the trigger then gets — BottomSheet's return
   // focus — is the entry to report.
   const hasReportedFocusRef = useRef(false);
-  // A control can hold focus without the field having seen a focus event:
-  // the inline input server-rendered with `autofocus` (`hasAutoFocus`) is
-  // focused before hydration, and the swap to the trigger in the first
-  // render after it removes that input. React detaches the old control
-  // before any effect of the swapping commit runs, so the live focus is
-  // read during that render, while the control is still in the document —
-  // a read of `document.activeElement` only, with no update made in render.
-  const previousPresentationRef = useRef(isSheetPresentation);
-  if (previousPresentationRef.current !== isSheetPresentation) {
-    previousPresentationRef.current = isSheetPresentation;
-    if (typeof document !== 'undefined') {
-      const active = document.activeElement;
-      if (
-        active != null &&
-        (active === inputRef.current || active === triggerRef.current)
-      ) {
-        isControlFocusedRef.current = true;
-      }
-    }
-  }
-  useEffect(() => {
-    if (!isControlFocusedRef.current) {
+  // When a presentation swap removes the focused control (the latch
+  // releasing into the popover, or `adaptive` changing while the sheet is
+  // closed), the new presentation's control takes the focus over, so focus
+  // never lands on the page body (`component:Tokenizer` FR16, `spec:AST-085`
+  // FR4). Both controls' callback refs own the hand-off
+  // (`architecture:react-component-runtime` INV6): the detaching control
+  // notes that it held focus — it is still in the document then, so this also
+  // covers a control focused before hydration (`hasAutoFocus`), which no focus
+  // event reported — and the attaching control takes it.
+  const isFocusPendingHandOffRef = useRef(false);
+  const handOffFocusRef = useCallback((node: HTMLElement | null) => {
+    if (node == null) {
       return;
     }
-    const active = document.activeElement;
-    if (active != null && active !== document.body) {
-      return;
+    const takesFocus = isFocusPendingHandOffRef.current;
+    isFocusPendingHandOffRef.current = false;
+    if (takesFocus && isFocusDetached(node.ownerDocument)) {
+      isHandingOffFocusRef.current = true;
+      node.focus();
+      isHandingOffFocusRef.current = false;
     }
-    isHandingOffFocusRef.current = true;
-    (isSheetPresentation ? triggerRef.current : inputRef.current)?.focus();
-    isHandingOffFocusRef.current = false;
-  }, [isSheetPresentation]);
+    return () => {
+      if (node.ownerDocument.activeElement === node) {
+        isFocusPendingHandOffRef.current = true;
+      }
+    };
+  }, []);
   // The trigger's accessible description names the selected tokens: the
   // button's children are tokens whose own content assistive technology
   // leaves out of a button's name (`spec:AST-020` FR1).
@@ -945,6 +939,29 @@ export function Tokenizer<T extends SearchableItem>({
     focusTrigger: 'always',
     isEnabled: showsDisabledMessage,
   });
+  // The inline field's wrapper holds every control a swap removes with the
+  // input — a token's Remove button, the inline Clear all — so it notes focus
+  // anywhere inside it for the hand-off above. It also anchors the
+  // disabled-message tooltip, whose handlers are gated internally by
+  // isEnabled, so attaching unconditionally is safe.
+  const tooltipAnchorRef = disabledMessageTooltip.ref;
+  const wrapperCallbackRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      wrapperRef.current = el;
+      tooltipAnchorRef(el);
+      if (el == null) {
+        return;
+      }
+      return () => {
+        if (el.contains(el.ownerDocument.activeElement)) {
+          isFocusPendingHandOffRef.current = true;
+        }
+        wrapperRef.current = null;
+        tooltipAnchorRef(null);
+      };
+    },
+    [tooltipAnchorRef],
+  );
 
   // The sheet presentation has no input; the public ref reaches the trigger,
   // the control it stands for (`family:input-fields` FR10).
@@ -952,6 +969,7 @@ export function Tokenizer<T extends SearchableItem>({
     triggerRef,
     ref as React.Ref<HTMLButtonElement> | undefined,
     disabledMessageTooltip.ref,
+    handOffFocusRef,
   );
 
   useImperativeHandle(handleRef, () => ({
@@ -1032,7 +1050,6 @@ export function Tokenizer<T extends SearchableItem>({
         layer.show();
       }
       if (comingFromOutside) {
-        isControlFocusedRef.current = true;
         if (!isHandingOffFocusRef.current) {
           hasReportedFocusRef.current = true;
           onFocus?.(e);
@@ -1050,8 +1067,9 @@ export function Tokenizer<T extends SearchableItem>({
   const handleBlurCapture = useCallback(
     (e: React.FocusEvent) => {
       if (!isFocusInTokenizer(e.relatedTarget)) {
-        isControlFocusedRef.current = false;
         hasReportedFocusRef.current = false;
+        // Focus left the field: no hand-off is owed any more.
+        isFocusPendingHandOffRef.current = false;
         setIsFocusedWithin(false);
         onBlur?.(e);
         if (isLayerMode) {
@@ -1084,8 +1102,16 @@ export function Tokenizer<T extends SearchableItem>({
 
   const filteredSource: SearchSource<T> = useMemo(
     () => ({
-      search: async (query: string) => {
-        const results = await searchSource.search(query);
+      // Committed values leave every list, partial or final
+      // (component:Tokenizer FR13, spec:AST-092 FR1).
+      search: async (query: string, context?: SearchContext<T>) => {
+        const results = await searchSource.search(
+          query,
+          context && {
+            update: items =>
+              context.update(items.filter(item => !selectedIds.has(item.id))),
+          },
+        );
         return results.filter(item => !selectedIds.has(item.id));
       },
       bootstrap: async () => {
@@ -1325,13 +1351,7 @@ export function Tokenizer<T extends SearchableItem>({
 
   const wrapperContent = (
     <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);
-      }}
+      ref={wrapperCallbackRef}
       role="group"
       aria-label={label}
       onClick={handleWrapperClick}
@@ -1397,6 +1417,7 @@ export function Tokenizer<T extends SearchableItem>({
               // With `experimental`, the ref type admits the trigger too; in
               // this presentation it receives the input.
               ref as React.Ref<HTMLInputElement> | undefined,
+              handOffFocusRef,
             )}
             searchSource={isAtMax ? emptySource : filteredSource}
             value={null}
@@ -1421,6 +1442,14 @@ export function Tokenizer<T extends SearchableItem>({
                 .join(' ') || undefined
             }
             onChangeQuery={onChangeQuery}
+            // 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']}
             __queryEntries={createEntries}
             debounceMs={debounceMs}
             onKeyDown={handleKeyDown}
@@ -1523,7 +1552,6 @@ export function Tokenizer<T extends SearchableItem>({
               React.MouseEventHandler<HTMLButtonElement> | undefined,
           )}
           onFocus={event => {
-            isControlFocusedRef.current = true;
             // BottomSheet focuses the trigger only after its exit completes;
             // that focus is the signal that the retained sheet can leave. If
             // the resolution moved to the popover meanwhile, the inline input
@@ -1552,8 +1580,8 @@ export function Tokenizer<T extends SearchableItem>({
             if (isSheetOpen) {
               return;
             }
-            isControlFocusedRef.current = false;
             hasReportedFocusRef.current = false;
+            isFocusPendingHandOffRef.current = false;
             onBlur?.(event);
           }}
           onKeyDown={onKeyDown}

package/src/Tokenizer/TokenizerBottomSheet.tsx

@@ -23,7 +23,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Tokenizer/Tokenizer.tsx (the trigger and the lazy host)
- * - /packages/core/src/Tokenizer/Tokenizer.spec.md (FR16–FR24, AR6, PR6)
+ * - /docs/specs/components/Tokenizer/Tokenizer.spec.md (FR16–FR24, AR6, PR6)
  */
 
 import {
@@ -35,6 +35,7 @@ import {
   type ReactNode,
   type RefObject,
 } from 'react';
+import {flushSync} from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import {AlertDialog} from '../AlertDialog/AlertDialog';
 import {BottomSheet} from '../BottomSheet/BottomSheet';
@@ -328,8 +329,9 @@ function TokenizerSheetContent<T extends SearchableItem>({
   // trigger's press — so an open sheet with no confirmation pending carries
   // no closed dialog (`architecture:component-style-authoring` INV7). Dialog
   // has an entrance animation and no exit, so a close is its unmount; the
-  // sheet then places focus itself, in the Effect below, once the modal is
-  // gone and the sheet's content can take focus again: on the search field
+  // close handler commits that unmount at once and then places focus itself,
+  // now that the modal is gone and the sheet's content can take focus again
+  // (`architecture:react-component-runtime` INV2): on the search field
   // after a confirmed clear — the clear is spent, and the search field is
   // where the next selection starts (FR24, `spec:AST-085` FR4) — and back on
   // Clear all after a cancel. A confirmed clear is announced there too — a
@@ -341,25 +343,17 @@ function TokenizerSheetContent<T extends SearchableItem>({
   // dialog, so FR14 routes the words into it while the sheet is open.
   const [isClearConfirmationOpen, setIsClearConfirmationOpen] = useState(false);
   const clearAllRef = useRef<HTMLButtonElement>(null);
-  const afterConfirmationRef = useRef<'search' | 'clear-all' | null>(null);
   const announce = useAnnounce();
   const closeClearConfirmation = (confirmed: boolean) => {
-    afterConfirmationRef.current = confirmed ? 'search' : 'clear-all';
-    setIsClearConfirmationOpen(false);
-  };
-  useEffect(() => {
-    if (isClearConfirmationOpen || afterConfirmationRef.current == null) {
-      return;
-    }
-    const destination = afterConfirmationRef.current;
-    afterConfirmationRef.current = null;
-    if (destination === 'search') {
+    // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the confirmation must be gone before focus moves into the sheet and the words are routed into it
+    flushSync(() => setIsClearConfirmationOpen(false));
+    if (confirmed) {
       searchRef.current?.focus();
       announce(t('@astryx.tokenizer.allRemoved'));
     } else {
       clearAllRef.current?.focus();
     }
-  }, [announce, isClearConfirmationOpen, t]);
+  };
   const selectedIds = useMemo(() => new Set(value.map(v => v.id)), [value]);
 
   // ---- sheet session ----

package/src/Tooltip/Tooltip.doc.mjs

@@ -84,7 +84,7 @@ export const docs = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',
+            'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (a button, link, or form control), whose tap belongs to the control; an aria-disabled control performs none, so a tap on it opens its reason. tap always opens; use it for an info icon rendered as a button, whose only job is to reveal the tooltip. none never opens on touch.',
           default: "'auto'",
         },
         {
@@ -197,7 +197,7 @@ export const docsZh = {
           name: 'touchTrigger',
           type: "'auto' | 'tap' | 'none'",
           description:
-            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。',
+            '在没有悬停的触摸设备上，轻点的行为。auto：轻点即打开，除非触发元素本身会执行操作（按钮、链接、表单控件），此时轻点归该控件所有；设置了 aria-disabled 的控件不执行操作，因此轻点它会显示其原因。tap：始终轻点打开——适用于以按钮形式呈现、唯一作用就是显示工具提示的信息图标。none：触摸永不打开。',
           default: "'auto'",
         },
         {
@@ -274,7 +274,7 @@ export const docsDense = {
         delay: 'Show delay in ms.',
         hideDelay: 'Hide delay in ms.',
         focusTrigger: 'Controls when focus events trigger tooltip.',
-        touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control); tap = always opens (info icon rendered as a button); none = never on touch.',
+        touchTrigger: 'Tap behavior where there is no hover. auto = tap opens unless the trigger acts (button/link/control; an aria-disabled control does not act); tap = always opens (info icon rendered as a button); none = never on touch.',
         isEnabled: 'Enables/disables tooltip triggers.',
         onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
         hasHoverIndication: 'Dashed underline on trigger element.',

package/src/Tooltip/useTooltip.doc.mjs

@@ -12,7 +12,7 @@ export const docs = {
     {name: 'delay', type: 'number', description: 'Delay before showing on hover, in milliseconds.', default: '200'},
     {name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '0'},
     {name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the tooltip. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
-    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own; tap always opens (an info icon rendered as a button); none never opens on touch.', default: "'auto'"},
+    {name: 'touchTrigger', type: "'auto' | 'tap' | 'none'", description: 'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens (an info icon rendered as a button); none never opens on touch.', default: "'auto'"},
     {name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
     {name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
     {name: 'isDefaultOpen', type: 'boolean', description: 'Whether the tooltip should be shown on mount.', default: 'false'},