@astryxdesign/core 0.7.7 → 0.7.8-canary.30b1896

package/src/PowerSearch/PowerSearch.tsx

@@ -4,19 +4,25 @@
 
 /**
  * @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 experimental `presentation` option 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, {
+  lazy,
+  Suspense,
   useCallback,
   useEffect,
+  useId,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -37,30 +43,45 @@ import {Token} from '../Token';
 import {TokenNamingContext} from '../Token/TokenNamingContext';
 import {Avatar} from '../Avatar';
 import {layerAnimations} from '../Layer/layerAnimations.stylex';
-import {Icon} from '../Icon';
+import {Icon, renderIconSlot} from '../Icon';
 import type {IconType} from '../Icon';
 import type {IconName} from '../Icon/globalIconRegistry';
 import type {InputStatus} from '../Field';
+import {Field} from '../Field/Field';
+import {
+  inputStatusBorderStyles,
+  inputStatusFocusWithinStyles,
+  inputStatusHoverShadowStyles,
+  inputWrapperStyles,
+} from '../Field/inputStyles.stylex';
 import {usePopover} from '../Popover/usePopover';
+import {useTooltip} from '../Tooltip/useTooltip';
 import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
 import {useAnnounce} from '../hooks/useAnnounce';
+import {useAdaptivePresentation} from '../hooks/useAdaptivePresentation';
+import {useDevWarning} from '../hooks/useDevWarning';
+import {useIsHydrating} from '../hooks/useIsHydrating';
 import {
   spacingVars,
   colorVars,
+  sizeVars,
   typeScaleVars,
+  typographyVars,
   fontWeightVars,
 } from '../theme/tokens.stylex';
 import {useSize} from '../SizeContext/SizeContext';
+import {isFocusDetached} from '../utils/focusReturn';
+import {isRenderable} from '../utils/isRenderable';
 import {useInternalConfig} from './useInternalConfig';
 import {usePowerSearchSource} from './usePowerSearchSource';
+import {formatFilterValue} from './formatFilterValue';
+import {NestedEditor, PowerSearchEditPopover} from './PowerSearchEditPopover';
 import {
-  formatFilterValue,
-  formatDateAbsoluteCompact,
-} from './formatFilterValue';
-import {PowerSearchEditPopover} from './PowerSearchEditPopover';
+  buildRelativeDateOptions,
+  PowerSearchValueEditor,
+} from './PowerSearchValueEditor';
 import {resolveOperatorLabel} from './resolveOperatorLabel';
 import {themeProps} from '../utils/themeProps';
-import {truncateCharacters} from '../utils/characters';
 import {useLocale} from '../i18n/useLocale';
 import type {Locale} from '../i18n/types';
 import type {SearchableItem} from '../Typeahead/types';
@@ -74,10 +95,14 @@ import type {
   PowerSearchHandle,
   FilterValue,
   OperatorValue,
-  EnumItem,
   PowerSearchComponents,
   PowerSearchOperator,
 } from './types';
+import type {
+  PowerSearchBottomSheetProps,
+  PowerSearchSheetEditors,
+} from './PowerSearchBottomSheet';
+import {formatTokenValueText} from './formatTokenValue';
 
 import {useMergedRefs} from '../hooks/useMergedRefs';
 import type {FieldStatusPlacement} from '../Field/fieldStatusPlacement';
@@ -150,130 +175,127 @@ const resultCountStyles = stylex.create({
   },
 });
 
-function truncateString(value: string, limit: number): string {
-  // 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, '...');
-}
+// 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 = stylex.create({
+  sm: {minHeight: sizeVars['--size-element-sm']},
+  md: {minHeight: sizeVars['--size-element-md']},
+  lg: {minHeight: sizeVars['--size-element-lg']},
+});
 
-function getEnumLabel(values: ReadonlyArray<EnumItem>, value: string): string {
-  return values.find(v => v.value === value)?.label ?? value;
-}
+const sheetTriggerStyles = stylex.create({
+  wrapper: {
+    position: 'relative',
+    flexWrap: 'nowrap',
+    gap: spacingVars['--spacing-1'],
+    height: 'auto',
+    cursor: {
+      default: 'pointer',
+      ':is([aria-disabled="true"])': 'default',
+    },
+  },
+  wrapperWithTokens: {
+    paddingBlock: `calc(${spacingVars['--spacing-1']} - 1px)`,
+    paddingInline: `calc(${spacingVars['--spacing-1']} - 1px)`,
+  },
+  contentSection: {
+    position: 'relative',
+    minWidth: 0,
+    flexGrow: 1,
+    display: 'flex',
+    alignItems: 'center',
+    flexWrap: 'wrap',
+    columnGap: spacingVars['--spacing-1'],
+    rowGap: `calc(${spacingVars['--spacing-1']} - 1px)`,
+  },
+  startIconWithTokens: {
+    marginInlineStart: `calc(${spacingVars['--spacing-2']} - ${spacingVars['--spacing-1']} + 1px)`,
+  },
+  // The only tab stop in the field. It stays visually borderless while the
+  // wrapper delegates taps on tokens and empty space to it.
+  trigger: {
+    appearance: 'none',
+    flex: '1 1 40px',
+    minWidth: '40px',
+    alignSelf: 'stretch',
+    display: 'flex',
+    alignItems: 'center',
+    paddingBlock: 0,
+    paddingInline: spacingVars['--spacing-1'],
+    margin: 0,
+    borderWidth: 0,
+    borderStyle: 'none',
+    backgroundColor: 'transparent',
+    color: colorVars['--color-text-secondary'],
+    fontFamily: typographyVars['--font-family-body'],
+    fontSize: typeScaleVars['--text-body-size'],
+    lineHeight: typeScaleVars['--text-body-leading'],
+    textAlign: 'start',
+    whiteSpace: 'nowrap',
+    cursor: {
+      default: 'pointer',
+      ':is([aria-disabled="true"])': 'default',
+    },
+    outline: 'none',
+  },
+  // Once a token is present the empty trigger covers the token lane instead
+  // of reserving 40px or wrapping onto an otherwise blank row.
+  triggerWithTokens: {
+    position: 'absolute',
+    inset: 0,
+    minWidth: 0,
+    padding: 0,
+  },
+  endSection: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-2'],
+    flexShrink: 0,
+    paddingInlineEnd: spacingVars['--spacing-1'],
+  },
+});
+
+// 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');
+const LazyPowerSearchBottomSheet = 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: PowerSearchSheetEditors = {
+  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: OperatorValue,
-  filterValue: FilterValue,
-  maxLength: number,
-  locale: Locale,
-): string | null {
-  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: Omit<PowerSearchBottomSheetProps, 'editors'>,
+) {
+  const isHydrating = useIsHydrating();
+  if (isHydrating) {
+    return null;
   }
+  return (
+    <Suspense fallback={null}>
+      <LazyPowerSearchBottomSheet {...props} editors={SHEET_EDITORS} />
+    </Suspense>
+  );
 }
 
 function PowerSearchTokenValue({text}: {text: string}) {
@@ -356,7 +378,13 @@ export interface PowerSearchProps extends Omit<
   maxSearchResults?: number;
   /** Label for the save button in edit popover. @default 'Apply' */
   popoverSaveButtonLabel?: string;
