Skip to content

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

TypeScript

fix(core): PowerSearch gives `isDateOnly: false` the time of day it names (#9702)

Xinzi Zhouc8f08f967f9b
diff --git a/.changeset/powersearch-date-zone.md b/.changeset/powersearch-date-zone.md
index 6302a4c94e..79af60c5cc 100644
--- a/.changeset/powersearch-date-zone.md
+++ b/.changeset/powersearch-date-zone.md
@@ -2,6 +2,6 @@
'@astryxdesign/core': patch
---
-[fix] PowerSearch: a date-only `date_absolute` value (`isDateOnly` unset or `true`) reads as one day in one zone — on the token, in the accessible label and announcements, and in the edit popover's date editor — and the editor writes the day picked. Before, the token showed the device's day, the label showed a date and a time in `timezoneID`, and the editor read and wrote the UTC day without receiving `timezoneID`, so west of UTC a filter opened on the day after the one its token showed and re-picking that day moved the value a day earlier. Now a date-only value (`isDateOnly` unset or true) is a calendar day in `timezoneID`, else the UTC day: the token shows that day; the accessible label and `formatFilterValue` show that day with no time of day (UTC midnight March 9 in Los Angeles read "Mar 8, 2024, 4:00 PM" and reads "Mar 9, 2024"); the editor opens on it; and a picked day stores as that zone's midnight — with `timezoneID` set this is a different instant from the UTC midnight stored before, so a caller that derived the day from the instant's UTC date reads it in `timezoneID` instead, and a value the old editor stored as UTC midnight under a `timezoneID` west of UTC now reads the day before in the editor on every device, and on the token for a viewer at or east of UTC (UTC midnight March 9 under `America/Los_Angeles` reads March 8 everywhere; a Los Angeles viewer's token and the label already did), the day it would have stored — re-save such values, or read them as UTC days; with `timezoneID` unset no stored value changes. Each absolute `date_range` part is read and written as a calendar day the same way in the range editor. An operator with `isDateOnly: false` is untouched: its token, label and editor read as before. In the sheet presentation the rows and the value step read and write the same day. The exported `PowerSearchToken` and a `components` Token override receive `timezoneID` (a new optional prop on `PowerSearchTokenProps`), and `PowerSearchToken` shows that day too, where it showed the label's date and time. A `[fix]`, not a breaking change: the released popover read one value in three zones, so nothing valid relied on how a day was stored, and `timezoneID` is documented for date formatting. A `components` Editor override and `PowerSearchFilterEditor` receive `timezoneID`.
+[fix] PowerSearch: a date-only `date_absolute` value (`isDateOnly` unset or `true`) reads as one day in one zone — on the token, in the accessible label and announcements, and in the edit popover's date editor — and the editor writes the day picked. Before, the token showed the device's day, the label showed a date and a time in `timezoneID`, and the editor read and wrote the UTC day without receiving `timezoneID`, so west of UTC a filter opened on the day after the one its token showed and re-picking that day moved the value a day earlier. Now a date-only value (`isDateOnly` unset or true) is a calendar day in `timezoneID`, else the UTC day: the token shows that day; the accessible label and `formatFilterValue` show that day with no time of day (UTC midnight March 9 in Los Angeles read "Mar 8, 2024, 4:00 PM" and reads "Mar 9, 2024"); the editor opens on it; and a picked day stores as that zone's midnight — with `timezoneID` set this is a different instant from the UTC midnight stored before, so a caller that derived the day from the instant's UTC date reads it in `timezoneID` instead, and a value the old editor stored as UTC midnight under a `timezoneID` west of UTC now reads the day before in the editor on every device, and on the token for a viewer at or east of UTC (UTC midnight March 9 under `America/Los_Angeles` reads March 8 everywhere; a Los Angeles viewer's token and the label already did), the day it would have stored — re-save such values, or read them as UTC days; with `timezoneID` unset no stored value changes. Each absolute `date_range` part is read and written as a calendar day the same way in the range editor. An operator with `isDateOnly: false` keeps its label; its token and editor change as its own entry describes. In the sheet presentation the rows and the value step read and write the same day. The exported `PowerSearchToken` and a `components` Token override receive `timezoneID` (a new optional prop on `PowerSearchTokenProps`), and `PowerSearchToken` shows that day too, where it showed the label's date and time. A `[fix]`, not a breaking change: the released popover read one value in three zones, so nothing valid relied on how a day was stored, and `timezoneID` is documented for date formatting. A `components` Editor override and `PowerSearchFilterEditor` receive `timezoneID`.
@imdreamrunner
diff --git a/.changeset/powersearch-is-date-only-time.md b/.changeset/powersearch-is-date-only-time.md
new file mode 100644
index 0000000000..cde1231b5c
--- /dev/null
+++ b/.changeset/powersearch-is-date-only-time.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] PowerSearch: a `date_absolute` operator with `isDateOnly: false` gets the time of day the option names. The edit popover shows a time field beside the date picker, the token shows the date and the time, and both read and write the instant in `timezoneID` when it is set, else the viewer's zone, so the time typed is the time shown. Before, `isDateOnly` was read nowhere: every `date_absolute` edited in the date picker and stored UTC midnight of the picked day. Only operators that set `isDateOnly: false` change: a value saved from their editor now carries the time entered where it carried midnight, and their token shows the time; `isDateOnly` unset or `true` is unchanged, and stored values are read as the instants they are.
+
+@imdreamrunner
diff --git a/docs/specs/components/PowerSearch/PowerSearch.spec.md b/docs/specs/components/PowerSearch/PowerSearch.spec.md
index 8c448cf72a..a5e71996b7 100644
--- a/docs/specs/components/PowerSearch/PowerSearch.spec.md
+++ b/docs/specs/components/PowerSearch/PowerSearch.spec.md
@@ -15,6 +15,7 @@ verified_by:
packages/core/src/PowerSearch/PowerSearch.test.tsx,
packages/core/src/PowerSearch/PowerSearchEditPopover.test.tsx,
packages/core/src/PowerSearch/PowerSearchDateZone.test.tsx,
+ packages/core/src/PowerSearch/PowerSearchDateTime.test.tsx,
packages/core/src/PowerSearch/formatFilterValue.test.ts,
packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx,
packages/core/src/PowerSearch/PowerSearch.ssr.test.tsx,
@@ -122,12 +123,8 @@ present-tense implementation gap note.
filter is a defect. `onChange` documents `index` as the affected position,
which the first removed index is. It ships as a `[fix]` patch release.
- DEC-3 changes nothing in the `popover` presentation. Its Clear all is FR23's
- (DEC-4), which the sheet presentation's matches, and its date-only days are
- FR25's (DEC-5), which the sheet presentation's match. Where its handling of
- a value whose operator sets `isDateOnly: false` still differs from the sheet
- presentation's (the known gap in Open questions), bringing it to the sheet's
- behavior changes what the stable presentation reports through `onChange`, so
- it ships as its own stable change, classified under `spec:AST-017/FR5`.
+ (DEC-4), which the sheet presentation's matches, and its dates are FR25's
+ and FR26's (DEC-5, DEC-6), which the sheet presentation's match.
- One stable fix (DEC-5): a date-only
`date_absolute` value reads as one day on the token, in the accessible
label and announcements, and in the editor, in both presentations (FR25).
@@ -142,6 +139,20 @@ present-tense implementation gap note.
with a time of day, the editor on the UTC day), so no consumer can validly
rely on how a day is stored or read, and `timezoneID` is documented for
date formatting, so honoring it restores that contract.
+- One stable fix (DEC-6): a
+ `date_absolute` operator with `isDateOnly: false` is an instant with a time
+ of day in both presentations, and in the popover presentation it edits in
+ a date picker beside a time field and its token shows the time (FR26). What
+ a caller observes, only for an operator that sets `isDateOnly: false`: the
+ popover's editor gains a time field; a value saved from
+ it carries the time entered, in `timezoneID` else the viewer's zone, where
+ it carried UTC midnight of the picked day; the token shows the date and
+ time in that zone, where it showed the device's day alone. A
+ `date_absolute` with `isDateOnly` unset or `true` is unchanged. Ships as a
+ `[fix]` (`spec:AST-017` FR5, FR32): `isDateOnly` is documented as choosing a
+ date picker without time only when true, and the shipped editor is the date
+ picker for every value and stores midnight, so the option changes nothing
+ and no consumer can validly rely on it; honoring it restores that contract.
Consumer migration instructions belong in consumer docs and release notes.
@@ -229,36 +240,37 @@ until its implementation and verification complete.
FR1–FR9 and FR22–FR24 govern the `popover` presentation — the tokenizer field and its editor
popover, rendered when `presentation` resolves to `popover`. The
editor popover does not render in the `bottom-sheet` presentation, whose surface
-FR10–FR21 govern. FR25 governs a date-only value in both.
-
-| 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 does not yet provide one (its record names INV14 as ownership not yet met), so until it does the field keeps its own hold, to be replaced by the runtime's when it exists; 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. 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. Implementation gap: the trigger's token reads a `date_absolute` value whose operator sets `isDateOnly: false` as the popover presentation's token does, as its day in the device's zone with no time, not as a date and time in `timezoneID`. |
-| 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 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 commits `onChange(rest, 'remove', index)` 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 the body is one empty state: a heading "No filters applied", 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. 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 commits `onChange(kept, 'remove', <index of the first removed filter>)`, where `kept` is the read-only filters in their order: 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. Implementation gap: a row reads a `date_absolute` value whose operator sets `isDateOnly: false` as the trigger's token does, as its day in the device's zone with no time, not as a date and time in `timezoneID`. |
-| 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 commits `onChange([...filters, filter], 'add', filters.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 commits `onChange([...filters, filter], 'add', filters.length)`; choosing a field whose only operator takes an `empty` value commits 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 commits `onChange(updated, 'edit', index)`; the row's trailing remove action, or a tap on an `empty`-valued filter's row, commits `onChange(rest, 'remove', index)`, where `index` is the filter's position at commit time: a controlled parent that reorders or clones its filters while the step is open is followed by object identity, then by a structurally equal filter in the original slot, then by a unique structural match; when the target is gone or ambiguous nothing is committed and the step closes back to Filters, focus landing as FR16 states for a row that no longer exists. Every commit shows the Filters sheet as FR15a states. While the field is read-only, or disabled, no commit happens. | DEC-3; touch-flow evidence | Current contract; verified by focused sheet tests and real-engine touch evidence. |
-| 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. |
-| 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 — followed across a controlled reorder or clone, and, when a controlled update removed it or left two filters it could be, the nearest remaining row that is a button around its former position (the following one on a tie), else Add filter; 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 full-width choice rows with a trailing indicator instead of a dropdown that would stack a second layer on the sheet — `radio` rows in a `radiogroup` named by the field label for `enum` and `date_relative` (a tap selects the row; the group is one tab stop — the checked row, else the first — and the arrow keys move focus and check the row they land on, wrapping, Home and End move to and check the first and last row, and Space or Enter checks the focused row — `spec:AST-020/FR15`), `checkbox` rows in a `group` named by the field label for `enum_list` (a tap toggles the row; each row is its own tab stop, toggled with Space or Enter), each carrying its state as `aria-checked`, as the Tokenizer's sheet rows do; `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 a date only and stores its midnight. |
-| 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. | `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 outside this row: in the popover presentation its token, label and editor keep their released reading (the known gap in Open questions); the sheet presentation's rule for it is FR11, FR12 and FR17's. | DEC-5; `timezoneID` prop contract; `component:DateInput` (a calendar-day control) | Current contract. |
+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 does not yet provide one (its record names INV14 as ownership not yet met), so until it does the field keeps its own hold, to be replaced by the runtime's when it exists; 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. 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 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 commits `onChange(rest, 'remove', index)` 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 the body is one empty state: a heading "No filters applied", 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. 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 commits `onChange(kept, 'remove', <index of the first removed filter>)`, where `kept` is the read-only filters in their order: 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 commits `onChange([...filters, filter], 'add', filters.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 commits `onChange([...filters, filter], 'add', filters.length)`; choosing a field whose only operator takes an `empty` value commits 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 commits `onChange(updated, 'edit', index)`; the row's trailing remove action, or a tap on an `empty`-valued filter's row, commits `onChange(rest, 'remove', index)`, where `index` is the filter's position at commit time: a controlled parent that reorders or clones its filters while the step is open is followed by object identity, then by a structurally equal filter in the original slot, then by a unique structural match; when the target is gone or ambiguous nothing is committed and the step closes back to Filters, focus landing as FR16 states for a row that no longer exists. Every commit shows the Filters sheet as FR15a states. While the field is read-only, or disabled, no commit happens. | DEC-3; touch-flow evidence | Current contract; verified by focused sheet tests and real-engine touch evidence. |
+| 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. |
+| 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 — followed across a controlled reorder or clone, and, when a controlled update removed it or left two filters it could be, the nearest remaining row that is a button around its former position (the following one on a tie), else Add filter; 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 full-width choice rows with a trailing indicator instead of a dropdown that would stack a second layer on the sheet — `radio` rows in a `radiogroup` named by the field label for `enum` and `date_relative` (a tap selects the row; the group is one tab stop — the checked row, else the first — and the arrow keys move focus and check the row they land on, wrapping, Home and End move to and check the first and last row, and Space or Enter checks the focused row — `spec:AST-020/FR15`), `checkbox` rows in a `group` named by the field label for `enum_list` (a tap toggles the row; each row is its own tab stop, toggled with Space or Enter), each carrying its state as `aria-checked`, as the Tokenizer's sheet rows do; `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. | `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
@@ -517,18 +529,19 @@ mark implementation and focused real-Chromium verification as pending.
## Verification map
-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
-| FR1–FR3, FR7 | PowerSearch unit tests plus real-Chromium geometry assertions | 399/400, 720/721, wide outer surface, narrow viewport, LTR/RTL, collision | Removing either clamp, capping the main menu, or allowing viewport overflow fails. | `audit:PowerSearch/layout` |
-| FR4–FR6, FR9 | Opening-path tests plus real-Chromium geometry assertions | Add from inner input; edit actual left/right/equidistant token/control; pointer/keyboard; reopen opposite side | Using pointer coordinates, modality, wrapper-only identity, stale identity, or public props fails. | `audit:PowerSearch/interaction` |
-| PR1–PR4 | Instrumented unit tests plus first-frame real-Chromium capture | Open, close, reopen opposite side; hidden placement commit; first painted frame | Render-time reads, repeated reads, observers, pointer tracking, or a default-position flash fails. | `audit:PowerSearch/performance` |
-| FR8, AR1–AR3 | Existing PowerSearch/editor suites plus focused browser checks | Pointer and keyboard edit, apply, cancel, Escape, light dismiss, focus return, selection, semantics | Focus, semantics, selection, dismissal, or reachability changes fail. | `audit:PowerSearch/accessibility` |
-| FR22 | PowerSearch and Tokenizer unit tests | A read-only field with a filter: no Clear all, no token remove control, Backspace on the empty input | A read-only field removes a filter through Backspace, Clear all, or a token control. | `audit:PowerSearch/interaction` |
-| FR23 | PowerSearch and Tokenizer unit tests | Clear all with a read-only filter before two editable ones; every filter read-only; Backspace with a read-only last filter; the words with and without a read-only filter left | A read-only filter is removed, Clear all reports an index other than the first removed one, Clear all shows with no editable filter, or its words say every filter went while one remains. | `audit:PowerSearch/interaction` |
-| FR24 | `PowerSearchTokenNaming.test.tsx`; real-Chromium accessibility tree of a popover token | Popover token with a value, read-only token, editor open and closed, a verb-last remove word | A token named without its value, a missing or stale `aria-expanded`, an unnamed or non-dialog editor, or a remove name that loses its locale's word order fails. | `audit:PowerSearch/accessibility` |
-| FR25 | PowerSearch date-zone tests under four host zones (UTC, Los Angeles, Tokyo, Honolulu) with `timezoneID` set to each zone and unset: token text, the removal announcement that carries the accessible label, the editor's opening day, the stored instant after a pick, a round trip that moves the day and back, a `components` Editor override and `PowerSearchFilterEditor` receiving the zone, range parts read and written, and an `isDateOnly: false` value kept on its released reading; plus the formatter's unit tests | a Los Angeles evening instant with `timezoneID` set and unset, a pick across the US daylight-time change, a `date_range` of two instants | The token and the editor show different days for one value, a re-picked day moves the instant, or a day shows a time | `audit:PowerSearch/interaction` |
-| FR10–FR21, AR4–AR6, PR5 | Focused PowerSearch sheet tests with the compact-touch query stubbed both ways, plus real-engine touch evidence | the default resolving both ways, `popover` kept on a compact coarse-pointer screen, forced sheet, adaptive both ways (the default's server markup the same as `popover`'s, server markup and hydration as the popover field on a coarse-pointer client, then the trigger, no recoverable error, focus on the body; with `hasAutoFocus`, the autofocused input's focus ending on the trigger with no `onBlur` or `onFocus` to the caller), trigger name, Filters/Add filter/value steps, each value type, list value through the Tokenizer sheet, Clear all, read-only, disabled while open, focus after each step, focus after an `adaptive` switch from the trigger, the input, a removed control, an open editor popover, and from outside the field, a field inside an open Dialog announcing the count, Clear all, and in-sheet messages inside that Dialog and never on the page body, StrictMode result count, in-sheet live region while a sheet is open (added, removed, count, empty results), Clear all announced only after the dialog's exit, row, token and Removed text sharing one formatter, a date-only value as its day in `timezoneID`, else the UTC day, and a date-and-time value in `timezoneID`, else the viewer's zone, on all three (UTC, Tokyo, Honolulu, unset), summaries and relative-date labels and values from the catalog, the row and Removed through one reorderable message, an unmatched relative-date value as stored, a filter the config no longer knows listed and removable, a cleared number unstaged, choice rows as radios and checkboxes with `aria-checked`, a stale read-only filter as a plain row, a removal next to a nested row focusing that row's remove action, a list value joined by the locale's narrow conjunction list in English, Simplified Chinese, Japanese, and German, an empty-result message spoken once per query from its rendered element, a controlled update that removes the edited field moving focus from the replaced body to Cancel and announcing the unavailable state in the sheet while the step is open and never from a step beneath another or retained closed, Apply and Cancel after a controlled update removed the edited filter focusing the nearest row, else Add filter, a row's trailing remove action focusing the next row's remove action, a one-tap `empty`-valued filter added from its field row and removed from its row, Clear all behind its confirmation keeping read-only filters and leaving Filters open, a dismissed step revealing the step beneath with focus restored to it, Add filter opening with its search unfocused and a touch drag on the rows blurring a focused search, a stale filter's step titled as its row reads (raw keys for what is gone, the field's label when the field remains), Cancel from creation after the opening field was removed focusing the Add filter sheet's first control, a removed focused Filters row, a removed Clear all, and a dropped focused field row each handing focus to the nearest remaining row or the sheet's first control, element counts at rest and with each of the Filters, Add filter and value sheets open, and with the Tokenizer's list-value sheet stacked above the value step, under fine and coarse pointers, nothing of the flow in the DOM at rest before a press and after the exit, a nested filter edited and created through the built-in nested editor (its sub-filter rows wrapping inside a 390 and a 414 px sheet; its root operator picker absent on a mixed field, the Operator group in its place), a nested-only field and its suggestion offered, a suggestion's operator checked over the field's default, the Operator group outside a caller's Editor override on a mixed field, a count changed during the exit spoken with Clear all's message as one catalog message after the close, a radio group's arrow keys, Home, and End moving and checking, Space and Enter checking a focused radio row and toggling a checkbox row, right-to-left layout with the row chevrons mirrored in RTL (`design:bidirectionality/DR4`) | A field with a fine pointer or on a screen that is not compact changes by default beyond what FR19 states, `presentation="popover"` presents the sheet flow, a value commits before the step confirms, Clear all removes a read-only filter, the trigger carries native `disabled`, focus lands elsewhere, an announcement reaches a channel outside the modal that holds the field at that moment, or the popover bundle carries the sheets. | `audit:PowerSearch/sheet` |
-| Record structure | `scripts/check-knowledge.mjs` | Component-contract schema and current-authority dependency | Missing or invalid metadata and sections fail repository validation. | `audit:PowerSearch/knowledge` |
+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
+| FR1–FR3, FR7 | PowerSearch unit tests plus real-Chromium geometry assertions | 399/400, 720/721, wide outer surface, narrow viewport, LTR/RTL, collision | Removing either clamp, capping the main menu, or allowing viewport overflow fails. | `audit:PowerSearch/layout` |
+| FR4–FR6, FR9 | Opening-path tests plus real-Chromium geometry assertions | Add from inner input; edit actual left/right/equidistant token/control; pointer/keyboard; reopen opposite side | Using pointer coordinates, modality, wrapper-only identity, stale identity, or public props fails. | `audit:PowerSearch/interaction` |
+| PR1–PR4 | Instrumented unit tests plus first-frame real-Chromium capture | Open, close, reopen opposite side; hidden placement commit; first painted frame | Render-time reads, repeated reads, observers, pointer tracking, or a default-position flash fails. | `audit:PowerSearch/performance` |
+| FR8, AR1–AR3 | Existing PowerSearch/editor suites plus focused browser checks | Pointer and keyboard edit, apply, cancel, Escape, light dismiss, focus return, selection, semantics | Focus, semantics, selection, dismissal, or reachability changes fail. | `audit:PowerSearch/accessibility` |
+| FR22 | PowerSearch and Tokenizer unit tests | A read-only field with a filter: no Clear all, no token remove control, Backspace on the empty input | A read-only field removes a filter through Backspace, Clear all, or a token control. | `audit:PowerSearch/interaction` |
+| FR23 | PowerSearch and Tokenizer unit tests | Clear all with a read-only filter before two editable ones; every filter read-only; Backspace with a read-only last filter; the words with and without a read-only filter left | A read-only filter is removed, Clear all reports an index other than the first removed one, Clear all shows with no editable filter, or its words say every filter went while one remains. | `audit:PowerSearch/interaction` |
+| FR24 | `PowerSearchTokenNaming.test.tsx`; real-Chromium accessibility tree of a popover token | Popover token with a value, read-only token, editor open and closed, a verb-last remove word | A token named without its value, a missing or stale `aria-expanded`, an unnamed or non-dialog editor, or a remove name that loses its locale's word order fails. | `audit:PowerSearch/accessibility` |
+| FR25 | PowerSearch date-zone tests under four host zones (UTC, Los Angeles, Tokyo, Honolulu) with `timezoneID` set to each zone and unset: token text, the removal announcement that carries the accessible label, the editor's opening day, the stored instant after a pick, a round trip that moves the day and back, a `components` Editor override and `PowerSearchFilterEditor` receiving the zone, range parts read and written, and an `isDateOnly: false` value left to FR26; plus the formatter's unit tests | a Los Angeles evening instant with `timezoneID` set and unset, a pick across the US daylight-time change, a `date_range` of two instants | The token and the editor show different days for one value, a re-picked day moves the instant, or a day shows a time | `audit:PowerSearch/interaction` |
+| FR26 | PowerSearch date-and-time tests under four host zones (UTC, Los Angeles, Tokyo, Honolulu) with `timezoneID` set and unset: the token's date and time, the editor's opening date and time, the stored instant after a time is typed, a `components` Editor override and `PowerSearchFilterEditor` receiving the zone, the editor on a line of its own, and a date-only operator kept on the date picker; plus the sheet's value step opening on the time in `timezoneID` | a Los Angeles evening instant with `isDateOnly: false` and `timezoneID` Los Angeles, Tokyo, empty and unset; the same instant with `isDateOnly: true` | The token shows no time, the editor has no time field or opens on another time than the token shows, a typed time stores a different instant than it names, or a date-only operator gains a time field | `audit:PowerSearch/interaction` |
+| FR10–FR21, AR4–AR6, PR5 | Focused PowerSearch sheet tests with the compact-touch query stubbed both ways, plus real-engine touch evidence | the default resolving both ways, `popover` kept on a compact coarse-pointer screen, forced sheet, adaptive both ways (the default's server markup the same as `popover`'s, server markup and hydration as the popover field on a coarse-pointer client, then the trigger, no recoverable error, focus on the body; with `hasAutoFocus`, the autofocused input's focus ending on the trigger with no `onBlur` or `onFocus` to the caller), trigger name, Filters/Add filter/value steps, each value type, list value through the Tokenizer sheet, Clear all, read-only, disabled while open, focus after each step, focus after an `adaptive` switch from the trigger, the input, a removed control, an open editor popover, and from outside the field, a field inside an open Dialog announcing the count, Clear all, and in-sheet messages inside that Dialog and never on the page body, StrictMode result count, in-sheet live region while a sheet is open (added, removed, count, empty results), Clear all announced only after the dialog's exit, row, token and Removed text sharing one formatter, a date-only value as its day in `timezoneID`, else the UTC day, and a date-and-time value in `timezoneID`, else the viewer's zone, on all three (UTC, Tokyo, Honolulu, unset), summaries and relative-date labels and values from the catalog, the row and Removed through one reorderable message, an unmatched relative-date value as stored, a filter the config no longer knows listed and removable, a cleared number unstaged, choice rows as radios and checkboxes with `aria-checked`, a stale read-only filter as a plain row, a removal next to a nested row focusing that row's remove action, a list value joined by the locale's narrow conjunction list in English, Simplified Chinese, Japanese, and German, an empty-result message spoken once per query from its rendered element, a controlled update that removes the edited field moving focus from the replaced body to Cancel and announcing the unavailable state in the sheet while the step is open and never from a step beneath another or retained closed, Apply and Cancel after a controlled update removed the edited filter focusing the nearest row, else Add filter, a row's trailing remove action focusing the next row's remove action, a one-tap `empty`-valued filter added from its field row and removed from its row, Clear all behind its confirmation keeping read-only filters and leaving Filters open, a dismissed step revealing the step beneath with focus restored to it, Add filter opening with its search unfocused and a touch drag on the rows blurring a focused search, a stale filter's step titled as its row reads (raw keys for what is gone, the field's label when the field remains), Cancel from creation after the opening field was removed focusing the Add filter sheet's first control, a removed focused Filters row, a removed Clear all, and a dropped focused field row each handing focus to the nearest remaining row or the sheet's first control, element counts at rest and with each of the Filters, Add filter and value sheets open, and with the Tokenizer's list-value sheet stacked above the value step, under fine and coarse pointers, nothing of the flow in the DOM at rest before a press and after the exit, a nested filter edited and created through the built-in nested editor (its sub-filter rows wrapping inside a 390 and a 414 px sheet; its root operator picker absent on a mixed field, the Operator group in its place), a nested-only field and its suggestion offered, a suggestion's operator checked over the field's default, the Operator group outside a caller's Editor override on a mixed field, a count changed during the exit spoken with Clear all's message as one catalog message after the close, a radio group's arrow keys, Home, and End moving and checking, Space and Enter checking a focused radio row and toggling a checkbox row, right-to-left layout with the row chevrons mirrored in RTL (`design:bidirectionality/DR4`) | A field with a fine pointer or on a screen that is not compact changes by default beyond what FR19 states, `presentation="popover"` presents the sheet flow, a value commits before the step confirms, Clear all removes a read-only filter, the trigger carries native `disabled`, focus lands elsewhere, an announcement reaches a channel outside the modal that holds the field at that moment, or the popover bundle carries the sheets. | `audit:PowerSearch/sheet` |
+| Record structure | `scripts/check-knowledge.mjs` | Component-contract schema and current-authority dependency | Missing or invalid metadata and sections fail repository validation. | `audit:PowerSearch/knowledge` |
Current-source Chromium evidence establishes the geometry gap, not implementation
completion:
@@ -667,9 +680,8 @@ read and write a date-only `date_absolute` value, and each absolute part of a
`date_range`, as one day in one zone, its day in `timezoneID` when the prop is
set, else the UTC day; a value whose operator sets `isDateOnly: false` is an
instant with a time of day, read and written in `timezoneID`, else the viewer's
-zone (FR11, FR12, FR17). The `popover` presentation reads a date-only value
-the same way (FR25, DEC-5); the known gap below lists where its handling of an
-`isDateOnly: false` value still differs.
+zone (FR11, FR12, FR17). The `popover` presentation reads both the same way
+(FR25, FR26; DEC-5, DEC-6).
### DEC-4 — Clear all keeps read-only filters
@@ -707,17 +719,28 @@ device west of UTC; the UTC fallback changes no stored value). Rejected: a
separate prop for the editor's zone (one field, one zone; `timezoneID` already
names it).
+### DEC-6 — `isDateOnly: false` is an instant with a time of day
+
+**Reference:** `component:PowerSearch/DEC-6`
+**Decider:** `imdreamrunner`, 2026-11-02
+
+A `date_absolute` operator that sets `isDateOnly: false` names a value with a
+time of day. Its popover editor is a date picker beside a time field (the
+sheet's control is FR17's), and its token shows the date and the time, both
+reading and writing the instant in
+`timezoneID` when the prop is set, else the viewer's zone: an instant has no
+day of its own to keep stable, and the person reads it where they are; a field
+that needs every viewer to see one wall-clock time passes `timezoneID`. An
+operator with `isDateOnly` unset or `true` keeps the date picker. Rejected: a
+date-only editor for `isDateOnly: false` (the option's one documented meaning
+is a value with a time, and a date-only editor stored midnight and showed no
+time, so the option changed nothing). Rejected: UTC as the fallback zone for an
+instant (a wall-clock time typed by the person would then name a different
+hour than the one they read on their clock). Rejected: a time on the token for
+every `date_absolute` value (a calendar day has no time to show).
+
## Open questions
-- Known gap between the two presentations of one field, for a value whose
- operator sets `isDateOnly: false`: the popover presentation's editor edits a
- date only on the UTC day and stores midnight, its token reads the device's
- day, and its label reads a date and time in `timezoneID`, where the sheet
- edits and shows a time of day in `timezoneID`, else the viewer's zone (FR11,
- FR12, FR17). Such a value can therefore read differently on the popover's
- token and on the sheet's trigger and rows; a date-only value reads the same
- on both (FR25). Bringing the popover presentation's handling of that value
- to the sheet's is a stable change of its own (Compatibility and migration).
- Known gap, pre-existing in the popover presentation, against
`architecture:internationalization/INV1a`: its token writes the list,
date-range, and nested summaries ("{n} items", "date range", "{n} filters") as
@@ -725,11 +748,8 @@ names it).
FR12's rows use the locale's list format, and shows a relative-date value as
the stored key (`3d_ago`), and its relative-date editor writes the choice
labels ("3 days ago") as English literals. `formatFilterValue` resolves its
- summaries from the catalog but differs from the token in five places: it
- formats a `date_absolute` value whose operator sets `isDateOnly: false` with
- a time of day in `timezoneID` where the token shows that value's day in the
- device's zone (a calendar day reads the same on both, FR25); it says "{n}
- entities" for an
+ summaries from the catalog but differs from the token in four places: it
+ says "{n} entities" for an
entity list where the token says "{n} items"; it formats an `integer` or
`float` through the locale's number format and appends the operator's `units`
where the token prints the raw number; it collapses a list to a count when the
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index 26f1b80c3e..63a79fb61a 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -142,7 +142,7 @@ export const docs = {
name: 'timezoneID',
type: 'string',
description:
- 'IANA zone a date-only date_absolute value, and each absolute part of a date_range, is read and written in: the day shows, edits and stores (as that midnight) in it; unset, a day is its UTC day. A date_absolute with isDateOnly: false formats its label in it. E.g. "America/New_York".',
+ 'IANA zone a date-only date_absolute value, and each absolute part of a date_range, is read and written in: the day shows, edits and stores (as that midnight) in it; unset, a day is its UTC day. A date_absolute with isDateOnly: false shows and edits its date and time in it; unset, in the viewer\'s zone. E.g. "America/New_York".',
},
{
name: 'handleRef',
@@ -450,7 +450,7 @@ export const docsZh = {
name: 'timezoneID',
type: 'string',
description:
- '仅日期的 date_absolute 值及 date_range 的每个绝对端点读写所用的 IANA 时区:该日在此时区显示、编辑并以其午夜存储;未设置时为 UTC 日。isDateOnly: false 的 date_absolute 值的标签也在此时区格式化。例如 "America/New_York"。',
+ '仅日期的 date_absolute 值及 date_range 的每个绝对端点读写所用的 IANA 时区:该日在此时区显示、编辑并以其午夜存储;未设置时为 UTC 日。isDateOnly: false 的 date_absolute 值在此时区显示并编辑其日期和时间;未设置时为查看者所在时区。例如 "America/New_York"。',
},
{
name: 'handleRef',
diff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsx
index addd2b8a8a..01ac502628 100644
--- a/packages/core/src/PowerSearch/PowerSearch.tsx
+++ b/packages/core/src/PowerSearch/PowerSearch.tsx
@@ -385,8 +385,8 @@ export interface PowerSearchProps extends Omit<
* IANA zone a date-only `date_absolute` value, and each absolute part of a
* `date_range`, is read and written in: the token, the label and the editor
* show its day there, and a picked day stores as that midnight. Unset, a
- * day is its UTC day. A `date_absolute` with `isDateOnly: false` formats
- * its label in it.
+ * day is its UTC day. A `date_absolute` with `isDateOnly: false` shows and
+ * edits its date and time in it; unset, in the viewer's zone.
*/
timezoneID?: string;
/**
diff --git a/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx b/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx
index f13b7b0aa5..719dda1c77 100644
--- a/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx
+++ b/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx
@@ -294,6 +294,17 @@ const valueTypesConfig: PowerSearchConfig = {
},
],
},
+ {
+ key: 'updated',
+ label: 'Updated',
+ operators: [
+ {
+ key: 'after',
+ label: 'is after',
+ value: {type: 'date_absolute', isDateOnly: false},
+ },
+ ],
+ },
{
key: 'age',
label: 'Age',
@@ -4408,6 +4419,46 @@ describe('PowerSearch sheet value types (FR17)', () => {
expect(seen).toContain('Asia/Tokyo');
});
+ it('date_absolute with isDateOnly: false: the value step shows the time in timezoneID on the row, the date picker and the time field, and stores the time typed (FR26)', () => {
+ const instantFilter: PowerSearchFilter = {
+ field: 'updated',
+ operator: 'after',
+ // 2024-03-10T03:00:00Z: March 9, 7:00 PM in Los Angeles.
+ value: {type: 'date_absolute', unixSeconds: 1710039600},
+ };
+ const {onChange} = setupValues({
+ filters: [instantFilter],
+ timezoneID: 'America/Los_Angeles',
+ });
+ openSheet();
+ expect(
+ within(sheet()).getByRole('button', {name: /Mar 9, 2024, 7:00 PM/}),
+ ).toBeTruthy();
+ tapRow(/^Updated is after/);
+ expect(within(sheet()).getByRole('combobox', {name: 'Date'})).toHaveValue(
+ 'March 9, 2024',
+ );
+ const time = within(sheet()).getByLabelText('Time');
+ expect(time).toHaveValue('7:00 PM');
+ fireEvent.change(time, {target: {value: '8:30 PM'}});
+ fireEvent.blur(time);
+ apply();
+ expect(onChange).toHaveBeenCalledWith(
+ [
+ {
+ field: 'updated',
+ operator: 'after',
+ value: {
+ type: 'date_absolute',
+ unixSeconds: Date.parse('2024-03-10T04:30:00Z') / 1000,
+ },
+ },
+ ],
+ 'edit',
+ 0,
+ );
+ });
+
it('date_relative: rows stage a single relative value', () => {
const {onChange} = setupValues();
openAddFlow();
diff --git a/packages/core/src/PowerSearch/PowerSearchDateTime.test.tsx b/packages/core/src/PowerSearch/PowerSearchDateTime.test.tsx
new file mode 100644
index 0000000000..5ec825326e
--- /dev/null
+++ b/packages/core/src/PowerSearch/PowerSearchDateTime.test.tsx
@@ -0,0 +1,376 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file PowerSearchDateTime.test.tsx
+ * @input The real PowerSearch with a `date_absolute` operator whose
+ * `isDateOnly` is false, under several host zones and `timezoneID` values
+ * @output Assertions that the value is an instant: the token shows its date
+ * and time, the editor is a date-and-time control that opens on that time,
+ * and a time typed is stored as the instant it names in the same zone
+ * @position Regression coverage for the `isDateOnly: false` contract
+ */
+
+import {afterAll, afterEach, beforeAll, describe, expect, it, vi} from 'vitest';
+import {act, fireEvent, render, screen, waitFor} from '@testing-library/react';
+import React from 'react';
+import {PowerSearch} from './PowerSearch';
+import {PowerSearchFilterEditor} from './PowerSearchFilterEditor';
+import type {
+ PowerSearchConfig,
+ PowerSearchEditorProps,
+ PowerSearchFilter,
+} from './types';
+
+const originalMatches = HTMLElement.prototype.matches;
+const popoverOpenState = new WeakMap<HTMLElement, boolean>();
+
+beforeAll(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ popoverOpenState.set(this, true);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ popoverOpenState.set(this, false);
+ });
+ HTMLElement.prototype.matches = function (
+ this: HTMLElement,
+ selector: string,
+ ) {
+ if (selector === ':popover-open') {
+ return popoverOpenState.get(this) ?? false;
+ }
+ return originalMatches.call(this, selector);
+ } as typeof HTMLElement.prototype.matches;
+ // A real frame, not a synchronous call: the announcer records the frame
+ // id after scheduling, so a callback that runs inside the call would leave
+ // a stale pending frame behind.
+ let frameId = 0;
+ vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+ setTimeout(() => cb(performance.now()), 0);
+ return ++frameId;
+ });
+ vi.stubGlobal('cancelAnimationFrame', () => {});
+});
+
+afterAll(() => {
+ HTMLElement.prototype.matches = originalMatches;
+ vi.unstubAllGlobals();
+});
+
+const originalTZ = process.env.TZ;
+afterEach(() => {
+ if (originalTZ === undefined) {
+ delete process.env.TZ;
+ } else {
+ process.env.TZ = originalTZ;
+ }
+});
+
+const config: PowerSearchConfig = {
+ name: 'instants',
+ fields: [
+ {
+ key: 'at',
+ label: 'At',
+ operators: [
+ {
+ key: 'on',
+ label: 'on',
+ value: {type: 'date_absolute', isDateOnly: false},
+ },
+ ],
+ },
+ {
+ key: 'due',
+ label: 'Due',
+ operators: [
+ {
+ key: 'on',
+ label: 'on',
+ value: {type: 'date_absolute', isDateOnly: true},
+ },
+ ],
+ },
+ ],
+};
+
+// 2024-03-09 19:00 in Los Angeles, 2024-03-10 03:00Z, 2024-03-10 12:00 in Tokyo.
+const EVENING_LA = Date.parse('2024-03-10T03:00:00Z') / 1000;
+
+function tokenFor(label: string): HTMLElement {
+ const button = screen
+ .getAllByRole('button')
+ .find(
+ b =>
+ (b.textContent ?? '').startsWith(`${label}:`) &&
+ !/remove/i.test(b.getAttribute('aria-label') ?? ''),
+ );
+ if (!button) {
+ throw new Error(`token for ${label} not found`);
+ }
+ return button;
+}
+
+function tokenText(label: string): string {
+ return (tokenFor(label).parentElement?.textContent ?? '')
+ .replace(/\s+/g, ' ')
+ .trim();
+}
+
+// The popover is outside the accessible tree jsdom exposes for role queries,
+// so a control is found through its <label>.
+function inputLabelled(scope: string, text: string): HTMLInputElement | null {
+ const label = Array.from(
+ document.querySelectorAll<HTMLLabelElement>(`${scope} label`),
+ ).find(l => l.textContent === text);
+ const id = label?.getAttribute('for');
+ return id ? document.querySelector<HTMLInputElement>(`[id="${id}"]`) : null;
+}
+
+async function openEditor(label: string): Promise<{
+ date: HTMLInputElement;
+ time: HTMLInputElement | null;
+}> {
+ act(() => {
+ fireEvent.click(tokenFor(label));
+ });
+ await waitFor(() => {
+ expect(document.querySelector('[popover] input')).toBeTruthy();
+ });
+ const date = document.querySelector<HTMLInputElement>('[popover] input');
+ if (!date) {
+ throw new Error('editor input not found');
+ }
+ return {
+ date,
+ time: inputLabelled('[popover]', 'Time'),
+ };
+}
+
+function apply(): void {
+ const button = Array.from(
+ document.querySelectorAll<HTMLButtonElement>('[popover] button'),
+ ).find(b => b.textContent === 'Apply');
+ if (!button) {
+ throw new Error('Apply not found');
+ }
+ act(() => {
+ fireEvent.click(button);
+ });
+}
+
+function renderOne(
+ filter: PowerSearchFilter,
+ timezoneID: string | undefined,
+ onChange = vi.fn(),
+) {
+ render(
+ <PowerSearch
+ config={config}
+ filters={[filter]}
+ onChange={onChange}
+ label="Search"
+ timezoneID={timezoneID}
+ />,
+ );
+ return onChange;
+}
+
+const instantAt: PowerSearchFilter = {
+ field: 'at',
+ operator: 'on',
+ value: {type: 'date_absolute', unixSeconds: EVENING_LA},
+};
+
+describe('PowerSearch isDateOnly: false', () => {
+ it('shows the date and time in timezoneID and edits them in a date-and-time control', async () => {
+ process.env.TZ = 'Asia/Tokyo';
+ const onChange = renderOne(instantAt, 'America/Los_Angeles');
+ expect(tokenText('At')).toBe('At: onMar 9, 2024, 7:00 PM');
+ const {date, time} = await openEditor('At');
+ expect(date.value).toBe('March 9, 2024');
+ expect(time?.value).toBe('7:00 PM');
+ // A time typed in the editor is read in the same zone.
+ fireEvent.change(time as HTMLInputElement, {target: {value: '8:30 PM'}});
+ fireEvent.blur(time as HTMLInputElement);
+ apply();
+ expect(onChange).toHaveBeenLastCalledWith(
+ [
+ {
+ field: 'at',
+ operator: 'on',
+ value: {
+ type: 'date_absolute',
+ unixSeconds: Date.parse('2024-03-10T04:30:00Z') / 1000,
+ },
+ },
+ ],
+ 'edit',
+ 0,
+ );
+ });
+
+ it.each(['UTC', 'America/Los_Angeles', 'Asia/Tokyo', 'Pacific/Honolulu'])(
+ 'in timezoneID whatever the host zone (%s)',
+ async hostZone => {
+ process.env.TZ = hostZone;
+ renderOne(instantAt, 'Asia/Tokyo');
+ expect(tokenText('At')).toBe('At: onMar 10, 2024, 12:00 PM');
+ const {date, time} = await openEditor('At');
+ expect(date.value).toBe('March 10, 2024');
+ expect(time?.value).toBe('12:00 PM');
+ },
+ );
+
+ it("in the viewer's zone when timezoneID is unset", async () => {
+ process.env.TZ = 'Asia/Tokyo';
+ const onChange = renderOne(instantAt, undefined);
+ expect(tokenText('At')).toBe('At: onMar 10, 2024, 12:00 PM');
+ const {date, time} = await openEditor('At');
+ expect(date.value).toBe('March 10, 2024');
+ expect(time?.value).toBe('12:00 PM');
+ fireEvent.change(time as HTMLInputElement, {target: {value: '1:15 PM'}});
+ fireEvent.blur(time as HTMLInputElement);
+ apply();
+ expect(onChange).toHaveBeenLastCalledWith(
+ [
+ {
+ field: 'at',
+ operator: 'on',
+ value: {
+ type: 'date_absolute',
+ unixSeconds: Date.parse('2024-03-10T04:15:00Z') / 1000,
+ },
+ },
+ ],
+ 'edit',
+ 0,
+ );
+ });
+
+ it('reads an empty timezoneID as unset', () => {
+ process.env.TZ = 'Asia/Tokyo';
+ renderOne(instantAt, '');
+ expect(tokenText('At')).toBe('At: onMar 10, 2024, 12:00 PM');
+ });
+
+ it('gives the date-and-time control a line of its own so the field selector keeps its width', async () => {
+ process.env.TZ = 'UTC';
+ renderOne(instantAt, 'America/Los_Angeles');
+ const {date} = await openEditor('At');
+ const popover = date.closest<HTMLElement>('[popover]');
+ // The value cell spans the row and the row wraps, so the two-input
+ // control does not squeeze the field selector beside it.
+ const valueCell = Array.from(
+ popover?.querySelectorAll<HTMLElement>('div') ?? [],
+ ).find(el => getComputedStyle(el).flexBasis === '100%');
+ expect(valueCell).toBeTruthy();
+ expect(valueCell?.contains(date)).toBe(true);
+ expect(getComputedStyle(valueCell!.parentElement!).flexWrap).toBe('wrap');
+ });
+
+ it('wraps the date-and-time pair in a nested sub-filter row, where the value cell is narrower than its two inputs', async () => {
+ process.env.TZ = 'UTC';
+ const nestedConfig: PowerSearchConfig = {
+ name: 'NestedDateTime',
+ fields: [
+ ...config.fields,
+ {
+ key: 'group',
+ label: 'Group',
+ operators: [
+ {key: 'all_of', label: 'all of', value: {type: 'nested'}},
+ ],
+ },
+ ],
+ };
+ render(
+ <PowerSearch
+ config={nestedConfig}
+ filters={[
+ {
+ field: 'group',
+ operator: 'all_of',
+ value: {type: 'nested', value: [instantAt]},
+ },
+ ]}
+ onChange={vi.fn()}
+ label="Search"
+ timezoneID="America/Los_Angeles"
+ />,
+ );
+ const {date, time} = await openEditor('Group');
+ expect(time).toBeTruthy();
+ // The pair's own row wraps, so the time field drops under the date field
+ // instead of overlapping it in the width the nested selectors leave.
+ const pairRow = Array.from(
+ document.querySelectorAll<HTMLElement>('[popover] div'),
+ ).find(
+ el =>
+ el.children.length === 2 &&
+ el.contains(date) &&
+ el.contains(time) &&
+ getComputedStyle(el).flexWrap === 'wrap',
+ );
+ expect(pairRow).toBeTruthy();
+ });
+
+ it('leaves a date-only operator on the date picker with no time', async () => {
+ process.env.TZ = 'UTC';
+ renderOne(
+ {
+ field: 'due',
+ operator: 'on',
+ value: {type: 'date_absolute', unixSeconds: EVENING_LA},
+ },
+ 'America/Los_Angeles',
+ );
+ expect(tokenText('Due')).not.toMatch(/\d:\d\d/);
+ const {time} = await openEditor('Due');
+ expect(time).toBeNull();
+ });
+
+ describe("a caller's editor receives the zone", () => {
+ it('passes timezoneID to a components Editor override', () => {
+ process.env.TZ = 'UTC';
+ const seen: (string | undefined)[] = [];
+ function Editor(props: PowerSearchEditorProps) {
+ seen.push(props.timezoneID);
+ return <div>custom editor</div>;
+ }
+ render(
+ <PowerSearch
+ config={config}
+ filters={[instantAt]}
+ onChange={vi.fn()}
+ label="Search"
+ timezoneID="America/Los_Angeles"
+ components={{date_absolute: {Editor}}}
+ />,
+ );
+ act(() => {
+ fireEvent.click(tokenFor('At'));
+ });
+ expect(seen).toContain('America/Los_Angeles');
+ });
+
+ it('PowerSearchFilterEditor opens the date-and-time editor in timezoneID', async () => {
+ process.env.TZ = 'UTC';
+ render(
+ <PowerSearchFilterEditor
+ config={config}
+ filter={instantAt}
+ mode="edit"
+ onSave={vi.fn()}
+ onCancel={vi.fn()}
+ timezoneID="America/Los_Angeles"
+ />,
+ );
+ await waitFor(() => {
+ expect(document.querySelector<HTMLInputElement>('input')?.value).toBe(
+ 'March 9, 2024',
+ );
+ });
+ expect(inputLabelled('body', 'Time')?.value).toBe('7:00 PM');
+ });
+ });
+});
diff --git a/packages/core/src/PowerSearch/PowerSearchDateZone.test.tsx b/packages/core/src/PowerSearch/PowerSearchDateZone.test.tsx
index acc1cde534..889539e21b 100644
--- a/packages/core/src/PowerSearch/PowerSearchDateZone.test.tsx
+++ b/packages/core/src/PowerSearch/PowerSearchDateZone.test.tsx
@@ -396,8 +396,8 @@ describe('PowerSearch date zone', () => {
expect(screen.getByText('Mar 9, 2024')).toBeTruthy();
});
- it("PowerSearchToken keeps an isDateOnly: false value in the viewer's zone with its time", () => {
- process.env.TZ = 'America/Los_Angeles';
+ it('PowerSearchToken reads an isDateOnly: false value with its time in timezoneID, as the editor does', () => {
+ process.env.TZ = 'Asia/Tokyo';
function Token(props: PowerSearchTokenProps) {
return <PowerSearchToken {...props} />;
}
@@ -413,12 +413,12 @@ describe('PowerSearch date zone', () => {
]}
onChange={vi.fn()}
label="Search"
- timezoneID="Asia/Tokyo"
+ timezoneID="America/Los_Angeles"
components={{date_absolute: {Token}}}
/>,
);
- // 7:00 PM March 9 in Los Angeles, as it read before timezoneID reached
- // the token; the Tokyo reading would be March 10, 12:00 PM.
+ // 7:00 PM March 9 in Los Angeles, the time the editor opens on; the
+ // Tokyo viewer's reading would be March 10, 12:00 PM.
expect(screen.getByText('Mar 9, 2024, 7:00 PM')).toBeTruthy();
});
@@ -443,34 +443,9 @@ describe('PowerSearch date zone', () => {
});
});
- it('leaves a value with a time of day (isDateOnly: false) on its released reading', async () => {
- // Not a calendar day, so outside the zone rule: the token keeps the
- // device's day, the label its date and time in timezoneID, and the editor
- // the UTC day — as before, until that value has its own rule.
- process.env.TZ = 'America/Los_Angeles';
- const onChange = renderOne(
- {
- field: 'at',
- operator: 'on',
- value: {type: 'date_absolute', unixSeconds: EVENING_LA},
- },
- 'Asia/Tokyo',
- );
- expect(tokenText('At')).toBe('At: onMar 9, 2024');
- const remove = screen.getByRole('button', {name: /^Remove /});
- act(() => {
- fireEvent.click(remove);
- });
- expect(onChange).toHaveBeenCalledWith([], 'remove', 0);
- await waitFor(() => {
- const announced = Array.from(document.querySelectorAll('[aria-live]'))
- .map(region => region.textContent ?? '')
- .join(' ');
- expect(announced).toContain('Removed At: on Mar 10, 2024, 12:00 PM');
- });
- });
-
- it('opens a value with a time of day (isDateOnly: false) on the UTC day, as before', () => {
+ it('a value with a time of day (isDateOnly: false) is an instant, not a calendar day', () => {
+ // FR26 governs it: its token and label show the date and time in
+ // timezoneID; the date-only rule leaves it alone.
process.env.TZ = 'America/Los_Angeles';
renderOne(
{
@@ -478,9 +453,9 @@ describe('PowerSearch date zone', () => {
operator: 'on',
value: {type: 'date_absolute', unixSeconds: EVENING_LA},
},
- 'America/Los_Angeles',
+ 'Asia/Tokyo',
);
- expect(openEditor('At').value).toBe('March 10, 2024');
+ expect(tokenText('At')).toBe('At: onMar 10, 2024, 12:00 PM');
});
describe('range parts are calendar days in the same zone', () => {
diff --git a/packages/core/src/PowerSearch/PowerSearchEditPopover.tsx b/packages/core/src/PowerSearch/PowerSearchEditPopover.tsx
index 50121c65a8..4469c99af3 100644
--- a/packages/core/src/PowerSearch/PowerSearchEditPopover.tsx
+++ b/packages/core/src/PowerSearch/PowerSearchEditPopover.tsx
@@ -60,6 +60,12 @@ const styles = stylex.create({
chipRow: {
flexWrap: {default: 'nowrap', [CHIP_ROW_COLLAPSE]: 'wrap'},
},
+ // A date-and-time control is two inputs wide. Beside the selectors it
+ // shrinks the field selector to nothing. The row wraps, so the control
+ // gets its own line.
+ chipRowWrapped: {
+ flexWrap: 'wrap',
+ },
footer: {
padding: spacingVars['--spacing-3'],
paddingTop: 0,
@@ -80,6 +86,9 @@ const styles = stylex.create({
flexGrow: 2,
minWidth: 0,
},
+ valueEditorFullWidth: {
+ flexBasis: '100%',
+ },
// Nested editor styles
nestedRootLabel: {
fontSize: typeScaleVars['--text-label-size'],
@@ -659,7 +668,10 @@ function valueEditorKey(filter: {field: string; operator?: string}): string {
// Keyed on field + operator, so this also mounts on a field switch, not just
// when the popover opens; the focus handoff below runs for both.
-function ValueEditorCell(props: PowerSearchValueEditorProps) {
+function ValueEditorCell({
+ isFullWidth = false,
+ ...props
+}: PowerSearchValueEditorProps & {isFullWidth?: boolean}) {
const ref = useRef<HTMLDivElement>(null);
useEffect(() => {
@@ -677,7 +689,12 @@ function ValueEditorCell(props: PowerSearchValueEditorProps) {
}, []);
return (
- <div ref={ref} {...stylex.props(styles.valueEditor)}>
+ <div
+ ref={ref}
+ {...stylex.props(
+ styles.valueEditor,
+ isFullWidth && styles.valueEditorFullWidth,
+ )}>
<PowerSearchValueEditor {...props} />
</div>
);
@@ -849,6 +866,9 @@ export function PowerSearchEditPopover({
const operatorValue: OperatorValue | undefined = currentOperator?.value;
const isEmptyType = operatorValue?.type === 'empty';
+ const hasDateTimeValue =
+ operatorValue?.type === 'date_absolute' &&
+ operatorValue.isDateOnly === false;
const isNestedType = operatorValue?.type === 'nested';
const showOperatorSelector = operatorOptions.length > 1 || !isEmptyType;
@@ -920,7 +940,9 @@ export function PowerSearchEditPopover({
return (
<div {...stylex.props(styles.container)} onKeyDown={handleKeyDown}>
<div {...stylex.props(styles.content)}>
- <HStack gap={2} xstyle={styles.chipRow}>
+ <HStack
+ gap={2}
+ xstyle={[styles.chipRow, hasDateTimeValue && styles.chipRowWrapped]}>
<div {...stylex.props(styles.fieldSelector)}>
<Selector
label={t('@astryx.powersearch.editor.field')}
@@ -948,6 +970,7 @@ export function PowerSearchEditPopover({
{operatorValue && !isEmptyType && (
<ValueEditorCell
key={valueEditorKey(partialFilter)}
+ isFullWidth={hasDateTimeValue}
operatorValue={operatorValue}
filterValue={partialFilter.value}
onChange={handleValueChange}
diff --git a/packages/core/src/PowerSearch/PowerSearchToken.tsx b/packages/core/src/PowerSearch/PowerSearchToken.tsx
index d7b798389d..d7c4f6b8a1 100644
--- a/packages/core/src/PowerSearch/PowerSearchToken.tsx
+++ b/packages/core/src/PowerSearch/PowerSearchToken.tsx
@@ -60,11 +60,6 @@ export function PowerSearchToken({
10,
);
- // A value with a time of day keeps its reading in the viewer's zone; only
- // a calendar day reads in `timezoneID`.
- const isDateTime =
- operator.value.type === 'date_absolute' &&
- operator.value.isDateOnly === false;
const valueStr = formatFilterValue(
config,
operator.value,
@@ -72,7 +67,7 @@ export function PowerSearchToken({
adjustedMaxLength,
t,
locale,
- isDateTime ? undefined : timezoneID,
+ timezoneID,
);
const valueContent = valueStr ? (
diff --git a/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx b/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx
index eeebcc85fe..97f58a35ca 100644
--- a/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx
+++ b/packages/core/src/PowerSearch/PowerSearchValueEditor.tsx
@@ -19,6 +19,7 @@ import React, {
useCallback,
useMemo,
useRef,
+ useState,
type FormEvent,
type KeyboardEvent,
} from 'react';
@@ -43,10 +44,14 @@ import {
} from '../NumberInput/numberInputCommit';
import {DateInput} from '../DateInput';
import {
+ isoDateTimeToUnixSeconds,
isoDateToUnixSeconds,
resolveDateZone,
unixSecondsToISODate,
+ unixSecondsToISODateTime,
} from './powerSearchDateZone';
+import type {ISODateTimeString} from '../DateTimeInput/DateTimeInput';
+import {HStack} from '../HStack/HStack';
import {DateRangeInput, type DateRange} from '../DateRangeInput';
import {resolveDateTimeRangePart} from './resolveDateTimeRangePart';
import {TimeInput} from '../TimeInput';
@@ -504,6 +509,85 @@ function TimeEditor({
);
}
+/**
+ * A value with a time of day: its wall-clock time in `zone`, read and written
+ * as one instant through a date picker beside a time field.
+ */
+function DateTimeEditor({
+ label,
+ isDisabled,
+ presentation,
+ unixSeconds,
+ zone,
+ onChange,
+}: {
+ label: string;
+ isDisabled?: boolean;
+ presentation: EditorPresentation;
+ unixSeconds: number | undefined;
+ zone: string | undefined;
+ onChange: (value: FilterValue) => void;
+}) {
+ const t = useComponentTranslator();
+ const [datePart, timePart] = useMemo(() => {
+ if (unixSeconds == null) {
+ return [undefined, undefined] as const;
+ }
+ const [date, time] = unixSecondsToISODateTime(unixSeconds, zone).split('T');
+ return [date as ISODateString, time as ISOTimeString] as const;
+ }, [unixSeconds, zone]);
+ // A part picked first waits for the other. The editor writes the instant
+ // once both parts exist.
+ const [pendingDate, setPendingDate] = useState<ISODateString | undefined>();
+ const [pendingTime, setPendingTime] = useState<ISOTimeString | undefined>();
+ const date = datePart ?? pendingDate;
+ const time = timePart ?? pendingTime;
+ const commit = (
+ nextDate: ISODateString | undefined,
+ nextTime: ISOTimeString | undefined,
+ ) => {
+ if (nextDate == null || nextTime == null) {
+ return;
+ }
+ onChange({
+ type: 'date_absolute',
+ unixSeconds: isoDateTimeToUnixSeconds(
+ `${nextDate}T${nextTime}` as ISODateTimeString,
+ zone,
+ ),
+ });
+ };
+ const width = presentation === 'bottom-sheet' ? '100%' : undefined;
+ // A nested sub-filter row keeps its selectors' widths, so the pair wraps
+ // where the value cell is narrower than the two inputs.
+ return (
+ <HStack gap={2} wrap="wrap">
+ <DateInput
+ label={label}
+ isLabelHidden
+ isDisabled={isDisabled}
+ value={date}
+ onChange={value => {
+ setPendingDate(value);
+ commit(value, time);
+ }}
+ width={width}
+ />
+ <TimeInput
+ label={t('@astryx.powersearch.valueEditor.time')}
+ isLabelHidden
+ isDisabled={isDisabled}
+ value={time}
+ onChange={value => {
+ setPendingTime(value);
+ commit(date, value);
+ }}
+ width={width}
+ />
+ </HStack>
+ );
+}
+
function DateAbsoluteEditor({
operatorValue,
filterValue,
@@ -520,18 +604,29 @@ function DateAbsoluteEditor({
timezoneID?: string;
}) {
const t = useComponentTranslator();
- // A date-only value edits in the zone the token and the label use. An
- // `isDateOnly: false` value edits its UTC day.
- const zone =
- operatorValue.isDateOnly === false
- ? 'UTC'
- : resolveDateZone(timezoneID, true);
+ const label = t('@astryx.powersearch.valueEditor.date');
const unixSeconds =
filterValue?.type === 'date_absolute' ? filterValue.unixSeconds : undefined;
+ if (operatorValue.isDateOnly === false) {
+ return (
+ <DateTimeEditor
+ label={label}
+ isDisabled={isDisabled}
+ presentation={presentation}
+ unixSeconds={unixSeconds}
+ zone={resolveDateZone(timezoneID, false)}
+ onChange={onChange}
+ />
+ );
+ }
+
+ // A calendar day edits in the one zone the token and the label read it in.
+ const zone = resolveDateZone(timezoneID, true);
+
return (
<DateInput
- label={t('@astryx.powersearch.valueEditor.date')}
+ label={label}
isLabelHidden
isDisabled={isDisabled}
value={
diff --git a/packages/core/src/PowerSearch/formatFilterValue.test.ts b/packages/core/src/PowerSearch/formatFilterValue.test.ts
index 1ae214a088..7cb10cfd68 100644
--- a/packages/core/src/PowerSearch/formatFilterValue.test.ts
+++ b/packages/core/src/PowerSearch/formatFilterValue.test.ts
@@ -1,11 +1,7 @@
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, expect, it} from 'vitest';
-import {
- formatDateAbsolute,
- formatDateAbsoluteCompact,
- formatFilterValue,
-} from './formatFilterValue';
+import {formatDateAbsolute, formatFilterValue} from './formatFilterValue';
import type {TranslatorFn} from '../i18n';
import type {OperatorValue, FilterValue} from './types';
@@ -298,7 +294,6 @@ describe('formatFilterValue', () => {
formatDateAbsolute(unixSeconds, 'th-TH', undefined),
formatDateAbsolute(unixSeconds, 'th-TH', 'UTC', false),
formatDateAbsolute(unixSeconds, 'th-TH', undefined, false),
- formatDateAbsoluteCompact(unixSeconds, 'th-TH'),
]) {
expect(value).toContain('2026');
expect(value).not.toContain('2569');
diff --git a/packages/core/src/PowerSearch/formatFilterValue.ts b/packages/core/src/PowerSearch/formatFilterValue.ts
index 88000e79d3..5694e8c62f 100644
--- a/packages/core/src/PowerSearch/formatFilterValue.ts
+++ b/packages/core/src/PowerSearch/formatFilterValue.ts
@@ -59,8 +59,8 @@ export function formatSharedNumber(
* zone `resolveDateZone` names. The token text and the accessible label share
* it; the editors read the same zone through `resolveDateZone`, so a value
* never reads as two days in one field. A value whose operator sets
- * `isDateOnly: false` is not a calendar day: it keeps its date and time in
- * `timezoneID`, else the viewer's zone.
+ * `isDateOnly: false` is an instant: its date and time in `timezoneID`,
+ * else the viewer's zone, the time its editor reads and writes.
*/
export function formatDateAbsolute(
unixSeconds: number,
@@ -88,22 +88,6 @@ export function formatDateAbsolute(
return new Intl.DateTimeFormat(locale, options).format(unixSeconds * 1000);
}
-/**
- * The released token text for a value with a time of day: its day in the
- * viewer's zone, as the token has always shown it.
- */
-export function formatDateAbsoluteCompact(
- unixSeconds: number,
- locale: Locale,
-): string {
- return new Intl.DateTimeFormat(locale, {
- year: 'numeric',
- month: 'short',
- day: 'numeric',
- calendar: 'gregory',
- }).format(unixSeconds * 1000);
-}
-
function formatRelativeDate(value: string): string {
// value is stored as a descriptive string like "7d" or "1w"
return value;
diff --git a/packages/core/src/PowerSearch/formatTokenValue.ts b/packages/core/src/PowerSearch/formatTokenValue.ts
index 499c05b294..9b4cad2c3c 100644
--- a/packages/core/src/PowerSearch/formatTokenValue.ts
+++ b/packages/core/src/PowerSearch/formatTokenValue.ts
@@ -14,11 +14,7 @@
import type {OperatorValue, FilterValue, EnumItem} from './types';
import type {Locale, TranslatorFn} from '../i18n';
import {truncateCharacters} from '../utils/characters';
-import {
- formatDateAbsolute,
- formatDateAbsoluteCompact,
- formatSharedNumber,
-} from './formatFilterValue';
+import {formatDateAbsolute, formatSharedNumber} from './formatFilterValue';
import {registerEnglishFallback} from '../i18n/englishFallback';
import english from '../i18n/generated-english/PowerSearch/formatTokenValue.generated';
@@ -178,13 +174,15 @@ export function formatTokenValueText(
return filterValue.value;
case 'date_absolute':
- // A date-only value reads in the zone its editor uses. An
- // `isDateOnly: false` value reads its day in the viewer's zone.
+ // The token reads a value in the zone its editor uses.
return truncateString(
- operatorValue.type === 'date_absolute' &&
- operatorValue.isDateOnly === false
- ? formatDateAbsoluteCompact(filterValue.unixSeconds, locale)
- : formatDateAbsolute(filterValue.unixSeconds, locale, timezoneID),
+ formatDateAbsolute(
+ filterValue.unixSeconds,
+ locale,
+ timezoneID,
+ operatorValue.type !== 'date_absolute' ||
+ operatorValue.isDateOnly !== false,
+ ),
maxLength,
);
diff --git a/packages/core/src/PowerSearch/powerSearchDateZone.ts b/packages/core/src/PowerSearch/powerSearchDateZone.ts
index 9b1ebdbb93..c55ef8bdde 100644
--- a/packages/core/src/PowerSearch/powerSearchDateZone.ts
+++ b/packages/core/src/PowerSearch/powerSearchDateZone.ts
@@ -5,13 +5,16 @@
* @input A `date_absolute` or range part's `unixSeconds`, the operator's
* `isDateOnly`, and the PowerSearch `timezoneID`
* @output The one zone every reading of such a value uses, and the
- * conversions between an instant and the calendar day shown in that zone
+ * conversions between an instant and the calendar day or wall-clock time
+ * shown in that zone
* @position Shared by the token text, the accessible label, and the value
* editors, so a value reads as the same day everywhere in one field
*/
import type {ISODateString} from '../utils/dateTypes';
+import type {ISODateTimeString} from '../DateTimeInput/DateTimeInput';
import {
+ getWallClock,
plainDateFromDate,
plainDateFromInstant,
plainDateFromISO,
@@ -38,6 +41,8 @@ export function resolveDateZone(
return isDateOnly ? 'UTC' : undefined;
}
+const pad = (n: number, width = 2) => String(n).padStart(width, '0');
+
export function unixSecondsToISODate(
unixSeconds: number,
zone: string | undefined,
@@ -62,3 +67,29 @@ export function isoDateToUnixSeconds(
: plainDateToInstant(plain, zone);
return Math.floor(instant / 1000);
}
+
+export function unixSecondsToISODateTime(
+ unixSeconds: number,
+ zone: string | undefined,
+): ISODateTimeString {
+ const w = getWallClock(new Date(unixSeconds * 1000), zone);
+ return `${pad(w.year, 4)}-${pad(w.month)}-${pad(w.day)}T${pad(w.hour)}:${pad(w.minute)}` as ISODateTimeString;
+}
+
+export function isoDateTimeToUnixSeconds(
+ value: ISODateTimeString,
+ zone: string | undefined,
+): number {
+ const [datePart, timePart = '00:00'] = value.split('T');
+ const [hour = 0, minute = 0] = timePart.split(':').map(Number);
+ const plain = plainDateFromISO(datePart as ISODateString);
+ let instant: number;
+ if (zone == null) {
+ const d = plainDateToDate(plain);
+ d.setHours(hour, minute, 0, 0);
+ instant = d.getTime();
+ } else {
+ instant = plainDateToInstant(plain, zone, hour, minute);
+ }
+ return Math.floor(instant / 1000);
+}
diff --git a/packages/core/src/PowerSearch/types.ts b/packages/core/src/PowerSearch/types.ts
index a4007b4450..44eca66d36 100644
--- a/packages/core/src/PowerSearch/types.ts
+++ b/packages/core/src/PowerSearch/types.ts
@@ -61,7 +61,12 @@ export interface TimeOperatorValue {
export interface DateAbsoluteOperatorValue {
readonly type: 'date_absolute';
- /** If true, only show date picker without time. */
+ /**
+ * True or unset: the value is a calendar day, edited with a date picker.
+ * False: the value is an instant with a time of day, edited with a date
+ * picker and a time field and shown with its time in `timezoneID`, else
+ * the viewer's zone.
+ */
readonly isDateOnly?: boolean;
}
diff --git a/packages/core/src/Timestamp/formatInstant.ts b/packages/core/src/Timestamp/formatInstant.ts
index f0ba7df322..746bb5efd5 100644
--- a/packages/core/src/Timestamp/formatInstant.ts
+++ b/packages/core/src/Timestamp/formatInstant.ts
@@ -29,7 +29,7 @@
* - /packages/core/src/Timestamp/Timestamp.test.tsx
*/
-import {SHARED_DATE_FORMAT_OPTIONS, getTimeZoneParts} from '../utils/plainDate';
+import {SHARED_DATE_FORMAT_OPTIONS, getWallClock} from '../utils/plainDate';
import type {Locale} from '../i18n/types';
import type {TimestampFormat} from './Timestamp';
@@ -125,38 +125,6 @@ function pad(n: number): string {
return String(n).padStart(2, '0');
}
-/** The fields a `system_*` string is assembled from. */
-interface WallClock {
- year: number;
- month: number;
- day: number;
- hour: number;
- minute: number;
- second: number;
-}
-
-/**
- * Wall-clock fields for an instant: in the named zone, or — with no zone —
- * the viewer's own, read straight off the `Date`. The zone-less branch
- * deliberately stays on plain getters so the default rendering never gains a
- * dependency on `Intl` zone data it did not have before.
- *
- * The explicit return type is load-bearing: it is what forces the two branches
- * to keep producing the same shape.
- */
-function getWallClock(date: Date, timeZone: string | undefined): WallClock {
- return timeZone === undefined
- ? {
- year: date.getFullYear(),
- month: date.getMonth() + 1,
- day: date.getDate(),
- hour: date.getHours(),
- minute: date.getMinutes(),
- second: date.getSeconds(),
- }
- : getTimeZoneParts(date.getTime(), timeZone);
-}
-
/**
* Renders one instant in one absolute format.
*
diff --git a/packages/core/src/utils/plainDate.ts b/packages/core/src/utils/plainDate.ts
index 5c0de3f807..183b55e900 100644
--- a/packages/core/src/utils/plainDate.ts
+++ b/packages/core/src/utils/plainDate.ts
@@ -173,6 +173,38 @@ export function getTimeZoneParts(
};
}
+/** The wall-clock fields of an instant: in a zone, or in the viewer's. */
+export interface WallClock {
+ year: number;
+ month: number;
+ day: number;
+ hour: number;
+ minute: number;
+ second: number;
+}
+
+/**
+ * Wall-clock fields for an instant, in the named zone or in the viewer's
+ * zone (`undefined`, `null` or ""). The zone-less branch reads plain `Date`
+ * getters, so the default rendering needs no `Intl` zone data. The explicit
+ * return type keeps both branches on one shape.
+ */
+export function getWallClock(
+ date: Date,
+ timeZone: string | null | undefined,
+): WallClock {
+ return !timeZone
+ ? {
+ year: date.getFullYear(),
+ month: date.getMonth() + 1,
+ day: date.getDate(),
+ hour: date.getHours(),
+ minute: date.getMinutes(),
+ second: date.getSeconds(),
+ }
+ : getTimeZoneParts(date.getTime(), timeZone);
+}
+
function getTimezoneOffsetMS(timezoneID: string, instant: number): number {
const parts = getTimeZoneParts(instant, timezoneID);
return (