@object-ui/plugin-dashboard 17.6.0 → 18.0.0

package/dist/legacyRetiredWidget.d.ts

@@ -1,4 +1,4 @@
-import { DashboardWidgetSchema } from '@object-ui/types';
+import { DashboardWidgetSlotEntry } from './widgetDispatch.js';
 /**
  * The placeholder schema rendered in place of a retired inline-analytics widget.
  *
@@ -10,7 +10,7 @@ import { DashboardWidgetSchema } from '@object-ui/types';
  */
 export declare const LEGACY_RETIRED_WIDGET_SCHEMA: {
     readonly type: "text";
-    readonly value: "This widget uses a retired data format. Edit it to bind a dataset.";
+    readonly content: "This widget uses a retired data format. Edit it to bind a dataset.";
     readonly variant: "caption";
     readonly align: "center";
     readonly className: "flex h-full w-full items-center justify-center rounded border border-dashed border-destructive/40 bg-destructive/5 p-4 text-center text-destructive";
@@ -37,5 +37,30 @@ export declare const LEGACY_RETIRED_WIDGET_SCHEMA: {
  * surface no observable behavior, and it keeps the predicate true on its own
  * terms for any surface that has no such fork.
  */
-export declare function isLegacyRetiredWidget(widget: DashboardWidgetSchema | null | undefined): boolean;
+export declare function isLegacyRetiredWidget(widget: DashboardWidgetSlotEntry | null | undefined): boolean;
+/**
+ * Is `node`, read from a widget's legacy `component` envelope
+ * (`{ id, component, layout }`, objectui's own format, which the spec's widget
+ * has no member for), a node the surfaces no longer draw? True for every node
+ * but a `metric-card` (objectui#12254).
+ *
+ * The envelope takes a `metric-card` and nothing else: the 2026-08-14 slot
+ * ruling (objectstack#8593) allowed that one node, and since objectui#12163
+ * (ruling C) both zod faces and `DashboardWidgetSchema['component']` refuse any
+ * other node by name. objectui#12254 retires the draw to match, after a census
+ * of stored use found no producer. So the accept set is the authoring one, read
+ * from the same closed list, `DASHBOARD_COMPONENT_WIDGET_TYPES`: a node whose
+ * `type` is a member draws as before, and anything else in the envelope (a
+ * node of another type, a node with no `type`, a string or a number) draws
+ * {@link LEGACY_RETIRED_WIDGET_SCHEMA}, the rebind prompt the metric and pivot
+ * arms return, and sends no query. The `object-metric` node objectui#11466
+ * retired here first is one case of the rule.
+ *
+ * An empty envelope (`component` absent, or a falsy value) holds no node, so
+ * this answers false and the widget draws by its family, as before.
+ *
+ * ⛔ Read only at the envelope: the same node types authored on a page, or a
+ * `metric-card` placed directly in `widgets[]`, are not judged here.
+ */
+export declare function isRetiredEnvelopeNode(node: unknown): boolean;
 //# sourceMappingURL=legacyRetiredWidget.d.ts.map

package/dist/legacyRetiredWidget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"legacyRetiredWidget.d.ts","sourceRoot":"","sources":["../src/legacyRetiredWidget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;;;;CAM/B,CAAC;AAoBX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAM/F"}
+{"version":3,"file":"legacyRetiredWidget.d.ts","sourceRoot":"","sources":["../src/legacyRetiredWidget.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAuDH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEjE;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B;;;;;;CAM/B,CAAC;AAoBX;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,wBAAwB,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAMlG;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAI5D"}

package/dist/measureRefusal.d.ts

@@ -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.
+ */
+/**
+ * objectui#8894 — what the widget door says about a widget's MEASURES.
+ *
+ * Returns the message of the `custom` issue objectui's authoring door raises at
+ * `values` for this type, these measures and these dimensions, or `undefined`
+ * when the door accepts them. The door is `DashboardWidgetSchema` from
+ * `@object-ui/types/zod`, which re-attaches the spec's own object-level checks,
+ * so its verdict and its message are the spec's (pinned by
+ * `packages/types/src/__tests__/dashboard-widget-metric-measure-door-8894.test.ts`).
+ *
+ * The door is ASKED, never restated: no widget-type list lives here. Whichever
+ * types the spec refuses a second measure on — the metric family since
+ * `@objectstack/spec` 17.5.0 (`checkDashboardWidgetMetricMeasureArity`), and
+ * any further shape once a spec release refuses it and the mirror re-attaches
+ * that check (objectstack#20958 is the pending one) — the authoring pickers that
+ * read this follow without an edit here.
+ *
+ * Only the keys a measure rule reads go into the probe — `id` (the message
+ * names it), `type`, `values` and `dimensions` — each kept to a shape the door
+ * accepts. zod skips object-level checks once a field-level issue aborts the
+ * parse, and a draft in an editor is half-written by nature: measured on the
+ * mirror, a numeric `id`, a non-string dimension or a malformed `title`
+ * anywhere in the document each hide the measure verdict completely, which
+ * would read as "accepted". The probe keeps those faults out of the question it
+ * asks.
+ *
+ * Module-private to this package (not re-exported from its index).
+ */
+export declare function measureRefusal(widget: {
+    id?: unknown;
+    type?: unknown;
+    values?: unknown;
+    dimensions?: unknown;
+}): string | undefined;
+/**
+ * A stand-in for "one more measure", used to ask the door whether a picker may
+ * offer another one before the author has chosen which. The door's measure
+ * rules judge how many measures a widget declares, not their names (whether a
+ * measure exists in the bound dataset is out of the widget schema's reach), so
+ * any name the widget does not already carry asks the same question.
+ */
+export declare const NEXT_MEASURE_PROBE = "__next_measure__";
+//# sourceMappingURL=measureRefusal.d.ts.map

package/dist/measureRefusal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"measureRefusal.d.ts","sourceRoot":"","sources":["../src/measureRefusal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB,GAAG,MAAM,GAAG,SAAS,CAgBrB;AAED;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,qBAAqB,CAAC"}

package/dist/metricTile.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The metric tile's layout rule — ONE home, read by every metric tile in this
+ * package: the plain cards (`MetricCard`, `MetricWidget`, and through it
+ * `ObjectMetricWidget` and every `object-metric` page block) and the
+ * dataset-bound tile (`DatasetWidget`) (objectui#12623).
+ *
+ *  - The title owns the first line: 13 px / 500, up to two lines, an ellipsis
+ *    on the second. Nothing shares its line but the plain card's icon chip.
+ *  - The value never wraps, and it scales before it would clip
+ *    (objectui#12942). A short value is one step smaller (20 px) in a tile
+ *    narrower than 160 px, 24 px from 160 px up. A longer one — a seven-digit
+ *    money figure with cents — takes a size ladder from 14 px to 24 px whose
+ *    steps start where that size fits (`metricTileValueClass`).
+ *  - The measure label (dataset-bound tile only) is an 11 px muted line under
+ *    the value, dropped below 160 px. The title's tooltip carries it, so it is
+ *    still there at every width.
+ *
+ * Width rules key off the TILE's own box (`@container` on the tile, `@[160px]:`
+ * variants), never the viewport: a dashboard grid, a page block and the
+ * Studio's folded canvas each size the same tile differently.
+ *
+ * Class strings stay static literals so Tailwind's content scanner sees them
+ * (`apps/console/src/index.css` sources this package's `src/**`).
+ */
+/** Put on the tile's root: the box the width rules below are measured against. */
+export declare const METRIC_TILE_CONTAINER_CLASS = "@container";
+/** The title: owns the first line, at most two lines, an ellipsis on the second. */
+export declare const METRIC_TILE_TITLE_CLASS = "min-w-0 line-clamp-2 break-words text-[13px] font-medium leading-snug text-foreground";
+/**
+ * The value: never wraps; 20 px below a 160 px tile, 24 px from 160 px up. The
+ * short value's face on a plain tile, and the dataset-bound tile's value at
+ * every length: that tile has no Card inset, so its value has the container's
+ * whole width and the ladder below, measured against a Card, does not apply.
+ */
+export declare const METRIC_TILE_VALUE_CLASS = "max-w-full overflow-hidden text-ellipsis whitespace-nowrap tabular-nums text-xl @[160px]:text-2xl";
+/**
+ * The value's size ladder, chosen by how wide the value is (objectui#12942).
+ *
+ * A plain tile (`MetricCard`, `MetricWidget`: a `Card`, 1 px border, the value
+ * in `CardContent`'s 24 px side padding) gives its value the container's width
+ * less {@link METRIC_TILE_VALUE_INSET} px — the container query reads the
+ * Card's content box, inside the border. A value `em` wide fits at a size of
+ * `px` from a container `INSET + em * px` wide, so each `@[N px]:` step below
+ * starts at `ceil(INSET + maxEm * px)` for its rung's widest value. The
+ * `metricTileValueScale-12942` test re-derives every step from that formula.
+ *
+ * The first rung is the short value's face, {@link METRIC_TILE_VALUE_CLASS}'s
+ * sizes unchanged. Every later rung starts at 14 px; past the last one, 14 px
+ * at every width. A value still wider than its tile at 14 px keeps the
+ * ellipsis, and the value node carries the full figure as its tooltip.
+ *
+ * Literals only: Tailwind's content scanner must see every class.
+ */
+export declare const METRIC_TILE_VALUE_INSET = 48;
+export declare const METRIC_TILE_VALUE_LADDER: ReadonlyArray<{
+    readonly maxEm: number;
+    readonly sizes: string;
+}>;
+/** Past the ladder's last rung: 14 px at every width. */
+export declare const METRIC_TILE_VALUE_FINAL_SIZES = "text-sm";
+/**
+ * How wide `text` draws, in em, at the tile's bold tabular figures — an upper
+ * bound read off Inter, the console's face: a digit is 0.65 em, a digit
+ * separator (`,` `.` `'` or a space) 0.27 em, a sign or currency symbol 0.7 em,
+ * and any other character a full em (letters, CJK).
+ */
+export declare function metricTileValueEm(text: string): number;
+/**
+ * The value node's class for `value`: the rung of {@link METRIC_TILE_VALUE_LADDER}
+ * its width falls in, or the 14 px final face past the last rung.
+ */
+export declare function metricTileValueClass(value: string | number): string;
+/** The measure label: an 11 px muted line under the value, dropped below 160 px. */
+export declare const METRIC_TILE_MEASURE_LABEL_CLASS = "hidden max-w-full truncate text-[11px] text-muted-foreground @[160px]:block";
+/**
+ * The title's tooltip: the description when one is authored, else the title,
+ * then the measure label on its own line — the one place the label survives in
+ * a tile too narrow to draw it.
+ */
+export declare function metricTileTooltip(title: string | undefined, description?: string, measureLabel?: string): string | undefined;
+/**
+ * The value node's tooltip: the full figure, for a value past the short rung —
+ * the one place it survives in a tile too narrow even for 14 px. A short value
+ * draws none, as before.
+ */
+export declare function metricTileValueTitle(value: string | number): string | undefined;
+//# sourceMappingURL=metricTile.d.ts.map

package/dist/metricTile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metricTile.d.ts","sourceRoot":"","sources":["../src/metricTile.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,kFAAkF;AAClF,eAAO,MAAM,2BAA2B,eAAe,CAAC;AAExD,oFAAoF;AACpF,eAAO,MAAM,uBAAuB,0FAA0F,CAAC;AAE/H;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,sGAAsG,CAAC;AAE3I;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,eAAO,MAAM,wBAAwB,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAOtG,CAAC;AAEF,yDAAyD;AACzD,eAAO,MAAM,6BAA6B,YAAY,CAAC;AAIvD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAStD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAInE;AAED,oFAAoF;AACpF,eAAO,MAAM,+BAA+B,gFAAgF,CAAC;AAE7H;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,WAAW,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG5H;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAG/E"}

package/dist/recordFields.d.ts

@@ -8,6 +8,74 @@ export declare const SYSTEM_FIELDS: Set<string>;
 export declare function isSystemField(name: string, def?: any): boolean;
 /** Numeric-flavoured field types (right-aligned in tables). */
 export declare const NUMERIC_FIELD_TYPES: Set<string>;
+/**
+ * The override vocabulary this package's two field surfaces share.
+ *
+ * ⚠️ This type is a DERIVATION SOURCE, not only a shape: `ObjectDataTable`'s
+ * two column bands are both `Exclude<keyof FieldMeta, …>` — `EnrichedColumn`'s
+ * write-side tombstones (objectui#6373) and `AuthoredColumnOverrides`' read-side
+ * refusal band (objectui#6425). So a member REMOVED here silently leaves both
+ * bands, and any refusal that rode on its membership stops enforcing with
+ * nothing going red. A member being retired must therefore be re-refused
+ * explicitly at that seam before it leaves this type — see
+ * `ObjectDataTableRetiredDecimalsTombstone` in `ObjectDataTable.tsx`, which is
+ * what `decimals` left behind.
+ *
+ * ⛔ `decimals` was RETIRED from this type by objectui#6625 — written from the
+ * schema def on every call and read by nothing (zero `.decimals` member reads
+ * across `@object-ui/fields`, `@object-ui/i18n`, `@object-ui/components`,
+ * `@object-ui/core` and this package, measured against a `.scale` positive
+ * control that hits `NumberField.tsx` / `GridField.tsx` / `index.tsx`). If a
+ * reader is ever wanted here it reads `scale` — the field def's decimal-places
+ * key, which is what the retired write resolved to anyway and what
+ * `NumberCellRenderer` already reads (`precision` is the total digit count, a
+ * different question — objectui#2131). ⛔ Do not resurrect `decimals`.
+ *
+ * ⛔ `referenceTo` was RETIRED from this type by objectui#6597 (enforce-or-remove,
+ * withdraw branch — maintainer's standing startup-stage rule, 2026-08-27: no
+ * measured demand retires immediately). It was documented by this package's
+ * README as an author-facing column override, but the promise was never kept:
+ * `LookupCellRenderer` (`@object-ui/fields`) resolves its lookup target from
+ * `field.reference_to` / `field.reference` — never `field.referenceTo` — and
+ * `computeLookupExpand` (`ObjectDataTable.tsx`) builds `$expand` from the OBJECT
+ * SCHEMA's field types, never from an authored override. Measured with the
+ * `referenceTo`-vs-`options` positive control in
+ * `ObjectDataTable.overrideSource-6425.test.tsx`: `options` (a live override)
+ * separates two equal-valued columns, `referenceTo` does not — an authored
+ * override renders byte-identical to its absence. No authoring story survived
+ * the search either: the sibling `ObjectGrid` producer's own relational-meta
+ * pass-through (`applyRelationalMeta`, `plugin-grid/src/ObjectGrid.tsx`) copies
+ * `reference_to` / `reference` from the SCHEMA field def only, never from an
+ * authored column override, and no example/doc/fixture in this repo shows a
+ * table column pinning a lookup's target to something other than what its
+ * schema field already says. If a reader for the resolved reference target is
+ * ever wanted here, it reads `reference_to` / `reference` off the schema field
+ * def directly — the spelling `LookupCellRenderer` and `computeLookupExpand`
+ * actually use. ⛔ Do not resurrect `referenceTo`.
+ *
+ * ⭐ That reader ARRIVED (objectui#6694): `reference` / `displayField` below
+ * (with `reference_to` beside them until objectui#11070 round 4 retired it,
+ * and `display_field` until objectui#11070's text-family round did), copied
+ * from the SCHEMA field def by {@link buildFieldMeta} and justified per key on
+ * `CELL_RELATIONAL_META_KEYS`.
+ * They are the "future reader" both retirement notes predicted, in the spelling
+ * they named, and they change neither verdict — the source is the schema field
+ * def, never an authored column override, which is the exact distinction
+ * objectui#6597 measured and withdrew on.
+ *
+ * ⚠️ Being `FieldMeta` members they GROW both derived bands in
+ * `ObjectDataTable.tsx` — `EnrichedColumn`'s emit tombstones and
+ * `UnheldFieldMetaOverrideKey`'s read-side refusal. `reference_to` left the
+ * type in objectui#11070 round 4 and `display_field` in its text-family round,
+ * so — by the rule at the top of this docblock — each one's refusal is
+ * re-stated by hand there (`ObjectDataTableRetiredReferenceToSnakeTombstone`,
+ * `ObjectDataTableRetiredDisplayFieldSnakeTombstone`). That is the intended
+ * verdict rather than a side effect: an AUTHORED column may not source a
+ * lookup's reference target (objectui#6597 measured no authoring story for
+ * one), while the schema-derived write is reached by neither band. They landed
+ * in both without anyone editing a list — the property this derivation exists
+ * for.
+ */
 export interface FieldMeta {
     name: string;
     label: string;
@@ -17,10 +85,34 @@ export interface FieldMeta {
         label: string;
         color?: string;
     }>;
-    referenceTo?: unknown;
     format?: string;
     currency?: string;
-    decimals?: number;
+    /**
+     * The field def's declared upper bound, which on a `percent` field is its
+     * STORAGE statement: the spec's `percentScaleOf` reads a fraction unless
+     * `max` is above 1 (objectui#11475). Copied from the SCHEMA field def by
+     * {@link buildFieldMeta} so the percent cell and the `%` branch of
+     * {@link renderFieldValue} read the field's storage rather than guess it
+     * from the value. Never an authored column override: as a `FieldMeta`
+     * member it lands in `ObjectDataTable`'s read-side refusal band, which is
+     * the intended verdict — a column may not restate how its field stores.
+     */
+    max?: number;
+    /**
+     * Lookup target object — the spelling `@objectstack/spec`'s `FieldSchema`
+     * declares and the only one `LookupCellRenderer` reads. Its snake_case twin
+     * `reference_to` was RETIRED from this type by objectui#11070 round 4.
+     */
+    reference?: string;
+    /**
+     * Author-declared display field on the lookup, in the SPEC spelling
+     * (`FieldSchema.displayField`) — it beats every resolver in the cell. The
+     * first leg of `LookupCellRenderer`'s `displayField || reference_field`
+     * chain, and the only leg a spec-compliant producer can emit
+     * (objectui#6875). Its snake_case twin `display_field` was RETIRED from this
+     * type by objectui#11070's text-family round: no reader read it.
+     */
+    displayField?: string;
 }
 /**
  * Normalize an object schema's `fields` into a `{ name → def }` map. Accepts
@@ -37,20 +129,39 @@ export interface BuildFieldMetaParams {
     objectName?: string;
     /** Translator for per-option labels (from `useSafeFieldLabel`). */
     fieldOptionLabel?: (objectName: string, field: string, value: string, fallback: string) => string;
-    /** Per-column overrides (table columns may pin type/format/options). */
+    /**
+     * Per-column overrides (table columns may pin type/format/options).
+     *
+     * A subset of {@link FieldMeta}, which is what makes that type the pool
+     * `ObjectDataTable`'s refusal band derives from. `decimals` left with the
+     * member (objectui#6625): its last feeder went when objectui#6425's ruling
+     * removed the authored read from `ObjectDataTable.enrich()`, and
+     * `RecordDetailDrawer` — the only other caller — passes no overrides at all.
+     * `referenceTo` left the same way (objectui#6597): `ObjectDataTable.enrich()`
+     * no longer reads it off the authored column, and `RecordDetailDrawer` never
+     * did.
+     */
     overrides?: {
         type?: string;
         format?: string;
         options?: any;
-        referenceTo?: unknown;
         currency?: string;
-        decimals?: number;
     };
 }
 /**
- * Build the `FieldMeta` for a single field, resolving `referenceTo`, currency
- * and decimals from the schema field def and translating select options.
- * Column-level overrides win over schema-derived values.
+ * Build the `FieldMeta` for a single field, resolving currency from the
+ * schema field def and translating select options. Column-level overrides
+ * win over schema-derived values.
+ *
+ * The field def's currency goes through `resolveFieldCurrency`
+ * (`@object-ui/i18n`) rather than a chain of this helper's own (objectui#10463).
+ * The resolver is what reads `currencyConfig`, the spec's one fixed-currency
+ * declaration, and only under `currencyMode: 'fixed'`. The chain it replaced
+ * read the flat `currency` / `defaultCurrency` spellings only, so a fixed
+ * field painted in the tenant currency in both the table cell and the record
+ * drawer. The call passes NO tenant default: `renderFieldValue` backstops with
+ * the tenant only after the symbol it infers from a `format`, and a tenant code
+ * resolved here would jump ahead of that symbol.
  */
 export declare function buildFieldMeta(params: BuildFieldMetaParams): FieldMeta;
 /** Whether a `FieldMeta` should be right-aligned (numeric / currency / percent). */

package/dist/recordFields.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recordFields.d.ts","sourceRoot":"","sources":["../src/recordFields.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAoB1B;;;GAGG;AACH,eAAO,MAAM,aAAa,aAIxB,CAAC;AAEH,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,OAAO,CAG9D;AAKD,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,aAE9B,CAAC;AAEH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUxE;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAClG,wEAAwE;IACxE,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;QACd,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CAoCtE;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,OAAO,CAKzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,SAAS,EACpB,cAAc,CAAC,EAAE,MAAM,EAKvB,aAAa,CAAC,EAAE,MAAM,GACrB,KAAK,CAAC,SAAS,CAiDjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAMhD"}
+{"version":3,"file":"recordFields.d.ts","sourceRoot":"","sources":["../src/recordFields.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAyB1B;;;GAGG;AACH,eAAO,MAAM,aAAa,aAIxB,CAAC;AAEH,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,OAAO,CAG9D;AAKD,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,aAE9B,CAAC;AAyIH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,KAAK,EAAE,GAAG,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;;;OASG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAUxE;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,GAAG,CAAC,EAAE,GAAG,CAAC;IACV,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC;IAClG;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,SAAS,CA8CtE;AAED,oFAAoF;AACpF,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG,OAAO,CAKzF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,GAAG,EACV,SAAS,EAAE,SAAS,EACpB,cAAc,CAAC,EAAE,MAAM,EAKvB,aAAa,CAAC,EAAE,MAAM,GACrB,KAAK,CAAC,SAAS,CA4EjB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CAMhD"}

package/dist/retired-node-types.d.ts

@@ -0,0 +1,29 @@
+import { default as React } from 'react';
+/**
+ * The bare name of every retired spelling, mapped to the refusal text the
+ * tombstone renders and logs. Keyed by the BARE name because that is what
+ * `ComponentRegistry.register` takes; the namespace is spelled at the call.
+ *
+ * The message names BOTH halves deliberately — the spelling that was written
+ * and the spelling that replaces it. A refusal that only says "unknown" is the
+ * one this table exists to stop being.
+ */
+export declare const RETIRED_DASHBOARD_NODE_TYPES: Readonly<Record<string, string>>;
+/**
+ * Log a retired node-type spelling once. Exported for the pin test, which has
+ * to be able to observe a SECOND occurrence being suppressed without inventing
+ * its own copy of the set.
+ */
+export declare function reportRetiredDashboardNodeType(spelling: string): void;
+/** Test seam: forget what has been reported, so a pin can measure the first one. */
+export declare function resetRetiredDashboardNodeTypeReports(): void;
+/**
+ * The widget a RETIRED dashboard node-type spelling renders.
+ *
+ * The rendered text and the logged text are the SAME string, read from
+ * {@link RETIRED_DASHBOARD_NODE_TYPES}. A pin that asserts only "nothing
+ * rendered" cannot tell this refusal apart from the key having been deleted
+ * outright, which is why the text is part of the contract and not decoration.
+ */
+export declare const RetiredDashboardNodeTombstone: React.FC<Record<string, unknown>>;
+//# sourceMappingURL=retired-node-types.d.ts.map

package/dist/retired-node-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retired-node-types.d.ts","sourceRoot":"","sources":["../src/retired-node-types.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;GAQG;AACH,eAAO,MAAM,4BAA4B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOxE,CAAC;AAKH;;;;GAIG;AACH,wBAAgB,8BAA8B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAOrE;AAED,oFAAoF;AACpF,wBAAgB,oCAAoC,IAAI,IAAI,CAE3D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,EAAE,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAwB3E,CAAC"}

package/dist/schemaHostProps.d.ts

@@ -1,10 +1,4 @@
-/**
- * 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 { DomProps } from '@object-ui/core';
 /**
  * The props `SchemaRenderer` hands a widget that are NOT DOM attributes
  * (objectui#4357).
@@ -43,10 +37,21 @@
  *
  * The line this type draws is **"is the key an HTML attribute name"**. None of
  * the seven is (the two dashed `aria-*` forms the renderer emits itself are, and
- * they keep flowing). Everything that IS one stays in the spread and reaches the
- * DOM exactly as before: `id`, `name`, `role`, `disabled`, `aria-*`, `data-*`,
- * `className`. Removing the spread instead would have been the wrong fix — it is
- * the component's only accessibility passthrough.
+ * they keep flowing). Removing the spread instead would have been the wrong fix —
+ * it is the component's only accessibility passthrough.
+ *
+ * ⚠️ That line was a DENY-LIST, and on the renderer's door it is no longer the
+ * judge. It stripped every one of the seven and the leak gate
+ * (`packages/app-shell/src/__tests__/widget-dom-leak-sweep.test.tsx`) still
+ * found the OPEN TAIL on both components — an authored key neither declares
+ * (`zzcanary`, `reference_to`, a `props: { colorVariant }` on `metric-card`, a
+ * `label` on `metric-card`) and `name` all landed as attributes, because a
+ * deny-list can only name what already exists. Per objectui#4425's phase-2
+ * ruling, what a component reached through `SchemaRenderer` may put on its
+ * element is decided by `toDomProps`' WHITELIST — see {@link hostDomProps}
+ * below. The seven are still destructured by name: they are this type's keys,
+ * and on the direct React door (below) the destructure is still what keeps them
+ * off the element.
  *
  * The renderer strips its own schema metadata (`type` / `children` / `visible` /
  * the schema's `dataSource` binding / …) before spreading, so those never
@@ -77,4 +82,43 @@ export interface SchemaHostProps {
      */
     dataSource?: unknown;
 }
+/**
+ * What a KPI card may spread onto its host element, decided by the DOOR the
+ * render came through (objectui#4425, phase-2 ruling: "a registered SDUI
+ * widget's host element receives only what passes the `toDomProps` whitelist").
+ *
+ * Both metric components have two doors, and they hand the component two
+ * different populations:
+ *
+ *   - **The renderer's door.** `SchemaRenderer` — the registry render path, and
+ *     so also an app that registers the exported component under a key of its
+ *     own — hands the component the authored node's own keys, the contents of
+ *     its `props` container, the runtime props it injects and its host's
+ *     trailing props. That set is unbounded, so only the whitelist may decide
+ *     what reaches the element: `toDomProps` keeps the SDUI contract's declared
+ *     pass-through set (`SDUI_DOM_PASS_THROUGH_KEYS`) and the `aria-*` /
+ *     `data-*` families, and drops everything else — `name`, `disabled`, the
+ *     injected adapter, every authored key neither component declares. One
+ *     executor, `@object-ui/core`'s, the
+ *     one `DashboardRenderer`'s grid container and `plugin-chatbot`'s
+ *     registrations already use — not a third list.
+ *   - **The direct React door.** A host rendering the exported component passes
+ *     typed props, and both props interfaces DECLARE `React.HTMLAttributes` as
+ *     their DOM pass-through (objectui#4426). That declaration is the
+ *     objectui#4435 pattern the ruling keeps available, so this door stays as it
+ *     was: narrowing it at runtime while the exported interface still extends
+ *     `HTMLAttributes` would type-check a `title` or an `onMouseEnter` and drop
+ *     it — declared but not delivered. Narrowing the interface itself is a
+ *     public prop-surface change, which this card's fence excludes.
+ *
+ * The discriminator is `schema`: the one key `SchemaRenderer` injects on EVERY
+ * render (the table above), declared on this type as the renderer's private
+ * door and never on either exported props interface. A direct consumer that
+ * passes it anyway has chosen the renderer's door and gets the whitelist, so a
+ * mistaken reading DROPS an attribute and never leaks one. If the renderer ever
+ * stopped injecting it, every canary the leak gate plants would reach the DOM
+ * again and the gate would go red — that sweep is what holds this function to
+ * its claim, alongside `__tests__/MetricWidget.domProps.test.tsx`.
+ */
+export declare function hostDomProps<P extends object>(schema: unknown, rest: P): P | DomProps<P>;
 //# sourceMappingURL=schemaHostProps.d.ts.map

package/dist/schemaHostProps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemaHostProps.d.ts","sourceRoot":"","sources":["../src/schemaHostProps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sEAAsE;IACtE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB"}
+{"version":3,"file":"schemaHostProps.d.ts","sourceRoot":"","sources":["../src/schemaHostProps.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,MAAM,WAAW,eAAe;IAC9B,kFAAkF;IAClF,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sDAAsD;IACtD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,2EAA2E;IAC3E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sEAAsE;IACtE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAExF"}

package/dist/useDashboardAutoRefresh.d.ts

@@ -0,0 +1,47 @@
+import { DashboardComponentSchema } from '@object-ui/types';
+/**
+ * The dashboard auto-refresh timer: ONE implementation, two mount points
+ * (objectui#8820).
+ *
+ * `DashboardGridLayout` and `DashboardRenderer` each used to carry their own
+ * copy of the same three things: a `refreshing` flag, a `handleRefresh`
+ * callback shared by the manual "Refresh All" button and the timer, and an
+ * effect that read the authored period and drove `setInterval`. The copies were
+ * identical in logic, and two copies of one rule is two places to change and
+ * one place to forget: the `refreshInterval` to `refreshIntervalSeconds` rename
+ * (objectui#7783) had to be made twice, and a copy that drifted would still
+ * pass its own component's tests.
+ *
+ * This hook is that logic, moved here. Both surfaces call it, so the authored
+ * period is read in exactly one place.
+ *
+ * - The period is `refreshIntervalSeconds`, in seconds, and nothing else. The
+ *   retired `refreshInterval` spelling is refused by the spec's
+ *   `DashboardSchema`, so no fallback reads it (AGENTS.md #0.1).
+ * - The timer runs only when the host wired `onRefresh` AND the period is
+ *   greater than zero: an absent period, `0` and a negative value all mean
+ *   "off".
+ * - The interval is armed on VALUES only: the period and whether a handler is
+ *   wired. The handler itself is read through a ref when a run happens, so a
+ *   new handler identity, from the host or from React discarding a memo, never
+ *   re-arms the interval or moves its phase, and the run still calls the
+ *   CURRENT handler (AGENTS.md #10, objectui#11004).
+ * - The indicator clears itself 600ms after each run, manual or timed.
+ *
+ * `__tests__/dashboardAutoRefreshTimer.test.tsx` mounts both surfaces and
+ * counts `onRefresh` calls under fake timers. It pins the first three points,
+ * the third under a forced memo discard; nothing pins the 600ms indicator.
+ */
+/** What a dashboard surface needs to drive its refresh affordance. */
+export interface DashboardAutoRefresh {
+    /** True while a refresh is in flight; drives the spinner and disables the button. */
+    refreshing: boolean;
+    /** Run a refresh now. Wired to both the manual button and the timer. */
+    handleRefresh: () => void;
+}
+/**
+ * Owns the refresh indicator, the manual refresh handler, and the auto-refresh
+ * interval for one dashboard surface.
+ */
+export declare function useDashboardAutoRefresh(schema: DashboardComponentSchema, onRefresh?: () => void): DashboardAutoRefresh;
+//# sourceMappingURL=useDashboardAutoRefresh.d.ts.map

package/dist/useDashboardAutoRefresh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDashboardAutoRefresh.d.ts","sourceRoot":"","sources":["../src/useDashboardAutoRefresh.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,qFAAqF;IACrF,UAAU,EAAE,OAAO,CAAC;IACpB,wEAAwE;IACxE,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B;AAoBD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,wBAAwB,EAChC,SAAS,CAAC,EAAE,MAAM,IAAI,GACrB,oBAAoB,CAsCtB"}

package/dist/utils.d.ts

@@ -1,10 +1,4 @@
-/**
- * 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 { useObjectLabel, useObjectTranslation } from '@object-ui/i18n';
 /** Returns true when the widget data config uses provider: 'object' (async data source). */
 export declare function isObjectProvider(widgetData: unknown): widgetData is {
     provider: 'object';
@@ -21,6 +15,41 @@ export declare function isObjectProvider(widgetData: unknown): widgetData is {
  * path derives headers with it when no columns were declared at all.
  */
 export declare function humanizeFieldKey(key: string): string;
+/**
+ * Resolve a chart series label — the SINGLE authority both dashboard relays
+ * (`DashboardRenderer`, `DashboardGridLayout`) call, so the three-arm decision
+ * below lives once instead of as two copies that could drift.
+ *
+ * Originated as a `DashboardRenderer`-local `useCallback` (objectui#9055,
+ * which fixed arms 2 and 3 there). `DashboardGridLayout` composed
+ * `series: [{ dataKey }]` with no `label` key on either of its branches — the
+ * legend and tooltip rendered the raw field key while the sibling relay's
+ * chart for the same widget rendered the humanized one (objectui#9172). That
+ * card is what moved this here rather than growing a second copy of the
+ * three-arm logic: a helper duplicated across the two relays is exactly the
+ * "one value, two spellings" class `56f4e34c0` ruled out.
+ *
+ * ⭐ THREE ARMS, and only the last two derive a display string from a FIELD
+ * KEY:
+ *
+ *   arm 1  synthetic y-field ('value' / 'count' / '') + an aggregate function
+ *          -> an i18n'd aggregate name (Count / Sum / Average …), so a
+ *          fieldless count aggregate doesn't leak the placeholder 'value' /
+ *          'count' string into the legend / tooltip.
+ *   arm 2  a real object + a real field -> `fieldLabel`'s bundle lookup, with
+ *          the HUMANIZED key (not the raw one) as its fallback.
+ *   arm 3  no object name at all (a static-data chart) -> the humanized key
+ *          outright.
+ *
+ * `t` and `fieldLabel` are injected rather than the hooks themselves, so this
+ * stays a plain function callable from either relay's own
+ * `useObjectTranslation()` / `useObjectLabel()` instances — no shared hook
+ * identity to manage, and each relay keeps memoizing its own `useCallback`
+ * wrapper over this (objectui#10's caution against depending on a memo's
+ * IDENTITY is about correctness, not about composing plain functions like
+ * this one).
+ */
+export declare function composeSeriesLabel(t: ReturnType<typeof useObjectTranslation>['t'], fieldLabel: ReturnType<typeof useObjectLabel>['fieldLabel'], objectName: string | undefined, yField: string, aggFn: string | undefined): string;
 /**
  * Columns for a STATIC (inline `options.data`) table widget whose author
  * declared none — objectui#4618.
@@ -48,6 +77,19 @@ export declare function deriveStaticTableColumns(rows: unknown): Array<{
 }>;
 export { resolveDateMacros, resolveFilterPlaceholders } from '@object-ui/core';
 export { shiftFilterByCompareTo, compareToTrendLabelKey, type CompareToConfig, } from '@object-ui/core';
+/**
+ * A period-over-period delta as `computeMetricDelta` returns it.
+ *
+ * `value` is the absolute percentage change, or `null` when the change has no
+ * percentage: a zero baseline with a non-zero current value (objectui#12677).
+ * Going from 0 to 10 is not a 100% increase — a percent change from zero is
+ * undefined — so the delta keeps its direction and states no number. Every
+ * reader draws it through {@link formatMetricDeltaPercent}.
+ */
+export interface MetricDelta {
+    value: number | null;
+    direction: 'up' | 'down' | 'neutral';
+}
 /**
  * Compute a percentage delta between the current and previous metric values.
  *
@@ -56,13 +98,18 @@ export { shiftFilterByCompareTo, compareToTrendLabelKey, type CompareToConfig, }
  * - previousValue is null / undefined (no comparison data)
  *
  * Edge cases:
- * - both 0 → neutral
- * - previous is 0 and current ≠ 0 → 100% in current's direction
+ * - both 0 → neutral, `value: 0`
+ * - previous is 0 and current ≠ 0 → current's direction, `value: null` (no
+ *   percentage is defined from a zero baseline; objectui#12677)
  * - previous is negative → uses |previous| as denominator so that "less
  *   negative" reads as a positive (up) delta.
  */
-export declare function computeMetricDelta(current: number | null | undefined, previous: number | null | undefined): {
-    value: number;
-    direction: 'up' | 'down' | 'neutral';
-} | null;
+export declare function computeMetricDelta(current: number | null | undefined, previous: number | null | undefined): MetricDelta | null;
+/**
+ * The text a delta badge draws for {@link MetricDelta.value}: `20%` for a
+ * defined percentage, and an em dash — never a number — when there is none
+ * (a zero baseline, objectui#12677). A symbol, not a word, so no locale pack
+ * carries it. The direction arrow beside it still says which way it moved.
+ */
+export declare function formatMetricDeltaPercent(value: number | null): string;
 //# sourceMappingURL=utils.d.ts.map