Skip to content

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

TypeScript
290 KB
Raw Blame

schema_version: 3 template_version: 3 kind: component id: component:PowerSearch authority: current archive_reason: null superseded_by: null approved_by: imdreamrunner approved_at: 2026-11-03 owners: [cixzhang] review_triggers: [public-api, behavior, layout, accessibility] verified_by: [ packages/core/src/PowerSearch/PowerSearch.test.tsx, packages/core/src/PowerSearch/PowerSearch.calendarSystems.test.tsx, packages/core/src/PowerSearch/PowerSearchEditPopover.test.tsx, packages/core/src/PowerSearch/PowerSearchDateZone.test.tsx, packages/core/src/PowerSearch/PowerSearchDateTime.test.tsx, packages/core/src/PowerSearch/formatFilterValue.test.ts, packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx, packages/core/src/PowerSearch/PowerSearch.ssr.test.tsx, packages/core/src/PowerSearch/tests/PowerSearchSheetTrigger.a11y.chromium.spec.ts, packages/core/src/Tokenizer/Tokenizer.test.tsx, packages/core/src/Typeahead/Typeahead.test.tsx, packages/core/src/Layer/useLayer.test.tsx, scripts/check-knowledge.mjs, ] modules: [] families: [family:overlay-dismissal] design_specs: [] architecture: [ architecture:component-style-authoring, architecture:interaction-modality, architecture:internationalization, architecture:layer-runtime, architecture:public-component-api, architecture:react-component-runtime, ] contributing: [] system_specs: [ spec:AST-013/FR12, spec:AST-017/FR3, spec:AST-017/FR27, spec:AST-020/FR15, spec:AST-055/FR3, spec:AST-056/FR3, spec:AST-085/FR1, spec:AST-085/FR2, spec:AST-085/FR4, spec:AST-086/FR3, spec:AST-086/FR4, spec:AST-086/FR14,

]

PowerSearch component contract

Intent

PowerSearch provides structured filtering through field, operator, and value selection. Its editor popover keeps the active editing task readable on both narrow and wide search bars. When the editor can follow the PowerSearch width, it stays aligned to that outer surface. When the 720 CSS px readability cap makes the editor narrower, it stays near the stable control that opened it instead of stretching across the page or depending on input modality.

PowerSearch also offers a touch presentation, the default on compact coarse-pointer screens (DEC-3): the whole field becomes one trigger showing display-only filter tokens, and the filter work moves into a stack of tall modal bottom sheets — Filters, Add filter, and a value step, each opened above the one that led to it and each dismissed back to it — that reads on a compact touch screen without a software keyboard covering the editor. With a fine pointer or on a screen that is not compact the field keeps the tokenizer and editor popover, and presentation="popover" keeps them on every device. DEC-3 states the flow's shape.

Where the shipped PowerSearch does not yet meet a requirement, the row carries a present-tense implementation gap note.

Compatibility and migration

  • Released default preserved: no for editor popovers anchored to a PowerSearch wider than 720 CSS px; other widths preserve their current sizing behavior.
  • Compatibility class (DEC-1, DEC-2): intentional default layout and placement change with no public API change. DEC-3 adds the stable presentation prop and its adaptive default, as the two DEC-3 bullets below state.
  • Controlled/uncontrolled behavior: unchanged.
  • Calendar: date values follow the provider's calendar. A provider locale with a -u-ca- keyword keeps Gregorian dates (spec:AST-111 DEC-2); set the provider's calendar to choose one.
  • Migration decisions: component:PowerSearch/DEC-1, component:PowerSearch/DEC-2, and, for the adaptive default, presentation="popover" (below).
  • Stable presentation (DEC-3): presentation is a new stable prop. The API change is additive: the prop is new and optional, and no existing prop, type, or export is removed or narrowed. The sheet presentation adds no theming target.
  • Default change (DEC-3): presentation defaults to adaptive, a change of the released popover default. With a fine pointer, on a screen that is not compact, on the server, and while hydrating, a field without presentation renders the tokenizer field and editor popover exactly as before (spec:AST-017/FR59). On a compact coarse-pointer screen it renders the trigger and the sheet flow (FR11–FR21): filters are added and edited through stacked sheets, not the typeahead and editor popover, a filter commits when its value step confirms, and menuWidth and tokenOverflowBehavior have no surface. The behavior changes only there, which is what adaptive is for. presentation="popover" restores the previous surface on every device — the restoring input spec:AST-017/DEC-23 and architecture:public-component-api/INV16 name. No codemod adds it, because adding it to every PowerSearch would opt every caller out of the new default. The stable prop and this default ship together in a patch as [feat]: that release tier is a product decision of the engineering owner, with the agreement of the owner of spec:AST-017 (DEC-3).
  • One stable fix alongside DEC-3: the result count is not announced on mount under StrictMode (FR19). It qualifies as a [fix] under spec:AST-017/FR5: it restores the documented contract (only a change after mount is spoken), no onChange value, prop, or rendered text changes, and no valid consumer must change. It ships as a [fix] patch release of its own.
  • A second stable fix: in the popover presentation, Backspace on an empty input removes no filter of a read-only field (FR22). It qualifies as a [fix] under spec:AST-017/FR5: it restores the documented isReadOnly contract, "Prevent adding, editing, or removing filters", no prop, onChange shape, or rendered text changes, and no valid consumer relies on a read-only field losing a filter. It ships as a [fix] patch release.
  • A third stable fix: in the popover presentation, Clear all keeps read-only filters, reports remove at the first removed index, and shows only while an editable filter exists, and Backspace keeps a read-only filter (FR23). It is a [fix] (DEC-4): a read-only filter is non-removable by contract, so "all filters" in Clear all means every removable filter, and a Clear all that removes a read-only filter is a defect. onChange documents index as the affected position, which the first removed index is. It ships as a [fix] patch release.
  • DEC-3 changes nothing in the popover presentation. Its Clear all is FR23's (DEC-4), which the sheet presentation's matches, and its dates are FR25's and FR26's (DEC-5, DEC-6), which the sheet presentation's match.
  • One stable fix (DEC-5): a date-only date_absolute value reads as one day on the token, in the accessible label and announcements, and in the editor, in both presentations (FR25). What a caller observes: with timezoneID set, the token, the label, the exported PowerSearchToken and the editor show the day in timezoneID, and a day picked in an editor stores as that zone's midnight; with timezoneID unset, the stored day stays UTC midnight and the token, the label and PowerSearchToken show the UTC day with no time of day. A value whose operator sets isDateOnly: false is untouched. Ships as [fix] (spec:AST-017 FR5, FR32): the shipped popover reads one date-only value in three zones (the token in the viewer's zone, the label in timezoneID with a time of day, the editor on the UTC day), so no consumer can validly rely on how a day is stored or read, and timezoneID is documented for date formatting, so honoring it restores that contract.
  • One stable fix (DEC-6): a date_absolute operator with isDateOnly: false is an instant with a time of day in both presentations, and in the popover presentation it edits in a date picker beside a time field and its token shows the time (FR26). What a caller observes, only for an operator that sets isDateOnly: false: the popover's editor gains a time field; a value saved from it carries the time entered, in timezoneID else the viewer's zone, where it carried UTC midnight of the picked day; the token shows the date and time in that zone, where it showed the device's day alone. A date_absolute with isDateOnly unset or true is unchanged. Ships as a [fix] (spec:AST-017 FR5, FR32): isDateOnly is documented as choosing a date picker without time only when true, and the shipped editor is the date picker for every value and stores midnight, so the option changes nothing and no consumer can validly rely on it; honoring it restores that contract.

Consumer migration instructions belong in consumer docs and release notes.

Ownership boundary

Owns

  • The readable width range of the filter-editor popover.
  • Identifying the stable control that opened the editor: the inner typeahead input for the add path, or the actual activated token/control for the edit path.
  • Choosing which outer PowerSearch edge a width-capped editor aligns to from that opening control's geometry.
  • Preserving the editing flow, content, and focus behavior while the editor's width and horizontal alignment change.
  • The touch sheet presentation: its trigger, the Filters, Add filter, and value sheets, which of them are open at once and which one dismissing reveals, which control receives focus after each step, the staging of a value until the step confirms it, the onChange metadata of each commit, Clear all's confirmation, and which PowerSearch props the sheets honor.

Does not own / non-goals

  • Main field/search-menu width — the existing menuWidth consumer surface is an exact pixel width forwarded to Tokenizer's main field menu, not a maximum and not an editor width control.
  • General anchor positioning, viewport collision handling, top-layer hosting, or dismissal — owned by architecture:layer-runtime.
  • Operator- and value-menu sizing inside the editor.
  • A public prop for overriding editor width or placement.
  • Pointer-coordinate placement, pointer-versus-keyboard branches, continuous pointer tracking, or an always-on geometry observer.
  • The compact-touch resolution rule behind adaptive. PowerSearch resolves adaptive with the same shared policy the selection controls use (component:Selector/FR4); it adds no query of its own.
  • The sheets' dialog, the one scrim of the stack of open modal sheets, gestures, snap behavior, keyboard accommodation, which sheet is on top and so takes a dismissal, how a covered sheet recedes, and how a dismissed top sheet reveals the sheet beneath it — owned by component:BottomSheet (its sheet stack) and family:overlay-dismissal.
  • The list-value sheet a string_list or entity_list value opens inside the value step — owned by component:Tokenizer (its DEC-3 sheet presentation).

Public concepts

One stable public concept is introduced: the presentation prop, with the values 'popover' | 'bottom-sheet' | 'adaptive' and adaptive the default, typed by the exported PowerSearchPresentation, the value set the selection controls and Tokenizer use (DEC-3).

The inclusive 400–720 CSS px range and conditional alignment of the editor popover are internal PowerSearch readability policy, not callsite options. Existing menuWidth remains an exact pixel width for only the main field/search menu of the popover presentation.

