Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
91.9 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file PowerSearchBottomSheet.tsx
 * @input The field's InternalConfig, filters, onChange, the field typeahead
 *   source, and the sheet options PowerSearch forwards; BottomSheet,
 *   Button, EmptyState, Heading, Icon, IconButton, Indicator, List,
 *   RadioList, Text, TextInput, PowerSearchValueEditor, the internal sheet
 *   confirmation and search-drag owners, i18n
 * @output Exports PowerSearchBottomSheet — the touch surface of
 *   `PowerSearch presentation="bottom-sheet"`: a Filters sheet
 *   with editable rows and trailing remove actions, Add filter in its fixed
 *   header and Clear all / Done in its fixed footer, an Add filter sheet with
 *   grouped field rows or the content search with inline suggestions, and a
 *   value step that stages field → operator → value and confirms from its
 *   footer
 * @position Internal presentation surface of PowerSearch. Loaded on demand by
 *   PowerSearch.tsx so the popover presentation never carries it. The
 *   trigger lives in PowerSearch.tsx.
 *
 * The three steps are sibling standalone BottomSheets that stack: each step
 * opens above the sheet that led to it, which stays open beneath as a covered
 * sheet, so no sheet needs a Back action. A dismissal closes only the top
 * sheet and reveals the step beneath; dismissing the bottom sheet ends the
 * flow. A list value's Tokenizer opens its own sheet above the value step, as
 * the top sheet of the stack.
 *
 * The sheets pad their own content (`padding={0}` on BottomSheet). The
 * Filters and Add filter sheets keep their header and footer fixed around a
 * scroll viewport that reaches the sheet edge; its content publishes the
 * padding as container padding so `edge="bleed"` lists run edge to edge with
 * row text on the header's inset. The sheets are pinned tall: the field list
 * resizes as it is searched and the editor changes with the operator, and
 * only a fully expanded tall sheet gives mobile-keyboard accommodation.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/PowerSearch/PowerSearch.tsx (the trigger and the lazy host)
 * - /docs/specs/components/PowerSearch/PowerSearch.spec.md (FR10–FR21, AR4–AR6, PR5)
 */

import React, {
  useCallback,
  useEffect,
  useId,
  useLayoutEffect,
  useMemo,
  useRef,
  useState,
  type ReactNode,
  type RefObject,
  type SVGProps,
} from 'react';
import {flushSync} from 'react-dom';
import * as stylex from '@stylexjs/stylex';
import {BottomSheet} from '../BottomSheet/BottomSheet';
import {Button} from '../Button/Button';
import {EmptyState} from '../EmptyState/EmptyState';
import {Heading} from '../Heading/Heading';
import {Icon} from '../Icon/Icon';
import {IconButton} from '../IconButton/IconButton';
import {isRenderable} from '../utils/isRenderable';
import {containerPaddingInlineVarStyles} from '../Layout/padding.stylex';
import {List} from '../List/List';
import {ListItem} from '../List/ListItem';
import {RadioList} from '../RadioList/RadioList';
import {RadioListItem} from '../RadioList/RadioListItem';
import {CheckboxList} from '../CheckboxList/CheckboxList';
import {CheckboxListItem} from '../CheckboxList/CheckboxListItem';
import {Text} from '../Text/Text';
import {TextInput} from '../TextInput/TextInput';
import type {SearchSource} from '../Typeahead/types';
import {useAnnounce, type AnnounceFn} from '../hooks/useAnnounce';
import type {TranslatorFn} from '../i18n';
import {useListFormatter} from '../i18n/useListFormatter';
import {useLocale} from '../i18n/useLocale';
import {useCalendarSystem} from '../i18n/useCalendarSystem';
import {SheetConfirmation} from '../internal/SheetConfirmation';
import {useDismissSearchOnTouchDrag} from '../internal/useDismissSearchOnTouchDrag';
import {
  colorVars,
  fontWeightVars,
  radiusVars,
  spacingVars,
} from '../theme/tokens.stylex';
import {isImeKeyEvent} from '../utils/ime';
import {rtlStyles} from '../utils/rtlStyles';
import {formatTokenValueText} from './formatTokenValue';

function resolveRelativeDateLabel(
  operatorValue: OperatorValue & {type: 'date_relative'},
  value: string,
  t: TranslatorFn,
  buildRelativeDateOptions: PowerSearchSheetEditors['buildRelativeDateOptions'],
): string {
  return (
    buildRelativeDateOptions(operatorValue, t).find(
      option => option.value === value,
    )?.label ?? value
  );
}

// A placeholder the Filters row formats `labelValue` with, then splits on, so
// the value segment can render bold inside the catalog's ordering. A private
// use code point: never part of a label or value.
const ROW_VALUE_SLOT = '\uE000';
import type {
  buildRelativeDateOptions,
  PowerSearchValueEditor,
} from './PowerSearchValueEditor';
import type {NestedEditor} from './PowerSearchEditPopover';
import {useAnnounceRenderedText} from '../hooks/useAnnounceRenderedText';
import {useInternalListFocus} from '../hooks/useListFocus';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {groupItems} from '../utils/groupItems';
import {
  createSheetSuggestionSource,
  fieldMatchesQuery,
  createFilterIdentities,
  filterSignature,
  isSupportedOperator,
  nearestEditableIndex,
  resolveFilterIdentityIndex,
} from './powerSearchSheetUtils';
import {resolveOperatorLabel} from './resolveOperatorLabel';
import type {InternalConfig} from './useInternalConfig';
import type {
  FilterValue,
  OperatorValue,
  PartialFilter,
  PowerSearchChangeType,
  PowerSearchComponents,
  PowerSearchConfig,
  PowerSearchField,
  PowerSearchFilter,
  PowerSearchItem,
  PowerSearchOperator,
} from './types';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/PowerSearch/PowerSearchBottomSheet.generated';

registerEnglishFallback(english);

// =============================================================================
// Props
// =============================================================================

/**
 * The popover presentation's editors, which the value step reuses. They come
 * from PowerSearch.tsx, whose module graph already loads them for the popover
 * presentation. Imported here, they and every component they reach would join
 * this lazily imported graph, whose modules must import Core directly and
 * never through a barrel.
 */
export interface PowerSearchSheetEditors {
  NestedEditor: typeof NestedEditor;
  PowerSearchValueEditor: typeof PowerSearchValueEditor;
  buildRelativeDateOptions: typeof buildRelativeDateOptions;
}

export interface PowerSearchBottomSheetProps {
  /** Whether the flow is open; the trigger in PowerSearch.tsx owns it. */
  isOpen: boolean;
  onOpenChange: (isOpen: boolean) => void;
  /**
   * The trigger: where focus returns when the flow closes, whichever step
   * closed it and however it opened (a tap on a token included).
   */
  finalFocusRef: RefObject<HTMLElement | null>;
  /**
   * The field's formatted result count, announced from inside the open
   * sheet's dialog when it changes while the flow is open. `useAnnounce`
   * routes a message by where its caller is, so the owner above the sheets
   * cannot reach the dialog's region.
   */
  resultCountText?: string | null;
  config: InternalConfig;
  /** The caller's config, handed to Editor overrides as they expect it. */
  configProp: PowerSearchConfig;
  /** The committed filters; the draft the sheet edits starts from them. */
  filters: ReadonlyArray<PowerSearchFilter>;
  /**
   * The field's `onChange`. Done replays the draft's edits through it, in
   * order, onto the field's latest filters, each call carrying that list
   * with the edit applied; nothing is reported before Done, and nothing when
   * the field is read-only or disabled at Done.
   */
  onChange: (
    filters: ReadonlyArray<PowerSearchFilter>,
    changeType: PowerSearchChangeType,
    index: number,
  ) => void;
  /** The field typeahead source; the content search lists its suggestions. */
  searchSource: SearchSource<PowerSearchItem>;
  /** Placeholder of the content search. */
  placeholder: string;
  isReadOnly: boolean;
  isDisabled: boolean;
  hasClear: boolean;
  maxOperatorMenuItems?: number;
  /** The zone a date-only value is read and written in; see PowerSearch. */
  timezoneID?: string;
  maxSearchResults: number;
  /** The caller's confirm label; the step picks a default per mode. */
  saveButtonLabel?: string;
  components?: PowerSearchComponents;
  editors: PowerSearchSheetEditors;
}

// =============================================================================
// Styles
// =============================================================================

/** One edit of the draft: the draft before and after it, and its type and index in the draft; Done replays it onto the field's latest filters. */
interface DraftEdit {
  before: ReadonlyArray<PowerSearchFilter>;
  after: ReadonlyArray<PowerSearchFilter>;
  changeType: PowerSearchChangeType;
  index: number;
}

// Whether two filter lists hold the same filters in the same order, by the
// key-order-insensitive signature the sheet matches filters with.
function hasSameFilters(
  a: ReadonlyArray<PowerSearchFilter>,
  b: ReadonlyArray<PowerSearchFilter>,
): boolean {
  return (
    a.length === b.length &&
    a.every(
      (filter, index) =>
        b[index] != null &&
        filterSignature(filter) === filterSignature(b[index]),
    )
  );
}

// The filters `before` holds that `after` does not, as a multiset by
// signature, in `before` order.
function removedFilters(
  before: ReadonlyArray<PowerSearchFilter>,
  after: ReadonlyArray<PowerSearchFilter>,
): PowerSearchFilter[] {
  const remaining = new Map<string, number>();
  for (const filter of after) {
    const signature = filterSignature(filter);
    remaining.set(signature, (remaining.get(signature) ?? 0) + 1);
  }
  return before.filter(filter => {
    const signature = filterSignature(filter);
    const count = remaining.get(signature) ?? 0;
    if (count > 0) {
      remaining.set(signature, count - 1);
      return false;
    }
    return true;
  });
}

/**
 * Replays the draft's edits onto `base`, the field's latest filters, and
 * reports each through `report` with the list after it. An add appends; an
 * edit replaces the first filter matching the one it edited; a removal drops
 * the filters it removed, by signature. An edit or removal whose target is
 * not in the base list is skipped: the parent removed it meanwhile.
 */
