@object-ui/plugin-dashboard 17.5.0 → 17.7.0

package/dist/ObjectDataTable.d.ts

@@ -1,21 +1,15 @@
 import { default as React } from 'react';
+import { ObjectDataTableSchema, TableColumn } from '@object-ui/types';
+import { FieldMeta } from './recordFields.js';
 export interface ObjectDataTableProps {
-    schema: {
-        type: string;
-        objectName?: string;
-        dataProvider?: {
-            provider: string;
-            object?: string;
-        };
-        bind?: string;
-        filter?: any;
-        data?: any[];
-        columns?: any[];
-        searchable?: boolean;
-        pagination?: boolean;
-        className?: string;
-        [key: string]: any;
-    };
+    /**
+     * The `object-data-table` node — anchored to the exported schema type
+     * (objectui#6576 / #6914). The hand-rolled literal that stood here carried
+     * its own string index signature and had drifted: `drillDown` and
+     * `onRowClick` were read behind casts and declared nowhere. Both are declared
+     * on the schema type now; `bind` / `className` are inherited from `BaseSchema`.
+     */
+    schema: ObjectDataTableSchema;
     dataSource?: any;
     className?: string;
 }
@@ -25,12 +19,425 @@ interface NormalizedColumn {
     accessorKey: string;
     [key: string]: any;
 }
