@object-ui/plugin-dashboard 17.6.0 → 17.7.0

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/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/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.

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,OAAO,GAAG,UAAU,IAAI;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,GAAG,CAAA;CAAE,CAO1I;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAOtG;AAUD,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAG/E,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,IAAI,CAkBhE"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,OAAO,GAAG,UAAU,IAAI;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,GAAG,CAAA;CAAE,CAO1I;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CASpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,kBAAkB,CAChC,CAAC,EAAE,UAAU,CAAC,OAAO,oBAAoB,CAAC,CAAC,GAAG,CAAC,EAC/C,UAAU,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,YAAY,CAAC,EAC3D,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GAAG,SAAS,GACxB,MAAM,CAUR;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAAC,CAOtG;AAUD,OAAO,EAAE,iBAAiB,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAG/E,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAClC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,IAAI,CAkBhE"}

package/dist/widgetDispatch.d.ts

@@ -1,26 +1,66 @@
+import { BaseSchema, DashboardComponentSchema, DashboardWidgetSchema, DashboardWidgetSlotComponentSchema, DashboardWidgetTypeName } from '@object-ui/types';
+import { MetricWidgetProps } from './MetricWidget.js';
 /**
- * ObjectUI
- * Copyright (c) 2024-present ObjectStack Inc.
+ * One entry of a dashboard's `widgets[]`: the slot's element type, a widget or
+ * a component node placed directly in the slot (the 2026-08-14 `metric-card`
+ * slot ruling, objectstack#8593). Read off `DashboardComponentSchema.widgets`,
+ * so it is the slot's own declaration, not a restatement.
  *
- * This source code is licensed under the MIT license found in the
- * LICENSE file in the root directory of this source tree.
+ * Every dashboard surface reads `widgets[]` entries by this type
+ * (objectui#11514). The widget arm, `DashboardWidgetSchema`, is not a read type
+ * for an entry: since objectui#11483's closure its `type` names the widget
+ * vocabulary only, so the component arm is not assignable to it.
  */
+export type DashboardWidgetSlotEntry = DashboardComponentSchema['widgets'][number];
+export declare function specDefaultWidgetType(): DashboardWidgetTypeName;
 /**
- * Widget-type → dispatch family, shared by every dashboard surface.
+ * The `type` a dashboard surface draws a `widgets[]` entry as: the authored
+ * `type`, or {@link specDefaultWidgetType} when the entry names none
+ * (objectui#11514, Q2 A). Every read of an entry's `type` on the two surfaces
+ * goes through it — the dispatch, the metric span and chrome, the mobile
+ * metric row — so a typeless widget draws exactly as the same widget with
+ * `type: 'metric'` does. It used to reach the slot-component passthrough and
+ * draw the registry's red OBJUI-001 panel.
  *
- * Three surfaces used to restate this knowledge independently and disagree:
- * `DatasetWidget` covered all 19 `ChartTypeSchema` values, `DashboardRenderer`
- * covered 15, and `DashboardGridLayout` 8. A type the surface didn't name fell
- * through to `{ ...widget }`, whose `type` no component registers — so
- * `SchemaRenderer` rendered a red `role="alert"` panel dumping the widget JSON
- * (#2943).
- *
- * The single-value families were the sharpest case: `DashboardRenderer` already
- * had `METRIC_LIKE_TYPES = ['gauge','solid-gauge','kpi','bullet']` with a
- * docstring saying they "render as a metric card rather than a chart" — and
- * consulted it only to pick a grid span. The tile was sized correctly and the
- * widget was never routed.
+ * ⛔ Not for the legacy `component` envelope (`{ id, component, layout }`,
+ * objectui's own format, which the spec's widget has no member for). It draws
+ * its node, never a family, so the spec's default `type` says nothing about it:
+ * an envelope that names no `type` keeps `undefined` here and draws, chrome
+ * included, as it always did.
+ */
+export declare function resolveWidgetType(entry: DashboardWidgetSlotEntry): DashboardWidgetSlotEntry['type'];
+/**
+ * The node an entry's legacy `component` envelope holds, typed as the widget
+ * arm declares that member (`DashboardWidgetSchema['component']`). Read off the
+ * entry whichever arm it is, as the surfaces always read it. The component arm
+ * declares no `component`, so a bare `entry.component` on the slot entry reads
+ * through `BaseSchema`'s index signature and is `any` — which made each
+ * surface's whole `getComponentSchema` return `any` (objectui#11514).
+ */
+export declare function entryComponent(entry: DashboardWidgetSlotEntry): DashboardWidgetSchema['component'];
+/**
+ * Whether a slot entry is the component arm, `DashboardWidgetSlotComponentSchema`:
+ * its `type` is a member of the closed `DASHBOARD_COMPONENT_WIDGET_TYPES`, which
+ * no widget `type` names (objectui#11483). Read at runtime, so a stored entry
+ * whose `type` is a string outside every vocabulary is NOT the component arm.
+ */
+export declare function isSlotComponentEntry(entry: DashboardWidgetSlotEntry): entry is DashboardWidgetSlotComponentSchema;
+/**
+ * The labelled placeholder a dashboard surface draws for a widget `type` it
+ * has no renderer for: a known family with no renderer yet
+ * (`UNSUPPORTED_CHART_TYPES`), and, since objectui#11514 (Q2 A), a `type` that
+ * names no family at all — stale metadata both validator faces refuse at
+ * `type`, which used to fall through to the slot-component passthrough and
+ * draw the registry's red OBJUI-001 panel dumping the widget. One declaration
+ * for both surfaces, which each spelled it out before.
  */