-  /** Timezone ID for date formatting. */
+  /**
+   * IANA zone a date-only `date_absolute` value, and each absolute part of a
+   * `date_range`, is read and written in: the token, the label and the editor
+   * show its day there, and a picked day stores as that midnight. Unset, a
+   * day is its UTC day. A `date_absolute` with `isDateOnly: false` formats
+   * its label in it.
+   */
   timezoneID?: string;
   /**
    * Controls how tokens overflow when the container is too narrow.
@@ -388,6 +416,37 @@ export interface PowerSearchProps extends Omit<
    * Keys are operator value types (e.g. 'string', 'enum', 'date_absolute').
    */
   components?: PowerSearchComponents;
+
+  /**
+   * 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 filter editing.
+     * - `'popover'`: the tokenizer field with its typeahead and the editor
+     *   popover — the stable behavior.
+     * - `'bottom-sheet'`: the whole field is one trigger showing display-only
+     *   filter tokens; it opens a stack of sheets. Filters lists the filters
+     *   as rows that edit or remove one, with Add filter, Done, and Clear
+     *   all, which asks first and keeps read-only filters. Add filter opens
+     *   above it with the fields (or the content search with inline
+     *   suggestions), and a value step opens above that, stages operator →
+     *   value, and confirms from its footer. Dismissing a step reveals the
+     *   one beneath. Suited to compact touch screens, where the editor
+     *   popover 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 `menuWidth` and `tokenOverflowBehavior` have
+     * no surface to act on and warn in development.
+     * @experimental
+     * @default 'popover'
+     */
+    presentation?: 'popover' | 'bottom-sheet' | 'adaptive';
+  };
 }
 
 // =============================================================================