+/**
+ * What this widget's column producer is allowed to EMIT (objectui#6373).
+ *
+ * `enrich` below hands its result to `data-table`, whose columns slot is
+ * `DataTableSchema.columns: TableColumn[]`. It used to return
+ * `NormalizedColumn`, whose `[key: string]: any` accepts anything, so nothing
+ * checked the emit against the slot's declaration at all: `{ ...col,
+ * ...fieldMeta }` wrote SEVEN keys `TableColumn` does not declare — `name`,
+ * `label`, `options`, `referenceTo`, `format`, `currency`, `decimals`.
+ *
+ * ## ⭐ Why this is not just `: TableColumn`
+ *
+ * Measured on this program before choosing the shape: annotating the return
+ * `TableColumn` and leaving the spread in place raises NO error. TypeScript's
+ * excess-property check is a FRESHNESS check on the properties an object
+ * literal WRITES OUT; properties arriving through a spread are exempt. So the
+ * plain annotation the card suggested is blind to the exact defect the card is
+ * about — it would have type-checked the seam without enforcing it, converting
+ * a surfaced-key census into a silenced one.
+ *
+ * The `?: never` members are what make the annotation able to fail. They are
+ * ADR-0049 retirement tombstones — this repo's convention for a key that is
+ * refused rather than merely absent (`StaticTableColumn` in
+ * `@object-ui/types`, `crud.ts` `confirm`) — and they bite by ASSIGNABILITY,
+ * not freshness: `FieldMeta['label']` is `string`, which is not assignable to
+ * `undefined`, so re-introducing `{ ...fieldMeta }` here is a compile error
+ * (TS2322) naming the first offending key. Writing one out explicitly is the
+ * other error (TS2353). Both directions were run before this type was written.
+ *
+ * ## The rule, so the next producer gets the same answer
+ *
+ * A producer may write into a `TableColumn[]` slot only keys the CONSUMER of
+ * that slot reads, and the consumer's read set is MEASURED from the consumer's
+ * source, never assumed. Then: a key the consumer reads and `TableColumn`
+ * declares is written; a key the consumer reads and `TableColumn` does not
+ * declare is held as an alias only where a ruling already holds it; a key the
+ * consumer does not read is RETIRED from the emit — never declared, because
+ * declaring a key nothing reads is the same `declared != enforced` defect
+ * facing the other way (objectui#5453's forwarded `wrap` key).
+ *
+ * Measured read set of the consumer (`data-table.tsx`, comments stripped):
+ * `accessorKey`, `width`, `align`, `header`, `className`, `cellClassName`,
+ * `sortable`, `resizable`, `editable`, `type`, `cell`, `headerIcon`,
+ * `fitContent`, and `name`. Not one of `label`, `options`, `referenceTo`,
+ * `format`, `currency`, `decimals` appears — so all six retired from the
+ * emit, and this producer still SOURCES none of them from `fieldMeta`.
+ *
+ * ⚠️ Three of the six — `format`, `options`, `currency` — have since been
+ * DECLARED on `TableColumn` itself (objectui#6425, maintainer ruling
+ * 2026-08-27), so they are no longer tombstoned on this emit type: the band
+ * below derives them away the moment the declaration landed. That is not a
+ * softening of the emit rule but its other branch — an AUTHORED value now
+ * passes through `{ ...col }` as declared metadata (the cell pipeline reads
+ * it back off the authored column), while writing one out of `fieldMeta`
+ * remains retired, pinned by the runtime census in
+ * `ObjectDataTable.emitBoundary-6373.test.tsx`.
+ *
+ * Retiring them is behaviour-preserving because none of them was the live path
+ * for its own value: everything they carried is read off `fieldMeta` by the
+ * `cell` closure below, which is where this widget's type-aware rendering
+ * actually happens. That check — does the value still reach its consumer by
+ * another road? — is part of the rule, not an aside: a key with no second road
+ * is not inert, and retiring it would change behaviour.
+ *
+ * `type` is not adjudicated here. `fc62bb490` already settled it at this
+ * seam, and its fold (`normalizeTableColumnType`) stands unchanged.
+ *
+ * `name` is HELD, not retired, and not adjudicated here either: it is
+ * objectui#5120's, still open. `data-table` reads `col.accessorKey || col.name`
+ * and holds that alias deliberately, because two PUBLISHED skill guides teach a
+ * `data-table` column spelled `{ name, label }`. So this producer keeps writing
+ * it, byte for byte what it wrote before, and the hold is now DECLARED at the
+ * seam instead of arriving anonymously inside a spread. When #5120 retires the
+ * consumer alias, this member becomes a tombstone with it.
+ */
+/**
+ * ⭐ `decimals` — RETIRED from `FieldMeta` ITSELF (objectui#6625), and this
+ * hand-written tombstone is now the ONLY enforcement of that key's refusal at
+ * BOTH halves of this seam. ⛔ Do not "tidy" it away as redundant.
+ *
+ * Until objectui#6625 the key needed no tombstone: it was a `FieldMeta` member,
+ * so BOTH bands below — {@link EnrichedColumn}'s write-side tombstones
+ * (objectui#6373) and {@link UnheldFieldMetaOverrideKey}'s read-side refusal
+ * (objectui#6425) — derived it for free. Refusal by MEMBERSHIP. #6625 then
+ * retired the member (written from the schema def, read by nothing), which
+ * removed it from `keyof FieldMeta` and silently ended that enforcement at both
+ * ends. Nothing would have gone red at the moment of loss: on the read side the
+ * suite's `@ts-expect-error` would merely have turned TS2578-unused, and on the
+ * write side the hand-written pin would have gone on passing on the
+ * excess-property check alone — a pin passing because its subject stopped
+ * existing.
+ *
+ * This is the exact mirror of the rule `ObjectGrid`'s sibling tombstone
+ * records (`ObjectGridRetiredOptionsTombstone`, objectui#6425): *a pin enforced
+ * by a key's non-membership silently stops enforcing the moment the key becomes
+ * a member.* Read from this end: **a refusal DERIVED from a key's membership
+ * silently stops enforcing the moment that member is deleted.** Same seam, same
+ * blindness, opposite direction — which is why the retirement had to be
+ * re-stated by hand rather than inherited.
+ *
+ * objectui#6425's verdict is unchanged — no reader for an authored `decimals`
+ * existed then and none exists now — and so is the runtime behaviour: the value
+ * the retired `buildFieldMeta` write resolved reached nothing. Only the
+ * refusal's mechanism moves, from derived to hand-written. It is intersected
+ * into BOTH types below, because the retirement belongs to the SEAM, not to one
+ * of its two halves — the same reason `ObjectGrid` intersects its own tombstone
+ * into both its draft and its post-fold column. ⭐ A future reader for decimal
+ * places reads `scale`, never this key (objectui#6625; `NumberCellRenderer`
+ * already does).
+ */
+type ObjectDataTableRetiredDecimalsTombstone = {
+    decimals?: never;
+};
+/**
+ * ⭐ `referenceTo` — RETIRED from `FieldMeta` ITSELF (objectui#6597), the same
+ * mechanism and the same reason as {@link ObjectDataTableRetiredDecimalsTombstone}
+ * above — read that docblock for the full mechanics of why a hand-written
+ * tombstone, not the derived band, is what has to carry this refusal now that
+ * the key has left `keyof FieldMeta`.
+ *
+ * The verdict: `referenceTo` was documented by this package's README as an
+ * author-facing column override, and objectui#6425's ruling routed it to this
+ * card (⛔ "not declared as spelled") rather than deciding it, because the
+ * card that could declare or retire a HELD key cannot also be the card that
+ * MEASURES whether a real authoring story exists for it. objectui#6597 did
+ * that measurement: `LookupCellRenderer` resolves its lookup target from
+ * `field.reference_to` / `field.reference`, never `field.referenceTo`, and
+ * `computeLookupExpand` builds `$expand` from the OBJECT SCHEMA's field types,
+ * never from an authored column override — so the key reached nothing, HELD
+ * or not, pinned by the `referenceTo`-vs-`options` positive control in
+ * `ObjectDataTable.overrideSource-6425.test.tsx`. No authoring story survived
+ * the search either: `ObjectGrid`'s own relational-meta pass-through
+ * (`applyRelationalMeta`) copies `reference_to` / `reference` from the SCHEMA
+ * field def only, never from an authored override, and nothing in this repo's
+ * docs/examples/fixtures shows a table column pinning a lookup's target away
+ * from what its schema field already says. Under the maintainer's standing
+ * startup-stage rule (2026-08-27: no measured demand retires immediately,
+ * no transition window), that measurement selects RETIRE — the README line is
+ * withdrawn with it. ⭐ A future reader for the resolved reference target
+ * reads `reference` off the schema field def — the spelling
+ * `LookupCellRenderer` and `computeLookupExpand` actually use (the cell read
+ * `reference_to` too until objectui#11070 round 4) — never this key.
+ */
+type ObjectDataTableRetiredReferenceToTombstone = {
+    referenceTo?: never;
+};
+/**
+ * ⭐ `reference_to` — RETIRED from `FieldMeta` ITSELF (objectui#11070 round 4),
+ * the third key to leave that type, by the same mechanism as
+ * {@link ObjectDataTableRetiredDecimalsTombstone} and
+ * {@link ObjectDataTableRetiredReferenceToTombstone}: read either docblock for
+ * why a hand-written tombstone, not the derived band, carries the refusal once
+ * a key leaves `keyof FieldMeta`.
+ *
+ * The verdict is unchanged and is objectui#6694's: an AUTHORED column may not
+ * source a lookup's reference target, and nothing this seam emits carries it
+ * either. What changed is the key's standing. `LookupCellRenderer` read
+ * `reference_to || reference` until that round and reads `reference` alone
+ * now; the ingestion choke point no longer stamps `reference_to` and no
+ * in-repo producer writes it, so `buildFieldMeta` stopped copying it and the
+ * member went. Without this tombstone the refusal would have ended at the
+ * moment of deletion with nothing going red — the blindness the two tombstones
+ * above exist to prevent.
+ */
+type ObjectDataTableRetiredReferenceToSnakeTombstone = {
+    reference_to?: never;
+};
+/**
+ * ⭐ `display_field` — RETIRED from `FieldMeta` ITSELF (objectui#11070's
+ * text-family round), the fourth key to leave that type, by the same mechanism
+ * as the three tombstones above: read {@link ObjectDataTableRetiredDecimalsTombstone}
+ * for why a hand-written tombstone, not the derived band, carries the refusal
+ * once a key leaves `keyof FieldMeta`.
+ *
+ * The verdict is unchanged and is objectui#6694's: an AUTHORED column may not
+ * source a lookup's display pointer, and nothing this seam emits carries this
+ * spelling either. What changed is the key's standing. `LookupCellRenderer`
+ * has resolved the display pointer as `displayField || reference_field` since
+ * objectui#7155 retired its `display_field` leg, and the ingestion choke point
+ * folds a served `display_field` onto `displayField`, so `buildFieldMeta`'s
+ * copy of it reached no reader; the copy stopped and the member went. The
+ * spec spelling `displayField` is still a `FieldMeta` member, so the derived
+ * band keeps refusing it on an authored column by itself.
+ */
+type ObjectDataTableRetiredDisplayFieldSnakeTombstone = {
+    display_field?: never;
+};
+export type EnrichedColumn = TableColumn
+/** HELD alias, objectui#5120 — see above. Not declared by `TableColumn`. */
+ & {
+    name?: string;
+}
+/** RETIRED at this emit seam, objectui#6373 — derived, never hand-listed, so
+ *  a future `FieldMeta` member is tombstoned by default and has to be
+ *  adjudicated to escape. */
+ & {
+    [K in Exclude<keyof FieldMeta, keyof TableColumn | 'name'>]?: never;
+} & ObjectDataTableRetiredDecimalsTombstone & ObjectDataTableRetiredReferenceToTombstone & ObjectDataTableRetiredReferenceToSnakeTombstone & ObjectDataTableRetiredDisplayFieldSnakeTombstone;
+/**
+ * What this widget's column producer is allowed to READ off the AUTHORED
+ * column as a field-meta override (objectui#6425) — the READ half of the seam
+ * {@link EnrichedColumn} above fences on the WRITE side. objectui#6373 fenced
+ * what `enrich` emits; nothing yet fenced what it consumes.
+ *
+ * `enrich` handed `buildFieldMeta` six values taken off the authored column.
+ * Five of them — `format`, `options`, `referenceTo`, `currency`, `decimals` —
+ * were declared by neither `TableColumn` (`@object-ui/types`) nor its
+ * `TableColumnSchema` zod mirror. Three were reached through `(col as any)`;
+ * the other two through {@link NormalizedColumn}'s `[key: string]: any`, which
+ * answers `any` just as loudly without the tell. So the widget honoured an
+ * authoring vocabulary the published types refuse, and no artefact in the repo
+ * said which keys those were or why.
+ *
+ * ## The per-key ruling landed (objectui#6425, maintainer 2026-08-27)
+ *
+ * This type used to hold all five keys with ⛔ "declares nothing and retires
+ * nothing" — both branches were maintainer decisions. The ruling has since
+ * disposed of them per key, and this keyhole now CARRIES that disposition:
+ *
+ *  - `format`, `options` — DECLARED on `TableColumn` + its zod mirror
+ *    (documented AND kept; declaring is truth-maintenance). Read below at
+ *    their published types via `Pick<TableColumn, …>`.
+ *  - `currency` — DECLARED (kept in production, never promised before;
+ *    declaring makes the existing behaviour honest). Same `Pick`.
+ *  - `decimals` — RETIRED, immediately (neither promised nor kept: zero
+ *    readers measured, and the authored read below is gone). Refused by
+ *    {@link ObjectDataTableRetiredDecimalsTombstone} since objectui#6625
+ *    retired the `FieldMeta` member itself and took the key out of the derived
+ *    band's pool; the verdict is unchanged, only its mechanism moved.
+ *  - `referenceTo` — RETIRED (objectui#6597, enforce-or-remove: measured no
+ *    authoring story for a column-level reference override — see the
+ *    withdraw verdict above `ObjectDataTableRetiredReferenceToTombstone`).
+ *    Refused by that tombstone the same way `decimals` is refused by its own.
+ *
+ * The shape itself is unchanged from what objectui#6461 landed for
+ * `plugin-grid` (`ObjectGridColumnHolds` / `RetiredListColumnKey`); the
+ * identifiers differ because this producer's seam is a READ, not an emit.
+ *
+ * ## The band is DERIVED, and it bites by assignability
+ *
+ * `FieldMeta` is the override vocabulary — `buildFieldMeta`'s `overrides` is a
+ * subset of it — so it is the pool a new tolerance would come from, and the
+ * same pool {@link EnrichedColumn}'s tombstones derive from. Deriving means a
+ * NEW `FieldMeta` member is refused here on the day it is added, without
+ * anyone remembering to extend a hand-written list. (Stated without a count on
+ * purpose: it read "a seventh" while the type had eight members, and
+ * objectui#6625 and objectui#6597 have since retired two. The property is
+ * that ADDING is covered by derivation — ⚠️ REMOVING is not, which is why
+ * those cards each had to leave a hand-written tombstone behind —
+ * {@link ObjectDataTableRetiredDecimalsTombstone} and
+ * {@link ObjectDataTableRetiredReferenceToTombstone}.)
+ *
+ * ⚠️ It derives from the OVERRIDE VOCABULARY, not from the authored input
+ * type, and that difference is forced rather than stylistic. `plugin-grid`'s
+ * sibling band (`RetiredListColumnKey`, objectui#6461) is
+ * `Exclude<keyof ListColumn, …>` — it can derive from its authored type
+ * because `ListColumn` DECLARES its keys. This producer's authored type
+ * cannot: {@link NormalizedColumn} carries `[key: string]: any`, so `keyof` it
+ * is `string | number`. Measured on this program — a band built on it accepts
+ * `'totallyMadeUpKey'` as a member, so it would ban nothing at all. The pool
+ * therefore has to be the vocabulary the overrides are drawn FROM.
+ *
+ * That choice has a cost, and it is stated here rather than left to be
+ * discovered: a candidate key OUTSIDE `FieldMeta` can never land in the band.
+ * It is refused by the other half of this type instead —
+ * `AuthoredColumnOverrides` declares no index signature, so reading an
+ * unadjudicated key is TS2339 AT THE READ SITE, which is the enforcement
+ * `enrich` actually runs on (`(col as any).x` and the bag's index signature
+ * both answered `any` there). Both halves are pinned by the suite.
+ *
+ * ⚠️ Measured on this program, in both directions, before this shape was
+ * written:
+ *  - `?: never` bites by ASSIGNABILITY, not by freshness, so the refusal
+ *    survives a spread — `const s: AuthoredColumnOverrides = someBag` fails on
+ *    a source that DECLARES a banded key, and passes on one that does not.
+ *  - `accessorKey` is required here for a reason that is not decoration:
+ *    without one property in common, TypeScript's weak-type check rejects the
+ *    assignment below outright (TS2559), and a type that refuses everything
+ *    pins nothing. It is the same key {@link NormalizedColumn} already
+ *    declares required, so this makes no new claim about the authored object.
+ *
+ * ## A VIEW, not a census of the object
+ *
+ * The banded members say "this producer must not SOURCE this override from the
+ * authored column" — not "this key is absent at run time". `normalizeColumns`
+ * deliberately leaves the authored spelling in place, so a column really can
+ * carry `name` / `label`; they are refused HERE because this seam already has
+ * answers for both and they do not come from the column: `name` comes from
+ * `accessorKey` and `label` from `col.header`, which objectui#5351 made the one
+ * place the authored label is translated.
+ */
+/**
+ * The undeclared-but-live override keys this producer still holds. **None
+ * remain.** objectui#6425's ruling (maintainer, 2026-08-27) declared `format` /
+ * `options` / `currency` on `TableColumn` itself (they are read via
+ * `Pick<TableColumn, …>` below, no hold needed) and retired `decimals`
+ * outright — refused by {@link ObjectDataTableRetiredDecimalsTombstone} since
+ * objectui#6625 retired the `FieldMeta` member that used to carry it into the
+ * derived band. `referenceTo` was the last hold — objectui#6425's ruling
+ * routed it to objectui#6597 rather than deciding it (⛔ "not declared as
+ * spelled"), and that card MEASURED no authoring story for a column-level
+ * reference override, so the maintainer's standing startup-stage rule
+ * (2026-08-27: no measured demand retires immediately) picked withdraw —
+ * refused by {@link ObjectDataTableRetiredReferenceToTombstone} the same way
+ * `decimals` is refused by its own tombstone.
+ *
+ * Kept as an interface — empty rather than deleted — because it is the
+ * documented anchor a future per-key ruling holds a new key onto, the same
+ * role it played for `format` / `options` / `currency` before objectui#6425
+ * declared them and for `referenceTo` before objectui#6597 retired it.
+ */
+export interface ObjectDataTableColumnHolds {
+}
+/**
+ * The candidate keys this seam refuses — DERIVED from the override vocabulary,
+ * never hand-listed, so a future `FieldMeta` member has to be adjudicated onto
+ * {@link ObjectDataTableColumnHolds} to escape. Keys `TableColumn` declares
+ * leave the pool by declaration: `type` (its VALUE set is `fc62bb490`'s,
+ * folded below by `normalizeTableColumnType`) and, since objectui#6425's
+ * ruling, `format` / `options` / `currency`.
+ *
+ * ⚠️ `decimals` and `referenceTo` USED TO land here — that is how objectui#6425's
+ * ruling was enforced for `decimals` at the read site, and how `referenceTo`
+ * stayed HELD (neither declared nor refused) until objectui#6597 ruled. Neither
+ * can any more: objectui#6625 and objectui#6597 each retired the `FieldMeta`
+ * member itself, so both keys are out of this Exclude's POOL rather than out of
+ * its exclusion list, and a derived band cannot refuse a key that is not in
+ * what it derives from. Their refusals are carried by
+ * {@link ObjectDataTableRetiredDecimalsTombstone} and
+ * {@link ObjectDataTableRetiredReferenceToTombstone} instead, intersected below.
+ * ⛔ Do not read this band's silence about either key as a softening — the
+ * tombstone and the band together are the same verdict, unchanged since each
+ * key's ruling.
+ *
+ * The pool shrank, then grew again. What THIS band refuses is `name` and
+ * `label` — both of them `FieldMeta` members with answers this seam already
+ * has (see the docblock above) — plus the relational members objectui#6694 and
+ * objectui#6875 added: `reference` and `displayField`. objectui#6694 added
+ * `reference_to` and `display_field` too; objectui#11070 retired both members
+ * from `FieldMeta` (round 4 and the text-family round), so they left this
+ * band's POOL, and {@link ObjectDataTableRetiredReferenceToSnakeTombstone} and
+ * {@link ObjectDataTableRetiredDisplayFieldSnakeTombstone} carry their refusals.
+ *
+ * ⭐ Those members are the derivation working as designed, and their verdict is
+ * the one objectui#6597 already reached for `referenceTo`: an AUTHORED column
+ * may not source a lookup's reference target. They are refused HERE while
+ * `buildFieldMeta` writes them freely, because that write's source is the
+ * OBJECT SCHEMA field def and never the column — the same distinction
+ * objectui#6597 measured, and the reason adding them needed no new hold. They
+ * reached this band without anyone extending a list.
+ */
+export type UnheldFieldMetaOverrideKey = Exclude<keyof FieldMeta, keyof TableColumn | keyof ObjectDataTableColumnHolds>;
+/** The keyhole `enrich` reads the authored column through. See the docblock above. */
+export type AuthoredColumnOverrides = {
+    accessorKey: string;
+}
+/** DECLARED by `TableColumn`; widened to `string` because the authored value
+ *  is folded onto the published union downstream, not at the read. */
+ & {
+    type?: string;
+}
+/** DECLARED by `TableColumn` + its zod mirror (objectui#6425, maintainer
+ *  ruling 2026-08-27) — the three adjudicated override keys are read at
+ *  their published types, straight off the declaration. */
+ & Pick<TableColumn, 'format' | 'options' | 'currency'> & ObjectDataTableColumnHolds & {
+    [K in UnheldFieldMetaOverrideKey]?: never;
+}
+/** RETIRED, objectui#6425's verdict — re-stated by hand because objectui#6625
+ *  took the key out of the derived band's pool. See the tombstone's docblock. */
+ & ObjectDataTableRetiredDecimalsTombstone
+/** RETIRED, objectui#6597's verdict (enforce-or-remove, withdraw) —
+ *  re-stated by hand for the same reason: the key left `keyof FieldMeta`,
+ *  so the derived band can no longer reach it. See the tombstone's docblock. */
+ & ObjectDataTableRetiredReferenceToTombstone
+/** RETIRED from `FieldMeta` by objectui#11070 round 4 — re-stated by hand for
+ *  the same reason. See the tombstone's docblock. */
+ & ObjectDataTableRetiredReferenceToSnakeTombstone
+/** RETIRED from `FieldMeta` by objectui#11070's text-family round —
+ *  re-stated by hand for the same reason. See the tombstone's docblock. */
+ & ObjectDataTableRetiredDisplayFieldSnakeTombstone;
 /**
  * Normalize columns to support both string[] shorthand and object[] formats.
  *
  * - `string[]` entries are converted to `{ header, accessorKey }` objects,
  *   handling both snake_case and camelCase for header generation.
- * - Object entries are returned as-is.
+ * - Object entries have their field identity AND their display text RESOLVED
+ *   here, at the producer, and stamped onto the data-table adapter's own keys
+ *   (`accessorKey` / `header`). The adapter reads only those two, and no longer
+ *   falls back to `name` / `label` (objectui#5120, objectui#5351).
+ *
+ * Object entries used to be returned raw (objectui#5120). `accessorKey` is the
+ * table LIBRARY's column key — `column-identity.ts` names it
+ * `TABLE_ADAPTER_COLUMN_KEY` and deliberately holds the metadata-identity fold
+ * away from it — so a column authored in the spec-canonical spelling
+ * (`{ field: 'stage' }`) reached the adapter carrying no `accessorKey` at all
+ * and rendered a header over `row[undefined]`: blank cells, no warning. The
+ * `$expand` whitelist in `computeLookupExpand` missed it for the same reason,
+ * so a `field`-spelled lookup column also lost its related record.
+ *
+ * Resolving it HERE is the move objectui#5022 made in `RelatedList` and
+ * objectui#5068 generalized in `ObjectGrid`: metadata vocabulary in, adapter
+ * vocabulary out, one translation in one place. The adapter stays monolingual;
+ * the producer owns the translation.
+ *
+ * Mirror, don't move — the same three rules `RelatedList` states:
+ *  - an author-supplied `accessorKey` is NEVER overwritten; a deliberate
+ *    divergence between the table slot and the metadata key belongs to the
+ *    author;
+ *  - the authored spelling is left in place, so a host reading `field` / `name`
+ *    back off these columns keeps working;
+ *  - an entry with neither a resolvable identity nor any display text is
+ *    returned UNTOUCHED — nothing is invented for it. It behaves exactly as it
+ *    does today: a header over empty cells, silently. Whether that silence
+ *    deserves a dev-time diagnostic is objectui#5349's question, and is
+ *    deliberately NOT answered here.
+ *
+ * Returning the INPUT entry by reference when there is nothing to add is load
+ * bearing: data-table re-seeds its column state whenever the list is a new
+ * object (objectui#4618), and this widget rebuilds its node on every render.
  */
 export declare function normalizeColumns(columns: (string | Record<string, any>)[]): NormalizedColumn[];
 /**
@@ -52,9 +459,56 @@ export declare function normalizeColumns(columns: (string | Record<string, any>)
 /**
  * Compute the list of lookup-typed accessors that should be expanded when
  * fetching rows. Returns column accessors whose object schema field type is
- * a relation (lookup/reference/master_detail/user/owner). Used by the
- * dashboard table widget to ask the data adapter to populate referenced
+ * a relation. Neither the type family nor the test itself is restated here:
+ * this delegates to {@link isLookupType} in `recordFields.tsx`, the package's
+ * single relation predicate, which reads `EXPANDABLE_FIELD_TYPES` — the family
+ * `@object-ui/core` publishes. Used
+ * by the dashboard table widget to ask the data adapter to populate referenced
  * records (e.g. `account: { id, name }`) so cells don't show raw FK ids.
+ *
+ * THE GATE (objectui#4914, ruling B) runs ahead of the relation test. Measured
+ * before the ruling: a `record_owner: { type: 'owner' }` column was ACTIVELY
+ * requested for `$expand` — the retired spelling got the full relational read
+ * path while the same field's editor answered with a tombstone. It is refused
+ * now, loudly and once, and the cell shows the raw id it was always going to
+ * show once the spelling stopped being a relation. That the author is TOLD is
+ * the whole difference between this and the mechanical deletion the
+ * measurement rejected.
+ *
+ * ## The relation test is core's object, not a private copy (objectui#5692)
+ *
+ * It used to be the inline literal
+ * `t === 'lookup' || t === 'reference' || t === 'master_detail' || t === 'user'`
+ * — one of TWO copies this package held (the other `LOOKUP_TYPES` in
+ * `recordFields.tsx`), neither deriving from nor pinned against the family core
+ * publishes. objectui#5312's claim to have converted "the LAST private copy"
+ * was false by these two; they predate that sweep and were outside its file
+ * surface.
+ *
+ * This is the LIVE half of that convergence — `computeLookupExpand` drives a
+ * real `$expand` on every dashboard table fetch — so both membership deltas are
+ * observable here, and both were decided by measurement (see `isLookupType` in
+ * `recordFields.tsx` for the full record):
+ *
+ *  - a `tree` column now GETS `$expand`-ed, the same treatment the form / grid
+ *    road already gives it;
+ *  - a `reference` column no longer does, and that is a no-op on spec-compliant
+ *    data: the spelling is absent from `@objectstack/spec`'s closed `FieldType`
+ *    and refused by `FieldSchema.safeParse`, so no object schema can declare a
+ *    field whose stored type is `reference`.
+ *
+ * ## One predicate, not two that agree by coincidence (objectui#5876)
+ *
+ * This function used to carry its own `isLookup`, byte-identical to
+ * `isLookupType` once objectui#5692 had pointed both at the same set — two
+ * bodies that agreed because one sweep aligned them, with nothing keeping them
+ * aligned afterwards. The test IS `isLookupType` now, so this module no longer
+ * IMPORTS the shared family or the retirement gate and no longer CALLS either
+ * (they are named in this prose and nowhere else in the file). That absence is
+ * the assertion: a BEHAVIOURAL test cannot see this change, because a
+ * byte-identical local copy satisfies every boolean claim you can make about
+ * `$expand`. The pin that can see it is the identity pin in
+ * `__tests__/expandableFamily.identity-5692.test.ts`.
  */
 export declare function computeLookupExpand(schema: {
     columns?: any[];

package/dist/ObjectDataTable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ObjectDataTable.d.ts","sourceRoot":"","sources":["../src/ObjectDataTable.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAgE,MAAM,OAAO,CAAC;AAerF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,YAAY,CAAC,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QACrD,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,GAAG,CAAC;QACb,IAAI,CAAC,EAAE,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;QAChB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;KACpB,CAAC;IACF,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,6EAA6E;AAC7E,UAAU,gBAAgB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,gBAAgB,EAAE,CAS9F;AAED;;;;;;;;;;;;;;;GAeG;AACH;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE;IAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAChD,YAAY,EAAE,GAAG,GAChB,MAAM,EAAE,CAgCV;AAED,eAAO,MAAM,eAAe,EAAE,KAAK,CAAC,EAAE,CAAC,oBAAoB,CA2T1D,CAAC"}
+{"version":3,"file":"ObjectDataTable.d.ts","sourceRoot":"","sources":["../src/ObjectDataTable.tsx"],"names":[],"mappings":"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"}

package/dist/ObjectMetricWidget.d.ts

@@ -1,6 +1,6 @@
 import { default as React } from 'react';
-import { DrillDownConfig } from '@object-ui/types';
-import { CompareToConfig } from './utils';
+import { I18nLabel, ObjectChartSchema, ObjectMetricDrillDownConfig } from '@object-ui/types';
+import { CompareToConfig } from './utils.js';
 /**
  * ObjectMetricWidget — Data-bound metric widget.
  *
@@ -19,39 +19,69 @@ import { CompareToConfig } from './utils';
 export interface ObjectMetricWidgetProps {
     /** The object/resource name to query */
     objectName: string;
-    /** Aggregation config (field, function, groupBy) */
+    /**
+     * Aggregation config (field, function, groupBy).
+     *
+     * `groupBy` is the contract's own union — BY REFERENCE through
+     * `ObjectChartSchema['aggregate']`, which holds `ChartAggregate` from
+     * `@objectstack/spec/ui` by reference in turn, never a local near-copy of it
+     * (`check:spec-symbols`). It is the same authored key the `object-chart` node
+     * carries, so a second spelling here could only be a way for the two to
+     * disagree. (Both dashboard relays used to compose this node and the chart's
+     * out of one `provider: 'object'` block; since objectui#11525 a dataset-less
+     * metric draws the retired-format placeholder, and this node is authored.)
+     *
+     * It used to say `string`, which was a claim about the AUTHOR that nothing
+     * upstream backed: the value crosses two `any` seams on its way in
+     * (`isObjectProvider` narrows the widget data to `aggregate?: any`, and
+     * `computeOne` takes the datasource untyped), so the declaration refused the
+     * structured `{ field, dateGranularity }` node at neither compile time nor
+     * runtime — it merely hid it from the reader, and from anyone asking whether
+     * `computeOne` handled it (objectui#8613). Optional here, unlike the chart's,
+     * because a metric paints ONE number and floors an absent `groupBy` at
+     * `'_all'`.
+     */
     aggregate?: {
         field: string;
         function: string;
-        groupBy?: string;
+        groupBy?: NonNullable<ObjectChartSchema['aggregate']>['groupBy'];
     };
     /** Filter conditions */
     filter?: any;
-    /** Static label for the metric */
-    label: string | {
-        key?: string;
-        defaultValue?: string;
-    };
+    /**
+     * The KPI's heading, in @objectstack/spec's `I18nLabel` vocabulary — a plain
+     * string or an inline per-locale map (`{ en: 'Revenue', 'zh-CN': '收入' }`).
+     *
+     * Was `string | { key?, defaultValue? }` — the key-reference form
+     * objectstack#5055 RETIRED at rc.6. The sibling `MetricWidgetProps` was
+     * migrated for this reason in objectui#4358; this interface was missed in
+     * that pass, and the omission was not inert (objectui#5264). This component
+     * forwards `label` straight to `MetricWidget`, which resolves it with
+     * `pickLocalized`. The retired object hits no locale limb, so resolution
+     * falls through to the last resort — the FIRST string property in insertion
+     * order — and `{ key, defaultValue }` written in that natural order paints
+     * the raw dotted translation key onto the card as its visible label.
+     *
+     * The producer side already says so: `ObjectMetricPropsSchema.label` in
+     * `@objectstack/spec/ui` is `I18nLabelSchema`, and its inline-map key regex
+     * rejects `key`/`defaultValue` by name. This declaration now agrees with it.
+     */
+    label: string | I18nLabel;
     /** Fallback static value (used when no dataSource or in demo mode) */
     fallbackValue?: string | number;
     /** Trend info */
     trend?: {
         value: number;
-        label?: string | {
-            key?: string;
-            defaultValue?: string;
-        };
+        /** Trend caption, same `I18nLabel` vocabulary as {@link ObjectMetricWidgetProps.label}. */
+        label?: string | I18nLabel;
         direction?: 'up' | 'down' | 'neutral';
     };
     /** Icon name or ReactNode */
     icon?: React.ReactNode | string;
     /** Additional CSS class */
     className?: string;
-    /** Description */
-    description?: string | {
-        key?: string;
-        defaultValue?: string;
-    };
+    /** Sub-caption under the value, same `I18nLabel` vocabulary as {@link ObjectMetricWidgetProps.label}. */
+    description?: string | I18nLabel;
     /** External data source (overrides context) */
     dataSource?: any;
     /** Visual color variant for the icon container */
@@ -72,16 +102,24 @@ export interface ObjectMetricWidgetProps {
      */
     invert?: boolean;
     /**
-     * Drill-down config. When enabled, clicking the metric card opens a
-     * drawer (or modal) showing the underlying records that contributed
-     * to this metric, filtered by the same `filter` used for aggregation.
+     * Drill-down config. When enabled, clicking the metric card opens a drawer
+     * (or dialog) listing the records behind the number, scoped by this
+     * widget's own `filter`, the one the aggregate runs over.
+     *
+     * Typed `ObjectMetricDrillDownConfig`, not the shared `DrillDownConfig`:
+     * `drillDown.filter` and `drillDown.mode` are refused by name on this block
+     * (objectui#9002, ruling B). A metric has no click event for a drill filter
+     * to interpolate against and no row to open as a record. The shared type
+     * keeps both members for the blocks that read them.
      */
-    drillDown?: DrillDownConfig;
-    /** Title for the drill-down panel; defaults to the metric label. */
-    title?: string | {
-        key?: string;
-        defaultValue?: string;
-    };
+    drillDown?: ObjectMetricDrillDownConfig;
+    /**
+     * Title for the drill-down panel; defaults to the metric label. Same
+     * `I18nLabel` vocabulary as {@link ObjectMetricWidgetProps.label}, and
+     * resolved through the same `pickLocalized` — see `drawerTitle` below, which
+     * used to read the retired form's `defaultValue` limb directly.
+     */
+    title?: string | I18nLabel;
     /**
      * Period-over-period comparison configuration — the executor's own
      * `{ kind, dimension? }` contract since objectstack#5011. When set, the