@astryxdesign/core 0.7.7 → 0.7.8-canary.07ee4b5

package/dist/PowerSearch/PowerSearch.js

@@ -4,16 +4,19 @@
 
 /**
  * @file PowerSearch.tsx
- * @input PowerSearchConfig, filters, onChange
+ * @input PowerSearchConfig, filters, onChange; Tokenizer, Field parts, Token,
+ *   useAdaptivePresentation, and PowerSearchBottomSheet (lazy)
  * @output Structured filter bar with token-based filter management
  * @position Main component; forwards DOM ref and exposes tokenizer control via
- *   handleRef
+ *   handleRef. The `presentation` prop swaps the tokenizer field and editor
+ *   popover for one trigger that opens PowerSearchBottomSheet.
  *
  * SYNC: When modified, update:
  * - /packages/core/src/PowerSearch/index.ts
+ * - /packages/core/src/PowerSearch/PowerSearchBottomSheet.tsx (sheet presentation)
  * - /packages/cli/assets/templates/blocks/components/PowerSearch/ (showcase blocks)
  */
-import React, { useCallback, useEffect, 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 { Tokenizer } from "../Tokenizer/index.js";
 import { TokenizerClearAllMessageContext } from "../Tokenizer/TokenizerClearAllMessageContext.js";
@@ -23,22 +26,31 @@ import { Token } from "../Token/index.js";
 import { TokenNamingContext } from "../Token/TokenNamingContext.js";
 import { Avatar } from "../Avatar/index.js";
 import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
-import { Icon } from "../Icon/index.js";
+import { Icon, renderIconSlot } from "../Icon/index.js";
+import { Field } from "../Field/Field.js";
+import { inputStatusBorderStyles, inputStatusFocusWithinStyles, inputStatusHoverShadowStyles, inputWrapperStyles } from "../Field/inputStyles.stylex.js";
 import { usePopover } from "../Popover/usePopover.js";
+import { useTooltip } from "../Tooltip/useTooltip.js";
 import "../Layer/layerViewportInset.stylex.js";
 import { layerViewportInset } from "../Layer/layerViewportInset.stylex.js";
 import { useAnnounce } from "../hooks/useAnnounce.js";
+import { useAdaptivePresentation } from "../hooks/useAdaptivePresentation.js";
+import { useDevWarning } from "../hooks/useDevWarning.js";
+import { useIsHydrating } from "../hooks/useIsHydrating.js";
 import "../theme/tokens.stylex.js";
-import { spacingVars, colorVars, typeScaleVars, fontWeightVars } from "../theme/tokens.stylex.js";
+import { spacingVars, colorVars, sizeVars, typeScaleVars, typographyVars, fontWeightVars } from "../theme/tokens.stylex.js";
 import { useSize } from "../SizeContext/SizeContext.js";
+import { isFocusDetached } from "../utils/isFocusDetached.js";
+import { isRenderable } from "../utils/isRenderable.js";
 import { useInternalConfig } from "./useInternalConfig.js";
 import { usePowerSearchSource } from "./usePowerSearchSource.js";
-import { formatFilterValue, formatDateAbsoluteCompact } from "./formatFilterValue.js";
-import { PowerSearchEditPopover } from "./PowerSearchEditPopover.js";
+import { formatFilterValue } from "./formatFilterValue.js";
+import { NestedEditor, PowerSearchEditPopover } from "./PowerSearchEditPopover.js";
+import { buildRelativeDateOptions, PowerSearchValueEditor } from "./PowerSearchValueEditor.js";
 import { resolveOperatorLabel } from "./resolveOperatorLabel.js";
 import { themeProps } from "../utils/themeProps.js";
-import { truncateCharacters } from "../utils/characters.js";
 import { useLocale } from "../i18n/useLocale.js";
+import { formatTokenValueText } from "./formatTokenValue.js";
 import { useMergedRefs } from "../hooks/useMergedRefs.js";
 import { registerEnglishFallback, useComponentTranslator } from "../i18n/useComponentTranslator.js";
 import english from "../i18n/generated-english/PowerSearch/PowerSearch.generated.js";
@@ -83,106 +95,76 @@ const popoverLayerStyles = {
     $$css: true
   }
 };
