@astryxdesign/core 0.7.4 → 0.7.5-canary.0418c47

package/dist/Tokenizer/Tokenizer.js

@@ -4,23 +4,36 @@
 
 /**
  * @file Tokenizer.tsx
- * @input Uses React, BaseTypeahead, Field, Token, useAnnounce
- * @output Exports Tokenizer multi-select typeahead component
+ * @input Uses React, BaseTypeahead, Field, Token, useAnnounce,
+ *   useAdaptivePresentation, and TokenizerBottomSheet (lazy)
+ * @output Exports Tokenizer multi-select typeahead component, and the
+ *   internal TokenizerWithPresentation signature the `internal/tokenizer-presentation`
+ *   entry re-exports
  * @position Composed component; forwards DOM ref and exposes focus control via
- *   handleRef
+ *   handleRef. The sheet presentation — a trigger that opens
+ *   TokenizerBottomSheet — is implemented but not exposed: `TokenizerProps`
+ *   offers no `experimental.presentation` while its user experience is being
+ *   finished (`component:Tokenizer` DEC-3, implementation gap), and only
+ *   Astryx's own packages reach it through the internal entry
+ *   (`architecture:react-component-runtime` INV13).
  *
  * SYNC: When modified, update:
  * - /packages/core/src/Tokenizer/index.ts
+ * - /packages/core/src/Tokenizer/TokenizerBottomSheet.tsx (sheet presentation)
  * - /apps/storybook/stories/Tokenizer.stories.tsx
  * - /packages/cli/assets/templates/blocks/components/Tokenizer/ (showcase blocks)
  */
