Skip to content

Commit 273cb7d

Browse files
committed
docs(combobox-web): record the selector gate as an openspec change
Proposal, design and tasks for combobox-selector-gate; the step 3 change ticks its follow-up; the design docs record the status and the decision; the changelog gets the static-selection fix.
1 parent 3502ec2 commit 273cb7d

7 files changed

Lines changed: 116 additions & 1 deletion

File tree

‎docs/design/headless-combobox.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -441,6 +441,7 @@ Each step keeps the MPK, the XML, and the existing unit and E2E tests green.
441441
Status 2026-10-30: done in the package change `combobox-viewmodel`, on the same branch as step 1. `ComboboxCore` derives the ViewModel as cached slices, the two views render from the snapshot only, and `onAfterSearchTermChange` is gone. The Core is assembled by a brandi container (`src/core/Combobox.container.ts`), the composition root pattern of datagrid-web and gallery-web: a frozen config for the static properties, a props gate for the Mendix values, the selector family bound per instance, and a setup host for the debounced filter-input action. `getSelector` and `useGetSelector` are gone with it. Deferred to step 3: `isOpen`, `inputValue`, `highlightedIndex` and `highlighted` per option (downshift still owns them), and the selector reads inside the downshift and lazy-loading hooks. Deferred to step 4: option `content` is still rendered by the captions providers, so the Core does decide the caption markup until then. Additions to the contract found on the way: `selectedContent`, `canSelectAll`, `loading.lazy`, `hints.selectionMethod`, and `tabIndex` on the envelope.
442442
3. **Extract Behavior and Popover.** Make downshift controlled by the Core. Move `useDownshift*` and `useFloatingMenu` into the two hooks with the getter shapes from sections 4 and 5. Verify every item in the "behaviour that must survive" list.
443443
Status 2026-11-02: done in the package change `combobox-behavior`. The Core owns `isOpen` and `highlightedIndex`, `inputValue` is the search term, `enter` and `leave` run the Mendix actions and `leave` closes, the lazy first page is requested by `open()`. `useComboboxBehavior` runs downshift fully controlled and returns the section 4 getters without the data attributes (step 4); `useComboboxPopover` wraps the floating menu. The views take the ViewModel only. Deferred: `a11y.statusMessage` stays composed in the Behavior because the multi-mode text depends on downshift's previous result count; the selectors still take props through `updateProps`, split off as `combobox-selector-gate`.
444+
Status 2026-11-02, later the same day: `combobox-selector-gate` done. The selectors are computeds over the props gate and the frozen config, the way the data grid and gallery models derive from theirs; the datasource limit, filter and selection writes are setup reactions; `container.setProps` is the gate alone. One deliberate fix on the way: a static combo box follows an external clear of its attribute.
444445
4. **Introduce classes and data attributes.** Replace literal class names with the map and modifier classes with data attributes per the table in section 6. Update `Combobox.scss` and the E2E selectors.
445446
5. **Split into parts.** Break the Atlas View into one component per class key. Add the `classes` and `parts` props.
446447
6. **Move to a package.** Create `packages/headless/combobox`, point the widget at it, reduce `Combobox.tsx` to the wrapper in section 10.

‎docs/design/headless-widgets.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -360,3 +360,4 @@ We cannot guarantee accessibility of a custom View. We can hand the author the t
360360
| 2026-10-28 | Options carry `caption: string` always and `content?: ReactNode` when configured. Placement is a hint; the Core never decides where content is shown. |
361361
| 2026-10-28 | All texts, ARIA included, come through a typed `t(key, ...params)` on the envelope, wrapping the upcoming platform system-text API. Mechanics out of scope. |
362362
| 2026-10-30 | The Core is composed with a brandi container like the data grid and gallery: config, gate, selector family and setup host as bindings. The container never crosses the package boundary. |
363+
| 2026-11-02 | The model derives from the gate and the config as computeds; Mendix values stay behind plain getters so an in-place change is never hidden; writes to Mendix values are setup reactions. |

‎packages/pluggableWidgets/combobox-web/CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
66

77
## [Unreleased]
88

9+
### Fixed
10+
11+
- We fixed an issue where a combo box with static values kept showing its previous selection after the attribute was cleared by a microflow or nanoflow.
12+
913
### Changed
1014