@@ -524,6 +583,7 @@ export function PowerSearch({
   className,
   style,
   components: componentOverrides,
+  experimental,
 }: PowerSearchProps) {
   const size = useSize(sizeProp, 'md');
   const config = useInternalConfig(configProp);
@@ -537,6 +597,105 @@ export function PowerSearch({
     popoverSaveButtonLabelFromProps ?? t('@astryx.powersearch.editor.apply');
   const tokenizerRef = useRef<TokenizerHandle>(null);
 
+  // Experimental presentation. `adaptive`
+  // resolves through the policy the selection controls share; an open flow
+  // 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 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<HTMLButtonElement>(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: {focus(): void} | null) => {
+    if (control == null) {
+      return;
+    }
+    isSwapFocusRef.current = true;
+    try {
+      control.focus();
+    } finally {
+      isSwapFocusRef.current = false;
+    }
+  }, []);
+  const handleFieldFocus = useCallback(
+    (event: React.FocusEvent) => {
+      if (!isSwapFocusRef.current) {
+        onFocus?.(event);
+      }
+    },
+    [onFocus],
+  );
+  const handleFieldBlur = useCallback(
+    (event: React.FocusEvent) => {
+      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<string | null>(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. Scope it to the popover presentation 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. Scope it to the popover presentation or leave it out.',
+    isSheetPresentation && tokenOverflowBehavior != null,
+  );
+
   const [popoverState, setPopoverStateRaw] = useState<PopoverState>({
     type: 'idle',
   });
@@ -552,7 +711,7 @@ export function PowerSearch({
       const operatorLabel = operator ? resolveOperatorLabel(operator, t) : '';
       const label = `${fieldLabel}: ${operatorLabel}`.trim();
       const value = operator
-        ? tokenValueText(
+        ? formatTokenValueText(
             operator.value,
             filter.value,
             Math.max(
@@ -560,11 +719,14 @@ export function PowerSearch({
               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.
@@ -581,9 +743,21 @@ export function PowerSearch({
     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'});
   }, []);
 
@@ -604,9 +778,54 @@ export function PowerSearch({
         : 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: HTMLDivElement | null) => {
+      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: PopoverState) => {
+      isPopoverOpenRef.current = state.type !== 'idle';
       setPopoverStateRaw(state);
       if (state.type !== 'idle') {
         // Schedule after the current frame so React can render the popover
@@ -623,13 +842,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();
+      }
     },
   }));
 
@@ -833,10 +1061,12 @@ export function PowerSearch({
     setPopoverState({type: 'idle'});
   }, [setPopoverState]);
 
-  // Custom token renderer
-  // Custom token renderer
-  const renderToken = useCallback(
-    (item: PowerSearchItem, onRemove: () => void) => {
+  // 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: PowerSearchItem, onRemove: (() => void) | undefined) => {
       const auxData = item.auxiliaryData;
       const filterIndex = auxData?.filterIndex ?? -1;
       const filter = filterIndex >= 0 ? filters[filterIndex] : undefined;
@@ -846,7 +1076,8 @@ export function PowerSearch({
         ? 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;
@@ -868,6 +1099,7 @@ export function PowerSearch({
             onClick={handleClick}
             onRemove={handleRemove}
             isDisabled={isDisabled}
+            timezoneID={timezoneID}
           />
         );
       }
@@ -944,6 +1176,7 @@ export function PowerSearch({
       );
     },
     [
+      timezoneID,
       filters,
       config,
       configProp,
@@ -959,6 +1192,12 @@ export function PowerSearch({
     ],
   );
 
+  const renderToken = useCallback(
+    (item: PowerSearchItem, onRemove: () => void) =>
+      renderFilterToken(item, onRemove),
+    [renderFilterToken],
+  );
+
   // Custom typeahead item renderer — adds field icon and description
   const renderItem = useCallback(
     (item: PowerSearchItem) => {
@@ -1032,6 +1271,7 @@ export function PowerSearch({
           onCancel={handlePopoverCancel}
           saveButtonLabel={popoverSaveButtonLabel}
           isReadOnly={isReadOnly}
+          timezoneID={timezoneID}
         />
       );
     }
@@ -1047,9 +1287,11 @@ export function PowerSearch({
         saveButtonLabel={popoverSaveButtonLabel}
         maxMenuItems={maxOperatorMenuItems}
         isReadOnly={isReadOnly}
+        timezoneID={timezoneID}
       />
     );
   }, [
+    timezoneID,
     popoverPartialFilter,
     popoverState,
     EditorOverride,
@@ -1076,13 +1318,18 @@ 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).
@@ -1095,15 +1342,20 @@ export function PowerSearch({
     [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((): React.ReactNode => {
@@ -1124,14 +1376,231 @@ 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 as React.Ref<HTMLDivElement>,
+    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<HTMLDivElement>(null);
+  const handleTriggerWrapperClick = useCallback(
+    (event: React.MouseEvent<HTMLDivElement>) => {
+      // 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: React.FocusEvent<HTMLDivElement>) => {
+      // 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: React.FocusEvent<HTMLDivElement>) => {
+      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 (
+      <div key="sheet" ref={rootRef} {...themeProps('power-search')}>
+        <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}>
+          <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],
+            )}>
+            {/* The trigger's name is the label plus everything visible here:
+                the placeholder, or the tokens, so speech input can say what
+                it sees and assistive technology hears the selected filters
+                (WCAG 2.5.3). */}
+            <div
+              id={triggerContentId}
+              {...stylex.props(sheetTriggerStyles.contentSection)}>
+              {isRenderable(startIcon as React.ReactNode) && (
+                <span
+                  {...stylex.props(
+                    filters.length > 0 &&
+                      sheetTriggerStyles.startIconWithTokens,
+                  )}>
+                  {renderIconSlot(startIcon, {size: 'sm', color: 'secondary'})}
+                </span>
+              )}
+              {tokenizerValue.map(item => (
+                <React.Fragment key={item.id}>
+                  {renderFilterToken(item, undefined)}
+                </React.Fragment>
+              ))}
+              <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}
+                {...stylex.props(
+                  sheetTriggerStyles.trigger,
+                  filters.length > 0 && sheetTriggerStyles.triggerWithTokens,
+                )}>
+                {filters.length === 0 ? placeholder : null}
+              </button>
+            </div>
+            {(endContent || isRenderable(resultCountText)) && (
+              <div
+                ref={endLaneRef}
+                {...stylex.props(sheetTriggerStyles.endSection)}>
+                {isRenderable(resultCountText) && (
+                  <span {...stylex.props(resultCountStyles.text)}>
+                    {resultCountText}
+                  </span>
+                )}
+                {endContent}
+              </div>
+            )}
+          </div>
+          {showsDisabledMessage &&
+            disabledMessageTooltip.renderTooltip(disabledMessage)}
+        </Field>
+        {/* Mounted from the press until the flow's exit has completed and
+            focus is back on the trigger (`isSheetPresented`): at rest the
+            field renders its trigger alone — no closed dialogs, rows, search
+            field or editors in the DOM. */}
+        {(isSheetOpen || isSheetPresented) && (
+          <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}
+          />
+        )}
+      </div>
+    );
+  }
+
   return (
     <>
-      <div
-        ref={useMergedRefs(
-          ref,
-          popover.triggerRef as React.Ref<HTMLDivElement>,
-        )}
-        {...themeProps('power-search')}>
+      <div key="popover" ref={rootRef} {...themeProps('power-search')}>
         {/* The field's Clear all announces PowerSearch's own words
             (component:PowerSearch; component:Tokenizer AR7). */}
         <TokenizerClearAllMessageContext value={clearAllMessage}>
@@ -1148,7 +1617,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}
@@ -1160,12 +1629,13 @@ 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}
+              presentation="popover"
             />
           </TokenizerItemRemovableContext>
         </TokenizerClearAllMessageContext>