@adminiumjs/widgets 0.1.0-rc.1

package/dist/families/kpi/GaugeArc.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `gauge-arc` (annex §1) — a 180° speedometer arc with coloured qualitative
+ * bands and a needle (or a plain half-arc dasharray gauge with `needle: false`),
+ * plus the annex's grid-of-gauges CLUSTER mode (2×2 / 5-up SLA + system-health
+ * clusters). Renders only the loaded state — skeleton/empty/error are
+ * WidgetFrame's job.
+ *
+ * TWO SHAPES, ONE WIDGET (04 §3): the definition declares
+ * `['single-metric', 'categorical']` because `cluster` is a CONFIG flag — the
+ * single gauge binds a score, the cluster binds a {label, pct, tone} list. The
+ * component reads whichever its config selects; `gaugeArcDemoData` emits a
+ * payload satisfying both.
+ *
+ * COLOUR: bands name semantic TONES, never raw colours — a gauge re-themes with
+ * the app (research/widget-registry.md Conventions: "CSS variables only").
+ *
+ * RTL: the arc does NOT mirror. The sweep is rotational, not directional (the
+ * @adminium/charts donut / radial-bar policy verbatim) — a mirrored speedometer
+ * would read as running backwards. The labels, values and the cluster grid
+ * around it are logical-property flex/grid and flip normally.
+ *
+ * REDUCED MOTION (04 §7.5, mandatory): the needle and the value sweep settle in
+ * from the arc's start via `useMountAnimation`, which paints the final frame
+ * immediately under `prefers-reduced-motion: reduce`.
+ */
+import type { GaugeArcConfig } from './kpi-config.js';
+import type { WidgetProps } from '../../registry/types.js';
+export { gaugeArcConfigSchema, gaugeArcDemoData } from './kpi-config.js';
+export type { GaugeArcConfig } from './kpi-config.js';
+export declare function GaugeArc({ config, data }: WidgetProps<GaugeArcConfig>): import("react").JSX.Element;
+//# sourceMappingURL=GaugeArc.d.ts.map

package/dist/families/kpi/GaugeArc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GaugeArc.d.ts","sourceRoot":"","sources":["../../../src/families/kpi/GaugeArc.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAQH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAItD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAuKtD,wBAAgB,QAAQ,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,WAAW,CAAC,cAAc,CAAC,+BAoFrE"}

package/dist/families/kpi/GaugeArc.js

