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

package/dist/Toast/ToastViewport.js

@@ -13,13 +13,14 @@
  * SYNC: When placement, stacking, hosting, focus, announcement, or safe-area
  *   behavior changes, update ToastViewport.test.tsx, Toast.doc.mjs, and Toast.stories.tsx.
  */
-import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react';
 import { createPortal } from 'react-dom';
 import * as stylex from '@stylexjs/stylex';
 import "../theme/tokens.stylex.js";
 import { spacingVars, durationVars, easeVars } from "../theme/tokens.stylex.js";
 import { mergeProps } from "../utils/index.js";
 import { getNodeText } from "../utils/getNodeText.js";
+import { moveFocusLeftBehind, noteFocusWithin } from "../utils/focusReturn.js";
 import { INTERACTIVE_SELECTORS } from "../hooks/useClickableContainer.js";
 import { useAnnounce } from "../hooks/useAnnounce.js";
 import { layerTextReset } from "../Layer/layerTextReset.stylex.js";
@@ -122,7 +123,8 @@ function ToastRow({
   isExiting,
   isReversed,
   onExited,
-  onDismiss
+  onDismiss,
+  isLiveRegion
 }) {
   const o = entry.options;
   const type = o.type ?? 'info';
@@ -194,12 +196,16 @@ function ToastRow({
         isExiting: isExiting,
         gestureDirection: isReversed ? -1 : 1,
         onDismiss: reason => onDismiss(entry.id, reason),
-        renderContent: o.renderContent
+        renderContent: o.renderContent,
+        timerKey: entry.id,
+        isLiveRegion: isLiveRegion
       })
     })
   });
 }
 ToastRow.displayName = 'ToastRow';
