@object-ui/plugin-dashboard 17.2.0 → 17.5.0

package/README.md

@@ -219,21 +219,36 @@ into each bound widget's inline query (`AND`-combined with the widget's own
       "field": "region",            // default binding target
       "label": "Region",
       "type": "select",             // text | select | date | number | lookup
-      "options": ["EMEA", "APAC", "AMER"]
+      // Canonical @objectstack/spec pair form — the only form the platform
+      // accepts at publish. The bare-string shorthand (["EMEA", …]) is
+      // deprecated: still lifted at runtime, now warns (objectui#4356).
+      "options": [
+        { "value": "EMEA", "label": "EMEA" },
+        { "value": "APAC", "label": "APAC" },
+        { "value": "AMER", "label": "AMER" }
+      ]
       // or dynamic: "optionsFrom": { "object": "accounts", "valueField": "region" }
     }
   ],
   "widgets": [
+    // Widgets bind a semantic-layer dataset (ADR-0021) and select its
+    // dimensions/measures by name. The pre-ADR-0021 top-level `object` +
+    // `categoryField`/`valueField`/`aggregate` shape was REMOVED — a widget
+    // still carrying it renders "This widget uses a retired data format.
+    // Edit it to bind a dataset." instead of a chart. A renderer-internal
+    // query lives under `options.data` as `{ provider: 'object', object,
+    // aggregate }`; an `options.data` array is fixed demo data.
+    //
     // Default binding: the filter's own `field` (dateRange → created_at).
-    { "id": "w1", "type": "bar", "object": "invoices", "aggregate": "count" },
+    { "id": "w1", "type": "bar", "dataset": "invoices", "dimensions": ["status"], "values": ["count"] },
     // Explicit binding: map each filter to THIS widget's own field.
     {
-      "id": "w2", "type": "line", "object": "accounts", "aggregate": "count",
+      "id": "w2", "type": "line", "dataset": "accounts", "dimensions": ["signed_month"], "values": ["count"],
       "filterBindings": { "dateRange": "signed_at", "region": "sales_region" }
     },
     // Opt out of a filter with `false`.
     {
-      "id": "w3", "type": "metric", "object": "invoices", "aggregate": "count",
+      "id": "w3", "type": "metric", "dataset": "invoices", "values": ["count"],
       "filterBindings": { "region": false }
     }
   ]
@@ -267,6 +282,39 @@ Notes:
   warning instead of emitting a query that matches nothing. Explicit
   `filterBindings` strings are always honoured as written.
 
