An open source design system that's fully customizable and agent ready
TypeScript
fix(PowerSearch): Done on a field that became read-only while the sheet was open reports nothing (#9914)
Xinzi Zhoucc034edb7dbe
diff --git a/.changeset/powersearch-presentation-stable.md b/.changeset/powersearch-presentation-stable.mdindex 1f5269f4d3..a50c0a89dc 100644--- a/.changeset/powersearch-presentation-stable.md+++ b/.changeset/powersearch-presentation-stable.md@@ -2,7 +2,7 @@'@astryxdesign/core': patch----[feat] PowerSearch gains a touch surface through a new `presentation` prop, `'popover' | 'bottom-sheet' | 'adaptive'`, typed by the new exported `PowerSearchPresentation`, with `'adaptive'` the default. `bottom-sheet` makes the whole field one trigger showing display-only filter tokens, and moves filter editing into a flow of tall modal sheets that stack: each step opens above the one that led to it, and dismissing a step reveals the one beneath, so no sheet has a Back action. A Filters sheet lists the active filters as rows that edit a filter, each with a trailing remove button, under a fixed header with Add filter and over a fixed footer with Clear all and Done; with no filter it shows one centered Add filter. The flow edits a draft of the filter list: adding, editing and removing a filter, and Clear all, change the draft, and Done applies it by calling `onChange` once per edit, in order, each with the list after that edit; a swipe, scrim or Escape close of a changed draft asks before discarding it, and a clean one closes directly. Clear all asks for confirmation, removes the editable filters, keeps read-only ones, and leaves Filters open. An Add filter sheet lists the fields grouped (searchable from eight fields), or the content search with the field typeahead's suggestions listed inline, and leaves its search unfocused until tapped; a field whose only operator takes no value adds at once. A value step stages operator → value and confirms from its footer, the editor on the sheet's surface, or in muted sections beside the operator choice. Closed vocabularies are full-width rows, numbers stage as typed, and `string_list` / `entity_list` values edit through the Tokenizer's own sheet presentation titled with the field label. `adaptive` uses the sheet on compact coarse-pointer screens and the popover otherwise, resolved the same way Selector resolves it. The sheet flow loads on demand, only when a field presents it. New `@astryx.powersearch.sheet.*` catalog keys for the sheets' strings; no new theming target.+[feat] PowerSearch gains a touch surface through a new `presentation` prop, `'popover' | 'bottom-sheet' | 'adaptive'`, typed by the new exported `PowerSearchPresentation`, with `'adaptive'` the default. `bottom-sheet` makes the whole field one trigger showing display-only filter tokens, and moves filter editing into a flow of tall modal sheets that stack: each step opens above the one that led to it, and dismissing a step reveals the one beneath, so no sheet has a Back action. A Filters sheet lists the active filters as rows that edit a filter, each with a trailing remove button, under a fixed header with Add filter and over a fixed footer with Clear all and Done; with no filter it shows one centered Add filter. The flow edits a draft of the filter list: adding, editing and removing a filter, and Clear all, change the draft, and Done applies it by calling `onChange` once per edit, in order, each with the list after that edit; a swipe, scrim or Escape close of a changed draft asks before discarding it, a clean one closes directly, and Done on a field that became read-only while the flow was open drops the draft. Clear all asks for confirmation, removes the editable filters, keeps read-only ones, and leaves Filters open. An Add filter sheet lists the fields grouped (searchable from eight fields), or the content search with the field typeahead's suggestions listed inline, and leaves its search unfocused until tapped; a field whose only operator takes no value adds at once. A value step stages operator → value and confirms from its footer, the editor on the sheet's surface, or in muted sections beside the operator choice. Closed vocabularies are full-width rows, numbers stage as typed, and `string_list` / `entity_list` values edit through the Tokenizer's own sheet presentation titled with the field label. `adaptive` uses the sheet on compact coarse-pointer screens and the popover otherwise, resolved the same way Selector resolves it. The sheet flow loads on demand, only when a field presents it. New `@astryx.powersearch.sheet.*` catalog keys for the sheets' strings; no new theming target.The API change is additive: the prop is new and optional, and no existing prop, type or export is removed or narrowed. The behavior changes only on compact coarse-pointer screens (phones), which is what `'adaptive'` is for: there a PowerSearch with no `presentation` shows the trigger and the sheet flow, a filter reaches `onChange` when Done applies the sheet's draft, and `menuWidth` and `tokenOverflowBehavior` have no surface, with a development warning that names them. With a mouse or trackpad, on a screen that is not compact, in the server render and while hydrating, nothing changes. Pass `presentation="popover"` to keep the previous behavior on every device. Shipping this default in a patch is a product decision of the engineering owner, agreed with the owner of the compatibility policy.diff --git a/docs/specs/components/PowerSearch/PowerSearch.spec.md b/docs/specs/components/PowerSearch/PowerSearch.spec.mdindex 859c53c397..bf11b0307b 100644--- a/docs/specs/components/PowerSearch/PowerSearch.spec.md+++ b/docs/specs/components/PowerSearch/PowerSearch.spec.md@@ -260,7 +260,7 @@ FR10–FR21 govern. FR25 governs a date-only value in both, and FR26 a date-and-| FR14 | The value step is a tall modal sheet that edits every operator's value, opened above the sheet that led to it — Filters for an edit, Add filter for a creation — which stays open beneath it (FR15a); its title is the dialog's name (AR5), and for a filter whose field or operator the config no longer has it reads as the Filters row does (FR12): the field's label when the config still has the field, the raw key for whatever is gone. Its header and footer stay fixed while the body scrolls. When the field offers more than one operator the body starts with an "Operator" radio group whose options read "{field label} {operator label}" and list the field's operators, with the operator the step opened with checked — the filter's operator while editing, and while creating the operator the suggestion named (FR13) or else the field's default operator, else its first; otherwise there is no group and the title is "{field label} {operator label}" naming that operator. When no operator label applies the title is the field label. The body below the group is the editor for the checked operator's value type: the sheet-native controls of FR17, or for a `nested` value the popover presentation's built-in nested editor — the sub-filter tree with its Add action, each sub-filter's field, operator, and value controls, and removal — rendered as the popover renders it, with one difference: the step's Operator group takes the place of the editor's root group-operator picker, which is not shown, and the tree root reads the checked operator's label; a sub-filter's controls are the popover editor's own, in their default presentation (a Selector's menu, the Tokenizer's inline field), not the sheet's choice rows (FR17) or Tokenizer sheet (FR21), which govern the step's top-level value only, because the nested editor renders its controls in their `popover` presentations; the tree is its own width container, so below 400 CSS px its rows wrap instead of overflowing the sheet, as they wrap in a narrow popover. A group is created and edited the same way in both presentations; switching the operator swaps the body. A value chosen in the body is staged, not committed: no `onChange` fires until the footer confirms it. Changing the operator keeps a staged value only when the new operator reads the same value type; an `empty` operator stages `{type: 'empty'}`. The body's sections sit on the sheet's surface when the editor is the body's only section; when the body has more than one section — the Operator group above the editor — each section is a muted container, so the grouping reads without a frame around a lone editor. The footer holds Cancel and the confirm action — `popoverSaveButtonLabel` when given, otherwise "Add filter" while creating and "Apply" while editing — disabled until the staged value is complete; the step has no Remove action: a filter is removed from its Filters row (FR12). When `components[type].Editor` is set for the checked operator's value type it replaces the body below the Operator group and the footer — the group stays outside it, so switching operators still swaps the body — receiving the props the popover presentation hands it, with the same meaning: the caller's `config`, the partial `filter`, `mode`, `saveButtonLabel`, `isReadOnly`, `timezoneID` (FR25), `onSave`, and `onCancel`, and nothing the popover does not pass; `onSave(filter)` commits it, `onSave(null)` removes the filter while editing and returns to Filters unchanged while creating. A controlled update that removes the field or operator being edited replaces the body with "This filter is no longer available", announced from its rendered element inside the sheet while the step is the open one (AR6), and keeps Cancel as the way out, the filter's trailing remove action on its Filters row being the removal path (FR12); when focus was on a control of the replaced body it moves to Cancel, so it never falls to the page body inside the open sheet (FR16). | DEC-3; touch-flow evidence | Current contract; verified by focused sheet tests and real-engine touch evidence. || FR15 | Confirming a created filter adds it to the draft (FR15b), recorded as `('add', draft.length)` with the list after it; choosing a field whose only operator takes an `empty` value adds that filter the same way from the Add filter row, with no value step. Tapping an editable Filters row opens the value step on that filter in edit mode; Apply writes the edited filter into the draft at its index, recorded as `('edit', index)`; the row's trailing remove action, or a tap on an `empty`-valued filter's row, removes it from the draft, recorded as `('remove', index)`, where `index` is the filter's position in the draft at that edit. The draft is the flow's own list: a controlled parent's change to `filters` while the flow is open does not reach the open sheets; Done replays the draft's edits onto the field's latest filters (FR15b), and a dismissal leaves the change in place, so it shows on the next open. Every edit shows the Filters sheet as FR15a states. While the field is read-only, or disabled, no edit happens. | DEC-3; DEC-7; touch-flow evidence | Current contract; verified by focused sheet tests. || FR15a | The steps stack: each step opens above the sheet that led to it, which stays open — receded and blocked as a covered sheet of the stack (`component:BottomSheet` FR5, FR6) — so the stack is Filters alone; Filters under Add filter; Filters under the value step for an edit; Filters under Add filter under the value step for a creation; or, when Add filter was the entry point, Add filter alone and then Add filter under the value step. No sheet of the flow carries a Back action: a dismissal — Escape, a scrim tap, a swipe, a platform close request — reaches only the top sheet (`component:BottomSheet` FR7), closes it, and reveals the sheet beneath, which takes focus back as FR16 states; dismissing the bottom sheet of the stack closes the flow. Cancel on the value step is that dismissal. A commit closes the step that made it: an edit's commit reveals Filters beneath the value step; a creation's commit, from the value step or from an Add filter row or suggestion that commits directly, closes Add filter, and the value step above it, together and shows Filters, so the person sees the filter just added: Filters is revealed when it is open beneath them; after a direct entry it opens in the same update that closes them — BottomSheet's same-update replace (`component:BottomSheet` FR10) when Add filter alone closes, and the stack's ordinary closes and open (`component:BottomSheet` FR5–FR9) when the value step closes with it. A creating `Editor` override's `onSave(null)` (FR14) shows Filters the same way. The flow therefore has one direction forward (open a step above) and one back (close the top step): no dismissal replaces a step, and Filters opens as other sheets close only when a creation ends after a direct entry. | DEC-3; `component:BottomSheet` FR5–FR9 | Current contract; verified by focused sheet tests and real-engine touch evidence. |-| FR15b | One open flow edits one draft of the filter list, which starts as `filters` when the flow opens. Every add, edit and removal (FR15) and Clear all (FR23, DEC-4) changes the draft, and the rows, the empty state and Clear all follow it; `onChange` is not called. Done applies the draft: it replays the recorded edits, in order, onto the field's latest `filters` — an add appends its filter; an edit replaces the first filter matching the one it edited (by field, operator, value and read-only flag); a removal drops the filters it removed — and calls `onChange` once per edit with the list after it and that edit's `changeType` and the `index` in that list, the calls a popover session makes, so a filter the parent added while the flow was open survives; an edit or removal whose target the parent removed meanwhile is skipped; then the flow closes; a draft that equals the filters at open (same filters, in order, by field, operator, value and read-only flag, whatever the order of a value's keys) reports nothing and closes. Done is in the Filters footer and in Add filter's footer when Add filter is the entry point. The field's result count follows the applied filters, so it changes on Done, not on an edit. | DEC-7 | Current contract; verified by focused sheet tests. |+| FR15b | One open flow edits one draft of the filter list, which starts as `filters` when the flow opens. Every add, edit and removal (FR15) and Clear all (FR23, DEC-4) changes the draft, and the rows, the empty state and Clear all follow it; `onChange` is not called. Done applies the draft: it replays the recorded edits, in order, onto the field's latest `filters` — an add appends its filter; an edit replaces the first filter matching the one it edited (by field, operator, value and read-only flag); a removal drops the filters it removed — and calls `onChange` once per edit with the list after it and that edit's `changeType` and the `index` in that list, the calls a popover session makes, so a filter the parent added while the flow was open survives; an edit or removal whose target the parent removed meanwhile is skipped; then the flow closes; a draft that equals the filters at open (same filters, in order, by field, operator, value and read-only flag, whatever the order of a value's keys) reports nothing and closes, and so does Done on a field that became read-only or disabled while the flow was open (the draft is dropped), as `component:Tokenizer` FR26 states for its sheet. Done is in the Filters footer and in Add filter's footer when Add filter is the entry point. The field's result count follows the applied filters, so it changes on Done, not on an edit. | DEC-7 | Current contract; verified by focused sheet tests. || FR15c | A dismissal of the flow's bottom sheet — Escape, a scrim tap, a swipe, a platform close request on Filters, or on Add filter when it is the entry point — closes the flow directly while the draft equals the filters at open. While the draft differs, it opens the discard confirmation inside the sheet (`SheetConfirmation`, the shape `component:Tokenizer` FR27 states): title "Discard changes?", description "Your changes to the filters haven't been applied.", the destructive Discard changes first in reading order and the safe Keep editing focused first; its scrim and Escape take the safe action. Keep editing closes the confirmation, keeps the draft, and returns focus to the sheet's first control — the Filters header's Add filter, else the sheet's panel; Discard changes closes the flow with no `onChange`, and the next open starts from the applied filters. A dismissal of a step above the bottom sheet reveals the step beneath (FR15a) and asks nothing: the draft is still open. | DEC-7; `component:Tokenizer` FR27 | Current contract; verified by focused sheet tests. || FR16 | Focus follows the step: after a commit from the value step while creating, the value step and Add filter close and focus lands on the Filters header's Add filter, ready for the next filter; after a content-search suggestion or an `empty`-valued field row commits a filter directly, that filter's row; after Apply or Cancel from editing, the edited filter's row; after a row's trailing remove action, or a caller's `Editor` override's `onSave(null)` while editing, which closes the value step, the trailing remove action of the nearest remaining row that has one (the following one on a tie) — a plain row, a read-only filter's, has none and is passed over — so a run of removals needs no re-aiming, else Add filter when no such row remains; after Cancel from creation, Add filter is revealed with focus on the field row that opened the step, or on the content search when a suggestion opened it — and when a controlled update has removed that field, or the content-search field itself, the Add filter sheet's first control: its search field when one shows, else its first field row; after Add filter is dismissed, the Filters header's Add filter, or the empty state's; after a caller's `Editor` override calls `onSave(null)` while creating, the same (the flow returns to Filters unchanged, FR14); after a confirmed Clear all, the Filters sheet's first remaining control — a kept read-only filter's row has none, so Add filter — with the sheet still open; after Keep filters, Escape, or a scrim tap dismisses the confirmation, Clear all (`component:Dialog` AR2); and, as one rule for the Filters and Add filter sheets, when a controlled update unmounts the control that holds focus — a filter's row or its remove action, a dropped field's row, Clear all gone with the last editable filter — the nearest remaining row that is a button, counted among the button rows by the removed one's index (the following one, else the last) — a plain row (a read-only filter, or every filter while the field is read-only) is passed over — else the sheet's first control (the Add filter sheet's search field, Add filter in the Filters header or empty state), else the sheet's panel, so focus never lands on the page body inside the open sheet; when a controlled update replaces the value step's body with the unavailable state while focus was on one of its controls, Cancel (FR14); after the flow closes, the trigger. A sheet that opens takes focus on its panel, not on a control, except where this row names one; the Add filter sheet's search fields never take it on open (FR13). | DEC-3; touch-flow evidence | Current contract; verified by focused sheet tests and real-engine touch evidence. || FR17 | The value step edits every value type with the same editor the popover presentation uses (`nested` through its built-in nested editor, FR14), with four sheet-native differences: `enum`, `enum_list`, and `date_relative` render as 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. |diff --git a/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx b/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsxindex c20d089321..f136c07ac0 100644--- a/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx+++ b/packages/core/src/PowerSearch/PowerSearchBottomSheet.test.tsx@@ -3852,6 +3852,36 @@ describe('PowerSearch sheet draft, Done and dismissal (FR15, FR15b, FR15c, FR22)]);});+ it('Done on a field that became read-only while the flow was open reports nothing and closes (FR15b)', () => {+ const onChange = vi.fn();+ function Harness() {+ const [isReadOnly, setIsReadOnly] = useState(false);+ return (+ <>+ <button type="button" onClick={() => setIsReadOnly(true)}>+ Lock+ </button>+ <PowerSearch+ config={config}+ filters={[openFilter, authorFilter]}+ onChange={onChange}+ isReadOnly={isReadOnly}+ presentation="bottom-sheet"+ />+ </>+ );+ }+ render(<Harness />);+ openSheet();+ fireEvent.click(removeButton('Author'));+ expect(onChange).not.toHaveBeenCalled();+ fireEvent.click(screen.getByRole('button', {name: 'Lock'}));+ expect(isSheetOpen()).toBe(true);+ done();+ expect(onChange).not.toHaveBeenCalled();+ expect(isSheetOpen()).toBe(false);+ });+it('the popover presentation is unchanged: a token removal reports at once, with no draft and no Done (desktop)', async () => {const {onChange} = setup({presentation: 'popover',diff --git a/packages/core/src/PowerSearch/PowerSearchBottomSheet.tsx b/packages/core/src/PowerSearch/PowerSearchBottomSheet.tsxindex 21516898dc..ff91beb608 100644--- a/packages/core/src/PowerSearch/PowerSearchBottomSheet.tsx+++ b/packages/core/src/PowerSearch/PowerSearchBottomSheet.tsx@@ -185,8 +185,9 @@ export interface PowerSearchBottomSheetProps {filters: ReadonlyArray<PowerSearchFilter>;/*** The field's `onChange`. Done replays the draft's edits through it, in- * order, each with the list as it stood after that edit; nothing is- * reported before Done.+ * order, onto the field's latest filters, each call carrying that list+ * with the edit applied; nothing is reported before Done, and nothing when+ * the field is read-only or disabled at Done.*/onChange: (filters: ReadonlyArray<PowerSearchFilter>,@@ -214,7 +215,7 @@ export interface PowerSearchBottomSheetProps {// Styles// =============================================================================-/** One edit of the draft: the list before it, the list after it, and how it was reported. */+/** One edit of the draft: the draft before and after it, and its type and index in the draft; Done replays it onto the field's latest filters. */interface DraftEdit {before: ReadonlyArray<PowerSearchFilter>;after: ReadonlyArray<PowerSearchFilter>;@@ -1159,12 +1160,13 @@ export function PowerSearchBottomSheet({// consumer gets the calls a popover session makes and keeps a filter it// added meanwhile.const commitAndClose = useCallback(() => {- if (isDraftDirty) {+ // A field that became read-only while the flow was open reports nothing.+ if (isDraftDirty && isInteractive) {replayDraftEdits(committedFilters, draftEditsRef.current, onCommit);}draftEditsRef.current = [];closeFlow();- }, [closeFlow, committedFilters, isDraftDirty, onCommit]);+ }, [closeFlow, committedFilters, isDraftDirty, isInteractive, onCommit]);const requestDismiss = useCallback(() => {if (isDraftDirty) {setIsDiscardConfirmationOpen(true);