Repository navigation
Commit 462d02f
docs(spec): describe objectui's normaliseOptions as it is at the console pin (#24072)
Fixes #24047
Clause-②: no
## What changes
Three comments in `packages/spec` still said that objectui's
`normaliseOptions` rebuilds each option a field-backed action param
inherits as a bare `{ label, value }` pair. At the console pin it keeps
every key by spread. This PR rewrites the three comments and adds a
prose-only changeset. Nothing else changes.
- `packages/spec/src/ui/action.zod.ts`, the `ActionParam` `options`
docblock. The paragraph that began "What this does NOT fix" said the
drop "is tracked in objectui". It now describes objectui at the pin,
with file, lines and pin sha. It also gives the reason that is still
true for the guidance not prescribing "make it field-backed and
inherit": the keys survive the resolver, but nothing in this repo
measures a reader of `color`, `icon` or `disabled` on the inherited
path.
- `packages/spec/src/ui/action.zod.ts`, the comment above the option
shape's `guidance` table. Same correction. It points at the docblock for
the pin and line.
- `packages/spec/src/ui/action.test.ts`, the comment inside `keeps each
rejection pointing at where that vocabulary IS real`. Same correction.
- `.changeset/24047-action-param-options-comments.md`:
`'@objectstack/spec': patch`, prose only (see "Changeset" below).
No `guidance` string, schema, export or message text changes. All 34
changed lines in `packages/spec` are `*` or `//` comment lines. The
mechanical check is under Verification.
## The pin reading
`.objectui-sha` = `f8267df93aba8fb09cc1cc0692eadc0c8c5a5e56`. I read the
files with `git show PIN:PATH` from the local objectui object store.
- `packages/fields/src/resolveActionParams.ts:503` declares
`normaliseOptions`. Line `:515` is `return { ...raw, label, value:
raw.value };`.
- Lines `:650`-`:651` hold the field-backed branch, `authoredOptions ??
normaliseOptions(field.options, ownerName, param.field,
ctx.fieldOptionLabel)`. An authored list still wins over the inherited
one.
- Line `:241` is in the `resolveOptionLabels` docblock. It names
objectui `fbc23e094` as the change that made `normaliseOptions` keep
keys.
The card quoted `:503` at objectui `main` `94b2489f`. At the pin the
return is on `:515`, the line the claim also read.
## Readers on the inherited path: a source read at the pin, not a
runtime measurement
The card asked for any reader measurement to go here, not into a
comment. I read the dialog path at the same pin:
- `packages/app-shell/src/views/ActionParamDialog.tsx:536` re-spreads
each option to localise its label (`{ ...o, label:
pickLocalized(o.label, language) }`). Inherited keys survive this step
as well.
- `packages/app-shell/src/utils/paramToField.ts:102` passes `options:
param.options` into the widget's field metadata unchanged.
- The four option widgets build each option from `value` and
`optionDisplayLabel(option)` and nothing else:
- `packages/fields/src/widgets/SelectField.tsx:227-230`
- `MultiSelectField.tsx:191-206`
- `RadioField.tsx:134-145`
- `CheckboxesField.tsx:152-168`
`optionDisplayLabel` (`packages/core/src/evaluator/optionRules.ts:173`)
reads only `label` and `value`. Each `disabled` in those four files is
the field-level `props.disabled` (`SelectField.tsx:213`,
`MultiSelectField.tsx:201`, `RadioField.tsx:129`,
`CheckboxesField.tsx:163`), never a per-option one. None of the four
files reads `color` or `icon`.
So at the pin, an inherited option's `color`, `icon` and `disabled`
reach the widget, and none of the four widgets reads them. That matches
the current `guidance` texts, so this PR proposes no `guidance` change;
the card puts any such change on a card of its own anyway. This reading
has limits. It is a static source read of the four widgets the docblock
already names, not a rendered dialog, and no test in this repo pins it.
For that reason the comments say "not measured from this repo" and do
not say "no reader".
## Changeset
The card allowed no changeset, or a prose-only `patch` changeset if a
gate requires one. `Check Changeset` requires either a changeset or the
`skip-changeset` label. `@objectstack/spec`'s `files` array ships
`src/**/*.zod.ts`, so the rewritten docblock in `src/ui/action.zod.ts`
goes into the published tarball verbatim. "Publishes nothing" would
therefore be false, and the changeset is the accurate declaration. Its
body carries `Clause-②: no`.
## Verification
All readings below are on the final head `c89eef4e3b` (the merge of
`main`) unless marked otherwise. Build and test ran through
`scripts/pm/os-verify-lock.sh`, and each exit code was captured before
any pipe.
- `pnpm --filter @objectstack/spec build`: exit 0.
- `pnpm --filter @objectstack/spec exec vitest run --project local
--maxWorkers=2`: exit 0, `Test Files 692 passed (692)`, `Tests 20952
passed | 1 todo (20953)`.
- `pnpm --filter @objectstack/spec typecheck`: exit 0, ending
`check:test-typecheck: OK`.
- `action.test.ts` alone with `--reporter=verbose`, on the pre-merge
head `56ad5cf153`: `Tests 150 passed (150)`, including `keeps each
rejection pointing at where that vocabulary IS real`.
- `pnpm --filter @objectstack/spec check:generated`: exit 0, `All 14
generated artifacts are up to date`. The rewritten docblock reaches no
generated artifact. `check:api-surface` reports `public API surface +
factory signatures unchanged`, and `check:docs` reports `227 generated
files in sync`.
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` derived 85 commands. All 85 exit 0. `--ran`
reconciliation: `85 derived, 85 run, 0 NOT-MEASURED, 0 UNRUN`. Among
them, `check:nul-bytes` reports OK, `check-empty-changeset` reports 1
declaring changeset added, and `check-changeset-no-major` reports no
`major` bump.
- On the pre-merge head the same sweep had three exit-3 results
(`PREREQUISITE NOT MET`: `check:doc-formula-expressions`,
`check:dual-build-cjs-loads`, `check:lean-entry-closure`), because their
input packages were not built. After a build of `@objectstack/formula`,
`@objectstack/lint` and `@objectstack/objectql`, all three exit 0 on the
final head.
- Local-only family `node scripts/check-dev-prereqs.mjs`: exit 0.
- Comment-only check: `git diff -U0 origin/main...HEAD -- packages/spec`
has 34 changed lines, and 0 of them start with anything other than `*`
or `//`. A control-byte scan of the three files finds nothing.
- No ablation: the diff changes no tested behaviour.
- Not run locally, left to CI: `test:repo` (Test Core), the type-check
lanes, and the families `dispatch-gates` lists outside its runnable set.
- Since the merge, `origin/main` has gained two `packages/lint`-only
commits. Neither touches the three files here.
## Acceptance notes
- `packages/spec/CHANGELOG.md` still describes the old drop in two
entries (lines 40254 and 73939). Both are release-owned history.
AGENTS.md routes any change to a released entry through a dedicated
docs-only PR, so this PR leaves them as they are.
- The same `options` docblock has a `visibleWhen` bullet that says
objectui's inline branch "does `options: param.options`". At the pin,
the inline branch returns `options: authoredOptions`
(`resolveActionParams.ts:574`), which is
`resolveOptionLabels(param.options, ctx.locale)`. That call returns the
list untouched when every label is already a string, and rebuilds it by
spread otherwise. So the bullet's point, that the list is lowered
verbatim, still holds; only the quoted expression is out of date. The
claim's file surface names only the two comment blocks above, so this PR
does not edit the bullet. Carrier: none.
## Deviations
- Labels: none written. The dispatch's write budget names `git push`,
one `pr_create` and the report comment, and no label write.
- `main` was merged once before this PR opened (`c89eef4e3b`), as
AGENTS.md section 10 asks. The incoming commits do not touch any of the
three files. Spec was rebuilt and re-verified on the merged head.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01LFqdRsuM5nkqoJdHd5ztVk)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 27d7c2a commit 462d02f
3 files changed
Lines changed: 34 additions & 14 deletions
File tree
- .changeset
- packages/spec/src/ui
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1754 | 1754 | | |
1755 | 1755 | | |
1756 | 1756 | | |
1757 | | - | |
1758 | | - | |
| 1757 | + | |
| 1758 | + | |
| 1759 | + | |
1759 | 1760 | | |
1760 | 1761 | | |
1761 | 1762 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
265 | 265 | | |
266 | 266 | | |
267 | 267 | | |
268 | | - | |
269 | | - | |
270 | | - | |
271 | | - | |
272 | | - | |
273 | | - | |
274 | | - | |
275 | | - | |
276 | | - | |
| 268 | + | |
| 269 | + | |
| 270 | + | |
| 271 | + | |
| 272 | + | |
| 273 | + | |
| 274 | + | |
| 275 | + | |
| 276 | + | |
| 277 | + | |
| 278 | + | |
| 279 | + | |
277 | 280 | | |
278 | 281 | | |
279 | 282 | | |
| |||
307 | 310 | | |
308 | 311 | | |
309 | 312 | | |
310 | | - | |
311 | | - | |
312 | | - | |
| 313 | + | |
| 314 | + | |
| 315 | + | |
| 316 | + | |
| 317 | + | |
313 | 318 | | |
314 | 319 | | |
315 | 320 | | |
| |||
0 commit comments