In the sheet presentation the props that describe the tokenizer's typeahead popover have no surface to act on: menuWidth and tokenOverflowBehavior. Passing either while a field resolves to bottom-sheet warns once in development and names presentation="popover"; neither is silently dropped. ref reaches the root element in both presentations, the element this record promises (architecture:public-component-api/INV8); xstyle, className, and style reach the field container in both. data-testid reaches the field's primary control: in the popover presentation the combobox input, where it is today, and in the sheet presentation the trigger button. handleRef.focusTypeahead() and blurTypeahead() act on the trigger. Every other prop keeps its meaning: label names the trigger and placeholder is its empty text and the content-search placeholder; isDisabled, disabledMessage, startIcon, endContent, resultCount, status, statusVariant, size, hasAutoFocus, onFocus, and onBlur apply to the trigger as FR11 states; hasClear governs Clear all (FR12); isReadOnly governs the rows, Add filter, and the value step (FR12, FR13, FR15); maxSearchResults and maxOperatorMenuItems apply to the Add filter and value steps (FR13, FR17); popoverSaveButtonLabel and components apply to the value step and the trigger (FR11, FR14); maxTokenLength applies to the trigger's tokens as to the popover's (FR11). timezoneID names the zone the sheet presentation reads and writes a date value in, on the trigger's tokens, the Filters rows, and the date editors: a date-only value is its day there, else the UTC day, and a value whose operator sets isDateOnly: false is its date and time there, else in the viewer's zone (FR11, FR12, FR17).

Behavioral and layout contract

Current requirements identify their basis and distinguish accepted contract from implementation status. The contract is authoritative; the behavior remains unshipped until its implementation and verification complete.

FR1–FR9 and FR22–FR24 govern the popover presentation — the tokenizer field and its editor popover, rendered when presentation resolves to popover. The editor popover does not render in the bottom-sheet presentation, whose surface FR10–FR21 govern. FR25 governs a date-only value in both, and FR26 a date-and-time value.

