Skip to content

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

TypeScript

fix(PowerSearch): a date range edits on an inline calendar in the sheet (#10618)

Cindy Zhangfece34c7d06e
diff --git a/.changeset/powersearch-sheet-date-range.md b/.changeset/powersearch-sheet-date-range.md
new file mode 100644
index 0000000000..e93f089214
--- /dev/null
+++ b/.changeset/powersearch-sheet-date-range.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] In PowerSearch's phone sheet, a date range is now picked on a calendar inside the sheet, instead of a calendar popover opening over it. The desktop editor popover is unchanged.
+
+@cixzhang
diff --git a/docs/specs/components/PowerSearch/PowerSearch.spec.md b/docs/specs/components/PowerSearch/PowerSearch.spec.md
index d2f6aa3c24..0ce73cfe23 100644
--- a/docs/specs/components/PowerSearch/PowerSearch.spec.md
+++ b/docs/specs/components/PowerSearch/PowerSearch.spec.md
@@ -248,37 +248,37 @@ 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 and a `date_range` value edit through the popover presentation's date fields in their sheet presentation — which read and write 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. |
+| 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
diff --git a/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx b/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx
index e646417097..16906ce8f0 100644
--- a/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx
+++ b/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx
@@ -4755,7 +4755,7 @@ describe('PowerSearch sheet value types (FR17)', () => {
);
});
- it('date_range: the range input is rendered with the stored range', () => {
+ it('date_range: an inline calendar on the sheet edits the range, and no popover opens (FR17)', () => {
const rangeFilter: PowerSearchFilter = {
field: 'window',
operator: 'between',
@@ -4767,14 +4767,44 @@ describe('PowerSearch sheet value types (FR17)', () => {
},
},
};
- setupValues({filters: [rangeFilter], timezoneID: 'UTC'});
+ const {onChange} = setupValues({filters: [rangeFilter], timezoneID: 'UTC'});
openEditFlow(/^Window is between/);
- // The popover presentation's editor labels the range with the catalog's
- // lowercase noun; the sheet reuses that editor.
- const range = within(sheet()).getByRole('button', {
- name: /date range.*Mar 1, 2024/i,
- });
- expect(range).toHaveAttribute('aria-expanded', 'false');
+ const step = sheet();
+ // No field that opens a popover: the calendar is on the sheet itself.
+ expect(
+ within(step).queryByRole('button', {name: /date range/i}),
+ ).toBeNull();
+ const grid = within(step).getByRole('grid', {name: /March 2024/});
+ expect(
+ within(grid)
+ .getAllByRole('gridcell', {selected: true})
+ .map(cell => cell.textContent),
+ ).toContain('1');
+ const day = (n: number) =>
+ within(grid).getByRole('button', {
+ name: new RegExp(`March\\s+${n},\\s+2024`),
+ });
+ fireEvent.click(day(10));
+ fireEvent.click(day(12));
+ apply();
+ done();
+ expect(onChange).toHaveBeenCalledWith(
+ [
+ {
+ field: 'window',
+ operator: 'between',
+ value: {
+ type: 'date_range',
+ value: {
+ start: {type: 'ABSOLUTE', unixSeconds: 1710028800}, // 2024-03-10Z
+ end: {type: 'ABSOLUTE', unixSeconds: 1710201600}, // 2024-03-12Z
+ },
+ },
+ },
+ ],
+ expect.anything(),
+ 0,
+ );
});
it("entity_list: the Tokenizer's sheet picks entities from the search source (FR21)", async () => {
diff --git a/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx b/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx
index 97f58a35ca..a408d2f946 100644
--- a/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx
+++ b/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx
@@ -53,6 +53,7 @@ import {
import type {ISODateTimeString} from '../DateTimeInput/DateTimeInput';
import {HStack} from '../HStack/HStack';
import {DateRangeInput, type DateRange} from '../DateRangeInput';
+import {Calendar} from '../Calendar/Calendar';
import {resolveDateTimeRangePart} from './resolveDateTimeRangePart';
import {TimeInput} from '../TimeInput';
import {Selector} from '../Selector';
@@ -806,6 +807,16 @@ function DateRangeEditor({
}
}, []);
+ // A sheet opens no popover over itself.
+ if (presentation === 'bottom-sheet') {
+ return (
+ // A disabled editor takes no input: the calendar has no disabled state.
+ <div inert={isDisabled === true}>
+ <Calendar mode="range" value={currentValue} onChange={handleChange} />
+ </div>
+ );
+ }
+
return (
<div onKeyDown={handleKeyDown}>
<DateRangeInput
@@ -815,9 +826,6 @@ function DateRangeEditor({
value={currentValue}
onChange={handleChange}
hasClear={false}
- // A phone-wide sheet fits one month; the popover keeps the default.
- numberOfMonths={presentation === 'bottom-sheet' ? 1 : undefined}
- width={presentation === 'bottom-sheet' ? '100%' : undefined}
/>
</div>
);