+## Widget accent colour (`colorVariant`)
+
+A KPI widget can declare a semantic accent. The vocabulary is
+`@objectstack/spec`'s `WidgetColorVariantSchema` enum — `default`, `blue`,
+`teal`, `orange`, `purple`, `success`, `warning`, `danger` — the same eight
+tokens the designer's swatch picker offers:
+
+```typescript
+{
+  id: 'kpi_at_risk',
+  type: 'metric',
+  title: 'At-Risk Projects',
+  dataset: 'project_health',
+  values: ['project_count'],
+  filter: { health: 'red' },
+  colorVariant: 'danger',   // tints the value; card chrome stays neutral
+}
+```
+
+Where the accent lands depends on the layout, not on the token:
+
+| Layout | Accent |
+| --- | --- |
+| Card chrome (`MetricWidget`, inline `object-metric`) | the icon chip's background + foreground |
+| Chrome-less (`MetricWidget variant: 'bare'`, and every dataset-bound `metric`) | the big number's text colour |
+
+Both read one shared table (`src/colorVariants.ts`), so the same declaration
+reads the same on either surface. `default` — and omitting the key — means "no
+accent"; the widget renders in the ambient foreground colour. A token outside
+the enum gets no accent and is not aliased to a nearby colour: it is invalid
+metadata, rejected where it is authored and published rather than reinterpreted
+here.
+
 ## TypeScript Support
 
 ```typescript
@@ -386,17 +434,6 @@ file system, …) per the protocol-agnostic architecture rule.
 > dashboards. If you still want a browser-local cache for a demo, do it
 > in the parent inside `onSchemaChange`.
 
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
-
 ## Links
 
 - 📚 [Documentation](https://www.objectui.org/docs/plugins/plugin-dashboard)

package/dist/DashboardFilterBar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DashboardFilterBar.d.ts","sourceRoot":"","sources":["../src/DashboardFilterBar.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH,OAAO,KAAuC,MAAM,OAAO,CAAC;AAiB5D,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAOzB,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA2ND,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,uBAAuB,4BAyCrH"}
+{"version":3,"file":"DashboardFilterBar.d.ts","sourceRoot":"","sources":["../src/DashboardFilterBar.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;GAQG;AAEH,OAAO,KAAuC,MAAM,OAAO,CAAC;AAiB5D,OAAO,EAEL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAoCzB,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,kBAAkB,EAAE,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAC7C,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkSD,wBAAgB,kBAAkB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,EAAE,uBAAuB,4BAyCrH"}

package/dist/DashboardGridLayout.d.ts

@@ -4,6 +4,33 @@ import * as React from 'react';
 export interface DashboardGridLayoutProps {
     schema: DashboardComponentSchema;
     className?: string;
+    /**
+     * Data-source adapter for the widgets this grid renders, handed to
+     * `DatasetWidget` for ADR-0021 dataset-bound widgets (objectui#4614).
+     *
+     * Typed `unknown`, not `any`. The sibling declares `dataSource?: any`
+     * (`DashboardRenderer.tsx:198`) for a reason that is explicitly historical —
+     * "that is precisely what it resolved to before", via the index signature that
+     * used to answer for it — and this is a NEW declaration with no prior
+     * resolution to preserve. `unknown` is what the consumer itself declares
+     * (`DatasetWidget.tsx:655`, `dataSource: unknown`), so the value is forwarded
+     * to exactly the type that receives it, and no call site is held to anything
+     * new: every value is assignable to `unknown`. Narrowing it further to a real
+     * adapter type is a separate change with its own consumer sweep, on both
+     * surfaces at once.
+     *
+     * Optional, and the omitted case is a SUPPORTED one rather than an oversight:
+     * `dashboard-grid`'s SDUI registration declares only `title` / `className`
+     * inputs, so schema-driven hosts render this component with no adapter at all.
+     * A dataset-bound widget arriving that way renders `DatasetWidget`'s own
+     * no-capability diagnostic — a visible state, never a blank tile.
+     *
+     * `SchemaRenderer` forwards this as a React prop (its `...props` spread, last:
+     * `SchemaRenderer.tsx:632`). It cannot be shadowed by the spec's per-element
+     * `dataSource` BINDING, which is stripped from the schema before that spread
+     * for exactly this reason (`SchemaRenderer.tsx:564-575`, objectstack#5576).
+     */
+    dataSource?: unknown;
     /**
      * Fires on every drag/resize tick with the raw react-grid-layout payload.
      * Useful for live previews; NOT a persistence hook.

package/dist/DashboardGridLayout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DashboardGridLayout.d.ts","sourceRoot":"","sources":["../src/DashboardGridLayout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAA2C,KAAK,UAAU,IAAI,SAAS,EAAuC,MAAM,mBAAmB,CAAC;AAC/I,OAAO,kCAAkC,CAAC;AAI1C,OAAO,KAAK,EAAE,wBAAwB,EAAyB,MAAM,kBAAkB,CAAC;AA4BxF,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,IAAI,CAAC;IAC/C;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAC;IAC5D,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,wBAAwB,EAChC,MAAM,EAAE,SAAS,EAAE,GAClB,wBAAwB,CAa1B;AAcD,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,wBAAwB,CA6UlE,CAAC"}
+{"version":3,"file":"DashboardGridLayout.d.ts","sourceRoot":"","sources":["../src/DashboardGridLayout.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAC/B,OAAO,EAA2C,KAAK,UAAU,IAAI,SAAS,EAAuC,MAAM,mBAAmB,CAAC;AAC/I,OAAO,kCAAkC,CAAC;AAK1C,OAAO,KAAK,EAAc,wBAAwB,EAAyB,MAAM,kBAAkB,CAAC;AA8BpG,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,IAAI,CAAC;IAC/C;;;;;;;;;OASG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,wBAAwB,KAAK,IAAI,CAAC;IAC5D,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,wBAAwB,EAChC,MAAM,EAAE,SAAS,EAAE,GAClB,wBAAwB,CAa1B;AAcD,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,EAAE,CAAC,wBAAwB,CA+blE,CAAC"}

package/dist/DashboardRenderer.d.ts

@@ -1,8 +1,51 @@
 import { DashboardComponentSchema, DashboardWidgetSchema } from '@object-ui/types';
-import { ActionDef, ActionResult, ActionContext, ModalHandler } from '@object-ui/core';
-export interface DashboardRendererProps {
+import { ActionDef, ActionResult, ActionContext, ModalHandler, SduiDomPassThroughKey } from '@object-ui/core';
+import { HTMLAttributes } from 'react';
+/**
+ * The dashboard renderer's props.
+ *
+ * ## Why there is no `[key: string]: any` here (objectui#4528)
+ *
+ * There used to be one, and it erased this entire interface. A string index
+ * signature puts `string` into `keyof Props`, so `'ref' extends keyof Props` is
+ * always true and React's `PropsWithoutRef` takes its `Omit` branch —  and
+ * `Omit` over a type carrying a string index signature keeps ONLY the index
+ * signature. Every declared property above was dropped from the resolved type:
+ * `keyof React.ComponentProps< typeof DashboardRenderer >` measured as
+ * `string | number`, and `onWidgetClick` measured as `any` at every JSX call
+ * site, while this interface went on declaring
+ * `(widgetId: string | null) => void`. The declaration was right and no
+ * consumer was held to it — a prop typo or a wrong-arity handler type-checked.
+ *
+ * The same trap, in `packages/components`, is objectui#4422 / PR #4438; this is
+ * the sweep of the two packages that issue left unswept.
+ *
+ * ## How the DOM pass-through survives without it
+ *
+ * `SchemaRenderer` hands this component the authored node's own keys, so the
+ * render function still collects an open rest object — but what may reach the
+ * element is decided by `toDomProps`' WHITELIST (objectui#4432), not by this
+ * type. The keys that whitelist forwards are therefore declared here BY NAME,
+ * derived from the whitelist constant itself so the two cannot drift, which is
+ * exactly what `@object-ui/core`'s `dom-props` doctrine asks for: "Deliberate
+ * DOM pass-through beyond this set stays available the objectui#4435 way —
+ * DECLARE it and forward it by name. Do not reopen the spread."
+ */
+export interface DashboardRendererProps extends Pick<HTMLAttributes<HTMLDivElement>, SduiDomPassThroughKey> {
     schema: DashboardComponentSchema;
     className?: string;
+    /**
+     * Data-source adapter for the widgets this dashboard renders.
+     *
+     * Destructured by the render function and handed to `DatasetWidget` /
+     * `SchemaRenderer`, and passed by both in-repo hosts (`DashboardView`,
+     * `DashboardPreview`) — but never declared until objectui#4528, because the
+     * index signature above was answering for it. Typed `any` deliberately: that
+     * is precisely what it resolved to before, so declaring it changes what is
+     * DECLARED without changing what any call site is held to. Narrowing it to a
+     * real adapter type is a separate change with its own consumer sweep.
+     */
+    dataSource?: any;
     /** Callback invoked when dashboard refresh is triggered (manual or auto) */
     onRefresh?: () => void;
     /** Total record count to display */
@@ -37,7 +80,6 @@ export interface DashboardRendererProps {
      * title/subtitle so we don't display them twice.
      */
     hideHeaderText?: boolean;
-    [key: string]: any;
 }
 /**
  * DashboardRenderer — the public dashboard renderer.
@@ -54,5 +96,5 @@ export interface DashboardRendererProps {
  * stay readable inside widget subtrees, and only a same-named filter shadows
  * the outer variable.
  */
-export declare const DashboardRenderer: import('react').ForwardRefExoticComponent<Omit<DashboardRendererProps, "ref"> & import('react').RefAttributes<HTMLDivElement>>;
+export declare const DashboardRenderer: import('react').ForwardRefExoticComponent<DashboardRendererProps & import('react').RefAttributes<HTMLDivElement>>;
 //# sourceMappingURL=DashboardRenderer.d.ts.map

package/dist/DashboardRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DashboardRenderer.d.ts","sourceRoot":"","sources":["../src/DashboardRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGxF,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAsJ5F,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,IAAI,CAAC;IAC9D,mGAAmG;IACnG,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wGAAwG;IACxG,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC,CAAC;IACrH;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAyuBD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,gIAiB7B,CAAC"}
+{"version":3,"file":"DashboardRenderer.d.ts","sourceRoot":"","sources":["../src/DashboardRenderer.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAc,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAGpG,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAUnH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AAmI5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,sBACf,SAAQ,IAAI,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,qBAAqB,CAAC;IACnE,MAAM,EAAE,wBAAwB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,GAAG,CAAC;IACjB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iCAAiC;IACjC,WAAW,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACrE,kEAAkE;IAClE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gDAAgD;IAChD,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uDAAuD;IACvD,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IAClD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,EAAE,KAAK,IAAI,CAAC;IAC9D,mGAAmG;IACnG,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,wGAAwG;IACxG,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,YAAY,CAAC,CAAC;IACrH;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAg3BD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB,mHAiB7B,CAAC"}

package/dist/DashboardWithConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DashboardWithConfig.d.ts","sourceRoot":"","sources":["../src/DashboardWithConfig.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,wBAAwB,EAAyB,MAAM,kBAAkB,CAAC;AAKxF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAMnE,MAAM,WAAW,wBAAwB;IACvC,qCAAqC;IACrC,MAAM,EAAE,wBAAwB,CAAC;IACjC,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,6DAA6D;IAC7D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IACpD,iEAAiE;IACjE,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IACvE,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACvC,oDAAoD;IACpD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,WAAW,EACX,iBAAyB,EACzB,SAAS,EACT,QAAQ,EACR,eAAe,GAChB,EAAE,wBAAwB,qBAyJ1B"}
+{"version":3,"file":"DashboardWithConfig.d.ts","sourceRoot":"","sources":["../src/DashboardWithConfig.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,wBAAwB,EAAyB,MAAM,kBAAkB,CAAC;AAKxF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,mBAAmB,CAAC;AAMnE,MAAM,WAAW,wBAAwB;IACvC,qCAAqC;IACrC,MAAM,EAAE,wBAAwB,CAAC;IACjC,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,6DAA6D;IAC7D,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IACpD,iEAAiE;IACjE,YAAY,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,KAAK,IAAI,CAAC;IACvE,2DAA2D;IAC3D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,yBAAyB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iDAAiD;IACjD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,yBAAyB,EAAE,CAAC;IACvC,oDAAoD;IACpD,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,MAAM,EACN,MAAM,EACN,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,WAAW,EACX,iBAAyB,EACzB,SAAS,EACT,QAAQ,EACR,eAAe,GAChB,EAAE,wBAAwB,qBAuK1B"}

package/dist/DatasetWidget.d.ts

@@ -1,19 +1,44 @@
-import { buildDatasetDrillFilter } from '@object-ui/core';
+import { buildDatasetDrillFilter, pivotCellKey, ChartSeriesBinding } from '@object-ui/core';
 /**
  * Build the record-list filter for a drilled row. Re-exported for back-compat;
  * the implementation now lives in `@object-ui/core` (`buildDatasetDrillFilter`)
  * so the dashboard and the report renderer drill identically.
  */
 export declare const buildDrillFilter: typeof buildDatasetDrillFilter;
+/**
+ * The pivot key encoders, re-exported for back-compat; the implementations now
+ * live in `@object-ui/core` (`pivotBucketId` / `pivotCellKey`) so this widget
+ * and the report renderer's cross-tab key their buckets identically. See that
+ * module for why both are `JSON.stringify` rather than a delimiter character,
+ * and why an empty value encodes as JSON `null` rather than a placeholder
+ * string (objectui#4056).
+ *
+ * Every consumer of a bucket id — the cell index below, the row-total lookup
+ * AND the column-total lookup in the cross-tab renderer — must build its key
+ * with these, over values normalized by `pivotDimensionValue`; a second,
+ * hand-rolled encoding of the same id is what made the old bug invisible.
+ *
+ * `pivotRowId` is the historical name of the axis-neutral encoder, kept as an
+ * alias so this package's published surface does not change.
+ */
+declare const pivotRowId: (dimensionValues: Array<string | null>) => string;
+export { pivotRowId, pivotCellKey };
 /**
  * Pivot flat dataset rows into a cross-tab: `rowDims` go DOWN, `colDim` spreads
  * ACROSS. Returns ordered row/column headers (display labels from the rows) and
- * a map from a `${rowId} ${colId}` cell key to the FLAT row index holding
- * that combination's measure values. No re-aggregation — the dataset already
- * grouped by every dimension, so each cell maps to exactly one row (the index
- * is also what drill-through uses to read `drillRawRows`).
+ * a map from a `pivotCellKey(rowId, colId)` cell key to the FLAT row index
+ * holding that combination's measure values. No re-aggregation — the dataset
+ * already grouped by every dimension, so each cell maps to exactly one row (the
+ * index is also what drill-through uses to read `drillRawRows`).
+ *
+ * `locale` is the display-locale tag the header LABELS are formatted in
+ * (objectui#4566) — this is a plain exported function, not a component, so it
+ * cannot read `useDisplayLocale()` itself. It affects `rowHeaders`/`colHeaders`
+ * only; the `id`s are opaque keys built by `pivotBucketId` from the RAW values
+ * and are deliberately untouched by it, so a locale change can never re-key a
+ * cell (which would break the `cellIndex` lookup and drill-through with it).
  */
-export declare function buildPivot(rows: Array<Record<string, unknown>>, rowDims: string[], colDim: string): {
+export declare function buildPivot(rows: Array<Record<string, unknown>>, rowDims: string[], colDim: string, locale?: string): {
     rowHeaders: Array<{
         id: string;
         labels: string[];
@@ -26,6 +51,161 @@ export declare function buildPivot(rows: Array<Record<string, unknown>>, rowDims
 };
 /** Serialize a 2D array (first row = headers) to CSV text. */
 export declare function toCsv(rows: Array<Array<string | number | null | undefined>>): string;
+/** A `DatasetSelection.timeDimensions` entry stating a bounded window. */
+export interface DatasetTimeWindow {
+    dimension: string;
+    dateRange: [string, string];
+}
+/**
+ * Split a RESOLVED runtime filter into the bounded date windows it states and
+ * the rest of the filter (objectui#3337 point 5).
+ *
+ * The executor shifts exactly one thing for a `compareTo`: a `timeDimensions`
+ * entry carrying a `dateRange`. A widget states its window in its own `filter`
+ * instead (a date macro, or the dashboard's date-range filter merged in by
+ * `DashboardRenderer`), which is why forwarding a structured `compareTo` alone
+ * still came back "compareTo needs a dated window to shift".
+ *
+ * Windows are **moved, not copied**: the comparison pass re-runs with the
+ * shifted `timeDimensions` but the SAME `runtimeFilter`, so a copy left behind
+ * would intersect the shifted window with the current one and every
+ * `<measure>__compare` column would come back empty.
+ *
+ * Only CONJUNCTIVE positions are walked — the top level and `$and` members. A
+ * window inside `$or` / `$not` is not a window the whole query runs in, so it
+ * stays in the filter untouched.
+ *
+ * **Which dimension gets shifted is not decided here.** Every window found is
+ * lowered under the name the author wrote. Zero of them, or two, is the
+ * executor's error to raise — it names the candidates (`resolveCompareDimension`).
+ * Guessing one renderer-side would trade a loud error for a quietly wrong
+ * window, which is the failure class objectstack#5011 set out to end.
+ */
+export declare function extractDateWindows(filter: unknown): {
+    windows: DatasetTimeWindow[];
+    rest: Record<string, unknown> | undefined;
+};
+/**
+ * Lower a dashboard widget's declared `chartConfig` (spec `ChartConfigSchema` —
+ * the same shape a report block and a react `<ObjectChart>` parse) onto the
+ * chart schema this widget hands to the renderer.
+ *
+ * ## Why this is a whitelist and not a spread
+ *
+ * Until #3135 NONE of `chartConfig` reached the renderer: this widget read
+ * `options` and nothing else, so an author who wrote `showLegend: false` still
+ * got a legend and one who wrote `true` only got one because "on" is the
+ * renderer's default. #3135 lowered that single flag and left the rest declared
+ * and inert. objectstack#7016 lowers the rest of the keys that are actually
+ * DELIVERED, admitting a key only when both of these hold:
+ *
+ *  1. **The chart block draws it end to end on this path.** `{ type: 'chart' }`
+ *     resolves to `ChartRenderer` → `AdvancedChartImpl`, which draws
+ *     `title`/`subtitle` in its ChartFrame, turns `description` into the chart
+ *     container's `role="img"` + `aria-label`, applies `height` as that
+ *     container's inline height, reads `colors` as the positional palette,
+ *     prints `showDataLabels` as a Recharts `LabelList`, draws `annotations` as
+ *     ReferenceLine/ReferenceArea and honours `interaction` as the tooltip
+ *     toggle plus `Brush`. Forwarding a key the renderer ignores would only
+ *     move declared-but-not-delivered one layer down, which is the failure this
+ *     change exists to remove.
+ *  2. **It does not fight the dataset derivation.** `type` stays out: the
+ *     widget's own `type` already picks the family through `CHART_TYPE_MAP`,
+ *     which is the dataset path's chart-family channel.
+ *
+ * ## Where `xAxis` / `yAxis` / `series` go — the ruled split (#4229)
+ *
+ * Those three used to be refused here under the same criterion 2, on the
+ * grounds that they are "DERIVED from the dataset selection". That belief was
+ * **half right, and the half it got wrong silently dropped authored intent**:
+ * a widget authoring the spec's own combo shape — `series[].type` plus
+ * `series[].yAxis: 'left'|'right'` and two `yAxis` entries — rendered as
+ * grouped bars on one axis, because the per-series mark and the axis binding
+ * never left this function (#4229, measured in the DOM: 2 bars / 0 lines / 1
+ * axis where 1 bar + 1 line + 2 axes were authored).
+ *
+ * The ruling: **the dataset owns DATA, the author owns PRESENTATION.**
+ *
+ *  - **Data (derived, never forwarded)** — series MEMBERSHIP (which columns
+ *    become series, which rows, which buckets) and the column each binding
+ *    reads. Concretely: `buildChartSeries`'s `dataKey`s, `xAxisKey`, and the
+ *    spec's two binding keys `series[].name` and `ChartAxis.field`.
+ *  - **Presentation (authored, merged forward)** — everything else on those
+ *    same objects: `series[].type` (the per-series mark), `series[].yAxis`
+ *    (which axis it binds to), `label`/`color`/`stack`/`variant`/`dashArray`/
+ *    `opacity`, and the axis definitions' `title`/`format`/`min`/`max`/
+ *    `stepSize`/`showGridLines`/`position`/`logarithmic`.
+ *
+ * This is #2880's S2 rule — dual axes are `yAxis[].position` plus
+ * `series[].yAxis`, and a combo assigns its axes by EXPLICIT binding first,
+ * falling back to the per-series-type guess only where the author bound
+ * nothing — extended from `ObjectChart` (where PR #2883 landed it) to the
+ * dataset path, which never carried it over. {@link mergeAuthoredPresentation}
+ * is the ONE place that merge happens; see it for the match rule and for why
+ * membership is safe.
+ *
+ * `aria` is the one declared key with **no reader at all** on this path:
+ * `AdvancedChartImpl` has no `aria` prop, and `SchemaRenderer`'s ARIA injection
+ * reads the FLAT `ariaLabel`/`ariaDescribedBy`/`role`, never a nested `aria`
+ * object. It is therefore left unforwarded on purpose (criterion 1) and
+ * reported back to objectstack#5175's narrowing half rather than papered over
+ * with a dashboard-only flattening that would also collide with the accessible
+ * name `description` already sets.
+ *
+ * @param raw the widget's `chartConfig` as authored (anything, incl. absent)
+ * @param fieldCategoryColors per-category colours resolved from the category
+ *   dimension's own select/lookup option colours, merged UNDER an explicit
+ *   author map (see the `colors` note below)
+ * @returns only the keys that resolved, so the caller can spread it over the
+ *   derived chart schema and every undeclared key keeps the renderer's default
+ */
+export declare function chartConfigPresentation(raw: unknown, fieldCategoryColors?: Record<string, string> | null): Record<string, unknown>;
+/** Authored spec `ChartSeries` presentation, in the renderer's internal spelling. */
+export interface AuthoredSeriesPresentation {
+    label?: string;
+    /** Spec `ChartSeries.type`, narrowed — see {@link seriesPresentation}. */
+    chartType?: 'bar' | 'line' | 'area';
+    yAxis?: 'left' | 'right';
+    color?: string;
+    stack?: string;
+    variant?: 'primary' | 'comparison';
+    dashArray?: string;
+    opacity?: number;
+}
+/** A derived series binding with the author's presentation merged onto it. */
+export type MergedChartSeries = ChartSeriesBinding & AuthoredSeriesPresentation;
+/**
+ * Merge the authored `chartConfig`'s PRESENTATION onto the series and axes the
+ * dataset selection derived — the one place that happens (#4229).
+ *
+ * The match rule is **by name/key**: an authored `series[].name` is paired with
+ * the derived binding whose `dataKey` it equals, and the pairing decides
+ * nothing but presentation:
+ *
+ *  - an authored entry naming a measure that is NOT in the dataset selection is
+ *    **ignored** — membership belongs to the dataset, so an author cannot add,
+ *    remove or re-point a series from `chartConfig`;
+ *  - a derived series with no authored entry keeps the family default, so every
+ *    dashboard that never wrote `chartConfig.series` renders byte-for-byte as
+ *    before;
+ *  - where both exist the **explicit binding wins** (#2880 S2), which is the
+ *    whole point: `type: 'line'` + `yAxis: 'right'` is how the spec says "this
+ *    measure is a line on the secondary axis".
+ *
+ * Matching on `name` only is deliberate: `name` is the spec's authorable key
+ * for a series (`dataKey` is a declared ALIAS of it, resolved where the
+ * metadata is parsed), so reading a second spelling here would fossilize a
+ * dialect this renderer has no business accepting (AGENTS.md #0.1).
+ *
+ * @param derived the bindings `buildChartSeries` produced from the selection
+ * @param raw the widget's `chartConfig` as authored (anything, incl. absent)
+ * @returns the merged series, plus the presentation-only axes to spread onto
+ *   the chart schema (absent when the author declared none)
+ */
+export declare function mergeAuthoredPresentation(derived: ChartSeriesBinding[], raw: unknown): {
+    series: MergedChartSeries[];
+    axes: Record<string, unknown>;
+};
 export declare function DatasetWidget({ widget, dataSource }: {
     widget: any;
     dataSource: unknown;

package/dist/DatasetWidget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DatasetWidget.d.ts","sourceRoot":"","sources":["../src/DatasetWidget.tsx"],"names":[],"mappings":"AA8BA,OAAO,EAUL,uBAAuB,EAGxB,MAAM,iBAAiB,CAAC;AAezB;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,gCAA0B,CAAC;AAExD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACpC,OAAO,EAAE,MAAM,EAAE,EACjB,MAAM,EAAE,MAAM,GACb;IACD,UAAU,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACpD,UAAU,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC,CAcA;AASD,8DAA8D;AAC9D,wBAAgB,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,GAAG,MAAM,CAEpF;AAmDD,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE;IAAE,MAAM,EAAE,GAAG,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,+BAgezF"}
+{"version":3,"file":"DatasetWidget.d.ts","sourceRoot":"","sources":["../src/DatasetWidget.tsx"],"names":[],"mappings":"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"}

package/dist/MetricCard.d.ts

@@ -1,17 +1,36 @@
 import { default as React } from 'react';
-export interface MetricCardProps {
-    title?: string | {
-        key?: string;
-        defaultValue?: string;
-    };
+import { I18nLabel } from '@object-ui/types';
+import { SchemaHostProps } from './schemaHostProps';
+/**
+ * DOM PASS-THROUGH (objectui#4426) — see `MetricWidget.tsx`'s interface header
+ * for the full argument; this is the same widening on the same spread, onto the
+ * same Shadcn `Card` (`div`).
+ *
+ * `title` is the one key `Omit`-ed, and the omission is the accurate contract
+ * rather than a workaround. HTML's `title` is a tooltip string; this card's
+ * `title` is its HEADING, in the `I18nLabel` vocabulary — an incompatible type,
+ * and one the component destructures out and renders into `CardTitle`, so no
+ * `title` attribute has ever reached this element. Declaring the inherited DOM
+ * `title` here would be the "declared but not delivered" failure this repo
+ * treats as first-class (objectui#3290, objectui#3222): it would type-check,
+ * read as a supported tooltip, and silently do nothing. `MetricWidget` has no
+ * such collision — its heading is `label` — so it extends the DOM attributes
+ * whole. The repo's spelling for this carve-out is `ComboboxProps`
+ * (`extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "value" | "onChange">`),
+ * omitted there for the same reason: the component's own contract owns the name.
+ */
+export interface MetricCardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+    /**
+     * Card heading, in @objectstack/spec's `I18nLabel` vocabulary — a plain
+     * string or an inline per-locale map. See `MetricWidget.label` for why the
+     * retired `{ key, defaultValue }` form is no longer accepted (objectui#4032).
+     */
+    title?: string | I18nLabel;
     value: string | number;
     icon?: string;
     trend?: 'up' | 'down' | 'neutral';
     trendValue?: string;
-    description?: string | {
-        key?: string;
-        defaultValue?: string;
-    };
+    description?: string | I18nLabel;
     className?: string;
     /** When true, the card is in a loading state (fetching data from server). */
     loading?: boolean;
@@ -22,5 +41,5 @@ export interface MetricCardProps {
  * MetricCard - Standalone metric card component for dashboard KPIs
  * Displays a metric value with optional icon, trend indicator, and description
  */
-export declare const MetricCard: React.FC<MetricCardProps>;
+export declare const MetricCard: React.FC<MetricCardProps & SchemaHostProps>;
 //# sourceMappingURL=MetricCard.d.ts.map

package/dist/MetricCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MetricCard.d.ts","sourceRoot":"","sources":["../src/MetricCard.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAY1B,MAAM,WAAW,eAAe;IAC9B,KAAK,CAAC,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CA+DhD,CAAC"}
+{"version":3,"file":"MetricCard.d.ts","sourceRoot":"","sources":["../src/MetricCard.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAI1B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,eAAgB,SAAQ,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAC1F;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,GAAG,eAAe,CA6ElE,CAAC"}

package/dist/MetricWidget.d.ts

@@ -1,25 +1,74 @@
 import { default as React } from 'react';
-export type MetricColorVariant = 'default' | 'blue' | 'teal' | 'orange' | 'purple' | 'success' | 'warning' | 'danger';
-export interface MetricWidgetProps {
-    label: string | {
-        key?: string;
-        defaultValue?: string;
-    };
+import { I18nLabel } from '@object-ui/types';
+import { MetricColorVariant } from './colorVariants';
+import { SchemaHostProps } from './schemaHostProps';
+/**
+ * The variant vocabulary and its two class tables now live in
+ * `./colorVariants` — the dataset-bound KPI (`DatasetWidget`, objectui#3359)
+ * paints the SAME accents, and two copies of a palette is how a
+ * declared-but-unenforced key becomes two disagreeing declarations. Re-exported
+ * here because this module was the type's original home.
+ */
+export type { MetricColorVariant };
+/**
+ * DOM PASS-THROUGH (objectui#4426). `MetricWidget` ends its prop list with a
+ * `...domProps` spread onto the Shadcn `Card` — a `div` — so `id`, `role`,
+ * `aria-*`, `data-*`, `tabIndex`, `title` and the DOM event handlers reach the
+ * element. objectui#4357 (PR #4428) deliberately KEPT that spread: it is the
+ * component's only accessibility passthrough, and removing it would delete the
+ * only way a host can put an `id` or an `aria-label` on a KPI card.
+ *
+ * Until now the type refused what the runtime accepted. A TypeScript consumer
+ * importing the component directly could not write `<MetricWidget id="revenue"
+ * role="region" aria-label="Revenue KPI" … />` without a cast, while a JS
+ * consumer and every SDUI author going through `SchemaRenderer` (untyped at
+ * that boundary) got the passthrough for free. This `extends` is that
+ * declaration — the mirror image of #4357, closing the same question from the
+ * other side: renderer metadata was reaching the DOM because the spread is
+ * open; DOM attributes were unreachable because the type was closed.
+ *
+ * Measured convention, not an invented spelling: an exported `*Props` interface
+ * that spreads onto a host element extends `React.HTMLAttributes<HTMLDivElement>`
+ * here — `PageHeaderComponentProps` (whose own doc says "it extends
+ * `HTMLAttributes` so every DOM prop rides along"), `ChatbotProps`,
+ * `ChatbotEnhancedProps`, `TypingIndicatorProps`, `RefreshIndicatorProps`,
+ * `FieldProps`, and shadcn's own `BadgeProps`.
+ *
+ * What this does NOT declare, deliberately: the schema-shaped keys
+ * `SchemaRenderer` injects (`schema` / `bind` / `events` / `props` /
+ * `ariaLabel` / `ariaDescribedBy` / `dataSource`). None of them is an HTML
+ * attribute name, all seven are destructured out and never reach the DOM, and
+ * declaring them here would re-assert as a public contract exactly what #4357
+ * stripped. They stay in `SchemaHostProps`, intersected in at the component's
+ * own signature — the renderer's private door, not the consumer's front door.
+ * The narrower `FieldWidgetDomProps` shape (objectui#3221) is the other spelling
+ * in this repo, but it exists to be bound key-by-key to a runtime whitelist
+ * (`toDomProps`) in both directions; this component has no such whitelist, and
+ * inventing a half of one here would declare a set the spread does not enforce.
+ * Whether plugin widgets should get that whitelist is objectui#4425.
+ */
+export interface MetricWidgetProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * The KPI's heading, in @objectstack/spec's `I18nLabel` vocabulary — a plain
+     * string or an inline per-locale map (`{ en: 'Revenue', 'zh-CN': '收入' }`).
+     *
+     * Was `string | { key?, defaultValue? }` — the key-reference form
+     * objectstack#5055 RETIRED. It is not accepted here any more because the spec
+     * rejects it at authoring time, and because reading it was never the point:
+     * the private resolver behind it ended `defaultValue || key` and never
+     * consulted a bundle, so the escape hatch was declared and inert
+     * (objectui#4032).
+     */
+    label: string | I18nLabel;
     value: string | number;
     trend?: {
         value: number;
-        label?: string | {
-            key?: string;
-            defaultValue?: string;
-        };
+        label?: string | I18nLabel;
         direction?: 'up' | 'down' | 'neutral';
     };
     icon?: React.ReactNode | string;
     className?: string;
-    description?: string | {
-        key?: string;
-        defaultValue?: string;
-    };
+    description?: string | I18nLabel;
     /** When true, the widget is in a loading state (fetching data from server). */
     loading?: boolean;
     /** Error message from a failed data fetch. When set, the widget shows an error state. */
@@ -30,11 +79,27 @@ export interface MetricWidgetProps {
     format?: string;
     /** ISO currency code (e.g. `'USD'`); enables currency formatting on numeric values. */
     currency?: string;
-    /** Static prefix appended in front of the formatted value (e.g. `'$'`, `'¥'`). */
+    /**
+     * Static prefix appended in front of the formatted value (e.g. `'$'`, `'¥'`).
+     *
+     * Same name, same `string` type as the inherited RDFa `prefix` attribute, and
+     * this declaration wins: the component reads it and destructures it out, so
+     * it never reaches the DOM. That is the accurate contract — it was already
+     * true before this interface declared its passthrough.
+     */
     prefix?: string;
     /** Static suffix appended after the formatted value (e.g. `' /mo'`). */
     suffix?: string;
-    /** When set, the entire card becomes clickable and emits this handler. */
+    /**
+     * When set, the entire card becomes clickable and emits this handler.
+     *
+     * Deliberately NARROWER than the inherited `MouseEventHandler<HTMLDivElement>`:
+     * the KPI card treats a click as "the tile was activated" and wires the same
+     * handler to Enter/Space, where there is no mouse event to hand over. A
+     * zero-arg function is assignable to the inherited signature, so consumers
+     * already passing `(e) => …` keep compiling; this only stops the component
+     * from promising an event object its keyboard path cannot produce.
+     */
     onClick?: () => void;
     /**
      * Layout variant. `'card'` (default) is the bordered KPI card; `'bare'` drops
@@ -43,5 +108,5 @@ export interface MetricWidgetProps {
      */
     variant?: 'card' | 'bare';
 }
-export declare const MetricWidget: ({ label, value, trend, icon, className, description, loading, error, colorVariant, format, currency, prefix, suffix, onClick, variant, ...props }: MetricWidgetProps) => React.JSX.Element;
+export declare const MetricWidget: ({ label, value, trend, icon, className, description, loading, error, colorVariant, format, currency, prefix, suffix, onClick, variant, schema: _schema, bind: _bind, events: _events, props: _propsBag, ariaLabel: _ariaLabel, ariaDescribedBy: _ariaDescribedBy, dataSource: _dataSource, ...domProps }: MetricWidgetProps & SchemaHostProps) => React.JSX.Element;
 //# sourceMappingURL=MetricWidget.d.ts.map