1115
- We hid the "Placeholder text" property when the combobox type is set to Boolean, since boolean attributes can never be empty and the placeholder has no effect.

‎packages/pluggableWidgets/combobox-web/openspec/changes/combobox-behavior/tasks.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@
1313

1414
## 3. Refactoring
1515

16-
- [ ] 3.1 `combobox-selector-gate`: the selectors derive from the gate and the config instead of `updateProps`; `container.setProps` becomes the gate alone; `getAll()` stops scheduling the datasource filter from a getter.
16+
- [x] 3.1 `combobox-selector-gate`: the selectors derive from the gate and the config instead of `updateProps`; `container.setProps` becomes the gate alone; `getAll()` stops scheduling the datasource filter from a getter. Done on 2026-11-02.
1717
- [ ] 3.2 Step 4: classes map and data attributes; `CaptionContent` moves into the View; `a11y.statusMessage` when a second View needs it.
1818

1919
## 4. Verification
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
## Test Cases
2+
3+
The characterisation specs from `combobox-selector-safety-net` stay the net, adapted at their construction only: `createSelector(props)` resolves the selector from the container and runs the setup host, `setProps(next)` stands for the next render. Every behavioural expectation that is not listed under Behaviour changes below holds unchanged.
4+
5+
### Regression Tests
6+
7+
- Views render the same DOM (unit) - `src/__tests__/*.spec.tsx`
8+
- **Given**: the views over the derived selectors
9+
- **When**: the 29 component cases run
10+
- **Then**: all pass, the 5 snapshots are unchanged
11+
- Selector seam (unit) - `src/helpers/**/__tests__/*.spec.ts*`
12+
- **Given**: every family through the harness, `enforceActions: "always"`
13+
- **When**: status, value, captions, filtering, limit, lazy loading, writes
14+
- **Then**: the pinned expectations hold, no `[MobX]` warning
15+
16+
### New cases
17+
18+
- Association: no items requested while a datasource without lazy loading is loading; the page limit kept and nothing requested from an unpaged datasource while a lazy one is loading; client-side filtering with an expression caption even when lazy loading is on.
19+
- Database single: the datasource selection is the value when no attribute is bound; an unchanged attribute value leaves the selection alone across a props push; loading status while the datasource loads.
20+
- Container: a props push reaches the selector through the gate; the selector's side effects start with the setup host and not before.
21+
- `useComboboxCore`: a props push during render is reflected in the ViewModel of that render.
22+
23+
### E2E
24+
25+
- `pnpm run e2e` locally against the test project after an app restart, then on the PR through CI. Snapshots must be identical; this change changes no DOM.
26+
27+
## Decisions
28+
29+
- **Derive, do not copy.** A selector is a set of computeds over `gate.props` and the frozen config, the pattern of `rows.model.ts` and `items.model.ts` in the data grid and gallery. The only state left is the search term and the "page requested" marker of lazy loading.
30+
- **Mendix values behind plain getters.** A computed that returns a Mendix value object would compare it by identity and hide a change made in place, which the test builders do and which the design doc's rule 5 warns about. `attr`, `ds`, `selection` and the like are plain getters, so every computed that uses them reads `gate.props` itself.
31+
- **Side effects as setup reactions.** The datasource limit is an autorun over the wanted limit; the filter is a reaction on the search term; the database single selector syncs the datasource selection in a reaction keyed on the attribute value and the page ids (structural comparison, so a props push without a change fires nothing). They run on mount for the first props and synchronously inside each props push afterwards. Before, the same writes ran during the first render too.
32+
- **Family-neutral providers through `MappedGate`.** The association and database selectors map their props into `DatasourceSource` and `CaptionSource`, so one options provider and one captions provider serve both families. The mapped props object is new on every gate change, which is what the providers want.
33+
- **The loaded page is latched.** A datasource mid-reload may report no items; the provider keeps the previous page until the next one arrives, which is what the database selector's "skip while loading" guard protected, without freezing the rest of the selector.
34+
- **The static config grows by what the selectors read once.** `clearable`, the caption type, the editability rule and the chip sorting are simple-type properties, so they are read once like the rest.
35+
- **The specs go through the container.** A harness that resolves the selector from `createComboboxContainer` tests the wiring as well as the class: a selector that forgets to register with the setup host, or a token that is bound wrong, fails here first.
36+
- **Preview selectors are plain objects.** They take the preview props once and never change, so they need neither MobX nor a gate.
37+
38+
## Behaviour changes
39+
40+
Deliberate, each one a candidate the safety-net change had rated. Flipped expectations are marked in the specs.
41+
42+
1. **Static: an external clear clears the selection.** The old selector kept a stale `currentId` when the attribute was emptied by a microflow (safety-net quirk 1, rated medium). A derivation cannot keep stale state; the CHANGELOG records the fix.
43+
2. **Database single: `status` is `"loading"` while the datasource loads.** It was `"unavailable"` on the first load and frozen at the previous value on later reloads. The views treat `"loading"` like `"available"`, so the widget renders with the previous page instead of a placeholder on the first load.
44+
3. **Database single without a bound attribute takes the datasource selection as its value.** Before, the value only existed after `setValue` in the same page visit, so a reload showed nothing selected.
45+
4. **Enumeration: `clearable` while unavailable is the configured value**, not `true` (a pinned quirk with no effect, since nothing renders in that status). Likewise `readOnly` and `validation` read the attribute in every status.
46+
5. **The lazy-loading limit never-shrink rule is gone.** `LazyLoadProvider` remembered a limit that was overwritten with the current one on every update, so the rule never applied.
47+
48+
Not changed on purpose: chip sorting without a datasource sort order is still descending (quirk 2); the forced boxes style was already resolved in the config by step 2 (quirk 3); a missing `emptyOptionText` still makes a selector unavailable; a read-only control still limits its datasource to zero items.
49+
50+
## Notes
51+
52+
- The Core bound its commands before `makeObservable`, so the first `ComboboxCore` instance in a process carried the unwrapped prototype methods and `highlight` from a downshift effect tripped strict mode. The full suite passed by ordering; `pnpm run test -t "sets option to selected item"` failed on the step 3 tip. Binding after `makeObservable` fixes it; with it, the component specs pass in any order.
53+
- brandi rejects a class whose instance has a protected member named `valueOf`, since `Object.valueOf` is public; the database helper is `optionValue`.
54+
- Test count: 227 on the step 3 tip, minus the 9 `LazyLoadProvider` cases and 6 cases on fields that moved to the config, plus 6 new cases, equals 218.
Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
## Why
2+
3+
The last piece of the model seam that predates the headless design: the selectors took the container props by method call. `Combobox.container` pushed every props object through the gate and through `selector.updateProps` in one action, each selector copied a dozen props into observable fields, and the lazy-loading side effects (datasource limit, filter, selected-value reload, selection sync) ran inside that copy, during render. The data grid and gallery stores derive from the gate instead; the combobox was the exception, deferred from step 2 and step 3 as `combobox-selector-gate`.
4+
5+
## Root Cause
6+
7+
The selectors were written as plain classes mutated per render, and steps 1 to 3 kept that shape so the characterisation tests could pin them unchanged. With the Behavior extracted, nothing outside the Core reads a selector any more, so the seam can change without touching a view.
8+
9+
## What Changes
10+
11+
- `src/core/ComboboxGate.ts`: the gate carries every Mendix value of the widget, the family values included. `src/core/Combobox.config.ts`: `clearable`, `captionType`, `customEditability` and `selectedItemsSorting` join the frozen config.
12+
- `src/helpers/types.ts`: the `Selector` seam keeps `type`, `status`, `readOnly`, `validation`, `clearable`, `currentId`, `setValue`, `options` and `caption`; multi adds `getOptions` and `isOptionsSelected`. `updateProps`, the copied Studio Pro enumerations and the provider internals leave the interface. `OptionsProvider.hasMore`, `isLoading` and `loadMore` are always there.
13+
- `src/helpers/DatasourceOptionsProvider.ts` (new, replaces `BaseDatasourceOptionsProvider`, the two family providers and `LazyLoadProvider`): the page, the id map and the ids are computeds over a `DatasourceSource` gate; `setup` keeps the datasource limit in step with an autorun and turns a search-term change into the debounced datasource filter with a reaction, aborted on dispose. `getAll()` is a pure read.
14+
- `src/helpers/DatasourceCaptionsProvider.tsx` (new, replaces the association and database captions providers and `DatabaseValuesProvider`): captions, custom content and the empty caption over a `CaptionSource` gate.
15+
- `src/helpers/BaseOptionsProvider.ts`: abstract `ids`, the search term as the only state, `keepSourceOrder` for the static family.
16+
- Every selector takes `(host, gate, config)` or `(gate, config)`: `status`, `currentId`, `readOnly`, `validation` and `clearable` are computeds; the datasource-backed ones are setup components whose side effects run in reactions. `src/helpers/multiSelection.ts` holds the two multi-mode rules both multi selectors shared.
17+
- `src/helpers/Preview/*`: the editor preview selectors are plain objects over the preview props, one for the datasource families and one for the static one.
18+
- `src/core/Combobox.container.ts`: `setProps` is the gate alone; the selector classes are registered with their tokens like every other service.
19+
- `src/core/ComboboxCore.ts`: the commands are bound after `makeObservable`, so they are the action wrappers for the first instance too.
20+
- Removed: `LazyLoadProvider`, `BaseDatasourceOptionsProvider`, the family `utils.ts` extractors (except `getReadonly` and the type check of the database family), the family-nested `Preview` folders.
21+
- Specs: the selector specs resolve their selector from the container through `src/helpers/__tests__/harness.ts`, with the setup host running, and push the next render with `setProps`. Assertions on fields that moved to the config are gone; the `LazyLoadProvider` spec is replaced by limit cases on the association spec.
22+
23+
## Impact
24+
25+
- **Behaviour**: five deliberate changes, listed in `design.md`; the user-visible one (a static combo box now follows an external clear of its attribute) has a CHANGELOG line. 218 tests pass, the 5 DOM snapshots are untouched, no `-u`.
26+
- **Size**: 59 files, +1466 / -2295 lines in `src/`.
27+
- **Runtime**: the side effects on the Mendix values run in reactions: on mount for the first props, then synchronously inside the props push, as before. The datasource filter is scheduled once per search-term change instead of once per `getAll()` call.
28+
- **Release**: one CHANGELOG line under Fixed.
29+
- **Dependencies**: none added.
Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## 1. Test Setup
2+
3+
- [x] 1.1 Baseline on the step 3 tip: 19 suites, 227 tests, 5 snapshots, green; E2E green locally after the app restart.
4+
- [x] 1.2 `src/helpers/__tests__/harness.ts`: the selector resolved from the container with the setup host running.
5+
6+
## 2. Implementation
7+
8+
- [x] 2.1 Gate carries every Mendix value; config carries `clearable`, `captionType`, `customEditability`, `selectedItemsSorting`.
9+
- [x] 2.2 `Selector` seam slimmed; `DatasourceOptionsProvider`, `DatasourceCaptionsProvider`, `BaseOptionsProvider` with abstract `ids`.
10+
- [x] 2.3 Association, database, enumeration and static selectors derived from the gate; side effects in `setup`.
11+
- [x] 2.4 Preview selectors as plain objects under `src/helpers/Preview/`.
12+
- [x] 2.5 Container: `setProps` is the gate alone; selector classes registered with tokens; Core commands bound after `makeObservable`.
13+
- [x] 2.6 Specs adapted at construction; new limit, selection and container cases.
14+
15+
## 3. Verification
16+
17+
- [x] 3.1 `pnpm run test`: 18 suites, 218 tests, 5 snapshots unchanged, no `-u`; `pnpm run test -t "sets option to selected item"` passes in isolation.
18+
- [x] 3.2 `pnpm run lint`: 0 errors; 7 warnings, all pre-existing.
19+
- [x] 3.3 `pnpm exec tsc --noEmit -p tsconfig.json`: clean.
20+
- [x] 3.4 `pnpm run build`: MPK, editor preview and editor config build.
21+
- [ ] 3.5 E2E locally against the test project after an app restart in Studio Pro.
22+
- [ ] 3.6 E2E on the PR through CI with zero visual snapshot changes; waits for the safety-net PR to merge and a rebase on `main`.
23+
24+
## Notes
25+
26+
- One code commit plus this change, on the same branch as steps 1 to 3.

0 commit comments

Comments
 (0)