@object-ui/core 17.6.0 → 17.7.0

package/dist/utils/normalize-list-view.js

@@ -73,8 +73,16 @@ const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
  * available to users in the view toolbar", and already carries `rowHeight` —
  * objectui's `showDensity` under its spec name. `group` / `hideFields` /
  * `rowColor` are the same kind of toggle and are named after the config key
- * they gate (`grouping`, `hiddenFields`, `rowColor`), pending promotion into
- * `UserActionsConfigSchema` upstream.
+ * they gate (`grouping`, `hiddenFields`, `rowColor`).
+ *
+ * That promotion has LANDED (objectui#5435, ruled Option A 2026-08-22):
+ * `UserActionsConfigSchema` declares all three from `@objectstack/spec@17.3.0`,
+ * and the spec's declaring docblock names this card. Every key this table emits
+ * is therefore authorable, which
+ * `__tests__/normalize-list-view.foldOutputAuthorable-5435.test.ts` pins with a
+ * firing control. ⛔ Do not read the three as legacy-only spellings awaiting
+ * retirement — the protocol declares them, so removing them here would leave
+ * objectui narrower than the protocol.
  */
 const SHOW_FLAG_TO_USER_ACTION = {
     showSearch: 'search',
@@ -101,6 +109,137 @@ const ARIA_KEY_ALIASES = {
     label: 'ariaLabel',
     describedBy: 'ariaDescribedBy',
 };
+/**
+ * The view kinds `ListView` actually draws.
+ *
+ * A total `Record<…, true>` over {@link ListViewVisualization}, for the same
+ * reason the density maps above are `Record<RowHeight, …>`: a kind added to the
+ * union fails the build HERE instead of silently staying unreadable authored
+ * input.
+ *
+ * ⚠️ That promise was FALSE between `@objectstack/spec@17.3.0` and `ca3942729`.
+ * `ViewType` was a hand-written copy of the spec's list, so this map was total
+ * over the copy and compiled green while the spec's `page` had nowhere to land.
+ * Both faces are derived now, and the two totality structures below close the
+ * other half of the union, so every member of the spec's list is accounted for
+ * by a structure that fails the build rather than by a reader's memory.
+ *
+ * `hasOwnProperty`, not `in` — same trap as {@link rowHeightToDensityMode}:
+ * `in` walks the prototype chain, so `'toString'` would read as a view kind.
+ */
+const LIST_VIEW_KINDS = {
+    grid: true,
+    kanban: true,
+    gallery: true,
+    calendar: true,
+    timeline: true,
+    gantt: true,
+    map: true,
+    chart: true,
+    tree: true,
+};
+/**
+ * Every member of {@link ViewType} that {@link LIST_VIEW_KINDS} does NOT carry,
+ * with the reason — and, where the answer is "the author authored something
+ * valid and will get a grid", the sentence to say out loud.
+ *
+ * The two tables together still partition the derived union — a member the spec
+ * ADDS must be classed as drawable or explained HERE, and until it is the build
+ * is red — but the red lands on {@link LIST_VIEW_KINDS} alone, because a kind
+ * neither table classes is not extracted into {@link UndrawableViewKind} and so
+ * stays inside {@link ListViewVisualization}, whose record is total. A key
+ * MISSPELLED here fails the same way, for the same reason: the kind it was
+ * meant to class is not extracted either. Both directions are pinned in
+ * `__tests__/normalize-list-view.undrawableBothLegs-9880.test.ts` rather than
+ * asserted in this sentence.
+ *
+ * ⛔ NOT annotated `Record<Exclude<ViewType, ListViewVisualization>, …>`, and
+ * the `satisfies` is not a style choice (objectui#9880). An annotation makes
+ * the literal EXACT in BOTH directions: a kind the spec adds is a missing key
+ * (wanted) and a kind the spec RETIRES is an EXCESS PROPERTY — a TS2353 that
+ * demands a deletion this repository cannot make while it resolves a published
+ * spec which still carries the kind (as it did with `page` through 17.4.0).
+ * `satisfies` keeps the value constraint
+ * (every reason is a `string` or `null`) and drops the exactness, which is what
+ * lets one spelling compile against both the pinned published spec and one
+ * built from objectstack `main`.
+ *
+ * `null` means silence is correct — these are objectui view CATEGORIES, never
+ * authored as a list-view kind:
+ *  - `list` is the view CATEGORY, not a kind — it already folds to `grid`.
+ *  - `detail` is a different renderer (`plugin-detail`), never a ListView case.
+ *
+ * `page` had a row here until objectui#11073. objectstack#17063 removed
+ * `type: 'page'` from the list-view enum, and the row answered for it while this
+ * repository still resolved a spec that published the kind. `@objectstack/spec`
+ * 17.5.0 carries the removal: both published `@object-ui/types` faces refuse
+ * `page`, `Extract` no longer extracted the row, and the residual pins that held
+ * it (`normalize-list-view.pageResidual-8429.test.ts`) were converted, so it was
+ * deleted as it said it would be. A stored `page` view now degrades like any
+ * kind outside the vocabulary.
+ */
+const UNDRAWABLE_VIEW_KINDS = {
+    list: null,
+    detail: null,
+};
+/** One warning per undrawable kind per process — see {@link warnUndrawableViewKind}. */
+const warnedUndrawableKinds = new Set();
+/**
+ * Fail-open is **loud**, not silent — the convention this repo already applies
+ * to unevaluable predicates (`../evaluator/fieldRules.ts`, objectstack#5149).
+ *
+ * The bug `ca3942729` records is not only that `type: 'page'` degrades to a
+ * grid; it is that it degrades IDENTICALLY to a typo. Measured on `5505aec`,
+ * `specType: 'page'` and `specType: 'nonsense'` both left `viewType: 'grid'`
+ * with no error, no warning and no console line — and `@object-ui/types`'
+ * published validator ACCEPTS `viewType: 'page'` while refusing the typo. An
+ * author who writes a spec-valid view and is silently handed a different one
+ * has no way to tell that from a working grid, so the degrade says so once.
+ *
+ * Once per kind per process, and never for the two objectui categories: this
+ * runs inside a normalizer that a render can call on every keystroke, and the
+ * point is one line, not a scrolling wall.
+ */
+function warnUndrawableViewKind(kind) {
+    const reason = Object.prototype.hasOwnProperty.call(UNDRAWABLE_VIEW_KINDS, kind)
+        ? UNDRAWABLE_VIEW_KINDS[kind]
+        : null;
+    if (reason === null || warnedUndrawableKinds.has(kind))
+        return;
+    warnedUndrawableKinds.add(kind);
+    console.warn(`[object-ui] This build accepts a ${JSON.stringify(kind)} list view but cannot draw one: ` +
+        `${reason}. The view falls back to a grid. ` +
+        'Author a visualization this renderer draws, or render the page through the surface that owns it.');
+}
+/**
+ * Whether `value` names a visualization `ListView` draws.
+ *
+ * Exported so a read site cannot restate the membership question as its own
+ * literal array: the gate and the seam must answer one question, which is the
+ * rule this file's own `availableViews` notes already argue for (objectui#5042,
+ * objectui#7544, and now `ca3942729`).
+ */
+export function isListViewVisualization(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(LIST_VIEW_KINDS, value);
+}
+/**
+ * The author's view kind, or `undefined` when the value names no kind ListView
+ * draws. An unrecognized kind is deliberately left unresolved rather than
+ * written through to `viewType`: the caller's own `'grid'` default is a more
+ * honest answer than a `viewType` no branch matches (the same call
+ * `normalizeChartSchema` makes for a chart family it cannot draw).
+ *
+ * A kind the SPEC allows but this renderer cannot draw takes the same fallback
+ * and additionally warns — see {@link warnUndrawableViewKind}.
+ */
+function readListViewKind(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (isListViewVisualization(value))
+        return value;
+    warnUndrawableViewKind(value);
+    return undefined;
+}
 /**
  * Per-view-type config aliases → the spec key each one aliases (#2890, the
  * phase-3 carry-over).
@@ -179,10 +318,34 @@ const PER_VIEW_CONFIG_ALIASES = {
  *    so objectui's field is typed from the spec but used as something else.
  *    That mismatch is real and out of scope here; converting formats inside a
  *    vocabulary fold would change what reaches the data source.
+ *  - `data: { provider: 'object', object }` → `objectName` (#7477, step 6 of
+ *    #2890). This is the spelling the published `react-blocks` contract
+ *    recommends and the one `@objectstack/spec`'s `ViewDataSchema` declares;
+ *    ListView read it at ZERO sites, so a page bound that way validated green
+ *    upstream and rendered an empty list here with no diagnostic. The `object`
+ *    provider is a `strictObject` carrying exactly `{ provider, object }`, so
+ *    `objectName` captures all of it. Two deliberate departures from the folds
+ *    above, both narrowing:
+ *      · an already-present `objectName` WINS — this fold only fills a gap, it
+ *        never re-points a binding that already resolves;
+ *      · `data` is NOT deleted. Every other fold deletes because the legacy key
+ *        has one meaning and one home; `data` has four providers, `api`/`value`
+ *        are read live in `ListView`, and the whole block is FORWARDED to child
+ *        views (the gantt branch), whose own `getDataConfig` reads `data` before
+ *        `objectName`. Deleting it for one provider would rewrite what a child
+ *        resolves. Nothing in `ListView` reads `data.provider === 'object'`, so
+ *        keeping it cannot create a second de-facto contract inside the renderer.
  *  - `viewType`: a missing kind, or the view CATEGORY `'list'` that AI-authored
  *    metadata stores and hosts forward verbatim, becomes the renderable `'grid'`
  *    — otherwise it reaches the renderer's typeless default branch and shows as
- *    a red "Unknown component type" box.
+ *    a red "Unknown component type" box. Before that default applies, the
+ *    AUTHOR's kind is read (#7477): `specType` — the slot
+ *    `components/renderers/layout/react-page.tsx` parks a react-tier `type` in
+ *    when the SDUI envelope claims the `type` key (ADR-0078) — and then a bare
+ *    `type` when it names a kind ListView draws, which the component
+ *    discriminator (`'list-view'`) never does. Same two legs, same order, as
+ *    `normalizeChartSchema`'s chart-family read. An explicit `viewType` still
+ *    wins: this leg only fills the gap that used to resolve to `'grid'`.
  *  - each `columns` entry's IDENTITY — `name` / `fieldName` → the spec's `field`
  *    (#3104). This one MIRRORS instead of deleting, for the reason given on
  *    {@link normalizeColumnIdentities}: `columns` entries cross the package
@@ -208,7 +371,12 @@ export function normalizeListViewSchema(schema) {
     const legacyFields = s.fields;
     const foldColumns = Array.isArray(legacyFields);
     const legacyDensity = s.densityMode;
-    const foldRowHeight = typeof legacyDensity === 'string' && legacyDensity in DENSITY_MODE_TO_ROW_HEIGHT;
+    // `hasOwnProperty`, not `in` — same trap as {@link rowHeightToDensityMode},
+    // in the fold direction: `in` walks the prototype chain, so `'toString'` used
+    // to fold into `rowHeight` as `Object.prototype.toString`, a FUNCTION, and
+    // drop the key (objectui#10868). An inherited key is an unrecognized density.
+    const foldRowHeight = typeof legacyDensity === 'string' &&
+        Object.prototype.hasOwnProperty.call(DENSITY_MODE_TO_ROW_HEIGHT, legacyDensity);
     const legacyFilters = s.filters;
     const foldFilter = Array.isArray(legacyFilters);
     const legacyFlags = Object.keys(SHOW_FLAG_TO_USER_ACTION).filter((k) => typeof s[k] === 'boolean');
@@ -217,7 +385,17 @@ export function normalizeListViewSchema(schema) {
     const foldAria = !!aria && Object.keys(ARIA_KEY_ALIASES).some((k) => aria[k] !== undefined);
     const sharing = isRecord(s.sharing) ? s.sharing : undefined;
     const foldSharing = !!sharing && (sharing.visibility !== undefined || sharing.enabled !== undefined);
+    // `data: { provider: 'object', object }` → `objectName` (#7477). Gap-fill
+    // only: a non-empty `objectName` already on the schema wins, so this can
+    // never re-point a binding that resolves today.
+    const dataConfig = isRecord(s.data) ? s.data : undefined;
+    const dataObjectName = dataConfig?.provider === 'object' && typeof dataConfig.object === 'string' && dataConfig.object
+        ? dataConfig.object
+        : undefined;
+    const foldObjectName = dataObjectName !== undefined && !(typeof s.objectName === 'string' && s.objectName);
     const viewType = s.viewType;
+    // The author's kind, read before the `'grid'` default applies (#7477).
+    const authoredViewKind = readListViewKind(s.specType) ?? readListViewKind(s.type);
     const defaultViewKind = !viewType || viewType === 'list';
     // The columns array the identity fold will see — mirroring the `foldColumns`
     // precedence below (canonical `columns` wins; otherwise the legacy `fields`
@@ -246,7 +424,7 @@ export function normalizeListViewSchema(schema) {
         .filter((entry) => entry !== undefined);
     if (!foldColumns && !foldRowHeight && !foldFilter && !legacyFlags.length &&
         !foldDescription && !foldAria && !foldSharing && !defaultViewKind &&
-        !foldColumnIdentity && !perViewFolds.length) {
+        !foldColumnIdentity && !perViewFolds.length && !foldObjectName) {
         return schema;
     }
     const next = { ...s };
@@ -333,7 +511,9 @@ export function normalizeListViewSchema(schema) {
         }
         next[viewKey] = nextCfg;
     }
+    if (foldObjectName)
+        next.objectName = dataObjectName;
     if (defaultViewKind)
-        next.viewType = 'grid';
+        next.viewType = authoredViewKind ?? 'grid';
     return next;
 }

package/dist/utils/number-display.d.ts

@@ -20,11 +20,12 @@
  *     grouped and pointed decimals the US way; and
  *  2. `useGrouping` was never set, so a four-digit YEAR stored as
  *     `Field.number({ scale: 0 })` rendered as `2,026` — in every locale, with
- *     no field property able to turn it off.
+ *     no field property able to turn it off. (That property now exists: the
+ *     spec's `FieldSchema.useGrouping`, read here since objectui#11026.)
  *
- * Both policies now live here and nowhere else. Call sites bring the value and
- * the display width; they do not bring a locale default and they do not decide
- * grouping.
+ * Both policies now live here and nowhere else. Call sites bring the value, the
+ * display width and whatever the FIELD declared (`scale`, `useGrouping`); they
+ * do not bring a locale default and they do not decide grouping.
  *
  * ── Why this module lives in `@object-ui/core` (objectui#4576) ──
  * It used to live in `@object-ui/i18n`, and that home cost the repo a real
@@ -57,6 +58,22 @@ export interface DisplayNumberFormatOptions {
      * for a non-React caller that has no locale in hand. It never means `en-US`:
      * assuming US conventions for the whole world is the defect this module was
      * created to remove.
+     *
+     * ── The caller this rule governs (objectui#10098) ──
+     * The `undefined` rule above is written for a NON-REACT display caller with
+     * no tag in hand: a plain formatter, an exporter, engine code — anything that
+     * cannot call a hook. For that caller the runtime default is the viewer's
+     * own environment, and the viewer's own environment is the honest locale for
+     * a user-facing display. A malformed tag ends in the same place, whoever the
+     * caller: {@link formatDisplayNumber} retries without it rather than
+     * throwing, so the number renders in the runtime default instead of taking
+     * the cell down.
+     *
+     * A React renderer is governed by a different rule, and the two do not
+     * contradict each other. It passes what `useDisplayLocale` returns, and that
+     * hook — `@object-ui/i18n`, `packages/i18n/src/useDisplayLocale.ts` — ends
+     * its provider chain on the concrete `'en'`, for determinism, when the chain
+     * yields no tag at all. That hook's docblock names this one in return.
      */
     locale?: string;
     /**
@@ -88,14 +105,40 @@ export interface DisplayNumberFormatOptions {
      *
      * ⚠️ INTERIM DEFAULT (objectui#4033, PM ruling 2026-08-11). Suppressing
      * grouping for every scale-0 number is a transitional policy with a known,
-     * accepted cost: a large scale-0 COUNT loses its separators too. It is the
-     * better trade only until the spec gains an authorable presentation hint
-     * (`useGrouping` / `displayFormat` — being specified separately, contract-first,
-     * in the objectstack repo). When that hint lands it OVERRIDES this default,
-     * and this heuristic should be reduced to the fallback for fields that
-     * declare nothing.
+     * accepted cost: a large scale-0 COUNT loses its separators too. The
+     * authorable hint it was waiting for has landed as
+     * {@link DisplayNumberFormatOptions.useGrouping} (objectui#11026): an
+     * authored boolean OVERRIDES this default, and the heuristic is now only the
+     * fallback for a field that declares nothing.
      */
     scale?: number;
+    /**
+     * The FIELD's authored `useGrouping` — `FieldSchema.useGrouping` in
+     * `@objectstack/spec`, the author's digit-grouping hint — and nothing else.
+     * Like `scale` it is a POLICY input: pass it only when a field declaration
+     * actually said so (objectui#11026).
+     *
+     * Three-valued, and the spec's own reading of each value is the one this
+     * option implements:
+     *
+     *   - `undefined` — the author made no judgement, so the renderer decides:
+     *     the `scale`/`currency` heuristic in {@link shouldGroupDisplayNumber},
+     *     unchanged.
+     *   - `false` — the author's explicit opt-out (a year, an ID, a zip code).
+     *     Never grouped, whatever `scale` or `currency` would have suggested.
+     *   - `true` — the author pins grouping ON, overriding the heuristic the
+     *     other way (a scale-0 count that should read `2,026`).
+     *
+     * The spec maps the key 1:1 onto `Intl.NumberFormat`'s `useGrouping`, so an
+     * authored `true` reaches `Intl` as `true`, which means "always". That is
+     * deliberately NOT what the heuristic's own "group" answer does: it omits
+     * the key and keeps the locale's "auto" (see the `Intl` note inside
+     * {@link formatDisplayNumber}). The two differ where a locale leaves a
+     * four-digit number alone under "auto" (es-ES and pl-PL render `1234`); an
+     * author who pinned grouping on gets `1.234` / `1 234` there, because that
+     * is what they declared.
+     */
+    useGrouping?: boolean;
     /**
      * How the number relates to a percentage — the ONE place that distinction is
      * expressed, because getting it wrong is the whole of objectui#4576.
@@ -137,11 +180,17 @@ export interface DisplayNumberFormatOptions {
  * The grouping policy, alone and testable: does this number get thousands
  * separators?
  *
- * @param scale    the field's declared `scale`, or `undefined` when the caller
- *                 has no field declaration behind it
- * @param currency ISO 4217 code when the number is money
+ * This is the ONE place the decision is made. An authored `useGrouping`
+ * answers it outright; only when the field declared nothing does the
+ * `scale`/`currency` heuristic below get a say (objectui#11026).
+ *
+ * @param scale       the field's declared `scale`, or `undefined` when the
+ *                    caller has no field declaration behind it
+ * @param currency    ISO 4217 code when the number is money
+ * @param useGrouping the field's authored `useGrouping`, or `undefined` when
+ *                    the author declared none
  */
-export declare function shouldGroupDisplayNumber(scale?: number, currency?: string): boolean;
+export declare function shouldGroupDisplayNumber(scale?: number, currency?: string, useGrouping?: boolean): boolean;
 /**
  * Format a number for DISPLAY, in the active locale, under the grouping policy
  * above.

package/dist/utils/number-display.js

@@ -9,11 +9,23 @@
  * The grouping policy, alone and testable: does this number get thousands
  * separators?
  *
- * @param scale    the field's declared `scale`, or `undefined` when the caller
- *                 has no field declaration behind it
- * @param currency ISO 4217 code when the number is money
+ * This is the ONE place the decision is made. An authored `useGrouping`
+ * answers it outright; only when the field declared nothing does the
+ * `scale`/`currency` heuristic below get a say (objectui#11026).
+ *
+ * @param scale       the field's declared `scale`, or `undefined` when the
+ *                    caller has no field declaration behind it
+ * @param currency    ISO 4217 code when the number is money
+ * @param useGrouping the field's authored `useGrouping`, or `undefined` when
+ *                    the author declared none
  */
-export function shouldGroupDisplayNumber(scale, currency) {
+export function shouldGroupDisplayNumber(scale, currency, useGrouping) {
+    // The author's explicit declaration beats every guess below, money included:
+    // the spec reads `false` as "never grouped, regardless of what the
+    // renderer's heuristic would have guessed", and `true` as the same override
+    // in the other direction.
+    if (typeof useGrouping === 'boolean')
+        return useGrouping;
     // Money always groups — including money whose currency code could not be
     // resolved, which still renders as an amount (just without a symbol).
     if (currency)
@@ -32,7 +44,7 @@ export function shouldGroupDisplayNumber(scale, currency) {
  * malformed tag from a tenant config must never take a grid cell down.
  */
 export function formatDisplayNumber(value, options = {}) {
-    const { locale, currency, scale, style, ...passthrough } = options;
+    const { locale, currency, scale, useGrouping, style, ...passthrough } = options;
     const intlOptions = { ...passthrough };
     if (style === 'percentPoints') {
         // The locale's percent convention WITHOUT `style: 'percent'`'s ×100 — see
@@ -50,15 +62,25 @@ export function formatDisplayNumber(value, options = {}) {
         delete intlOptions.unit;
         delete intlOptions.unitDisplay;
     }
-    // ⚠️ Set `useGrouping` ONLY to suppress. `useGrouping: true` is NOT the same
-    // as omitting the key: `true` means "always", while omitting it means "auto"
-    // (and "min2" under compact notation), which is the locale's own preference.
-    // Measured — for 1234: es-ES "auto" → `1234` but "always" → `1.234`; pl-PL
-    // "auto" → `1234` but "always" → `1 234`. Writing `true` here would silently
-    // override those locales' conventions in the name of preserving en-US output.
-    if (!shouldGroupDisplayNumber(scale, currency)) {
+    // ⚠️ Never write `useGrouping: true` on the renderer's own behalf.
+    // `useGrouping: true` is NOT the same as omitting the key: `true` means
+    // "always", while omitting it means "auto" (and "min2" under compact
+    // notation), which is the locale's own preference. Measured — for 1234:
+    // es-ES "auto" → `1234` but "always" → `1.234`; pl-PL "auto" → `1234` but
+    // "always" → `1 234`. Writing `true` for a field that declared nothing would
+    // silently override those locales' conventions in the name of preserving
+    // en-US output.
+    //
+    // The ONE `true` this function writes is the author's own (objectui#11026):
+    // `FieldSchema.useGrouping` maps 1:1 onto this `Intl` option, and an author
+    // who pinned grouping on asked for "always". The decision itself is made
+    // once, above, by `shouldGroupDisplayNumber`; this only spells it for `Intl`.
+    if (!shouldGroupDisplayNumber(scale, currency, useGrouping)) {
         intlOptions.useGrouping = false;
     }
+    else if (useGrouping === true) {
+        intlOptions.useGrouping = true;
+    }
     try {
         return new Intl.NumberFormat(locale, intlOptions).format(value);
     }

package/dist/utils/object-aggregate-query.d.ts

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+/**
+ * object-aggregate-query — the ONE answer to "which CALL does an object-bound
+ * `aggregate` make when its authored `groupBy` is the structured node?"
+ * (objectui#8613).
+ *
+ * ## The two wires, and why the choice is not cosmetic
+ *
+ * An authored `aggregate.groupBy` is a union: a bare field name, or the
+ * structured date-bucketing node `{ field, dateGranularity?, alias? }` — the
+ * union `ChartGroupBySchema` declares and `GroupByNodeSchema` (the query AST)
+ * mirrors. The adapter routes on the SHAPE of the params it is handed, not on
+ * the shape of the authored value:
+ *
+ *   - `{ groupBy: GroupByNode[], aggregations, where }` — the spec-shape query,
+ *     which reaches `engine.aggregate` and runs the server-side date-bucket
+ *     engine;
+ *   - `{ field, function, groupBy, filter }` — the legacy cube/analytics query,
+ *     whose `dimensions` the contract declares as an array of dimension NAMES
+ *     and which does NOT honour `dateGranularity` at all.
+ *
+ * So a structured node forwarded on the legacy wire is posted as a dimension
+ * OBJECT where a name is declared: the author asks for monthly buckets and the
+ * platform answers a different question, with no diagnostic on the way. That is
+ * the defect objectui#8613 records on the metric path, and it was reachable
+ * there only because this payload was spelled INSIDE one renderer
+ * (`ObjectChart.runAggregate`) rather than anywhere a second renderer could
+ * reuse it.
+ *
+ * ## Why a shared module rather than a second copy
+ *
+ * The alternative was to transcribe the eight lines into the metric widget.
+ * That is the objectui#5042 / #7544 / #8193 / #8266 / #8269 drift shape — a
+ * second opinion of one question, with nothing keeping the two in agreement —
+ * and it is the same shape those cards' fixes (`chartMeasureKey`,
+ * `chartCategoryKey`) exist to end, one column at a time. This module is that
+ * move applied to the REQUEST rather than to a result column.
+ *
+ * ## What is NOT here
+ *
+ * The legacy bag itself. The two renderers do not agree on it and should not be
+ * made to: a chart passes the authored `groupBy` through untouched, while a
+ * metric floors an absent one at `'_all'` (one bucket) because it paints a
+ * single number. Folding that difference into a shared builder would put a
+ * renderer's own default into a module that has no business holding one, so the
+ * shared part stops exactly where the agreement stops.
+ */
+import type { ChartGroupBy } from '@objectstack/spec/ui';
+import { type ChartAggregateLike } from './chart-measure-key.js';
+/**
+ * The STRUCTURED arm of the contract's `groupBy` union — the date-bucketing
+ * node, as distinct from the bare field name the same union admits.
+ *
+ * Extracted from `ChartGroupBy` rather than restated, so a member added to the
+ * node upstream (as `alias` once was) arrives here without an edit.
+ */
+export type StructuredGroupBy = Extract<ChartGroupBy, {
+    field: string;
+}>;
+/**
+ * The spec-shape aggregate query's `aggregations[]` entry, as
+ * `AggregationNodeSchema` declares it: `alias` is REQUIRED (it names the column
+ * the measure is projected under), `field` is optional because a `count` counts
+ * rows rather than a column.
+ */
+export interface ObjectAggregationNode {
+    function?: string;
+    alias: string;
+    field?: string;
+}
+/** The spec-shape query body — `{ groupBy: GroupByNode[], aggregations, where }`. */
+export interface ObjectAggregateSpecQuery {
+    groupBy: StructuredGroupBy[];
+    aggregations: ObjectAggregationNode[];
+    where: unknown;
+}
+/**
+ * Is this authored `aggregate.groupBy` the structured node rather than a bare
+ * field name?
+ *
+ * ⚠️ An ARRAY answers `false`. It is an object, but it is not this union's
+ * object arm — neither `ChartGroupBySchema` nor `ObjectMetricPropsSchema`'s
+ * `aggregate` admits one at this position, and `data-objectstack`'s adapter
+ * already refuses it at the wire (`503cd8b89`). Letting it through here would
+ * wrap it into `groupBy: [[…]]` and turn a producer-side refusal into a
+ * malformed query.
+ */
+export declare function isStructuredGroupBy(groupBy: unknown): groupBy is StructuredGroupBy;
+/**
+ * The spec-shape aggregate query for an object-bound `aggregate` whose
+ * `groupBy` is the structured node.
+ *
+ * The measure is projected under {@link chartMeasureKey}'s answer — the raw
+ * field name, or the literal `'count'` for a fieldless count — so a caller's
+ * existing result readback finds the value under the key it already looks for,
+ * and a chart's series binding names the column the rows actually carry.
+ *
+ * `field` is omitted for `count` so the engine emits `count(*)`: the dashboard
+ * relays default `field: 'value'` for a widget with no explicit measure column,
+ * and `count(value)` crashes SQL drivers with "no such column: value" on the
+ * count-the-rows case that is the common one.
+ *
+ * @param aggregate the authored inline aggregate
+ * @param groupBy   its `groupBy`, already narrowed by {@link isStructuredGroupBy}
+ * @param where     the resolved filter, in the spec Query DSL's `where` position
+ */
+export declare function objectAggregateSpecQuery(aggregate: ChartAggregateLike, groupBy: StructuredGroupBy, where: unknown): ObjectAggregateSpecQuery;

package/dist/utils/object-aggregate-query.js

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+import { chartMeasureKey } from './chart-measure-key.js';
+/**
+ * Is this authored `aggregate.groupBy` the structured node rather than a bare
+ * field name?
+ *
+ * ⚠️ An ARRAY answers `false`. It is an object, but it is not this union's
+ * object arm — neither `ChartGroupBySchema` nor `ObjectMetricPropsSchema`'s
+ * `aggregate` admits one at this position, and `data-objectstack`'s adapter
+ * already refuses it at the wire (`503cd8b89`). Letting it through here would
+ * wrap it into `groupBy: [[…]]` and turn a producer-side refusal into a
+ * malformed query.
+ */
+export function isStructuredGroupBy(groupBy) {
+    return !!groupBy && typeof groupBy === 'object' && !Array.isArray(groupBy);
+}
+/**
+ * The spec-shape aggregate query for an object-bound `aggregate` whose
+ * `groupBy` is the structured node.
+ *
+ * The measure is projected under {@link chartMeasureKey}'s answer — the raw
+ * field name, or the literal `'count'` for a fieldless count — so a caller's
+ * existing result readback finds the value under the key it already looks for,
+ * and a chart's series binding names the column the rows actually carry.
+ *
+ * `field` is omitted for `count` so the engine emits `count(*)`: the dashboard
+ * relays default `field: 'value'` for a widget with no explicit measure column,
+ * and `count(value)` crashes SQL drivers with "no such column: value" on the
+ * count-the-rows case that is the common one.
+ *
+ * @param aggregate the authored inline aggregate
+ * @param groupBy   its `groupBy`, already narrowed by {@link isStructuredGroupBy}
+ * @param where     the resolved filter, in the spec Query DSL's `where` position
+ */
+export function objectAggregateSpecQuery(aggregate, groupBy, where) {
+    const aggFn = aggregate.function;
+    const node = {
+        function: aggFn,
+        alias: chartMeasureKey(aggregate, aggFn || 'count'),
+    };
+    if (aggFn !== 'count' && aggregate.field)
+        node.field = aggregate.field;
+    return { groupBy: [groupBy], aggregations: [node], where };
+}