ID Invariant Basis Status
FR1 In the popover presentation, the filter-editor popover MUST have a rendered border-box width no greater than 720 CSS px. Owner direction; legibility issue demonstrated by wide PowerSearch adopters Accepted contract; implementation pending
FR2 In the popover presentation, before viewport collision handling, the editor's preferred width MUST be the outer PowerSearch width clamped to the inclusive 400–720 CSS px range. The 400 px floor MUST yield when the available viewport width cannot fit it. Existing 400 px editing floor plus component:PowerSearch/DEC-1 Accepted contract; implementation pending
FR3 In the popover presentation, when the 720 CSS px cap does not make the editor narrower than the outer PowerSearch, including when the 400 px floor is active, the editor MUST preserve current logical-start alignment to the outer PowerSearch. Compatibility requirement Accepted contract; implementation pending
FR4 In the popover presentation, when the 720 CSS px cap makes the editor narrower, PowerSearch MUST resolve one stable opening control for that open: the inner typeahead input for the add path, or the actual activated token/control for the edit path. Owner direction plus current composition analysis Accepted contract; implementation pending
FR5 In the popover presentation, for a capped editor, PowerSearch MUST compare the opening control's border-box distance from the outer PowerSearch's physical left and right edges, select the nearer outer edge, and align the editor to that edge. Equal distances MUST fall back to the outer PowerSearch's logical-start edge. The result MUST depend on control geometry, not pointer coordinates or pointer/keyboard modality. component:PowerSearch/DEC-2 Accepted contract; implementation pending
FR6 In the popover presentation, opening-control identity and the selected edge MUST be latched for the open lifetime. Reopening from a control on the opposite side MUST recalculate both; movement after open MUST NOT move the editor. Stable interaction and performance requirement Accepted contract; implementation pending
FR7 In the popover presentation, width and preferred-edge selection MUST still yield to the layer runtime's viewport collision handling so the editor remains horizontally visible within the runtime's existing safe area. architecture:layer-runtime Accepted contract; implementation pending
FR8 In the popover presentation, the width and alignment change MUST NOT alter editor content, field/operator/value state, vertical placement, focus movement, selection, dismissal, or screen-reader semantics. Compatibility and accessibility requirement Accepted contract; implementation pending
FR9 In the popover presentation, the opening-control descriptor owned by component:Tokenizer/DEC-1 and consumed by PowerSearch MUST remain package-internal. PowerSearch MUST NOT add a public width, maximum-width, input-ref, or positioning prop for this behavior. component:Tokenizer/DEC-1, architecture:public-component-api, and component:PowerSearch/DEC-1 Accepted contract; implementation pending
FR10 presentation selects the surface. adaptive, the value when presentation is omitted, resolves to bottom-sheet on compact coarse-pointer screens and to popover otherwise, through the same shared resolution the selection controls use (component:Selector/FR4); with a fine pointer or on a screen that is not compact it renders exactly the popover presentation. popover is the tokenizer field with its typeahead and editor popover on every device, unchanged except as FR19 (no mount announcement) states. bottom-sheet is the trigger and sheet flow of FR11–FR21 on every device. That resolution answers popover on the server and during the hydrating render, so an adaptive field server-renders as, and hydrates without a mismatch as, the popover presentation's tokenizer field; on a compact coarse-pointer screen the first client render after hydration swaps it to the trigger. Focus follows the resolution rule below: before any interaction nothing in the field has focus and nothing moves, except that with hasAutoFocus the server markup's autofocus has focused the combobox input, and the swap then moves focus to the trigger within the same visit — the caller is told of neither a blur nor a new focus. The two closed fields share the field's wrapper, border, and minimum height for the size, and show the same tokens, but their row counts may differ: the popover field's editable tokens each carry a 16 px remove control the trigger's display-only tokens do not (FR11), so the trigger's tokens can wrap into fewer rows (seven filters in a 326 px field take seven rows editable and six as display-only tokens), and the popover field also carries its inline combobox input after the tokens, which may take a row of its own — the swap then changes the field's height by those rows (none on the measured story at 390 px, one token row at 414 px). A resolution change while the flow is open takes effect after it closes and focus has returned to the trigger (the focus the close reports, FR11) — the presentation hold architecture:layer-runtime/INV14 assigns to the layer runtime; INV14 gap: the runtime provides that hold (Layer/presentationHold.ts), but the field still keeps its own, to be replaced by the runtime's; when the new presentation is popover, focus then moves to the tokenizer's combobox input as the same visit — no onBlur and no second onFocus reaches the caller. A resolution change while the flow is closed takes effect at once; when focus is anywhere inside the closed field — the trigger, the combobox input, a token or its remove control, the clear control, or an interactive endContent — and the focused element does not survive the switch, focus moves to the other presentation's primary control (the combobox input, or the trigger) as a continuation of the same visit — no onBlur and no onFocus reaches the caller for the hand-off; when the focused element survives, or focus is outside the field, focus stays where it is. When the switch to the sheet presentation happens while the popover presentation's editor popover is open, the popover and its focused control unmount with the tokenizer field, and focus moves to the trigger. Focus never lands on the page body. DEC-3; touch-flow evidence Current contract; verified by focused sheet tests and real-engine touch evidence.
FR11 In the sheet presentation the field's control is one trigger: a button with aria-haspopup="dialog" and aria-expanded, whose accessible name is the field label followed by the trigger's visible text — the placeholder while no filter exists, otherwise the text of the filter tokens — so the name contains what is visible and exposes the selected filters. The tokens are display-only — each is the token's static structure (component:Token/FR2): no remove control, no click of its own, no inner control inside the trigger button — and the tokens, the placeholder, and the empty space around them belong to the trigger: a tap on any of them opens the flow. Tokens wrap onto further lines; the trigger does not reserve a row of its own once a token exists. A placeholder longer than the trigger stays on one line and ends in an ellipsis inside the trigger: it never runs under the result count or past the field's border. The trigger's tokens are the popover presentation's tokens, the same component and the same words for a value, and a date_absolute value reads as the sheet's date editor shows it (FR17): a date-only value as its day in timezoneID, else the UTC day, and a value whose operator sets isDateOnly: false as its date and time in timezoneID, else the viewer's zone. A components[type].Token override renders on the trigger in place of PowerSearch's token, receiving the props the popover presentation hands it — config, filter, field, operator, maxLength, isDisabled — with onClick and onRemove undefined, as the popover hands them for a read-only filter: the trigger's tokens are display-only, and the override formats its own value. startIcon renders in the trigger's lane. The result count and endContent render in the field's end lane, outside the trigger button and after it: an interactive endContent keeps its own tab stop, its own taps, and its own accessible name, and a tap on it does not open the flow, so a caller's control is never nested inside the component's button and the end lane's text is not part of the trigger's name. size sizes the trigger field and its tokens as it sizes the tokenizer field; statusVariant places status.message as the popover presentation places it; hasAutoFocus focuses the trigger on mount. onFocus fires when focus enters the field from outside and onBlur when it leaves the field: opening the flow moves focus into a sheet, outside the field, so onBlur fires, and the close that returns focus to the trigger fires onFocus — as the popover presentation fires them around its editor. While disabled the trigger stays focusable with aria-disabled="true", never carries the native disabled attribute, does not open, and shows disabledMessage as the field does (spec:AST-085/FR1, FR2). When the component becomes disabled with the flow open, every open sheet of the flow closes and focus moves to the trigger, the destination this record names (spec:AST-085/FR4). DEC-3; touch-flow evidence; spec:AST-085; WCAG 2.5.3 Current contract; verified by focused sheet tests and real-engine touch evidence.
FR12 Opening the flow from a field with at least one filter, or from a read-only field, shows the Filters sheet, a tall modal sheet named "Filters". Its header — a heading and, while the field is interactive and at least one filter exists, an Add filter button at the medium size whose hit area is at least 44 px tall — and its footer — Done, which applies the sheet's draft (FR15b), and, while hasClear is set, the field is interactive, and at least one editable filter exists, Clear all — stay fixed while only the rows between them scroll, the scroll viewport reaching the sheet's edge so its scrollbar does too, with the rows' text on the header's inset. One row per filter shows "{field label} {operator label}" (one catalog message, so a locale can reorder it) and, in bold, the value as the trigger's token shows it — the same formatter, so the same words, with the token's width budget lifted: the row never truncates a single value and never collapses a list to its "{n} items" count — with the token's summaries resolved from the catalog (@astryx.powersearch.valueEditor.dateRange, itemsCount, filtersCount, ICU plurals): an integer or float value reads as the token's own text (String(value): 2.3456, 1e+21, 1e-7, and 0 for negative zero) wherever the locale writes numbers with the token's numerals — Latin digits and a . decimal mark — and elsewhere with the locale's digits and decimal mark, no grouping and no rounding; a string_list, enum_list, or entity_list value reads as all of its items joined by the locale's narrow conjunction list (Intl.ListFormat, {type: 'conjunction', style: 'narrow'} — "Open, Closed" in English, "高、中" in Simplified Chinese and Japanese, "A, B und C" in German); a date-only date_absolute value reads as its day in timezoneID, else the UTC day, with no time, and one whose operator sets isDateOnly: false as its date and time in timezoneID, else the viewer's zone, a date_range as "date range", a nested value as "{n} filters", and a date_relative value as the value step's choice row reads it ("3 days ago", FR20) when a choice matches the stored value, otherwise as stored. A row's label and value are one catalog message, "{label} {value}", the same message the removal announcement of AR6 uses, with the value segment bold. A filter the field can edit is a row button that opens the value step on it, with a trailing remove action — an icon button at the medium size named "Remove {field label} filter", its hit area at least 44 px square, that removes it from the draft (FR15b) without opening the step — except that a filter whose operator takes an empty value (a one-tap boolean filter) is a row whose tap removes it, with the same trailing remove action, since it has no value to edit; a read-only filter, or every filter while the field is read-only, is a plain row with no remove action, as the popover gives such a token no remove control. A nested filter's row is a row button like any other; its step edits the group with the popover presentation's built-in nested editor (FR14). An editable filter whose field or operator the config no longer has — which the trigger still shows as a token — lists as a row button reading the field's label when the config still has the field and the raw key for whatever is gone — "{field key} {operator key}" when both are, "{field label} {operator key}" when only the operator is — that opens the step's "This filter is no longer available" state (FR14), its trailing remove action still the removal path; it is a plain row while the filter, or the field, is read-only. With no filter in the draft the body is one empty state: a heading — "No filters applied" while the field has none, "No filters" while the draft is empty but the field's filters are still applied (Done replaces them) — a line of guidance, and, while the field is interactive, a centered primary Add filter action that is then the sheet's only Add filter (the header shows none), so the single thing to do is the only visible action; the footer stays, with Done alone, while the draft differs from the applied filters (an emptied draft still has removals to apply), and is absent otherwise. Done closes the flow. Clear all opens a confirmation above the sheet — a dialog titled "Clear all filters?" with "Clear filters" and "Keep filters" — and only confirming removes the editable filters from the draft, recorded as ('remove', <index of the first removed filter>) with kept, the read-only filters in their order, as the list (FR15b): read-only filters are the consumer's, not the person's, so Clear all leaves them in place, as the popover presentation's Clear all does (FR23); the Filters sheet stays open for further editing and focus returns to it (FR16). After the flow closes focus returns to the trigger. DEC-3; touch-flow evidence; the read-only filter contract (isReadOnly, FR22); DEC-4 Current contract; verified by focused sheet tests and real-engine touch evidence.
FR13 Add filter — from the Filters sheet's Add filter action, or directly when an interactive field with no filter opens — is a tall modal sheet named "Add filter" opened above the Filters sheet, which stays open beneath it (FR15a), so the sheet has no Back action: dismissing it — Escape, a scrim tap, a swipe — reveals Filters again, or closes the flow when Add filter was the entry point, in which case its fixed footer holds Done. Its header — the heading and, when one shows, the search field — stays fixed while the rows scroll. Without a content-search field it lists the visible fields grouped by group, each group a named list: the ungrouped fields first, under the heading "General", then each group under its name in order of first appearance, each a row button with the field's icon, a trailing chevron — or, for a field whose only operator takes an empty value, a trailing plus, since choosing it adds the filter at once (FR15) — and, once the field count reaches eight, a "Search filters" field above the list that matches labels and typeaheadAliases case-insensitively, caps a non-empty query's matches at maxSearchResults, and shows the empty state "No filters match your search" when nothing matches. With a contentSearchFieldKey whose default operator takes a string value it shows instead a "Search" searchbox using placeholder, with the same suggestions the popover presentation's typeahead offers listed inline as row buttons ("Search results"): fields, field-and-operator pairs, value matches, and a leading free-text item for the content field; Enter commits the first suggestion, ArrowDown and ArrowUp move between the search and the rows — arrow movement across independently focusable controls, recorded here as this record's exception to spec:AST-020/FR15, which adopts arrow keys for a single composite only: the searchbox-to-list continuity is what the popover presentation's combobox gives the same suggestions, and the rows stay in the Tab order as well — an IME-composing Enter does nothing, and a query with no suggestion shows the empty state "No results found" — the searchbox's aria-controls names the results list, or that message while nothing lists, so it always names an element; the field list's "No filters match your search" likewise shows only for a non-empty query that matches nothing, never for a config with no field. Each of the two is a compact empty state with a search icon, that title, and the description "Try a different search.", mounted only while the Add filter sheet is the open one. Neither search field takes focus when the sheet opens: the sheet opens with focus on its panel and the software keyboard stays down until the person taps the search; a direct vertical touch drag on the rows while a search field has focus blurs it, so the keyboard leaves and the rows can be read. A suggestion that carries a value adds the filter to the draft (FR15b), recorded as ('add', draft.length), announces Added {label} inside the Filters sheet (AR6), and shows Filters as FR15a states; any other suggestion or field row opens the value step with that field and operator, above Add filter. Every visible field lists, a field whose every operator is nested included: the value step edits every operator's value (FR14). DEC-3; touch-flow evidence; current typeahead source Current contract; verified by focused sheet tests and real-engine touch evidence.
FR14 The value step is a tall modal sheet that edits every operator's value, opened above the sheet that led to it — Filters for an edit, Add filter for a creation — which stays open beneath it (FR15a); its title is the dialog's name (AR5), and for a filter whose field or operator the config no longer has it reads as the Filters row does (FR12): the field's label when the config still has the field, the raw key for whatever is gone. Its header and footer stay fixed while the body scrolls. When the field offers more than one operator the body starts with an "Operator" radio group whose options read "{field label} {operator label}" and list the field's operators, with the operator the step opened with checked — the filter's operator while editing, and while creating the operator the suggestion named (FR13) or else the field's default operator, else its first; otherwise there is no group and the title is "{field label} {operator label}" naming that operator. When no operator label applies the title is the field label. The body below the group is the editor for the checked operator's value type: the sheet-native controls of FR17, or for a nested value the popover presentation's built-in nested editor — the sub-filter tree with its Add action, each sub-filter's field, operator, and value controls, and removal — rendered as the popover renders it, with one difference: the step's Operator group takes the place of the editor's root group-operator picker, which is not shown, and the tree root reads the checked operator's label; a sub-filter's controls are the popover editor's own, in their default presentation (a Selector's menu, the Tokenizer's inline field), not the sheet's choice rows (FR17) or Tokenizer sheet (FR21), which govern the step's top-level value only, because the nested editor renders its controls in their popover presentations; the tree is its own width container, so below 400 CSS px its rows wrap instead of overflowing the sheet, as they wrap in a narrow popover. A group is created and edited the same way in both presentations; switching the operator swaps the body. A value chosen in the body is staged, not committed: no onChange fires until the footer confirms it. Changing the operator keeps a staged value only when the new operator reads the same value type; an empty operator stages {type: 'empty'}. The body's sections sit on the sheet's surface when the editor is the body's only section; when the body has more than one section — the Operator group above the editor — each section is a muted container, so the grouping reads without a frame around a lone editor. The footer holds Cancel and the confirm action — popoverSaveButtonLabel when given, otherwise "Add filter" while creating and "Apply" while editing — disabled until the staged value is complete; the step has no Remove action: a filter is removed from its Filters row (FR12). When components[type].Editor is set for the checked operator's value type it replaces the body below the Operator group and the footer — the group stays outside it, so switching operators still swaps the body — receiving the props the popover presentation hands it, with the same meaning: the caller's config, the partial filter, mode, saveButtonLabel, isReadOnly, timezoneID (FR25), onSave, and onCancel, and nothing the popover does not pass; onSave(filter) commits it, onSave(null) removes the filter while editing and returns to Filters unchanged while creating. A controlled update that removes the field or operator being edited replaces the body with "This filter is no longer available", announced from its rendered element inside the sheet while the step is the open one (AR6), and keeps Cancel as the way out, the filter's trailing remove action on its Filters row being the removal path (FR12); when focus was on a control of the replaced body it moves to Cancel, so it never falls to the page body inside the open sheet (FR16). DEC-3; touch-flow evidence Current contract; verified by focused sheet tests and real-engine touch evidence.
FR15 Confirming a created filter adds it to the draft (FR15b), recorded as ('add', draft.length) with the list after it; choosing a field whose only operator takes an empty value adds that filter the same way from the Add filter row, with no value step. Tapping an editable Filters row opens the value step on that filter in edit mode; Apply writes the edited filter into the draft at its index, recorded as ('edit', index); the row's trailing remove action, or a tap on an empty-valued filter's row, removes it from the draft, recorded as ('remove', index), where index is the filter's position in the draft at that edit. The draft is the flow's own list: a controlled parent's change to filters while the flow is open does not reach the open sheets; Done replays the draft's edits onto the field's latest filters (FR15b), and a dismissal leaves the change in place, so it shows on the next open. Every edit shows the Filters sheet as FR15a states. While the field is read-only, or disabled, no edit happens. DEC-3; DEC-7; touch-flow evidence Current contract; verified by focused sheet tests.
FR15a The steps stack: each step opens above the sheet that led to it, which stays open — receded and blocked as a covered sheet of the stack (component:BottomSheet FR5, FR6) — so the stack is Filters alone; Filters under Add filter; Filters under the value step for an edit; Filters under Add filter under the value step for a creation; or, when Add filter was the entry point, Add filter alone and then Add filter under the value step. No sheet of the flow carries a Back action: a dismissal — Escape, a scrim tap, a swipe, a platform close request — reaches only the top sheet (component:BottomSheet FR7), closes it, and reveals the sheet beneath, which takes focus back as FR16 states; dismissing the bottom sheet of the stack closes the flow. Cancel on the value step is that dismissal. A commit closes the step that made it: an edit's commit reveals Filters beneath the value step; a creation's commit, from the value step or from an Add filter row or suggestion that commits directly, closes Add filter, and the value step above it, together and shows Filters, so the person sees the filter just added: Filters is revealed when it is open beneath them; after a direct entry it opens in the same update that closes them — BottomSheet's same-update replace (component:BottomSheet FR10) when Add filter alone closes, and the stack's ordinary closes and open (component:BottomSheet FR5–FR9) when the value step closes with it. A creating Editor override's onSave(null) (FR14) shows Filters the same way. The flow therefore has one direction forward (open a step above) and one back (close the top step): no dismissal replaces a step, and Filters opens as other sheets close only when a creation ends after a direct entry. DEC-3; component:BottomSheet FR5–FR9 Current contract; verified by focused sheet tests and real-engine touch evidence.
FR15b One open flow edits one draft of the filter list, which starts as filters when the flow opens. Every add, edit and removal (FR15) and Clear all (FR23, DEC-4) changes the draft, and the rows, the empty state and Clear all follow it; onChange is not called. Done applies the draft: it replays the recorded edits, in order, onto the field's latest filters — an add appends its filter; an edit replaces the first filter matching the one it edited (by field, operator, value and read-only flag); a removal drops the filters it removed — and calls onChange once per edit with the list after it and that edit's changeType and the index in that list, the calls a popover session makes, so a filter the parent added while the flow was open survives; an edit or removal whose target the parent removed meanwhile is skipped; then the flow closes; a draft that equals the filters at open (same filters, in order, by field, operator, value and read-only flag, whatever the order of a value's keys) reports nothing and closes, and so does Done on a field that became read-only or disabled while the flow was open (the draft is dropped), as component:Tokenizer FR26 states for its sheet. Done is in the Filters footer and in Add filter's footer when Add filter is the entry point. The field's result count follows the applied filters, so it changes on Done, not on an edit. DEC-7 Current contract; verified by focused sheet tests.
FR15c A dismissal of the flow's bottom sheet — Escape, a scrim tap, a swipe, a platform close request on Filters, or on Add filter when it is the entry point — closes the flow directly while the draft equals the filters at open. While the draft differs, it opens the discard confirmation inside the sheet (SheetConfirmation, the shape component:Tokenizer FR27 states): title "Discard changes?", description "Your changes to the filters haven't been applied.", the destructive Discard changes first in reading order and the safe Keep editing focused first; its scrim and Escape take the safe action. Keep editing closes the confirmation, keeps the draft, and returns focus to the sheet's first control — the Filters header's Add filter, else the sheet's panel; Discard changes closes the flow with no onChange, and the next open starts from the applied filters. A dismissal of a step above the bottom sheet reveals the step beneath (FR15a) and asks nothing: the draft is still open. DEC-7; component:Tokenizer FR27 Current contract; verified by focused sheet tests.
FR16 Focus follows the step: after a commit from the value step while creating, the value step and Add filter close and focus lands on the Filters header's Add filter, ready for the next filter; after a content-search suggestion or an empty-valued field row commits a filter directly, that filter's row; after Apply or Cancel from editing, the edited filter's row; after a row's trailing remove action, or a caller's Editor override's onSave(null) while editing, which closes the value step, the trailing remove action of the nearest remaining row that has one (the following one on a tie) — a plain row, a read-only filter's, has none and is passed over — so a run of removals needs no re-aiming, else Add filter when no such row remains; after Cancel from creation, Add filter is revealed with focus on the field row that opened the step, or on the content search when a suggestion opened it — and when a controlled update has removed that field, or the content-search field itself, the Add filter sheet's first control: its search field when one shows, else its first field row; after Add filter is dismissed, the Filters header's Add filter, or the empty state's; after a caller's Editor override calls onSave(null) while creating, the same (the flow returns to Filters unchanged, FR14); after a confirmed Clear all, the Filters sheet's first remaining control — a kept read-only filter's row has none, so Add filter — with the sheet still open; after Keep filters, Escape, or a scrim tap dismisses the confirmation, Clear all (component:Dialog AR2); and, as one rule for the Filters and Add filter sheets, when a controlled update unmounts the control that holds focus — a filter's row or its remove action, a dropped field's row, Clear all gone with the last editable filter — the nearest remaining row that is a button, counted among the button rows by the removed one's index (the following one, else the last) — a plain row (a read-only filter, or every filter while the field is read-only) is passed over — else the sheet's first control (the Add filter sheet's search field, Add filter in the Filters header or empty state), else the sheet's panel, so focus never lands on the page body inside the open sheet; when a controlled update replaces the value step's body with the unavailable state while focus was on one of its controls, Cancel (FR14); after the flow closes, the trigger. A sheet that opens takes focus on its panel, not on a control, except where this row names one; the Add filter sheet's search fields never take it on open (FR13). DEC-3; touch-flow evidence Current contract; verified by focused sheet tests and real-engine touch evidence.
FR17 The value step edits every value type with the same editor the popover presentation uses (nested through its built-in nested editor, FR14), with four sheet-native differences: enum, enum_list, and date_relative render as the system's lists instead of a dropdown that would stack a second layer on the sheet — a component:RadioList named by the field label for enum and date_relative, and a component:CheckboxList named by the field label for enum_list, each at its standard density, with its own spacing, keyboard behavior, and checked state; integer and float stage every parseable keystroke, so the confirm action enables while the person is still typing, and unstage when the field is cleared or stops parsing, so it disables again over an empty field; a string_list or entity_list value edits through the Tokenizer's own sheet presentation (component:Tokenizer/FR16–FR24), its trigger showing the staged tokens in the step and its sheet titled with the field label; and a date_absolute value with isDateOnly unset or true, and a date_range value, edit through an inline Calendar on the sheet's surface — no popover opens from a sheet — reading a stored instant as its day in timezoneID, else the UTC day, and writing a picked day as that day's midnight in the same zone, the day the trigger's token and the Filters row show (FR11, FR12); a date_absolute value with isDateOnly: false edits through a date-and-time input, sized for touch, that reads and writes the wall-clock time in timezoneID, else the viewer's zone. maxOperatorMenuItems caps the string and entity suggestions as in the popover presentation. DEC-3; touch-flow evidence; current value editors Current contract; verified by focused sheet tests and real-engine touch evidence. Implementation gap: a date-only date_absolute value edits through the popover presentation's date field in its sheet presentation — which reads and writes the day in timezoneID, else the UTC day, as this row states — not through an inline Calendar; a value whose operator sets isDateOnly: false edits through the popover presentation's date picker and time field in their sheet presentation, which read and write the wall-clock time this row names, not through one date-and-time input.
FR18 Every list in the sheets derives synchronously from the config — the field list, its search, the content-search suggestions, and the choice rows — so no sheet shows an empty state before results arrive: "No filters match your search" and "No results found" render only for a non-empty query whose synchronous result set is empty, and only while their sheet is the open one; a sheet that is open beneath another, or closed with its body retained, renders and announces no empty-result or unavailable message (AR6). The value typeaheads and tokenizers inside the value step own their own pending states. DEC-3; architecture:react-component-runtime/INV1 Current contract; verified by focused sheet tests and real-engine touch evidence.
FR19 The result count renders at the end of the field in both presentations and is announced only when it changes after mount; the first render announces nothing, including under StrictMode's effect replay. The announcement takes the route spec:AST-086/FR14 names for where the field is at that moment: inside the open sheet's dialog while a sheet of the flow is open (AR6), otherwise inside the nearest open native modal that holds the field (a Dialog, a modal Drawer), and the shared polite channel only when no modal does — never a channel the record names itself. Current popover behavior; architecture:react-component-runtime/INV3 Current contract; verified by focused sheet tests and real-engine touch evidence.
FR20 Every string the sheets introduce comes from the @astryx.powersearch.* catalog, reusing the existing editor keys where their meaning fits (Cancel, Apply, Operator, Value, Values, Entities, the placeholders, the result count). Content the popover presentation already renders keeps its source — field, operator, and value text from the config and its formatters — except that every label the sheets render for a generated choice comes from the catalog as one ICU message with a plural: the relative-date choice rows (@astryx.powersearch.sheet.relative{Days,Weeks,Months}{Ago,FromNow}, the same choices and, in English, the same words as the popover's editor lists) and the value summaries of FR12. DEC-3; catalog contract Current contract; verified by focused sheet tests and real-engine touch evidence.
FR21 A string_list or entity_list value inside the value step opens the Tokenizer's sheet above the value step, one more sheet of the same stack (FR15a). Escape, a scrim tap, and a swipe dismiss only that topmost sheet; closing it returns focus to its trigger inside the value step; the value step keeps its staged state. DEC-3; family:overlay-dismissal; component:Tokenizer/FR18 Current contract; verified by focused sheet tests and real-engine touch evidence.
FR22 In the popover presentation, a read-only field (isReadOnly) MUST NOT remove a filter: it shows no Clear all, no token has a remove control, and Backspace on an empty input removes nothing. The isReadOnly prop docs: "Prevent adding, editing, or removing filters." Current contract
FR23 In the popover presentation, Clear all MUST remove every editable filter and keep every read-only filter: it commits onChange(<the read-only filters>, 'remove', <index of the first removed filter>) and announces "Editable filters removed" while a read-only filter remains, otherwise "All filters removed". The clear control MUST render only while hasClear is set, the field is neither read-only nor disabled, and at least one editable filter exists. Backspace on an empty input MUST NOT remove a read-only filter; its token has no remove control. DEC-4; a read-only filter's token has no remove control (current source) Current contract
FR24 In the popover presentation, a built-in filter token (no components Token override) that opens its editor is named by its visible text (field, operator and value); aria-haspopup="dialog", aria-expanded is true while its editor is open, and the editor is a dialog named by the token's visible text. Its remove button is named by the remove word and the same visible text. The token's full text is one catalog message; a locale whose full token text is not the label, a space, then the value shows that text in one weight, and the accessible name and the visible text stay the same. A filter whose field the config lacks shows the field key. spec:AST-020 FR1; WCAG 2.5.3 and 4.1.2; component:Token/FR10 Current contract.
FR25 In both presentations a date_absolute value whose operator has isDateOnly unset or true, and each ABSOLUTE part of a date_range value, is a calendar day: the day its unixSeconds falls on in timezoneID when the prop is set, else the UTC day. The built-in token's text, the filter's accessible label and every announcement that names the value, the Filters row of the sheet presentation, and the date editor of either presentation all read that one day, with no time of day, so one value is never two days in one field; a components[type].Token override formats its own value (FR11) and receives timezoneID in its props, as the exported PowerSearchToken (the default token) does and reads, and a components[type].Editor override and PowerSearchFilterEditor receive timezoneID in their props so they can read the same day. A day picked in an editor is stored as that day's midnight in the same zone — timezoneID's midnight, else UTC midnight — and the editor reopens on the day it stored, so an edit that keeps the day keeps the instant. Nothing about a value is rewritten by rendering or reopening: a value stored before timezoneID was given reads as its day in the zone now given. A date_range whose part is NOW or RELATIVE reads that part resolved to an instant first, then as its day. A value whose operator sets isDateOnly: false is an instant, not a calendar day: FR26 governs it. DEC-5; timezoneID prop contract; component:DateInput (a calendar-day control) Current contract.
FR26 A date_absolute value whose operator has isDateOnly: false is an instant with a time of day. In both presentations its token shows its date and time and the sheet's Filters row shows the same, and its editor reads the stored instant's wall-clock time and stores the wall-clock time entered as the instant it names, both in timezoneID when the prop is set, else the viewer's zone — the zone the viewer reads a clock in — so the time typed is the time shown. In the popover presentation that editor is a date picker beside a time field; the sheet presentation's control is FR17's. A components[type].Editor override and PowerSearchFilterEditor receive timezoneID in their props so they can read the same time. A date_absolute whose operator has isDateOnly unset or true keeps its date-only picker and shows no time (FR25). DEC-6; OperatorValue.isDateOnly contract; component:DateInput; component:TimeInput Current contract.

Allowed variation

  • AV1 — Viewport clamping. The layer runtime may shift or shrink the editor when the preferred width or edge alignment would cross its viewport safe area.
  • AV2 — Writing direction. Implementations may express the selected physical edge through logical alignment values as long as the rendered edge is correct in both LTR and RTL.
  • AV3 — Submenus. Operator and value menus may retain their own width and collision behavior; this contract applies only to the filter-editor popover.
  • AV4 — Internal representation. The shared opening-control descriptor may use refs, elements, or an equivalent package-internal value. Its observable geometry, lifetime, and precedence must satisfy FR3–FR9.
  • AV5 — Sheet flow composition. The sheet presentation hosts its steps as standalone BottomSheets driven by one step state, each step's isOpen true while it is open or beneath an open step (FR15a), so the stack is component:BottomSheet's own (FR5–FR9) and Filters opens as other sheets close only where FR15a names it; it may compose List, RadioList, TextInput, Calendar, Button, Heading, EmptyState and Text in any internal structure, and may load the whole surface on demand, provided FR10–FR21, AR4–AR6, and PR5 hold and the composition stays within architecture:component-style-authoring/INV7: one presentation mounted per open layer, no content mounted twice, and, while one sheet of the flow is open, the open flow under a coarse pointer within the popover presentation's open editor under a fine pointer; each sheet open beneath the top one is the owner exception DEC-3 records with its counts, beyond the open-layer allowance (spec:AST-017/FR60, DEC-29). The Tokenizer's list-value sheet opens as one more sheet of the same stack above the step.
  • AV6 — Sheet layout. Sheet padding, the field-list search threshold's visual placement, row density, and the footer's button widths may vary; the 44 px minimum hit area of every sheet action (AR5) and the edge-to-edge Filters and field rows on the body's inset are the constants.

Representative states

State Required invariant Allowed variation
Outer PowerSearch narrower than 400 px Editor prefers 400 px and logical-start alignment to the outer surface, but yields to available viewport width. Layer runtime may shift or shrink it to remain visible.
Outer PowerSearch from 400 through 720 px Editor matches the outer surface and remains logical-start aligned. Existing vertical collision behavior may flip.
Wider than 720 px; add from inner input near left Editor is 720 px wide and prefers the outer surface's physical left edge. Viewport collision handling may shift it.
Wider than 720 px; add from inner input near right Editor is 720 px wide and prefers the outer surface's physical right edge. Viewport collision handling may shift it.
Wider than 720 px; edit a token/control near either end Editor is 720 px wide and prefers the outer edge nearest that activated control. Custom token markup may vary; identity remains exact.
Wider than 720 px; opening control is equidistant Editor is 720 px wide and uses the outer surface's logical-start edge. Direction determines the physical start edge.
Pointer, keyboard, or programmatic activation The same stable opening control produces the same preferred edge regardless of activation modality. Focus behavior remains unchanged.
Reopen from a control on the opposite side Opening-control identity and preferred edge are recalculated for the new open, then remain latched until close. Later layout changes do not move the open editor.
Sheet presentation, closed The trigger shows the tokens or placeholder, aria-expanded="false"; its name is the label plus the visible text. Token wrapping and placeholder text may vary.
Sheet presentation, Filters One tall modal sheet named "Filters": fixed header with Add filter, rows with trailing remove actions scrolling between it and the fixed footer's Done, which applies the draft, and Clear all; with no filter, the centered Add filter is the only action, Done staying while the draft has removals to apply. Row count and the empty state's guidance text may vary.
Sheet presentation, Add filter Above Filters: fixed header with an unfocused search when one shows, grouped field rows (the ungrouped ones under "General") or the content search's inline suggestions, and a compact empty state when a search matches nothing; no Back — a dismissal reveals Filters. Field search appears from eight fields.
Sheet presentation, value step Above the sheet that led to it: title, operator radios when needed, the staged editor on the sheet surface (or in muted sections with the operator group), Cancel and the confirm action; no Remove. Editor per value type follows FR17.
Sheet presentation, Clear all A confirmation dialog above Filters; confirming removes the editable filters, keeps read-only ones, and leaves Filters open with focus on it. The confirmation's wording may vary.
Sheet presentation, list value The Tokenizer's sheet opens above the step, titled with the field label, as the top sheet of the stack under its one scrim; Escape closes it alone. One backdrop per stack, dismissal at the top sheet (component:BottomSheet FR6, FR7).
Sheet presentation, disabled while open The flow closes; focus returns to the trigger; the trigger stays focusable. Exit motion may vary.
Sheet presentation, adaptive resolution The surface follows the shared compact-touch query while closed; an open flow keeps its presentation until it closes. The query is shared, not PowerSearch-owned.

Transformation and precedence order

  • ORD1 — Width. Resolve outer PowerSearch width → apply the 400 px readable floor → apply the 720 px readable ceiling → yield to available viewport width.
  • ORD2 — Opening control. Resolve the stable inner input or activated token/control for the current open.
  • ORD3 — Horizontal alignment. If the ceiling did not narrow the editor, use outer logical start. Otherwise compare the opening control's physical edge gaps inside the outer PowerSearch → choose the nearer outer edge → use outer logical start on a tie.
  • ORD4 — Collision. Let the layer runtime apply viewport collision handling after preferred width and edge selection.

Performance and resources

  • PR1 — One batched open-time read. PowerSearch MUST read the outer PowerSearch and opening-control geometry together once in response to open intent, never during React render.
  • PR2 — Hidden commit before show. Placement state MUST commit while the editor popover is hidden, and the popover MUST show on the next animation frame. Real Chromium verification MUST prove there is no first-frame flash at a default or stale position.
  • PR3 — Latch, do not track. The resolved opening control and preferred edge MUST remain latched until close. The implementation MUST NOT install continuous pointer tracking or an always-on geometry observer.
  • PR4 — CSS owns responsive geometry. CSS anchor sizing and the layer runtime MUST own the 400–720 width policy and collision behavior. JavaScript may select the per-open anchor/alignment descriptor but MUST NOT continuously calculate popup width or collision offsets.
  • PR5 — The sheet surface is opt-in cost. A field in the popover presentation does not load the sheet flow's code; the flow's chunk loads on demand while a field resolves to bottom-sheet, so the first press does not wait for the network, and renders nothing on the server or during the hydrating render. At rest the field renders none of the flow: its three dialogs, rows, search fields, editors and the Clear all confirmation are mounted only from the press until the exit has completed and focus is back on the trigger (architecture:component-style-authoring/INV7); the trigger, its end lane (the result count, endContent) and the field chrome of FR11 render as the field does.

Accessibility contract

  • AR1 — Modality equivalence. Pointer, keyboard, and programmatic activation of the same control MUST resolve the same preferred edge. Keyboard users retain the current field selection, editor focus, traversal, apply/cancel, Escape, and focus-return behavior.
  • AR2 — Semantic stability. Width and placement MUST NOT change the current combobox, listbox, option, menu, or editor semantics and accessible names.
  • AR3 — Visible content. Viewport clamping MUST keep all editor controls horizontally reachable without requiring page-level horizontal scrolling.
  • AR4 — Trigger semantics. In the sheet presentation the trigger is a button named by the field label plus its visible text, with aria-haspopup="dialog" and aria-expanded; status.message and disabledMessage describe it; a disabled trigger uses aria-disabled and keeps its focus order; an interactive endContent is a sibling of the trigger with its own name and tab stop, never a descendant of it.
  • AR5 — Sheet semantics. Each step is a modal dialog named by its title ("Filters", "Add filter", the value step's title), the open one on top of the sheets it was opened from, which are inert beneath it (component:BottomSheet FR6); the Filters rows, field rows, and suggestion rows are buttons named by their visible text, and a Filters row's trailing remove action is a button named "Remove {field label} filter" with that name as its tooltip; the Clear all confirmation is a modal alertdialog named "Clear all filters?" whose actions read "Clear filters" and "Keep filters", with Keep filters focused when it opens, so a stray Enter keeps the filters; a value choice is a radio in a component:RadioList (single choice) or a checkbox in a component:CheckboxList (enum_list), named by the field label (FR17); the operator step is a component:RadioList named "Operator"; the content search is a searchbox named "Search" controlling the suggestion list; the field-list search is a textbox named "Search filters"; every sheet action except the choice lists has a hit area at least 44 px tall, and the trailing remove action and the header's Add filter keep their medium visible size, their hit area meeting that minimum. The choice lists — the operator and value RadioList and CheckboxList — follow the standard list density and its shared touch band instead, as they do everywhere else (owner decision, cixzhang, 2026-11-07).
  • AR6 — Announcements and focus. While a sheet is open, every announcement the flow makes — Added {label} for a committed suggestion or an empty-valued field row, Removed {label} for a filter removed by its row's trailing remove action, by a tap on an empty-valued filter's row, or by a caller's Editor override that calls onSave(null) while editing (FR14) (the label is the Filters row's text — the same "{label} {value}" catalog message the row renders, its summaries and relative-date values resolved from the catalog as FR12 states; the popover presentation's removal is the Tokenizer's tokenRemoved with the filter's formatFilterValue label, "{field}: {operator} {value}" — not the token's text: 1500 with units: 'ms' shows "1500" on the token and is announced "1,500 ms" — and the sheet's is the Filters row's text, so the two readings differ wherever FR12's row and formatFilterValue differ), the result count of FR19, the Add filter sheet's empty-result messages ("No results found", "No filters match your search"), each a compact EmptyState (FR13), and the value step's "This filter is no longer available" (FR14), plain rendered text, each read from its rendered element and spoken once per query that matches nothing, or once per opened filter, by the shared own-content module (architecture:react-component-runtime/INV10), and only while the message's sheet is the open one — a sheet beneath another, or one closed with its body retained, speaks nothing (FR18) — so nothing speaks them a second time, and reopening the same stale filter speaks its message again — is delivered by a persistent polite live region inside the open sheet: an element that stays mounted while its text changes and never mounts already holding the text to announce (spec:AST-086/FR3), that delivers the content added inside it at its own polite urgency (spec:AST-086/FR4), and that is the route an owner inside an open native modal takes (spec:AST-086/FR14), so the announcement reaches assistive technology behind the native modal dialog where a channel outside it does not. Clear all announces "Editable filters removed" while a read-only filter remains, otherwise "All filters removed", inside the Filters sheet once its confirmation dialog has closed — not before, since the confirmation is the top modal until then and hides the sheet's region. The result count follows the applied filters, which change on Done (FR15b), so no count changes with an edit inside the flow; after Done, while the flow is closed, the changed count takes the route spec:AST-086/FR14 names for the field's position (FR19). Focus moves as FR16 states and returns to the trigger after the flow closes.

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
Search field and tokens Continue presenting the structured query and its current interaction states. Current source and public docs Prominent FR8
Main field/search menu Retain its exact menuWidth surface and current selection behavior; it does not inherit the editor's 720 px cap. Current source and public docs Prominent Ownership boundary, FR9
Filter-editor popover Stay within the readable 400–720 px range before viewport clamping. component:PowerSearch/DEC-1 Prominent FR1–FR3, FR7
Width-capped editor Prefer the outer edge nearest the stable opening control, independent of activation modality. component:PowerSearch/DEC-2 Prominent FR4–FR8
Keyboard-opened editor Use the same control-geometry rule and preserve current focus behavior. Accessibility contract Prominent FR5, FR8, AR1
Sheet trigger The field's control surface in the sheet presentation: display-only tokens or the placeholder; endContent beside it. PowerSearch and Token source Prominent FR11, AR4
Filters sheet Fixed header with Add filter, divided edge-to-edge rows with bold values and trailing remove actions, fixed Done and Clear all; one centered Add filter when empty. PowerSearch source; component:List Prominent FR12, FR16
Add filter sheet Fixed header with an unfocused search when one shows; grouped field rows or the content search with inline suggestion rows; no Back. PowerSearch source; component:List Prominent FR13, FR15a
Value step Title, operator radios, the staged editor on the sheet surface or in muted sections, Cancel and the confirm action. PowerSearch source; current editors Prominent FR14, FR15, FR17
Clear all confirmation A dialog above Filters; confirming keeps read-only filters and leaves Filters open. PowerSearch source; component:Dialog Prominent FR12, AR5

DEC-1 and DEC-2 change editor geometry only. The sheet presentation (DEC-3) adds no theming target or theme state; the root element keeps the existing power-search target in both presentations.

Family and system relationships

  • architecture:layer-runtime owns anchor wiring, collision fallbacks, viewport safety, top-layer hosting, and visibility reconciliation. PowerSearch supplies its per-open preferred width source, stable opening control, and edge choice.
  • architecture:interaction-modality continues to own shared modality state, but the editor placement result intentionally does not branch on modality.
  • architecture:public-component-api owns the public-surface bar. Width and placement remain internal because they are component usability invariants rather than adopter policy. architecture:public-component-api/INV16 governs the touch presentation DEC-3 adds: the fine-pointer surface — the tokenizer field and its editor popover, popover — stays reachable on every device through the presentation value; every touch mode is reachable by callers, as bottom-sheet on every device and adaptive on compact coarse-pointer screens; and the caller's explicit value wins over any default. DEC-3's default is adaptive: INV16 makes touch the default "where it serves touch users", and the sheet flow is the surface that serves them on a compact coarse-pointer screen.
  • family:overlay-dismissal continues to own shared Escape and platform-close ordering; DEC-1 and DEC-2 change no dismissal behavior, and DEC-3's sheets take the family's dismissal paths through component:BottomSheet, as the "Does not own" bullet on the sheets' dialog, scrim, gestures, snap behavior, keyboard accommodation, and dismissal paths states.
  • component:Tokenizer/DEC-1 is current authority for the package-internal stable outer-field/opening-control descriptor and its safe fallback semantics. PowerSearch consumes that identity only after resolving an editor narrower than the outer field; Tokenizer contributes no PowerSearch width policy.
  • component:Tokenizer/DEC-3 owns the sheet presentation a string_list or entity_list value opens inside the value step; PowerSearch passes the field label as that sheet's title and claims nothing of its rows, search, or Clear all.
  • component:BottomSheet owns the sheets' dialogs, the stack's one scrim, gestures, keyboard accommodation, how a covered step recedes and how a dismissed step reveals the one beneath (FR15a); the top sheet of that stack — the value step, Add filter, or the Tokenizer's list-value sheet above the value step — is the one Escape, a scrim tap, a swipe, and a platform close request reach (component:BottomSheet FR7), with family:overlay-dismissal owning the Escape and platform-close ordering.
  • architecture:public-component-api/INV8 governs where ref lands (the root element this record promises, in both presentations); data-testid reaches the primary control of each presentation. PowerSearch is a composition that consumes family:input-fields members and is not itself a member of that family.
  • spec:AST-086/FR3, FR4, and FR14 govern the flow's own polite live region: a persistent container inside the open sheet that delivers the content added to it, the route an owner rendered inside an open native modal takes because the shared page-body channel is not exposed there.
  • spec:AST-017/FR3 governs the default change.

spec:AST-013 FR12 exception — calendars that need Temporal

  • Capability: date values that PowerSearch (its tokens in both presentations, and the sheet's Filters rows and removal announcement) and PowerSearchToken write in the provider's calendar (spec:AST-111 FR18), for calendars other than gregory, iso8601, buddhist, roc, and japanese, which need the runtime's Temporal.
  • Reduction: where Temporal is missing or does not support the calendar, as in Safari on macOS and iOS, such a calendar resolves to gregory before the first render and warns once in development, on the server and in the browser, naming temporal-polyfill/full/global (spec:AST-111 FR5). Date values then show Gregorian dates; filter values stay Unix seconds. An application that loads a Temporal polyfill gets the full calendar. A server without Temporal renders Gregorian text, which a browser with Temporal does not match, so a server-rendered application loads Temporal on the server too.
  • Preserved obligations: spec:AST-013 FR7 and FR8, and FR9 whenever the server and the browser resolve the calendar the same way, outside the chinese and dangi case of spec:AST-111 FR19. The filter flow and the filter values do not change; nothing throws.
  • Evidence: PowerSearch.calendarSystems.test.tsx with a Temporal polyfill and with Temporal removed; PowerSearchBottomSheet.test.tsx ("writes the trigger token and the Filters row in the provider calendar"). Evidence gap: no real-browser run, and no server render and hydration test, under a calendar that needs Temporal.
  • Owner: nynexman4464.
  • Review condition: Safari ships Temporal.

Current dependency

component:Tokenizer is current authority on main and satisfies PowerSearch's opening-control prerequisite. Its DEC-1 owns the package-internal descriptor, modality-neutral edge choice, hidden placement commit, one-read open preparation, and collision-last ordering that this record consumes. Both current contracts still mark implementation and focused real-Chromium verification as pending.

Required visual evidence stories

  • PowerSearch MUST provide dedicated wide-field evidence above 720 CSS px with the editor already open in the captured state. The matrix MUST cover opening controls near the outer start edge, outer end edge, and equidistant; keyboard activation; LTR and RTL; narrow-viewport collision; and the first painted frame with no default-position flash.
  • Separate Tokenizer evidence stories MUST cover its unchanged full-width menu, wrapped-token and unfocusedLayer states, RTL, and viewport collision. Those stories verify the package-internal opening-control prerequisite; they MUST NOT inherit PowerSearch's 400–720 editor width policy.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1–FR3, FR7 PowerSearch unit tests plus real-Chromium geometry assertions 399/400, 720/721, wide outer surface, narrow viewport, LTR/RTL, collision Removing either clamp, capping the main menu, or allowing viewport overflow fails. audit:PowerSearch/layout
FR4–FR6, FR9 Opening-path tests plus real-Chromium geometry assertions Add from inner input; edit actual left/right/equidistant token/control; pointer/keyboard; reopen opposite side Using pointer coordinates, modality, wrapper-only identity, stale identity, or public props fails. audit:PowerSearch/interaction
PR1–PR4 Instrumented unit tests plus first-frame real-Chromium capture Open, close, reopen opposite side; hidden placement commit; first painted frame Render-time reads, repeated reads, observers, pointer tracking, or a default-position flash fails. audit:PowerSearch/performance
FR8, AR1–AR3 Existing PowerSearch/editor suites plus focused browser checks Pointer and keyboard edit, apply, cancel, Escape, light dismiss, focus return, selection, semantics Focus, semantics, selection, dismissal, or reachability changes fail. audit:PowerSearch/accessibility
FR15b, FR15c Focused sheet tests: no onChange before Done, Done's replay in order, an unchanged draft's silent close, clean and changed-draft dismissal with Keep editing and Discard changes, read-only filters kept through Clear all and Done, and the popover presentation's at-once reports
FR22 PowerSearch and Tokenizer unit tests A read-only field with a filter: no Clear all, no token remove control, Backspace on the empty input A read-only field removes a filter through Backspace, Clear all, or a token control. audit:PowerSearch/interaction
FR23 PowerSearch and Tokenizer unit tests Clear all with a read-only filter before two editable ones; every filter read-only; Backspace with a read-only last filter; the words with and without a read-only filter left A read-only filter is removed, Clear all reports an index other than the first removed one, Clear all shows with no editable filter, or its words say every filter went while one remains. audit:PowerSearch/interaction
FR24 PowerSearchTokenNaming.test.tsx; real-Chromium accessibility tree of a popover token Popover token with a value, read-only token, editor open and closed, a verb-last remove word A token named without its value, a missing or stale aria-expanded, an unnamed or non-dialog editor, or a remove name that loses its locale's word order fails. audit:PowerSearch/accessibility
FR25 PowerSearch date-zone tests under four host zones (UTC, Los Angeles, Tokyo, Honolulu) with timezoneID set to each zone and unset: token text, the removal announcement that carries the accessible label, the editor's opening day, the stored instant after a pick, a round trip that moves the day and back, a components Editor override and PowerSearchFilterEditor receiving the zone, range parts read and written, and an isDateOnly: false value left to FR26; plus the formatter's unit tests a Los Angeles evening instant with timezoneID set and unset, a pick across the US daylight-time change, a date_range of two instants The token and the editor show different days for one value, a re-picked day moves the instant, or a day shows a time audit:PowerSearch/interaction
FR26 PowerSearch date-and-time tests under four host zones (UTC, Los Angeles, Tokyo, Honolulu) with timezoneID set and unset: the token's date and time, the editor's opening date and time, the stored instant after a time is typed, a components Editor override and PowerSearchFilterEditor receiving the zone, the editor on a line of its own, and a date-only operator kept on the date picker; plus the sheet's value step opening on the time in timezoneID a Los Angeles evening instant with isDateOnly: false and timezoneID Los Angeles, Tokyo, empty and unset; the same instant with isDateOnly: true The token shows no time, the editor has no time field or opens on another time than the token shows, a typed time stores a different instant than it names, or a date-only operator gains a time field audit:PowerSearch/interaction
FR10–FR21, AR4–AR6, PR5 Focused PowerSearch sheet tests with the compact-touch query stubbed both ways, plus real-engine touch evidence, and a real-engine width sweep of a long placeholder in both writing directions the default resolving both ways, popover kept on a compact coarse-pointer screen, forced sheet, adaptive both ways (the default's server markup the same as popover's, server markup and hydration as the popover field on a coarse-pointer client, then the trigger, no recoverable error, focus on the body; with hasAutoFocus, the autofocused input's focus ending on the trigger with no onBlur or onFocus to the caller), trigger name, Filters/Add filter/value steps, each value type, list value through the Tokenizer sheet, Clear all, read-only, disabled while open, focus after each step, focus after an adaptive switch from the trigger, the input, a removed control, an open editor popover, and from outside the field, a field inside an open Dialog announcing the count, Clear all, and in-sheet messages inside that Dialog and never on the page body, StrictMode result count, in-sheet live region while a sheet is open (added, removed, count, empty results), Clear all announced only after the dialog's exit, row, token and Removed text sharing one formatter, a date-only value as its day in timezoneID, else the UTC day, and a date-and-time value in timezoneID, else the viewer's zone, on all three (UTC, Tokyo, Honolulu, unset), summaries and relative-date labels and values from the catalog, the row and Removed through one reorderable message, an unmatched relative-date value as stored, a filter the config no longer knows listed and removable, a cleared number unstaged, a stale read-only filter as a plain row, a removal next to a nested row focusing that row's remove action, a list value joined by the locale's narrow conjunction list in English, Simplified Chinese, Japanese, and German, an empty-result message spoken once per query from its rendered element, a controlled update that removes the edited field moving focus from the replaced body to Cancel and announcing the unavailable state in the sheet while the step is open and never from a step beneath another or retained closed, Apply and Cancel after a controlled update removed the edited filter focusing the nearest row, else Add filter, a row's trailing remove action focusing the next row's remove action, a one-tap empty-valued filter added from its field row and removed from its row, Clear all behind its confirmation keeping read-only filters and leaving Filters open, a dismissed step revealing the step beneath with focus restored to it, Add filter opening with its search unfocused and a touch drag on the rows blurring a focused search, a stale filter's step titled as its row reads (raw keys for what is gone, the field's label when the field remains), Cancel from creation after the opening field was removed focusing the Add filter sheet's first control, a removed focused Filters row, a removed Clear all, and a dropped focused field row each handing focus to the nearest remaining row or the sheet's first control, element counts at rest and with each of the Filters, Add filter and value sheets open, and with the Tokenizer's list-value sheet stacked above the value step, under fine and coarse pointers, nothing of the flow in the DOM at rest before a press and after the exit, a nested filter edited and created through the built-in nested editor (its sub-filter rows wrapping inside a 390 and a 414 px sheet; its root operator picker absent on a mixed field, the Operator group in its place), a nested-only field and its suggestion offered, a suggestion's operator checked over the field's default, the Operator group outside a caller's Editor override on a mixed field, a count changed during the exit spoken with Clear all's message as one catalog message after the close, a single choice as a RadioList with one radio group whose arrow keys move and check, a multiple choice as a CheckboxList whose rows Space toggles, right-to-left layout with the row chevrons mirrored in RTL (design:bidirectionality/DR4) A field with a fine pointer or on a screen that is not compact changes by default beyond what FR19 states, presentation="popover" presents the sheet flow, a value commits before the step confirms, Clear all removes a read-only filter, the trigger carries native disabled, focus lands elsewhere, an announcement reaches a channel outside the modal that holds the field at that moment, or the popover bundle carries the sheets. audit:PowerSearch/sheet
Record structure scripts/check-knowledge.mjs Component-contract schema and current-authority dependency Missing or invalid metadata and sections fail repository validation. audit:PowerSearch/knowledge

Current-source Chromium evidence establishes the geometry gap, not implementation completion:

  • At an 800 px PowerSearch with many filters, the active inner input's logical text start was 570.8 px inward from the outer edge while the editor remained aligned to the outer 800 px surface.
  • In a 400 px Tokenizer with two selected tokens, the active inner input's logical text start was 242.3 px inward while the suggestion surface remained aligned to the outer wrapper. The same magnitude reproduced in LTR and RTL.

Completion still requires real-Chromium proof at the 400 and 720 boundaries, a narrow viewport, opening controls near both edges and equidistant, reopen from the opposite side, pointer and keyboard activation, LTR and RTL, collision handling, first-frame stability, and unchanged focus, selection, and dismissal.

Decision log

DEC-1 — PowerSearch owns one internal readable editor width

Reference: component:PowerSearch/DEC-1 Decider: cixzhang, 2026-08-31

A very wide editor makes a small field/operator/value task harder to scan, while a callsite width prop would turn readability policy into permanent public API and produce inconsistent products. PowerSearch therefore owns one internal preferred range: outer PowerSearch width clamped to 400–720 CSS px, then constrained by the viewport. This rule does not change Tokenizer's main-menu sizing or PowerSearch's existing exact-pixel menuWidth surface.

Rejected: a public editor width/max-width prop, applying the 720 cap to Tokenizer's main menu, or treating menuWidth as an editor width.

DEC-2 — Only a capped editor follows the stable opening control

Reference: component:PowerSearch/DEC-2 Decider: cixzhang, 2026-08-31

A full-width or floor-expanded editor remains aligned to the outer PowerSearch. Only when the 720 px ceiling makes the editor narrower does PowerSearch use the stable opening control to choose the nearer outer edge. The add path uses the inner typeahead input; the edit path uses the actual activated token/control. The control's geometry produces the same result for pointer, keyboard, and programmatic activation, and the result is latched until close.

Rejected: pointer-coordinate placement, pointer-versus-keyboard branches, always using one edge, anchoring every width to the inner control, continuous tracking, render-time geometry reads, and showing before hidden placement state commits.

DEC-3 — The touch sheet is a stable presentation, and adaptive is the default

Reference: component:PowerSearch/DEC-3 Decider: imdreamrunner, 2026-11-03

PowerSearch offers its touch surface through a stable presentation prop, with the values popover, bottom-sheet, and adaptive that the selection controls and Tokenizer use, and adaptive is the default: the sheet flow on a compact coarse-pointer screen, where the editor popover competes with the software keyboard, and the tokenizer field with its editor popover everywhere else. A caller's explicit value wins on every device, and popover keeps the tokenizer field and editor popover (architecture:public-component-api INV16). adaptive resolves through the shared compact coarse-pointer policy, so a PowerSearch, a Tokenizer, and a Selector on the same page switch together. The stable prop and the adaptive default ship together in a patch release: the API change is additive, the behavior changes only on compact coarse-pointer screens, and presentation="popover" keeps the previous behavior everywhere. That release tier is the engineering owner's product decision, made with the agreement of cixzhang, an owner of spec:AST-017. Rejected: keeping popover as the default, because a phone then gets the editor popover under the software keyboard unless the caller opts in (component:Selector DEC-1 rejects the same default for the same reason).

The sheet surface: the whole field is one trigger with display-only tokens; a Filters sheet lists the filters as rows with trailing remove actions, under a fixed header with Add filter and over a fixed footer with Done and Clear all, and is one centered Add filter when empty; Add filter opens above Filters and lists the fields, or carries the content search with inline suggestions, its search unfocused until tapped; the value step opens above the sheet that led to it, stages operator → value with the editor on the sheet's surface, and confirms from its footer. Every step stays open beneath the next, so a dismissal reveals the previous step and no sheet needs a Back action. Closed vocabularies are rows; list values edit through the Tokenizer's sheet presentation titled with the field label; a nested value uses the popover presentation's built-in nested editor; a date-only value edits on an inline Calendar in timezoneID, else UTC, and a value with a time of day on a date-and-time control in timezoneID, else the viewer's zone; every other value type uses the editor the popover presentation uses. Clear all asks for confirmation, removes the filters the person can edit, keeps read-only ones, and leaves Filters open. The flow edits a draft that Done applies, and a dismissal with a changed draft asks before discarding it (FR15b, FR15c, DEC-7). Seven details the flow fixes: a date-only value with no timezoneID is its UTC day; a field whose every operator is nested lists, edited through the built-in nested editor; every string comes from the catalog (FR20); the empty results of Add filter's searches carry Core's titles (FR13); Clear all says "All filters removed" when no read-only filter remains (AR6); a one-tap empty filter added from its field row is announced Added {label} (AR6); and the flow mounts nothing until a press (PR5). Rejected: steps that replace one another in place with Back actions to return (an earlier draft of the flow): a dismissal then closed the whole flow from any step, and the person re-entered Filters by its entry point rather than finding it where they left it. Rejected: Remove in the value step's footer (a second removal path, reached only by opening the step; the row's trailing action removes in one tap). Rejected: focusing Add filter's search on open (the software keyboard then covers the rows the person came to read). Rejected: a separate touch component chosen by the caller (two components, two draft states, an import swap per breakpoint).

Owner exception to architecture:component-style-authoring/INV7's layer budget: the flow keeps every step open beneath the next (FR15a), so with the value step open two or three sheets are mounted at once — each a covered sheet of the stack (component:BottomSheet FR6: receded, blocked, its state kept so the person finds it where they left it) — and with the Tokenizer's list-value sheet open above a creation's value step, four; the Clear all confirmation open above Filters covers it the same way; each covered sheet is a whole dialog, more than the 5-element open-layer allowance (spec:AST-017/FR60, DEC-29). Existing elements cannot do the job: a replaced step would have to be rebuilt on return and its staged state and scroll position recreated, and a dismissal could not reveal it. The counts are document.body.querySelectorAll('*').length at 390×844. The bound AV5 measures the flow against is the popover presentation's open editor on the Adaptive (default) story under a fine pointer: 334, and 166 at rest. The sheet flow, on that story under a coarse pointer, each state read once it has settled (every open dialog is that state's own and two readings one second apart agree), reads 123 at rest, 313 with Filters open, 314 with Add filter above Filters, 332 with a choice-row value step above both, 349 with a list-value step above both and 420 with the Tokenizer's list-value sheet above that step, 373 with an edit step above Filters, and 333 with the Clear all confirmation above Filters. From the first press until the exit completes, it keeps the closed Add filter sheet and value step mounted, which is most of the step from 123 to 313; the confirmation mounts only while it is open.

Owner exception to INV7's surface budget, which asks that a pointer-specific presentation be a change of attributes and styles on the same elements: under adaptive the closed field swaps its elements by pointer — the tokenizer field with its combobox input and token remove controls for one trigger button holding display-only tokens (FR11) — because the two surfaces differ in role (a combobox editing inline against a button opening a modal flow), and a combobox cannot be restyled into a dialog trigger without lying about its role. The swap renders fewer elements, not more (123 against 166 at rest), and happens only on resolution changes (FR10); the Tokenizer's own adaptive trigger records the same exception.

The sheet presentation's Clear all keeps read-only filters, which are the consumer's, and records a remove at the first removed index in the draft, which Done reports, as the popover presentation's Clear all reports it at once (FR23, DEC-4, FR15b). Its date editors, tokens and rows read and write a date-only date_absolute value, and each absolute part of a date_range, as one day in one zone, its day in timezoneID when the prop is set, else the UTC day; a value whose operator sets isDateOnly: false is an instant with a time of day, read and written in timezoneID, else the viewer's zone (FR11, FR12, FR17). The popover presentation reads both the same way (FR25, FR26; DEC-5, DEC-6).

DEC-4 — Clear all keeps read-only filters

Reference: component:PowerSearch/DEC-4 Decider: imdreamrunner, 2026-11-02

A read-only filter is non-removable by contract: it has no remove control, and no key or bulk action removes it either. "All filters" in Clear all therefore means every removable filter, and a Clear all that removes a read-only filter is a defect. Clear all removes the editable filters, keeps the read-only ones, and reports remove at the first removed index — at once in the popover presentation, on Done in the sheet presentation (FR15b). Backspace on an empty input removes nothing when the last filter is read-only (FR23). Rejected: a Clear all that also removes read-only filters (a filter the person cannot remove alone would go with the rest).

DEC-5 — A date-only value is one day in one zone

Reference: component:PowerSearch/DEC-5 Decider: imdreamrunner, 2026-11-02

A date_absolute value whose operator has isDateOnly unset or true, and each absolute part of a date_range, is a calendar day. timezoneID, when set, is the one zone the day is read and written in: the token's text, the accessible label, the announcements, the sheet's rows, and the editors of both presentations show the day the instant falls on there, and a day picked in an editor stores as that zone's midnight. With no timezoneID the day is the UTC day, read and written, so a value a caller stored as UTC midnight keeps its day and its instant whatever the device's zone. Rejected: keeping the token on the device's zone (a UTC-midnight day reads as the day before everywhere west of UTC, and the editor then opens on a different day than the token shows, so re-picking the token's day moves the value a day earlier each time). Rejected: the viewer's zone as the fallback for a date-only value (a stored UTC-midnight day would then be shown and, on edit, rewritten as a different instant on every device west of UTC; the UTC fallback changes no stored value). Rejected: a separate prop for the editor's zone (one field, one zone; timezoneID already names it).

DEC-6 — isDateOnly: false is an instant with a time of day

Reference: component:PowerSearch/DEC-6 Decider: imdreamrunner, 2026-11-02

A date_absolute operator that sets isDateOnly: false names a value with a time of day. Its popover editor is a date picker beside a time field (the sheet's control is FR17's), and its token shows the date and the time, both reading and writing the instant in timezoneID when the prop is set, else the viewer's zone: an instant has no day of its own to keep stable, and the person reads it where they are; a field that needs every viewer to see one wall-clock time passes timezoneID. An operator with isDateOnly unset or true keeps the date picker. Rejected: a date-only editor for isDateOnly: false (the option's one documented meaning is a value with a time, and a date-only editor stored midnight and showed no time, so the option changed nothing). Rejected: UTC as the fallback zone for an instant (a wall-clock time typed by the person would then name a different hour than the one they read on their clock). Rejected: a time on the token for every date_absolute value (a calendar day has no time to show).

DEC-7 — The sheet edits a draft that Done applies, and asks before discarding a changed one

Reference: component:PowerSearch/DEC-7 Decider: imdreamrunner, 2026-11-04, with the designer's confirmation

The sheet presentation holds a draft of the filter list from open: adding, editing and removing a filter, and Clear all, change the draft, and the field's onChange is called only when Done applies it (FR15b). A dismissal with a changed draft asks before discarding it, through the confirmation Tokenizer's sheet uses (FR15c). The save model is the one component:Tokenizer DEC-4 states for its sheet, so the two sheets a PowerSearch flow stacks — the filter list and a list value's Tokenizer — commit the same way: with an explicit action, never under the finger. Done reports the draft through the public onChange(filters, changeType, index) by replaying the recorded edits in order onto the field's latest filters, each call carrying the list after that edit: a consumer receives the calls a popover session makes, with real change types and indexes; one that keeps only the last call's list ends on the applied list, since every call carries the whole list; and a filter the parent added while the flow was open — a read-only one above all — survives, since the replay starts from the list that holds it. An edit or removal whose target the parent removed meanwhile is skipped, with nothing reported for it. Rejected: one call for the whole draft (the public changeType has no value for a batch, and inventing one is an API change; a consumer that switches on the type would receive a type it does not know). Rejected: replaying only the net edits (a consumer that logs or reacts per change would see an edit history that never happened). Rejected: applying the draft on every dismissal (a swipe or a scrim tap would then commit by accident, which is what the confirmation exists to prevent). Rejected: showing a controlled parent's filters change inside the open flow (the draft is the flow's own list; the change takes part on Done and shows on the next open). Rejected: replaying the draft's own lists as recorded (a filter the parent added while the flow was open would be replaced on Done).

Open questions

  • Known gap, pre-existing in the popover presentation, against architecture:internationalization/INV1a: its token writes the list, date-range, and nested summaries ("{n} items", "date range", "{n} filters") as English literals, joins the items of a list value with a literal ", " where FR12's rows use the locale's list format, and shows a relative-date value as the stored key (3d_ago), and its relative-date editor writes the choice labels ("3 days ago") as English literals. formatFilterValue resolves its summaries from the catalog but differs from the token in four places: it says "{n} entities" for an entity list where the token says "{n} items"; it formats an integer or float through the locale's number format and appends the operator's units where the token prints the raw number; it collapses a list to a count when the joined text exceeds the width budget, where the token compares the labels' total length, so the two collapse at different lengths; and it cuts a single value at a different length and with a different mark — the token's budget is maxTokenLength less the field and operator label lengths, at least 10, with 3 characters of slack and "..." (three periods), where formatFilterValue cuts at maxTokenLength with "…" (the ellipsis character) — (both show a relative-date value as stored). The sheet presentation resolves all of these from the catalog, or the locale's formats, on its own surfaces (FR12, FR20) and shows the popover token's text on the trigger, except a date, which FR11 reads in timezoneID or its fallback zone; changing the token's and the editor's own text is a separate stable change for the owner.
  • Known gap against family:input-fields/FR10, opened by DEC-3: the sheet presentation's trigger composes Field for the box the tokenizer field has, so PowerSearch is a component that composes Field, which FR10 binds even outside the family's membership, and this record departs from FR10 in two places. Item 1: ref, id, data-*, aria-*, hidden, inert, dir, and DOM event handlers go to the primary semantic control under FR10, while this record keeps ref on the root in both presentations (the INV8 promise above), routes only data-testid to the primary control, and forwards no id, aria-*, other data-*, hidden, inert, dir, or handler at all — the stable component destructures its props with no rest. Items 2–4: PowerSearch's stable props carry root xstyle, className, and style, which both presentations apply to the field box — FR10's container* target — so the styling lands where FR10 puts it, but the props type still accepts the root names and offers no container* or control* parts. Moving ref or removing the root names is a stable API change for existing callers (spec:AST-017/FR5), so the conversion is a separate stable decision with its own migration, not part of DEC-3; the implementation of DEC-3 adds PowerSearch to the family coverage check's pending list, where it stays until that decision or an amendment of the family record resolves which rule governs a composition that consumes member behavior.
  • The editor geometry contract (DEC-1, DEC-2) is accepted and current; its implementation and focused real-Chromium verification remain pending.

Content boundary

This file does not duplicate consumer prop tables, configuration examples, operator/value editor internals, current audit results, implementation steps, shared layer positioning and dismissal rules, BottomSheet's dialog and gesture contract, or the Tokenizer sheet's row, search, and Clear all behavior. It links to their owners.