export function replayDraftEdits(
  base: ReadonlyArray<PowerSearchFilter>,
  edits: ReadonlyArray<DraftEdit>,
  report: (
    filters: ReadonlyArray<PowerSearchFilter>,
    changeType: PowerSearchChangeType,
    index: number,
  ) => void,
): ReadonlyArray<PowerSearchFilter> {
  let current = base;
  for (const edit of edits) {
    if (edit.changeType === 'add') {
      const added = edit.after[edit.index];
      if (added == null) {
        continue;
      }
      current = [...current, added];
      report(current, 'add', current.length - 1);
    } else if (edit.changeType === 'edit') {
      const original = edit.before[edit.index];
      const updated = edit.after[edit.index];
      if (original == null || updated == null) {
        continue;
      }
      const signature = filterSignature(original);
      const index = current.findIndex(
        filter => filterSignature(filter) === signature,
      );
      if (index === -1) {
        continue;
      }
      current = current.map((filter, i) => (i === index ? updated : filter));
      report(current, 'edit', index);
    } else {
      const removed = removedFilters(edit.before, edit.after).map(
        filterSignature,
      );
      const indexes: number[] = [];
      for (const signature of removed) {
        const index = current.findIndex(
          (filter, i) =>
            !indexes.includes(i) && filterSignature(filter) === signature,
        );
        if (index !== -1) {
          indexes.push(index);
        }
      }
      if (indexes.length === 0) {
        continue;
      }
      current = current.filter((_, i) => !indexes.includes(i));
      report(current, 'remove', Math.min(...indexes));
    }
  }
  return current;
}

// The trailing plus a field row shows when choosing it adds the filter at
// once, and the Add filter actions' glyph. Core's default icon set has no plus.
function PlusIcon(props: SVGProps<SVGSVGElement>) {
  return (
    <svg
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth={1.5}
      strokeLinecap="round"
      strokeLinejoin="round"
      {...props}>
      <path d="M5 12h14" />
      <path d="M12 5v14" />
    </svg>
  );
}

const styles = stylex.create({
  // 44px touch targets for every sheet action, without resizing inputs.
  touchAction: {
    minHeight: 44,
  },
  // A sheet action drawn smaller than 44px keeps its drawn size and grows
  // only its hit area to 44px, under a coarse pointer. The custom properties
  // carry the media condition because StyleX allows plain values inside a
  // pseudo-element. On a fine pointer the overlay is not generated, so it
  // never takes hover from the action's own content.
  touchHitArea: {
    '--_power-search-sheet-hit-inset': {
      default: '0px',
      '@media (pointer: coarse)': 'min(0px, calc((100% - 44px) / 2))',
    },
    '--_power-search-sheet-hit-content': {
      default: 'none',
      '@media (pointer: coarse)': '""',
    },
    '::after': {
      content: 'var(--_power-search-sheet-hit-content)',
      position: 'absolute',
      inset: 'var(--_power-search-sheet-hit-inset)',
    },
  },
  // Scopes the sticky header's and footer's layer to this sheet's content:
  // the List rows are `position: relative` and come after the header, so
  // without a layer of its own the header is painted under the rows that
  // scroll beneath it. Isolating the content keeps that z-index inside it, so
  // the sheet's grab handle (z-index 1 on the panel, outside this wrapper)
  // still paints above.
  sheet: {
    display: 'flex',
    flexDirection: 'column',
    minHeight: '100%',
    isolation: 'isolate',
  },
  // The Filters and Add filter sheets fill the panel and scroll only their
  // viewport, so the header and footer stay fixed.
  sheetWithFixedFooter: {
    height: '100%',
    overflow: 'hidden',
  },
  header: {
    position: 'sticky',
    insetBlockStart: 0,
    // Above the rows that scroll under it, within the isolated sheet content.
    zIndex: 1,
    display: 'flex',
    flexDirection: 'column',
    gap: spacingVars['--spacing-3'],
    paddingBlockEnd: spacingVars['--spacing-3'],
    paddingInline: spacingVars['--spacing-4'],
    backgroundColor: colorVars['--color-background-surface'],
  },
  // The value sheet scrolls its whole content, so its sticky header can reach
  // the sheet's top. The header rises into the band that the sheet keeps
  // under its grab bar and keeps its own padding there, so it clears the bar
  // at rest and while stuck. The Filters and Add filter sheets do not scroll
  // their header, and the band alone clears the bar.
  headerScrollsToTop: {
    marginBlockStart: `calc(-1 * ${spacingVars['--spacing-6']})`,
    paddingBlockStart: spacingVars['--spacing-6'],
  },
  headerRow: {
    display: 'flex',
    alignItems: 'center',
    gap: spacingVars['--spacing-2'],
  },
  headerText: {
    minWidth: 0,
    flexGrow: 1,
    display: 'flex',
    flexDirection: 'column',
  },
  // The body pads the sheet's content and publishes that inline padding as
  // the container padding its lists read: with `edge="bleed"` their rows run
  // edge to edge (full-bleed dividers) while row text keeps this inset, so
  // row text, group headings and the sheet title share one edge.
  body: {
    flexGrow: 1,
    display: 'flex',
    flexDirection: 'column',
    gap: spacingVars['--spacing-4'],
    paddingInline: spacingVars['--spacing-4'],
    paddingBlockEnd: spacingVars['--spacing-4'],
  },
  // The viewport reaches the sheet edge, so its scrollbar does too; the
  // content inside it carries the body's padding.
  scrollViewport: {
    flexGrow: 1,
    minHeight: 0,
    overflowY: 'auto',
    overscrollBehaviorY: 'contain',
  },
  scrollContent: {
    minHeight: '100%',
    display: 'flex',
    flexDirection: 'column',
    gap: spacingVars['--spacing-4'],
    paddingInline: spacingVars['--spacing-4'],
    paddingBlockEnd: spacingVars['--spacing-4'],
  },
  footer: {
    position: 'sticky',
    insetBlockEnd: 0,
    zIndex: 1,
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'space-between',
    gap: spacingVars['--spacing-2'],
    paddingBlock: spacingVars['--spacing-3'],
    paddingInline: spacingVars['--spacing-4'],
    backgroundColor: colorVars['--color-background-surface'],
  },
  fixedFooter: {
    position: 'relative',
    insetBlockEnd: 'auto',
    flexShrink: 0,
  },
  footerEqualAction: {
    flexGrow: 1,
    flexBasis: 0,
    minWidth: 0,
    minHeight: 44,
  },
  footerSoleAction: {
    flexGrow: 1,
  },
  empty: {
    paddingBlock: spacingVars['--spacing-6'],
    textAlign: 'center',
  },
  emptyState: {
    flexGrow: 1,
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
  },
  // With more than one section in the value step, each section is a muted
  // container.
  controlSection: {
    padding: spacingVars['--spacing-3'],
    borderRadius: radiusVars['--radius-container'],
    backgroundColor: colorVars['--color-background-muted'],
  },
  // The built-in nested editor's sub-filter rows collapse from one line to
  // wrapped lines under a container query on the popover's own container;
  // the sheet renders no such container, so the editor's tree root is the
  // query container here, and at phone widths the rows wrap instead of
  // running past the sheet's edge.
  nestedEditorContainer: {
    containerType: 'inline-size',
    overflow: 'hidden',
  },
  rowValue: {
    fontWeight: fontWeightVars['--font-weight-bold'],
  },
  editorInput: {
    paddingBlockStart: spacingVars['--spacing-1'],
  },
});

// =============================================================================
// Draft state
// =============================================================================

type SheetStep = 'manage' | 'fields' | 'value';

type PendingSheetFocus =
  | {readonly type: 'manager-add'}
  | {readonly type: 'content-search'}
  | {
      readonly type: 'manager-filter';
      readonly sourceFilter: PowerSearchFilter;
      readonly sourceSignature: string;
      readonly preferredIndex: number;
      /**
       * After a removal, focus goes to the row's trailing remove action, so a
       * run of removals needs no re-aiming; otherwise to the row.
       */
      readonly part?: 'remove';
    }
  | {readonly type: 'field'; readonly fieldKey: string};

interface FilterDraft {
  readonly mode: 'create' | 'edit';
  /**
   * Counts the value steps opened in this flow. Part of the editor's `key`:
   * the step's sheet stays mounted between openings, and an editor that
   * reads its filter on mount (the built-in nested editor, a caller's
   * override) must remount per opened filter, not per field and operator —
   * two groups on one field would otherwise share one editor's state.
   */
  readonly generation: number;
  /** Control within the Add filter sheet that launched this draft. */
  readonly returnFocus?: 'field' | 'content-search';
  /** Index in `filters` when edit mode opened. */
  readonly filterIndex?: number;
  /** Original controlled filter identity, used to follow immutable reorders. */
  readonly sourceFilter?: PowerSearchFilter;
  /** Structural snapshot, used when controlled parents clone their values. */
  readonly sourceSignature?: string;
  readonly field: string;
  readonly operator?: string;
  readonly value?: FilterValue;
}

function resolveDraftFilterIndex(
  filters: ReadonlyArray<PowerSearchFilter>,
  draft: FilterDraft,
): number | null {
  if (
    draft.mode !== 'edit' ||
    draft.filterIndex == null ||
    draft.sourceFilter == null ||
    draft.sourceSignature == null
  ) {
    return null;
  }
  return resolveFilterIdentityIndex(
    filters,
    draft.sourceFilter,
    draft.sourceSignature,
    draft.filterIndex,
  );
}

// Below this many fields a search box is noise: the whole list is on screen.
const SEARCHABLE_FIELD_COUNT = 8;
// Empty-query browsing keeps the popover presentation's safety ceiling.
const MAX_BROWSE_MENU_ITEMS = 1000;

// =============================================================================
// Choice rows (enum, enum_list, date_relative)
// =============================================================================

/**
 * Rendered inside a step's BottomSheet so that `useAnnounce` resolves the
 * sheet's dialog as the enclosing modal; publishes that
 * dialog's `announce` to the flow above through `onAnnounceChange` while
 * mounted. Renders nothing.
 */
function SheetAnnouncer({
  onAnnounceChange,
}: {
  onAnnounceChange: (announce: AnnounceFn | null) => void;
}) {
  const announce = useAnnounce();
  // Hands this dialog's announce function up; the cleanup withdraws it when
  // the step changes or the flow closes.
  useEffect(() => {
    onAnnounceChange(announce);
    return () => {
      onAnnounceChange(null);
    };
  }, [announce, onAnnounceChange]);
  return null;
}

/**
 * The value step's "This filter is no longer available" message, rendered
 * inside the step's dialog. The shared own-content module reads the rendered
 * text and speaks it once per opened filter while the step is the open one.
 * Called from inside the sheet's dialog, `useAnnounce` routes it into the
 * dialog. The message is plain text, not an EmptyState, so nothing announces
 * it a second time.
 */
function SheetEmptyMessage({
  id,
  message,
  occasion,
  isShown,
}: {
  id?: string;
  message: string;
  occasion: string;
  /**
   * Whether the message's step is the open one. A sheet beneath another, or
   * closed with its body retained, speaks nothing, and the hook re-arms so
   * the same occasion is spoken again when the step reopens on it.
   */
  isShown: boolean;
}) {
  const ref = useRef<HTMLDivElement>(null);
  useAnnounceRenderedText(ref, isShown, occasion);
  return (
    <div ref={ref} id={id} {...stylex.props(styles.empty)}>
      <Text type="supporting" color="secondary">
        {message}
      </Text>
    </div>
  );
}