@@ -0,0 +1,121 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `gauge-arc` (annex §1) — a 180° speedometer arc with coloured qualitative
+ * bands and a needle (or a plain half-arc dasharray gauge with `needle: false`),
+ * plus the annex's grid-of-gauges CLUSTER mode (2×2 / 5-up SLA + system-health
+ * clusters). Renders only the loaded state — skeleton/empty/error are
+ * WidgetFrame's job.
+ *
+ * TWO SHAPES, ONE WIDGET (04 §3): the definition declares
+ * `['single-metric', 'categorical']` because `cluster` is a CONFIG flag — the
+ * single gauge binds a score, the cluster binds a {label, pct, tone} list. The
+ * component reads whichever its config selects; `gaugeArcDemoData` emits a
+ * payload satisfying both.
+ *
+ * COLOUR: bands name semantic TONES, never raw colours — a gauge re-themes with
+ * the app (research/widget-registry.md Conventions: "CSS variables only").
+ *
+ * RTL: the arc does NOT mirror. The sweep is rotational, not directional (the
+ * @adminium/charts donut / radial-bar policy verbatim) — a mirrored speedometer
+ * would read as running backwards. The labels, values and the cluster grid
+ * around it are logical-property flex/grid and flip normally.
+ *
+ * REDUCED MOTION (04 §7.5, mandatory): the needle and the value sweep settle in
+ * from the arc's start via `useMountAnimation`, which paints the final frame
+ * immediately under `prefers-reduced-motion: reduce`.
+ */
+import { EmptyState, MonoText } from '@adminium/ui';
+import { useMountAnimation } from '@adminium/charts';
+import { formatMetricValue, formatOptionsOf } from '../../lib/format.js';
+import { asCategorical, asSingleMetric } from '../../lib/shapes.js';
+import { bandFor, clampValue, gaugeArcGeometry, toneOf } from './kpi-lib.js';
+// Config schema + deterministic demo payload live in the pure `kpi-config`
+// module so the registry metadata graph never reaches this component file
+// (04 §2.3). Re-exported here to keep existing import points stable.
+export { gaugeArcConfigSchema, gaugeArcDemoData } from './kpi-config.js';
+/**
+ * Tone → `stroke` / `fill` / `text` utilities. Lookup tables (not interpolated
+ * class names) so Tailwind's scanner sees every literal and never tree-shakes a
+ * tone that only appears at runtime.
+ */
+const STROKE_TONE = {
+    neutral: 'stroke-fg-subtle',
+    accent: 'stroke-accent',
+    pos: 'stroke-pos',
+    warn: 'stroke-warn',
+    danger: 'stroke-danger',
+    info: 'stroke-info',
+};
+const FILL_TONE = {
+    neutral: 'fill-fg-subtle',
+    accent: 'fill-accent',
+    pos: 'fill-pos',
+    warn: 'fill-warn',
+    danger: 'fill-danger',
+    info: 'fill-info',
+};
+const TEXT_TONE = {
+    neutral: 'text-fg-muted',
+    accent: 'text-accent',
+    pos: 'text-pos',
+    warn: 'text-warn',
+    danger: 'text-danger',
+    info: 'text-info',
+};
+/** The bare arc canvas — geometry only, no chrome. */
+function Arc({ value, max, bands, needle, width, mounted, label, tone }) {
+    const geometry = gaugeArcGeometry(value, max, bands, { width });
+    const rest = gaugeArcGeometry(0, max, bands, { width });
+    return (_jsxs("svg", { width: geometry.width, height: geometry.height, viewBox: `0 0 ${geometry.width} ${geometry.height}`, role: "img", "aria-label": label, "data-export-node": "", className: "overflow-visible", children: [_jsx("path", { d: geometry.trackPath, fill: "none", strokeWidth: geometry.thickness, strokeLinecap: "round", className: "stroke-surface-3" }), geometry.bandSegments.map((segment, index) => (_jsx("path", { "data-part": "gauge-band", "data-tone": segment.tone, d: segment.path, fill: "none", strokeWidth: geometry.thickness, 
+                // Bands are the qualitative backdrop; the value sweep reads on top.
+                className: `opacity-30 ${STROKE_TONE[segment.tone]}` }, `${segment.tone}-${index}`))), _jsx("path", { "data-part": "gauge-value", d: mounted ? geometry.valuePath : rest.valuePath, fill: "none", strokeWidth: geometry.thickness, strokeLinecap: "round", className: STROKE_TONE[tone] }), needle ? (_jsxs("g", { "data-part": "gauge-needle", className: "transition-opacity duration-500 ease-out motion-reduce:transition-none", opacity: mounted ? 1 : 0, children: [_jsx("line", { x1: geometry.cx, y1: geometry.cy, x2: mounted ? geometry.needle.x : rest.needle.x, y2: mounted ? geometry.needle.y : rest.needle.y, strokeWidth: 2.5, strokeLinecap: "round", className: `transition-all duration-700 ease-out motion-reduce:transition-none ${STROKE_TONE[tone]}` }), _jsx("circle", { cx: geometry.cx, cy: geometry.cy, r: 4, className: FILL_TONE[tone] })] })) : null] }));
+}
+/** One cluster cell: a small arc + its label and value (annex §1 cluster mode). */
+function ClusterCell({ label, value, max, bands, needle, mounted, text, tone, }) {
+    return (_jsxs("div", { className: "flex flex-col items-center gap-1", "data-part": "gauge-cell", "data-tone": tone, children: [_jsx(Arc, { value: value, max: max, bands: bands, needle: needle, width: 110, mounted: mounted, label: `${label}: ${text}`, tone: tone }), _jsx(MonoText, { className: `text-body-sm font-bold leading-none ${TEXT_TONE[tone]}`, children: text }), _jsx("span", { className: "max-w-full truncate text-micro uppercase tracking-wide text-fg-subtle", children: label })] }));
+}
+/** Format one gauge reading with the config's unit suffix. */
+function readingOf(value, config, opts) {
+    const text = formatMetricValue(value, config.valueFormat, opts);
+    return config.unit === undefined ? text : `${text}${config.unit}`;
+}
+/** Cluster-mode grid columns — a lookup table so Tailwind sees the literals. */
+const GRID_COLUMNS = {
+    1: 'grid-cols-1',
+    2: 'grid-cols-2',
+    3: 'grid-cols-3',
+    4: 'grid-cols-4',
+    5: 'grid-cols-5',
+};
+export function GaugeArc({ config, data }) {
+    const mounted = useMountAnimation();
+    const opts = formatOptionsOf(config);
+    if (config.cluster) {
+        const categorical = asCategorical(data);
+        if (categorical === null) {
+            return _jsx("p", { className: "px-4 pb-4 text-body-sm text-fg-muted", children: "Unexpected data shape." });
+        }
+        // A categorical payload with no items is EMPTY, not malformed — an SLA or
+        // system-health query is allowed to return zero rows. The frame can't route
+        // it (see `emptyTitle` in kpi-config), so the per-widget empty copy is here
+        // rather than the developer-facing "unexpected shape" line above.
+        if (categorical.items.length === 0) {
+            return (_jsx(EmptyState, { compact: true, preset: "no-data", title: config.emptyTitle ?? 'No gauges to show', body: config.emptyBody ?? 'Services appear here as gauges once there is a reading for them.' }));
+        }
+        return (_jsx("div", { className: `grid h-full content-center gap-3 px-4 pb-4 compact:px-3 compact:pb-3 ${GRID_COLUMNS[config.columns] ?? 'grid-cols-2'}`, "data-widget": "gauge-arc", "data-cluster": "true", children: categorical.items.map((item) => {
+                const value = clampValue(item.value, config.max);
+                const tone = toneOf(item.tone, bandFor(value, config.bands)?.tone ?? 'accent');
+                return (_jsx(ClusterCell, { label: item.label, value: value, max: config.max, bands: config.bands, needle: config.needle, mounted: mounted, text: readingOf(value, config, opts), tone: tone }, item.key));
+            }) }));
+    }
+    const metric = asSingleMetric(data);
+    if (metric === null) {
+        return _jsx("p", { className: "px-4 pb-4 text-body-sm text-fg-muted", children: "Unexpected data shape." });
+    }
+    const value = clampValue(metric.value, config.max);
+    const band = bandFor(value, config.bands);
+    const tone = band?.tone ?? 'accent';
+    const text = readingOf(value, config, opts);
+    return (_jsxs("div", { className: "flex h-full flex-col items-center justify-center gap-2 px-4 pb-4 compact:px-3 compact:pb-3", "data-widget": "gauge-arc", "data-cluster": "false", "data-tone": tone, children: [_jsx(Arc, { value: value, max: config.max, bands: config.bands, needle: config.needle, width: 180, mounted: mounted, label: `${band?.label === undefined ? '' : `${band.label}: `}${text}`, tone: tone }), _jsx(MonoText, { "data-part": "gauge-value-text", className: "text-[22px] font-bold leading-none text-fg", children: text }), band?.label === undefined ? null : (_jsx("span", { className: `text-micro font-bold uppercase tracking-wide ${TEXT_TONE[tone]}`, children: band.label }))] }));
+}
+//# sourceMappingURL=GaugeArc.js.map