+const hasActiveModalOutlet = () => getActiveModalOutlet() != null;
+const hasNoModalOutlet = () => false;
 
 /**
  * Container that renders and manages toast notifications. Place at the root
@@ -260,6 +266,11 @@ 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(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(null);
+  // Where focus was inside a toast whose dismissal hands focus off.
+  const dismissFocusNoteRef = useRef(null);
 
   // Collect a focusable control within a toast node, if any.
   // Reuses the canonical INTERACTIVE_SELECTORS list (native controls plus
@@ -280,13 +291,9 @@ export function ToastViewport({
     return null;
   }, []);
 
-  // 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
@@ -294,6 +301,12 @@ 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 => {
     const {
       uniqueID,
@@ -326,7 +339,26 @@ export function ToastViewport({
     if (overwritten && renderedToastsRef.current.includes(overwritten)) {
       replacedRef.current.set(overwritten.id, overwritten);
     }
-    const projected = overwritten ? committed.map(t => t === overwritten ? entry : t) : [...committed, entry];
+    // 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 = 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(`[data-toast-id="${overwritten.id}"]`));
+      if (note != null) {
+        overwriteFocusRef.current = {
+          id: placed.id,
+          note
+        };
+      }
+    }
+    const projected = overwritten ? 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(projected.filter((t, i) => i < firstVisible && exitingIdsRef.current.has(t.id)).map(t => t.id));
@@ -349,7 +381,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
@@ -360,7 +392,7 @@ export function ToastViewport({
       // replaced namesake as leaving since, which must not turn the
       // 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];
+      return overwritten && kept.includes(overwritten) ? kept.map(t => t === overwritten ? placed : t) : [...kept, placed];
     });
   }, [announce, maxVisible]);
   const removeToast = useCallback((id, reason) => {
@@ -383,9 +415,15 @@ 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(`[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(`[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
@@ -441,6 +479,31 @@ 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, targetId) => {
+    const el = viewportRef.current;
+    const rowFor = id => el?.querySelector(`[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 = 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.
@@ -456,25 +519,21 @@ export function ToastViewport({
     }
     focusHandoffIdRef.current = null;
     pendingFocusRef.current = null;
-    const el = viewportRef.current;
-    if (target !== 'restore' && el) {
-      const nextNode = el.querySelector(`[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 => {
     return toastsRef.current.find(t => t.options.uniqueID === uid);
   }, []);
@@ -519,6 +578,9 @@ export function ToastViewport({
       setHost(null);
     };
   }, [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;
@@ -663,8 +725,9 @@ export function ToastViewport({
         isExiting: exitingIds.has(entry.id),
         isReversed: isReversed,
         onExited: handleExited,
-        onDismiss: removeToast
-      }, entry.id))
+        onDismiss: removeToast,
+        isLiveRegion: isModalHosted
+      }, entry.rowKey ?? entry.id))
     })
   });
   return /*#__PURE__*/_jsxs(ToastContext, {

package/dist/Toast/types.d.ts

@@ -31,9 +31,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.
      *
@@ -85,5 +86,10 @@ 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;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/Toast/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/Toast/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzC,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,CAAC;AAEhF,mEAAmE;AACnE,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE5D,wCAAwC;AACxC,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnD,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAErC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C,gDAAgD;IAChD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC/C;AAED,oDAAoD;AACpD,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC;AAExC,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,IAAI,EAAE,SAAS,CAAC;IAChB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,4EAA4E;IAC5E,IAAI,EAAE,SAAS,CAAC;IAChB,8CAA8C;IAC9C,UAAU,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,KAAK,EAAE,uBAAuB,KAC3B,SAAS,CAAC;AAEf,oDAAoD;AACpD,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,cAAc,CAAC;AAEpE,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CACnB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/Toast/types.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAErC,gDAAgD;AAChD,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,OAAO,CAAC;AAEzC,6DAA6D;AAC7D,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,aAAa,CAAC;AAEhF,mEAAmE;AACnE,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE5D,wCAAwC;AACxC,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEnD,mCAAmC;AACnC,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,EAAE,oBAAoB,CAAC;IAErC,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,sBAAsB,CAAC;IAC3C,gDAAgD;IAChD,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,kBAAkB,KAAK,IAAI,CAAC;CAC/C;AAED,oDAAoD;AACpD,MAAM,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC;AAExC,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC,yDAAyD;IACzD,IAAI,EAAE,SAAS,CAAC;IAChB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,4EAA4E;IAC5E,IAAI,EAAE,SAAS,CAAC;IAChB,8CAA8C;IAC9C,UAAU,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,EAAE,cAAc,CAAC;CACzB;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,CACjC,KAAK,EAAE,uBAAuB,KAC3B,SAAS,CAAC;AAEf,oDAAoD;AACpD,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,EAAE,YAAY,KAAK,cAAc,CAAC;AAEpE,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,YAAY,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/dist/Toast/useToast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useToast.d.ts","sourceRoot":"","sources":["../../src/Toast/useToast.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,SAAS,CAAC;AAwIjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,IAAI,WAAW,CAetC"}
+{"version":3,"file":"useToast.d.ts","sourceRoot":"","sources":["../../src/Toast/useToast.tsx"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,SAAS,CAAC;AAyIjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,IAAI,WAAW,CAetC"}

package/dist/Toast/useToast.js

@@ -70,6 +70,7 @@ function getFallbackContext() {
   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/dist/Tokenizer/Tokenizer.d.ts

@@ -4,8 +4,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
@@ -15,6 +15,7 @@
  */
 import React, { type ReactNode } from 'react';
 import { type FieldInputBaseProps } from '../Field/fieldParts.js';
+import { type AdaptivePresentation } from '../hooks/useAdaptivePresentation.js';
 import type { SizeValue } from '../utils/types.js';
 import { type InputStatus } from '../Field/index.js';
 import { type IconType } from '../Icon/index.js';
@@ -202,62 +203,59 @@ export interface TokenizerProps<T extends SearchableItem> extends Omit<FieldInpu
     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<TokenizerProps<T>, 'ref' | 'experimental'> & {
-    /** @experimental */
-    experimental: NonNullable<TokenizerProps<T>['experimental']>;
+type TokenizerAcceptedProps<T extends SearchableItem> = Omit<TokenizerProps<T>, 'ref'> & {
     /**
      * 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>;
 };
-export declare function Tokenizer<T extends SearchableItem>(props: TokenizerExperimentalProps<T>): React.JSX.Element;
+export declare function Tokenizer<T extends SearchableItem>(props: TokenizerAcceptedProps<T>): React.JSX.Element;
 export declare function Tokenizer<T extends SearchableItem>(props: TokenizerProps<T>): React.JSX.Element;
 export declare namespace Tokenizer {
     var displayName: string;

package/dist/Tokenizer/Tokenizer.d.ts.map

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

package/dist/Tokenizer/Tokenizer.js

@@ -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
@@ -47,7 +47,7 @@ import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, sizeVars, typeScaleVars } from "../theme/tokens.stylex.js";
 import { composeEventHandlers, mergeProps } from "../utils/index.js";
 import { joinAriaIDs } from "../utils/inputAria.js";
-import { isFocusDetached } from "../utils/focusReturn.js";
+import { isFocusDetached } from "../utils/isFocusDetached.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useResolvedRequired } from "../hooks/useResolvedRequired.js";
 import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
@@ -77,13 +77,14 @@ registerEnglishFallback(english);
  * Imperative handle for Tokenizer handleRef.
  */
 
+/** How Tokenizer presents its choices; see `TokenizerProps.presentation`. */
+
 /**
- * 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.
  */
 
 // =============================================================================
@@ -381,9 +382,9 @@ 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({
   label,
@@ -430,7 +431,7 @@ export function Tokenizer({
   ref,
   handleRef,
   onKeyDown,
-  experimental,
+  presentation = 'adaptive',
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
   'aria-labelledby': ariaLabelledByProp,
@@ -467,11 +468,9 @@ export function Tokenizer({
   const inputRef = useRef(null);
   const wrapperRef = useRef(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
@@ -561,7 +560,7 @@ export function Tokenizer({
     if (inertSheetPropsKey === '') {
       return;
     }
-    warnOnce(`tokenizer:sheet-inert:${inertSheetPropsKey}`, 'Tokenizer', `\`${inertSheetProps.join('`, `')}\` ${inertSheetProps.length === 1 ? 'has' : 'have'} no surface in the bottom-sheet presentation and ${inertSheetProps.length === 1 ? 'is' : 'are'} not rendered there.`);
+    warnOnce(`tokenizer:sheet-inert:${inertSheetPropsKey}`, 'Tokenizer', `\`${inertSheetProps.join('`, `')}\` ${inertSheetProps.length === 1 ? 'has' : 'have'} no surface in the bottom-sheet presentation and ${inertSheetProps.length === 1 ? 'is' : 'are'} 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]);
   // A field that becomes disabled cannot keep its sheet open, and must not
@@ -996,8 +995,8 @@ export function Tokenizer({
           children: /*#__PURE__*/_jsx(BaseTypeahead, {
             ...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, handOffFocusRef),
             searchSource: isAtMax ? emptySource : filteredSource,
             value: null,

package/dist/Tokenizer/TokenizerBottomSheet.d.ts

@@ -4,7 +4,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

package/dist/Tokenizer/TokenizerBottomSheet.js

@@ -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
@@ -189,10 +189,10 @@ function TokenizerSheetContent({
   // 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
@@ -206,11 +206,9 @@ function TokenizerSheetContent({
   const closeClearConfirmation = confirmed => {
     // 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
@@ -419,11 +417,9 @@ function TokenizerSheetContent({
   // `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
@@ -747,11 +743,9 @@ function TokenizerSheetContent({
         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') : undefined,
         ref: clearAllRef,

package/dist/Tokenizer/index.d.ts

@@ -7,5 +7,5 @@
  * SYNC: When adding new Tokenizer files, update exports here
  */
 export { Tokenizer } from './Tokenizer.js';
-export type { TokenizerProps, TokenizerSize, TokenizerOverflowBehavior, TokenizerChange, TokenizerHandle, TokenizerStatus, TokenizerStatusType, } from './Tokenizer.js';
+export type { TokenizerProps, TokenizerSize, TokenizerOverflowBehavior, TokenizerPresentation, TokenizerChange, TokenizerHandle, TokenizerStatus, TokenizerStatusType, } from './Tokenizer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/Tokenizer/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Tokenizer/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,YAAY,EACV,cAAc,EACd,aAAa,EACb,yBAAyB,EACzB,eAAe,EACf,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/Tokenizer/index.ts"],"names":[],"mappings":"AAIA;;;;;;;GAOG;AAEH,OAAO,EAAC,SAAS,EAAC,MAAM,aAAa,CAAC;AACtC,YAAY,EACV,cAAc,EACd,aAAa,EACb,yBAAyB,EACzB,qBAAqB,EACrB,eAAe,EACf,eAAe,EACf,eAAe,EACf,mBAAmB,GACpB,MAAM,aAAa,CAAC"}