interface ChoiceItem {
  readonly value: string;
  readonly label: string;
  readonly icon?: ReactNode;
}

/**
 * Closed vocabularies render as lists, not as a dropdown. A dropdown layer
 * inside a sheet stacks a second overlay on a surface the person is already
 * inside.
 */
function ChoiceRows(
  props: {
    items: ReadonlyArray<ChoiceItem>;
    selected: ReadonlyArray<string>;
    isDisabled?: boolean;
    /** The group's accessible name: the field label. */
    label: string;
  } & (
    | {isMultiple: true; onChange: (values: string[]) => void}
    | {isMultiple?: false; onChange: (value: string) => void}
  ),
) {
  const {items, selected, isDisabled, label} = props;
  const itemLabel = (item: ChoiceItem) =>
    isRenderable(item.icon) ? (
      <>
        <span aria-hidden="true">{item.icon}</span> {item.label}
      </>
    ) : (
      item.label
    );
  if (props.isMultiple === true) {
    return (
      <CheckboxList
        label={label}
        isLabelHidden
        isDisabled={isDisabled}
        value={[...selected]}
        onChange={props.onChange}>
        {items.map(item => (
          <CheckboxListItem
            key={item.value}
            value={item.value}
            label={itemLabel(item)}
          />
        ))}
      </CheckboxList>
    );
  }
  return (
    <RadioList
      label={label}
      isLabelHidden
      isDisabled={isDisabled}
      value={selected[0] ?? ''}
      onChange={props.onChange}>
      {items.map(item => (
        <RadioListItem
          key={item.value}
          value={item.value}
          label={itemLabel(item)}
        />
      ))}
    </RadioList>
  );
}

/**
 * The value control for one filter inside the value step. Closed vocabularies
 * are rows here; every other type is the popover presentation's own editor in
 * its sheet presentation.
 */
function SheetValueEditor({
  operatorValue,
  filterValue,
  onChange,
  onUnstage,
  config,
  fieldLabel,
  isDisabled,
  maxMenuItems,
  timezoneID,
  editors,
}: {
  operatorValue: OperatorValue;
  filterValue: FilterValue | undefined;
  onChange: (value: FilterValue) => void;
  onUnstage: () => void;
  config: InternalConfig;
  fieldLabel: string;
  isDisabled: boolean;
  maxMenuItems?: number;
  timezoneID?: string;
  editors: PowerSearchSheetEditors;
}) {
  const {buildRelativeDateOptions, PowerSearchValueEditor} = editors;
  const t = useComponentTranslator();
  const selectedValues = useMemo<ReadonlyArray<string>>(() => {
    if (filterValue?.type === 'enum' || filterValue?.type === 'date_relative') {
      return [filterValue.value];
    }
    if (filterValue?.type === 'enum_list') {
      return filterValue.value;
    }
    return [];
  }, [filterValue]);

  switch (operatorValue.type) {
    case 'empty':
    case 'nested':
      return null;
    case 'enum':
      return (
        <ChoiceRows
          items={operatorValue.values}
          selected={selectedValues}
          isDisabled={isDisabled}
          label={fieldLabel}
          onChange={value => onChange({type: 'enum', value})}
        />
      );
    case 'enum_list':
      return (
        <ChoiceRows
          items={operatorValue.values}
          selected={selectedValues}
          isDisabled={isDisabled}
          isMultiple
          label={fieldLabel}
          onChange={values => onChange({type: 'enum_list', value: values})}
        />
      );
    case 'date_relative':
      return (
        <ChoiceRows
          items={buildRelativeDateOptions(operatorValue, t)}
          selected={selectedValues}
          isDisabled={isDisabled}
          label={fieldLabel}
          onChange={value => onChange({type: 'date_relative', value})}
        />
      );
    case 'string':
    case 'string_list':
    case 'integer':
    case 'float':
    case 'time':
    case 'date_absolute':
    case 'date_range':
    case 'entity_list':
    case 'custom':
      return (
        <div {...stylex.props(styles.editorInput)}>
          <PowerSearchValueEditor
            operatorValue={operatorValue}
            filterValue={filterValue}
            onChange={onChange}
            onUnstage={onUnstage}
            config={config}
            maxMenuItems={maxMenuItems}
            isDisabled={isDisabled}
            presentation="bottom-sheet"
            fieldLabel={fieldLabel}
            timezoneID={timezoneID}
          />
        </div>
      );
  }
}

// =============================================================================
// Component
// =============================================================================

/**
 * The sheet flow of PowerSearch's touch presentation: Filters, Add filter,
 * and the value step, as standalone sheets that stack, each open beneath the
 * step it led to.
 */