package/dist/families/kpi/GaugeArc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GaugeArc.js","sourceRoot":"","sources":["../../../src/families/kpi/GaugeArc.tsx"],"names":[],"mappings":"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"}

package/dist/families/kpi/GaugeRing.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `gauge-ring` (annex §1) — an SVG circle with an animated `stroke-dashoffset`
+ * sweep, a center value and a status caption ("86/100 Healthy", "73% of 5M
+ * rows"), plus the annex's footer variants (spent-of-total figures + trend pill,
+ * or an avatar stack). Doubles as the budget/allocation donut gauge. Renders only
+ * the loaded state — skeleton/empty/error are WidgetFrame's job.
+ *
+ * COLOUR: the sweep is tinted by the band the value falls in, and bands name
+ * semantic TONES (`pos`/`warn`/`danger`/…), never raw colours — so a gauge
+ * re-themes with the app and stays legible in dark mode
+ * (research/widget-registry.md Conventions: "CSS variables only").
+ *
+ * RTL: the ring geometry does NOT mirror. A clockwise sweep is rotational, not
+ * directional — mirroring it would read as "the gauge runs backwards", exactly
+ * as it would for a donut (@adminium/charts geometry/radialBar.ts states the
+ * same policy verbatim). The caption, footer figures and avatar stack around it
+ * are ordinary logical-property flex and flip normally.
+ *
+ * REDUCED MOTION (04 §7.5, mandatory): the sweep animates from empty to its
+ * value on mount via `useMountAnimation`, which paints the final frame
+ * immediately under `prefers-reduced-motion: reduce`.
+ */
+import type { GaugeRingConfig } from './kpi-config.js';
+import type { WidgetProps } from '../../registry/types.js';
+export { gaugeRingConfigSchema, gaugeRingDemoData } from './kpi-config.js';
+export type { GaugeRingConfig } from './kpi-config.js';
+export declare function GaugeRing({ config, data }: WidgetProps<GaugeRingConfig>): import("react").JSX.Element;
+//# sourceMappingURL=GaugeRing.d.ts.map

package/dist/families/kpi/GaugeRing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GaugeRing.d.ts","sourceRoot":"","sources":["../../../src/families/kpi/GaugeRing.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAQH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,OAAO,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC3E,YAAY,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAsCvD,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,WAAW,CAAC,eAAe,CAAC,+BA2GvE"}

package/dist/families/kpi/GaugeRing.js