+export declare function unsupportedWidgetSchema(widgetType: string | undefined): {
+    readonly type: "text";
+    readonly content: `\u300C${string}\u300Dchart type is not supported yet`;
+    readonly variant: "caption";
+    readonly align: "center";
+    readonly className: "flex h-full w-full items-center justify-center rounded border border-dashed bg-muted/20 p-4 text-muted-foreground";
+};
 /**
  * Spec chart families that only render as another family. Normalizing them
  * here is what lets one branch serve `column` and `bar` (the spec's own
@@ -28,6 +68,16 @@
  */
 export declare const CHART_TYPE_ALIASES: Record<string, string>;
 /** Cartesian / categorical / flow families the chart renderer draws. */
+declare const SERIES_CHART_FAMILIES: readonly ["bar", "horizontal-bar", "line", "area", "pie", "donut", "scatter", "funnel", "radar", "treemap", "sankey", "combo"];
+/**
+ * A family {@link SERIES_CHART_TYPES} names, as a literal union: the
+ * `chartType` a `series` dispatch carries. Each member is one of the families
+ * `ObjectChartSchema.chartType` declares (objectui#11513), so the `object-chart`
+ * node a surface builds from a dispatch names its family with no cast
+ * (objectui#11514). Pinned by `__tests__/dashboard-producer-node-types-11514.test.ts`.
+ */
+export type SeriesChartFamily = (typeof SERIES_CHART_FAMILIES)[number];
+/** Cartesian / categorical / flow families the chart renderer draws. */
 export declare const SERIES_CHART_TYPES: ReadonlySet<string>;
 /**
  * Single-value "performance" families — one number, optionally against a
@@ -65,7 +115,7 @@ export type WidgetDispatchFamily =
 export interface WidgetDispatch {
     family: WidgetDispatchFamily;
     /** For `series`: the alias-resolved base family to draw. */
-    chartType?: string;
+    chartType?: SeriesChartFamily;
 }
 /**
  * Classify a widget `type` into its dispatch family. Exported for the
@@ -73,4 +123,80 @@ export interface WidgetDispatch {
  * `passthrough` (the branch that produces the red box).
  */
 export declare function classifyWidgetType(widgetType: string | undefined): WidgetDispatch;
+/**
+ * The node key a dashboard surface hands `SchemaRenderer` for each component
+ * this package registers with `skipFallback: true` (objectui#10859 batch 8,
+ * phase 2b, seat ruling M3 option A).
+ *
+ * `metric` and `metric-card` are two vocabularies that happened to share one
+ * spelling: the dashboard WIDGET type (the spec's `ChartTypeSchema` value
+ * `metric`; the 2026-08-14 slot ruling's `metric-card`, objectstack#8593) and
+ * the internal NODE key the dashboard renders that widget through. The widget
+ * vocabulary is untouched. Only the node key moved: the registrations publish
+ * `plugin-dashboard:metric` / `plugin-dashboard:metric-card` and no bare
+ * fallback, so nothing authors a bare `metric` / `metric-card` NODE that the
+ * registry mounts while `objectui validate` refuses it at `type`.
+ *
+ * ⛔ Both surfaces (`DashboardRenderer`, `DashboardGridLayout`) emit through
+ * this table, so they cannot drift apart; a new `skipFallback` registration in
+ * this package that a widget can reach gets its row here in the same edit.
+ *
+ * The values are literal types (objectui#11466), so a node a surface builds
+ * under `DASHBOARD_NODE_TYPES.metric` is discriminated by its key and checked
+ * against {@link DashboardMetricNodeSchema}, the `CustomNodeRegistry` entry
+ * below. A lookup by an authored `type` string goes through the string-keyed
+ * view {@link toDashboardNodeType} reads.
+ */
+export declare const DASHBOARD_NODE_TYPES: {
+    readonly metric: "plugin-dashboard:metric";
+    readonly 'metric-card': "plugin-dashboard:metric-card";
+};
+/**
+ * The `plugin-dashboard:metric` node: what both dashboard surfaces hand
+ * `SchemaRenderer` for a `metric` widget drawn inline, and what the `metric`
+ * registration (`skipFallback: true`) mounts as `MetricWidget`.
+ *
+ * Declared in `@object-ui/types`' `CustomNodeRegistry` (objectui#11466, as
+ * objectui#11479's Q1 A ruled), the registry an application augments for the
+ * node types it registers that `@object-ui/types` does not declare. So the
+ * producers name a declared node type, and `SchemaRenderer` takes the node
+ * with no cast. The key is this package's: `@object-ui/types` cannot name a
+ * plugin's namespace.
+ *
+ * Its keys are the ones `MetricWidget` reads off the node, typed by that
+ * component's props so the two cannot disagree. Host state (`loading`,
+ * `error`) and the `onClick` handler are props, ⛔ not node keys.
+ */
+export interface DashboardMetricNodeSchema extends BaseSchema {
+    type: typeof DASHBOARD_NODE_TYPES.metric;
+    label: MetricWidgetProps['label'];
+    value: MetricWidgetProps['value'];
+    description?: MetricWidgetProps['description'];
+    trend?: MetricWidgetProps['trend'];
+    /** A Lucide icon name. A React element is a host prop, never a node key. */
+    icon?: string;
+    colorVariant?: MetricWidgetProps['colorVariant'];
+    format?: MetricWidgetProps['format'];
+    currency?: MetricWidgetProps['currency'];
+    prefix?: MetricWidgetProps['prefix'];
+    suffix?: MetricWidgetProps['suffix'];
+    variant?: MetricWidgetProps['variant'];
+}
+declare module '@object-ui/types' {
+    interface CustomNodeRegistry {
+        'plugin-dashboard:metric': DashboardMetricNodeSchema;
+    }
+}
+/**
+ * `node` with its `type` moved onto the namespaced key {@link
+ * DASHBOARD_NODE_TYPES} names, or `node` itself when the type has no row.
+ *
+ * Applied where a surface forwards a node it did not build: the slot-component
+ * passthrough (`{ type: 'metric-card', ... }` directly in `widgets[]`) and an
+ * author-supplied `widget.component`. Both are widget-vocabulary positions,
+ * which keep their spelling; this is the boundary where the widget becomes a
+ * node.
+ */
+export declare function toDashboardNodeType<T>(node: T): T;
+export {};
 //# sourceMappingURL=widgetDispatch.d.ts.map

