@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/affordanceGrants.js

@@ -0,0 +1,252 @@
+/**
+ * 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 affordance-to-grant map (objectui#12082): ONE table naming, for every
+ * console affordance that offers a write, the grant the caller must hold for
+ * it — and ONE resolver every such affordance reads.
+ *
+ * ## The family this closes
+ *
+ * Each console surface used to decide on its own which grant its affordance
+ * reads, and each surface that decided wrongly was found and fixed alone
+ * (objectui#4296, #10107, #11000, #12047). objectui#12082 is the member that
+ * hurt most: a create form gated its fields on the EDIT grant, so a
+ * create-only role could not fill the form it was allowed to submit. The same
+ * pass found the record header not reading the update grant at all, and a
+ * lookup offering "Create new" with no grant read either (objectui#12081). The
+ * cause is one shape — an affordance spelling its own permission logic — so
+ * the fix is one table every affordance reads, not another one-off repair.
+ *
+ * ## What a row says
+ *
+ * `crud` — the resolved CRUD-affordance bit the affordance also needs: the
+ * object's managed-object policy (ADR-0103, the spec's
+ * `resolveCrudAffordances`) intersected with the server's effective API
+ * operation set (`/me/permissions` `apiOperations`, objectstack#3391), both
+ * through {@link resolveEffectiveCrudAffordances}. `null` for an affordance
+ * whose write does not go through the object's generic data door (an
+ * attachment upload goes through the storage route; the import template has
+ * its own endpoint), so that door's operation set says nothing about it.
+ *
+ * `grant` — the caller's object grant it exercises, asked as `can(object,
+ * grant)` (`MePermissionsProvider` maps `create` → `allowCreate`, `update` →
+ * `allowEdit`, `delete` → `allowDelete`).
+ *
+ * `field` — for an affordance that offers FIELDS to write, the field-level
+ * question asked of each one: `create` for an insert, `write` for an update.
+ * They differ only for a field the permission set does not mention, which the
+ * server's field step lets through so that object admission decides: on an
+ * insert that is `allowCreate`, on an update `allowEdit`. A field the set marks
+ * `editable: false` is refused on both, and the resolver answers that the same
+ * way for both questions. So a create form follows what the server enforces on
+ * insert, and adds no rule the server does not have.
+ *
+ * The `write` question is the server's whole update rule for the field, so it
+ * also carries the one field whose update needs an OBJECT grant beyond
+ * `allowEdit`: the record's owner, the field the spec's `SystemFieldName`
+ * constant names `OWNER_ID`. The server refuses an update that writes it without
+ * the transfer grant (`allowTransfer`, or `modifyAllRecords`), so the resolver
+ * answers `write` for it with that grant too (objectui#12103). Every row that
+ * asks `write` therefore offers the owner field only to a caller who may
+ * transfer the record — the in-place edit, the list's in-cell edit and an edit
+ * form alike, with no row of its own to forget.
+ *
+ * ## The verdict
+ *
+ * An affordance shows when the managed-object policy, the effective API
+ * operation set AND the caller's grant all allow it ({@link resolveAffordance}).
+ * Its `userActions` predicates (the #2614 object form) are surfaced only then:
+ * a predicate narrows, and never re-opens what policy, operation set or grant
+ * closed.
+ *
+ * ## Fail-open, as before
+ *
+ * With no permission provider mounted, `usePermissions()` answers `can` with
+ * `true` and `isLoaded` with `false`, so every grant here reads open and the
+ * field question is not asked at all — a standalone embed, a designer preview
+ * and a public surface behave as they did before permissions existed, and the
+ * server still enforces (the `fieldWriteGate.ts` contract in
+ * `@object-ui/plugin-form`). The policy half is not a per-principal answer and
+ * does not fail open with it, exactly as `resolveEffectiveCrudAffordances`
+ * never did.
+ *
+ * ## Adding an affordance
+ *
+ * Add its row here and read it through {@link resolveAffordance} (or
+ * {@link resolveFieldAffordance} for fields). The enumeration pin in
+ * `@object-ui/plugin-form` (`affordanceGrantMap-12082.test.tsx`) runs every row
+ * against four grant shapes and holds the row set to its own expectation table,
+ * and its census refuses a console source file that reads a CRUD grant without
+ * this map.
+ *
+ * An affordance that reads NO grant is invisible to a census of grant reads —
+ * the calendar's quick-create and drag-to-reschedule and the kanban card move
+ * were such affordances until they gained their rows. So the same pin also
+ * counts the WRITES: every call site that invokes a create, update or delete on
+ * a data source has an entry there naming the row it sits behind and the file
+ * that reads it, or the reason it has none. A write site added without an entry
+ * turns that pin red.
+ */
+import { resolveEffectiveCrudAffordances, } from './managedBy.js';
+/**
+ * Every console affordance that offers a write → the grant it reads. Each
+ * row's comment names the affordance and the object the grant is asked of;
+ * where no object is named, it is the object the surface shows.
+ */
+export const AFFORDANCE_GRANTS = {
+    /** A create form's fields (every `ObjectForm` layout) and its form-wide lock. */
+    createFormFields: { crud: 'create', grant: 'create', field: 'create' },
+    /** An edit form's fields (every `ObjectForm` layout) and its form-wide lock. */
+    editFormFields: { crud: 'edit', grant: 'update', field: 'write' },
+    /**
+     * The record page's Edit — the header CTA and the record body's in-place
+     * editing (the details body and the highlights strip), each of whose fields
+     * asks the update question (objectui#12103) — and the record overlay's
+     * inline edit, the same body in the overlay the calendar, kanban and gantt
+     * open (`RecordDetailPanel` in `@object-ui/plugin-detail`).
+     */
+    recordEdit: { crud: 'edit', grant: 'update', field: 'write' },
+    /** The record page's Delete. */
+    recordDelete: { crud: 'delete', grant: 'delete' },
+    /**
+     * An object list's New: the console list page's toolbar button and phone
+     * "+", and the `object-view` node's toolbar button (`@object-ui/plugin-view`).
+     */
+    listNew: { crud: 'create', grant: 'create' },
+    /**
+     * An object list's Import, and the import wizard's writable target fields —
+     * and the AI build panel's spreadsheet import (`ExcelImportBar` in
+     * `@object-ui/app-shell`), the wizard's second mount, asked of the object it
+     * imports into.
+     */
+    listImport: { crud: 'import', grant: 'create', field: 'create' },
+    /** The import wizard's template download — its endpoint answers 403 without the create grant. */
+    importTemplate: { crud: null, grant: 'create' },
+    /** A list's inline (in-cell) editing, each of whose cells asks the update question (objectui#12103). */
+    listInlineEdit: { crud: 'edit', grant: 'update', field: 'write' },
+    /** A list's bulk Delete. */
+    listBulkDelete: { crud: 'delete', grant: 'delete' },
+    /**
+     * A grid row's Edit — and the writes that update the same rows in place: a
+     * grid's bulk field update (a `bulkActionDefs` `update` operation, with its
+     * undo and retry), and a gantt task's in-chart edits (a bar's drag, resize
+     * and progress, its title edited in place, and its dependency links).
+     */
+    rowEdit: { crud: 'edit', grant: 'update' },
+    /** A grid row's Delete — and a gantt row's Delete. */
+    rowDelete: { crud: 'delete', grant: 'delete' },
+    /** A grid's inline add-record row. */
+    gridAddRow: { crud: 'create', grant: 'create' },
+    /**
+     * A related list's "+ New", asked of the CHILD object — and a line-items
+     * panel's or a master-detail form's add-a-line (its Add, entry row and
+     * Duplicate), which creates a child under the same parent.
+     */
+    relatedNew: { crud: 'create', grant: 'create' },
+    /** A related list row's Edit, asked of the child object. */
+    relatedRowEdit: { crud: 'edit', grant: 'update' },
+    /**
+     * A related list row's Delete, asked of the child object — and a line-items
+     * panel's or a master-detail EDIT form's remove-a-line, which deletes that
+     * child on Save.
+     */
+    relatedRowDelete: { crud: 'delete', grant: 'delete' },
+    /**
+     * Setup's Clone of a declared item (objectui#12982): a declared sharing
+     * rule's Clone creates an organization rule, asked of the object the
+     * environment authors such items as (`sys_sharing_rule`).
+     */
+    declarationClone: { crud: 'create', grant: 'create' },
+    /** A lookup picker's "Create new", asked of the TARGET object. */
+    lookupCreateNew: { crud: 'create', grant: 'create' },
+    /** The record Attachments panel's Upload, asked of `sys_attachment` (storage route, not the data door). */
+    attachmentUpload: { crud: null, grant: 'create' },
+    /** The record Attachments panel's per-row delete, asked of `sys_attachment`. */
+    attachmentDelete: { crud: null, grant: 'delete' },
+    /**
+     * The record feed's comment composer and its reply composer, asked of
+     * `sys_comment`: each creates a comment row.
+     */
+    feedComment: { crud: 'create', grant: 'create' },
+    /**
+     * The record feed's reaction control, adding the caller's reaction (its Add
+     * button, or an emoji the caller has not reacted with), asked of
+     * `sys_comment_reaction`: it creates the caller's own reaction row.
+     */
+    feedReactionAdd: { crud: 'create', grant: 'create' },
+    /**
+     * The same control taking the caller's reaction back, asked of
+     * `sys_comment_reaction`: it deletes the caller's own reaction row.
+     */
+    feedReactionRemove: { crud: 'delete', grant: 'delete' },
+    /**
+     * The same control on a deployment with no `sys_comment_reaction` (the
+     * reactions column store), asked of `sys_comment`: a click updates the
+     * comment's `reactions` column.
+     */
+    feedReactionColumn: { crud: 'edit', grant: 'update' },
+    /**
+     * The record feed's Edit on a comment or reply the caller wrote, asked of
+     * `sys_comment`: it updates that comment row (objectui#12268). Whose comment
+     * it is decides only which rows offer it; the server's own rule decides the
+     * write.
+     */
+    feedCommentEdit: { crud: 'edit', grant: 'update' },
+    /** The same rows' Delete, asked of `sys_comment`: it deletes that comment row. */
+    feedCommentDelete: { crud: 'delete', grant: 'delete' },
+    /** A calendar's quick-create: an empty-day click, or a time-range drag in the week / day grid. */
+    calendarQuickCreate: { crud: 'create', grant: 'create' },
+    /** A calendar's drag-to-reschedule: moving or resizing an event writes its date fields. */
+    calendarReschedule: { crud: 'edit', grant: 'update' },
+    /** A kanban's card move: a cross-column drop writes the record's `groupBy` field. */
+    kanbanCardMove: { crud: 'edit', grant: 'update' },
+};
+const PREDICATES = {
+    create: 'createPredicates',
+    import: 'importPredicates',
+    edit: 'editPredicates',
+    delete: 'deletePredicates',
+};
+/**
+ * Resolve one affordance: its row's CRUD-affordance bit (managed-object policy
+ * ∧ the effective API operation set) AND the caller's grant.
+ */
+export function resolveAffordance(affordance, { objectSchema, objectName, perms } = {}) {
+    const row = AFFORDANCE_GRANTS[affordance];
+    let predicates;
+    if (row.crud !== null) {
+        const ops = objectName ? perms?.getObjectApiOperations?.(objectName) : undefined;
+        const crud = resolveEffectiveCrudAffordances(objectSchema, ops);
+        if (!crud[row.crud])
+            return { allowed: false };
+        predicates = crud[PREDICATES[row.crud]];
+    }
+    if (objectName && perms && !perms.can(objectName, row.grant))
+        return { allowed: false };
+    return predicates ? { allowed: true, predicates } : { allowed: true };
+}
+/**
+ * The field-level half of a field affordance: may the caller write `field`
+ * through it? Asks the resolver the row's question (`create` or `write`); with
+ * no provider mounted (`isLoaded` false) it asks nothing and answers `true`.
+ */
+export function resolveFieldAffordance(affordance, perms, objectName, field) {
+    if (!perms?.isLoaded)
+        return true;
+    return perms.checkField(objectName, field, AFFORDANCE_GRANTS[affordance].field);
+}
+/**
+ * The form row for a form's mode: a create form's fields ask the create
+ * question, every other form that writes asks the edit question, and a `view`
+ * form writes nothing (`undefined`).
+ */
+export function formFieldsAffordance(mode) {
+    if (mode === 'view')
+        return undefined;
+    return mode === 'create' ? 'createFormFields' : 'editFormFields';
+}