@@ -0,0 +1,96 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `gauge-ring` (annex §1) — an SVG circle with an animated `stroke-dashoffset`
+ * sweep, a center value and a status caption ("86/100 Healthy", "73% of 5M
+ * rows"), plus the annex's footer variants (spent-of-total figures + trend pill,
+ * or an avatar stack). Doubles as the budget/allocation donut gauge. Renders only
+ * the loaded state — skeleton/empty/error are WidgetFrame's job.
+ *
+ * COLOUR: the sweep is tinted by the band the value falls in, and bands name
+ * semantic TONES (`pos`/`warn`/`danger`/…), never raw colours — so a gauge
+ * re-themes with the app and stays legible in dark mode
+ * (research/widget-registry.md Conventions: "CSS variables only").
+ *
+ * RTL: the ring geometry does NOT mirror. A clockwise sweep is rotational, not
+ * directional — mirroring it would read as "the gauge runs backwards", exactly
+ * as it would for a donut (@adminium/charts geometry/radialBar.ts states the
+ * same policy verbatim). The caption, footer figures and avatar stack around it
+ * are ordinary logical-property flex and flip normally.
+ *
+ * REDUCED MOTION (04 §7.5, mandatory): the sweep animates from empty to its
+ * value on mount via `useMountAnimation`, which paints the final frame
+ * immediately under `prefers-reduced-motion: reduce`.
+ */
+import { Avatar, AvatarStack, DeltaPill, MonoText } from '@adminium/ui';
+import { useMountAnimation } from '@adminium/charts';
+import { computeDelta, formatMetricValue, formatOptionsOf } from '../../lib/format.js';
+import { asMetricDelta } from '../../lib/shapes.js';
+import { bandFor, clampValue, gaugeRingGeometry, sharedToneOf } from './kpi-lib.js';
+// Config schema + deterministic demo payload live in the pure `kpi-config`
+// module so the registry metadata graph never reaches this component file
+// (04 §2.3). Re-exported here to keep existing import points stable.
+export { gaugeRingConfigSchema, gaugeRingDemoData } from './kpi-config.js';
+/**
+ * Tone → the `stroke` utility for the value sweep. A lookup table (not an
+ * interpolated class name) so Tailwind's scanner sees every literal and never
+ * tree-shakes a tone that only appears at runtime.
+ */
+const STROKE_TONE = {
+    neutral: 'stroke-fg-subtle',
+    accent: 'stroke-accent',
+    pos: 'stroke-pos',
+    warn: 'stroke-warn',
+    danger: 'stroke-danger',
+    info: 'stroke-info',
+};
+/** Tone → the caption's text utility. */
+const TEXT_TONE = {
+    neutral: 'text-fg-muted',
+    accent: 'text-accent',
+    pos: 'text-pos',
+    warn: 'text-warn',
+    danger: 'text-danger',
+    info: 'text-info',
+};
+/** The avatar names off the payload (the annex's avatar-stack footer). */
+function avatarsOf(data) {
+    const raw = typeof data === 'object' && data !== null ? data.avatars : undefined;
+    return Array.isArray(raw) ? raw.filter((name) => typeof name === 'string') : [];
+}
+/** The denominator off the payload (annex "+ optional numerator/denominator"). */
+function totalOf(data, max) {
+    const raw = typeof data === 'object' && data !== null ? data.total : undefined;
+    return typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? raw : max;
+}
+export function GaugeRing({ config, data }) {
+    const mounted = useMountAnimation();
+    const metric = asMetricDelta(data);
+    if (metric === null) {
+        return _jsx("p", { className: "px-4 pb-4 text-body-sm text-fg-muted", children: "Unexpected data shape." });
+    }
+    const opts = formatOptionsOf(config);
+    const value = clampValue(metric.value, config.max);
+    const geometry = gaugeRingGeometry(value, config.max, config.size);
+    const band = bandFor(value, config.bands);
+    // The band the value lands in wins; the shared `tone` override only applies
+    // to a band-less gauge (an empty `bands` array).
+    const tone = band?.tone ?? sharedToneOf(config.tone, 'accent');
+    const total = totalOf(data, config.max);
+    const delta = computeDelta(metric, config.deltaMode, config.metricFormat, opts);
+    const center = config.centerFormat === 'percent'
+        ? formatMetricValue(geometry.fraction, 'percent', opts)
+        : config.centerFormat === 'fraction'
+            ? `${formatMetricValue(value, 'plain', opts)}/${formatMetricValue(config.max, 'plain', opts)}`
+            : formatMetricValue(value, 'plain', opts);
+    const caption = config.caption ?? band?.label;
+    const avatars = avatarsOf(data);
+    return (_jsxs("div", { className: "flex h-full flex-col items-center justify-center gap-3 px-4 pb-4 compact:gap-2 compact:px-3 compact:pb-3", "data-widget": "gauge-ring", "data-tone": tone, children: [_jsxs("div", { className: "relative shrink-0", children: [_jsxs("svg", { width: geometry.size, height: geometry.size, viewBox: `0 0 ${geometry.size} ${geometry.size}`, role: "img", "aria-label": `${caption === undefined ? '' : `${caption}: `}${center}`, "data-export-node": "", 
+                        // Rotation is direction-neutral: the sweep starts at 12 o'clock in
+                        // LTR and RTL alike (see the module note).
+                        className: "-rotate-90", children: [_jsx("circle", { cx: geometry.center, cy: geometry.center, r: geometry.radius, fill: "none", strokeWidth: geometry.thickness, className: "stroke-surface-3" }), _jsx("circle", { "data-part": "gauge-value", cx: geometry.center, cy: geometry.center, r: geometry.radius, fill: "none", strokeWidth: geometry.thickness, strokeLinecap: "round", strokeDasharray: geometry.circumference, 
+                                // Starts fully offset (empty) and settles to the value; under
+                                // reduced motion `mounted` is true on the first render, so the
+                                // final frame paints immediately and the transition never runs.
+                                strokeDashoffset: mounted ? geometry.dashOffset : geometry.circumference, className: `transition-[stroke-dashoffset] duration-700 ease-out motion-reduce:transition-none ${STROKE_TONE[tone]}` })] }), _jsxs("div", { className: "absolute inset-0 flex flex-col items-center justify-center gap-0.5", children: [_jsx(MonoText, { "data-part": "gauge-center", className: "text-[20px] font-bold leading-none text-fg", children: center }), caption === undefined ? null : (_jsx("span", { "data-part": "gauge-caption", className: `text-micro font-bold uppercase tracking-wide ${TEXT_TONE[tone]}`, children: caption }))] })] }), config.footer === 'spent-of-total' && (_jsxs("div", { className: "flex w-full items-center justify-between gap-2", "data-part": "gauge-footer", children: [_jsxs(MonoText, { className: "truncate text-caption text-fg-muted", children: [config.spentLabel === undefined ? '' : `${config.spentLabel} `, _jsx("span", { className: "font-semibold text-fg", children: formatMetricValue(value, config.metricFormat, opts) }), ` / ${formatMetricValue(total, config.metricFormat, opts)}`, config.totalLabel === undefined ? '' : ` ${config.totalLabel}`] }), delta === null ? null : (_jsx(DeltaPill, { trend: delta.trend, invertGood: config.invertDeltaGood, children: delta.text }))] })), config.footer === 'avatar-stack' && avatars.length > 0 && (_jsx("div", { className: "flex w-full justify-center", "data-part": "gauge-footer", children: _jsx(AvatarStack, { size: "sm", max: 4, label: config.totalLabel, children: avatars.map((name) => (_jsx(Avatar, { name: name, size: "sm" }, name))) }) }))] }));
+}
+//# sourceMappingURL=GaugeRing.js.map

