Uh oh!
There was an error while loading. Please reload this page.
feat(spec): let an inline lookup action param declare its reference target (#3405) - #3406
Merged
Merged
Conversation
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 104 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
This was referenced Jul 22, 2026
… target (#3405) `ActionParamSchema` had no way to name the object an inline record-picker param should search. Authors reasonably wrote the same key the field schema uses — `{ name: 'inspector', type: 'lookup', reference: 'sys_user' }` — and the schema stripped it as an unknown key, silently. Downstream the param dialog saw a picker with no target and degraded it to a "paste the record id (UUID)" text input, so the authored intent was dropped and the user was handed a control a human cannot reasonably operate (found on a QC dispatch assign/transfer action). - Added `reference` to `ActionParamSchema`, spelled to match `FieldSchema.reference` so one spelling works in both places. It joins the existing inline widget config (`multiple` / `accept` / `maxSize`), which had covered the file/image params but not the picker ones. - A `lookup` / `master_detail` param declared inline with no `reference` is now a parse-time error pointing at the missing key, instead of degrading at render time. Field-backed params are unaffected: they inherit the target from the referenced field's metadata, which is not visible at parse time. - app-showcase's action-param gallery gains the inline picker specimen it could not previously express, next to the other widget types. Verified: `objectstack validate` on app-showcase fails with the new message when `reference` is removed and passes with it, and the param renders a working searchable picker in the console (see objectui's companion change). Refs #3405 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
os-zhuang pushed a commit
that referenced
this pull request
Jul 22, 2026
The `ui/action` reference doc regeneration is generated output and releases nothing on its own — the `@objectstack/spec` release is declared by the changeset in #3406. This empty-frontmatter changeset satisfies the "Check Changeset" gate, which diffs added .changeset files against this PR's base (the #3406 head) and otherwise sees none. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011W4a1eVS3aaYVRxKut68hK
Uh oh!
There was an error while loading. Please reload this page.
os-zhuang added a commit
that referenced
this pull request
Jul 24, 2026
…t (spec-owned), typed action handlers, file-as-reference (#3412) * docs(adr): ADR-0104 — field runtime value-shape as a first-class contract Design for three coupled gaps with one root cause (the runtime value shape of a field is nobody's contract): - D1: spec-owned valueSchemaFor(field) + semantic type classes; converge the four hand-duplicated type lists (record-validator, import-coerce, driver-sql, verify); reconcile the three dead value-schema exports; wire the field-zoo oracle to the contract. - D2: typed action handlers — declared params validated at REST/MCP dispatch, typed ctx.params via FieldValue<T>, file params become fileId references. - D3: file-as-reference — Field.file/image values store sys_file ids instead of inline {url} blobs, joining the existing lifecycle/GC/authz machinery. - D4: three-phase rollout (non-breaking convergence -> param enforcement -> protocol-major file migration). Generalizes the #3405/#3406 silently-stripped-param incident; relates #3407, #1878/#1891. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd * chore: empty changeset — ADR-0104 is a design doc, releases nothing Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd * docs(adr): ADR-0104 — add risks/migration-hazards and performance-budget sections Nine named risks (legacy-row stranding, warn-first rollout, unknown-key allowlist, GC freeze during migration, public-posture inventory, sub-key read breakage, external-URL retirement, cross-repo sequencing, spec purity) and the performance budgets/benchmark gates for each phase, so the phase PRs inherit them as acceptance items. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd * docs(adr): ADR-0104 accepted — implementation staged per D4 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd * chore: retrigger CI after GitHub Actions hosted-runner incident Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SHpGw3GBA9aFpfwVArRWfd --------- Co-authored-by: Claude <noreply@anthropic.com>
This was referenced Jul 24, 2026
Merged
os-zhuang added a commit
that referenced
this pull request
Jul 28, 2026
…ng them (#3405) (#3746) * feat(spec): reject unknown keys on an action param instead of stripping them (#3405) Closes part 3 of #3405 — the item deferred out of #3406 as "evaluate separately". Parts 1 and 2 gave an inline record-picker param a `reference` key and made a targetless one a parse error. That fixed the symptom. The mechanism that caused it stayed: `ActionParamSchema` was zod-default `.strip`, so any key it does not declare was discarded silently and the param went on parsing. An author wrote a correct, clearly intended `reference: 'sys_user'`, the key was eaten, and the dialog rendered a text box asking a human to paste a UUID — no error anywhere. The next mis-spelled key would have failed the same way, just as quietly. An action param is now `.strict()`, with an error map that makes the rejection fixable rather than merely loud: - Case/underscore slips (`help_text` → `helpText`, `default_value` → `defaultValue`) resolve through the shared `findClosestMatches`, bounded by the same length-relative distance `suggestKey` uses in `data/object.zod.ts` — a flat distance of 3 suggests `visible` for `wibble`. - Semantic near-misses edit distance cannot reach are named explicitly, in the `FIELD_TYPE_ALIASES` style: `reference_to` / `referenceTo` / `targetObject` → `reference` (the runtime field shape spells it the first way, objectui's resolved param the second), and `visibleWhen` / `visibleOn` / `visibility` → `visible`. That last one is why this matters beyond typos: ADR-0089 made `visibleWhen` canonical on view/page schemas, so borrowing it here used to strip a param's capability gate and render it unconditionally. Follows ADR-0078 (no-silently-inert-metadata) and ADR-0049 (enforce-or-remove), and matches the precedent set by ADR-0089 D3a for the view/page schemas. Verification: spec 258 files / 6716 tests pass; `tsc --noEmit` clean; app-showcase, app-crm and app-todo all `validate` clean — no existing metadata in the repo carried an undeclared param key. Planting `visibleWhen` on showcase's inline picker param reproduces the new error with the `visibleWhen` → `visible` prescription, and removing it validates again. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LkvDs4y4gveyB5NJZKxaZt * fix(spec): keep the schema's own JSDoc first in action.zod.ts (#3405) `scripts/build-docs.ts` `getFileDescription()` takes the FIRST `/** */` block in a module, verbatim, as the description of its generated reference page. Placing the new `ACTION_PARAM_KEYS` / error-map helpers above the "Action Parameter Schema" JSDoc therefore replaced the public authoring guide on `content/docs/references/ui/action.mdx` with an internal note about why a key list is kept beside the schema — which is what `check:docs` caught. Moved the helpers back below that JSDoc (after the `lazySchema` import, where they were originally). The generated doc is byte-identical to main again: `check:docs` reports 250 generated files in sync. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LkvDs4y4gveyB5NJZKxaZt * fix(spec): regenerate skill references, keep the error map internal (#3405) Two more generated-artifact gates behind `check:docs`, both tripped by the same commit: - `check:skill-refs` — importing `shared/suggestions.zod.ts` from `ui/action.zod.ts` pulls it into the transitive reference set of the objectstack-data / -ui / -platform skills. Regenerated via `gen:skill-refs`; the diff is the one expected line per skill, and `action.zod.ts` still resolves to "Action Parameter Schema", confirming the JSDoc-order fix held. - `check:api-surface` — `actionParamUnknownKeyError` was exported, which added it to the package's public API. It has no caller outside its own module, so the export was unnecessary: unlike `strictVisibilityError`, which is shared across the view/page schemas, this map is wired into exactly one schema. Made it module-private; the public API surface is now unchanged by this PR. All ten `check:*` gates in packages/spec pass locally, alongside 258 files / 6716 tests and a clean `tsc --noEmit`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LkvDs4y4gveyB5NJZKxaZt --------- Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes part 1 + 2 of #3405. Companion UI change: objectstack-ai/objectui#2786
问题
ActionParamSchema没有任何键可以指定内联 record-picker 参数要搜哪个对象。作者很自然地写了字段 schema 同名的键：schema 是
.strip，reference作为未知键被静默丢弃，不报错。下游的动作参数弹窗看到一个没有目标的 picker，降级成「粘贴记录 ID（UUID）」文本框。作者写对了，配置被吃掉了，用户拿到一个真人没法用的控件。真机场景（PLAT-DEF-005，天顺 EHR）：质检主管点【指派】/【转派】要选质检员，得先跑到别处把人的 UUID 复制出来再粘回去。同一套引用字段在新建/编辑弹窗里是正常的搜索式选择器。
讽刺的是 schema 里已经有一段「Widget config for inline params」的注释，把
multiple/accept/maxSize专门补给了内联参数 —— 唯独漏了 picker 需要的那一个。file/image 类内联参数能配全，lookup 配不全。改动
ActionParamSchema增加reference，键名对齐FieldSchema.reference，让同一个拼法在两处都成立 —— 租户已经写出来的代码原样就合法，不需要为平台再学第二种拼法。位置就放在现有的内联 widget config 那一组。lookup/master_detail缺reference→ 解析期报错，错误path指向reference，message 同时给出两条出路（补reference或改成字段引用式）。挂在现有.refine()链上。字段引用式参数不受影响 —— 它从被引用字段的元数据继承目标，那在解析期不可见。
验证
objectstack validate（app-showcase）：reference→✗ ["reference"] ActionParam with type "lookup"/"master_detail" requires "reference" (the target object) when declared inline …✓ Validation passed真机 UI（framework showcase :5311 + objectui console 指过去）：
GET /api/v1/meta/objects/showcase_field_zoo里p_account带上了reference: showcase_account；弹窗渲染出搜索式选择器，GET /api/v1/data/showcase_account?top=50&search=华宁服务端过滤命中，选中后按记录 ID 回填。全程不接触 UUID。@objectstack/spec全量测试：256 文件 / 6822 用例通过。破坏性说明
内联
lookup参数漏配reference的既有元数据，之前是静默降级成文本框，现在会在validate/ 解析期报错。这正是本 PR 的意图 —— 那些参数本来就是坏的，只是坏得没声音。修法就是错误信息里给的两条。🤖 Generated with Claude Code