@astryxdesign/core 0.7.7-canary.c0929c8 → 0.7.7-canary.c19ca12

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,
@@ -31,36 +37,54 @@ import {
   type TokenizerOverflowBehavior,
 } from '../Tokenizer';
 import {TokenizerClearAllMessageContext} from '../Tokenizer/TokenizerClearAllMessageContext';
+import {TokenizerItemRemovableContext} from '../Tokenizer/TokenizerItemRemovableContext';
 import {TypeaheadItem} from '../Typeahead/TypeaheadItem';
 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';
 import type {
   PowerSearchConfig,
   PowerSearchFilter,
@@ -71,9 +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';
@@ -146,217 +175,131 @@ 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, '...');
-}
-
-function getEnumLabel(values: ReadonlyArray<EnumItem>, value: string): string {
-  return values.find(v => v.value === value)?.label ?? value;
-}
-
-function PowerSearchTokenValue({
-  operatorValue,
-  filterValue,
-  maxLength,
-  locale,
-}: {
-  operatorValue: OperatorValue;
-  filterValue: FilterValue;
-  maxLength: number;
-  locale: Locale;
-}) {
-  switch (filterValue.type) {
-    case 'empty':
-      return null;
-
-    case 'string':
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {truncateString(filterValue.value, maxLength)}
-        </span>
-      );
-
-    case 'integer':
-    case 'float':
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {filterValue.value}
-        </span>
-      );
-
-    case 'enum':
-      if (operatorValue.type === 'enum') {
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {truncateString(
-              getEnumLabel(operatorValue.values, filterValue.value),
-              maxLength,
-            )}
-          </span>
-        );
-      }
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {truncateString(filterValue.value, maxLength)}
-        </span>
-      );
-
-    case 'string_list': {
-      const items = filterValue.value;
-      if (items.length === 0) {
-        return null;
-      }
-      if (items.length === 1) {
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {truncateString(items[0], maxLength)}
-          </span>
-        );
-      }
-      const totalLength = items.reduce((sum, s) => sum + s.length, 0);
-      if (totalLength > maxLength) {
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {items.length} items
-          </span>
-        );
-      }
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {items.join(', ')}
-        </span>
-      );
-    }
-
-    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 (
-            <span {...stylex.props(tokenValueStyles.value)}>
-              {truncateString(labels[0], maxLength)}
-            </span>
-          );
-        }
-        const totalLength = labels.reduce((sum, s) => sum + s.length, 0);
-        if (totalLength > maxLength) {
-          return (
-            <span {...stylex.props(tokenValueStyles.value)}>
-              {labels.length} items
-            </span>
-          );
-        }
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {labels.join(', ')}
-          </span>
-        );
-      }
-      if (items.length === 1) {
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {truncateString(items[0], maxLength)}
-          </span>
-        );
-      }
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {items.length} items
-        </span>
-      );
-    }
-
-    case 'entity_list': {
-      const entities = filterValue.value;
-      if (entities.length === 0) {
-        return null;
-      }
-      if (entities.length === 1) {
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {truncateString(entities[0].label, maxLength)}
-          </span>
-        );
-      }
-      const totalLength = entities.reduce((sum, e) => sum + e.label.length, 0);
-      if (totalLength > maxLength) {
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {entities.length} items
-          </span>
-        );
-      }
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {entities.map(e => e.label).join(', ')}
-        </span>
-      );
-    }
-
-    case 'time':
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {filterValue.value}
-        </span>
-      );
-
-    case 'date_absolute': {
-      const formatted = formatDateAbsoluteCompact(
-        filterValue.unixSeconds,
-        locale,
-      );
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {truncateString(formatted, maxLength)}
-        </span>
-      );
-    }
-
-    case 'date_relative':
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {truncateString(filterValue.value, maxLength)}
-        </span>
-      );
-
-    case 'date_range':
-      return <span {...stylex.props(tokenValueStyles.value)}>date range</span>;
+// 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']},
+});
 
