@astryxdesign/core 0.7.7 → 0.7.8-canary.0588a13

package/src/Toast/ToastViewport.tsx

@@ -21,6 +21,7 @@ import {
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
 } from 'react';
 import type {ReactNode} from 'react';
 import {createPortal} from 'react-dom';
@@ -28,6 +29,11 @@ import * as stylex from '@stylexjs/stylex';
 import {spacingVars, durationVars, easeVars} from '../theme/tokens.stylex';
 import {mergeProps} from '../utils';
 import {getNodeText} from '../utils/getNodeText';
+import {
+  moveFocusLeftBehind,
+  noteFocusWithin,
+  type FocusWithin,
+} from '../utils/focusReturn';
 import {INTERACTIVE_SELECTORS} from '../hooks/useClickableContainer';
 import {useAnnounce} from '../hooks/useAnnounce';
 import {layerTextReset} from '../Layer/layerTextReset.stylex';
@@ -224,6 +230,8 @@ interface ToastRowProps {
   isReversed: boolean;
   onExited: (id: string) => void;
   onDismiss: (id: string, reason: ToastDismissReason) => void;
+  /** Whether the card carries its own live region (see ToastViewport). */
+  isLiveRegion: boolean;
 }
 
 /**
@@ -246,6 +254,7 @@ function ToastRow({
   isReversed,
   onExited,
   onDismiss,
+  isLiveRegion,
 }: ToastRowProps) {
   const o = entry.options;
   const type = o.type ?? 'info';
@@ -296,6 +305,8 @@ function ToastRow({
           gestureDirection={isReversed ? -1 : 1}
           onDismiss={reason => onDismiss(entry.id, reason)}
           renderContent={o.renderContent}
+          timerKey={entry.id}
+          isLiveRegion={isLiveRegion}
         />
       </div>
     </div>
@@ -303,6 +314,9 @@ function ToastRow({
 }
 ToastRow.displayName = 'ToastRow';
 
+const hasActiveModalOutlet = (): boolean => getActiveModalOutlet() != null;
+const hasNoModalOutlet = (): boolean => false;
+
 /**
  * Container that renders and manages toast notifications. Place at the root
  * of your app to enable useToast(). Toasts stack with enter/exit
@@ -363,6 +377,13 @@ export function ToastViewport({
   // The next toast id that should receive focus once the dismissed toast has
   // unmounted, or 'restore' to fall back to the previously-focused element.
   const pendingFocusRef = useRef<string | 'restore' | null>(null);
+  // The id of a toast whose overwrite updated a row that held focus. If the
+  // update removed the focused control, the commit hands focus off.
+  const overwriteFocusRef = useRef<{id: string; note: FocusWithin} | null>(
+    null,
+  );
+  // Where focus was inside a toast whose dismissal hands focus off.
+  const dismissFocusNoteRef = useRef<FocusWithin | null>(null);
 
   // Collect a focusable control within a toast node, if any.
   // Reuses the canonical INTERACTIVE_SELECTORS list (native controls plus
@@ -392,13 +413,9 @@ export function ToastViewport({
     [],
   );
 
-  // Announce toasts through the persistent singleton live regions. Each
-  // <Toast> also renders its own role="status"/"alert" region, but that region
-  // is "born with content" — mounted together with its text — which many
-  // screen readers do not announce (see useAnnounce.ts); the singleton regions
-  // are mounted empty and only mutated afterwards, so they are what actually
-  // guarantees the announcement (the per-toast markup is kept for browse-mode
-  // discoverability). The announcement happens in addToast — the imperative
+  // Announce toasts through the persistent singleton live regions. They are
+  // mounted empty and only mutated afterwards, which screen readers announce
+  // (see useAnnounce.ts). The announcement happens in addToast — the imperative
   // dispatch path invoked once per useToast() call from an event handler,
   // never from render — so each toast is announced exactly once by
   // construction, independent of the React render lifecycle (StrictMode
@@ -406,6 +423,16 @@ export function ToastViewport({
   // re-renders never re-announce). It is client-only (addToast never runs
   // during SSR), so it is SSR-safe.
   const announce = useAnnounce();
+  // An open native modal hides the body-level channel above from assistive
+  // technology, so while the viewport is hosted in one, each card announces
+  // itself through its own live region instead. Outside a modal the cards
+  // carry none, so a card updated in place is announced once.
+  const hasModalOutlet = useSyncExternalStore(
+    subscribeModalOutlets,
+    hasActiveModalOutlet,
+    hasNoModalOutlet,
+  );
+  const isModalHosted = isTopLayer && hasModalOutlet;
 
   const addToast = useCallback(
     (entry: ToastEntry) => {
@@ -441,9 +468,29 @@ export function ToastViewport({
       if (overwritten && renderedToastsRef.current.includes(overwritten)) {
         replacedRef.current.set(overwritten.id, overwritten);
       }
+      // An overwrite of a toast that is not leaving keeps its row, so the card
+      // updates in place and focus inside it stays. A leaving namesake
+      // is replaced by a new row, which enters again.
+      const keepsRow =
+        overwritten != null && !exitingIdsRef.current.has(overwritten.id);
+      const placed: ToastEntry = keepsRow
+        ? {...entry, rowKey: overwritten.rowKey ?? overwritten.id}
+        : entry;
+      if (keepsRow) {
+        // If the update removes the focused control, the commit hands focus
+        // off as a dismissal does.
+        const note = noteFocusWithin(
+          viewportRef.current?.querySelector<HTMLElement>(
+            `[data-toast-id="${overwritten.id}"]`,
+          ),
+        );
+        if (note != null) {
+          overwriteFocusRef.current = {id: placed.id, note};
+        }
+      }
       const projected = overwritten
-        ? committed.map(t => (t === overwritten ? entry : t))
-        : [...committed, entry];
+        ? committed.map(t => (t === overwritten ? placed : t))
+        : [...committed, placed];
       // `maxVisible={0}` shows every toast (FR7): nothing leaves the window.
       const firstVisible = maxVisible > 0 ? projected.length - maxVisible : 0;
       const cutIds = new Set(
@@ -470,7 +517,7 @@ export function ToastViewport({
           }
         }
       }
-      pending.set(entry.id, entry);
+      pending.set(entry.id, placed);
       // An overwrite swaps a new entry, with a new id, into the replaced
       // toast's place, so the old row leaves the DOM without ever being
       // dismissed. Its settled id is dropped by the prune below, which covers
@@ -482,8 +529,8 @@ export function ToastViewport({
         // overwrite into an append. An ignored collision already returned.
         const kept = prev.filter(t => !cutIds.has(t.id));
         return overwritten && kept.includes(overwritten)
-          ? kept.map(t => (t === overwritten ? entry : t))
-          : [...kept, entry];
+          ? kept.map(t => (t === overwritten ? placed : t))
+          : [...kept, placed];
       });
     },
     [announce, maxVisible],
@@ -512,14 +559,23 @@ export function ToastViewport({
     // focused before the user entered the viewport) rather than <body>.
     const el = viewportRef.current;
     const active = document.activeElement;
-    const dismissedNode =
-      el?.querySelector<HTMLElement>(`[data-toast-id="${id}"]`) ?? null;
+    // A toast an overwrite replaced in place no longer owns its row: the
+    // replacement does, so dismissing the replaced toast leaves the row, and
+    // focus in it, to the replacement.
+    const rowKey = entry.rowKey ?? entry.id;
+    const isReplacedInPlace =
+      !toastsRef.current.some(t => t.id === id) &&
+      toastsRef.current.some(t => t.rowKey === rowKey);
+    const dismissedNode = isReplacedInPlace
+      ? null
+      : (el?.querySelector<HTMLElement>(`[data-toast-id="${id}"]`) ?? null);
     if (
       dismissedNode &&
       active instanceof Node &&
       dismissedNode.contains(active)
     ) {
       focusHandoffIdRef.current = id;
+      dismissFocusNoteRef.current = noteFocusWithin(dismissedNode);
       // Pick the toast to receive focus while the DOM is still intact: the
       // nearest one after it, then before it, that shows once it is gone
       // (FR10), else restore. The list may already run ahead of the render
@@ -587,6 +643,41 @@ export function ToastViewport({
     setToasts(prev => prev.filter(t => t.id !== id));
   }, []);
 
+  // Moves focus to a control in the target toast, else in another toast that
+  // shows (newest first), else back to the element focused before focus
+  // entered the viewport, so a handoff never drops focus to <body>.
+  const handOffFocus = useCallback(
+    (note: FocusWithin | null, targetId: string | null) => {
+      const el = viewportRef.current;
+      const rowFor = (id: string) =>
+        el?.querySelector<HTMLElement>(`[data-toast-id="${id}"]`) ?? null;
+      const shownIds = toastsRef.current
+        .slice(maxVisibleRef.current > 0 ? -maxVisibleRef.current : 0)
+        .map(t => t.id)
+        .reverse();
+      const candidates =
+        targetId == null
+          ? []
+          : [targetId, ...shownIds.filter(id => id !== targetId)];
+      let target: HTMLElement | null = null;
+      for (const id of candidates) {
+        target = getFocusable(rowFor(id));
+        if (target != null) {
+          break;
+        }
+      }
+      const prev = prevFocusRef.current;
+      const isReturning = target == null && prev != null && prev.isConnected;
+      if (target == null) {
+        target = isReturning ? prev : el;
+      }
+      if (moveFocusLeftBehind(note, target) && isReturning) {
+        prevFocusRef.current = null;
+      }
+    },
+    [getFocusable],
+  );
+
   // After a dismissed toast unmounts, hand focus off so it never falls to
   // <body>. Runs in a layout effect once the toast list no longer contains
   // the dismissed toast.
@@ -602,27 +693,21 @@ export function ToastViewport({
     }
     focusHandoffIdRef.current = null;
     pendingFocusRef.current = null;
-    const el = viewportRef.current;
-    if (target !== 'restore' && el) {
-      const nextNode = el.querySelector<HTMLElement>(
-        `[data-toast-id="${target}"]`,
-      );
-      const focusable = getFocusable(nextNode) ?? nextNode;
-      if (focusable) {
-        focusable.focus();
-        return;
-      }
-    }
-    // No remaining toast to receive focus — restore the previously-focused
-    // element if it's still connected, else fall back to the container.
-    const prev = prevFocusRef.current;
-    prevFocusRef.current = null;
-    if (prev && prev.isConnected) {
-      prev.focus();
-    } else if (el) {
-      el.focus();
+    const note = dismissFocusNoteRef.current;
+    dismissFocusNoteRef.current = null;
+    handOffFocus(note, target === 'restore' ? null : target);
+  }, [toasts, handOffFocus]);
+
+  // After an overwrite updated a row that held focus: focus stays on the same
+  // control, or, if the update removed it, moves as a dismissal hands it off.
+  useLayoutEffect(() => {
+    const overwrite = overwriteFocusRef.current;
+    if (overwrite == null) {
+      return;
     }
-  }, [toasts, getFocusable]);
+    overwriteFocusRef.current = null;
+    handOffFocus(overwrite.note, overwrite.id);
+  }, [toasts, handOffFocus]);
 
   const findByUniqueID = useCallback((uid: string) => {
     return toastsRef.current.find(t => t.options.uniqueID === uid);
@@ -672,6 +757,8 @@ export function ToastViewport({
     };
   }, [isTopLayer]);
 
+  // Syncs the host's place with the modal outlet registry. The host moves into
+  // the latest open modal, and back when that modal closes.
   useLayoutEffect(() => {
     if (!isTopLayer || host == null) {
       return;
@@ -830,12 +917,13 @@ export function ToastViewport({
       <LayerContentBoundary>
         {visibleToasts.map(entry => (
           <ToastRow
-            key={entry.id}
+            key={entry.rowKey ?? entry.id}
             entry={entry}
             isExiting={exitingIds.has(entry.id)}
             isReversed={isReversed}
             onExited={handleExited}
             onDismiss={removeToast}
+            isLiveRegion={isModalHosted}
           />
         ))}
       </LayerContentBoundary>

package/src/Toast/types.ts

@@ -38,9 +38,10 @@ export interface ToastOptions {
   /**
    * Replaces the content of this toast's card with your own layout.
    *
-   * Astryx keeps the card, live-region role and auto-hide behavior, then hands
-   * the renderer this toast's content, resolved settings and `dismiss`
-   * callback. The renderer owns every control inside its layout; call
+   * Astryx keeps the card and its auto-hide behavior (inside a
+   * `ToastViewport` the viewport announces the toast, and while a modal hosts
+   * the viewport the card announces itself), then hands the
+   * renderer this toast's content, resolved settings and `dismiss` callback. The renderer owns every control inside its layout; call
    * `dismiss` from the control that should close the toast. Astryx does not
    * inject a fallback control into custom content.
    *
@@ -100,4 +101,9 @@ export interface ToastEntry {
   id: string;
   options: ToastOptions;
   createdAt: number;
+  /**
+   * The row's identity in the stack. A uniqueID overwrite keeps the replaced
+   * toast's, so the card updates in place and focus inside it stays.
+   */
+  rowKey?: string;
 }