package/dist/utils/chart-category-key.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 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.
+ */
+/**
+ * chart-category-key — the ONE answer to "which result column carries the
+ * CATEGORY?" for an object-bound chart (objectui#8269).
+ *
+ * The mirror of `chart-measure-key` (objectui#8266) on the other axis. That
+ * card landed `chartMeasureKey` over the contract's `chartAggregateValueKey`;
+ * the contract publishes a CATEGORY sibling in the same module —
+ * `chartAggregateCategoryKey` — and nothing in this repository read it.
+ *
+ * ## The disagreement this replaces
+ *
+ * Both dashboard relays composed the category binding as a LITERAL FLOOR:
+ *
+ *   const xAxisKey = options.xField || 'name';
+ *
+ * and handed it to the `object-chart` node without ever consulting the
+ * `aggregate` that decides it. An object-bound aggregate returns one row per
+ * group, keyed by the raw `groupBy` field, so a widget declaring
+ * `aggregate: { function: 'count', groupBy: 'status' }` and no `options.xField`
+ * bound `'name'` against rows keyed `'status'`.
+ *
+ * Unlike the measure half, this one is LOUD: `hasNoCategoryKey`
+ * (`plugin-charts/src/AdvancedChartImpl.tsx`, framework#4033) fires and the
+ * author reads "This chart cannot plot its category axis: no row has a `name`
+ * field." The diagnostic is wrong-CAUSE — it names a binding the author never
+ * wrote and never mentions the `groupBy` they did — so it points at the wrong
+ * layer. Being loud makes it a lesser harm than objectui#8266, not a
+ * non-defect: measured over the rows a fieldless count returns,
+ * `[{status:'open',count:2},{status:'paid',count:5}]`, an `xAxisKey` of
+ * `'name'` refuses under BOTH series bindings, i.e. objectui#8266's fix does
+ * not reach this authoring shape at all.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * Restating the rule here would make this file a second opinion of a question
+ * the contract already answers — the objectui#5042 / #7544 / #8193 / #8168
+ * drift shape that `chart-measure-key` exists to end. So the rule stays
+ * upstream in `@objectstack/spec/ui` and this is the seam objectui-side callers
+ * share.
+ *
+ * ## ⚠️ NOT the same function as `resolveChartCategoryField`
+ *
+ * `plugin-charts`' own `resolveChartCategoryField` (objectui#8168) reads
+ * `aggregate.groupBy` first too — which is exactly why `ObjectChart` does NOT
+ * refuse this shape at its own level, and then forwards `schema.xAxisKey`
+ * verbatim as the render binding anyway. But the two answer DIFFERENT
+ * questions and must not be collapsed:
+ *
+ *   - `resolveChartCategoryField` answers "which FIELD is the category?" — its
+ *     structured-`groupBy` leg returns `node.field`, because its two readers
+ *     are the refusal (does the author name a category at all?) and the
+ *     field-metadata probe that loads that field's option labels and colours.
+ *   - this function answers "which COLUMN do the returned rows carry it
+ *     under?" — `groupBy.alias ?? groupBy.field` per the contract, because an
+ *     `alias` (admitted by `ChartGroupBySchema`) renames the projected column.
+ *
+ * They coincide whenever no alias is written, which is why the distinction is
+ * easy to miss; conflating them would either bind an axis to a column the rows
+ * do not carry, or probe field metadata for a field that does not exist.
+ */
+import { type ChartAggregateLike } from '@objectstack/spec/ui';
+/**
+ * The result column a chart's category axis / x-axis binding must name.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `xField` is the right key),
+ * an UNGROUPED aggregate (one row, no category column), or a `groupBy` shape
+ * `ChartGroupBySchema` already rejects. It is never a second opinion about an
+ * aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export declare function chartCategoryKey(aggregate: ChartAggregateLike | undefined, fallback: string): string;

package/dist/utils/chart-category-key.js

@@ -0,0 +1,84 @@
+/**
+ * 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.
+ */
+/**
+ * chart-category-key — the ONE answer to "which result column carries the
+ * CATEGORY?" for an object-bound chart (objectui#8269).
+ *
+ * The mirror of `chart-measure-key` (objectui#8266) on the other axis. That
+ * card landed `chartMeasureKey` over the contract's `chartAggregateValueKey`;
+ * the contract publishes a CATEGORY sibling in the same module —
+ * `chartAggregateCategoryKey` — and nothing in this repository read it.
+ *
+ * ## The disagreement this replaces
+ *
+ * Both dashboard relays composed the category binding as a LITERAL FLOOR:
+ *
+ *   const xAxisKey = options.xField || 'name';
+ *
+ * and handed it to the `object-chart` node without ever consulting the
+ * `aggregate` that decides it. An object-bound aggregate returns one row per
+ * group, keyed by the raw `groupBy` field, so a widget declaring
+ * `aggregate: { function: 'count', groupBy: 'status' }` and no `options.xField`
+ * bound `'name'` against rows keyed `'status'`.
+ *
+ * Unlike the measure half, this one is LOUD: `hasNoCategoryKey`
+ * (`plugin-charts/src/AdvancedChartImpl.tsx`, framework#4033) fires and the
+ * author reads "This chart cannot plot its category axis: no row has a `name`
+ * field." The diagnostic is wrong-CAUSE — it names a binding the author never
+ * wrote and never mentions the `groupBy` they did — so it points at the wrong
+ * layer. Being loud makes it a lesser harm than objectui#8266, not a
+ * non-defect: measured over the rows a fieldless count returns,
+ * `[{status:'open',count:2},{status:'paid',count:5}]`, an `xAxisKey` of
+ * `'name'` refuses under BOTH series bindings, i.e. objectui#8266's fix does
+ * not reach this authoring shape at all.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * Restating the rule here would make this file a second opinion of a question
+ * the contract already answers — the objectui#5042 / #7544 / #8193 / #8168
+ * drift shape that `chart-measure-key` exists to end. So the rule stays
+ * upstream in `@objectstack/spec/ui` and this is the seam objectui-side callers
+ * share.
+ *
+ * ## ⚠️ NOT the same function as `resolveChartCategoryField`
+ *
+ * `plugin-charts`' own `resolveChartCategoryField` (objectui#8168) reads
+ * `aggregate.groupBy` first too — which is exactly why `ObjectChart` does NOT
+ * refuse this shape at its own level, and then forwards `schema.xAxisKey`
+ * verbatim as the render binding anyway. But the two answer DIFFERENT
+ * questions and must not be collapsed:
+ *
+ *   - `resolveChartCategoryField` answers "which FIELD is the category?" — its
+ *     structured-`groupBy` leg returns `node.field`, because its two readers
+ *     are the refusal (does the author name a category at all?) and the
+ *     field-metadata probe that loads that field's option labels and colours.
+ *   - this function answers "which COLUMN do the returned rows carry it
+ *     under?" — `groupBy.alias ?? groupBy.field` per the contract, because an
+ *     `alias` (admitted by `ChartGroupBySchema`) renames the projected column.
+ *
+ * They coincide whenever no alias is written, which is why the distinction is
+ * easy to miss; conflating them would either bind an axis to a column the rows
+ * do not carry, or probe field metadata for a field that does not exist.
+ */
+import { chartAggregateCategoryKey } from '@objectstack/spec/ui';
+/**
+ * The result column a chart's category axis / x-axis binding must name.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `xField` is the right key),
+ * an UNGROUPED aggregate (one row, no category column), or a `groupBy` shape
+ * `ChartGroupBySchema` already rejects. It is never a second opinion about an
+ * aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export function chartCategoryKey(aggregate, fallback) {
+    return chartAggregateCategoryKey(aggregate) ?? fallback;
+}

package/dist/utils/chart-measure-key.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 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.
+ */
+/**
+ * chart-measure-key — the ONE answer to "which result column carries the
+ * measure?" for an object-bound chart (objectui#8266).
+ *
+ * ## The disagreement this replaces
+ *
+ * The question was answered independently in three places, and for a FIELDLESS
+ * `count` — the normal way to author "how many records per status", and the
+ * most common dashboard chart there is — two of them answered differently:
+ *
+ *   - the ROW PROJECTION (`aggregateValueKey` / `aggregateRecords` /
+ *     `runAggregate`'s alias, all in `plugin-charts/src/ObjectChart.tsx`) keys
+ *     the value column `'count'`, the alias the engine projects `COUNT(*)`
+ *     under;
+ *   - the SERIES BINDING, spelled twice in `plugin-dashboard`
+ *     (`DashboardGridLayout.tsx` and `DashboardRenderer.tsx`), read
+ *     `aggregate.field || (options.yField || 'value')` and so bound `'value'`.
+ *
+ * A `dataKey` naming a column no row carries plots nothing, and nothing says
+ * so: measured on `origin/main` `0fa7a9c83`, rows `[{status:'open',count:2},
+ * {status:'paid',count:5}]` with `series:[{dataKey:'value'}]` rendered a
+ * `.recharts-surface` with the category ticks "open"/"paid", **0 bars, 0
+ * rectangles**, no refusal and no empty state — the same rows under
+ * `dataKey:'count'` drew 2 rectangles. An empty chart reads as "no data yet",
+ * which is exactly what an author with a genuinely empty object also sees.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * `chartAggregateValueKey` in `@objectstack/spec/ui` is the CONTRACT's own
+ * derivation — "the VALUE column an object-bound aggregate produces … what a
+ * chart's series / y-axis binding must name". Producers and checkers already
+ * read it. Restating the rule here would make this file a fourth opinion of the
+ * same question, which is the shape (objectui#5042 / #7544 / #8193 / #8168)
+ * this module exists to end. So the rule lives upstream in the spec and this is
+ * the seam objectui-side callers share, exactly as `humanizeLabel` (objectui#5444)
+ * and `buildChartSeries` (ADR-0021) already are.
+ *
+ * ⛔ The inverse fix — making the row projection key a fieldless count
+ * `'value'` — is not available: it contradicts a pin the tree already carries
+ * (`ObjectChart.aggregateResultColumns.test.ts`) and renames the column every
+ * other consumer reads, including the engine's own `COUNT(*)` alias.
+ */
+import { type ChartAggregateLike } from '@objectstack/spec/ui';
+export type { ChartAggregateLike };
+/**
+ * The result column a chart's series must bind to.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `yField` is the right key),
+ * or an aggregate shape `ChartAggregateSchema` already rejects. It is never a
+ * second opinion about an aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export declare function chartMeasureKey(aggregate: ChartAggregateLike | undefined, fallback: string): string;

package/dist/utils/chart-measure-key.js

@@ -0,0 +1,65 @@
+/**
+ * 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.
+ */
+/**
+ * chart-measure-key — the ONE answer to "which result column carries the
+ * measure?" for an object-bound chart (objectui#8266).
+ *
+ * ## The disagreement this replaces
+ *
+ * The question was answered independently in three places, and for a FIELDLESS
+ * `count` — the normal way to author "how many records per status", and the
+ * most common dashboard chart there is — two of them answered differently:
+ *
+ *   - the ROW PROJECTION (`aggregateValueKey` / `aggregateRecords` /
+ *     `runAggregate`'s alias, all in `plugin-charts/src/ObjectChart.tsx`) keys
+ *     the value column `'count'`, the alias the engine projects `COUNT(*)`
+ *     under;
+ *   - the SERIES BINDING, spelled twice in `plugin-dashboard`
+ *     (`DashboardGridLayout.tsx` and `DashboardRenderer.tsx`), read
+ *     `aggregate.field || (options.yField || 'value')` and so bound `'value'`.
+ *
+ * A `dataKey` naming a column no row carries plots nothing, and nothing says
+ * so: measured on `origin/main` `0fa7a9c83`, rows `[{status:'open',count:2},
+ * {status:'paid',count:5}]` with `series:[{dataKey:'value'}]` rendered a
+ * `.recharts-surface` with the category ticks "open"/"paid", **0 bars, 0
+ * rectangles**, no refusal and no empty state — the same rows under
+ * `dataKey:'count'` drew 2 rectangles. An empty chart reads as "no data yet",
+ * which is exactly what an author with a genuinely empty object also sees.
+ *
+ * ## Why the answer is delegated rather than restated
+ *
+ * `chartAggregateValueKey` in `@objectstack/spec/ui` is the CONTRACT's own
+ * derivation — "the VALUE column an object-bound aggregate produces … what a
+ * chart's series / y-axis binding must name". Producers and checkers already
+ * read it. Restating the rule here would make this file a fourth opinion of the
+ * same question, which is the shape (objectui#5042 / #7544 / #8193 / #8168)
+ * this module exists to end. So the rule lives upstream in the spec and this is
+ * the seam objectui-side callers share, exactly as `humanizeLabel` (objectui#5444)
+ * and `buildChartSeries` (ADR-0021) already are.
+ *
+ * ⛔ The inverse fix — making the row projection key a fieldless count
+ * `'value'` — is not available: it contradicts a pin the tree already carries
+ * (`ObjectChart.aggregateResultColumns.test.ts`) and renames the column every
+ * other consumer reads, including the engine's own `COUNT(*)` alias.
+ */
+import { chartAggregateValueKey } from '@objectstack/spec/ui';
+/**
+ * The result column a chart's series must bind to.
+ *
+ * `fallback` is the caller's own floor, used ONLY when the contract has no
+ * answer — a chart that declares no `aggregate` at all (its rows are raw
+ * records or authored literals, where the author's `yField` is the right key),
+ * or an aggregate shape `ChartAggregateSchema` already rejects. It is never a
+ * second opinion about an aggregate the contract CAN answer for.
+ *
+ * @param aggregate the chart's inline aggregate, or `undefined`
+ * @param fallback  the key to bind when the contract has no answer
+ */
+export function chartMeasureKey(aggregate, fallback) {
+    return chartAggregateValueKey(aggregate) ?? fallback;
+}