package/dist/families/kpi/GaugeRing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GaugeRing.js","sourceRoot":"","sources":["../../../src/families/kpi/GaugeRing.tsx"],"names":[],"mappings":"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"}

package/dist/families/kpi/KpiStatCard.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `kpi-stat-card` — the workhorse metric card (annex §1, 04 §11): tinted
+ * icon tile, label, large mono value, optional delta pill (pos/danger tone
+ * with the "down-is-good" inversion flag), optional 7–8 bar mini sparkline
+ * with the last bar at full accent. Renders only the loaded state —
+ * skeleton/empty/error are WidgetFrame's job.
+ */
+import type { KpiStatCardConfig } from './kpi-config.js';
+import type { WidgetProps } from '../../registry/types.js';
+export { kpiStatCardConfigSchema, kpiStatCardDemoData } from './kpi-config.js';
+export type { KpiStatCardConfig } from './kpi-config.js';
+export declare function KpiStatCard({ config, data }: WidgetProps<KpiStatCardConfig>): import("react").JSX.Element;
+//# sourceMappingURL=KpiStatCard.d.ts.map

package/dist/families/kpi/KpiStatCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KpiStatCard.d.ts","sourceRoot":"","sources":["../../../src/families/kpi/KpiStatCard.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAkBH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,OAAO,EAAE,uBAAuB,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAezD,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,WAAW,CAAC,iBAAiB,CAAC,+BAsC3E"}

package/dist/families/kpi/KpiStatCard.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `kpi-stat-card` — the workhorse metric card (annex §1, 04 §11): tinted
+ * icon tile, label, large mono value, optional delta pill (pos/danger tone
+ * with the "down-is-good" inversion flag), optional 7–8 bar mini sparkline
+ * with the last bar at full accent. Renders only the loaded state —
+ * skeleton/empty/error are WidgetFrame's job.
+ */
+import { DeltaPill, IconTile, MonoText } from '@adminium/ui';
+import { Sparkline } from '@adminium/charts';
+import { Activity, CircleDollarSign, Database, Gauge, Package, ShoppingCart, Star, TrendingUp, Users, Zap, } from 'lucide-react';
+import { computeDelta, formatMetricValue, formatOptionsOf } from '../../lib/format.js';
+import { asMetricDelta } from '../../lib/shapes.js';
+// Config schema + deterministic demo payload live in the pure `kpi-config`
+// module so the registry metadata graph never reaches this component file
+// (04 §2.3). Re-exported here to keep existing import points stable.
+export { kpiStatCardConfigSchema, kpiStatCardDemoData } from './kpi-config.js';
+const ICONS = {
+    activity: Activity,
+    dollar: CircleDollarSign,
+    users: Users,
+    cart: ShoppingCart,
+    gauge: Gauge,
+    database: Database,
+    zap: Zap,
+    star: Star,
+    package: Package,
+    trending: TrendingUp,
+};
+export function KpiStatCard({ config, data }) {
+    const metric = asMetricDelta(data);
+    if (metric === null) {
+        return _jsx("p", { className: "px-4 pb-4 text-body-sm text-fg-muted", children: "Unexpected data shape." });
+    }
+    const opts = formatOptionsOf(config);
+    const value = formatMetricValue(metric.value, config.metricFormat, opts);
+    const delta = computeDelta(metric, config.deltaMode, config.metricFormat, opts);
+    const label = config.metricLabel ?? config.title;
+    const Icon = ICONS[config.iconName];
+    const spark = config.showSparkline ? metric.spark : undefined;
+    return (_jsxs("div", { className: "flex h-full flex-col justify-between gap-2 px-4 pb-4 compact:px-3 compact:pb-3", "data-widget": "kpi-stat-card", children: [_jsxs("div", { className: "flex items-start justify-between gap-2", children: [_jsx(IconTile, { tone: config.iconTone, size: "md", icon: _jsx(Icon, {}) }), delta !== null && (_jsx(DeltaPill, { trend: delta.trend, invertGood: config.invertDeltaGood, children: delta.text }))] }), _jsxs("div", { className: "flex items-end justify-between gap-3", children: [_jsxs("div", { className: "min-w-0", children: [label !== undefined && (_jsx("p", { className: "truncate text-body-sm text-fg-muted", children: label })), _jsx(MonoText, { className: "block text-[26px] font-bold leading-tight text-fg compact:text-[22px]", children: value })] }), spark !== undefined && (_jsx(Sparkline, { data: spark, variant: "bar", width: 72, height: 26, className: "shrink-0" }))] })] }));
+}
+//# sourceMappingURL=KpiStatCard.js.map