export function PowerSearchBottomSheet({
  isOpen,
  onOpenChange,
  finalFocusRef,
  resultCountText,
  config,
  configProp,
  filters: committedFilters,
  onChange: onCommit,
  searchSource,
  placeholder,
  isReadOnly,
  isDisabled,
  hasClear,
  maxOperatorMenuItems,
  timezoneID,
  maxSearchResults,
  saveButtonLabel: saveButtonLabelFromProps,
  components: componentOverrides,
  editors,
}: PowerSearchBottomSheetProps) {
  const {NestedEditor} = editors;
  const t = useComponentTranslator();
  const locale = useLocale();
  const calendar = useCalendarSystem(undefined, 'PowerSearch');
  const formatList = useListFormatter();
  const isInteractive = !isDisabled && !isReadOnly;

  // ---- draft ----
  // One open flow edits one draft of the filter list; `onChange` waits for
  // Done, and a dismissal with a changed draft asks first.
  const [filtersAtOpen, setFiltersAtOpen] = useState(() => committedFilters);
  const [filters, setFilters] = useState(() => committedFilters);
  // The draft as of the last edit, for the edit log's `before` lists.
  const draftRef = useRef(filters);
  const draftEditsRef = useRef<DraftEdit[]>([]);
  const onChange = useCallback(
    (
      next: ReadonlyArray<PowerSearchFilter>,
      changeType: PowerSearchChangeType,
      index: number,
    ) => {
      draftEditsRef.current.push({
        before: draftRef.current,
        after: next,
        changeType,
        index,
      });
      draftRef.current = next;
      setFilters(next);
    },
    [],
  );
  const isDraftDirty = !hasSameFilters(filtersAtOpen, filters);
  const [isDiscardConfirmationOpen, setIsDiscardConfirmationOpen] =
    useState(false);

  const contentSearchFieldKey = config.config.contentSearchFieldKey;
  const contentSearchOperator =
    contentSearchFieldKey == null
      ? undefined
      : config.getDefaultOperator(contentSearchFieldKey);
  const hasContentSearch = contentSearchOperator?.value.type === 'string';
  const suggestionSource = useMemo(
    () => createSheetSuggestionSource(config, searchSource),
    [config, searchSource],
  );

  const contentResultsId = useId();
  const managerAddButtonRef = useRef<HTMLButtonElement>(null);
  const contentSearchRef = useRef<HTMLDivElement>(null);
  const fieldSearchRef = useRef<HTMLDivElement>(null);
  // The Add filter sheet's panel: the fallback focus target when the control
  // a step came from is gone — its first focusable control, which is the
  // search field when one shows, else the first field row.
  const fieldsSheetRef = useRef<HTMLDivElement>(null);
  // The content search and its suggestion rows are one vertical list for the
  // arrow keys: ArrowDown from the searchbox reaches the first suggestion,
  // ArrowUp from the first suggestion returns to the searchbox, and the ends
  // do not wrap. Home and End stay with the searchbox's caret.
  const contentListFocus = useInternalListFocus<HTMLDivElement>({
    itemSelector: `[role="searchbox"], [id="${contentResultsId}"] button`,
    wrap: false,
    hasHomeEnd: false,
  });
  const fieldsSheetCallbackRef = useMergedRefs(
    fieldsSheetRef,
    contentListFocus.listRef,
  );
  const handleContentListKeyDown = (event: React.KeyboardEvent) => {
    if (!isImeKeyEvent(event.nativeEvent)) {
      contentListFocus.handleKeyDown(event);
    }
  };
  const manageSheetRef = useRef<HTMLDivElement>(null);
  // Where focus was inside the Filters or Add filter sheet, read on every
  // focus change there, so a controlled update that unmounts the focused
  // control (a filter's row, a dropped field's row, Clear all after the last
  // filter) can put focus on the nearest remaining row by that index, else
  // the sheet's first control, else the sheet panel. A removed element
  // fires no blur, so the position is what the effect below reads.
  const lastSheetFocusRef = useRef<{
    sheet: 'manage' | 'fields';
    rowIndex: number | null;
  } | null>(null);
  // One index space for the record and the recovery: rows that are buttons
  // (a plain read-only row is passed over, as the removal and Apply/Cancel
  // rules pass it over), in document order.
  const buttonRowsOf = (panel: HTMLElement): HTMLElement[] =>
    Array.from(panel.querySelectorAll<HTMLLIElement>('li'))
      .map(row => row.querySelector<HTMLElement>('button'))
      .filter((button): button is HTMLElement => button != null);
  const noteSheetFocus = useCallback(
    (sheet: 'manage' | 'fields') => (event: React.FocusEvent) => {
      const row = (event.target as HTMLElement).closest('li');
      const button = row?.querySelector<HTMLElement>('button') ?? null;
      const rowIndex =
        button == null
          ? -1
          : buttonRowsOf(event.currentTarget as HTMLElement).indexOf(button);
      lastSheetFocusRef.current = {
        sheet,
        rowIndex: rowIndex === -1 ? null : rowIndex,
      };
    },
    [],
  );
  const managerRowsRef = useRef(new Map<number, HTMLLIElement>());
  const fieldRowsRef = useRef(new Map<string, HTMLLIElement>());
  const latestFiltersRef = useRef(filters);
  const pendingSheetFocusRef = useRef<PendingSheetFocus | null>(null);
  const pendingMutationFocusRef = useRef(false);

  // The step an open starts on: Add filter directly when an interactive field
  // has nothing to manage yet, otherwise Filters. Neither search field takes
  // focus on open, so the software keyboard stays down until the person taps
  // the search. Add filter opened directly is the flow's entry point: no
  // Filters sheet beneath it, and Done in its footer.
  const isEntryAddFilter = filters.length === 0 && isInteractive;
  const [step, setStep] = useState<SheetStep | null>(() =>
    isOpen ? (isEntryAddFilter ? 'fields' : 'manage') : null,
  );
  const [fieldPickerOrigin, setFieldPickerOrigin] = useState<
    'manage' | 'trigger'
  >(() => (isOpen && isEntryAddFilter ? 'trigger' : 'manage'));
  // The current step, read by the sheets' close reports and by a removal that
  // decides where to speak.
  const stepRef = useRef(step);
  useLayoutEffect(() => {
    stepRef.current = step;
  }, [step]);
  // The draft outlives a step change on purpose: a closing value step stays
  // presented through its exit, and clearing the draft with the step would
  // blank that sheet mid-transition.
  const [draft, setDraft] = useState<FilterDraft | null>(null);
  const draftGenerationRef = useRef(0);
  const nextDraftGeneration = useCallback(() => {
    draftGenerationRef.current += 1;
    return draftGenerationRef.current;
  }, []);
  const [fieldQuery, setFieldQuery] = useState('');
  const [contentQuery, setContentQuery] = useState('');
  const [isClearConfirmationOpen, setIsClearConfirmationOpen] = useState(false);
  const clearAllButtonRef = useRef<HTMLButtonElement>(null);

  // `useAnnounce` delivers inside the open Astryx modal that encloses its
  // caller, and this component renders above the
  // sheets, so it cannot call the hook itself. Each step's body renders a
  // `SheetAnnouncer` inside its BottomSheet, which publishes the dialog's own
  // `announce` here while that step is the active one; the effects below
  // speak through it, so every message about a sheet's content is delivered
  // in that sheet's dialog.
  const announceRef = useRef<AnnounceFn | null>(null);
  const handleAnnounceChange = useCallback((next: AnnounceFn | null) => {
    announceRef.current = next;
  }, []);
  const announce = useCallback((message: string) => {
    announceRef.current?.(message);
  }, []);
  const pendingAnnouncementRef = useRef<string | null>(null);

  // The controlled `isOpen` opens and closes the flow; the step follows it in
  // the render that sees the change, not an effect, so the entry step's sheet
  // opens in the same commit as the flow (React's adjust-state-on-
  // prop-change pattern). Closing from outside — the field became disabled —
  // ends the flow wherever it was, the Clear all confirmation included.
  const [wasOpen, setWasOpen] = useState(isOpen);
  if (isOpen !== wasOpen) {
    setWasOpen(isOpen);
    if (isOpen) {
      // A fresh draft from the committed filters; the entry step is judged
      // against them, not the previous session's draft.
      setFiltersAtOpen(committedFilters);
      setFilters(committedFilters);
      draftRef.current = committedFilters;
      draftEditsRef.current = [];
      const startsOnAddFilter = committedFilters.length === 0 && isInteractive;
      setFieldQuery('');
      setContentQuery('');
      setStep(startsOnAddFilter ? 'fields' : 'manage');
      setFieldPickerOrigin(startsOnAddFilter ? 'trigger' : 'manage');
    } else {
      setStep(null);
      setIsClearConfirmationOpen(false);
      setIsDiscardConfirmationOpen(false);
    }
  }

  const closeFlow = useCallback(() => {
    pendingSheetFocusRef.current = null;
    setStep(null);
    onOpenChange(false);
  }, [onOpenChange]);
  // Done replays each edit in order onto the field's latest filters, so a
  // consumer gets the calls a popover session makes and keeps a filter it
  // added meanwhile.
  const commitAndClose = useCallback(() => {
    // A field that became read-only while the flow was open reports nothing.
    if (isDraftDirty && isInteractive) {
      replayDraftEdits(committedFilters, draftEditsRef.current, onCommit);
    }
    draftEditsRef.current = [];
    closeFlow();
  }, [closeFlow, committedFilters, isDraftDirty, isInteractive, onCommit]);
  const requestDismiss = useCallback(() => {
    if (isDraftDirty) {
      setIsDiscardConfirmationOpen(true);
    } else {
      closeFlow();
    }
  }, [closeFlow, isDraftDirty]);
  const closeDiscardConfirmation = () => {
    // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the confirmation must be gone before focus moves back into the sheet
    flushSync(() => setIsDiscardConfirmationOpen(false));
    const target =
      stepRef.current === 'manage'
        ? (managerAddButtonRef.current ??
          manageSheetRef.current?.closest<HTMLElement>('[tabindex="-1"]'))
        : fieldsSheetRef.current?.closest<HTMLElement>('[tabindex="-1"]');
    target?.focus({preventScroll: true});
  };

  // Whether a Filters row is a button: the field interactive and the
  // filter not read-only. The row opens the value step — the editor for its
  // operator's value type, the built-in nested editor for a `nested` one, or
  // for a filter the config no longer knows the unavailable state — and its
  // trailing remove action removes it, as the popover's token has its × for
  // it.
  const isRowButton = useCallback(
    (filter: PowerSearchFilter): boolean => !filter.isReadOnly && isInteractive,
    [isInteractive],
  );

  // ------------------------------------------------------------------ focus --

  // The control a step change named also becomes where the closing step
  // sheets return focus when their exit ends: a closing sheet that held focus
  // keeps it until then, and BottomSheet then returns it, so the named control
  // receives it even when the first move could not land. With no control
  // named, the closing steps return focus as the flow does.
  const stepReturnTargetRef = useRef<HTMLElement | null>(null);
  const stepFinalFocusRef = useMemo<React.RefObject<HTMLElement | null>>(
    () => ({
      get current() {
        return stepReturnTargetRef.current ?? finalFocusRef.current;
      },
    }),
    [finalFocusRef],
  );
  const placeFocus = (element: HTMLElement | null | undefined) => {
    if (element == null) {
      return;
    }
    stepReturnTargetRef.current = element;
    element.focus({preventScroll: true});
  };
  const focusPendingSheetTarget = useCallback(() => {
    const target = pendingSheetFocusRef.current;
    if (target == null) {
      return;
    }
    pendingSheetFocusRef.current = null;
    if (target.type === 'manager-add') {
      placeFocus(managerAddButtonRef.current);
      return;
    }
    // Add filter's fallback: a controlled update may have removed the field
    // whose row opened the step, or the content-search field itself; the
    // sheet's first focusable control then takes focus — the search field
    // when one shows, else the first field row.
    const firstFieldsControl = () => {
      const panel = fieldsSheetRef.current;
      return (
        panel?.querySelector<HTMLElement>('input') ??
        panel?.querySelector<HTMLElement>('li button') ??
        panel?.querySelector<HTMLElement>('button') ??
        null
      );
    };
    if (target.type === 'content-search') {
      placeFocus(
        contentSearchRef.current?.querySelector<HTMLInputElement>('input') ??
          firstFieldsControl(),
      );
      return;
    }
    if (target.type === 'field') {
      placeFocus(
        fieldRowsRef.current
          .get(target.fieldKey)
          ?.querySelector<HTMLButtonElement>('button') ?? firstFieldsControl(),
      );
      return;
    }
    // The row the step came from, followed across a controlled reorder or
    // clone; when a controlled update removed it, or left two filters it
    // could be, the nearest remaining row that is a button, as after a
    // removal; else Add filter.
    const index =
      resolveFilterIdentityIndex(
        latestFiltersRef.current,
        target.sourceFilter,
        target.sourceSignature,
        target.preferredIndex,
      ) ??
      nearestEditableIndex(
        latestFiltersRef.current,
        target.preferredIndex,
        isRowButton,
      );
    const row = index == null ? null : managerRowsRef.current.get(index);
    const rowButton =
      target.part === 'remove'
        ? (row?.querySelector<HTMLButtonElement>('[data-sheet-remove]') ??
          row?.querySelector<HTMLButtonElement>('button'))
        : row?.querySelector<HTMLButtonElement>('button');
    placeFocus(rowButton ?? managerAddButtonRef.current);
  }, [isRowButton]);

  // A controlled update that unmounts the focused control of the Filters or
  // Add filter sheet leaves focus on the page body inside the open modal.
  // Read before paint on every commit of an open step: when focus is no
  // longer inside the sheet's dialog, the nearest remaining row by the last
  // focused index takes it, else the sheet's first control, else its panel.
  // The pending-target effects below run after and win when a step
  // change named a control.
  useLayoutEffect(() => {
    const last = lastSheetFocusRef.current;
    if (step !== 'manage' && step !== 'fields') {
      return;
    }
    if (last == null || last.sheet !== step) {
      return;
    }
    const panel =
      step === 'manage' ? manageSheetRef.current : fieldsSheetRef.current;
    const dialog = panel?.closest('dialog');
    const active = document.activeElement;
    if (
      panel == null ||
      dialog == null ||
      (active != null && active !== document.body && dialog.contains(active))
    ) {
      return;
    }
    const rowButtons = buttonRowsOf(panel);
    let target: HTMLElement | null = null;
    if (last.rowIndex != null && rowButtons.length > 0) {
      // The following button row, else the last.
      target = rowButtons[Math.min(last.rowIndex, rowButtons.length - 1)];
    }
    target ??=
      panel.querySelector<HTMLElement>('input') ??
      rowButtons[0] ??
      panel.querySelector<HTMLElement>('button') ??
      null;
    if (target != null) {
      target.focus({preventScroll: true});
    } else {
      const focusable = dialog.querySelector<HTMLElement>('[tabindex="-1"]');
      (focusable ?? dialog).focus({preventScroll: true});
    }
  });

  // Both Effects move focus inside the entering sheet — the external system
  // is the document's focus — to the control the step named. They run after
  // the entering sheet's own
  // panel focus (child effects commit first), so the intended control wins,
  // and they acquire nothing, so they need no cleanup. The filters effect is
  // declared first so a mutation that lands in the same commit as the step
  // change resolves its row against the new filters.
  useEffect(() => {
    latestFiltersRef.current = filters;
    if (step === 'manage' && pendingMutationFocusRef.current) {
      pendingMutationFocusRef.current = false;
      focusPendingSheetTarget();
    }
  }, [filters, focusPendingSheetTarget, step]);

  // A target still pending when the flow closes, such as a commit that
  // disabled the field, never carries into the next open.
  useEffect(() => {
    if (step == null) {
      stepReturnTargetRef.current = null;
      pendingSheetFocusRef.current = null;
      return;
    }
    // A step that opens starts with no named return target; a return to
    // Filters keeps the one its commit, or its removal, has just named.
    if (step !== 'manage') {
      stepReturnTargetRef.current = null;
    }
    focusPendingSheetTarget();
  }, [focusPendingSheetTarget, step]);

  // An announcement queued by a step change — a suggestion or a removal that
  // changed the filters — is spoken in the commit that shows the next step,
  // so it lands in that step's dialog region rather than the one about to
  // close. It synchronizes the live region named above and acquires nothing.
  useEffect(() => {
    const message = pendingAnnouncementRef.current;
    if (step != null && message != null) {
      pendingAnnouncementRef.current = null;
      announce(message);
    }
  }, [announce, step]);

  // ----------------------------------------------------------------- fields --

  // Every visible field lists: the value step edits every operator's value,
  // `nested` through the popover's built-in editor.
  const fields = useMemo(() => config.getVisibleFields(), [config]);

  const normalizedFieldQuery = fieldQuery.trim().toLowerCase();
  const matchingFields = useMemo(() => {
    const matches = fields.filter(field =>
      fieldMatchesQuery(field, normalizedFieldQuery),
    );
    return normalizedFieldQuery === ''
      ? matches
      : matches.slice(0, maxSearchResults);
  }, [fields, maxSearchResults, normalizedFieldQuery]);

  // Ungrouped fields first, then each group in first-appearance order — the
  // same grouping the popover presentation's field suggestions use
  // (`groupItems` with `ungroupedFirst`), so the two presentations
  // list a config's fields in one order.
  const groupedFields = useMemo(
    () =>
      matchingFields.length === 0
        ? []
        : groupItems(
            matchingFields.map(field => ({
              id: field.key,
              label: field.label,
              auxiliaryData: {group: field.group},
              field,
            })),
            {ungroupedFirst: true},
          ).map(
            group =>
              [
                group.heading ?? '',
                group.items.map(item => item.field),
              ] as const,
          ),
    [matchingFields],
  );

  const isFieldSearchShown = fields.length >= SEARCHABLE_FIELD_COUNT;

  // A field whose only operator takes an `empty` value is a one-tap filter:
  // its row adds it with no value step, and shows a plus, not a chevron.
  const isImmediateAddField = useCallback(
    (field: PowerSearchField): boolean => {
      const operators = config.getVisibleOperators(field.key);
      return operators.length === 1 && operators[0].value.type === 'empty';
    },
    [config],
  );

  // The steps stack: each opens above the sheet that led to it, which stays
  // open beneath. Add filter entered directly has no Filters sheet beneath.
  const isFieldPickerDirectEntry = fieldPickerOrigin === 'trigger';
  const isManageSheetOpen =
    step === 'manage' ||
    (step === 'fields' && !isFieldPickerDirectEntry) ||
    (step === 'value' && (draft?.mode === 'edit' || !isFieldPickerDirectEntry));
  const isFieldsSheetOpen =
    step === 'fields' || (step === 'value' && draft?.mode === 'create');

  // The suggestions derive synchronously from the config, so a list never
  // waits on a request: an empty list means an empty result, not a pending
  // one. They stay listed while the value step covers Add filter.
  const contentResults = useMemo(() => {
    if (!isFieldsSheetOpen || !hasContentSearch || !isInteractive) {
      return [];
    }
    const results =
      contentQuery.trim() === ''
        ? suggestionSource.bootstrap()
        : suggestionSource.search(contentQuery);
    return results.slice(0, MAX_BROWSE_MENU_ITEMS);
  }, [
    contentQuery,
    hasContentSearch,
    isFieldsSheetOpen,
    isInteractive,
    suggestionSource,
  ]);

  // The field's result count, while a sheet is open: the owner's own Effect
  // is quiet then, so the change is spoken here, inside the dialog. Only a
  // change after the flow opened is spoken.
  const announcedResultCountRef = useRef(resultCountText);
  useEffect(() => {
    if (resultCountText === announcedResultCountRef.current) {
      return;
    }
    announcedResultCountRef.current = resultCountText;
    if (step != null && resultCountText != null) {
      announce(resultCountText);
    }
  }, [announce, resultCountText, step]);

  // ------------------------------------------------------------------ draft --

  const draftField = draft ? config.getField(draft.field) : undefined;
  const draftOperator =
    draft?.operator != null
      ? config.getOperator(draft.field, draft.operator)
      : undefined;
  const draftOperators = useMemo(
    () => (draft ? config.getVisibleOperators(draft.field) : []),
    [config, draft],
  );

  // The two parts of a Filters row's text for `filter`: "{field} {operator}"
  // as one catalog message, and the value as the popover presentation's
  // token shows it — the same function, so the same words and the same zone
  // handling, before the token's width budget. The rows render these, and
  // the removal announcement joins them, so the three can never
  // disagree.
  const describeFilterParts = useCallback(
    (filter: PowerSearchFilter): {label: string; value: string | null} => {
      const field = config.getField(filter.field);
      const operator = config.getOperator(filter.field, filter.operator);
      // A filter whose field or operator the config no longer has still
      // lists, by its raw keys, as its token does on the trigger; its row
      // opens the unavailable step, and its trailing remove action removes
      // it.
      const fieldLabel = field?.label ?? filter.field;
      const operatorLabel =
        operator == null ? filter.operator : resolveOperatorLabel(operator, t);
      const label = operatorLabel
        ? t('@astryx.powersearch.sheet.fieldOperator', {
            field: fieldLabel,
            operator: operatorLabel,
          })
        : fieldLabel;
      if (operator == null) {
        return {label, value: null};
      }
      // A relative-date value is stored as a key (`3d_ago`); the row reads it
      // as the value step's choice row does ("3 days ago"), through the
      // catalog's relative-date messages, so the sheet agrees with itself. The popover token
      // shows the stored key (a known gap of the record).
      const value =
        operator.value.type === 'date_relative' &&
        filter.value.type === 'date_relative'
          ? resolveRelativeDateLabel(
              operator.value,
              filter.value.value,
              t,
              editors.buildRelativeDateOptions,
            )
          : formatTokenValueText(
              operator.value,
              filter.value,
              Number.MAX_SAFE_INTEGER,
              locale,
              calendar,
              t,
              formatList,
              timezoneID,
            );
      return {label, value};
    },
    [calendar, config, editors, formatList, locale, t, timezoneID],
  );
  const describeFilter = useCallback(
    (filter: PowerSearchFilter): string => {
      const parts = describeFilterParts(filter);
      return parts.value
        ? t('@astryx.powersearch.sheet.labelValue', {
            label: parts.label,
            value: parts.value,
          })
        : parts.label;
    },
    [describeFilterParts, t],
  );

  const openFieldList = useCallback(() => {
    if (!isInteractive) {
      return;
    }
    setFieldPickerOrigin('manage');
    setFieldQuery('');
    setContentQuery('');
    pendingSheetFocusRef.current = null;
    setStep('fields');
  }, [isInteractive]);

  const queueManagerAddFocus = useCallback(() => {
    pendingSheetFocusRef.current = {type: 'manager-add'};
  }, []);

  const commitSavedFilter = useCallback(
    (next: FilterDraft, filter: PowerSearchFilter) => {
      if (!isInteractive) {
        queueManagerAddFocus();
        setStep('manage');
        return;
      }
      if (next.mode === 'edit') {
        const filterIndex = resolveDraftFilterIndex(filters, next);
        const currentFilter =
          filterIndex == null ? undefined : filters[filterIndex];
        if (
          filterIndex == null ||
          currentFilter == null ||
          currentFilter.isReadOnly
        ) {
          // A controlled update removed the edited filter, or left two it
          // could be, or made it read-only: nothing is written, and focus
          // returns to the nearest row that is a button around where it was,
          // else Add filter.
          pendingSheetFocusRef.current =
            next.sourceFilter != null &&
            next.sourceSignature != null &&
            next.filterIndex != null
              ? {
                  type: 'manager-filter',
                  sourceFilter: next.sourceFilter,
                  sourceSignature: next.sourceSignature,
                  preferredIndex: next.filterIndex,
                }
              : {type: 'manager-add'};
          setStep('manage');
          return;
        }
        pendingSheetFocusRef.current = {
          type: 'manager-filter',
          sourceFilter: filter,
          sourceSignature: filterSignature(filter),
          preferredIndex: filterIndex,
        };
        const updated = [...filters];
        updated[filterIndex] = filter;
        onChange(updated, 'edit', filterIndex);
      } else {
        queueManagerAddFocus();
        onChange([...filters, filter], 'add', filters.length);
      }
      setStep('manage');
    },
    [filters, isInteractive, onChange, queueManagerAddFocus],
  );

  // Opening a new filter can come from a field row or a content-search
  // suggestion. The origin is kept so Cancel returns to the control the person
  // came from.
  const openCreateEditor = useCallback(
    (
      field: PowerSearchField,
      operator: PowerSearchOperator,
      returnFocus: 'field' | 'content-search' = 'field',
    ) => {
      setDraft({
        mode: 'create',
        generation: nextDraftGeneration(),
        returnFocus,
        field: field.key,
        operator: operator.key,
        value: operator.value.type === 'empty' ? {type: 'empty'} : undefined,
      });
      pendingSheetFocusRef.current = null;
      setStep('value');
    },
    [nextDraftGeneration],
  );

  const handleFieldSelect = useCallback(
    (field: PowerSearchField) => {
      if (!isInteractive) {
        return;
      }
      // A one-tap filter has nothing to stage: choosing its field adds it
      // and returns to Filters.
      if (isImmediateAddField(field)) {
        const [operator] = config.getVisibleOperators(field.key);
        const nextFilter: PowerSearchFilter = {
          field: field.key,
          operator: operator.key,
          value: {type: 'empty'},
        };
        pendingSheetFocusRef.current = {
          type: 'manager-filter',
          sourceFilter: nextFilter,
          sourceSignature: filterSignature(nextFilter),
          preferredIndex: filters.length,
        };
        pendingMutationFocusRef.current = true;
        onChange([...filters, nextFilter], 'add', filters.length);
        pendingAnnouncementRef.current = t('@astryx.tokenizer.tokenAdded', {
          label: describeFilter(nextFilter),
        });
        setStep('manage');
        return;
      }
      const operator =
        config.getDefaultOperator(field.key) ?? field.operators[0];
      if (operator == null) {
        return;
      }
      openCreateEditor(field, operator);
    },
    [
      config,
      describeFilter,
      filters,
      isImmediateAddField,
      isInteractive,
      onChange,
      openCreateEditor,
      t,
    ],
  );

  const handleContentSuggestionSelect = useCallback(
    (item: PowerSearchItem | null) => {
      if (!isInteractive || item?.auxiliaryData == null) {
        return;
      }
      const {fieldKey, filterValue, operatorKey} = item.auxiliaryData;
      const field = config.getField(fieldKey);
      const operator =
        operatorKey == null
          ? config.getDefaultOperator(fieldKey)
          : config.getOperator(fieldKey, operatorKey);
      if (field == null || operator == null) {
        return;
      }
      setContentQuery('');
      if (filterValue != null) {
        const nextFilter: PowerSearchFilter = {
          field: field.key,
          operator: operator.key,
          value: filterValue,
        };
        pendingSheetFocusRef.current = {
          type: 'manager-filter',
          sourceFilter: nextFilter,
          sourceSignature: filterSignature(nextFilter),
          preferredIndex: filters.length,
        };
        pendingMutationFocusRef.current = true;
        onChange([...filters, nextFilter], 'add', filters.length);
        // The same announcement the popover presentation's typeahead add
        // makes, so assistive technology hears one phrase for one outcome;
        // spoken once the Filters sheet is the open dialog.
        pendingAnnouncementRef.current = t('@astryx.tokenizer.tokenAdded', {
          label: item.label,
        });
        setStep('manage');
        return;
      }
      openCreateEditor(field, operator, 'content-search');
    },
    [config, filters, isInteractive, onChange, openCreateEditor, t],
  );

  const handleFilterEdit = useCallback(
    (index: number) => {
      const filter = filters[index];
      if (!isInteractive || filter == null || filter.isReadOnly) {
        return;
      }
      setDraft({
        mode: 'edit',
        generation: nextDraftGeneration(),
        filterIndex: index,
        sourceFilter: filter,
        sourceSignature: filterSignature(filter),
        field: filter.field,
        operator: filter.operator,
        value: filter.value,
      });
      pendingSheetFocusRef.current = null;
      setStep('value');
    },
    [filters, isInteractive, nextDraftGeneration],
  );

  const handleRemoveFilter = useCallback(
    (index: number) => {
      const filter = filters[index];
      if (!isInteractive || filter == null || filter.isReadOnly) {
        return;
      }
      const nextFilters = filters.filter((_, i) => i !== index);
      const nextIndex = nearestEditableIndex(nextFilters, index, isRowButton);
      if (nextIndex == null) {
        pendingSheetFocusRef.current = {type: 'manager-add'};
      } else {
        const nextFilter = nextFilters[nextIndex];
        pendingSheetFocusRef.current = {
          type: 'manager-filter',
          sourceFilter: nextFilter,
          sourceSignature: filterSignature(nextFilter),
          preferredIndex: nextIndex,
          part: 'remove',
        };
      }
      pendingMutationFocusRef.current = true;
      onChange(nextFilters, 'remove', index);
      // The popover presentation's token × announces the same phrase. A
      // removal from a Filters row stays in that sheet and speaks at once; a
      // caller's Editor that removes while returning to Filters speaks once
      // the Filters sheet is the open dialog.
      const message = t('@astryx.tokenizer.tokenRemoved', {
        label: describeFilter(filter),
      });
      if (stepRef.current === 'manage') {
        announce(message);
      } else {
        pendingAnnouncementRef.current = message;
      }
    },
    [
      announce,
      describeFilter,
      filters,
      isInteractive,
      isRowButton,
      onChange,
      t,
    ],
  );

  // Closing Clear all's confirmation. Kept, focus returns to Clear all.
  // Confirmed, Clear all removes the filters the person can edit and keeps
  // read-only ones, which are the consumer's: one `remove` at the first
  // removed index. The Filters sheet stays open for further editing. The
  // confirmation must be gone before focus moves into the sheet and the
  // outcome is routed into the sheet's region, so its close is flushed
  // first. The outcome is "Editable filters removed" while a read-only filter
  // remains, otherwise "All filters removed"; the result count follows the
  // applied filters, which change on Done, so none changes here. Focus moves
  // to the sheet's first remaining control: a kept read-only row has none,
  // so Add filter.
  const closeClearConfirmation = (confirmed: boolean) => {
    const kept = filters.filter(filter => filter.isReadOnly);
    const firstRemovedIndex = filters.findIndex(filter => !filter.isReadOnly);
    const isClearing = confirmed && isInteractive && firstRemovedIndex >= 0;
    // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the confirmation must be gone before focus moves into the sheet and the words are routed into it
    flushSync(() => {
      setIsClearConfirmationOpen(false);
      if (isClearing) {
        onChange(kept, 'remove', firstRemovedIndex);
      }
    });
    if (!isClearing) {
      clearAllButtonRef.current?.focus();
      return;
    }
    managerAddButtonRef.current?.focus({preventScroll: true});
    announce(
      kept.length > 0
        ? t('@astryx.powersearch.editableFiltersRemoved')
        : t('@astryx.powersearch.allFiltersRemoved'),
    );
  };

  const handleOperatorSelect = useCallback((operator: PowerSearchOperator) => {
    setDraft(current => {
      if (current == null) {
        return current;
      }
      // A value survives an operator change only when the new operator
      // reads the same value type.
      const keepsValue =
        current.value != null && current.value.type === operator.value.type;
      return {
        ...current,
        operator: operator.key,
        value:
          operator.value.type === 'empty'
            ? {type: 'empty'}
            : keepsValue
              ? current.value
              : undefined,
      };
    });
  }, []);

  const handleDraftValueChange = useCallback((value: FilterValue) => {
    setDraft(current => (current == null ? current : {...current, value}));
  }, []);
  // The number input's draft was cleared or stopped parsing: nothing stands
  // to confirm, so the confirm action disables again.
  const handleDraftUnstage = useCallback(() => {
    setDraft(current =>
      current == null ? current : {...current, value: undefined},
    );
  }, []);

  const handleSave = useCallback(() => {
    if (draft?.value == null || draft.operator == null) {
      return;
    }
    commitSavedFilter(draft, {
      field: draft.field,
      operator: draft.operator,
      value: draft.value,
    });
  }, [commitSavedFilter, draft]);

  const returnFromValue = useCallback(() => {
    if (draft == null) {
      queueManagerAddFocus();
      setStep('manage');
      return;
    }
    if (
      draft.mode === 'edit' &&
      draft.sourceFilter != null &&
      draft.sourceSignature != null &&
      draft.filterIndex != null
    ) {
      pendingSheetFocusRef.current = {
        type: 'manager-filter',
        sourceFilter: draft.sourceFilter,
        sourceSignature: draft.sourceSignature,
        preferredIndex:
          resolveDraftFilterIndex(filters, draft) ?? draft.filterIndex,
      };
      setStep('manage');
      return;
    }
    if (draft.returnFocus === 'content-search') {
      pendingSheetFocusRef.current = {type: 'content-search'};
      setStep('fields');
      return;
    }
    pendingSheetFocusRef.current = {type: 'field', fieldKey: draft.field};
    setStep('fields');
  }, [draft, filters, queueManagerAddFocus]);

  const handleRemove = useCallback(() => {
    if (draft?.mode !== 'edit') {
      return;
    }
    const filterIndex = resolveDraftFilterIndex(filters, draft);
    if (filterIndex == null || filters[filterIndex]?.isReadOnly) {
      queueManagerAddFocus();
      setStep('manage');
      return;
    }
    handleRemoveFilter(filterIndex);
    setStep('manage');
  }, [draft, filters, handleRemoveFilter, queueManagerAddFocus]);

  // Each step sheet is controlled by `step`; a sheet only ever asks to close
  // (a dismissal its `purpose` allows: Escape, the scrim, a swipe, a platform
  // close request), which only the top sheet of the stack receives. Closing
  // the top step reveals the step beneath it; closing the bottom one ends the
  // flow. A stale report from a step that is no longer current is ignored.
  // Every step change goes through the handlers above.
  const handleManageOpenChange = useCallback(
    (isSheetOpen: boolean) => {
      if (!isSheetOpen && stepRef.current === 'manage') {
        requestDismiss();
      }
    },
    [requestDismiss],
  );
  const handleFieldsOpenChange = useCallback(
    (isSheetOpen: boolean) => {
      if (isSheetOpen || stepRef.current !== 'fields') {
        return;
      }
      if (fieldPickerOrigin === 'trigger') {
        requestDismiss();
        return;
      }
      queueManagerAddFocus();
      setStep('manage');
    },
    [fieldPickerOrigin, queueManagerAddFocus, requestDismiss],
  );
  const handleValueOpenChange = useCallback(
    (isSheetOpen: boolean) => {
      if (!isSheetOpen && stepRef.current === 'value') {
        returnFromValue();
      }
    },
    [returnFromValue],
  );

  // ---------------------------------------------------------------- render --

  // Rows are keyed by filter identity, not position: a parent's reorder or a
  // removal above the focused row then moves elements instead of remounting
  // them, and focus stays on the same filter. Only a filter that is
  // itself removed loses its element, and the re-home effect above takes
  // over.
  const [filterIdentities] = useState(createFilterIdentities);
  const filterIds = filterIdentities.next(filters);
  const filterRows = filters.map((filter, index) => {
    const {label, value} = describeFilterParts(filter);
    const isEditable = isRowButton(filter);
    // The row reads from the same catalog message the removal announcement
    // uses (`labelValue`), so a locale that reorders it reorders both: the
    // message is formatted with a placeholder for the value, and the text
    // either side of that placeholder wraps the bold value.
    let displayLabel: ReactNode = label;
    if (value) {
      const [before, after] = t('@astryx.powersearch.sheet.labelValue', {
        label,
        value: ROW_VALUE_SLOT,
      }).split(ROW_VALUE_SLOT);
      displayLabel = (
        <>
          {before}
          <span {...stylex.props(styles.rowValue)}>{value}</span>
          {after}
        </>
      );
    }
    return {
      displayLabel,
      filter,
      index,
      isEditable,
      key: `filter-${filterIds[index]}`,
    };
  });

  const hasRemovableFilter = filters.some(filter => !filter.isReadOnly);
  const isClearAllShown = hasClear && isInteractive && hasRemovableFilter;

  const EditorOverride =
    draftOperator != null
      ? componentOverrides?.[draftOperator.value.type]?.Editor
      : undefined;

  const draftOperatorLabel =
    draftOperator == null ? '' : resolveOperatorLabel(draftOperator, t);
  // The title names the filter's own operator when the step offers no
  // Operator group: one visible operator, or an operator the config no longer
  // lists as visible. The step then never shows another operator's name.
  const showsOperatorGroup =
    draftOperators.length > 1 &&
    draftOperator != null &&
    draftOperators.includes(draftOperator);
  // The title — the dialog's name — reads the field and operator as
  // the Filters row does: by their labels, or, for a filter whose field or
  // operator the config no longer has, by the raw keys the row shows.
  const editorTitle =
    draft == null
      ? t('@astryx.powersearch.sheet.addFilter')
      : draftField == null || (draftOperator == null && draft.operator != null)
        ? t('@astryx.powersearch.sheet.fieldOperator', {
            field: draftField?.label ?? draft.field,
            operator:
              draftOperatorLabel !== ''
                ? draftOperatorLabel
                : (draft.operator ?? ''),
          }).trim()
        : !showsOperatorGroup && draftOperatorLabel !== ''
          ? t('@astryx.powersearch.sheet.fieldOperator', {
              field: draftField.label,
              operator: draftOperatorLabel,
            })
          : draftField.label;
  const saveButtonLabel =
    saveButtonLabelFromProps ??
    (draft?.mode === 'edit'
      ? t('@astryx.powersearch.editor.apply')
      : t('@astryx.powersearch.sheet.addFilter'));

  // Every sheet body: padded, and publishing that padding to its lists.
  const bodyProps = stylex.props(
    styles.body,
    containerPaddingInlineVarStyles[4],
  );
  const scrollContentProps = stylex.props(
    styles.scrollContent,
    containerPaddingInlineVarStyles[4],
  );
  const controlSectionProps = stylex.props(styles.controlSection);

  // A vertical touch drag on the Add filter rows moves focus off a focused
  // search to the sheet, so the software keyboard leaves and the rows can be
  // read.
  const fieldPickerDragProps = useDismissSearchOnTouchDrag(
    () => [
      contentSearchRef.current?.querySelector('input'),
      fieldSearchRef.current?.querySelector('input'),
    ],
    () => fieldsSheetRef.current?.closest<HTMLElement>('[tabindex="-1"]'),
  );

  const isEditorDisabled = isDisabled || isReadOnly;
  const isSaveDisabled =
    isEditorDisabled || draft?.operator == null || draft.value == null;
  // The step has something to edit when the field and operator still exist
  // (a controlled config update can remove either). A caller's `Editor`
  // override replaces the body for its value type with the props the popover
  // hands it; otherwise a `nested` value takes the popover's built-in
  // NestedEditor and every other type the sheet's own control.
  const isDraftRenderable =
    draft != null && draftField != null && draftOperator != null;
  const isDraftNested =
    isDraftRenderable && !isSupportedOperator(draftOperator);
  // A controlled config update that removes the field or operator being
  // edited replaces the step's body with the unavailable state while focus
  // may be on one of the body's controls, which unmount without a blur. Focus
  // then moves to Cancel, the way back to the Filters row whose remove action
  // is the removal path, so it never falls to the page body inside the open
  // sheet. The message itself is announced by its rendered element.
  const cancelButtonRef = useRef<HTMLButtonElement>(null);
  const wasDraftRenderableRef = useRef(isDraftRenderable);
  useLayoutEffect(() => {
    const becameUnavailable =
      wasDraftRenderableRef.current && !isDraftRenderable && draft != null;
    wasDraftRenderableRef.current = isDraftRenderable;
    if (!becameUnavailable || step !== 'value') {
      return;
    }
    const active = document.activeElement;
    const dialog = cancelButtonRef.current?.closest('dialog');
    if (dialog != null && active != null && dialog.contains(active)) {
      return;
    }
    cancelButtonRef.current?.focus();
  }, [draft, isDraftRenderable, step]);
  // The operator group stays outside either editor, so switching operators
  // swaps the body — a `nested` operator beside a plain one included.
  const operatorGroup = isDraftRenderable && showsOperatorGroup && (
    <RadioList
      label={t('@astryx.powersearch.editor.operator')}
      isLabelHidden
      value={draft.operator ?? ''}
      onChange={operatorKey => {
        const operator = draftOperators.find(
          candidate => candidate.key === operatorKey,
        );
        if (operator != null) {
          handleOperatorSelect(operator);
        }
      }}
      isDisabled={isEditorDisabled}>
      {draftOperators.map(operator => (
        <RadioListItem
          key={operator.key}
          label={t('@astryx.powersearch.sheet.fieldOperator', {
            field: draftField.label,
            operator: resolveOperatorLabel(operator, t),
          })}
          value={operator.key}
        />
      ))}
    </RadioList>
  );
  // The step's Operator group owns the operator choice, so the built-in
  // nested editor's root operator picker is hidden and its root shows the
  // checked operator's label.
  const nestedOperatorOptions = useMemo(
    () =>
      draftOperator == null
        ? []
        : [
            {
              value: draftOperator.key,
              label: resolveOperatorLabel(draftOperator, t),
            },
          ],
    [draftOperator, t],
  );
  const handleNestedDraftChange = useCallback((next: PartialFilter) => {
    setDraft(current =>
      current == null ? current : {...current, value: next.value},
    );
  }, []);

  const valueEditor =
    isDraftRenderable &&
    (isDraftNested ? (
      <NestedEditor
        key={`${draft.generation}-${draft.field}-${draft.operator}`}
        config={config}
        partialFilter={{
          field: draft.field,
          operator: draft.operator,
          value: draft.value,
        }}
        operatorOptions={nestedOperatorOptions}
        hasRootOperatorPicker={false}
        onOperatorChange={() => {}}
        onPartialFilterChange={handleNestedDraftChange}
        maxMenuItems={maxOperatorMenuItems}
        timezoneID={timezoneID}
        isReadOnly={isEditorDisabled}
        xstyle={styles.nestedEditorContainer}
      />
    ) : (
      <SheetValueEditor
        key={`${draft.generation}-${draft.field}-${draft.operator}`}
        operatorValue={draftOperator.value}
        filterValue={draft.value}
        onChange={handleDraftValueChange}
        onUnstage={handleDraftUnstage}
        config={config}
        fieldLabel={draftField.label}
        isDisabled={isEditorDisabled}
        maxMenuItems={maxOperatorMenuItems}
        timezoneID={timezoneID}
        editors={editors}
      />
    ));

  return (
    <>
      <BottomSheet
        isOpen={isManageSheetOpen}
        onOpenChange={handleManageOpenChange}
        finalFocusRef={finalFocusRef}
        label={t('@astryx.powersearch.sheet.filtersTitle')}
        height="tall"
        padding={0}>
        <div
          ref={manageSheetRef}
          onFocus={noteSheetFocus('manage')}
          {...stylex.props(styles.sheet, styles.sheetWithFixedFooter)}>
          {step === 'manage' && (
            <SheetAnnouncer onAnnounceChange={handleAnnounceChange} />
          )}
          <div {...stylex.props(styles.header)}>
            <div {...stylex.props(styles.headerRow)}>
              <div {...stylex.props(styles.headerText)}>
                <Heading level={3}>
                  {t('@astryx.powersearch.sheet.filtersTitle')}
                </Heading>
              </div>
              {isInteractive && filterRows.length > 0 && (
                <Button
                  ref={managerAddButtonRef}
                  label={t('@astryx.powersearch.sheet.addFilter')}
                  icon={<Icon icon={PlusIcon} size="sm" />}
                  isIconOnly
                  variant="secondary"
                  size="md"
                  xstyle={styles.touchHitArea}
                  onClick={openFieldList}
                />
              )}
            </div>
          </div>
          <div {...stylex.props(styles.scrollViewport)}>
            <div {...scrollContentProps}>
              {filterRows.length === 0 ? (
                // With no filter the single thing to do is the only visible
                // action. Mounted only while the sheet is open, so its text
                // is spoken in this sheet when it appears.
                isManageSheetOpen && (
                  <EmptyState
                    title={t(
                      isDraftDirty
                        ? '@astryx.powersearch.sheet.noFiltersInDraft'
                        : '@astryx.powersearch.sheet.noFilters',
                    )}
                    description={t(
                      '@astryx.powersearch.sheet.noFiltersDescription',
                    )}
                    headingLevel={4}
                    icon={<Icon icon="funnel" size="lg" color="secondary" />}
                    xstyle={styles.emptyState}
                    actions={
                      isInteractive ? (
                        <Button
                          ref={managerAddButtonRef}
                          label={t('@astryx.powersearch.sheet.addFilter')}
                          icon={<Icon icon={PlusIcon} size="sm" />}
                          variant="primary"
                          size="lg"
                          xstyle={styles.touchHitArea}
                          onClick={openFieldList}
                        />
                      ) : undefined
                    }
                  />
                )
              ) : (
                <List hasDividers density="spacious" edge="bleed">
                  {filterRows.map(row => {
                    const operator = config.getOperator(
                      row.filter.field,
                      row.filter.operator,
                    );
                    const fieldLabel =
                      config.getField(row.filter.field)?.label ??
                      row.filter.field;
                    // A one-tap filter has no value to edit: its row removes
                    // it.
                    const isOneTap = operator?.value.type === 'empty';
                    const removeLabel = t(
                      '@astryx.powersearch.sheet.removeFilter',
                      {field: fieldLabel},
                    );
                    return (
                      <ListItem
                        key={row.key}
                        ref={node => {
                          if (node == null) {
                            managerRowsRef.current.delete(row.index);
                          } else {
                            managerRowsRef.current.set(row.index, node);
                          }
                        }}
                        label={row.displayLabel}
                        onClick={
                          row.isEditable
                            ? isOneTap
                              ? () => handleRemoveFilter(row.index)
                              : () => handleFilterEdit(row.index)
                            : undefined
                        }
                        endContent={
                          row.isEditable ? (
                            <IconButton
                              data-sheet-remove=""
                              label={removeLabel}
                              tooltip={removeLabel}
                              icon={<Icon icon="close" size="sm" />}
                              variant="ghost"
                              size="md"
                              xstyle={styles.touchHitArea}
                              onClick={event => {
                                event.stopPropagation();
                                handleRemoveFilter(row.index);
                              }}
                            />
                          ) : undefined
                        }
                      />
                    );
                  })}
                </List>
              )}
            </div>
          </div>
          {/* The footer stays while the draft differs from the applied
              filters: an emptied draft still needs Done to apply the
              removals. */}
          {(filterRows.length > 0 || isDraftDirty) && (
            <div {...stylex.props(styles.footer, styles.fixedFooter)}>
              {isClearAllShown && (
                <Button
                  ref={clearAllButtonRef}
                  label={t('@astryx.powersearch.sheet.clearAll')}
                  variant="secondary"
                  size="lg"
                  xstyle={styles.footerEqualAction}
                  onClick={() => setIsClearConfirmationOpen(true)}
                />
              )}
              <Button
                label={t('@astryx.powersearch.sheet.done')}
                variant="primary"
                size="lg"
                xstyle={
                  isClearAllShown
                    ? styles.footerEqualAction
                    : [styles.footerSoleAction, styles.touchHitArea]
                }
                onClick={commitAndClose}
                width={isClearAllShown ? undefined : '100%'}
              />
            </div>
          )}
        </div>
      </BottomSheet>

      <BottomSheet
        isOpen={isFieldsSheetOpen}
        onOpenChange={handleFieldsOpenChange}
        finalFocusRef={stepFinalFocusRef}
        label={t('@astryx.powersearch.sheet.addFilter')}
        height="tall"
        padding={0}>
        <div
          ref={fieldsSheetCallbackRef}
          onFocus={noteSheetFocus('fields')}
          onKeyDown={hasContentSearch ? handleContentListKeyDown : undefined}
          {...stylex.props(styles.sheet, styles.sheetWithFixedFooter)}>
          {step === 'fields' && (
            <SheetAnnouncer onAnnounceChange={handleAnnounceChange} />
          )}
          <div {...stylex.props(styles.header)}>
            <div {...stylex.props(styles.headerRow)}>
              <div {...stylex.props(styles.headerText)}>
                <Heading level={3}>
                  {t('@astryx.powersearch.sheet.addFilter')}
                </Heading>
              </div>
            </div>
            {hasContentSearch ? (
              <div ref={contentSearchRef}>
                <TextInput
                  label={t('@astryx.powersearch.sheet.search')}
                  isLabelHidden
                  role="searchbox"
                  aria-controls={contentResultsId}
                  value={contentQuery}
                  onChange={setContentQuery}
                  onKeyDown={event => {
                    if (isImeKeyEvent(event.nativeEvent)) {
                      return;
                    }
                    if (event.key === 'Enter' && contentResults[0] != null) {
                      event.preventDefault();
                      handleContentSuggestionSelect(contentResults[0]);
                    }
                  }}
                  placeholder={placeholder}
                  hasClear
                  startIcon={<Icon icon="search" size="sm" color="secondary" />}
                  isDisabled={!isInteractive}
                  size="lg"
                  width="100%"
                />
              </div>
            ) : isFieldSearchShown ? (
              <div ref={fieldSearchRef}>
                <TextInput
                  label={t('@astryx.powersearch.sheet.searchFields')}
                  isLabelHidden
                  placeholder={t(
                    '@astryx.powersearch.sheet.searchFieldsPlaceholder',
                  )}
                  value={fieldQuery}
                  onChange={setFieldQuery}
                  startIcon={<Icon icon="search" size="sm" color="secondary" />}
                  isDisabled={!isInteractive}
                  size="lg"
                  width="100%"
                />
              </div>
            ) : null}
          </div>
          <div
            {...stylex.props(styles.scrollViewport)}
            {...fieldPickerDragProps}>
            <div {...scrollContentProps}>
              {hasContentSearch ? (
                contentResults.length > 0 ? (
                  <List
                    id={contentResultsId}
                    aria-label={t('@astryx.powersearch.sheet.searchResults')}
                    hasDividers
                    density="spacious"
                    edge="bleed">
                    {contentResults.map(item => (
                      <ListItem
                        key={item.id}
                        label={item.label}
                        isDisabled={!isInteractive}
                        onClick={() => handleContentSuggestionSelect(item)}
                      />
                    ))}
                  </List>
                ) : contentQuery.trim() !== '' ? (
                  // The searchbox's `aria-controls` target while nothing
                  // lists. The empty state mounts only while this step is the
                  // open one and is spoken from its rendered text, once per
                  // query that matches nothing.
                  <div id={contentResultsId}>
                    {step === 'fields' && (
                      <EmptyState
                        key={contentQuery}
                        icon={
                          <Icon icon="search" size="lg" color="secondary" />
                        }
                        title={t('@astryx.powersearch.sheet.noResults')}
                        description={t(
                          '@astryx.powersearch.sheet.tryDifferentSearch',
                        )}
                        headingLevel={4}
                        isCompact
                        xstyle={styles.emptyState}
                      />
                    )}
                  </div>
                ) : (
                  // An empty query with no bootstrap suggestion: the results
                  // region exists, empty, so the searchbox's `aria-controls`
                  // always names an element in the document.
                  <div id={contentResultsId} />
                )
              ) : groupedFields.length === 0 ? (
                // A search outcome: only a non-empty query that matches
                // nothing shows it; a config with no field lists nothing.
                normalizedFieldQuery !== '' &&
                step === 'fields' && (
                  <EmptyState
                    key={normalizedFieldQuery}
                    icon={<Icon icon="search" size="lg" color="secondary" />}
                    title={t('@astryx.powersearch.sheet.noMatchingFields')}
                    description={t(
                      '@astryx.powersearch.sheet.tryDifferentSearch',
                    )}
                    headingLevel={4}
                    isCompact
                    xstyle={styles.emptyState}
                  />
                )
              ) : (
                groupedFields.map(([group, groupFields]) => (
                  <List
                    key={group}
                    hasDividers
                    density="spacious"
                    header={
                      <Heading level={4}>
                        {group === ''
                          ? t('@astryx.powersearch.sheet.ungroupedFields')
                          : group}
                      </Heading>
                    }
                    edge="bleed">
                    {groupFields.map(field => (
                      <ListItem
                        key={field.key}
                        ref={node => {
                          if (node == null) {
                            fieldRowsRef.current.delete(field.key);
                          } else {
                            fieldRowsRef.current.set(field.key, node);
                          }
                        }}
                        label={field.label}
                        isDisabled={!isInteractive}
                        startContent={field.icon}
                        endContent={
                          isImmediateAddField(field) ? (
                            <Icon icon={PlusIcon} size="sm" color="secondary" />
                          ) : (
                            <Icon
                              icon="chevronRight"
                              size="sm"
                              color="secondary"
                              xstyle={rtlStyles.mirror}
                            />
                          )
                        }
                        onClick={() => handleFieldSelect(field)}
                      />
                    ))}
                  </List>
                ))
              )}
            </div>
          </div>
          {isFieldPickerDirectEntry && (
            <div {...stylex.props(styles.footer, styles.fixedFooter)}>
              <Button
                label={t('@astryx.powersearch.sheet.done')}
                variant="primary"
                width="100%"
                xstyle={styles.touchAction}
                onClick={commitAndClose}
              />
            </div>
          )}
        </div>
      </BottomSheet>

      <BottomSheet
        isOpen={step === 'value'}
        onOpenChange={handleValueOpenChange}
        finalFocusRef={stepFinalFocusRef}
        label={editorTitle}
        height="tall"
        padding={0}
        purpose="info">
        <div {...stylex.props(styles.sheet)}>
          <div {...stylex.props(styles.header, styles.headerScrollsToTop)}>
            <div {...stylex.props(styles.headerRow)}>
              <div {...stylex.props(styles.headerText)}>
                <Heading level={3} maxLines={1}>
                  {editorTitle}
                </Heading>
              </div>
            </div>
          </div>
          {isDraftRenderable && EditorOverride != null ? (
            <div {...bodyProps}>
              {step === 'value' && (
                <SheetAnnouncer onAnnounceChange={handleAnnounceChange} />
              )}
              {operatorGroup && (
                <div {...controlSectionProps}>{operatorGroup}</div>
              )}
              <EditorOverride
                key={`${draft.generation}-${draft.field}-${draft.operator}`}
                config={configProp}
                filter={{
                  field: draft.field,
                  operator: draft.operator,
                  value: draft.value,
                }}
                mode={draft.mode}
                onSave={saved => {
                  if (saved == null) {
                    if (draft.mode === 'edit') {
                      handleRemove();
                    } else {
                      queueManagerAddFocus();
                      setStep('manage');
                    }
                    return;
                  }
                  commitSavedFilter(draft, saved);
                }}
                onCancel={returnFromValue}
                saveButtonLabel={saveButtonLabel}
                isReadOnly={isEditorDisabled}
                timezoneID={timezoneID}
              />
            </div>
          ) : (
            <>
              <div {...bodyProps}>
                {step === 'value' && (
                  <SheetAnnouncer onAnnounceChange={handleAnnounceChange} />
                )}
                {isDraftRenderable ? (
                  // A lone editor sits on the sheet's surface; with the
                  // Operator group above it, each section is a muted
                  // container.
                  operatorGroup ? (
                    <>
                      <div {...controlSectionProps}>{operatorGroup}</div>
                      <div {...controlSectionProps}>{valueEditor}</div>
                    </>
                  ) : (
                    valueEditor
                  )
                ) : (
                  // A controlled config update removed the field or operator
                  // being edited: say so (the element's rendered text is
                  // announced, once per opened filter, while this step is the
                  // open one) and keep a way out.
                  draft != null && (
                    <SheetEmptyMessage
                      message={t('@astryx.powersearch.sheet.filterUnavailable')}
                      occasion={String(draft.generation)}
                      isShown={step === 'value'}
                    />
                  )
                )}
              </div>
              <div {...stylex.props(styles.footer)}>
                {isReadOnly ? (
                  <Button
                    ref={cancelButtonRef}
                    label={t('@astryx.powersearch.editor.cancel')}
                    variant="secondary"
                    width="100%"
                    xstyle={[styles.footerSoleAction, styles.touchHitArea]}
                    onClick={returnFromValue}
                  />
                ) : (
                  <>
                    <Button
                      ref={cancelButtonRef}
                      label={t('@astryx.powersearch.editor.cancel')}
                      variant="secondary"
                      size="lg"
                      xstyle={styles.footerEqualAction}
                      onClick={returnFromValue}
                    />
                    {isDraftRenderable && (
                      <Button
                        label={saveButtonLabel}
                        variant="primary"
                        size="lg"
                        isDisabled={isSaveDisabled}
                        xstyle={styles.footerEqualAction}
                        onClick={handleSave}
                      />
                    )}
                  </>
                )}
              </div>
            </>
          )}
        </div>
      </BottomSheet>

      {isClearConfirmationOpen && (
        <SheetConfirmation
          isOpen
          onOpenChange={isConfirmationOpen => {
            if (!isConfirmationOpen) {
              closeClearConfirmation(false);
            }
          }}
          title={t('@astryx.powersearch.sheet.clearAllTitle')}
          description={t('@astryx.powersearch.sheet.clearAllDescription')}
          actionLabel={t('@astryx.powersearch.sheet.clearAllConfirm')}
          cancelLabel={t('@astryx.powersearch.sheet.clearAllCancel')}
          onAction={() => closeClearConfirmation(true)}
        />
      )}
      {isDiscardConfirmationOpen && (
        <SheetConfirmation
          isOpen
          onOpenChange={isConfirmationOpen => {
            if (!isConfirmationOpen) {
              closeDiscardConfirmation();
            }
          }}
          title={t('@astryx.powersearch.sheet.discardTitle')}
          description={t('@astryx.powersearch.sheet.discardDescription')}
          actionLabel={t('@astryx.powersearch.sheet.discardConfirm')}
          cancelLabel={t('@astryx.powersearch.sheet.keepEditing')}
          onAction={() => {
            setIsDiscardConfirmationOpen(false);
            draftEditsRef.current = [];
            closeFlow();
          }}
        />
      )}
    </>
  );
}

PowerSearchBottomSheet.displayName = 'PowerSearchBottomSheet';