@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/drill-down.d.ts

@@ -89,3 +89,81 @@ export declare function computeDrillFilter(config: DrillDownConfig | undefined,
 export declare function resolveDrillTitle(config: DrillDownConfig | undefined, event: DrillEvent, fallback?: string): string;
 /** Whether drill-down is enabled on a config (treats `{}` as enabled too). */
 export declare function isDrillEnabled(config: DrillDownConfig | undefined): boolean;
+/**
+ * Compose a widget's OWN filter with the filter a drill click derived, into the
+ * one filter the drilled list is scoped by.
+ *
+ * ## The rule: `widget.filter ∧ drill.filter`
+ *
+ * The two are independent filter SOURCES and a drill must satisfy BOTH. The
+ * widget's filter is what scopes the chart; the click context only says WHICH
+ * bucket of that scope the user asked to see. So a drill may narrow the widget's
+ * scope and may never widen it — which makes the composition a conjunction, not
+ * a merge and emphatically not a spread.
+ *
+ * ⛔ The rule is NOT invented here. It is the contract {@link mergeFilterNodes}
+ * already states — "combine filter sources under a single `and`, each as its OWN
+ * child" — the sink every other multi-source filter in this repo goes through
+ * (`ObjectView`, `RelatedList`, `LineItemsPanel`, `RecordPickerDialog`,
+ * `ElementDataSourceGate`, `buildEffectiveFilter`). This function only applies
+ * it at the drill seam and names it, so the answer is in one place rather than
+ * re-derived per widget.
+ *
+ * ## Why the two arms needed a sink at all (objectui#8944)
+ *
+ * `ObjectChartSchema.filter` admits BOTH a spec `FilterArray`
+ * (`[['stage','=','won']]`) and the ObjectQL `$filter` object
+ * (`{ close_date: { $gte } }`), because both are read — both are forwarded
+ * verbatim to `ds.aggregate` / `ds.find`. The drill seam used to compose them by
+ * SPREADING the widget's filter into an object literal, which is correct for the
+ * object arm and silent nonsense for the array arm: spreading `[['stage','=',
+ * 'won']]` yields the index key `{ '0': ['stage','=','won'] }`, so the widget's
+ * own conditions were replaced by a key the query layer ignores and the drilled
+ * list showed rows the chart itself was scoped to exclude. `toFilterNode` (via
+ * `mergeFilterNodes`) already lowers all three shapes in circulation, so routing
+ * the pair through it is what makes the array arm survive.
+ *
+ * ## Why the result is lowered back to the object dialect
+ *
+ * {@link mergeFilterNodes} answers in the ObjectQL AST
+ * (`['and', <widget>, <drill>]`). Both drill sinks take the `FilterCondition`
+ * OBJECT dialect instead — the drawer hands the value to `object-data-table`'s
+ * `filter` (which becomes `$filter`), and `DrillNavigationContext.openRecordList`
+ * declares `Record<string, unknown>` and serializes it to `filter[...]` URL
+ * params. `parseFilterAST` is the spec's single lowering sink between the two
+ * dialects, so it is what converts, rather than a second local translation.
+ *
+ * ⭐ A lone surviving source lowers back to exactly the flat object the spread
+ * produced (`{ stage: 'won' }`), so a chart with no filter of its own drills
+ * identically to before; only a genuinely composed pair gains the `$and`.
+ *
+ * Returns `undefined` when neither source carries anything, so callers can omit
+ * the key rather than send an empty filter.
+ *
+ * ⚠️ Refusals are the sink's, not this seam's: `mergeFilterNodes` rejects a
+ * comparand the wire would also reject (a bare array on `=`, a `RegExp`) with
+ * the `INVALID_FILTER` / 400 envelope. Such a filter already fails the widget's
+ * OWN query for the same reason, so the drill and the chart now agree instead of
+ * the drill quietly sending something the chart could not.
+ *
+ * ## One refusal type out of this seam (objectui#10789)
+ *
+ * The seam has TWO refusing steps, and they used to throw two different
+ * things. `mergeFilterNodes` throws a {@link FilterOperatorError}. The spec's
+ * `parseFilterAST`, which judges comparand shapes the converter passes
+ * through, throws a plain `Error` that carries the same envelope as own
+ * properties: `code: 'INVALID_FILTER'` and `status: 400`. An array-dialect
+ * widget filter holds no rule objects, so the converter never judges it, and
+ * `[['stage', 'in', 'won']]` (a scalar on a list operator) is refused only
+ * there. So is the object spelling `{ stage: { $in: 'won' } }`.
+ *
+ * Every caller catches the refusal as a `FilterOperatorError`: the chart,
+ * pivot and dataset drills report it and open nothing (never a filter-less
+ * drill). So the spec's refusal is re-raised here AS one, with its message
+ * verbatim and the same `INVALID_FILTER` / 400 envelope, rather than taught to
+ * each caller as a second shape. Only an error whose `code` is
+ * `INVALID_FILTER` is re-raised; anything else from `parseFilterAST` is a
+ * defect rather than a statement about the author's filter, and passes
+ * through untouched.
+ */
+export declare function composeDrillFilter(widgetFilter: unknown, drillFilter: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/dist/utils/drill-down.js

@@ -21,6 +21,8 @@
  * The helpers are intentionally protocol-agnostic — any caller can
  * synthesize an `event` object and rely on the same defaults / templating.
  */
+import { parseFilterAST } from '@objectstack/spec/data';
+import { FilterOperatorError, mergeFilterNodes } from './filter-converter.js';
 const TEMPLATE = /\$\{event\.([a-zA-Z0-9_]+)\}/g;
 /**
  * Substitute `${event.x}` placeholders in a string with values from the
@@ -137,3 +139,94 @@ export function isDrillEnabled(config) {
         return false;
     return config.enabled !== false;
 }
+/**
+ * Compose a widget's OWN filter with the filter a drill click derived, into the
+ * one filter the drilled list is scoped by.
+ *
+ * ## The rule: `widget.filter ∧ drill.filter`
+ *
+ * The two are independent filter SOURCES and a drill must satisfy BOTH. The
+ * widget's filter is what scopes the chart; the click context only says WHICH
+ * bucket of that scope the user asked to see. So a drill may narrow the widget's
+ * scope and may never widen it — which makes the composition a conjunction, not
+ * a merge and emphatically not a spread.
+ *
+ * ⛔ The rule is NOT invented here. It is the contract {@link mergeFilterNodes}
+ * already states — "combine filter sources under a single `and`, each as its OWN
+ * child" — the sink every other multi-source filter in this repo goes through
+ * (`ObjectView`, `RelatedList`, `LineItemsPanel`, `RecordPickerDialog`,
+ * `ElementDataSourceGate`, `buildEffectiveFilter`). This function only applies
+ * it at the drill seam and names it, so the answer is in one place rather than
+ * re-derived per widget.
+ *
+ * ## Why the two arms needed a sink at all (objectui#8944)
+ *
+ * `ObjectChartSchema.filter` admits BOTH a spec `FilterArray`
+ * (`[['stage','=','won']]`) and the ObjectQL `$filter` object
+ * (`{ close_date: { $gte } }`), because both are read — both are forwarded
+ * verbatim to `ds.aggregate` / `ds.find`. The drill seam used to compose them by
+ * SPREADING the widget's filter into an object literal, which is correct for the
+ * object arm and silent nonsense for the array arm: spreading `[['stage','=',
+ * 'won']]` yields the index key `{ '0': ['stage','=','won'] }`, so the widget's
+ * own conditions were replaced by a key the query layer ignores and the drilled
+ * list showed rows the chart itself was scoped to exclude. `toFilterNode` (via
+ * `mergeFilterNodes`) already lowers all three shapes in circulation, so routing
+ * the pair through it is what makes the array arm survive.
+ *
+ * ## Why the result is lowered back to the object dialect
+ *
+ * {@link mergeFilterNodes} answers in the ObjectQL AST
+ * (`['and', <widget>, <drill>]`). Both drill sinks take the `FilterCondition`
+ * OBJECT dialect instead — the drawer hands the value to `object-data-table`'s
+ * `filter` (which becomes `$filter`), and `DrillNavigationContext.openRecordList`
+ * declares `Record<string, unknown>` and serializes it to `filter[...]` URL
+ * params. `parseFilterAST` is the spec's single lowering sink between the two
+ * dialects, so it is what converts, rather than a second local translation.
+ *
+ * ⭐ A lone surviving source lowers back to exactly the flat object the spread
+ * produced (`{ stage: 'won' }`), so a chart with no filter of its own drills
+ * identically to before; only a genuinely composed pair gains the `$and`.
+ *
+ * Returns `undefined` when neither source carries anything, so callers can omit
+ * the key rather than send an empty filter.
+ *
+ * ⚠️ Refusals are the sink's, not this seam's: `mergeFilterNodes` rejects a
+ * comparand the wire would also reject (a bare array on `=`, a `RegExp`) with
+ * the `INVALID_FILTER` / 400 envelope. Such a filter already fails the widget's
+ * OWN query for the same reason, so the drill and the chart now agree instead of
+ * the drill quietly sending something the chart could not.
+ *
+ * ## One refusal type out of this seam (objectui#10789)
+ *
+ * The seam has TWO refusing steps, and they used to throw two different
+ * things. `mergeFilterNodes` throws a {@link FilterOperatorError}. The spec's
+ * `parseFilterAST`, which judges comparand shapes the converter passes
+ * through, throws a plain `Error` that carries the same envelope as own
+ * properties: `code: 'INVALID_FILTER'` and `status: 400`. An array-dialect
+ * widget filter holds no rule objects, so the converter never judges it, and
+ * `[['stage', 'in', 'won']]` (a scalar on a list operator) is refused only
+ * there. So is the object spelling `{ stage: { $in: 'won' } }`.
+ *
+ * Every caller catches the refusal as a `FilterOperatorError`: the chart,
+ * pivot and dataset drills report it and open nothing (never a filter-less
+ * drill). So the spec's refusal is re-raised here AS one, with its message
+ * verbatim and the same `INVALID_FILTER` / 400 envelope, rather than taught to
+ * each caller as a second shape. Only an error whose `code` is
+ * `INVALID_FILTER` is re-raised; anything else from `parseFilterAST` is a
+ * defect rather than a statement about the author's filter, and passes
+ * through untouched.
+ */
+export function composeDrillFilter(widgetFilter, drillFilter) {
+    const merged = mergeFilterNodes(widgetFilter, drillFilter);
+    try {
+        // `FilterCondition` is the spec's object-dialect filter; the drill sinks
+        // type the same value as `Record<string, unknown>`, and this is the one
+        // seam where the two names meet.
+        return parseFilterAST(merged);
+    }
+    catch (error) {
+        if (error?.code !== 'INVALID_FILTER')
+            throw error;
+        throw new FilterOperatorError(error.message);
+    }
+}

package/dist/utils/emptiness.d.ts

@@ -0,0 +1,96 @@
+/**
+ * ObjectUI — the shared emptiness floor
+ * 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 floor under "is this value empty" (objectui#8496 — director seat,
+ * decision batch #86, 2026-09-08, option B).
+ *
+ * Exactly four members, and it never grows past them:
+ *
+ *   `null` · `undefined` · the empty string · the empty array
+ *
+ * ## What a floor IS, and what it is not
+ *
+ * It is the WEAKEST claim the surfaces below it can all make — not the answer
+ * any one of them gives. A caller does one of two things with it, and both are
+ * legitimate:
+ *
+ *  - **extends** it — `isEmptyValue(v) || <its own clause>` — when its surface
+ *    calls MORE things empty (a grid trims whitespace; a boolean column calls
+ *    every non-boolean empty);
+ *  - **declines a member** in the open — `isEmptyValue(v) && !Array.isArray(v)`
+ *    — when its surface has MEASURED that member to be a value there (a `json`
+ *    cell draws the two-character literal `[]` on purpose, objectui#8474).
+ *
+ * What is NOT legitimate is a sixth private re-spelling of these four members.
+ * That is the defect this function exists to close: `plugin-detail`'s
+ * `hasCellValue`, `RelatedList`'s `isValueEmpty`, `ObjectGallery`'s and
+ * `ObjectKanban`'s inline guards and the guard idioms across
+ * `@object-ui/fields`' cell renderers each grew their own copy, and
+ * objectui#8481 was the THIRD rediscovery of the same hole — objectui#8474 and
+ * objectui#8459 had each closed it at their own door first. A copy that agrees
+ * today stops agreeing; one definition cannot.
+ *
+ * ## ⛔ The floor never grows past those four members
+ *
+ * The ruling fixed the member list, and every candidate fifth member is a
+ * measured disagreement rather than an oversight:
+ *
+ *  - **whitespace-only strings.** `'   '` is EMPTY on `record:details` and in
+ *    `RelatedList` (objectui#8350 measured the damage a blank cell does there)
+ *    and a VALUE on the gallery, the kanban and the shared renderers. Both are
+ *    right for their surface, so the trim is an EXTENSION, not a member.
+ *  - **`{}`.** Measured as a VALUE and pinned (objectui#8474): a populated or
+ *    empty object literal is handed to a type-aware renderer that draws it, and
+ *    the shape that would sweep it in — `Object.keys(v).length === 0` — is also
+ *    true of `new Date(0)`, of a populated `Map`, of a populated `Set` and of
+ *    any class instance whose state sits behind getters.
+ *  - **`0` / `false`.** Values everywhere. `BooleanCellRenderer` keeping
+ *    `false` a value is the pinned case (objectui#8582).
+ *
+ * ## Why `@object-ui/core` and not `@object-ui/types`
+ *
+ * It is a runtime predicate, not a protocol type, so it belongs in the engine.
+ * The ruling made that conditional on a measurement — `@object-ui/fields` is
+ * the lowest consumer, and if it did not already depend on `core` the floor
+ * would have had to fall back to `types`. Measured on the implementing branch:
+ * `@object-ui/fields`' `package.json` lists `@object-ui/core` in
+ * `dependencies`, and its barrel already imports from it. No new dependency
+ * edge is created by this file, in either direction — `core` reaches no
+ * consumer, which is why exporting the helper from `@object-ui/fields` instead
+ * (option C) was refused: the gallery and the kanban would then import a
+ * `fields` helper to decide whether to call a `fields` renderer.
+ *
+ * ## "Empty" is two questions; this floor answers the half both share
+ *
+ * objectui#8496's later evidence (comment 5603203484) measured that the word
+ * has split in two on this codebase: SCALAR-MISSING (`EmptyValue`, the em-dash
+ * affordance whose accessible name is fixed) and COLLECTION-EMPTY
+ * (`EmptyDescription`, an author's own sentence). The floor serves both and
+ * does not have to choose: its four members ARE two scalar-missing members,
+ * one blank scalar and one empty collection, and no call site asks a boolean to
+ * tell those apart — each one knows statically which affordance it is drawing.
+ * ⛔ So this function is deliberately NOT the place to grow a second axis. Which
+ * COMPONENT states the emptiness is a different question, carried by
+ * objectui#8570 / objectui#8526 / objectui#8507.
+ *
+ * ## Readers
+ *
+ * `isOptionGroupGated` / `isValueStillOffered` here in `core` (this function's
+ * origin: it was written privately in `evaluator/optionRules.ts`, byte-for-byte
+ * these four members, before the ruling promoted it); `hasCellValue` and
+ * `RelatedList.isValueEmpty` in `@object-ui/plugin-detail`; `ObjectGallery`'s
+ * card-field row filter; `ObjectKanban`'s card-field loop; and the cell-renderer
+ * guards in `@object-ui/fields`.
+ *
+ * The extensions and the declensions are pinned — the assertion that each
+ * surface still answers DIFFERENTLY from the floor, not merely that the floor
+ * works — in `__tests__/emptiness-floor-8496.test.ts` here and in
+ * `emptinessFloorExtensions-8496.test.tsx` in `@object-ui/fields` and
+ * `@object-ui/plugin-detail`.
+ */
+export declare function isEmptyValue(value: unknown): boolean;

package/dist/utils/emptiness.js

@@ -0,0 +1,101 @@
+/**
+ * ObjectUI — the shared emptiness floor
+ * 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 floor under "is this value empty" (objectui#8496 — director seat,
+ * decision batch #86, 2026-09-08, option B).
+ *
+ * Exactly four members, and it never grows past them:
+ *
+ *   `null` · `undefined` · the empty string · the empty array
+ *
+ * ## What a floor IS, and what it is not
+ *
+ * It is the WEAKEST claim the surfaces below it can all make — not the answer
+ * any one of them gives. A caller does one of two things with it, and both are
+ * legitimate:
+ *
+ *  - **extends** it — `isEmptyValue(v) || <its own clause>` — when its surface
+ *    calls MORE things empty (a grid trims whitespace; a boolean column calls
+ *    every non-boolean empty);
+ *  - **declines a member** in the open — `isEmptyValue(v) && !Array.isArray(v)`
+ *    — when its surface has MEASURED that member to be a value there (a `json`
+ *    cell draws the two-character literal `[]` on purpose, objectui#8474).
+ *
+ * What is NOT legitimate is a sixth private re-spelling of these four members.
+ * That is the defect this function exists to close: `plugin-detail`'s
+ * `hasCellValue`, `RelatedList`'s `isValueEmpty`, `ObjectGallery`'s and
+ * `ObjectKanban`'s inline guards and the guard idioms across
+ * `@object-ui/fields`' cell renderers each grew their own copy, and
+ * objectui#8481 was the THIRD rediscovery of the same hole — objectui#8474 and
+ * objectui#8459 had each closed it at their own door first. A copy that agrees
+ * today stops agreeing; one definition cannot.
+ *
+ * ## ⛔ The floor never grows past those four members
+ *
+ * The ruling fixed the member list, and every candidate fifth member is a
+ * measured disagreement rather than an oversight:
+ *
+ *  - **whitespace-only strings.** `'   '` is EMPTY on `record:details` and in
+ *    `RelatedList` (objectui#8350 measured the damage a blank cell does there)
+ *    and a VALUE on the gallery, the kanban and the shared renderers. Both are
+ *    right for their surface, so the trim is an EXTENSION, not a member.
+ *  - **`{}`.** Measured as a VALUE and pinned (objectui#8474): a populated or
+ *    empty object literal is handed to a type-aware renderer that draws it, and
+ *    the shape that would sweep it in — `Object.keys(v).length === 0` — is also
+ *    true of `new Date(0)`, of a populated `Map`, of a populated `Set` and of
+ *    any class instance whose state sits behind getters.
+ *  - **`0` / `false`.** Values everywhere. `BooleanCellRenderer` keeping
+ *    `false` a value is the pinned case (objectui#8582).
+ *
+ * ## Why `@object-ui/core` and not `@object-ui/types`
+ *
+ * It is a runtime predicate, not a protocol type, so it belongs in the engine.
+ * The ruling made that conditional on a measurement — `@object-ui/fields` is
+ * the lowest consumer, and if it did not already depend on `core` the floor
+ * would have had to fall back to `types`. Measured on the implementing branch:
+ * `@object-ui/fields`' `package.json` lists `@object-ui/core` in
+ * `dependencies`, and its barrel already imports from it. No new dependency
+ * edge is created by this file, in either direction — `core` reaches no
+ * consumer, which is why exporting the helper from `@object-ui/fields` instead
+ * (option C) was refused: the gallery and the kanban would then import a
+ * `fields` helper to decide whether to call a `fields` renderer.
+ *
+ * ## "Empty" is two questions; this floor answers the half both share
+ *
+ * objectui#8496's later evidence (comment 5603203484) measured that the word
+ * has split in two on this codebase: SCALAR-MISSING (`EmptyValue`, the em-dash
+ * affordance whose accessible name is fixed) and COLLECTION-EMPTY
+ * (`EmptyDescription`, an author's own sentence). The floor serves both and
+ * does not have to choose: its four members ARE two scalar-missing members,
+ * one blank scalar and one empty collection, and no call site asks a boolean to
+ * tell those apart — each one knows statically which affordance it is drawing.
+ * ⛔ So this function is deliberately NOT the place to grow a second axis. Which
+ * COMPONENT states the emptiness is a different question, carried by
+ * objectui#8570 / objectui#8526 / objectui#8507.
+ *
+ * ## Readers
+ *
+ * `isOptionGroupGated` / `isValueStillOffered` here in `core` (this function's
+ * origin: it was written privately in `evaluator/optionRules.ts`, byte-for-byte
+ * these four members, before the ruling promoted it); `hasCellValue` and
+ * `RelatedList.isValueEmpty` in `@object-ui/plugin-detail`; `ObjectGallery`'s
+ * card-field row filter; `ObjectKanban`'s card-field loop; and the cell-renderer
+ * guards in `@object-ui/fields`.
+ *
+ * The extensions and the declensions are pinned — the assertion that each
+ * surface still answers DIFFERENTLY from the floor, not merely that the floor
+ * works — in `__tests__/emptiness-floor-8496.test.ts` here and in
+ * `emptinessFloorExtensions-8496.test.tsx` in `@object-ui/fields` and
+ * `@object-ui/plugin-detail`.
+ */
+export function isEmptyValue(value) {
+    return (value === undefined ||
+        value === null ||
+        value === '' ||
+        (Array.isArray(value) && value.length === 0));
+}

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

@@ -7,14 +7,52 @@
  */
 /**
  * Relational ("reference-bearing") field types whose stored value is a foreign
- * key into another object — and which therefore benefit from `$expand` so a
- * list / grid / detail cell can render the related record's display name
- * instead of a bare id placeholder ("—").
+ * key into another object — and which therefore benefit from `$expand`, so a
+ * response carries the related record instead of only its foreign key.
  *
  * `user` is a lookup specialised to `sys_user`: it carries the same `reference`
  * + id storage and the server resolves it through the same expand path as
  * `lookup` / `master_detail`, so a `user` column that is NOT requested for
- * expansion comes back as a raw user id and renders as "—" (objectui#2032).
+ * expansion comes back as a raw user id (objectui#2032). What a CELL then
+ * prints for that id is deliberately not stated here — see the next section.
+ *
+ * ## No rendering claim is made here, on purpose — objectui#8693
+ *
+ * Both paragraphs above used to make one: the `user` sentence ended "…and
+ * renders as '—'", and the opening one called the unexpanded cell "a bare id
+ * placeholder ('—')". Measured on `da5e4f69e` by resolving each family through
+ * `getCellRenderer` and rendering three unexpanded primitives:
+ *
+ * | unexpanded value     | `lookup` / `master_detail` / `tree` | `user`             |
+ * |----------------------|-------------------------------------|--------------------|
+ * | `'u_1'`              | `u_1`, plain truncated span         | `u_1`, same span   |
+ * | `'01HQZX9K2M4N6P8R'` | muted `—`                           | the raw ULID       |
+ * | `'Ada Lovelace'`     | `Ada Lovelace`, plain span          | the raw string     |
+ *
+ * Wrong twice over. `user` never drew the em-dash at all — `UserCellRenderer`
+ * has no resolver, no `useLookupName`, no `isLikelyOpaqueId`. And the three
+ * families that do draw it draw it ONLY for values `isLikelyOpaqueId` accepts;
+ * that qualifier is the entire content of the behaviour and the sentence never
+ * carried it, so a reader was told a human-readable id would degrade visibly
+ * when it printed as if it were a name — the defect objectui#8434 was for.
+ *
+ * It is not replaced by a corrected sentence, because a corrected sentence
+ * could not be kept true HERE. `@object-ui/core` does not depend on
+ * `@object-ui/fields` in `dependencies`, `peerDependencies` or
+ * `devDependencies` — the arrow runs the other way — so no test that can reach
+ * this file can render the cell it would describe, and nothing in this repo
+ * compares a docblock to rendered output. A replacement would be checked by
+ * whatever checked the last one: nobody. Its shelf life was measured too —
+ * while objectui#8693 was open, PR #8698 (objectui#8434) sat in the merge
+ * queue rewriting the `user` column of that very table: on its head
+ * `3692f7218` all three primitives render an unresolved-reference affordance
+ * that KEEPS the raw value. A corrected sentence would have been stale before
+ * it landed. The other three families are byte-identical on both trees.
+ *
+ * The storage claim is the half this set actually depends on, and that half IS
+ * checkable here (`__tests__/expand-fields.test.ts`, plus the identity pins
+ * below). How an unexpanded reference prints belongs next to the renderers in
+ * `@object-ui/fields`, where a test can fail.
  *
  * Note on `tree`: a self-referencing hierarchy field is a reference too, so it
  * belongs in this set; whether the backend materialises the expanded object
@@ -31,6 +69,12 @@
  * the falsification note at the end. Read the list below as the lineage of the
  * conversions, not as a census; the mechanical fact is the identity pins.
  *
+ * Re-measured for objectui#8693 on `da5e4f69e`: stale again, by FOUR. The
+ * commit that corrected the "fourth and last" claim (objectui#5874 / #6064)
+ * converged four more private copies of its own and never added them here —
+ * the last four bullets below. Re-derive before trusting it; the recipe is at
+ * the end of the list.
+ *
  * This is the reference-bearing FAMILY, not the `$expand` builder's private
  * list, and these concerns read it under several different words:
  *
@@ -43,7 +87,7 @@
  *  - the grid's bulk-action dialog — `widgetNeedsDataSource` in
  *    `packages/plugin-grid/src/components/bulkParamToField.ts`, which decides
  *    which param widget is handed the grid's `DataSource` and which param field
- *    shape carries `reference_to` / `display_field`;
+ *    shape carries `reference` / `displayField`;
  *  - the action-param dialog — `paramToField` in
  *    `packages/app-shell/src/utils/paramToField.ts`, which decides which param
  *    carries a reference target (objectui#5312);
@@ -52,7 +96,34 @@
  *  - the dashboard table's `$expand` whitelist — `computeLookupExpand` in
  *    `packages/plugin-dashboard/src/ObjectDataTable.tsx` (objectui#5692);
  *  - the dashboard's relation/link test — `isLookupType` in
- *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692).
+ *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692);
+ *  - the action-param RESOLVER (one step before `paramToField`) —
+ *    `packages/fields/src/resolveActionParams.ts` (objectui#5874; moved out of
+ *    app-shell by objectui#12105 so the bulk dialog shares it);
+ *  - the detail header's relation test — `HeaderHighlight.tsx` in
+ *    `packages/plugin-detail` (objectui#5874);
+ *  - the detail drawer's relation test — `RecordDetailDrawer.tsx` in
+ *    `packages/plugin-detail`, reading through `isExpandableFieldType`
+ *    (objectui#5874);
+ *  - the kanban board's `$expand` — `ObjectKanban.tsx` in
+ *    `packages/plugin-kanban`, reading through `buildExpandFields`
+ *    (objectui#5874).
+ *
+ * ⚠️ Re-derive rather than trust. One command, from the repo root, over the
+ * whole tree with NO pathspec. (Narrowing it to `packages/` + a `*` segment +
+ * `/src` matches ZERO files, and would drop `apps/` besides. The two-character
+ * sequence is spelled out in words here because writing it literally would end
+ * this comment.)
+ *
+ *     git grep -lE 'EXPANDABLE_FIELD_TYPES|isExpandableFieldType|buildExpandFields'
+ *
+ * 96 files on `da5e4f69e`. Drop tests, changesets and changelogs and the
+ * production readers fall into three radii, only the first of which the list
+ * above is about: this file plus 8 more naming the set directly, plus 4 more
+ * calling `isExpandableFieldType`, plus 13 more calling `buildExpandFields`.
+ * The sweep was controlled by planting a reader under `apps/console/src/` and
+ * confirming the same command found it — `apps/` holds no reader today, and a
+ * zero-hit region is otherwise indistinguishable from a blind spot.
  *
  * The third one used to be a second hand-maintained copy, and this comment used
  * to claim the set "mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`
@@ -64,10 +135,11 @@
  * (objectui#4790). The form now DERIVES from this set instead of restating it:
  *
  *     form's data-source rule  ==  EXPANDABLE_FIELD_TYPES
- *                                  + three widget-hint-only picker names
+ *                                  + the widget-hint-only picker names
  *
  * The extension is one-directional and cannot fold back into this set:
- * `object-ref` / `filter-condition` / `recipient-picker` are widget HINTS, never
+ * `object-ref` / `filter-condition` / `recipient-picker` (and the registry-name
+ * pickers `position-ref` / `permission-ref`, objectui#7611) are widget HINTS, never
  * declarable field types (`widgetHintOnly: true` in
  * `app-shell/src/utils/paramValueShape.ts`), so no object schema can produce a
  * field whose `type` is one of them.
@@ -76,7 +148,7 @@
  * of the above (`lookup` / `master_detail` / `user` — no `tree`, no pickers, and
  * for a while a fifth spelling, `owner`, that objectui#4814 retired). It now
  * derives from this set with NO extension, because the bulk dialog's params
- * cannot produce the three widget-hint names (objectui#4815):
+ * cannot produce the widget-hint names (objectui#4815):
  *
  *     bulk dialog's data-source rule  ==  EXPANDABLE_FIELD_TYPES
  *

package/dist/utils/expand-fields.js

@@ -8,14 +8,52 @@
 import { columnIdentity } from './column-identity.js';
 /**
  * Relational ("reference-bearing") field types whose stored value is a foreign
- * key into another object — and which therefore benefit from `$expand` so a
- * list / grid / detail cell can render the related record's display name
- * instead of a bare id placeholder ("—").
+ * key into another object — and which therefore benefit from `$expand`, so a
+ * response carries the related record instead of only its foreign key.
  *
  * `user` is a lookup specialised to `sys_user`: it carries the same `reference`
  * + id storage and the server resolves it through the same expand path as
  * `lookup` / `master_detail`, so a `user` column that is NOT requested for
- * expansion comes back as a raw user id and renders as "—" (objectui#2032).
+ * expansion comes back as a raw user id (objectui#2032). What a CELL then
+ * prints for that id is deliberately not stated here — see the next section.
+ *
+ * ## No rendering claim is made here, on purpose — objectui#8693
+ *
+ * Both paragraphs above used to make one: the `user` sentence ended "…and
+ * renders as '—'", and the opening one called the unexpanded cell "a bare id
+ * placeholder ('—')". Measured on `da5e4f69e` by resolving each family through
+ * `getCellRenderer` and rendering three unexpanded primitives:
+ *
+ * | unexpanded value     | `lookup` / `master_detail` / `tree` | `user`             |
+ * |----------------------|-------------------------------------|--------------------|
+ * | `'u_1'`              | `u_1`, plain truncated span         | `u_1`, same span   |
+ * | `'01HQZX9K2M4N6P8R'` | muted `—`                           | the raw ULID       |
+ * | `'Ada Lovelace'`     | `Ada Lovelace`, plain span          | the raw string     |
+ *
+ * Wrong twice over. `user` never drew the em-dash at all — `UserCellRenderer`
+ * has no resolver, no `useLookupName`, no `isLikelyOpaqueId`. And the three
+ * families that do draw it draw it ONLY for values `isLikelyOpaqueId` accepts;
+ * that qualifier is the entire content of the behaviour and the sentence never
+ * carried it, so a reader was told a human-readable id would degrade visibly
+ * when it printed as if it were a name — the defect objectui#8434 was for.
+ *
+ * It is not replaced by a corrected sentence, because a corrected sentence
+ * could not be kept true HERE. `@object-ui/core` does not depend on
+ * `@object-ui/fields` in `dependencies`, `peerDependencies` or
+ * `devDependencies` — the arrow runs the other way — so no test that can reach
+ * this file can render the cell it would describe, and nothing in this repo
+ * compares a docblock to rendered output. A replacement would be checked by
+ * whatever checked the last one: nobody. Its shelf life was measured too —
+ * while objectui#8693 was open, PR #8698 (objectui#8434) sat in the merge
+ * queue rewriting the `user` column of that very table: on its head
+ * `3692f7218` all three primitives render an unresolved-reference affordance
+ * that KEEPS the raw value. A corrected sentence would have been stale before
+ * it landed. The other three families are byte-identical on both trees.
+ *
+ * The storage claim is the half this set actually depends on, and that half IS
+ * checkable here (`__tests__/expand-fields.test.ts`, plus the identity pins
+ * below). How an unexpanded reference prints belongs next to the renderers in
+ * `@object-ui/fields`, where a test can fail.
  *
  * Note on `tree`: a self-referencing hierarchy field is a reference too, so it
  * belongs in this set; whether the backend materialises the expanded object
@@ -32,6 +70,12 @@ import { columnIdentity } from './column-identity.js';
  * the falsification note at the end. Read the list below as the lineage of the
  * conversions, not as a census; the mechanical fact is the identity pins.
  *
+ * Re-measured for objectui#8693 on `da5e4f69e`: stale again, by FOUR. The
+ * commit that corrected the "fourth and last" claim (objectui#5874 / #6064)
+ * converged four more private copies of its own and never added them here —
+ * the last four bullets below. Re-derive before trusting it; the recipe is at
+ * the end of the list.
+ *
  * This is the reference-bearing FAMILY, not the `$expand` builder's private
  * list, and these concerns read it under several different words:
  *
@@ -44,7 +88,7 @@ import { columnIdentity } from './column-identity.js';
  *  - the grid's bulk-action dialog — `widgetNeedsDataSource` in
  *    `packages/plugin-grid/src/components/bulkParamToField.ts`, which decides
  *    which param widget is handed the grid's `DataSource` and which param field
- *    shape carries `reference_to` / `display_field`;
+ *    shape carries `reference` / `displayField`;
  *  - the action-param dialog — `paramToField` in
  *    `packages/app-shell/src/utils/paramToField.ts`, which decides which param
  *    carries a reference target (objectui#5312);
@@ -53,7 +97,34 @@ import { columnIdentity } from './column-identity.js';
  *  - the dashboard table's `$expand` whitelist — `computeLookupExpand` in
  *    `packages/plugin-dashboard/src/ObjectDataTable.tsx` (objectui#5692);
  *  - the dashboard's relation/link test — `isLookupType` in
- *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692).
+ *    `packages/plugin-dashboard/src/recordFields.tsx` (objectui#5692);
+ *  - the action-param RESOLVER (one step before `paramToField`) —
+ *    `packages/fields/src/resolveActionParams.ts` (objectui#5874; moved out of
+ *    app-shell by objectui#12105 so the bulk dialog shares it);
+ *  - the detail header's relation test — `HeaderHighlight.tsx` in
+ *    `packages/plugin-detail` (objectui#5874);
+ *  - the detail drawer's relation test — `RecordDetailDrawer.tsx` in
+ *    `packages/plugin-detail`, reading through `isExpandableFieldType`
+ *    (objectui#5874);
+ *  - the kanban board's `$expand` — `ObjectKanban.tsx` in
+ *    `packages/plugin-kanban`, reading through `buildExpandFields`
+ *    (objectui#5874).
+ *
+ * ⚠️ Re-derive rather than trust. One command, from the repo root, over the
+ * whole tree with NO pathspec. (Narrowing it to `packages/` + a `*` segment +
+ * `/src` matches ZERO files, and would drop `apps/` besides. The two-character
+ * sequence is spelled out in words here because writing it literally would end
+ * this comment.)
+ *
+ *     git grep -lE 'EXPANDABLE_FIELD_TYPES|isExpandableFieldType|buildExpandFields'
+ *
+ * 96 files on `da5e4f69e`. Drop tests, changesets and changelogs and the
+ * production readers fall into three radii, only the first of which the list
+ * above is about: this file plus 8 more naming the set directly, plus 4 more
+ * calling `isExpandableFieldType`, plus 13 more calling `buildExpandFields`.
+ * The sweep was controlled by planting a reader under `apps/console/src/` and
+ * confirming the same command found it — `apps/` holds no reader today, and a
+ * zero-hit region is otherwise indistinguishable from a blind spot.
  *
  * The third one used to be a second hand-maintained copy, and this comment used
  * to claim the set "mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`
@@ -65,10 +136,11 @@ import { columnIdentity } from './column-identity.js';
  * (objectui#4790). The form now DERIVES from this set instead of restating it:
  *
  *     form's data-source rule  ==  EXPANDABLE_FIELD_TYPES
- *                                  + three widget-hint-only picker names
+ *                                  + the widget-hint-only picker names
  *
  * The extension is one-directional and cannot fold back into this set:
- * `object-ref` / `filter-condition` / `recipient-picker` are widget HINTS, never
+ * `object-ref` / `filter-condition` / `recipient-picker` (and the registry-name
+ * pickers `position-ref` / `permission-ref`, objectui#7611) are widget HINTS, never
  * declarable field types (`widgetHintOnly: true` in
  * `app-shell/src/utils/paramValueShape.ts`), so no object schema can produce a
  * field whose `type` is one of them.
@@ -77,7 +149,7 @@ import { columnIdentity } from './column-identity.js';
  * of the above (`lookup` / `master_detail` / `user` — no `tree`, no pickers, and
  * for a while a fifth spelling, `owner`, that objectui#4814 retired). It now
  * derives from this set with NO extension, because the bulk dialog's params
- * cannot produce the three widget-hint names (objectui#4815):
+ * cannot produce the widget-hint names (objectui#4815):
  *
  *     bulk dialog's data-source rule  ==  EXPANDABLE_FIELD_TYPES
  *