package/dist/widgetDispatch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widgetDispatch.d.ts","sourceRoot":"","sources":["../src/widgetDispatch.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;GAeG;AAEH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAUrD,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CASjD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAEhD,CAAC;AAEH,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAA8B,CAAC;AAEhF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAGtD,CAAC;AAEH,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB;AAC9B,mEAAmE;AACjE,QAAQ;AACV,kCAAkC;GAChC,QAAQ;AACV,uBAAuB;GACrB,OAAO;AACT,6EAA6E;GAC3E,OAAO;AACT,iDAAiD;GAC/C,QAAQ;AACV,wDAAwD;GACtD,aAAa;AACf,sEAAsE;GACpE,aAAa,CAAC;AAElB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,oBAAoB,CAAC;IAC7B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAUjF"}
+{"version":3,"file":"widgetDispatch.d.ts","sourceRoot":"","sources":["../src/widgetDispatch.ts"],"names":[],"mappings":"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"}

package/dist/widgetSubCaption.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 structural minimum this resolution reads. Deliberately not
+ * `DashboardWidgetSchema`: the two surfaces hold their widgets at two different
+ * static types (the grid holds the `DashboardWidgetSlotComponentSchema |
+ * DashboardWidgetSchema` union its `widgets` slot declares), and both satisfy
+ * this shape. `options` is `unknown` because that is what
+ * `DashboardWidgetSchema` declares it as.
+ */
+export interface SubCaptionWidget {
+    id?: string;
+    options?: unknown;
+}
+/**
+ * Resolve a dataset/metric widget's sub-caption for the active UI language.
+ *
+ * `dashName` is the dashboard schema's `name` — the segment every convention
+ * key on this surface is built from. Without it (or without a widget `id`)
+ * there is no key to look up, so the authored limb answers alone; that is the
+ * same silent degradation `tWidgetTitle` / `tWidgetDescription` perform, not a
+ * new one.
+ *
+ * `localized` is the host's word that the document was served already
+ * translated (`DashboardRendererProps.localized`): the authored limb then
+ * answers alone, because the served value IS the translation.
+ *
+ * Provider-safe: `useObjectLabel` and `useObjectTranslation` both degrade to a
+ * no-instance stand-in when no `I18nProvider` is mounted (objectui#5564), which
+ * `DashboardGridLayout` depends on — it is a separately exported component a
+ * host mounts standalone (its `dashboard-grid` node key was retired by
+ * objectui#10859 batch 8).
+ */
+export declare function useWidgetSubCaption(dashName: string | undefined, localized?: boolean): (widget: SubCaptionWidget) => string | undefined;
+//# sourceMappingURL=widgetSubCaption.d.ts.map

package/dist/widgetSubCaption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widgetSubCaption.d.ts","sourceRoot":"","sources":["../src/widgetSubCaption.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA4EH;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC/B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,SAAS,UAAQ,GAChB,CAAC,MAAM,EAAE,gBAAgB,KAAK,MAAM,GAAG,SAAS,CAalD"}