-    case 'custom':
-      if (operatorValue.type === 'custom') {
-        return (
-          <span {...stylex.props(tokenValueStyles.value)}>
-            {truncateString(
-              operatorValue.getString(filterValue.value),
-              maxLength,
-            )}
-          </span>
-        );
-      }
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {filterValue.value}
-        </span>
-      );
+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'],
+  },
+});
 
-    case 'nested': {
-      const count = filterValue.value.length;
-      return (
-        <span {...stylex.props(tokenValueStyles.value)}>
-          {count === 1 ? '1 filter' : `${count} filters`}
-        </span>
-      );
-    }
+// 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,
+};
 
-    default:
-      return null;
+/**
+ * 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 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}) {
+  return <span {...stylex.props(tokenValueStyles.value)}>{text}</span>;
 }
 
 // =============================================================================
@@ -467,6 +410,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';
+  };
 }
 
 // =============================================================================
@@ -489,6 +463,20 @@ type PopoverState =
 // Component
 // =============================================================================
 
+/**
+ * Whether a press on a token with this operator commits the filter instead of
+ * opening its editor: an `empty` operator with no `empty` Editor override.
+ */
+function commitsWithoutEditor(
+  operator: PowerSearchOperator | undefined,
+  componentOverrides: PowerSearchComponents | undefined,
+): boolean {
+  return (
+    operator?.value.type === 'empty' &&
+    componentOverrides?.empty?.Editor == null
+  );
+}
+
 /**
  * Structured filter bar where each token represents a filter (field + operator + value).
  *
@@ -589,6 +577,7 @@ export function PowerSearch({
   className,
   style,
   components: componentOverrides,
+  experimental,
 }: PowerSearchProps) {
   const size = useSize(sizeProp, 'md');
   const config = useInternalConfig(configProp);
@@ -602,12 +591,164 @@ 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',
   });
 
+  // A default filter token's visible text: its label (field and operator)
+  // and its value. The token's remove button and editor dialog are named by
+  // the same text.
+  const tokenText = useCallback(
+    (filter: PowerSearchFilter) => {
+      const field = config.getField(filter.field);
+      const operator = config.getOperator(filter.field, filter.operator);
+      const fieldLabel = field?.label ?? '';
+      const operatorLabel = operator ? resolveOperatorLabel(operator, t) : '';
+      const label = `${fieldLabel}: ${operatorLabel}`.trim();
+      const value = operator
+        ? formatTokenValueText(
+            operator.value,
+            filter.value,
+            Math.max(
+              maxTokenLength - fieldLabel.length - operatorLabel.length,
+              10,
+            ),
+            locale,
+          )
+        : null;
+      return {label, value, full: value != null ? `${label} ${value}` : label};
+    },
+    [config, maxTokenLength, t, locale],
+  );
+  // 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'});
   }, []);
 
@@ -616,14 +757,66 @@ export function PowerSearch({
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
-    // The popup's own listbox/menu content is the exposed semantics; focus
-    // stays on the tokenizer input, so a modal dialog wrapper is incorrect.
-    role: 'none',
+    // Adding: the popup's own listbox/menu content is the exposed semantics,
+    // and focus stays on the tokenizer input, so a dialog wrapper is
+    // incorrect. Editing a token: focus moves into the editor's controls, so
+    // the editor is a non-modal dialog named by the token's visible text.
+    role: editedBuiltInFilter != null ? 'dialog' : 'none',
+    isModal: false,
+    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: 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
@@ -640,13 +833,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();
+      }
     },
   }));
 
@@ -738,19 +940,39 @@ export function PowerSearch({
             value: undefined,
           },
         });
-      } else if (change.type === 'remove' && change.item) {
-        const auxData = change.item.auxiliaryData as PowerSearchAuxData;
-        if (auxData?.filterIndex != null) {
-          const newFilters = filters.filter((_, i) =>
-            _items.some(item => item.auxiliaryData?.filterIndex === i),
+      } else if (change.type === 'remove') {
+        const keptIndices = new Set(
+          _items.map(item => item.auxiliaryData?.filterIndex),
+        );
+        const firstRemovedIndex = filters.findIndex(
+          (_, i) => !keptIndices.has(i),
+        );
+        if (firstRemovedIndex >= 0) {
+          onChange(
+            filters.filter((_, i) => keptIndices.has(i)),
+            'remove',
+            firstRemovedIndex,
           );
-          onChange(newFilters, 'remove', auxData.filterIndex);
         }
       }
     },
     [config, filters, onChange, setPopoverState],
   );
 
+  // Tokenizer's Backspace and Clear all do not go through renderToken. This
+  // predicate locks each read-only filter, and every token of a read-only
+  // field.
+  const isItemRemovable = useCallback(
+    (item: SearchableItem) => {
+      if (isReadOnly) {
+        return false;
+      }
+      const filterIndex = (item as PowerSearchItem).auxiliaryData?.filterIndex;
+      return filterIndex == null || !filters[filterIndex]?.isReadOnly;
+    },
+    [filters, isReadOnly],
+  );
+
   // Handle clicking a token to edit
   const handleTokenClick = useCallback(
     (index: number) => {
@@ -767,10 +989,7 @@ export function PowerSearch({
       // edit: commit it as that editor's save would, the way adding one does,
       // instead of opening it. A consumer's `empty` Editor override still opens.
       const operator = config.getOperator(filter.field, filter.operator);
-      if (
-        operator?.value.type === 'empty' &&
-        componentOverrides?.empty?.Editor == null
-      ) {
+      if (commitsWithoutEditor(operator, componentOverrides)) {
         const newFilters = [...filters];
         newFilters[index] = {
           field: filter.field,
@@ -833,10 +1052,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 +1067,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;
@@ -875,20 +1097,16 @@ export function PowerSearch({
       // Default token rendering
       const fieldLabel = field?.label ?? '';
       const operatorLabel = operator ? resolveOperatorLabel(operator, t) : '';
-      const tokenLabel = `${fieldLabel}: ${operatorLabel}`.trim();
-      const adjustedMaxLength = Math.max(
-        maxTokenLength - fieldLabel.length - operatorLabel.length,
-        10,
-      );
-
+      const text =
+        filter != null
+          ? tokenText(filter)
+          : {label: `${fieldLabel}: ${operatorLabel}`.trim(), value: null};
+      const tokenLabel = text.label;
+      const fullText =
+        text.value != null ? `${text.label} ${text.value}` : text.label;
       const valueContent =
-        operator && filter ? (
-          <PowerSearchTokenValue
-            operatorValue={operator.value}
-            filterValue={filter.value}
-            maxLength={adjustedMaxLength}
-            locale={locale}
-          />
+        text.value != null ? (
+          <PowerSearchTokenValue text={text.value} />
         ) : undefined;
 
       // Show entity photo as token icon for single-entity filters
@@ -902,32 +1120,49 @@ export function PowerSearch({
         tokenIcon = <Avatar src={entity.photo} name={entity.label} size={16} />;
       }
 
+      // A token that opens its editor says that it opens a dialog, and the
+      // naming context names it by all its visible text.
+      const editorProps =
+        handleClick != null &&
+        !commitsWithoutEditor(operator, componentOverrides)
+          ? {
+              'aria-haspopup': 'dialog' as const,
+              'aria-expanded':
+                popoverState.type === 'editing' &&
+                popoverState.filterIndex === filterIndex,
+            }
+          : null;
+
       return (
-        <Token
-          label={tokenLabel}
-          size={size}
-          icon={tokenIcon}
-          endContent={valueContent}
-          onMouseDown={
-            handleClick
-              ? e => {
-                  // Keep a token press from entering Tokenizer's input-focus
-                  // redirect. Click still edits/removes; Tab entry is unchanged.
-                  e.preventDefault();
-                }
-              : undefined
-          }
-          onClick={
-            handleClick
-              ? (e: React.MouseEvent) => {
-                  e.stopPropagation();
-                  handleClick();
-                }
-              : undefined
-          }
-          onRemove={handleRemove}
-          isDisabled={isDisabled}
-        />
+        <TokenNamingContext
+          value={{actionName: fullText, removeName: fullText}}>
+          <Token
+            label={tokenLabel}
+            size={size}
+            icon={tokenIcon}
+            {...editorProps}
+            endContent={valueContent}
+            onMouseDown={
+              handleClick
+                ? e => {
+                    // Keep a token press from entering Tokenizer's input-focus
+                    // redirect. Click still edits/removes; Tab entry is unchanged.
+                    e.preventDefault();
+                  }
+                : undefined
+            }
+            onClick={
+              handleClick
+                ? (e: React.MouseEvent) => {
+                    e.stopPropagation();
+                    handleClick();
+                  }
+                : undefined
+            }
+            onRemove={handleRemove}
+            isDisabled={isDisabled}
+          />
+        </TokenNamingContext>
       );
     },
     [
@@ -935,16 +1170,23 @@ export function PowerSearch({
       config,
       configProp,
       maxTokenLength,
-      locale,
       size,
       isReadOnly,
       isDisabled,
       handleTokenClick,
       componentOverrides,
       t,
+      popoverState,
+      tokenText,
     ],
   );
 
+  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) => {
@@ -1062,30 +1304,44 @@ 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(
-    () => t('@astryx.powersearch.allFiltersRemoved'),
-    [t],
+    () =>
+      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((): React.ReactNode => {
@@ -1106,48 +1362,266 @@ 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}
+            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}>
-          <Tokenizer
-            handleRef={tokenizerRef}
-            label={label}
-            isLabelHidden={isLabelHidden}
-            searchSource={searchSource}
-            value={tokenizerValue}
-            onChange={handleTokenizerChange}
-            renderToken={renderToken}
-            renderItem={renderItem}
-            maxMenuItems={MAX_BROWSE_MENU_ITEMS}
-            menuWidth={menuWidth}
-            placeholder={filters.length === 0 ? placeholder : ''}
-            hasAutoFocus={hasAutoFocus}
-            hasClear={hasClear && !isReadOnly}
-            startIcon={startIcon}
-            endContent={combinedEndContent}
-            isDisabled={isDisabled}
-            disabledMessage={disabledMessage}
-            size={size}
-            tokenOverflowBehavior={tokenOverflowBehavior}
-            hasEntriesOnFocus
-            debounceMs={0}
-            status={status}
-            statusVariant={statusVariant}
-            onFocus={onFocus}
-            onBlur={onBlur}
-            containerXstyle={xstyle}
-            containerClassName={className}
-            containerStyle={style}
-            data-testid={testId}
-          />
+          <TokenizerItemRemovableContext value={isItemRemovable}>
+            <Tokenizer
+              handleRef={tokenizerRef}
+              label={label}
+              isLabelHidden={isLabelHidden}
+              searchSource={searchSource}
+              value={tokenizerValue}
+              onChange={handleTokenizerChange}
+              renderToken={renderToken}
+              renderItem={renderItem}
+              maxMenuItems={MAX_BROWSE_MENU_ITEMS}
+              menuWidth={menuWidth}
+              placeholder={filters.length === 0 ? placeholder : ''}
+              hasAutoFocus={autoFocusOnMount}
+              hasClear={hasClear && !isReadOnly}
+              startIcon={startIcon}
+              endContent={combinedEndContent}
+              isDisabled={isDisabled}
+              disabledMessage={disabledMessage}
+              size={size}
+              tokenOverflowBehavior={tokenOverflowBehavior}
+              hasEntriesOnFocus
+              debounceMs={0}
+              status={status}
+              statusVariant={statusVariant}
+              onFocus={handleFieldFocus}
+              onBlur={handleFieldBlur}
+              containerXstyle={xstyle}
+              containerClassName={className}
+              containerStyle={style}
+              data-testid={testId}
+            />
+          </TokenizerItemRemovableContext>
         </TokenizerClearAllMessageContext>
       </div>
       {popover.render(popoverContent, {