@object-ui/plugin-dashboard 17.5.0 → 17.7.0

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":"AAAA;;;;;;GAMG;AAoBH,OAAO,KAAK,EACV,UAAU,EACV,wBAAwB,EACxB,qBAAqB,EACrB,kCAAkC,EAClC,uBAAuB,EAExB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,wBAAwB,GAAG,wBAAwB,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC;AAenF,wBAAgB,qBAAqB,IAAI,uBAAuB,CAK/D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,wBAAwB,GAAG,wBAAwB,CAAC,MAAM,CAAC,CAGnG;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,wBAAwB,GAAG,qBAAqB,CAAC,WAAW,CAAC,CAElG;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,wBAAwB,GAAG,KAAK,IAAI,kCAAkC,CAEjH;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS;;;;;;EAQrE;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAUrD,CAAC;AAEF,wEAAwE;AACxE,QAAA,MAAM,qBAAqB,gIASjB,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,wEAAwE;AACxE,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAA0C,CAAC;AAO9F;;;;;;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,iBAAiB,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,cAAc,CAUjF;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,oBAAoB;;;CAGvB,CAAC;AAKX;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,yBAA0B,SAAQ,UAAU;IAC3D,IAAI,EAAE,OAAO,oBAAoB,CAAC,MAAM,CAAC;IACzC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAClC,KAAK,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAClC,WAAW,CAAC,EAAE,iBAAiB,CAAC,aAAa,CAAC,CAAC;IAC/C,KAAK,CAAC,EAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;IACnC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IACjD,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,iBAAiB,CAAC,UAAU,CAAC,CAAC;IACzC,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IACrC,OAAO,CAAC,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;CACxC;AAED,OAAO,QAAQ,kBAAkB,CAAC;IAChC,UAAU,kBAAkB;QAC1B,yBAAyB,EAAE,yBAAyB,CAAC;KACtD;CACF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAKjD"}

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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/plugin-dashboard",
-  "version": "17.5.0",
+  "version": "17.7.0",
   "type": "module",
   "license": "MIT",
   "description": "Dashboard plugin for Object UI",
@@ -18,17 +18,15 @@
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
-    "clsx": "^2.1.1",
-    "lucide-react": "^1.29.0",
-    "react": "19.2.8",
-    "react-dom": "19.2.8",
-    "tailwind-merge": "^3.6.0",
-    "@object-ui/fields": "17.5.0",
-    "@object-ui/i18n": "17.5.0",
-    "@object-ui/core": "17.5.0",
-    "@object-ui/components": "17.5.0",
-    "@object-ui/react": "17.5.0",
-    "@object-ui/types": "17.5.0"
+    "@objectstack/spec": "^17.5.0",
+    "lucide-react": "^1.43.0",
+    "@object-ui/components": "17.7.0",
+    "@object-ui/core": "17.7.0",
+    "@object-ui/fields": "17.7.0",
+    "@object-ui/i18n": "17.7.0",
+    "@object-ui/permissions": "17.7.0",
+    "@object-ui/react": "17.7.0",
+    "@object-ui/types": "17.7.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
@@ -36,14 +34,16 @@
     "react-grid-layout": "^2.2.0 || ^1.4.0"
   },
   "devDependencies": {
-    "@objectstack/spec": "^17.0.0-rc.6",
     "@types/react-grid-layout": "^2.1.0",
     "@vitejs/plugin-react": "^6.0.5",
+    "react": "19.2.8",
     "react-grid-layout": "^2.2.4",
     "typescript": "^6.0.3",
     "vite": "^8.2.1",
     "vite-plugin-dts": "^5.0.3",
-    "@object-ui/plugin-charts": "17.5.0"
+    "@object-ui/plugin-charts": "17.7.0",
+    "@object-ui/sdui-parser": "17.7.0",
+    "@object-ui/test-support": "17.4.0"
   },
   "keywords": [
     "objectui",
@@ -81,7 +81,7 @@
   "scripts": {
     "build": "vite build",
     "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "test": "vitest run",
+    "test": "vitest run --root ../.. packages/plugin-dashboard/",
     "lint": "eslint ."
   }
 }