-function truncateString(value, limit) {
-  // Same semantics as before — strings within limit + 3 pass through, longer
-  // ones cut to limit + '...' — but counted in characters, not code units.
-  return truncateCharacters(value, limit + 3, '...');
-}
-function getEnumLabel(values, value) {
-  return values.find(v => v.value === value)?.label ?? value;
-}
+// The sheet presentation's trigger field: the same control box as the
+// tokenizer field, with display-only tokens and one button as its only tab
+// stop.
+const sheetTriggerSizeStyles = {
+  sm: {
+    kAzted: "x1gdqauq",
+    $$css: true
+  },
+  md: {
+    kAzted: "x1uogy3y",
+    $$css: true
+  },
+  lg: {
+    kAzted: "x1xf4nls",
+    $$css: true
+  }
+};
+const sheetTriggerStyles = {
+  wrapper: {
+    kVAEAm: "x1n2onr6",
+    kwnvtZ: "xozqiw3",
+    kOIVth: "xzye2dw",
+    kZKoxP: "xt7dq6l",
+    kkrTdU: "x1ypdohk xvivl9a",
+    $$css: true
+  },
+  wrapperWithTokens: {
+    k8WAf4: "x1x7cmac",
+    kg3NbH: "xx2oswg",
+    $$css: true
+  }
+};
+
+// The sheet flow (three standalone sheets, the sheet editors) only
+// renders for the bottom-sheet presentation. Loading it on demand keeps it out
+// of pages whose PowerSearch stays a tokenizer field.
+// One import promise, shared by the preload and the lazy element: the sheet
+// presentation loads the flow's chunk as soon as it is active, so the first
+// press does not wait for the network, while nothing of the flow is rendered
+// until a press.
+const loadPowerSearchBottomSheet = async () => import("./PowerSearchBottomSheet.js");
+const LazyPowerSearchBottomSheet = /*#__PURE__*/lazy(async () => loadPowerSearchBottomSheet().then(module => ({
+  default: module.PowerSearchBottomSheet
+})));
+// The value step reuses the popover presentation's editors, which this
+// module already loads; see PowerSearchSheetEditors.
+const SHEET_EDITORS = {
+  NestedEditor,
+  PowerSearchValueEditor,
+  buildRelativeDateOptions
+};
 
 /**
- * The visible text of a filter token's value. The token renders it, and the
- * token's remove button and editor dialog are named by the same text.
+ * Hosts the lazily loaded sheet flow. 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 flow
+ * has no visible markup, so it first renders right after hydration.
  */