package/src/Toast/useToast.tsx

@@ -91,6 +91,7 @@ function getFallbackContext(): ToastContextValue {
   const FallbackCapture = () => {
     const ctx = use(ToastContext);
     const doneRef = useRef(false);
+    // Syncs the module-level fallback with the first toast context that mounts.
     useEffect(() => {
       if (ctx && !doneRef.current) {
         doneRef.current = true;

package/src/Tokenizer/Tokenizer.doc.mjs

@@ -293,11 +293,11 @@ export const docs = {
       description: 'Inline styles for the visual control box.',
     },
     {
-      name: 'experimental',
-      type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",
-      stability: 'experimental',
+      name: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'adaptive'",
       description:
-        "Experimental options: anything in this object may change or be removed in a patch release, and omitting it keeps the stable behavior. presentation (default 'popover') chooses how the field presents its choices. popover is the inline combobox with its anchored suggestion menu. bottom-sheet replaces it with a trigger showing the selected tokens that opens one tall modal sheet: a search row on top, full-width checkbox rows that keep their place while the sheet is open, a Create row with hasCreate, and a footer pinned in every state with a confirmed Clear all and Save; the sheet edits a draft, so onChange fires once, when Save commits it, and a swipe, scrim or Escape close of a changed draft asks before discarding. adaptive uses the bottom sheet on compact touch screens and the popover otherwise, resolved the same way Selector resolves it. In the sheet presentation the trigger is the control (ref, id, aria-* and data-* reach it; with experimental passed, ref also accepts a Ref<HTMLInputElement | HTMLButtonElement> — an input-only ref still type-checks against that wider type, but with adaptive or bottom-sheet it receives the trigger button at runtime, so type the ref for both elements; TokenizerProps keeps its released ref type and gains only the optional experimental), and renderItem, renderToken, endContent, hasClear, hasEntriesOnFocus, menuWidth, tokenOverflowBehavior and hasAutoFocus have no surface to act on; the field warns once in development when they are passed. For example: <Tokenizer label=\"Tags\" searchSource={tagSource} value={tags} onChange={setTags} hasCreate experimental={{presentation: 'adaptive'}} />.",
+        'How the field presents its choices. adaptive (the default) uses the bottom sheet on compact touch screens and the popover otherwise, resolved the same way Selector resolves it; the server render and the hydrating render are the popover. popover is the inline combobox with its anchored suggestion menu on every device. bottom-sheet replaces it on every device with a trigger showing the selected tokens that opens one tall modal sheet: a search row on top, full-width checkbox rows that keep their place while the sheet is open, a Create row with hasCreate, and a footer pinned in every state with a confirmed Clear all and Save; the sheet edits a draft, so onChange fires once, when Save commits it, and a swipe, scrim or Escape close of a changed draft asks before discarding. In the sheet presentation the trigger is the control: ref, id, aria-* and data-* reach it, and ref receives the trigger button there, so type it Ref<HTMLInputElement | HTMLButtonElement>, which the component accepts (TokenizerProps keeps its released input ref type). renderItem, renderToken, endContent, hasClear, hasEntriesOnFocus, menuWidth, tokenOverflowBehavior and hasAutoFocus have no surface in the sheet, and the field warns once in development when they are passed. Pass presentation="popover" to keep the inline field and those props on every device.',
+      default: "'adaptive'",
     },
   ],
   theming: {
@@ -639,11 +639,11 @@ export const docsZh = {
       description: '可视控件框的内联样式。',
     },
     {
-      name: 'experimental',
-      type: "{presentation?: 'popover' | 'bottom-sheet' | 'adaptive'}",
-      stability: 'experimental',
+      name: 'presentation',
+      type: "'popover' | 'bottom-sheet' | 'adaptive'",
       description:
-        "实验性选项：此对象中的任何内容都可能在补丁版本中更改或移除；省略它即保持稳定行为。presentation（默认 'popover'）决定字段如何呈现选项：popover 为内联组合框及其锚定建议菜单；bottom-sheet 改为一个显示已选标记的触发按钮，点按后打开一个高的模态底部面板——顶部为搜索行，下方为整行复选框行（面板打开期间位置保持不变），hasCreate 时有「创建」行，底部固定显示需确认的「全部清除」和「保存」；面板编辑的是草稿，onChange 仅在「保存」提交时触发一次，草稿有改动时滑动、点击遮罩或按 Escape 关闭会先询问是否放弃；adaptive 在紧凑触摸屏上使用底部面板，其他情况使用 popover，解析方式与 Selector 相同。在底部面板呈现中，触发按钮即为控件（ref、id、aria-* 和 data-* 都作用于它；传入 experimental 后，ref 也接受 Ref<HTMLInputElement | HTMLButtonElement>——仅为输入框类型的 ref 在这个更宽的类型下仍能通过类型检查，但在 adaptive 或 bottom-sheet 下运行时收到的是触发按钮，因此请为两种元素声明 ref 的类型；TokenizerProps 保留已发布的 ref 类型，仅新增可选的 experimental）；renderItem、renderToken、endContent、hasClear、hasEntriesOnFocus、menuWidth、tokenOverflowBehavior 和 hasAutoFocus 没有作用对象，传入时开发模式下会警告一次。例如：<Tokenizer label=\"标签\" searchSource={tagSource} value={tags} onChange={setTags} hasCreate experimental={{presentation: 'adaptive'}} />。",
+        '字段如何呈现选项。adaptive（默认）在紧凑触摸屏上使用底部面板，其他情况使用 popover，解析方式与 Selector 相同；服务端渲染和水合期间的渲染均为 popover。popover 在所有设备上为内联组合框及其锚定建议菜单。bottom-sheet 在所有设备上改为一个显示已选标记的触发按钮，点按后打开一个高的模态底部面板——顶部为搜索行，下方为整行复选框行（面板打开期间位置保持不变），hasCreate 时有「创建」行，底部固定显示需确认的「全部清除」和「保存」；面板编辑的是草稿，onChange 仅在「保存」提交时触发一次，草稿有改动时滑动、点击遮罩或按 Escape 关闭会先询问是否放弃。在底部面板呈现中，触发按钮即为控件：ref、id、aria-* 和 data-* 都作用于它，ref 在该呈现中收到的是触发按钮，因此请将其类型声明为组件所接受的 Ref<HTMLInputElement | HTMLButtonElement>（TokenizerProps 保留已发布的输入框 ref 类型）。renderItem、renderToken、endContent、hasClear、hasEntriesOnFocus、menuWidth、tokenOverflowBehavior 和 hasAutoFocus 在底部面板中没有作用对象，传入时开发模式下会警告一次。传入 presentation="popover" 可在所有设备上保留内联字段和这些属性。',
+      default: "'adaptive'",
     },
   ],
   theming: {
@@ -844,7 +844,7 @@ export const docsDense = {
       'Icon at input start, before tokens. Icon name, SVG component, or ReactNode.',
     endContent: 'Content at input row end. For buttons, counts, controls.',
     handleRef: 'Imperative handle for focus() and blur() control.',
-    experimental:
-      "Experimental; may change in a patch. presentation: 'popover' (default, inline combobox) | 'bottom-sheet' (trigger + one searchable modal sheet of checkbox rows editing a draft that Save commits; onChange fires once, on Save) | 'adaptive' (sheet on compact touch, else popover).",
+    presentation:
+      "'adaptive' (default: sheet on compact touch, else popover; SSR/hydration render popover) | 'popover' (inline combobox, every device) | 'bottom-sheet' (trigger + one searchable modal sheet of checkbox rows editing a draft that Save commits; onChange fires once, on Save). Sheet: ref reaches the trigger button; renderItem/renderToken/endContent/hasClear/hasEntriesOnFocus/menuWidth/tokenOverflowBehavior/hasAutoFocus inert (dev warning). presentation=\"popover\" keeps them on every device.",
   },
 };

package/src/Tokenizer/Tokenizer.tsx

@@ -8,8 +8,8 @@
  *   useAdaptivePresentation, and TokenizerBottomSheet (lazy)
  * @output Exports Tokenizer multi-select typeahead component
  * @position Composed component; forwards DOM ref and exposes focus control via
- *   handleRef. The experimental `presentation` option swaps the inline
- *   combobox for a trigger that opens TokenizerBottomSheet.
+ *   handleRef. The `presentation` prop swaps the inline combobox for a
+ *   trigger that opens TokenizerBottomSheet.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Tokenizer/index.ts
@@ -51,7 +51,10 @@ import {useMergedRefs} from '../hooks/useMergedRefs';
 import {TokenizerClearAllMessageContext} from './TokenizerClearAllMessageContext';
 import {TokenizerItemRemovableContext} from './TokenizerItemRemovableContext';
 import {useBusyAnnouncement} from '../hooks/useBusyAnnouncement';
-import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';
+import {
+  type AdaptivePresentation,
+  useAdaptivePresentation,
+} from '../hooks/useAdaptivePresentation';
 import {useIsHydrating} from '../hooks/useIsHydrating';
 import {VisuallyHidden} from '../VisuallyHidden';
 import {warnOnce} from '../utils/devWarning';
@@ -88,7 +91,7 @@ import type {
 } from '../Typeahead/types';
 import {composeEventHandlers, mergeProps} from '../utils';
 import {joinAriaIDs} from '../utils/inputAria';
-import {isFocusDetached} from '../utils/focusReturn';
+import {isFocusDetached} from '../utils/isFocusDetached';
 import {themeProps} from '../utils/themeProps';
 import type {SheetDraftChange} from '../internal/sheetDraft';
 import type {TokenizerBottomSheetProps} from './TokenizerBottomSheet';
@@ -296,62 +299,60 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<
   onFocus?: (e: React.FocusEvent) => void;
   /** Fires when focus leaves the tokenizer entirely. */
   onBlur?: (e: React.FocusEvent) => void;
-  /** Ref forwarded to the combobox input. */
+  /**
+   * How the field presents its choices.
+   * - `'popover'`: the inline combobox with its anchored suggestion menu, on
+   *   every device.
+   * - `'bottom-sheet'`: a trigger showing the selected tokens that opens one
+   *   tall modal sheet: a search row on top, full-width checkbox rows that
+   *   keep their place while the sheet is open, a create row with
+   *   `hasCreate`, and a footer pinned in every state with a confirmed Clear
+   *   all and Save. The sheet edits a draft: `onChange` fires once, when Save
+   *   commits it, and a swipe, scrim or Escape close of a changed draft asks
+   *   before discarding. Suited to compact touch screens, where the inline
+   *   combobox competes with the software keyboard.
+   * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,
+   *   otherwise the popover — the same resolution Selector uses. The server
+   *   render and the hydrating render are the popover.
+   *
+   * In the sheet presentation the trigger is the control: `ref`, `id`,
+   * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,
+   * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,
+   * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on
+   * and warn once in development. Pass `'popover'` to keep the inline field
+   * and those props on every device.
+   * @default 'adaptive'
+   */
+  presentation?: TokenizerPresentation;
+  /**
+   * Ref forwarded to the control: the combobox input in the popover
+   * presentation, the trigger button in the sheet presentation. This type
+   * keeps its released input element; the component itself also accepts a
+   * `Ref<HTMLInputElement | HTMLButtonElement>`, the type to use where the
+   * sheet can present.
+   */
   ref?: React.Ref<HTMLInputElement>;
   /** Imperative handle ref for focus/blur control. */
   handleRef?: React.Ref<TokenizerHandle>;
-  /**
-   * Experimental options, outside the stable compatibility promise: anything
-   * in this object may change or be removed in a patch release. Omit it for
-   * the stable behavior.
-   * @experimental
-   */
-  experimental?: {
-    /**
-     * How the field presents its choices.
-     * - `'popover'`: the inline combobox with its anchored suggestion menu —
-     *   the stable behavior.
-     * - `'bottom-sheet'`: a trigger showing the selected tokens that opens one
-     *   tall modal sheet: a search row on top, full-width checkbox rows that
-     *   keep their place while the sheet is open, a create row with
-     *   `hasCreate`, and a footer pinned in every state with a confirmed Clear
-     *   all and Save. The sheet edits a draft: `onChange` fires once, when Save
-     *   commits it, and a swipe, scrim or Escape close of a changed draft asks
-     *   before discarding. Suited to compact touch screens, where the inline
-     *   combobox competes with the software keyboard.
-     * - `'adaptive'`: the bottom sheet on compact coarse-pointer screens,
-     *   otherwise the popover — the same resolution Selector uses.
-     *
-     * In the sheet presentation the trigger is the control: `ref`, `id`,
-     * `aria-*`, and `data-*` reach it. `renderItem`, `renderToken`,
-     * `endContent`, `hasClear`, `hasEntriesOnFocus`, `menuWidth`,
-     * `tokenOverflowBehavior`, and `hasAutoFocus` have no surface to act on
-     * and warn once in development.
-     * @experimental
-     * @default 'popover'
-     */
-    presentation?: 'popover' | 'bottom-sheet' | 'adaptive';
-  };
 }
 
+/** How Tokenizer presents its choices; see `TokenizerProps.presentation`. */
+export type TokenizerPresentation = AdaptivePresentation;
+
 /**
- * The props the experimental opt-in admits. `experimental` is present, and
- * `ref` also accepts the sheet presentation's trigger button, the control it
- * stands for there. Only the overload below reaches this type. `TokenizerProps`
- * stays the component's declared props type: it is an interface, so
- * `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>, …>` and
- * `ComponentProps<typeof Tokenizer>` keep their released shapes.
+ * The props the component accepts: `TokenizerProps`, whose `ref` keeps its
+ * released input type, with a `ref` that also accepts the sheet
+ * presentation's trigger button. `TokenizerProps` stays the declared props
+ * type, so `interface X extends TokenizerProps<T>`, `Omit<TokenizerProps<T>,
+ * …>` and `ComponentProps<typeof Tokenizer>` keep their released shapes.
  */
-type TokenizerExperimentalProps<T extends SearchableItem> = Omit<
+type TokenizerAcceptedProps<T extends SearchableItem> = Omit<
   TokenizerProps<T>,
-  'ref' | 'experimental'
+  'ref'
 > & {
-  /** @experimental */
-  experimental: NonNullable<TokenizerProps<T>['experimental']>;
   /**
    * Ref forwarded to the control: the combobox input in the popover
    * presentation, the trigger button in the sheet presentation.
-   * @experimental
    */
   ref?: React.Ref<HTMLInputElement | HTMLButtonElement>;
 };
@@ -722,11 +723,11 @@ function EndLane({
 }
 
 // Keep this overload first. TypeScript resolves `ComponentProps<typeof
-// Tokenizer>` against the last overload, so that type stays the stable props.
-// A call that passes `experimental` matches this one and may pass the wider
-// `ref`.
+// Tokenizer>` against the last overload, so that type stays the released
+// props. Every call matches this one, so a ref typed for both controls is
+// accepted.
 export function Tokenizer<T extends SearchableItem>(
-  props: TokenizerExperimentalProps<T>,
+  props: TokenizerAcceptedProps<T>,
 ): React.JSX.Element;
 export function Tokenizer<T extends SearchableItem>(
   props: TokenizerProps<T>,
@@ -776,12 +777,12 @@ export function Tokenizer<T extends SearchableItem>({
   ref,
   handleRef,
   onKeyDown,
-  experimental,
+  presentation = 'adaptive',
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
   'aria-labelledby': ariaLabelledByProp,
   ...restProps
-}: TokenizerProps<T> | TokenizerExperimentalProps<T>): React.JSX.Element {
+}: TokenizerProps<T> | TokenizerAcceptedProps<T>): React.JSX.Element {
   const isEffectivelyRequired = useResolvedRequired({isRequired, isOptional});
   const {rest, container} = useFieldInputStyling('Tokenizer', restProps, {
     containerXstyle,
@@ -807,11 +808,9 @@ export function Tokenizer<T extends SearchableItem>({
   const inputRef = useRef<HTMLInputElement>(null);
   const wrapperRef = useRef<HTMLDivElement>(null);
 
-  // Experimental presentation (`component:Tokenizer` DEC-3). `adaptive`
-  // resolves through the policy the selection controls share; an open sheet
-  // keeps its presentation until it closes, so a resolution change mid-task
-  // cannot pull the surface out from under the person.
-  const presentation = experimental?.presentation ?? 'popover';
+  // `adaptive` resolves through the policy the selection controls share. An
+  // open sheet keeps its presentation until it closes. A resolution change
+  // during a task does not replace the open surface.
   const resolvedPresentation = useAdaptivePresentation(presentation);
   const [isSheetOpen, setIsSheetOpen] = useState(false);
   // Latched for the sheet's lifetime: a sheet stays presented after it closes
@@ -931,7 +930,7 @@ export function Tokenizer<T extends SearchableItem>({
         inertSheetProps.length === 1 ? 'has' : 'have'
       } no surface in the bottom-sheet presentation and ${
         inertSheetProps.length === 1 ? 'is' : 'are'
-      } not rendered there.`,
+      } not rendered there. Pass \`presentation="popover"\` to keep the inline field on every device.`,
     );
     // eslint-disable-next-line @eslint-react/exhaustive-deps -- keyed by the joined names
   }, [inertSheetPropsKey]);
@@ -1466,8 +1465,8 @@ export function Tokenizer<T extends SearchableItem>({
               {...rest}
               ref={useMergedRefs(
                 inputRef,
-                // With `experimental`, the ref type admits the trigger too; in
-                // this presentation it receives the input.
+                // The ref type admits the sheet's trigger too; in this
+                // presentation it receives the input.
                 ref as React.Ref<HTMLInputElement> | undefined,
                 handOffFocusRef,
               )}

package/src/Tokenizer/TokenizerBottomSheet.tsx

@@ -8,7 +8,7 @@
  *   EmptyState, AlertDialog, Icon, Spinner, Text, useBusyAnnouncement, and
  *   the i18n translator
  * @output Exports TokenizerBottomSheet — the touch surface of
- *   `Tokenizer experimental.presentation="bottom-sheet"`: one tall modal sheet
+ *   `Tokenizer presentation="bottom-sheet"`: one tall modal sheet
  *   with a search row on top, stable-order checkbox rows, progressive
  *   long-list rendering, an optional create row, and a confirmed Clear all
  * @position Internal presentation surface of Tokenizer. Loaded on demand by
@@ -354,10 +354,10 @@ function TokenizerSheetContent<T extends SearchableItem>({
   // has an entrance animation and no exit, so a close is its unmount; the
   // 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
+  // (`architecture:react-component-runtime` INV2). After a clear, Clear all
+  // is aria-disabled but stays focusable, so it keeps focus (FR24,
+  // `spec:AST-085` FR4). Focus on the search field opens the on-screen
+  // keyboard over the cleared rows. A confirmed clear is announced too — a
   // change the person hears about, as an add or a remove is
   // (`component:Tokenizer` AR6) — after the confirmation's dialog has gone,
   // so the sheet is the modal on top and the words are delivered inside it
@@ -372,11 +372,9 @@ function TokenizerSheetContent<T extends SearchableItem>({
   const closeClearConfirmation = (confirmed: boolean) => {
     // 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));
+    clearAllRef.current?.focus();
     if (confirmed) {
-      searchRef.current?.focus();
       announce(t('@astryx.tokenizer.allRemoved'));
-    } else {
-      clearAllRef.current?.focus();
     }
   };
   // Keep editing: the confirmation is gone, and focus returns to the search
@@ -614,16 +612,14 @@ function TokenizerSheetContent<T extends SearchableItem>({
   // `action` is declared on `SearchableItem` for the grid-adopting hosts; the
   // sheet rows have not adopted it, so a row renders the item without the
   // control and says so (`spec:AST-058` FR9), as the inline panel does.
-  useEffect(() => {
-    if (results.some(item => item.action != null)) {
-      warnOnce(
-        'tokenizer-sheet:item-action',
-        'Tokenizer',
-        'A result carries `action`, which the bottom-sheet rows do not render ' +
-          'yet; the item is shown without it.',
-      );
-    }
-  }, [results]);
+  if (results.some(item => item.action != null)) {
+    warnOnce(
+      'tokenizer-sheet:item-action',
+      'Tokenizer',
+      'A result carries `action`, which the bottom-sheet rows do not render ' +
+        'yet; the item is shown without it.',
+    );
+  }
 
   // The pending Spinner below stays named, as the inline field's does
   // (`family:input-fields` FR7), but is not a live region; the sheet announces
@@ -1002,11 +998,9 @@ function TokenizerSheetContent<T extends SearchableItem>({
           variant="secondary"
           size="lg"
           isDisabled={draftValue.length === 0}
-          // With a tooltip, Button's disabled mode is `aria-disabled`: the
-          // action keeps its focus order and says why it does nothing
-          // (`spec:AST-085` FR1), instead of leaving the tab order as a
-          // natively disabled button does — a confirmed Clear all returns
-          // focus here before the search field takes it (FR24).
+          // With a tooltip, Button uses aria-disabled, so Clear all stays
+          // focusable after a clear and says why it does nothing
+          // (`spec:AST-085` FR1; FR24).
           tooltip={
             draftValue.length === 0
               ? t('@astryx.tokenizer.nothingToClear')