@object-ui/core 17.6.0 → 17.7.0

package/dist/utils/parent-scope.d.ts

@@ -0,0 +1,123 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * The parent-relationship condition a detail-page related list is scoped by —
+ * compiled ONCE, here, for every surface that asks the question.
+ *
+ * ## Why this is a seam and not a helper
+ *
+ * A related list asks its backend "which children belong to this parent?" from
+ * two places: the ROW query (`RelatedList`) and the tab-badge count probe
+ * (`RelatedCountStore`). Those two used to compile the condition separately,
+ * and objectui#8882 is what that costs: objectui#7299 taught the ROW side to
+ * compile by the relationship field's ARITY, the BADGE side kept sending bare
+ * equality, and on a multi-value relationship the page then rendered rows above
+ * a tab with no count at all — two implementations of one question, drifted.
+ *
+ * Patching the second copy to match the first would leave two copies. So the
+ * condition has one implementation, and both callers import it.
+ *
+ * ## The rule itself is not invented here
+ *
+ * The arity verdict is `@objectstack/spec/data`'s own `isMultiValueField`. That
+ * matters more here than anywhere: this function chooses `$contains` vs `=` and
+ * every surface that asks the question now reads that one choice, so two
+ * readers of one question disagreeing — the entire defect class — cannot
+ * recur INSIDE this repository. The spec's rule is BROADER than an eyeballed
+ * `multiple === true` in both directions — `multiselect` / `checkboxes` /
+ * `tags` persist an array with no flag at all, and `multiple: true` is INERT on
+ * a type outside the spec's multi-capable set (`master_detail`, say) — so a
+ * local approximation is wrong in both directions, not merely incomplete.
+ *
+ * ⛔ Do not add a local arity rule at any call site, however small, and ⛔ do
+ * not widen this function to accept an arity the caller computed: the parameter
+ * it takes is METADATA, and the verdict is drawn from it here.
+ *
+ * ## ⚠️ The STORAGE side does not read this predicate — the two rules DIVERGE
+ *
+ * This header used to say `isMultiValueField` is "the same predicate the driver
+ * that executes the query decides on". It is not, and the difference is
+ * observable (objectui#8937). Measured on objectstack `origin/main`,
+ * `driver-sql` gates the equality family on its own STORAGE question,
+ * `isJsonField`: a column is JSON when the field's type is in that driver's
+ * `JSON_COLUMN_TYPES` — the spec's `STRUCTURED_JSON_TYPES` and
+ * `MULTI_OPTION_TYPES`, plus the driver-internal `object` / `array` aliases —
+ * OR when `multiple` is merely TRUTHY, on ANY type; a single-value media type
+ * answers from the ADR-0104 dual-encoding window instead. The spec's predicate
+ * is `MULTI_OPTION_TYPES.has(type) || (MULTI_CAPABLE_TYPES.has(type) &&
+ * multiple === true)`.
+ *
+ * ⇒ They diverge for a type OUTSIDE `MULTI_CAPABLE_TYPES` carrying
+ * `multiple: true` (`master_detail` / `tree` / `text`): the spec says
+ * single-valued, so this seam compiles `=`, while the driver stores a JSON
+ * column and refuses `=` with the same `400 INVALID_FILTER` objectui#7299 was
+ * filed for. That is a KNOWN divergence and ⛔ not a regression — both
+ * surfaces sent `=` for that shape before objectui#7299 and objectui#8882 too.
+ *
+ * ⛔ Do NOT close it by widening the predicate here: which of the two rules is
+ * right is an upstream question, filed as objectstack#17469 (enforce-or-align),
+ * and this seam is deliberately not blocked on it. Widening on this side would
+ * move the disagreement across the wire rather than end it, and would make the
+ * ONE compiler this module exists to be disagree with the spec it delegates to.
+ * The divergence is re-derived from the installed spec on every run by
+ * `relatedListParentScopeResidue-8937.test.ts`, so this section reddens when the
+ * spec side moves.
+ */
+import { type ValueShapeFieldDef } from '@objectstack/spec/data';
+import type { FieldContainerLike } from './predicate-record.js';
+/**
+ * Look one field def up in either container shape the metadata API serves.
+ *
+ * The pair is the one {@link FieldContainerLike} names: the Record keyed by
+ * field name, and the array of defs carrying their own `name`. A reader that
+ * knows only one of them silently answers "no such field" for the other — and
+ * "no such field" here means "single-valued", which is this card's own bug
+ * spelled as a default.
+ */
+export declare function parentRelationshipFieldDef(fields: FieldContainerLike, fieldName: string | undefined): ValueShapeFieldDef | undefined;
+/**
+ * Does this relationship field store MANY parent ids rather than one?
+ *
+ * The seam's verdict, exposed on its own because a caller sometimes needs the
+ * ANSWER without the condition — the raw-URL related-list path, whose
+ * `filter[<field>]=<value>` grammar has no membership operator, has to know
+ * the arity in order to REFUSE. Deriving it a second time at that call site is
+ * how the two compilers this module exists to merge came about, so it is
+ * derived once here and read from both shapes below.
+ */
+export declare function isMultiValueRelationship(fields: FieldContainerLike, fieldName: string | undefined): boolean;
+/**
+ * The parent-relationship condition, compiled to match the field's ARITY.
+ *
+ *   - single-valued → `{ [relationshipField]: parentId }` — equality, byte for
+ *     byte what both surfaces have always sent;
+ *   - `multiple: true` (per the spec predicate) →
+ *     `{ [relationshipField]: { $contains: parentId } }` — MEMBERSHIP, because
+ *     the stored value is an ARRAY of ids and equality asks whether that whole
+ *     array IS one id. `$contains` is the spelling the drivers execute for it,
+ *     the one `driver-sql` names in the `400 INVALID_FILTER` it answers the
+ *     equality form with.
+ *
+ * The author never writes either: they named a relationship, and its storage
+ * form is the renderer's business.
+ *
+ * The return value is the plain MongoDB-style object both call sites have
+ * always put on the wire, NOT a lowered ObjectQL AST. That is deliberate: with
+ * nothing else declared the query must stay byte-identical to what it was, and
+ * a freshly lowered AST would mean the same thing, be invisible on screen, and
+ * break every caller pinning the wire. Composition with a list's own declared
+ * scope stays the caller's step, through `mergeFilterNodes`.
+ *
+ * @param relationshipField  The child field pointing back at the parent.
+ * @param parentId           The parent record's primary key value.
+ * @param fields             The CHILD object's field defs (`objectSchema.fields`),
+ *                           in either served shape. Without them the condition
+ *                           compiles to equality — the historical wire, and the
+ *                           only answer available to a caller that cannot see
+ *                           the metadata. A caller that CAN see it must pass it.
+ */
+export declare function composeParentScopeFilter(relationshipField: string, parentId: string | number, fields?: FieldContainerLike): Record<string, unknown>;

package/dist/utils/parent-scope.js

@@ -0,0 +1,140 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * The parent-relationship condition a detail-page related list is scoped by —
+ * compiled ONCE, here, for every surface that asks the question.
+ *
+ * ## Why this is a seam and not a helper
+ *
+ * A related list asks its backend "which children belong to this parent?" from
+ * two places: the ROW query (`RelatedList`) and the tab-badge count probe
+ * (`RelatedCountStore`). Those two used to compile the condition separately,
+ * and objectui#8882 is what that costs: objectui#7299 taught the ROW side to
+ * compile by the relationship field's ARITY, the BADGE side kept sending bare
+ * equality, and on a multi-value relationship the page then rendered rows above
+ * a tab with no count at all — two implementations of one question, drifted.
+ *
+ * Patching the second copy to match the first would leave two copies. So the
+ * condition has one implementation, and both callers import it.
+ *
+ * ## The rule itself is not invented here
+ *
+ * The arity verdict is `@objectstack/spec/data`'s own `isMultiValueField`. That
+ * matters more here than anywhere: this function chooses `$contains` vs `=` and
+ * every surface that asks the question now reads that one choice, so two
+ * readers of one question disagreeing — the entire defect class — cannot
+ * recur INSIDE this repository. The spec's rule is BROADER than an eyeballed
+ * `multiple === true` in both directions — `multiselect` / `checkboxes` /
+ * `tags` persist an array with no flag at all, and `multiple: true` is INERT on
+ * a type outside the spec's multi-capable set (`master_detail`, say) — so a
+ * local approximation is wrong in both directions, not merely incomplete.
+ *
+ * ⛔ Do not add a local arity rule at any call site, however small, and ⛔ do
+ * not widen this function to accept an arity the caller computed: the parameter
+ * it takes is METADATA, and the verdict is drawn from it here.
+ *
+ * ## ⚠️ The STORAGE side does not read this predicate — the two rules DIVERGE
+ *
+ * This header used to say `isMultiValueField` is "the same predicate the driver
+ * that executes the query decides on". It is not, and the difference is
+ * observable (objectui#8937). Measured on objectstack `origin/main`,
+ * `driver-sql` gates the equality family on its own STORAGE question,
+ * `isJsonField`: a column is JSON when the field's type is in that driver's
+ * `JSON_COLUMN_TYPES` — the spec's `STRUCTURED_JSON_TYPES` and
+ * `MULTI_OPTION_TYPES`, plus the driver-internal `object` / `array` aliases —
+ * OR when `multiple` is merely TRUTHY, on ANY type; a single-value media type
+ * answers from the ADR-0104 dual-encoding window instead. The spec's predicate
+ * is `MULTI_OPTION_TYPES.has(type) || (MULTI_CAPABLE_TYPES.has(type) &&
+ * multiple === true)`.
+ *
+ * ⇒ They diverge for a type OUTSIDE `MULTI_CAPABLE_TYPES` carrying
+ * `multiple: true` (`master_detail` / `tree` / `text`): the spec says
+ * single-valued, so this seam compiles `=`, while the driver stores a JSON
+ * column and refuses `=` with the same `400 INVALID_FILTER` objectui#7299 was
+ * filed for. That is a KNOWN divergence and ⛔ not a regression — both
+ * surfaces sent `=` for that shape before objectui#7299 and objectui#8882 too.
+ *
+ * ⛔ Do NOT close it by widening the predicate here: which of the two rules is
+ * right is an upstream question, filed as objectstack#17469 (enforce-or-align),
+ * and this seam is deliberately not blocked on it. Widening on this side would
+ * move the disagreement across the wire rather than end it, and would make the
+ * ONE compiler this module exists to be disagree with the spec it delegates to.
+ * The divergence is re-derived from the installed spec on every run by
+ * `relatedListParentScopeResidue-8937.test.ts`, so this section reddens when the
+ * spec side moves.
+ */
+import { isMultiValueField } from '@objectstack/spec/data';
+/**
+ * Look one field def up in either container shape the metadata API serves.
+ *
+ * The pair is the one {@link FieldContainerLike} names: the Record keyed by
+ * field name, and the array of defs carrying their own `name`. A reader that
+ * knows only one of them silently answers "no such field" for the other — and
+ * "no such field" here means "single-valued", which is this card's own bug
+ * spelled as a default.
+ */
+export function parentRelationshipFieldDef(fields, fieldName) {
+    if (!fieldName || !fields || typeof fields !== 'object')
+        return undefined;
+    const def = Array.isArray(fields)
+        ? fields.find((f) => f?.name === fieldName)
+        : fields[fieldName];
+    if (!def || typeof def !== 'object')
+        return undefined;
+    // `type` is the one member the spec's predicate reads besides `multiple`; a
+    // def without it answers `false` through both of the predicate's set lookups,
+    // which is the right answer for a field whose type nobody declared.
+    return def;
+}
+/**
+ * Does this relationship field store MANY parent ids rather than one?
+ *
+ * The seam's verdict, exposed on its own because a caller sometimes needs the
+ * ANSWER without the condition — the raw-URL related-list path, whose
+ * `filter[<field>]=<value>` grammar has no membership operator, has to know
+ * the arity in order to REFUSE. Deriving it a second time at that call site is
+ * how the two compilers this module exists to merge came about, so it is
+ * derived once here and read from both shapes below.
+ */
+export function isMultiValueRelationship(fields, fieldName) {
+    const def = parentRelationshipFieldDef(fields, fieldName);
+    return def !== undefined && isMultiValueField(def);
+}
+/**
+ * The parent-relationship condition, compiled to match the field's ARITY.
+ *
+ *   - single-valued → `{ [relationshipField]: parentId }` — equality, byte for
+ *     byte what both surfaces have always sent;
+ *   - `multiple: true` (per the spec predicate) →
+ *     `{ [relationshipField]: { $contains: parentId } }` — MEMBERSHIP, because
+ *     the stored value is an ARRAY of ids and equality asks whether that whole
+ *     array IS one id. `$contains` is the spelling the drivers execute for it,
+ *     the one `driver-sql` names in the `400 INVALID_FILTER` it answers the
+ *     equality form with.
+ *
+ * The author never writes either: they named a relationship, and its storage
+ * form is the renderer's business.
+ *
+ * The return value is the plain MongoDB-style object both call sites have
+ * always put on the wire, NOT a lowered ObjectQL AST. That is deliberate: with
+ * nothing else declared the query must stay byte-identical to what it was, and
+ * a freshly lowered AST would mean the same thing, be invisible on screen, and
+ * break every caller pinning the wire. Composition with a list's own declared
+ * scope stays the caller's step, through `mergeFilterNodes`.
+ *
+ * @param relationshipField  The child field pointing back at the parent.
+ * @param parentId           The parent record's primary key value.
+ * @param fields             The CHILD object's field defs (`objectSchema.fields`),
+ *                           in either served shape. Without them the condition
+ *                           compiles to equality — the historical wire, and the
+ *                           only answer available to a caller that cannot see
+ *                           the metadata. A caller that CAN see it must pass it.
+ */
+export function composeParentScopeFilter(relationshipField, parentId, fields) {
+    const multi = isMultiValueRelationship(fields, relationshipField);
+    return { [relationshipField]: multi ? { $contains: parentId } : parentId };
+}

package/dist/utils/predicate-fields.d.ts

@@ -32,7 +32,10 @@
  * predicate.)
  *
  * Since objectstack#8018 the same reader also carries the non-predicate row keys
- * a view's actions read — today just `recordIdField`. The name kept the
+ * a view's actions read: `recordIdField`, since objectui#10277 the field a
+ * `defaultFromRow` param seeds from and the `{field}` tokens of an action's
+ * `target`, and since objectui#10404 the fields an `undoable` action writes,
+ * whose prior values the Undo capture reads off the row. The name kept the
  * "predicate" spelling because the mechanism is identical (harvest a name, gate
  * it against the declared fields, add it to `$select`); see
  * {@link listViewPredicates} for what is in the set and why.
@@ -85,24 +88,54 @@ export declare function collectPredicateFieldRefs(predicates: readonly unknown[]
  * kebab (custom defs AND the built-in Edit/Delete overrides), the selection bar,
  * and the object's declared actions.
  *
- * Most entries are predicates. Two are not, and both are spelled as a synthetic
+ * Most entries are predicates. Five are not, and all are spelled as a synthetic
  * `record.<name>` so the one harvester handles them: conditional formatting's
- * native `{ field, operator, value }` shape, and an action's `recordIdField`
- * (objectstack#8018). The `recordIdField` case is the same *class* of bug the
- * predicate harvest exists to close, one surface over — the action runtime reads
+ * native `{ field, operator, value }` shape, an action's `recordIdField`
+ * (objectstack#8018), the field each `defaultFromRow` param seeds from, each
+ * `{field}` token of the action's `target` (both objectui#10277), and the fields
+ * an `undoable` action writes (objectui#10404). The
+ * `recordIdField` case is the same *class* of bug the predicate harvest exists
+ * to close, one surface over — the action runtime reads
  * `rowRecord[action.recordIdField]` to seed `recordIdParam`, so a key outside the
  * listView columns arrived absent and the injection was silently skipped, which
  * turns a record-scoped mutation into one that names no record while still
  * reporting success. The default (`id`) is already projected unconditionally, so
  * only an explicit declaration adds anything here.
  *
- * A `recordIdField` that is not a bare identifier is dropped here, and one naming
- * a field the object does not declare is dropped by the caller's
- * `isProjectableField` guard. Both drops are the safe direction: such a name is
- * not a column anywhere, and an unknown key in `$select` is not ignored by every
- * backend. The identifier gate is not decoration — without it the harvester's
- * regex would read a PREFIX of a malformed name (`record.not a field` → `not`)
- * and contribute a plausible wrong field instead of nothing.
+ * The last two are the same class again, and they were silent in the same way.
+ * `resolveActionParam` seeds a `defaultFromRow` param only when the row HAS the
+ * key (an own-property check), so an absent key opened the param dialog with the
+ * field blank; and the console's `api` handler fills a `{field}` token from the
+ * row, so an absent key put an empty path segment into the URL. The key a param
+ * seeds from is `field ?? name` — the runtime's precedence, not the param's
+ * payload name — and the token grammar is the handler's own. Neither is
+ * narrowed by the action's `type`, for the asymmetry stated below: an extra
+ * column costs bytes.
+ *
+ * The written fields are the same class once more, and the worst of them,
+ * because what went wrong was a write. The Undo capture of an `undoable` update
+ * reads each written field's prior value off the row; on a projected row a
+ * written field no column shows was absent, the capture recorded `null`, and
+ * Undo then wrote `null` over the stored value it existed to restore. The
+ * written keys are `patch`, each param's collected key and `bodyExtra` (see
+ * `undoableWrittenKeys`). This one IS narrowed, to `undoable`, and not for
+ * cost: the capture is the only reader of a written field's prior value, and it
+ * runs only under `undoable`, so without it the row reads none of these keys.
+ *
+ * A `recordIdField`, param key or written key that is not a bare identifier is
+ * dropped here
+ * (a `target` token is one by construction of its grammar), and a name the
+ * object does not declare is dropped by the caller's `isProjectableField`
+ * guard. Both drops are the safe direction: such a name is not a column
+ * anywhere, and an unknown key in `$select` is not ignored by every backend.
+ * The identifier gate is not decoration — without it the harvester's regex would
+ * read a PREFIX of a malformed name (`record.not a field` → `not`) and
+ * contribute a plausible wrong field instead of nothing.
+ *
+ * ⛔ Harvesting is not a read grant. Every name here is a CANDIDATE: each
+ * consumer still passes it through its own field-level read filter before it
+ * reaches `$select`, so a field the principal may not read is not requested
+ * because an action names it.
  *
  * `objectActions` is deliberately the object's WHOLE action set rather than
  * only the ones this view promotes. Narrowing it would mean re-running the

package/dist/utils/predicate-fields.js

@@ -32,7 +32,10 @@
  * predicate.)
  *
  * Since objectstack#8018 the same reader also carries the non-predicate row keys
- * a view's actions read — today just `recordIdField`. The name kept the
+ * a view's actions read: `recordIdField`, since objectui#10277 the field a
+ * `defaultFromRow` param seeds from and the `{field}` tokens of an action's
+ * `target`, and since objectui#10404 the fields an `undoable` action writes,
+ * whose prior values the Undo capture reads off the row. The name kept the
  * "predicate" spelling because the mechanism is identical (harvest a name, gate
  * it against the declared fields, add it to `$select`); see
  * {@link listViewPredicates} for what is in the set and why.
@@ -88,6 +91,73 @@ const RECORD_REF = /\b(?:record|data)\.([A-Za-z_][A-Za-z0-9_]*)/g;
  * declaration contributes nothing instead of contributing a plausible wrong name.
  */
 const BARE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * A `{field}` token in an action's `target` — the grammar the console's `api`
+ * handler (`useConsoleActionRuntime` in `@object-ui/app-shell`) substitutes from
+ * the row record, spelled exactly as that handler spells it, so the harvest
+ * reads the same tokens it fills. The capture is a bare identifier by
+ * construction: a dotted path (`{owner.name}`), an expression (`{a + b}`) and
+ * the runner's own `${param.X}` / `${ctx.X}` scopes all fall outside it and
+ * match nothing here — this grammar does not read them off the row, so they owe
+ * the projection nothing.
+ */
+const TARGET_ROW_TOKEN = /\{([a-z_][a-z0-9_]*)\}/gi;
+/**
+ * The row key a `defaultFromRow` param seeds its value from — `field` wins,
+ * because row data is keyed by object field; `name` is the fallback. The same
+ * precedence `resolveActionParam` (`@object-ui/app-shell`) reads, which is the
+ * point: the projection must carry the key the runtime looks up, not the
+ * param's payload name. `remove_team_member` seeds `teamId` from `team_id`.
+ */
+function defaultFromRowKey(param) {
+    if (!param || typeof param !== 'object')
+        return undefined;
+    const p = param;
+    if (!p.defaultFromRow)
+        return undefined;
+    return p.field ?? p.name;
+}
+/**
+ * The keys an `undoable` action WRITES, which are the keys its Undo capture
+ * reads off the row (objectui#10404). Returned unfiltered; the caller applies
+ * the identifier gate.
+ *
+ * Each source is the one a writer actually merges into the written set:
+ *
+ *  - `patch`: the static field values of `operation: 'update'`, merged under the
+ *    collected params (`ActionRunner`'s `executeUpdateOperation`);
+ *  - each param's COLLECTED key, `name ?? field`: the key the param dialog
+ *    stores its answer under (`paramName` in `app-shell`'s
+ *    `resolveActionParams`). This is the opposite precedence to
+ *    {@link defaultFromRowKey} on purpose: that one asks which row key a value
+ *    is READ from, this one asks which key a value is WRITTEN under, and the
+ *    capture looks the written key up on the row;
+ *  - `bodyExtra`: the static body the console's generic `api` handler merges
+ *    over the params before it writes (`useConsoleActionRuntime`).
+ *
+ * `recordId` is left out: both writers read it as the record's address and
+ * strip it from the written set, so no capture ever looks it up.
+ *
+ * A key the harvest cannot make the row carry (undeclared, or a field the
+ * principal may not read) is not rescued here. The capture refuses to invent a
+ * prior value for it instead, and offers no Undo.
+ */
+function undoableWrittenKeys(def) {
+    const keys = [];
+    for (const bag of [def.patch, def.bodyExtra]) {
+        if (bag && typeof bag === 'object' && !Array.isArray(bag))
+            keys.push(...Object.keys(bag));
+    }
+    if (Array.isArray(def.params)) {
+        for (const param of def.params) {
+            if (!param || typeof param !== 'object')
+                continue;
+            const p = param;
+            keys.push(p.name ?? p.field);
+        }
+    }
+    return keys.filter((key) => key !== 'recordId');
+}
 /** Pull the CEL source out of any of the shapes a predicate is authored in. */
 function predicateSource(pred) {
     if (typeof pred === 'string')
@@ -139,24 +209,54 @@ export function collectPredicateFieldRefs(predicates) {
  * kebab (custom defs AND the built-in Edit/Delete overrides), the selection bar,
  * and the object's declared actions.
  *
- * Most entries are predicates. Two are not, and both are spelled as a synthetic
+ * Most entries are predicates. Five are not, and all are spelled as a synthetic
  * `record.<name>` so the one harvester handles them: conditional formatting's
- * native `{ field, operator, value }` shape, and an action's `recordIdField`
- * (objectstack#8018). The `recordIdField` case is the same *class* of bug the
- * predicate harvest exists to close, one surface over — the action runtime reads
+ * native `{ field, operator, value }` shape, an action's `recordIdField`
+ * (objectstack#8018), the field each `defaultFromRow` param seeds from, each
+ * `{field}` token of the action's `target` (both objectui#10277), and the fields
+ * an `undoable` action writes (objectui#10404). The
+ * `recordIdField` case is the same *class* of bug the predicate harvest exists
+ * to close, one surface over — the action runtime reads
  * `rowRecord[action.recordIdField]` to seed `recordIdParam`, so a key outside the
  * listView columns arrived absent and the injection was silently skipped, which
  * turns a record-scoped mutation into one that names no record while still
  * reporting success. The default (`id`) is already projected unconditionally, so
  * only an explicit declaration adds anything here.
  *
- * A `recordIdField` that is not a bare identifier is dropped here, and one naming
- * a field the object does not declare is dropped by the caller's
- * `isProjectableField` guard. Both drops are the safe direction: such a name is
- * not a column anywhere, and an unknown key in `$select` is not ignored by every
- * backend. The identifier gate is not decoration — without it the harvester's
- * regex would read a PREFIX of a malformed name (`record.not a field` → `not`)
- * and contribute a plausible wrong field instead of nothing.
+ * The last two are the same class again, and they were silent in the same way.
+ * `resolveActionParam` seeds a `defaultFromRow` param only when the row HAS the
+ * key (an own-property check), so an absent key opened the param dialog with the
+ * field blank; and the console's `api` handler fills a `{field}` token from the
+ * row, so an absent key put an empty path segment into the URL. The key a param
+ * seeds from is `field ?? name` — the runtime's precedence, not the param's
+ * payload name — and the token grammar is the handler's own. Neither is
+ * narrowed by the action's `type`, for the asymmetry stated below: an extra
+ * column costs bytes.
+ *
+ * The written fields are the same class once more, and the worst of them,
+ * because what went wrong was a write. The Undo capture of an `undoable` update
+ * reads each written field's prior value off the row; on a projected row a
+ * written field no column shows was absent, the capture recorded `null`, and
+ * Undo then wrote `null` over the stored value it existed to restore. The
+ * written keys are `patch`, each param's collected key and `bodyExtra` (see
+ * `undoableWrittenKeys`). This one IS narrowed, to `undoable`, and not for
+ * cost: the capture is the only reader of a written field's prior value, and it
+ * runs only under `undoable`, so without it the row reads none of these keys.
+ *
+ * A `recordIdField`, param key or written key that is not a bare identifier is
+ * dropped here
+ * (a `target` token is one by construction of its grammar), and a name the
+ * object does not declare is dropped by the caller's `isProjectableField`
+ * guard. Both drops are the safe direction: such a name is not a column
+ * anywhere, and an unknown key in `$select` is not ignored by every backend.
+ * The identifier gate is not decoration — without it the harvester's regex would
+ * read a PREFIX of a malformed name (`record.not a field` → `not`) and
+ * contribute a plausible wrong field instead of nothing.
+ *
+ * ⛔ Harvesting is not a read grant. Every name here is a CANDIDATE: each
+ * consumer still passes it through its own field-level read filter before it
+ * reaches `$select`, so a field the principal may not read is not requested
+ * because an action names it.
  *
  * `objectActions` is deliberately the object's WHOLE action set rather than
  * only the ones this view promotes. Narrowing it would mean re-running the
@@ -191,6 +291,31 @@ export function listViewPredicates(view) {
             if (typeof d.recordIdField === 'string' && BARE_IDENTIFIER.test(d.recordIdField)) {
                 preds.push(`record.${d.recordIdField}`);
             }
+            // A `defaultFromRow` param's seed field and the `{field}` tokens of the
+            // action's `target` (objectui#10277) — two more row keys the runtime
+            // READS, by the same rule and the same identifier gate.
+            if (Array.isArray(d.params)) {
+                for (const param of d.params) {
+                    const key = defaultFromRowKey(param);
+                    if (typeof key === 'string' && BARE_IDENTIFIER.test(key))
+                        preds.push(`record.${key}`);
+                }
+            }
+            if (typeof d.target === 'string') {
+                TARGET_ROW_TOKEN.lastIndex = 0;
+                for (let m = TARGET_ROW_TOKEN.exec(d.target); m; m = TARGET_ROW_TOKEN.exec(d.target)) {
+                    preds.push(`record.${m[1]}`);
+                }
+            }
+            // The fields an `undoable` action writes (objectui#10404): its Undo
+            // capture reads each one's prior value off the row. Same rule, same
+            // identifier gate.
+            if (d.undoable) {
+                for (const key of undoableWrittenKeys(d)) {
+                    if (typeof key === 'string' && BARE_IDENTIFIER.test(key))
+                        preds.push(`record.${key}`);
+                }
+            }
         }
     }
     for (const override of Object.values(view.userActions ?? {})) {

package/dist/utils/record-color.d.ts

@@ -0,0 +1,75 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Resolve the colour a record's value stands for, off the field's own metadata.
+ *
+ * ## Why this is shared (objectui#7243)
+ *
+ * `colorField` is one authored key — `gantt.colorField`, `calendar.colorField`,
+ * `timeline.colorField` — and it used to mean three different things:
+ *
+ *   - `plugin-timeline` resolved the field's option `color` (correct);
+ *   - `plugin-calendar` passed the raw value on to a deterministic hash, so the
+ *     colour the author declared on the option was never consulted;
+ *   - `plugin-gantt` passed the raw value straight into `backgroundColor`, so
+ *     `colorField: 'status'` emitted `backgroundColor: "open"` — not a colour.
+ *     The browser dropped the declaration and every bar rendered identically,
+ *     which made DECLARING the documented key strictly worse than omitting it.
+ *
+ * The timeline's resolver is lifted here verbatim so all three answer the same
+ * question the same way. What lives here is the part that is genuinely common —
+ * the two rungs that depend only on the field metadata and the stored value:
+ *
+ *   1. the field's own option `color` for that value;
+ *   2. the value itself when it already IS a CSS colour literal.
+ *
+ * The LAST rung deliberately stays with each caller, because each one has a
+ * different right answer for "a value that is neither": the gantt derives a
+ * semantic token hex (a bar must be painted), the calendar hashes onto its
+ * theme-aware 8-stop class palette (a soft tint, not a solid fill), and the
+ * timeline draws its default marker variant. Pulling those together would be a
+ * repaint of existing views, not a bug fix.
+ *
+ * ## Keyed by option `value` only
+ *
+ * Deliberately NOT `buildOptionColorMap` (`./chart-series.ts`), which keys by
+ * value AND display label: that one reads dataset ROWS, where the server may
+ * have resolved a select dimension to its label. These callers read RECORDS,
+ * where `record[colorField]` is the stored value. Keying by label as well would
+ * colour a record whose stored value happens to collide with another option's
+ * label — a tolerance nothing here needs, and one the timeline never had.
+ */
+/** One entry of a select-like field's `options`, as far as colour is concerned. */
+export interface FieldColorOption {
+    value?: unknown;
+    color?: unknown;
+}
+/** The slice of a field definition this resolver reads. */
+export interface FieldColorDefinition {
+    options?: unknown;
+}
+/** Does this string already name a colour the DOM can paint? */
+export declare function isColorLiteral(value: string): boolean;
+/**
+ * Build a `value -> option colour` lookup from a field definition's `options`.
+ * Returns an empty map for a field with no options, so callers need no guard.
+ */
+export declare function buildFieldColorMap(fieldDef: FieldColorDefinition | undefined | null): Record<string, string>;
+/**
+ * Build the per-field colour resolver: rung 1 (option colour) then rung 2 (the
+ * value is already a colour literal), else `undefined` so the caller runs its
+ * own last rung.
+ *
+ * A factory rather than a plain function because callers resolve one field
+ * across every row of a view — the option map is built once, not per record.
+ *
+ * @param fieldDef `objectSchema.fields[colorField]`, or `undefined` when the
+ *   view has no schema in hand (an inline-data or `api`-provider view). With no
+ *   options, rung 1 is a no-op and rung 2 still answers for literal colours.
+ */
+export declare function createFieldColorResolver(fieldDef: FieldColorDefinition | undefined | null): (value: unknown) => string | undefined;