package/dist/families/kpi/KpiStatCard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KpiStatCard.js","sourceRoot":"","sources":["../../../src/families/kpi/KpiStatCard.tsx"],"names":[],"mappings":"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"}

package/dist/families/kpi/KpiStatTileCompact.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `kpi-stat-tile-compact` (annex §1) — the slim tile variant of the workhorse
+ * card, for dense "power" rows of 4–6: uppercase micro-label, mono value, a tiny
+ * delta chip, and a 22px 6-bar sparkline. No icon tile (that is what separates it
+ * from `kpi-stat-card`). Renders only the loaded state — skeleton/empty/error
+ * are WidgetFrame's job.
+ */
+import type { KpiStatTileCompactConfig } from './kpi-config.js';
+import type { WidgetProps } from '../../registry/types.js';
+export { kpiStatTileCompactConfigSchema, kpiStatTileCompactDemoData } from './kpi-config.js';
+export type { KpiStatTileCompactConfig } from './kpi-config.js';
+export declare function KpiStatTileCompact({ config, data }: WidgetProps<KpiStatTileCompactConfig>): import("react").JSX.Element;
+//# sourceMappingURL=KpiStatTileCompact.d.ts.map

package/dist/families/kpi/KpiStatTileCompact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KpiStatTileCompact.d.ts","sourceRoot":"","sources":["../../../src/families/kpi/KpiStatTileCompact.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,OAAO,EAAE,8BAA8B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAC7F,YAAY,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAEhE,wBAAgB,kBAAkB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,WAAW,CAAC,wBAAwB,CAAC,+BAoCzF"}