-import React, { useCallback, useId, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import React, { lazy, Suspense, useCallback, useEffect, useId, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import * as stylex from '@stylexjs/stylex';
 import { BusyIndicatorLaneProvider, createBusyIndicatorLane, useIsBusy } from "../Typeahead/busyIndicatorLane.js";
 import { TrailingKeyDownContext } from "../Typeahead/trailingKeyDown.js";
 import { useFieldInputStyling } from "../Field/fieldParts.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { useBusyAnnouncement } from "../hooks/useBusyAnnouncement.js";
+import { useAdaptivePresentation } from "../hooks/useAdaptivePresentation.js";
+import { useIsHydrating } from "../hooks/useIsHydrating.js";
+import { VisuallyHidden } from "../VisuallyHidden/index.js";
+import { warnOnce } from "../utils/devWarning.js";
 import { BaseTypeahead } from "../Typeahead/BaseTypeahead.js";
 import { useSize } from "../SizeContext/SizeContext.js";
 import { Field, InputClearButton, inputWrapperStyles, inputStatusBorderStyles, inputStatusHoverShadowStyles, inputStatusFocusWithinStyles } from "../Field/index.js";
@@ -34,7 +47,7 @@ import { useTooltip } from "../Tooltip/index.js";
 import { useAnnounce } from "../hooks/useAnnounce.js";
 import "../theme/tokens.stylex.js";
 import { colorVars, spacingVars, sizeVars, typeScaleVars } from "../theme/tokens.stylex.js";
-import { mergeProps } from "../utils/index.js";
+import { composeEventHandlers, mergeProps } from "../utils/index.js";
 import { themeProps } from "../utils/themeProps.js";
 import { useTranslator } from "../i18n/index.js";
 
@@ -58,6 +71,23 @@ import { useTranslator } from "../i18n/index.js";
 /**
  * Imperative handle for Tokenizer handleRef.
  */
+
+/**
+ * The presentation options the sheet-capable signature admits. Not public:
+ * `TokenizerProps` has no `experimental` while the sheet's user experience is
+ * being finished; Astryx's own packages reach the sheet through
+ * `@astryxdesign/core/internal/tokenizer-presentation`.
+ */
+
+/**
+ * The props of the sheet-capable signature: `TokenizerProps` plus the
+ * presentation options and a `ref` that also accepts the sheet presentation's
+ * trigger button, the control it stands for there. Not public: reached only
+ * as `TokenizerWithPresentation` through the internal entry, so the released
+ * `TokenizerProps` — an interface, so `interface X extends TokenizerProps<T>`,
+ * `Omit<TokenizerProps<T>, …>` and `ComponentProps<typeof Tokenizer>` keep
+ * their released shapes — names no presentation.
+ */
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 // =============================================================================
 // Styles
@@ -67,11 +97,8 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
 // because the input's reserve is derived from the same value.
 const END_LANE_INSET = spacingVars['--spacing-2'];
 const TOKEN_ROW_INSET = `calc(${spacingVars['--spacing-1']} - 1px)`;
-// InputClearButton grows 2px past its visible box under `(pointer: coarse)`.
-// Keep this maximum reserve in sync with Field/InputClearButton.tsx.
-const INPUT_CLEAR_COARSE_POINTER_OUTSET = '2px';
-// Kept in sync with useEndLaneReserve: inputCompact reads the custom property
-// directly so its empty-query pseudo-class can suppress the inner reserve.
+// Kept in sync with useEndLaneReserve: wrapperWithTokens reads the custom
+// property directly, to keep token rows and the input short of the lane.
 const END_LANE_RESERVE_VAR = '--_tokenizer-end-lane-reserve';
 const styles = {
   wrapper: {
@@ -85,12 +112,14 @@ const styles = {
   wrapperWithTokens: {
     k8WAf4: "x1x7cmac",
     kg3NbH: "xx2oswg",
+    kwRFfy: "xx0flbe",
     khm7nJ: "xajebq8",
     $$css: true
   },
   token: {
     k1xSpc: "x78zum5",
     kmuXW: "x2lah0s",
+    ks0D6T: "x193iq5w",
     kVAEAm: "x1n2onr6",
     kY2c9j: "x1vjfegm",
     $$css: true
@@ -105,6 +134,11 @@ const styles = {
     kY2c9j: "x1vjfegm",
     $$css: true
   },
+  idleSpinner: {
+    k33iCy: "xlshs6z",
+    kCygrm: "xdps06",
+    $$css: true
+  },
   inputAtMax: {
     kzqmXN: "xnalus7",
     k7Eaqz: "xeuugli",
@@ -115,16 +149,15 @@ const styles = {
     $$css: true
   },
   inputCompact: {
-    kVAEAm: "x1n2onr6 x1utg46d",
+    kVAEAm: "x1n2onr6",
     kB7OPa: "x9f619",
-    kLqNvP: "xhi6v0a x1cs7wtd",
     kY2c9j: "x1ja2u2z",
-    k7Eaqz: "x1fns5xo xcax4zt",
-    kUk6DE: "xfoc8du xf0xpto",
-    kzqmXN: "xnalus7 xbuu7xz",
-    kZCmMZ: "x2a0j69 xf0ofad",
-    kwRFfy: "x1p6hqjl x1wg34a1",
-    k9WMMc: "x1yc453h x75j1tr",
+    k7Eaqz: "x1fns5xo x14dcwvw",
+    kUk6DE: "xfoc8du x1q9bidn",
+    kzqmXN: "xnalus7",
+    keTefX: "x1lziwak x1rq9t4t",
+    kZCmMZ: "x2a0j69 x1jwxvv4",
+    kwRFfy: "xyri2b",
     $$css: true
   },
   truncatedWrapper: {
@@ -135,6 +168,25 @@ const styles = {
   layerPopover: {
     kzqmXN: "x1xgy17j",
     $$css: true
+  },
+  sheetTrigger: {
+    kzqmXN: "xh8yej3",
+    kMv6JI: "xjb2p0i",
+    kGuDYH: "x1qlqyl8",
+    kMwMTN: "x1heor9g",
+    k9WMMc: "x1yc453h",
+    kysU6D: "xjyslct",
+    kkrTdU: "x1ypdohk x16khyan",
+    $$css: true
+  },
+  sheetTriggerDisabled: {
+    kVAM5u: "xvy26l8 xmnqt3w",
+    kMwMTN: "x1bhcspo",
+    $$css: true
+  },
+  sheetTokenDisabled: {
+    kMwMTN: "x1tgivj0 x1bhcspo",
+    $$css: true
   }
 };
 const sizeStyles = {
@@ -168,23 +220,6 @@ const endSectionSizeStyles = {
     $$css: true
   }
 };
-const compactInputSizeStyles = {
-  sm: {
-    k87sOh: "x80663w x1a21zuh",
-    k3aq6I: "x1c071of xv6p7n0",
-    $$css: true
-  },
-  md: {
-    k87sOh: "x80663w x811pv0",
-    k3aq6I: "x1c071of xv6p7n0",
-    $$css: true
-  },
-  lg: {
-    k87sOh: "x80663w x1o13q2w",
-    k3aq6I: "x1c071of xv6p7n0",
-    $$css: true
-  }
-};
 const truncatedSizeStyles = {
   sm: {
     kZKoxP: "x6k0iem",
@@ -222,6 +257,41 @@ const layerPlaceholderSizeStyles = {
 // "Create: X" suggestions from real search results.
 const CREATABLE_ID_PREFIX = '__xds_create__';
 
+// The touch sheet (BottomSheet, its gestures, the confirmation dialog, and
+// the empty state) only renders for the bottom-sheet presentation. Loading it
+// on demand keeps it out of pages whose tokenizers stay inline combobox fields
+// (`component:Tokenizer` PR6).
+// One import promise, shared by the preload and the lazy element: the sheet
+// presentation loads its chunk as soon as it is active, so the first press
+// does not wait for the network, while nothing of the sheet is rendered until
+// a press (`architecture:component-style-authoring` INV7).
+const loadTokenizerBottomSheet = async () => import("./TokenizerBottomSheet.js");
+const LazyTokenizerBottomSheet = /*#__PURE__*/lazy(async () => loadTokenizerBottomSheet().then(module => ({
+  default: module.TokenizerBottomSheet
+})));
+
+/**
+ * Hosts the lazily loaded sheet. Renders nothing on the server or in the
+ * render that hydrates server HTML: a lazy component that has not loaded yet
+ * would leave server markup incomplete and abort hydration. The closed sheet
+ * has no visible markup, so it first renders right after hydration.
+ */
+function TokenizerSheetHost(props) {
+  const isHydrating = useIsHydrating();
+  if (isHydrating) {
+    return null;
+  }
+  // `lazy` erases the component's type parameter; the module exports the
+  // generic component this props type belongs to.
+  const Sheet = LazyTokenizerBottomSheet;
+  return /*#__PURE__*/_jsx(Suspense, {
+    fallback: null,
+    children: /*#__PURE__*/_jsx(Sheet, {
+      ...props
+    })
+  });
+}
+
 /**
  * Multi-select input with token chips and typeahead search.
  *
@@ -271,6 +341,13 @@ const CREATABLE_ID_PREFIX = '__xds_create__';
  *
  * Renders nothing when the lane would be empty, so `useEndLaneReserve` sees no
  * element, publishes no width, and the input keeps its full content box.
+ *
+ * With `hasBusySlot` the Spinner stays mounted while idle, unrendered, not
+ * animating and out of the accessibility tree, so its box keeps the themed
+ * Spinner's own size.
+ * Token rows reserve the lane's measured width, so a Spinner that came and
+ * went with the search would re-wrap them, and widen a content-sized field,
+ * on every search.
  */
 function EndLane({
   lane,
@@ -279,6 +356,7 @@ function EndLane({
   loadingLabel,
   anchorRef,
   hasStaticContent,
+  hasBusySlot,
   children
 }) {
   const isBusy = useIsBusy(lane);
@@ -286,19 +364,30 @@ function EndLane({
   // live region; the field announces each search's busy start instead
   // (spec:AST-086 FR8).
   useBusyAnnouncement(isBusy, loadingLabel, anchorRef);
-  if (!isBusy && !hasStaticContent) {
+  if (!isBusy && !hasStaticContent && !hasBusySlot) {
     return null;
   }
   return /*#__PURE__*/_jsxs("div", {
     ref: laneRef,
     ...stylex.props(laneXStyle),
-    children: [isBusy && /*#__PURE__*/_jsx(Spinner, {
+    children: [(isBusy || hasBusySlot) && /*#__PURE__*/_jsx(Spinner
+    // Remounts when a search starts, so the ring syncs its phase on
+    // mount exactly as a newly shown Spinner did before.
+    , {
       size: "sm",
       "aria-label": loadingLabel,
-      role: "img"
-    }), children]
+      role: "img",
+      "aria-hidden": isBusy ? undefined : true,
+      xstyle: isBusy ? undefined : styles.idleSpinner
+    }, isBusy ? 'busy' : 'idle'), children]
   });
 }
+
+// The public signature names no presentation: `ComponentProps<typeof
+// Tokenizer>` and every public call resolve against `TokenizerProps`. The
+// implementation also reads the presentation options, reached only through
+// `TokenizerWithPresentation` below.
+
 export function Tokenizer({
   label,
   isLabelHidden = false,
@@ -344,6 +433,7 @@ export function Tokenizer({
   ref,
   handleRef,
   onKeyDown,
+  experimental,
   id: idProp,
   'aria-describedby': ariaDescribedByProp,
   ...restProps
@@ -356,6 +446,12 @@ export function Tokenizer({
     containerClassName,
     containerStyle
   });
+  // A caller's onClick arrives through the base props; the sheet trigger
+  // composes it with its own open handler rather than letting either win.
+  const {
+    onClick: callerOnClick,
+    ...restWithoutClick
+  } = rest;
   const t = useTranslator();
   const size = useSize(sizeProp, 'md');
   const generatedInputId = useId();
@@ -365,10 +461,128 @@ export function Tokenizer({
   const inputRef = useRef(null);
   const wrapperRef = useRef(null);
 
-  // Disabled-reason tooltip. Disabled controls swallow pointer events, so the
-  // tooltip listeners attach to the input wrapper and the typeahead input stays
-  // perceivable via aria-disabled instead of the disabled attribute. Input is
-  // blocked by the isDisabled guards in BaseTypeahead and handleWrapperClick.
+  // 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';
+  const resolvedPresentation = useAdaptivePresentation(presentation);
+  const [isSheetOpen, setIsSheetOpen] = useState(false);
+  // Latched for the sheet's lifetime: a sheet stays presented after it closes
+  // until BottomSheet has run its exit and handed focus back to the trigger.
+  // Without the latch, `adaptive` resolving to `popover` mid-session (a phone
+  // turned to landscape) would unmount the sheet and the trigger it returns
+  // focus to in the same render, dropping focus to the page body
+  // (`component:Tokenizer` FR16).
+  const [isSheetPresented, setIsSheetPresented] = useState(false);
+  const isSheetPresentation = isSheetOpen || isSheetPresented || resolvedPresentation === 'bottom-sheet';
+  // Preload the sheet's chunk while the sheet presentation is active, so the
+  // first press opens without waiting for the network; nothing renders.
+  useEffect(() => {
+    if (isSheetPresentation) {
+      void loadTokenizerBottomSheet();
+    }
+  }, [isSheetPresentation]);
+  const triggerRef = useRef(null);
+  // The sheet's query between presentations: the sheet is in the DOM only
+  // from a press until its exit completes, and a close the field forces
+  // keeps the query (FR18). The ref follows every report; the press
+  // snapshots it into the state the next presentation starts from.
+  const sheetQueryRef = useRef('');
+  const [sheetInitialQuery, setSheetInitialQuery] = useState('');
+  const handleSheetQueryChange = useCallback(query => {
+    sheetQueryRef.current = query;
+    onChangeQuery?.(query);
+  }, [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.
+  const isHandingOffFocusRef = useRef(false);
+  // Whether the caller has been told focus entered the field in this visit,
+  // so `onBlur` is never reported without its `onFocus`: in Safari a click
+  // or tap does not focus a button, so a pointer-opened sheet reports no
+  // 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) {
+      return;
+    }
+    const active = document.activeElement;
+    if (active != null && active !== document.body) {
+      return;
+    }
+    isHandingOffFocusRef.current = true;
+    (isSheetPresentation ? triggerRef.current : inputRef.current)?.focus();
+    isHandingOffFocusRef.current = false;
+  }, [isSheetPresentation]);
+  // 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).
+  const triggerTokensId = useId();
+  // Each rendered token's id, for the trigger's description; the item id is
+  // an arbitrary string, so it is encoded rather than used as is.
+  const tokenElementId = itemId => `${triggerTokensId}-${encodeURIComponent(itemId)}`;
+  // Props that describe the inline combobox have no surface in the sheet
+  // presentation. Say so once in development rather than dropping them
+  // silently (`architecture:public-component-api` INV3).
+  const inertSheetProps = isSheetPresentation ? [['renderItem', renderItem], ['renderToken', renderToken], ['endContent', endContent], ['hasClear', hasClear || undefined], ['hasEntriesOnFocus', hasEntriesOnFocus || undefined], ['menuWidth', menuWidth], ['tokenOverflowBehavior', tokenOverflowBehavior], ['hasAutoFocus', hasAutoFocus || undefined]].filter(([, v]) => v !== undefined && v !== 'none').map(([name]) => name) : [];
+  const inertSheetPropsKey = inertSheetProps.join(',');
+  useEffect(() => {
+    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.`);
+    // 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
+  // reopen it when re-enabled (`component:Tokenizer` FR17). Adjusted in the
+  // render that sees the change, not an effect, so no frame shows both.
+  const [wasDisabled, setWasDisabled] = useState(isDisabled);
+  // A sheet that was open when the field became disabled stays mounted,
+  // closed, so it runs its exit and hands focus back to the trigger; a field
+  // that is disabled from the start mounts no sheet.
+  const [keepsSheetWhileDisabled, setKeepsSheetWhileDisabled] = useState(false);
+  if (isDisabled !== wasDisabled) {
+    setWasDisabled(isDisabled);
+    if (isDisabled && isSheetOpen) {
+      setIsSheetOpen(false);
+      setKeepsSheetWhileDisabled(true);
+    }
+    if (!isDisabled) {
+      setKeepsSheetWhileDisabled(false);
+    }
+  }
+
+  // Disabled-reason tooltip. The tooltip listeners attach to the input wrapper
+  // and the typeahead input stays perceivable via aria-disabled instead of the
+  // disabled attribute. Input is blocked by the isDisabled guards in
+  // BaseTypeahead and handleWrapperClick.
   const showsDisabledMessage = isDisabled && !!disabledMessage;
   const disabledMessageTooltip = useTooltip({
     placement: 'above',
@@ -377,12 +591,16 @@ export function Tokenizer({
     focusTrigger: 'always',
     isEnabled: showsDisabledMessage
   });
+
+  // The sheet presentation has no input; the public ref reaches the trigger,
+  // the control it stands for (`family:input-fields` FR10).
+  const triggerMergedRef = useMergedRefs(triggerRef, ref, disabledMessageTooltip.ref);
   useImperativeHandle(handleRef, () => ({
     focus() {
-      inputRef.current?.focus();
+      (isSheetPresentation ? triggerRef : inputRef).current?.focus();
     },
     blur() {
-      inputRef.current?.blur();
+      (isSheetPresentation ? triggerRef : inputRef).current?.blur();
     }
   }));
 
@@ -448,7 +666,11 @@ export function Tokenizer({
       layer.show();
     }
     if (comingFromOutside) {
-      onFocus?.(e);
+      isControlFocusedRef.current = true;
+      if (!isHandingOffFocusRef.current) {
+        hasReportedFocusRef.current = true;
+        onFocus?.(e);
+      }
       // Redirect to the input so the user doesn't have to tab through
       // every token remove button.
       if (e.target !== inputRef.current) {
@@ -458,6 +680,8 @@ export function Tokenizer({
   }, [isLayerMode, layer, isFocusInTokenizer, onFocus]);
   const handleBlurCapture = useCallback(e => {
     if (!isFocusInTokenizer(e.relatedTarget)) {
+      isControlFocusedRef.current = false;
+      hasReportedFocusRef.current = false;
       setIsFocusedWithin(false);
       onBlur?.(e);
       if (isLayerMode) {
@@ -519,19 +743,21 @@ export function Tokenizer({
     bootstrap: async () => []
   }), []);
 
-  // Announce token add/remove politely via the persistent live region.
-  // Tokens previously appeared and disappeared silently — Backspace on an
-  // empty input removes the trailing token, and the per-token remove buttons
-  // gave no audible feedback either.
+  // Announce token add/remove politely via a persistent live region.
+  // Announce token add/remove politely. `useAnnounce` follows where this
+  // call is made (`spec:AST-086` FR14): the inline field's words go to the
+  // shared channel, or into the modal that encloses the field. The sheet's
+  // own changes are announced from inside the sheet, where FR14 routes them
+  // into the sheet's dialog; the handlers below stay silent for those.
   const announce = useAnnounce();
 
   // Handle adding an item — detect creatable synthetic items
-  const handleAdd = useCallback(item => {
-    if (!item) {
-      return;
+  const handleAdd = useCallback((item, options) => {
+    if (isDisabled || !item) {
+      return false;
     }
     if (isAtMax) {
-      return;
+      return false;
     }
 
     // Detect "Create: X" synthetic items from the creatable source
@@ -541,7 +767,7 @@ export function Tokenizer({
       // label, so a selection carrying an opaque id with that label is also a
       // duplicate, not just one whose id happens to equal the text.
       if (selectedIds.has(createdValue) || selectedLabels.has(createdValue.toLowerCase())) {
-        return;
+        return false;
       }
       const base = {
         id: createdValue,
@@ -553,42 +779,53 @@ export function Tokenizer({
         item: realItem,
         type: 'create'
       });
-      announce(t('@astryx.tokenizer.tokenAdded', {
-        label: createdValue
-      }));
-      return;
+      if (!options?.silent) {
+        announce(t('@astryx.tokenizer.tokenAdded', {
+          label: createdValue
+        }));
+      }
+      return true;
     }
     if (selectedIds.has(item.id)) {
-      return;
+      return false;
     }
     const newItems = [...value, item];
     onChange(newItems, {
       item,
       type: 'add'
     });
-    announce(t('@astryx.tokenizer.tokenAdded', {
-      label: item.label
-    }));
-  }, [value, onChange, isAtMax, selectedIds, selectedLabels, hasCreate, announce, t]);
+    if (!options?.silent) {
+      announce(t('@astryx.tokenizer.tokenAdded', {
+        label: item.label
+      }));
+    }
+    return true;
+  }, [value, onChange, isDisabled, isAtMax, selectedIds, selectedLabels, hasCreate, announce, t]);
 
   // Handle removing an item. Single removal path: both Backspace on an empty
   // input and the per-token remove buttons route through here, so the
   // announcement covers both.
-  const handleRemove = useCallback(item => {
+  const handleRemove = useCallback((item, options) => {
+    if (isDisabled) {
+      return false;
+    }
     const newItems = value.filter(v => v.id !== item.id);
     onChange(newItems, {
       item,
       type: 'remove'
     });
-    announce(t('@astryx.tokenizer.tokenRemoved', {
-      label: item.label
-    }));
+    if (!options?.silent) {
+      announce(t('@astryx.tokenizer.tokenRemoved', {
+        label: item.label
+      }));
+    }
     inputRef.current?.focus();
-  }, [value, onChange, announce, t]);
+    return true;
+  }, [value, onChange, isDisabled, announce, t]);
 
   // Handle clearing all items
   const handleClearAll = useCallback(() => {
-    if (value.length === 0) {
+    if (isDisabled || value.length === 0) {
       return;
     }
     // Report the last item as removed (convention)
@@ -598,7 +835,7 @@ export function Tokenizer({
       type: 'remove'
     });
     inputRef.current?.focus();
-  }, [value, onChange]);
+  }, [value, onChange, isDisabled]);
 
   // Handle backspace on empty input — remove last token
   const handleKeyDown = useCallback(e => {
@@ -633,7 +870,7 @@ export function Tokenizer({
     if (renderToken) {
       return /*#__PURE__*/_jsx("span", {
         ...{
-          className: "x78zum5 x2lah0s x1n2onr6 x1vjfegm"
+          className: "x78zum5 x2lah0s x193iq5w x1n2onr6 x1vjfegm"
         },
         children: renderToken(item, onRemoveItem)
       }, item.id);
@@ -709,7 +946,10 @@ export function Tokenizer({
         value: onKeyDown,
         children: /*#__PURE__*/_jsx(BaseTypeahead, {
           ...rest,
-          ref: useMergedRefs(inputRef, ref),
+          ref: useMergedRefs(inputRef,
+          // With `experimental`, the ref type admits the trigger too; in
+          // this presentation it receives the input.
+          ref),
           searchSource: isAtMax ? emptySource : filteredSource,
           value: null,
           onChange: handleAdd,
@@ -734,28 +974,29 @@ export function Tokenizer({
           onKeyDown: handleKeyDown,
           anchorRef: wrapperRef,
           size: size,
-          inputXStyle: [isAtMax || isTruncated ? styles.inputAtMax : value.length > 0 ? [styles.inputCompact, compactInputSizeStyles[size]] : undefined,
-          // The compact-token style owns the same reserve with an empty-query
-          // exception. This standalone rule is only for an empty Tokenizer;
-          // it still resolves to zero until the lane publishes a width.
+          inputXStyle: [isAtMax || isTruncated ? styles.inputAtMax : value.length > 0 ? styles.inputCompact : undefined,
+          // With tokens, wrapperWithTokens reserves the lane for every row.
+          // This rule is only for an empty Tokenizer; it still resolves to
+          // zero until the lane publishes a width.
           !(isAtMax || isTruncated || value.length > 0) && laneReserve]
         })
       })
-    }), htmlName != null && value.map(item => /*#__PURE__*/_jsx("input", {
+    }), htmlName != null && !isDisabled && value.map(item => /*#__PURE__*/_jsx("input", {
       type: "hidden",
       name: htmlName,
       value: item.id
-      // Disabled native controls are excluded from form submission;
-      // mirror that for the hidden carriers.
-      ,
-      disabled: isDisabled
     }, item.id)), /*#__PURE__*/_jsxs(EndLane, {
       lane: busyLane,
       laneRef: laneRef,
       laneXStyle: [styles.endSection, endSectionSizeStyles[size]],
       loadingLabel: t('@astryx.typeahead.loading'),
       anchorRef: wrapperRef,
-      hasStaticContent: hasStaticEndLane,
+      hasStaticContent: hasStaticEndLane
+      // Wherever a search can run beside tokens: enabled and below
+      // maxEntries. A collapsed overflow row keeps it too, since a search
+      // started while focused can settle after focus leaves.
+      ,
+      hasBusySlot: value.length > 0 && !isDisabled && !isAtMax,
       children: [endContent, hasClearButton && /*#__PURE__*/_jsx(InputClearButton, {
         label: t('@astryx.tokenizer.clearAll'),
         onClick: e => {
@@ -766,7 +1007,143 @@ export function Tokenizer({
     })]
   });
   let tokenizerContent;
-  if (isLayerMode) {
+  if (isSheetPresentation) {
+    tokenizerContent = /*#__PURE__*/_jsxs(_Fragment, {
+      children: [/*#__PURE__*/_jsxs("button", {
+        ...restWithoutClick,
+        ref: triggerMergedRef,
+        type: "button",
+        id: inputId,
+        "aria-haspopup": "dialog",
+        "aria-expanded": isSheetOpen,
+        "aria-disabled": isDisabled || undefined
+        // The description is what the inline input's is, in its order —
+        // the caller's ids, the field description, the status message, the
+        // disabled reason (`spec:AST-085` FR5: a disabled control exposes
+        // its description and reason on itself) — then the hidden count and
+        // the rendered tokens themselves, each by id: the
+        // accessible-description algorithm reads the referenced elements in
+        // order and separates them, so every label renders once
+        // (`architecture:component-style-authoring` INV7) and no locale's
+        // list punctuation is written here (AR6).
+        ,
+        "aria-describedby": [ariaDescribedByProp, ariaDescribedBy, value.length > 0 ? triggerTokensId : null, ...value.map(item => tokenElementId(item.id))].filter(Boolean).join(' ') || undefined
+        // The open runs first and the caller's onClick after it, as the
+        // inline input composes its click: a caller observes the click but
+        // cannot cancel the field's own handling
+        // (`family:input-fields` FR10).
+        ,
+        onClick: composeEventHandlers(() => {
+          if (isDisabled) {
+            return;
+          }
+          setIsSheetPresented(true);
+          setSheetInitialQuery(sheetQueryRef.current);
+          setIsSheetOpen(true);
+        },
+        // Typed for the input by the base props; here the control is the
+        // trigger button, and the handler only reads the event.
+        callerOnClick),
+        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
+          // takes the focus over once it mounts. The field's own sheet is
+          // part of the field: focus coming back from it, or handed over by
+          // a presentation swap, is not focus entering from outside, so the
+          // caller's onFocus — "when focus enters the tokenizer from
+          // outside" — stays quiet for it (`family:input-fields` FR10).
+          const isReturningFromSheet = !isSheetOpen && isSheetPresented;
+          if (isReturningFromSheet) {
+            setIsSheetPresented(false);
+          }
+          const isInsideTheField = isReturningFromSheet && hasReportedFocusRef.current || isHandingOffFocusRef.current;
+          if (!isInsideTheField) {
+            hasReportedFocusRef.current = true;
+            onFocus?.(event);
+          }
+        },
+        onBlur: event => {
+          // Focus moving into the sheet is still the field's: the flag
+          // stays, and the caller's onBlur — "when focus leaves the
+          // tokenizer entirely" — stays quiet. Only a blur to somewhere
+          // else reports.
+          if (isSheetOpen) {
+            return;
+          }
+          isControlFocusedRef.current = false;
+          hasReportedFocusRef.current = false;
+          onBlur?.(event);
+        },
+        onKeyDown: onKeyDown,
+        ...mergeProps(themeProps('tokenizer', {
+          size,
+          status: status?.type,
+          disabled: isDisabled ? 'disabled' : null
+        }), stylex.props(inputWrapperStyles.base, styles.wrapper, styles.sheetTrigger,
+        // The trigger keeps the inline field's height for its size step,
+        // as Selector's bottom-sheet trigger does; the sheet's own rows
+        // and search field carry the touch-sized targets.
+        sizeStyles[size], value.length > 0 && styles.wrapperWithTokens, isDisabled && inputWrapperStyles.disabled, isDisabled && styles.sheetTriggerDisabled, status && inputStatusBorderStyles[status.type], status && !isDisabled && inputStatusHoverShadowStyles[status.type], status && inputStatusFocusWithinStyles[status.type], controlXstyle), controlClassName, controlStyle),
+        children: [startIcon && /*#__PURE__*/_jsx("span", {
+          ...{
+            0: {},
+            1: {
+              className: "x1xrm450 x1n2onr6 x1vjfegm"
+            }
+          }[!!(value.length > 0) << 0],
+          children: renderIconSlot(startIcon, {
+            size: 'sm',
+            color: 'secondary'
+          })
+        }), value.length > 0 ? value.map(item => /*#__PURE__*/_jsx(Token, {
+          id: tokenElementId(item.id),
+          label: item.label,
+          size: size,
+          isDisabled: isDisabled,
+          xstyle: isDisabled ? styles.sheetTokenDisabled : undefined
+        }, item.id)) : /*#__PURE__*/_jsx("span", {
+          ...{
+            0: {
+              className: "xv1l7n4 x7a5moj"
+            },
+            1: {
+              className: "x7a5moj xv1l7n4 x1bhcspo"
+            }
+          }[!!isDisabled << 0],
+          children: placeholder ?? ''
+        })]
+      }), value.length > 0 && /*#__PURE__*/_jsx(VisuallyHidden, {
+        id: triggerTokensId,
+        children: t('@astryx.tokenizer.selectedCount', {
+          count: value.length
+        })
+      }), htmlName != null && !isDisabled && value.map(item => /*#__PURE__*/_jsx("input", {
+        type: "hidden",
+        name: htmlName,
+        value: item.id
+      }, item.id)), (isSheetOpen || isSheetPresented) && (!isDisabled || keepsSheetWhileDisabled) && /*#__PURE__*/_jsx(TokenizerSheetHost, {
+        isOpen: isSheetOpen,
+        onOpenChange: setIsSheetOpen,
+        finalFocusRef: triggerRef,
+        initialQuery: sheetInitialQuery,
+        label: label,
+        searchSource: searchSource,
+        value: value,
+        isAtMax: isAtMax,
+        hasCreate: hasCreate,
+        maxMenuItems: maxMenuItems ?? 10,
+        minQueryLength: minQueryLength ?? 1,
+        debounceMs: debounceMs ?? 150,
+        emptySearchText: emptySearchText,
+        onAdd: handleAdd,
+        onRemove: handleRemove,
+        onClearAll: handleClearAll,
+        onChangeQuery: handleSheetQueryChange
+      })]
+    });
+  } else if (isLayerMode) {
     const placeholderSizeStyle = layerPlaceholderSizeStyles[size];
     tokenizerContent = /*#__PURE__*/_jsxs(_Fragment, {
       children: [/*#__PURE__*/_jsx("div", {
@@ -828,4 +1205,16 @@ export function Tokenizer({
     children: [tokenizerContent, showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
   });
 }
-Tokenizer.displayName = 'Tokenizer';
+Tokenizer.displayName = 'Tokenizer';
+
+/**
+ * The same component with the sheet presentation reachable: `experimental`
+ * (`presentation: 'popover' | 'bottom-sheet' | 'adaptive'`) and a `ref` that
+ * also takes the trigger button. Not public — re-exported only by
+ * `@astryxdesign/core/internal/tokenizer-presentation`, the entry reserved
+ * for Astryx's own packages (`architecture:react-component-runtime` INV13),
+ * while the sheet's user experience is being finished (`component:Tokenizer`
+ * DEC-3). The public `Tokenizer` renders the popover presentation for every
+ * field.
+ */
+export const TokenizerWithPresentation = Tokenizer;