-function tokenValueText(operatorValue, filterValue, maxLength, locale) {
-  switch (filterValue.type) {
-    case 'empty':
-      return null;
-    case 'string':
-      return truncateString(filterValue.value, maxLength);
-    case 'integer':
-    case 'float':
-      return String(filterValue.value);
-    case 'enum':
-      if (operatorValue.type === 'enum') {
-        return truncateString(getEnumLabel(operatorValue.values, filterValue.value), maxLength);
-      }
-      return truncateString(filterValue.value, maxLength);
-    case 'string_list':
-      {
-        const items = filterValue.value;
-        if (items.length === 0) {
-          return null;
-        }
-        if (items.length === 1) {
-          return truncateString(items[0], maxLength);
-        }
-        const totalLength = items.reduce((sum, s) => sum + s.length, 0);
-        if (totalLength > maxLength) {
-          return `${items.length} items`;
-        }
-        return items.join(', ');
-      }
-    case 'enum_list':
-      {
-        const items = filterValue.value;
-        if (items.length === 0) {
-          return null;
-        }
-        if (operatorValue.type === 'enum_list') {
-          const labels = items.map(v => getEnumLabel(operatorValue.values, v));
-          if (labels.length === 1) {
-            return truncateString(labels[0], maxLength);
-          }
-          const totalLength = labels.reduce((sum, s) => sum + s.length, 0);
-          if (totalLength > maxLength) {
-            return `${labels.length} items`;
-          }
-          return labels.join(', ');
-        }
-        if (items.length === 1) {
-          return truncateString(items[0], maxLength);
-        }
-        return `${items.length} items`;
-      }
-    case 'entity_list':
-      {
-        const entities = filterValue.value;
-        if (entities.length === 0) {
-          return null;
-        }
-        if (entities.length === 1) {
-          return truncateString(entities[0].label, maxLength);
-        }
-        const totalLength = entities.reduce((sum, e) => sum + e.label.length, 0);
-        if (totalLength > maxLength) {
-          return `${entities.length} items`;
-        }
-        return entities.map(e => e.label).join(', ');
-      }
-    case 'time':
-      return filterValue.value;
-    case 'date_absolute':
-      return truncateString(formatDateAbsoluteCompact(filterValue.unixSeconds, locale), maxLength);
-    case 'date_relative':
-      return truncateString(filterValue.value, maxLength);
-    case 'date_range':
-      return 'date range';
-    case 'custom':
-      if (operatorValue.type === 'custom') {
-        return truncateString(operatorValue.getString(filterValue.value), maxLength);
-      }
-      return filterValue.value;
-    case 'nested':
-      {
-        const count = filterValue.value.length;
-        return count === 1 ? '1 filter' : `${count} filters`;
-      }
-    default:
-      return null;
+function PowerSearchSheetHost(props) {
+  const isHydrating = useIsHydrating();
+  if (isHydrating) {
+    return null;
   }
+  return /*#__PURE__*/_jsx(Suspense, {
+    fallback: null,
+    children: /*#__PURE__*/_jsx(LazyPowerSearchBottomSheet, {
+      ...props,
+      editors: SHEET_EDITORS
+    })
+  });
 }
 function PowerSearchTokenValue({
   text
@@ -199,6 +181,8 @@ function PowerSearchTokenValue({
 // Types
 // =============================================================================
 
+/** How PowerSearch presents filter editing; see `PowerSearchProps.presentation`. */
+
 // =============================================================================
 // State
 // =============================================================================
@@ -314,7 +298,8 @@ export function PowerSearch({
   xstyle,
   className,
   style,
-  components: componentOverrides
+  components: componentOverrides,
+  presentation = 'adaptive'
 }) {
   const size = useSize(sizeProp, 'md');
   const config = useInternalConfig(configProp);
@@ -325,6 +310,81 @@ export function PowerSearch({
   const placeholder = placeholderFromProps ?? t('@astryx.powersearch.placeholder');
   const popoverSaveButtonLabel = popoverSaveButtonLabelFromProps ?? t('@astryx.powersearch.editor.apply');
   const tokenizerRef = useRef(null);
+  const resolvedPresentation = useAdaptivePresentation(presentation);
+  const [isSheetOpen, setIsSheetOpen] = useState(false);
+  // Latched for the flow's lifetime: the flow stays presented after it closes
+  // until the sheets have run their 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 sheets and the trigger they return
+  // focus to in the same render, dropping focus to the page body.
+  const [isSheetPresented, setIsSheetPresented] = useState(false);
+  const isSheetPresentation = isSheetOpen || isSheetPresented || resolvedPresentation === 'bottom-sheet';
+  const triggerRef = useRef(null);
+  // `hasAutoFocus` applies only to the control the field first mounts. A
+  // presentation swap remounts the control (combobox input or trigger), and
+  // React's `autoFocus` on the new one would pull focus from wherever on the
+  // page it was; the roots' callback refs hand over the focus the field held
+  // instead. A field that never swaps keeps `autoFocus` on every render, so a
+  // Dialog that keeps it mounted still finds its `data-autofocus` on open.
+  const [autoFocusState, setAutoFocusState] = useState({
+    presentation: isSheetPresentation,
+    isFirstControl: true
+  });
+  if (autoFocusState.presentation !== isSheetPresentation) {
+    setAutoFocusState({
+      presentation: isSheetPresentation,
+      isFirstControl: false
+    });
+  }
+  const autoFocusOnMount = hasAutoFocus && autoFocusState.isFirstControl && autoFocusState.presentation === isSheetPresentation;
+  // A focus the swap moves continues the same visit to the field: the
+  // control that held focus is gone (no blur fires for a removed element), so
+  // the caller is told of neither a blur nor a new focus.
+  const isSwapFocusRef = useRef(false);
+  const focusAfterSwap = useCallback(control => {
+    if (control == null) {
+      return;
+    }
+    isSwapFocusRef.current = true;
+    try {
+      control.focus();
+    } finally {
+      isSwapFocusRef.current = false;
+    }
+  }, []);
+  const handleFieldFocus = useCallback(event => {
+    if (!isSwapFocusRef.current) {
+      onFocus?.(event);
+    }
+  }, [onFocus]);
+  const handleFieldBlur = useCallback(event => {
+    onBlur?.(event);
+  }, [onBlur]);
+  // While the flow is open, the sheet announces its own content from inside
+  // its dialog; this component announces only with the flow closed, and
+  // `useAnnounce` routes those messages by where the field is — into a Dialog
+  // or modal Drawer that holds it, or the shared channel when no modal does.
+  // A result count that changed during the flow's exit is spoken once the
+  // flow has fully closed and focus is back on the trigger: the closing
+  // dialog stays modal through its exit, so neither its region nor the
+  // page-body channel is heard before.
+  const afterCloseResultCountRef = useRef(null);
+  const triggerId = useId();
+  const triggerLabelId = useId();
+  const triggerContentId = useId();
+  const statusMessageId = useId();
+  // A field that becomes disabled cannot keep its flow open, and must not
+  // reopen it when re-enabled. Adjusted in the
+  // render that sees the change, not an effect, so no frame shows both.
+  const [wasDisabled, setWasDisabled] = useState(isDisabled);
+  if (isDisabled !== wasDisabled) {
+    setWasDisabled(isDisabled);
+    if (isDisabled && isSheetOpen) {
+      setIsSheetOpen(false);
+    }
+  }
+  useDevWarning('PowerSearch', '`menuWidth` has no surface in the bottom-sheet presentation: the sheet flow has no typeahead popover to size. Pass `presentation="popover"` to keep the popover on every device, or leave it out.', isSheetPresentation && menuWidth != null);
+  useDevWarning('PowerSearch', '`tokenOverflowBehavior` has no surface in the bottom-sheet presentation: the trigger wraps its display-only tokens. Pass `presentation="popover"` to keep the tokenizer field on every device, or leave it out.', isSheetPresentation && tokenOverflowBehavior != null);
   const [popoverState, setPopoverStateRaw] = useState({
     type: 'idle'
   });
@@ -338,21 +398,35 @@ export function PowerSearch({
     const fieldLabel = field?.label ?? '';
     const operatorLabel = operator ? resolveOperatorLabel(operator, t) : '';
     const label = `${fieldLabel}: ${operatorLabel}`.trim();
-    const value = operator ? tokenValueText(operator.value, filter.value, Math.max(maxTokenLength - fieldLabel.length - operatorLabel.length, 10), locale) : null;
+    const value = operator ? formatTokenValueText(operator.value, filter.value, Math.max(maxTokenLength - fieldLabel.length - operatorLabel.length, 10), locale, undefined, undefined, timezoneID) : null;
     return {
       label,
       value,
       full: value != null ? `${label} ${value}` : label
     };
-  }, [config, maxTokenLength, t, locale]);
+  }, [config, maxTokenLength, t, locale, timezoneID]);
   // The built-in token being edited. A token from a `components` override
   // names itself, so its editor keeps the plain popover.
   const editedFilter = popoverState.type === 'editing' ? filters[popoverState.filterIndex] : undefined;
   const editedOperator = editedFilter != null ? config.getOperator(editedFilter.field, editedFilter.operator) : undefined;
   const editedBuiltInFilter = editedOperator == null || componentOverrides?.[editedOperator.value.type]?.Token == null ? editedFilter : undefined;
+  // Whether the editor popover is open, for the hand-off below, which runs
+  // in the commit that swaps presentations.
+  const isPopoverOpenRef = useRef(false);
+  // When `adaptive` flips to the sheet while the editor popover is open (a
+  // phone rotated), the editing ends with the popover: its state returns to
+  // idle (through the raw setter, since the tokenizer input is gone), in the
+  // render that sees the swap, so a later switch back does not reopen a stale
+  // editor.
+  if (isSheetPresentation && popoverState.type !== 'idle') {
+    setPopoverStateRaw({
+      type: 'idle'
+    });
+  }
 
   // Layer for positioning the edit popover anchored to the tokenizer
   const handleLayerHide = useCallback(() => {
+    isPopoverOpenRef.current = false;
     setPopoverStateRaw({
       type: 'idle'
     });
@@ -371,8 +445,47 @@ export function PowerSearch({
     dialogLabel: editedBuiltInFilter != null ? tokenText(editedBuiltInFilter).full : undefined
   });
 
+  // A presentation swap removes the focused control, so the other
+  // presentation's primary control (the combobox input or the trigger) takes
+  // focus and focus never falls to the page body. Each presentation keys its
+  // root, so a swap mounts a new root. The detaching root notes that it held
+  // focus, which also covers an input focused by server-rendered `autofocus`
+  // before hydration. The editor popover is portaled outside the root, so an
+  // open editor counts as held focus. The attaching root gives focus to its
+  // primary control when focus has fallen to the page body; the sheet root
+  // also hides a popover layer left open.
+  const isFocusPendingHandOffRef = useRef(false);
+  const hidePopover = popover.hide;
+  const handOffFocusRef = useCallback(node => {
+    if (node == null) {
+      return;
+    }
+    const trigger = triggerRef.current;
+    const isSheetRoot = trigger != null && node.contains(trigger);
+    // The sheet presentation preloads the flow's chunk, so the first press
+    // opens without waiting for the network; nothing renders.
+    if (isSheetRoot) {
+      void loadPowerSearchBottomSheet();
+    }
+    if (isSheetRoot && isPopoverOpenRef.current) {
+      isPopoverOpenRef.current = false;
+      hidePopover();
+    }
+    const takesFocus = isFocusPendingHandOffRef.current;
+    isFocusPendingHandOffRef.current = false;
+    if (takesFocus && isFocusDetached(node.ownerDocument)) {
+      focusAfterSwap(isSheetRoot ? trigger : tokenizerRef.current);
+    }
+    return () => {
+      if (node.contains(node.ownerDocument.activeElement) || isPopoverOpenRef.current) {
+        isFocusPendingHandOffRef.current = true;
+      }
+    };
+  }, [focusAfterSwap, hidePopover]);
+
   // Wrapper that manages layer visibility and tokenizer focus alongside state
   const setPopoverState = useCallback(state => {
+    isPopoverOpenRef.current = state.type !== 'idle';
     setPopoverStateRaw(state);
     if (state.type !== 'idle') {
       // Schedule after the current frame so React can render the popover
@@ -387,13 +500,22 @@ export function PowerSearch({
     }
   }, [popover]);
 
-  // Expose imperative handle
+  // Expose imperative handle; in the sheet presentation the trigger is the
+  // field's focusable control.
   useImperativeHandle(handleRef, () => ({
     focusTypeahead() {
-      tokenizerRef.current?.focus();
+      if (isSheetPresentation) {
+        triggerRef.current?.focus();
+      } else {
+        tokenizerRef.current?.focus();
+      }
     },
     blurTypeahead() {
-      tokenizerRef.current?.blur();
+      if (isSheetPresentation) {
+        triggerRef.current?.blur();
+      } else {
+        tokenizerRef.current?.blur();
+      }
     }
   }));
 
@@ -554,15 +676,17 @@ export function PowerSearch({
     });
   }, [setPopoverState]);
 
-  // Custom token renderer
-  // Custom token renderer
-  const renderToken = useCallback((item, onRemove) => {
+  // Token renderer for both presentations. Given `onRemove`, the token is
+  // the tokenizer field's: click edits, × removes. Without it (the sheet
+  // presentation's trigger) the token is display-only; the field as a whole
+  // opens the flow.
+  const renderFilterToken = useCallback((item, onRemove) => {
     const auxData = item.auxiliaryData;
     const filterIndex = auxData?.filterIndex ?? -1;
     const filter = filterIndex >= 0 ? filters[filterIndex] : undefined;
     const field = auxData ? config.getField(auxData.fieldKey) : undefined;
     const operator = auxData?.operatorKey ? config.getOperator(auxData.fieldKey, auxData.operatorKey) : undefined;
-    const canInteract = !isReadOnly && !isDisabled && !filter?.isReadOnly;
+    const canInteract = onRemove != null && !isReadOnly && !isDisabled && !filter?.isReadOnly;
     const handleClick = canInteract ? () => handleTokenClick(filterIndex) : undefined;
     const handleRemove = canInteract ? onRemove : undefined;
 
@@ -577,7 +701,8 @@ export function PowerSearch({
         maxLength: maxTokenLength,
         onClick: handleClick,
         onRemove: handleRemove,
-        isDisabled: isDisabled
+        isDisabled: isDisabled,
+        timezoneID: timezoneID
       });
     }
 
@@ -635,7 +760,8 @@ export function PowerSearch({
         isDisabled: isDisabled
       })
     });
-  }, [filters, config, configProp, maxTokenLength, size, isReadOnly, isDisabled, handleTokenClick, componentOverrides, t, popoverState, tokenText]);
+  }, [timezoneID, filters, config, configProp, maxTokenLength, size, isReadOnly, isDisabled, handleTokenClick, componentOverrides, t, popoverState, tokenText]);
+  const renderToken = useCallback((item, onRemove) => renderFilterToken(item, onRemove), [renderFilterToken]);
 
   // Custom typeahead item renderer — adds field icon and description
   const renderItem = useCallback(item => {
@@ -692,7 +818,8 @@ export function PowerSearch({
         onSave: handlePopoverSave,
         onCancel: handlePopoverCancel,
         saveButtonLabel: popoverSaveButtonLabel,
-        isReadOnly: isReadOnly
+        isReadOnly: isReadOnly,
+        timezoneID: timezoneID
       }, popoverKey);
     }
     return /*#__PURE__*/_jsx(PowerSearchEditPopover, {
@@ -703,9 +830,10 @@ export function PowerSearch({
       onCancel: handlePopoverCancel,
       saveButtonLabel: popoverSaveButtonLabel,
       maxMenuItems: maxOperatorMenuItems,
-      isReadOnly: isReadOnly
+      isReadOnly: isReadOnly,
+      timezoneID: timezoneID
     }, popoverKey);
-  }, [popoverPartialFilter, popoverState, EditorOverride, configProp, config, handlePopoverSave, handlePopoverCancel, popoverSaveButtonLabel, maxOperatorMenuItems, isReadOnly]);
+  }, [timezoneID, popoverPartialFilter, popoverState, EditorOverride, configProp, config, handlePopoverSave, handlePopoverCancel, popoverSaveButtonLabel, maxOperatorMenuItems, isReadOnly]);
 
   // Plain-text form of the result count, shared by the visible label and the
   // screen-reader announcement so the two never drift. The ICU plural handles
@@ -723,28 +851,38 @@ export function PowerSearch({
     return resultCount;
   }, [resultCount, t]);
 
-  // Announce result-count changes to screen readers through a polite live
-  // region, mirroring the way Typeahead announces its dropdown result count.
-  // The count is otherwise only shown visually and stays silent to assistive
-  // tech. Only a change after mount is spoken: the guard compares against the
-  // last announced text rather than a mounted flag, so StrictMode's effect
-  // replay (which resets a flag and would speak the count present on mount
-  // unprompted) announces nothing until the count changes.
+  // This Effect synchronizes a polite live region with the result count,
+  // mirroring the way Typeahead announces its dropdown result count: the count
+  // is otherwise only shown visually and stays silent to assistive tech. The
+  // region follows where the field is: the modal that holds the field (a
+  // Dialog, a modal Drawer), else the shared channel. While a sheet of the flow is open the sheet itself announces the
+  // count from inside its dialog, and this Effect stays quiet. Only a
+  // change after mount is spoken — the count present on mount is not
+  // announced unprompted — and the guard compares against the last announced
+  // text rather than a mounted flag, so StrictMode's effect replay announces
+  // nothing either. A change that lands while the flow is closing waits for
+  // the trigger focus, since the dialog is still modal through its exit. The
+  // announcement acquires no resource, so there is no cleanup.
   const announce = useAnnounce();
   // PowerSearch words its Clear all as its record does; the field announces
   // these words instead of Tokenizer's (component:Tokenizer AR7).
   const hasReadOnlyFilter = filters.some(filter => filter.isReadOnly);
   const clearAllMessage = useMemo(() => hasReadOnlyFilter ? t('@astryx.powersearch.editableFiltersRemoved') : t('@astryx.powersearch.allFiltersRemoved'), [hasReadOnlyFilter, t]);
   const announcedResultCountRef = useRef(resultCountText);
+  const isSheetExiting = isSheetPresented && !isSheetOpen;
   useEffect(() => {
     if (resultCountText === announcedResultCountRef.current) {
       return;
     }
     announcedResultCountRef.current = resultCountText;
     if (resultCountText != null) {
-      announce(resultCountText);
+      if (isSheetExiting) {
+        afterCloseResultCountRef.current = resultCountText;
+      } else if (!isSheetOpen) {
+        announce(resultCountText);
+      }
     }
-  }, [resultCountText, announce]);
+  }, [resultCountText, announce, isSheetExiting, isSheetOpen]);
 
   // Build combined endContent from resultCount + endContent props
   const combinedEndContent = useMemo(() => {
@@ -763,9 +901,177 @@ export function PowerSearch({
     }
     return resultCountNode || endContent || undefined;
   }, [resultCountText, endContent]);
+
+  // ------------------------------------------------------- sheet trigger --
+
+  // Disabled-reason tooltip for the sheet trigger. Disabled controls swallow
+  // pointer events, so the listeners attach to the field's control box; the
+  // trigger stays perceivable through aria-disabled.
+  const showsDisabledMessage = isDisabled && !!disabledMessage;
+  const disabledMessageTooltip = useTooltip({
+    placement: 'above',
+    focusTrigger: 'always',
+    isEnabled: isSheetPresentation && showsDisabledMessage
+  });
+  const rootRef = useMergedRefs(ref, popover.triggerRef, handOffFocusRef);
+  const openSheet = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    // The flow restores focus to the element that was active when it opened;
+    // make sure that is the trigger even for a tap on a token.
+    triggerRef.current?.focus({
+      preventScroll: true
+    });
+    setIsSheetPresented(true);
+    setIsSheetOpen(true);
+  }, [isDisabled]);
+
+  // The field's end lane — the result count and `endContent` — sits outside
+  // the trigger button: a caller's action button there keeps its own tab stop
+  // and taps, and an interactive control must not nest in a component
+  // button, so a tap on it must not open the flow.
+  const endLaneRef = useRef(null);
+  const handleTriggerWrapperClick = useCallback(event => {
+    // Tokens are display-only; a tap on them or the empty space around them
+    // opens the flow. The trigger button handles its own click, and the end
+    // lane handles its own.
+    if (event.target instanceof Node && (triggerRef.current?.contains(event.target) || endLaneRef.current?.contains(event.target))) {
+      return;
+    }
+    openSheet();
+  }, [openSheet]);
+  const handleTriggerFocusWithin = useCallback(event => {
+    // The flow focuses the trigger only after its exit completes; that focus
+    // is the signal that the retained sheets can leave. If the resolution
+    // moved to the popover meanwhile, the tokenizer input takes over the
+    // focus once it mounts (the hand-off above).
+    if (!isSheetOpen && isSheetPresented) {
+      setIsSheetPresented(false);
+      // The dialogs have closed: the page-body channel is exposed again.
+      const resultCount = afterCloseResultCountRef.current;
+      afterCloseResultCountRef.current = null;
+      if (resultCount != null) {
+        announce(resultCount);
+      }
+    }
+    if (!(event.relatedTarget instanceof Node) || !event.currentTarget.contains(event.relatedTarget)) {
+      handleFieldFocus(event);
+    }
+  }, [announce, handleFieldFocus, isSheetOpen, isSheetPresented]);
+  const handleTriggerBlurWithin = useCallback(event => {
+    if (!(event.relatedTarget instanceof Node) || !event.currentTarget.contains(event.relatedTarget)) {
+      handleFieldBlur(event);
+    }
+  }, [handleFieldBlur]);
+  if (isSheetPresentation) {
+    const triggerDescribedBy = [status?.message ? statusMessageId : null, showsDisabledMessage ? disabledMessageTooltip.describedBy : null].filter(Boolean).join(' ') || undefined;
+    return /*#__PURE__*/_jsxs("div", {
+      ref: rootRef,
+      ...themeProps('power-search'),
+      children: [/*#__PURE__*/_jsxs(Field, {
+        label: label,
+        isLabelHidden: isLabelHidden,
+        inputID: triggerId,
+        labelID: triggerLabelId,
+        isDisabled: isDisabled,
+        status: status ? {
+          type: status.type,
+          message: status.message,
+          messageID: status.message ? statusMessageId : undefined
+        } : undefined,
+        statusVariant: statusVariant,
+        xstyle: xstyle,
+        className: className,
+        style: style,
+        children: [/*#__PURE__*/_jsxs("div", {
+          ref: disabledMessageTooltip.ref,
+          onClick: handleTriggerWrapperClick,
+          onFocus: handleTriggerFocusWithin,
+          onBlur: handleTriggerBlurWithin,
+          "aria-disabled": isDisabled ? true : undefined,
+          ...stylex.props(inputWrapperStyles.base, sheetTriggerStyles.wrapper, filters.length > 0 && sheetTriggerStyles.wrapperWithTokens, sheetTriggerSizeStyles[size], isDisabled && inputWrapperStyles.disabled, status && inputStatusBorderStyles[status.type], status && !isDisabled && inputStatusHoverShadowStyles[status.type], status && inputStatusFocusWithinStyles[status.type]),
+          children: [/*#__PURE__*/_jsxs("div", {
+            id: triggerContentId,
+            ...{
+              className: "x1n2onr6 xeuugli x1iyjqo2 x78zum5 x6s0dn4 x1a02dak x1lfs0n9 xajebq8"
+            },
+            children: [isRenderable(startIcon) && /*#__PURE__*/_jsx("span", {
+              ...{
+                0: {},
+                1: {
+                  className: "x1xrm450"
+                }
+              }[!!(filters.length > 0) << 0],
+              children: renderIconSlot(startIcon, {
+                size: 'sm',
+                color: 'secondary'
+              })
+            }), tokenizerValue.map(item => /*#__PURE__*/_jsx(React.Fragment, {
+              children: renderFilterToken(item, undefined)
+            }, item.id)), /*#__PURE__*/_jsx("button", {
+              type: "button",
+              id: triggerId,
+              ref: triggerRef
+              // The field's primary control: `data-testid` lands here, as it
+              // lands on the combobox input in the popover presentation.
+              ,
+              "data-testid": testId,
+              autoFocus: autoFocusOnMount,
+              onClick: openSheet,
+              "aria-disabled": isDisabled ? true : undefined,
+              "aria-haspopup": "dialog",
+              "aria-expanded": isSheetOpen,
+              "aria-labelledby": `${triggerLabelId} ${triggerContentId}`,
+              "aria-describedby": triggerDescribedBy,
+              ...{
+                0: {
+                  className: "xjyslct xfoc8du x1fns5xo xkh2ocl x78zum5 x6s0dn4 xt970qd x7a5moj x1ghz6dp xc342km xng3xce xjbqb8w xv1l7n4 x9ynric xjm74w1 xw6l6zx x1yc453h xuxw1ft x1ypdohk xvivl9a x1a2a7pz"
+                },
+                1: {
+                  className: "xjyslct xfoc8du xkh2ocl x78zum5 x6s0dn4 xt970qd x7a5moj x1ghz6dp xc342km xng3xce xjbqb8w xv1l7n4 x9ynric xjm74w1 xw6l6zx x1yc453h xuxw1ft x1ypdohk xvivl9a x1a2a7pz x10l6tqk x10a8y8t xeuugli x1717udv"
+                }
+              }[!!(filters.length > 0) << 0],
+              children: filters.length === 0 ? placeholder : null
+            })]
+          }), (endContent || isRenderable(resultCountText)) && /*#__PURE__*/_jsxs("div", {
+            ref: endLaneRef,
+            ...{
+              className: "x78zum5 x6s0dn4 x1txdalj x2lah0s x1nryj5t"
+            },
+            children: [isRenderable(resultCountText) && /*#__PURE__*/_jsx("span", {
+              ...{
+                className: "x141an7d x1ltkj2j xv1l7n4 xuxw1ft"
+              },
+              children: resultCountText
+            }), endContent]
+          })]
+        }), showsDisabledMessage && disabledMessageTooltip.renderTooltip(disabledMessage)]
+      }), (isSheetOpen || isSheetPresented) && /*#__PURE__*/_jsx(PowerSearchSheetHost, {
+        isOpen: isSheetOpen,
+        onOpenChange: setIsSheetOpen,
+        finalFocusRef: triggerRef,
+        resultCountText: resultCountText,
+        config: config,
+        configProp: configProp,
+        filters: filters,
+        onChange: onChange,
+        searchSource: searchSource,
+        placeholder: placeholder,
+        isReadOnly: isReadOnly,
+        isDisabled: isDisabled,
+        hasClear: hasClear,
+        maxOperatorMenuItems: maxOperatorMenuItems,
+        timezoneID: timezoneID,
+        maxSearchResults: maxSearchResults,
+        saveButtonLabel: popoverSaveButtonLabelFromProps,
+        components: componentOverrides
+      })]
+    }, "sheet");
+  }
   return /*#__PURE__*/_jsxs(_Fragment, {
     children: [/*#__PURE__*/_jsx("div", {
-      ref: useMergedRefs(ref, popover.triggerRef),
+      ref: rootRef,
       ...themeProps('power-search'),
       children: /*#__PURE__*/_jsx(TokenizerClearAllMessageContext, {
         value: clearAllMessage,
@@ -783,7 +1089,7 @@ export function PowerSearch({
             maxMenuItems: MAX_BROWSE_MENU_ITEMS,
             menuWidth: menuWidth,
             placeholder: filters.length === 0 ? placeholder : '',
-            hasAutoFocus: hasAutoFocus,
+            hasAutoFocus: autoFocusOnMount,
             hasClear: hasClear && !isReadOnly,
             startIcon: startIcon,
             endContent: combinedEndContent,
@@ -795,16 +1101,17 @@ export function PowerSearch({
             debounceMs: 0,
             status: status,
             statusVariant: statusVariant,
-            onFocus: onFocus,
-            onBlur: onBlur,
+            onFocus: handleFieldFocus,
+            onBlur: handleFieldBlur,
             containerXstyle: xstyle,
             containerClassName: className,
             containerStyle: style,
-            "data-testid": testId
+            "data-testid": testId,
+            presentation: "popover"
           })
         })
       })
-    }), popover.render(popoverContent, {
+    }, "popover"), popover.render(popoverContent, {
       placement: 'below',
       alignment: 'start',
       offset: spacingVars['--spacing-1'],