package/dist/families/kpi/KpiStatTileCompact.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `kpi-stat-tile-compact` (annex §1) — the slim tile variant of the workhorse
+ * card, for dense "power" rows of 4–6: uppercase micro-label, mono value, a tiny
+ * delta chip, and a 22px 6-bar sparkline. No icon tile (that is what separates it
+ * from `kpi-stat-card`). Renders only the loaded state — skeleton/empty/error
+ * are WidgetFrame's job.
+ */
+import { DeltaPill, MonoText } from '@adminium/ui';
+import { Sparkline } from '@adminium/charts';
+import { computeDelta, formatMetricValue, formatOptionsOf } from '../../lib/format.js';
+import { asMetricDelta } from '../../lib/shapes.js';
+// Config schema + deterministic demo payload live in the pure `kpi-config`
+// module so the registry metadata graph never reaches this component file
+// (04 §2.3). Re-exported here to keep existing import points stable.
+export { kpiStatTileCompactConfigSchema, kpiStatTileCompactDemoData } from './kpi-config.js';
+export function KpiStatTileCompact({ config, data }) {
+    const metric = asMetricDelta(data);
+    if (metric === null) {
+        return _jsx("p", { className: "px-3 pb-3 text-body-sm text-fg-muted", children: "Unexpected data shape." });
+    }
+    const opts = formatOptionsOf(config);
+    const value = formatMetricValue(metric.value, config.metricFormat, opts);
+    const delta = computeDelta(metric, config.deltaMode, config.metricFormat, opts);
+    const label = config.metricLabel ?? config.title;
+    const spark = config.showSparkline ? metric.spark : undefined;
+    return (_jsxs("div", { className: "flex h-full flex-col justify-between gap-1.5 px-3 pb-3 compact:px-2.5 compact:pb-2.5", "data-widget": "kpi-stat-tile-compact", "data-columns": config.columns, children: [label === undefined ? null : (_jsx("p", { className: "truncate text-micro font-bold uppercase tracking-wide text-fg-subtle", children: label })), _jsxs("div", { className: "flex items-end justify-between gap-2", children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-1", children: [_jsx(MonoText, { className: "block truncate text-[19px] font-bold leading-none text-fg", children: value }), delta === null ? null : (_jsx(DeltaPill, { trend: delta.trend, invertGood: config.invertDeltaGood, className: "self-start", children: delta.text }))] }), spark === undefined ? null : (_jsx(Sparkline, { data: spark, variant: "bar", width: 48, height: 22, className: "shrink-0" }))] })] }));
+}
+//# sourceMappingURL=KpiStatTileCompact.js.map

package/dist/families/kpi/KpiStatTileCompact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"KpiStatTileCompact.js","sourceRoot":"","sources":["../../../src/families/kpi/KpiStatTileCompact.tsx"],"names":[],"mappings":";AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIpD,2EAA2E;AAC3E,0EAA0E;AAC1E,qEAAqE;AACrE,OAAO,EAAE,8BAA8B,EAAE,0BAA0B,EAAE,MAAM,iBAAiB,CAAC;AAG7F,MAAM,UAAU,kBAAkB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAyC;IACxF,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,OAAO,YAAG,SAAS,EAAC,sCAAsC,uCAA2B,CAAC;IACxF,CAAC;IAED,MAAM,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,iBAAiB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAChF,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,KAAK,CAAC;IACjD,MAAM,KAAK,GAAG,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;IAE9D,OAAO,CACL,eACE,SAAS,EAAC,sFAAsF,iBACpF,uBAAuB,kBACrB,MAAM,CAAC,OAAO,aAE3B,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAC5B,YAAG,SAAS,EAAC,sEAAsE,YAAE,KAAK,GAAK,CAChG,EACD,eAAK,SAAS,EAAC,sCAAsC,aACnD,eAAK,SAAS,EAAC,6BAA6B,aAC1C,KAAC,QAAQ,IAAC,SAAS,EAAC,2DAA2D,YAAE,KAAK,GAAY,EACjG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CACvB,KAAC,SAAS,IAAC,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,eAAe,EAAE,SAAS,EAAC,YAAY,YACtF,KAAK,CAAC,IAAI,GACD,CACb,IACG,EACL,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAC5B,KAAC,SAAS,IAAC,IAAI,EAAE,KAAK,EAAE,OAAO,EAAC,KAAK,EAAC,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,SAAS,EAAC,UAAU,GAAG,CACrF,IACG,IACF,CACP,CAAC;AACJ,CAAC"}

package/dist/families/kpi/MetricHero.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `metric-hero` (annex §1) — the oversized single metric: a
+ * `requestAnimationFrame` count-up to the bound value, a delta pill, a spark
+ * strip, and a goal progress track ("Goal · $650k, 74%"). Renders only the
+ * loaded state — skeleton/empty/error are WidgetFrame's job.
+ *
+ * REDUCED MOTION (04 §7.5, mandatory): `prefers-reduced-motion: reduce` skips
+ * the count-up entirely and paints the final value on the first frame — an
+ * animated number is exactly the kind of motion the query exists to suppress,
+ * and a KPI that "spins up" is unreadable to a vestibular-sensitive user. The
+ * hook seeds its state from the query rather than transitioning to it, so the
+ * intermediate values never render even once.
+ */
+import type { MetricHeroConfig } from './kpi-config.js';
+import type { WidgetProps } from '../../registry/types.js';
+export { metricHeroConfigSchema, metricHeroDemoData } from './kpi-config.js';
+export type { MetricHeroConfig } from './kpi-config.js';
+/**
+ * Animate 0 → `target` over `COUNT_UP_MS` via rAF. Returns `target` immediately
+ * when the caller disables it, when the browser has no rAF (SSR / the Node test
+ * env), or under `prefers-reduced-motion`.
+ */
+export declare function useCountUp(target: number, enabled: boolean): number;
+export declare function MetricHero({ config, data }: WidgetProps<MetricHeroConfig>): import("react").JSX.Element;
+//# sourceMappingURL=MetricHero.d.ts.map

package/dist/families/kpi/MetricHero.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricHero.d.ts","sourceRoot":"","sources":["../../../src/families/kpi/MetricHero.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAUxD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAsBnE;AASD,wBAAgB,UAAU,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,WAAW,CAAC,gBAAgB,CAAC,+BAqEzE"}

package/dist/families/kpi/MetricHero.js

@@ -0,0 +1,85 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * `metric-hero` (annex §1) — the oversized single metric: a
+ * `requestAnimationFrame` count-up to the bound value, a delta pill, a spark
+ * strip, and a goal progress track ("Goal · $650k, 74%"). Renders only the
+ * loaded state — skeleton/empty/error are WidgetFrame's job.
+ *
+ * REDUCED MOTION (04 §7.5, mandatory): `prefers-reduced-motion: reduce` skips
+ * the count-up entirely and paints the final value on the first frame — an
+ * animated number is exactly the kind of motion the query exists to suppress,
+ * and a KPI that "spins up" is unreadable to a vestibular-sensitive user. The
+ * hook seeds its state from the query rather than transitioning to it, so the
+ * intermediate values never render even once.
+ */
+import { DeltaPill, MonoText, ProgressBar } from '@adminium/ui';
+import { Sparkline, prefersReducedMotion } from '@adminium/charts';
+import { useEffect, useRef, useState } from 'react';
+import { computeDelta, formatMetricValue, formatOptionsOf } from '../../lib/format.js';
+import { asMetricDelta } from '../../lib/shapes.js';
+import { fractionOf } from './kpi-lib.js';
+// Config schema + deterministic demo payload live in the pure `kpi-config`
+// module so the registry metadata graph never reaches this component file
+// (04 §2.3). Re-exported here to keep existing import points stable.
+export { metricHeroConfigSchema, metricHeroDemoData } from './kpi-config.js';
+/** Count-up duration in ms (research/design-system.md §4.3 — "hero" tier). */
+const COUNT_UP_MS = 900;
+/** Cubic ease-out — fast start, settled landing. */
+function easeOut(t) {
+    return 1 - (1 - t) ** 3;
+}
+/**
+ * Animate 0 → `target` over `COUNT_UP_MS` via rAF. Returns `target` immediately
+ * when the caller disables it, when the browser has no rAF (SSR / the Node test
+ * env), or under `prefers-reduced-motion`.
+ */
+export function useCountUp(target, enabled) {
+    const reduced = prefersReducedMotion();
+    const animate = enabled && !reduced && typeof requestAnimationFrame === 'function';
+    const [value, setValue] = useState(() => (animate ? 0 : target));
+    const frameRef = useRef(0);
+    useEffect(() => {
+        if (!animate) {
+            setValue(target);
+            return undefined;
+        }
+        const start = performance.now();
+        const tick = (now) => {
+            const t = Math.min(1, (now - start) / COUNT_UP_MS);
+            setValue(target * easeOut(t));
+            if (t < 1)
+                frameRef.current = requestAnimationFrame(tick);
+        };
+        frameRef.current = requestAnimationFrame(tick);
+        return () => cancelAnimationFrame(frameRef.current);
+    }, [target, animate]);
+    return value;
+}
+/** The goal scalar off the payload (config wins when set). */
+function goalOf(data, configGoal) {
+    if (configGoal !== undefined)
+        return configGoal;
+    const raw = typeof data === 'object' && data !== null ? data.goal : undefined;
+    return typeof raw === 'number' && Number.isFinite(raw) && raw > 0 ? raw : undefined;
+}
+export function MetricHero({ config, data }) {
+    const metric = asMetricDelta(data);
+    const goal = goalOf(data, config.goalValue);
+    // Hooks must run before any early return (rules-of-hooks); a malformed
+    // payload counts up to 0 and is discarded by the guard below.
+    const animated = useCountUp(metric?.value ?? 0, config.countUp);
+    if (metric === null) {
+        return _jsx("p", { className: "px-4 pb-4 text-body-sm text-fg-muted", children: "Unexpected data shape." });
+    }
+    const opts = formatOptionsOf(config);
+    const value = formatMetricValue(animated, config.metricFormat, opts);
+    const delta = computeDelta(metric, config.deltaMode, config.metricFormat, opts);
+    const label = config.metricLabel ?? config.title;
+    const spark = metric.spark?.slice(0, config.sparkBars);
+    const goalPct = goal === undefined ? null : fractionOf(metric.value, goal) * 100;
+    const goalText = goal === undefined
+        ? null
+        : `${config.goalLabel ?? 'Goal'} · ${formatMetricValue(goal, config.metricFormat, opts)}, ${formatMetricValue(goalPct / 100, 'percent', opts)}`;
+    return (_jsxs("div", { className: "flex h-full flex-col justify-between gap-3 px-4 pb-4 compact:px-3 compact:pb-3", "data-widget": "metric-hero", children: [_jsxs("div", { className: "flex flex-col gap-1.5", children: [label === undefined ? null : _jsx("p", { className: "truncate text-body-sm text-fg-muted", children: label }), _jsxs("div", { className: "flex flex-wrap items-center gap-2.5", children: [_jsx(MonoText, { "data-part": "hero-value", className: "text-[38px] font-bold leading-none text-fg compact:text-[30px]", children: value }), delta === null ? null : (_jsx(DeltaPill, { trend: delta.trend, invertGood: config.invertDeltaGood, children: delta.text }))] })] }), spark === undefined || spark.length === 0 ? null : (_jsx(Sparkline, { data: spark, variant: "bar", width: 220, height: 40, className: "w-full" })), goalText === null ? null : (_jsxs("div", { className: "flex flex-col gap-1.5", "data-part": "goal-track", children: [_jsx("span", { className: "truncate text-caption text-fg-muted", children: goalText }), _jsx(ProgressBar, { value: goalPct, max: 100, tone: "accent", size: "md", label: goalText })] }))] }));
+}
+//# sourceMappingURL=MetricHero.js.map

package/dist/families/kpi/MetricHero.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricHero.js","sourceRoot":"","sources":["../../../src/families/kpi/MetricHero.tsx"],"names":[],"mappings":"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"}

package/dist/families/kpi/MicroKpiSubtitle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `micro-kpi-subtitle` (annex §1) — the inline header micro-KPI line recomputed
+ * from live state ("3 unread · 10 total", "24 members · 8 online", "N connected ·
+ * 12 available"). `placement: 'inline'`, so it renders in a page-header slot
+ * rather than a grid cell and never carries WidgetFrame chrome.
+ *
+ * The sentence is a stored TEMPLATE with `{placeholder}` tokens resolved against
+ * the bound scalars — see `interpolateTemplate` in `kpi-lib` for why an unknown
+ * token degrades to the empty string rather than leaking `{token}` into the UI.
+ */
+import type { ScalarBag } from './kpi-lib.js';
+import type { MicroKpiSubtitleConfig } from './kpi-config.js';
+import type { WidgetProps } from '../../registry/types.js';
+export { microKpiSubtitleConfigSchema, microKpiSubtitleDemoData } from './kpi-config.js';
+export type { MicroKpiSubtitleConfig } from './kpi-config.js';
+/**
+ * Every scalar the payload carries, flattened for template interpolation. The
+ * annex's contract is "1–3 derived scalars over a sibling `record-list`" — the
+ * host compiles them into a `single-metric` envelope whose sibling keys are the
+ * other scalars, so any number/string column is addressable by name.
+ */
+export declare function scalarsOf(data: unknown): ScalarBag;
+export declare function MicroKpiSubtitle({ config, data }: WidgetProps<MicroKpiSubtitleConfig>): import("react").JSX.Element;
+//# sourceMappingURL=MicroKpiSubtitle.d.ts.map

package/dist/families/kpi/MicroKpiSubtitle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MicroKpiSubtitle.d.ts","sourceRoot":"","sources":["../../../src/families/kpi/MicroKpiSubtitle.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3D,OAAO,EAAE,4BAA4B,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AACzF,YAAY,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,SAAS,CAQlD;AAED,wBAAgB,gBAAgB,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,WAAW,CAAC,sBAAsB,CAAC,+BAmBrF"}