Skip to content

Commit c3842ac

Browse files
feat(spec): a lookup field declares which fields a pick fills (lookupAutofill) (#28244)
domain:spec#1 · os-tesla · session_01L9qibwb6hBqszPTYJobitm <!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6JaoVaESC6HURrqfbfYJPCW9Nm)_ Fixes #27945 Clause-②: yes (widening) Metadata-protocol: added Skills-docs: follow-up #28246 ## 维护者速读 - 改了什么:查找字段新增 `lookupAutofill` 声明,写明「选中一条记录后,用它的哪个字段填本记录的哪个字段」(例:报价行选产品,`unit_price ← list_price`);规范侧在解析时和 `os validate` / `os build` 时校验,界面侧填值是后续 ui 卡。 - 为什么改:HotCRM 报价行的销售价只能在保存后由服务端钩子补上,表单里选完产品看不到价格;平台没有任何元数据能声明「选查找就带出字段」。 - 风险与回滚:纯新增可选键,现有元数据零影响;明细网格 `autofill` 列键的默认与语义不变(有对照测试)。回滚即 revert 本 PR。 - 先看:`packages/spec/src/data/field.zod.ts` 的 `lookupAutofill`(describe 里的覆盖规则)、`packages/spec/src/stack.zod.ts` 的 `lookupAutofillTypeMismatch`(类型兼容表)、`packages/spec/src/data/object.zod.ts` 的 `refuseDishonestLookupAutofill`。 - 两分钟验证:`pnpm --filter @objectstack/spec exec vitest run src/data/field-lookup-autofill.test.ts`,预期 18/18 通过。 - 需要你做的:无,席位落地。 ## What changes **The declaration: `FieldSchema.lookupAutofill`.** A single-value `lookup` / `master_detail` field may declare `[{ target, source, overwrite? }]`. A pick in the lookup copies the picked record's `source` field (a field of the `reference` object) into this record's `target` field. HotCRM's quote line declares it on its product lookup as `[{ target: 'unit_price', source: 'list_price' }]`. A pair is a closed shape (`strictObject`, with alias prescriptions `from` → `source`, `field` → `target`, `replace` → `overwrite`, and a few more), and the list is `.min(1)`. **The overwrite rule, stated in the describe.** A pick never replaces a value somebody wrote. The target is filled only while it is empty or still holds the value an earlier pick filled in, so a value the user typed, or one the record already stored, stays. A pair that declares `overwrite: true` says otherwise out loud and replaces the target on every pick. This is the HotCRM server hook's own rule moved to the form: its negotiated `unit_price` is defaulted only when blank and never overwritten on update. **Placement: the field, not a form view.** The record form draws a field from its definition whichever form shows it: a declared form view, a `formViews` entry, or the derived form an object without one gets. The inline line-item grid hydrates its columns from the same child field definitions (`hydrateColumns`). So the field is the one home both readers reach. A form-view key would be invisible to the grid and to every other form of the object. **Relation to the grid column key `autofill`, which is unchanged.** `InlineGridColumnSchema.autofill` keeps its contract: it governs only the grid's implicit same-named copy, on by default (`GridField.tsx#lookupAutofillPatch` overwrites with it today). A declared pair applies in a grid column over the field too, under its own overwrite rule, and takes its target out of the same-named copy, so one target never has two writers on one pick. `autofill: false` still switches off only the same-named copy. The describe says this, and a control test pins the column key's parse and its describe byte-for-byte. **Three doors judge it, each with a located refusal:** | Door | Refuses | Code + path | |:---|:---|:---| | `FieldSchema` superRefine | the key off `lookup` / `master_detail`; on `multiple: true` | `custom` at `lookupAutofill` | | `ObjectSchema` superRefine (`refuseDishonestLookupAutofill`) | a target that is the lookup itself, not a declared field, `readonly`, computed (`formula`, `summary`, `autonumber`, or an `expression`), or named twice | `custom` at `fields.FIELD.lookupAutofill.N.target` | | `defineStack` cross-reference pass (`collectLookupAutofillErrors`) | a source the referenced object does not declare, an `internal` source, a source whose value the target cannot hold | `STACK_CROSS_REFERENCE_INVALID` (422), one finding per pair, prefixed `Object 'O' field 'F' lookupAutofill[N].source:` | The first two run at every parse, the save door included. The third runs at `os validate` / `os build`, because only the stack holds the referenced object. It follows `collectHydratedInlineColumnErrors`: a referenced object the stack does not declare is not judged, and neither is an undeclared source that is one of the injected audit columns (`created_at`, …). **Type rule** (`lookupAutofillTypeMismatch`): the same type with the same multiplicity; a string-valued source (`text`, `textarea`, `email`, `url`, `phone`, `markdown`, `richtext`, `html`, `autonumber`) into a plain text target; `number` and `currency` into each other; a relationship only into a relationship over the same object. A `formula` source is judged by its `returnType`. A `summary`, or a formula with no `returnType`, is not judged. **Generated artefacts:** `content/docs/references/data/{field,object}.mdx`, `content/docs/references/system/migration.mdx`, `packages/spec/authorable-surface/data.json`, `docs/audits/2026-07-unknown-key-strictness-ledger.counts/data.md` (one new strict site), `packages/spec/liveness/state-counts/field.md`. **Liveness:** `liveness/field.json` gains a `planned` row (with `target` / `source` / `overwrite` children), naming the producer (HotCRM's quote line) and the consumer (the ui card: `LookupField` and `GridField`). No `authorWarn`, on the `referenceDeletedWhen` precedent. A warned field row would reopen the lint's field walk, which is outside this card's surface. **Form ledger:** `metadata-form-zod-reconciliation.test.ts` gains an `omit` row for `field.lookupAutofill` (planned, not yet read), beside `conditionalFormatting`. **Changeset:** `.changeset/27945-lookup-pick-autofill.md`, `@objectstack/spec` minor, with both declaration lines. **Not in this PR (the ui half).** The record form's lookup widget and the line-item grid writing the declared targets on pick are a separate `domain:ui` card. This PR does not touch `ui/`. ## Tests `packages/spec/src/data/field-lookup-autofill.test.ts`, 18 cases, each refusal pinned by its code and its path (never by the prose around it): - **Field half:** accepts on `lookup` and `master_detail` (control); refuses the key on a `text` field and on a `multiple: true` lookup (`custom` at `lookupAutofill`); refuses an empty list (`too_small`), a non-snake_case name (`invalid_format` at `lookupAutofill.0.target`) and an unknown key, whose message names `source` (`unrecognized_keys` at `lookupAutofill.0`). - **Target half:** the HotCRM shape and three target kinds parse clean (control); the lookup itself, an undeclared target, a `readonly` target, a `formula`, an `autonumber`, a stored field with an `expression`, and a target named twice (refused at the later pair, index 1) are each one `custom` issue at `fields.crm_product.lookupAutofill.N.target`. The registered `object` type schema (the save door) refuses the same way. - **Source half:** the HotCRM shape and seven compatible pairings build clean (control), as do an unresolved referenced object and an injected audit column; an undeclared source, an `internal` source, and five type mismatches (`text` → `currency`, `number` → `boolean`, a lookup over another object, a list → a single value, a `currency` formula → `boolean`) each raise one `STACK_CROSS_REFERENCE_INVALID` (422) finding at `lookupAutofill[N].source`. - **Control, grid `autofill` unchanged:** a lookup column still parses with `autofill: true` and `false`, an identity-only column still parses, the key's describe is pinned byte-for-byte, and a grid column refuses `lookupAutofill` (the pairs live on the field only). Also re-run on the merged head: `packages/spec` vitest over `src/data`, `src/stack*`, `src/compose-stacks*`, `src/define-stack*`, `src/inline-grid-column-carriers.test.ts` and `src/system/metadata-form-zod-reconciliation.test.ts`. The result was Test Files 200/200 and Tests 6051 passed, 1 todo. `pnpm --filter @objectstack/spec typecheck` passed (exit 0), and so did `pnpm --filter @objectstack/spec build` (no new dropped-refinement site: the checks sit in the existing `FieldSchema` / `ObjectSchema` superRefines). ## Acceptance notes - **The publish-time door, measured.** The order asked for the declared map to be validated "at publish". Inside `packages/spec` there are two doors. The parse runs at every door, the metadata save included, and it judges the field half and the target half. The stack cross-reference pass runs at `os validate` / `os build` only ("No wire door raises it", in `StackCrossReferenceError`'s own docblock), and it judges the source half. A runtime metadata save therefore judges the target and not the source. The runtime publish gate's object-aware field-ref checks live in `@objectstack/lint` (`validate-object-field-refs.ts`), which is outside this card's surface. Extending that rule to `lookupAutofill[].source` would close the gap for the save door. I am noting that here and not filing it: an unjudged source fills nothing, and a refusal at `os build` already covers every package-authored stack. - **`objectExtensions`.** A `lookupAutofill` declared on a field that an object extension adds is judged by the field half and by the source half (the stack pass merges extension fields by name). Its target half is not judged, because `ObjectExtensionSchema` has no view of the base object's field map. This is the same reach as `referenceDeletedWhen`. - **A `readonly` target is refused, by design.** HotCRM's line `list_price` is `readonly` and is stamped by its server hook. So the HotCRM declaration is `unit_price ← list_price` only, and `list_price` keeps arriving from the hook on save. Filling a readonly field on the form would show a value that the save then strips. - **Field-level security is not judged at authoring.** A source the reader cannot read (field `requiredPermissions`, or a permission set marking it non-readable) arrives masked or absent at run time. The ui half should read an absent value as "nothing to fill". `internal` is judged because it is absent for every reader. - **The grid's same-named copy overwrites; a declared pair does not.** This PR does not change the grid's `autofill` behaviour. The ui card applies the declared pairs under this key's overwrite rule and takes each declared target out of the same-named copy, as the describe states. The contract review can judge whether that relation is the right one. - **Out of scope, by the order:** the ui half (the record form's `LookupField` and `GridField` writing the declared targets on pick) is the follow-up `domain:ui` card, which the seat files. The `Skills-docs:` line above names the two teaching files owed with it. ## Verification Every reading below was taken on head `4c70e71e`, which is `origin/main` `7c3cc889` merged into the branch. The diff against `main` is the same 13 paths as before the merge. <details><summary>Derived gates: 107/107, all exit 0, reconciled with <code>dispatch-gates --ran</code> (0 NOT-MEASURED)</summary> - `node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack` derived 107 families from 13 changed paths at `4c70e71e`. The list is identical to the one derived before the merge, at `6ea314a6`. - Each family ran with `</dev/null`, and each exit code was recorded before any pipe. 106 exited 0 in the sweep. `check:skill-examples` answered exit 3 (PREREQUISITE NOT MET) because the merge's spec rebuild left the `client-react` closure stale. After `turbo run build --filter='@objectstack/client-react...'` it exited 0. - `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --ran FILE` printed: `✓ dispatch-gates --ran: 107 derived famil(ies) accounted for — 107 run, 0 NOT-MEASURED`. - On the pre-merge head `6ea314a6`, the same 107 also all reached exit 0. Seven exit-3 prerequisites needed workspace dists, and `check-plugin-teardown-shape --self-test` needed its pinned commit fetched. `check:type-check-debt` needed a longer window than the first sweep's per-gate timeout. </details> <details><summary>Spec artefacts, build and types</summary> - `pnpm --filter @objectstack/spec build` exited 0. No new dropped-refinement site, and the baseline is unchanged. - `pnpm --filter @objectstack/spec check:generated` reported all 14 artefacts current, after `--fix` regenerated the three it proved stale (`check:docs`, `check:strictness-ledger`, `check:liveness`), plus `gen:docs` for `object.mdx` after the merge. - `pnpm --filter @objectstack/spec typecheck` exited 0 (src, scripts and the test layer). </details> <details><summary>Local-only families (not in the derivation; machine state, reported only)</summary> - `pnpm check:skill-frame-freshness` exited 0. - `pnpm check:dev-prereqs` exited 1, on machine state only: 29 `ui/` workspace packages have no `dist/` in this container, because the `ui/` tree was not built. This diff touches no `ui/` path. </details> Dogfood: not run. The PR title carries no `!` and `Clause-②` carries the `(widening)` arm. --- _Generated by [Claude Code](https://claude.ai/code/session_01L9qibyU9JHYh6atGVnEXr3)_ --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent 744ad0a commit c3842ac

17 files changed

Lines changed: 688 additions & 8 deletions

File tree

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
'@objectstack/spec': minor
3+
'@objectstack/driver-sql': minor
4+
'@objectstack/metadata-core': minor
5+
---
6+
7+
feat(spec): a lookup field declares which fields a pick fills (`lookupAutofill`)
8+
9+
Clause-②: yes (widening)
10+
Metadata-protocol: added
11+
12+
A single-value `lookup` / `master_detail` field can now declare `lookupAutofill`: a list of `{ target, source, overwrite? }` pairs. A pick in the lookup copies the picked record's `source` field (a field of the referenced object) into the record's `target` field. A quote line's product lookup declares `[{ target: 'unit_price', source: 'list_price' }]`, so the sales price can fill from the product as soon as the product is picked, instead of only after save.
13+
14+
- **The overwrite rule.** By default (`overwrite` absent or false), a pick never replaces a value somebody wrote. The target is filled only while it is empty or still holds the value an earlier pick filled in, so a typed value, or one the record already stored, stays. A pair that declares `overwrite: true` replaces the target on every pick.
15+
- **One home for the form and the grid.** The declaration lives on the field, so the record form and a line-item grid column over the field both read it. The grid column key `autofill` is unchanged: it still governs only the grid's same-named copy, on by default. A declared pair takes its target out of that copy.
16+
- **Client-side only.** It fills the form. Nothing on the write path reads it, so an import or API write that sets the lookup fills nothing.
17+
- **Refused at parse:** the key on anything but a single-value relationship; a target that is the lookup itself, not a field of the object, `readonly`, computed (`formula`, `summary`, `autonumber`, or a field with an `expression`), or named twice; an unknown key in a pair.
18+
- **Refused by `os validate` / `os build`** (`STACK_CROSS_REFERENCE_INVALID`): a source the referenced object does not declare, an `internal` source, and a source whose value the target cannot hold (the same type and multiplicity, a string into a plain text field, `number` and `currency` into each other, or a relationship over the same object).
19+
- **Every-key tables classify the new key.** `@objectstack/driver-sql` classifies it `presentation` in `FIELD_KEY_STORAGE_CLASS`: no column DDL reads it. `@objectstack/metadata-core`'s field-level-security scrub (`FIELD_REFERENCE_POSITIONS`) drops a pair whose `target` is a field the caller cannot read, and deletes a list left empty. Each `source` names a field of the referenced object, which that object's own projection governs, so it is kept.
20+
21+
The form and grid that write the declared targets on pick ship in a follow-up. Until then the declaration is checked and stored, and fills nothing. Nothing to do for existing metadata.

‎content/docs/references/data/field.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ const result = CurrencyConfigSchema.parse(data);
8686
| **lookupFilters** | `{ field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'lt' \| 'gte' \| 'lte' \| 'contains' \| 'in' \| 'notIn'>; value: any }[]` | optional | Base filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter. |
8787
| **dependsOn** | `(string \| { field: string; param?: string })[]` | optional | Declares that this field's available values depend on the value of other field(s) on the same record — the form gates the field until they are set and re-evaluates as they change. For `lookup`/`master_detail` it scopes the candidate query (string = same local/remote key; `{field,param}` when the remote filter key differs — the `{field,param}` form is lookup-only). For `select`/`multiselect`/`radio` the actual per-option rule lives in each option's `visibleWhen`; list the referenced fields here (string form) so the option list gates and refreshes with the parent. |
8888
| **allowCreate** | `boolean` | optional | Allow inline quick-create from the record picker: when no match exists the user can create a record from the typed text (optimistic dataSource.create with the display field). Best for simple objects whose only required field is the display field. |
89+
| **lookupAutofill** | `{ target: string; source: string; overwrite?: boolean }[]` | optional | Fields a pick in this lookup fills on the record being edited: each `{ target, source }` pair copies the picked record's `source` field (a field of the `reference` object) into this object's `target` field — e.g. `[{ target: 'unit_price', source: 'list_price' }]` on a quote line's product lookup. Read wherever this field is picked: the record form, and a line-item grid column over it. OVERWRITE RULE — the default, `overwrite` absent or false: a pick never replaces a value somebody wrote. The target is filled only while it is empty or still holds the value an earlier pick filled in; a value the user typed, or one the record already stored, stays. Only a pair that declares `overwrite: true` replaces the target on every pick, whatever it holds. Client-side only: it fills the form, and nothing on the write path reads it — the filled value is saved as an ordinary write, and an import or API write that sets the lookup fills nothing. Only on a single-value `lookup` / `master_detail`. Each target is a field of this object other than this one, written by its author — not `readonly`, not computed (`formula`, `summary`, `autonumber`, or an `expression`) — and named once. Each source is a field of the referenced object that the record carries (not `internal`) and whose value the target can hold; `os validate` / `os build` judge the source. In a line-item grid the column key `autofill` still governs only the same-named copy and is unchanged; a declared pair takes its target out of that copy. |
8990
| **expression** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | CEL expression the field's value is computed from, e.g. F`record.amount * 0.1`. On a `formula` field: computed on read, no column. On any other (stored) field: computed by the engine from the row the write stores and stored, so a client-sent value never stands and a `summary` can roll the column up — on every insert and every update by id (the stored row merged with the patch), and on a predicate update only when the patch moves an input (one value for every matched row, else the update is refused). |
9091
| **returnType** | `Enum<'number' \| 'text' \| 'boolean' \| 'date' \| 'currency'>` | optional | Inferred value type of a formula field (number/text/boolean/date/currency). `currency`: an amount of money, in the currency the formula's own `currencyConfig` declares, as a currency field declares it (no `currencyConfig`: dynamic, the tenant default currency). |
9192
| **summaryOperations** | `{ object: string; field?: string; function: Enum<'count' \| 'sum' \| 'min' \| 'max' \| 'avg'>; relationshipField?: string; … }` | optional | Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted. |
@@ -224,6 +225,14 @@ const result = CurrencyConfigSchema.parse(data);
224225
| **readonlyWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Predicate (CEL) — the cell is read-only when TRUE, evaluated per row against the row as `record` plus the header as `parent` (e.g. P`parent.status == 'paid'`). |
225226
| **requiredWhen** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | Predicate (CEL) — the cell is required when TRUE. Same `record` + `parent` scope as `readonlyWhen`. PRESENTATION ONLY: this flags the cell inline-invalid in the grid; nothing on the write path reads it. The server-enforced contract is the child FIELD's own `requiredWhen` — a transition gate, see `Field.requiredWhen` — which hydration copies onto an identity-only column, so declaring the requirement here alone enforces nothing. |
226227

228+
### Nested Shape: `Field.lookupAutofill[number]`
229+
230+
| Property | Type | Required | Description |
231+
| :--- | :--- | :--- | :--- |
232+
| **target** | `string` | ✅ | Field of THIS object the pick fills (snake_case machine name). |
233+
| **source** | `string` | ✅ | Field of the picked record — a field of this lookup's `reference` object — whose value is copied (snake_case machine name). |
234+
| **overwrite** | `boolean` | optional | TRUE: the pick replaces whatever the target holds, a typed value included. Absent or FALSE: the pick fills the target only while it is empty or still holds the value an earlier pick filled in. |
235+
227236
### Nested Shape: `Field.summaryOperations`
228237

229238
| Property | Type | Required | Description |

‎content/docs/references/data/object.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -264,6 +264,7 @@ const result = ApiMethod.parse(data);
264264
| **lookupFilters** | `{ field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'lt' \| 'gte' \| 'lte' \| 'contains' \| 'in' \| 'notIn'>; value: any }[]` | optional | Base filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter. |
265265
| **dependsOn** | `(string \| { field: string; param?: string })[]` | optional | Declares that this field's available values depend on the value of other field(s) on the same record — the form gates the field until they are set and re-evaluates as they change. For `lookup`/`master_detail` it scopes the candidate query (string = same local/remote key; `{field,param}` when the remote filter key differs — the `{field,param}` form is lookup-only). For `select`/`multiselect`/`radio` the actual per-option rule lives in each option's `visibleWhen`; list the referenced fields here (string form) so the option list gates and refreshes with the parent. |
266266
| **allowCreate** | `boolean` | optional | Allow inline quick-create from the record picker: when no match exists the user can create a record from the typed text (optimistic dataSource.create with the display field). Best for simple objects whose only required field is the display field. |
267+
| **lookupAutofill** | `{ target: string; source: string; overwrite?: boolean }[]` | optional | Fields a pick in this lookup fills on the record being edited: each `{ target, source }` pair copies the picked record's `source` field (a field of the `reference` object) into this object's `target` field — e.g. `[{ target: 'unit_price', source: 'list_price' }]` on a quote line's product lookup. Read wherever this field is picked: the record form, and a line-item grid column over it. OVERWRITE RULE — the default, `overwrite` absent or false: a pick never replaces a value somebody wrote. The target is filled only while it is empty or still holds the value an earlier pick filled in; a value the user typed, or one the record already stored, stays. Only a pair that declares `overwrite: true` replaces the target on every pick, whatever it holds. Client-side only: it fills the form, and nothing on the write path reads it — the filled value is saved as an ordinary write, and an import or API write that sets the lookup fills nothing. Only on a single-value `lookup` / `master_detail`. Each target is a field of this object other than this one, written by its author — not `readonly`, not computed (`formula`, `summary`, `autonumber`, or an `expression`) — and named once. Each source is a field of the referenced object that the record carries (not `internal`) and whose value the target can hold; `os validate` / `os build` judge the source. In a line-item grid the column key `autofill` still governs only the same-named copy and is unchanged; a declared pair takes its target out of that copy. |
267268
| **expression** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | CEL expression the field's value is computed from, e.g. F`record.amount * 0.1`. On a `formula` field: computed on read, no column. On any other (stored) field: computed by the engine from the row the write stores and stored, so a client-sent value never stands and a `summary` can roll the column up — on every insert and every update by id (the stored row merged with the patch), and on a predicate update only when the patch moves an input (one value for every matched row, else the update is refused). |
268269
| **returnType** | `Enum<'number' \| 'text' \| 'boolean' \| 'date' \| 'currency'>` | optional | Inferred value type of a formula field (number/text/boolean/date/currency). `currency`: an amount of money, in the currency the formula's own `currencyConfig` declares, as a currency field declares it (no `currencyConfig`: dynamic, the tenant default currency). |
269270
| **summaryOperations** | `{ object: string; field?: string; function: Enum<'count' \| 'sum' \| 'min' \| 'max' \| 'avg'>; relationshipField?: string; … }` | optional | Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted. |
@@ -629,6 +630,7 @@ const result = ApiMethod.parse(data);
629630
| **lookupFilters** | `{ field: string; operator: Enum<'eq' \| 'ne' \| 'gt' \| 'lt' \| 'gte' \| 'lte' \| 'contains' \| 'in' \| 'notIn'>; value: any }[]` | optional | Base filters restricting which records are selectable (e.g. only active). The structured, picker-honoured lookup filter. |
630631
| **dependsOn** | `(string \| { field: string; param?: string })[]` | optional | Declares that this field's available values depend on the value of other field(s) on the same record — the form gates the field until they are set and re-evaluates as they change. For `lookup`/`master_detail` it scopes the candidate query (string = same local/remote key; `{field,param}` when the remote filter key differs — the `{field,param}` form is lookup-only). For `select`/`multiselect`/`radio` the actual per-option rule lives in each option's `visibleWhen`; list the referenced fields here (string form) so the option list gates and refreshes with the parent. |
631632
| **allowCreate** | `boolean` | optional | Allow inline quick-create from the record picker: when no match exists the user can create a record from the typed text (optimistic dataSource.create with the display field). Best for simple objects whose only required field is the display field. |
633+
| **lookupAutofill** | `{ target: string; source: string; overwrite?: boolean }[]` | optional | Fields a pick in this lookup fills on the record being edited: each `{ target, source }` pair copies the picked record's `source` field (a field of the `reference` object) into this object's `target` field — e.g. `[{ target: 'unit_price', source: 'list_price' }]` on a quote line's product lookup. Read wherever this field is picked: the record form, and a line-item grid column over it. OVERWRITE RULE — the default, `overwrite` absent or false: a pick never replaces a value somebody wrote. The target is filled only while it is empty or still holds the value an earlier pick filled in; a value the user typed, or one the record already stored, stays. Only a pair that declares `overwrite: true` replaces the target on every pick, whatever it holds. Client-side only: it fills the form, and nothing on the write path reads it — the filled value is saved as an ordinary write, and an import or API write that sets the lookup fills nothing. Only on a single-value `lookup` / `master_detail`. Each target is a field of this object other than this one, written by its author — not `readonly`, not computed (`formula`, `summary`, `autonumber`, or an `expression`) — and named once. Each source is a field of the referenced object that the record carries (not `internal`) and whose value the target can hold; `os validate` / `os build` judge the source. In a line-item grid the column key `autofill` still governs only the same-named copy and is unchanged; a declared pair takes its target out of that copy. |
632634
| **expression** | `string \| { dialect: Enum<'cel' \| 'cron' \| 'template'>; source: string; ast?: any; meta?: object }` | optional | CEL expression the field's value is computed from, e.g. F`record.amount * 0.1`. On a `formula` field: computed on read, no column. On any other (stored) field: computed by the engine from the row the write stores and stored, so a client-sent value never stands and a `summary` can roll the column up — on every insert and every update by id (the stored row merged with the patch), and on a predicate update only when the patch moves an input (one value for every matched row, else the update is refused). |
633635
| **returnType** | `Enum<'number' \| 'text' \| 'boolean' \| 'date' \| 'currency'>` | optional | Inferred value type of a formula field (number/text/boolean/date/currency). `currency`: an amount of money, in the currency the formula's own `currencyConfig` declares, as a currency field declares it (no `currencyConfig`: dynamic, the tenant default currency). |
634636
| **summaryOperations** | `{ object: string; field?: string; function: Enum<'count' \| 'sum' \| 'min' \| 'max' \| 'avg'>; relationshipField?: string; … }` | optional | Roll-up summary definition. The engine recomputes the value when child records are inserted/updated/deleted. |

0 commit comments

Comments
 (0)