@asteby/metacore-runtime-react 18.16.0 → 18.17.0

package/dist/widgets/widget-card.js

@@ -0,0 +1,30 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Card, CardContent, CardHeader } from '@asteby/metacore-ui';
+import { cn } from '@asteby/metacore-ui/lib';
+import { DynamicIcon, isLucideIconName } from '../dynamic-icon';
+import { accentClasses } from './widget-format';
+/**
+ * The card frame shared by all widgets. Keep the chrome here so a single style
+ * change propagates to every kind (and to federated custom widgets).
+ */
+export function WidgetCard({ title, subtitle, icon, accent, headerExtra, children, className, ...rest }) {
+    const a = accentClasses(accent);
+    const showIcon = icon && isLucideIconName(icon);
+    return (_jsxs(Card, { ...rest, className: cn(
+        // base: subtle border, ring on hover, gentle lift, mount fade-in
+        'group/widget relative flex h-full flex-col overflow-hidden', 'border-border/60 transition-all duration-200', 'hover:border-border hover:ring-1 hover:ring-ring/30 hover:shadow-sm', 'motion-safe:animate-in motion-safe:fade-in-0 motion-safe:slide-in-from-bottom-1 motion-safe:duration-500', className), children: [_jsxs(CardHeader, { className: "flex flex-row items-start justify-between gap-3 space-y-0 pb-2", children: [_jsxs("div", { className: "flex min-w-0 items-start gap-3", children: [showIcon && (_jsx("span", { className: cn('flex size-9 shrink-0 items-center justify-center rounded-lg', a.chip), children: _jsx(DynamicIcon, { name: icon, className: "size-[18px]" }) })), _jsxs("div", { className: "min-w-0", children: [_jsx("div", { className: "truncate text-sm font-medium leading-tight text-foreground", children: title }), subtitle && (_jsx("div", { className: "mt-0.5 truncate text-xs text-muted-foreground", children: subtitle }))] })] }), headerExtra && _jsx("div", { className: "shrink-0", children: headerExtra })] }), _jsx(CardContent, { className: "flex flex-1 flex-col justify-end pt-1", children: children })] }));
+}
+/** Delta chip: green up / red down, neutral on zero. `text` is preformatted. */
+export function DeltaChip({ delta, text }) {
+    const up = delta > 0;
+    const down = delta < 0;
+    return (_jsxs("span", { className: cn('inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-medium tabular-nums', up && 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400', down && 'bg-rose-500/10 text-rose-600 dark:text-rose-400', !up && !down && 'bg-muted text-muted-foreground'), children: [up && '▲', down && '▼', text] }));
+}
+/** Centered empty state inside a widget body (no data / missing). */
+export function WidgetEmpty({ message }) {
+    return (_jsx("div", { className: "flex flex-1 items-center justify-center py-6 text-center text-xs text-muted-foreground", children: message }));
+}
+/** Per-widget error state — isolated so a broken widget never tumbles the grid. */
+export function WidgetError({ message }) {
+    return (_jsxs("div", { className: "flex flex-1 items-center justify-center gap-2 py-6 text-center text-xs text-destructive", children: [_jsx(DynamicIcon, { name: "TriangleAlert", className: "size-4" }), _jsx("span", { children: message })] }));
+}

package/dist/widgets/widget-format.d.ts

@@ -0,0 +1,42 @@
+import type { WidgetAccent, WidgetFormat } from '../dashboard-types';
+export interface WidgetFormatCtx {
+    format?: WidgetFormat;
+    locale?: string;
+    currency?: string;
+}
+/**
+ * Formats a scalar/series value with the widget's declared format. `currency`
+ * uses the org currency + locale (same fallback chain as table cells); `percent`
+ * treats the value as a fraction (0.142 → "14.2%"); `compact` uses Intl compact
+ * notation (1_200 → "1.2K").
+ */
+export declare function formatWidgetValue(value: number, { format, locale, currency }: WidgetFormatCtx): string;
+/** Axis-tick formatter — always compact so charts stay legible. */
+export declare function formatAxisTick(value: number, { format, locale, currency }: WidgetFormatCtx): string;
+/** Formats the compare delta fraction (0.142 → "+14.2%"). */
+export declare function formatDelta(delta: number, locale?: string): string;
+export interface AccentClasses {
+    /** Icon chip background + foreground. */
+    chip: string;
+    /** Text color for accented labels. */
+    text: string;
+    /** Solid bar/fill background (progress, list proportion). */
+    bar: string;
+    /** Soft track background behind a bar. */
+    track: string;
+    /** Hex-ish CSS color used for recharts stroke/fill (var-based). */
+    chartVar: string;
+}
+/** Resolves the accent class bundle, defaulting to `sky`. */
+export declare function accentClasses(accent?: WidgetAccent): AccentClasses;
+/**
+ * A categorical palette for multi-series charts (pie/donut/bar by bucket).
+ * Cycles the accent chart vars so slices stay theme-aware + dark-mode safe.
+ */
+export declare const CHART_PALETTE: string[];
+/** Picks a palette color by index, wrapping around. */
+export declare function paletteColor(index: number): string;
+/** Grid/axis muted color from the theme (works in light + dark). */
+export declare const CHART_MUTED = "var(--muted-foreground, #94a3b8)";
+export declare const CHART_GRID = "var(--border, #e2e8f0)";
+//# sourceMappingURL=widget-format.d.ts.map

package/dist/widgets/widget-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-format.d.ts","sourceRoot":"","sources":["../../src/widgets/widget-format.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEpE,MAAM,WAAW,eAAe;IAC5B,MAAM,CAAC,EAAE,YAAY,CAAA;IACrB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,MAAM,EACb,EAAE,MAAiB,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,eAAe,GACzD,MAAM,CA2BR;AAED,mEAAmE;AACnE,wBAAgB,cAAc,CAC1B,KAAK,EAAE,MAAM,EACb,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,eAAe,GAC9C,MAAM,CAoBR;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUlE;AAQD,MAAM,WAAW,aAAa;IAC1B,yCAAyC;IACzC,IAAI,EAAE,MAAM,CAAA;IACZ,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAA;IACZ,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAA;IACX,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAA;CACnB;AAiDD,6DAA6D;AAC7D,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,YAAY,GAAG,aAAa,CAElE;AAED;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,EAOjC,CAAA;AAED,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,oEAAoE;AACpE,eAAO,MAAM,WAAW,qCAAqC,CAAA;AAC7D,eAAO,MAAM,UAAU,2BAA2B,CAAA"}

package/dist/widgets/widget-format.js

@@ -0,0 +1,138 @@
+// Shared widget formatting + accent theming. Reuses the same Intl-based
+// approach as the table cells (dynamic-columns) so dashboard numbers read
+// identically to the grids: org currency + locale, compact notation, percent.
+/**
+ * Formats a scalar/series value with the widget's declared format. `currency`
+ * uses the org currency + locale (same fallback chain as table cells); `percent`
+ * treats the value as a fraction (0.142 → "14.2%"); `compact` uses Intl compact
+ * notation (1_200 → "1.2K").
+ */
+export function formatWidgetValue(value, { format = 'number', locale, currency }) {
+    if (value === null || value === undefined || Number.isNaN(value))
+        return '—';
+    const loc = locale || undefined;
+    switch (format) {
+        case 'currency':
+            return new Intl.NumberFormat(loc, {
+                style: 'currency',
+                currency: currency || 'USD',
+                maximumFractionDigits: 2,
+            }).format(value);
+        case 'percent':
+            return new Intl.NumberFormat(loc, {
+                style: 'percent',
+                minimumFractionDigits: 0,
+                maximumFractionDigits: 1,
+            }).format(value);
+        case 'compact':
+            return new Intl.NumberFormat(loc, {
+                notation: 'compact',
+                maximumFractionDigits: 1,
+            }).format(value);
+        case 'number':
+        default:
+            return new Intl.NumberFormat(loc, {
+                maximumFractionDigits: 2,
+            }).format(value);
+    }
+}
+/** Axis-tick formatter — always compact so charts stay legible. */
+export function formatAxisTick(value, { format, locale, currency }) {
+    const loc = locale || undefined;
+    if (format === 'currency') {
+        return new Intl.NumberFormat(loc, {
+            style: 'currency',
+            currency: currency || 'USD',
+            notation: 'compact',
+            maximumFractionDigits: 1,
+        }).format(value);
+    }
+    if (format === 'percent') {
+        return new Intl.NumberFormat(loc, {
+            style: 'percent',
+            maximumFractionDigits: 0,
+        }).format(value);
+    }
+    return new Intl.NumberFormat(loc, {
+        notation: 'compact',
+        maximumFractionDigits: 1,
+    }).format(value);
+}
+/** Formats the compare delta fraction (0.142 → "+14.2%"). */
+export function formatDelta(delta, locale) {
+    const sign = delta > 0 ? '+' : '';
+    return (sign +
+        new Intl.NumberFormat(locale || undefined, {
+            style: 'percent',
+            minimumFractionDigits: 0,
+            maximumFractionDigits: 1,
+        }).format(delta));
+}
+const ACCENTS = {
+    emerald: {
+        chip: 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+        text: 'text-emerald-600 dark:text-emerald-400',
+        bar: 'bg-emerald-500',
+        track: 'bg-emerald-500/15',
+        chartVar: 'var(--color-widget-emerald, #10b981)',
+    },
+    sky: {
+        chip: 'bg-sky-500/10 text-sky-600 dark:text-sky-400',
+        text: 'text-sky-600 dark:text-sky-400',
+        bar: 'bg-sky-500',
+        track: 'bg-sky-500/15',
+        chartVar: 'var(--color-widget-sky, #0ea5e9)',
+    },
+    violet: {
+        chip: 'bg-violet-500/10 text-violet-600 dark:text-violet-400',
+        text: 'text-violet-600 dark:text-violet-400',
+        bar: 'bg-violet-500',
+        track: 'bg-violet-500/15',
+        chartVar: 'var(--color-widget-violet, #8b5cf6)',
+    },
+    amber: {
+        chip: 'bg-amber-500/10 text-amber-600 dark:text-amber-400',
+        text: 'text-amber-600 dark:text-amber-400',
+        bar: 'bg-amber-500',
+        track: 'bg-amber-500/15',
+        chartVar: 'var(--color-widget-amber, #f59e0b)',
+    },
+    rose: {
+        chip: 'bg-rose-500/10 text-rose-600 dark:text-rose-400',
+        text: 'text-rose-600 dark:text-rose-400',
+        bar: 'bg-rose-500',
+        track: 'bg-rose-500/15',
+        chartVar: 'var(--color-widget-rose, #f43f5e)',
+    },
+    slate: {
+        chip: 'bg-slate-500/10 text-slate-600 dark:text-slate-300',
+        text: 'text-slate-600 dark:text-slate-300',
+        bar: 'bg-slate-500',
+        track: 'bg-slate-500/15',
+        chartVar: 'var(--color-widget-slate, #64748b)',
+    },
+};
+const DEFAULT_ACCENT = 'sky';
+/** Resolves the accent class bundle, defaulting to `sky`. */
+export function accentClasses(accent) {
+    return ACCENTS[accent ?? DEFAULT_ACCENT] ?? ACCENTS[DEFAULT_ACCENT];
+}
+/**
+ * A categorical palette for multi-series charts (pie/donut/bar by bucket).
+ * Cycles the accent chart vars so slices stay theme-aware + dark-mode safe.
+ */
+export const CHART_PALETTE = [
+    ACCENTS.sky.chartVar,
+    ACCENTS.emerald.chartVar,
+    ACCENTS.violet.chartVar,
+    ACCENTS.amber.chartVar,
+    ACCENTS.rose.chartVar,
+    ACCENTS.slate.chartVar,
+];
+/** Picks a palette color by index, wrapping around. */
+export function paletteColor(index) {
+    return CHART_PALETTE[index % CHART_PALETTE.length];
+}
+/** Grid/axis muted color from the theme (works in light + dark). */
+export const CHART_MUTED = 'var(--muted-foreground, #94a3b8)';
+export const CHART_GRID = 'var(--border, #e2e8f0)';

package/dist/widgets/widget-renderer.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+import type { DashboardWidgetSpec, WidgetData, WidgetSize } from '../dashboard-types';
+/** Maps a widget size to its column span in the 4-col grid. */
+export declare const SIZE_SPAN: Record<WidgetSize, number>;
+/** Tailwind col-span class per size (static → scanned in this package build). */
+export declare const SIZE_CLASS: Record<WidgetSize, string>;
+export interface WidgetRendererProps {
+    spec: DashboardWidgetSpec;
+    data?: WidgetData;
+    locale?: string;
+    currency?: string;
+    /** Translated empty fallback for this widget. */
+    emptyText: string;
+    /** Translated error message for this widget. */
+    errorText: string;
+}
+/**
+ * Renders one widget. `kind:"custom"` defers to the federated slot
+ * (`spec.slot ?? 'dashboard.widgets'`) inside the same card chrome so it
+ * combines with the declarative widgets.
+ */
+export declare function WidgetRenderer({ spec, data, locale, currency, emptyText, errorText, }: WidgetRendererProps): React.JSX.Element;
+/** Skeleton placeholder shown per widget while data loads. */
+export declare function WidgetSkeleton({ spec }: {
+    spec: DashboardWidgetSpec;
+}): React.JSX.Element;
+//# sourceMappingURL=widget-renderer.d.ts.map

package/dist/widgets/widget-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-renderer.d.ts","sourceRoot":"","sources":["../../src/widgets/widget-renderer.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAE9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAcrF,+DAA+D;AAC/D,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAKhD,CAAA;AAED,iFAAiF;AACjF,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAKjD,CAAA;AAiDD,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,mBAAmB,CAAA;IACzB,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAA;IACjB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAA;CACpB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAC3B,IAAI,EACJ,IAAI,EACJ,MAAM,EACN,QAAQ,EACR,SAAS,EACT,SAAS,GACZ,EAAE,mBAAmB,qBAkDrB;AAED,8DAA8D;AAC9D,wBAAgB,cAAc,CAAC,EAAE,IAAI,EAAE,EAAE;IAAE,IAAI,EAAE,mBAAmB,CAAA;CAAE,qBAqBrE"}

package/dist/widgets/widget-renderer.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Per-widget dispatcher: maps a spec.kind to its built-in renderer (or a
+// federated <Slot> for kind:"custom"), wrapped in an error boundary so a single
+// broken widget renders its own error card instead of tumbling the grid.
+import * as React from 'react';
+import { Slot } from '../slot';
+import { WidgetCard, WidgetError } from './widget-card';
+import { StatWidget, BarWidget, LineWidget, AreaWidget, PieWidget, DonutWidget, ListWidget, ProgressWidget, } from './renderers';
+/** Maps a widget size to its column span in the 4-col grid. */
+export const SIZE_SPAN = {
+    sm: 1,
+    md: 2,
+    lg: 3,
+    full: 4,
+};
+/** Tailwind col-span class per size (static → scanned in this package build). */
+export const SIZE_CLASS = {
+    sm: 'sm:col-span-2 lg:col-span-1',
+    md: 'sm:col-span-2 lg:col-span-2',
+    lg: 'sm:col-span-2 lg:col-span-3',
+    full: 'sm:col-span-2 lg:col-span-4',
+};
+const RENDERERS = {
+    stat: StatWidget,
+    bar: BarWidget,
+    line: LineWidget,
+    area: AreaWidget,
+    pie: PieWidget,
+    donut: DonutWidget,
+    list: ListWidget,
+    progress: ProgressWidget,
+};
+/** Isolated boundary: a throwing widget renders its own error card. */
+class WidgetErrorBoundary extends React.Component {
+    state = { error: false };
+    static getDerivedStateFromError() {
+        return { error: true };
+    }
+    render() {
+        if (this.state.error) {
+            return (_jsx(WidgetCard, { "data-testid": `widget-${this.props.spec.key}`, title: this.props.spec.title, subtitle: this.props.spec.subtitle, icon: this.props.spec.icon, accent: this.props.spec.accent, children: _jsx(WidgetError, { message: this.props.message }) }));
+        }
+        return this.props.children;
+    }
+}
+/**
+ * Renders one widget. `kind:"custom"` defers to the federated slot
+ * (`spec.slot ?? 'dashboard.widgets'`) inside the same card chrome so it
+ * combines with the declarative widgets.
+ */
+export function WidgetRenderer({ spec, data, locale, currency, emptyText, errorText, }) {
+    let body;
+    if (spec.kind === 'custom') {
+        body = (_jsx(WidgetCard, { "data-testid": `widget-${spec.key}`, title: spec.title, subtitle: spec.subtitle, icon: spec.icon, accent: spec.accent, children: _jsx(Slot, { name: spec.slot ?? 'dashboard.widgets', props: { spec, data, locale, currency }, fallback: _jsx("div", { className: "flex flex-1 items-center justify-center py-6 text-xs text-muted-foreground", children: emptyText }) }) }));
+    }
+    else {
+        const Renderer = RENDERERS[spec.kind];
+        body = Renderer ? (_jsx(Renderer, { spec: spec, data: data, locale: locale, currency: currency, emptyText: emptyText })) : (_jsx(WidgetCard, { "data-testid": `widget-${spec.key}`, title: spec.title, subtitle: spec.subtitle, icon: spec.icon, accent: spec.accent, children: _jsx(WidgetError, { message: errorText }) }));
+    }
+    return (_jsx(WidgetErrorBoundary, { spec: spec, message: errorText, children: body }));
+}
+/** Skeleton placeholder shown per widget while data loads. */
+export function WidgetSkeleton({ spec }) {
+    const isChart = spec.kind !== 'stat' && spec.kind !== 'progress' && spec.kind !== 'custom';
+    return (_jsx(WidgetCard, { "data-testid": `widget-skeleton-${spec.key}`, title: spec.title, subtitle: spec.subtitle, icon: spec.icon, accent: spec.accent, children: isChart ? (_jsx("div", { className: "h-[132px] w-full animate-pulse rounded-md bg-muted" })) : (_jsxs("div", { className: "flex flex-col gap-2", children: [_jsx("div", { className: "h-8 w-2/3 animate-pulse rounded bg-muted" }), _jsx("div", { className: "h-2 w-full animate-pulse rounded bg-muted/60" })] })) }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "18.16.0",
+  "version": "18.17.0",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@module-federation/runtime": "^2.5.0",
+    "recharts": "^2.15.0",
     "zod": "^4.3.0"
   },
   "peerDependencies": {
@@ -34,7 +35,7 @@
     "sonner": ">=1.7",
     "zustand": ">=5",
     "@asteby/metacore-sdk": "^3.2.0",
-    "@asteby/metacore-ui": "^2.5.1"
+    "@asteby/metacore-ui": "^2.5.2"
   },
   "peerDependenciesMeta": {
     "@tanstack/react-router": {
@@ -64,7 +65,7 @@
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
     "@asteby/metacore-sdk": "3.2.0",
-    "@asteby/metacore-ui": "2.5.1"
+    "@asteby/metacore-ui": "2.5.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/src/__tests__/dashboard-grid.test.tsx

@@ -0,0 +1,222 @@
+// @vitest-environment happy-dom
+//
+// DashboardGrid contract coverage:
+//   - normalizeGroups (pure): flat widgets → ordered groups by group/order.
+//   - render per kind: stat/list/progress paint their value; chart kinds paint
+//     the card chrome (title) — recharts itself isn't exercised in jsdom.
+//   - skeletons while loading, then real content after the batch resolves.
+//   - global empty state when there are no widgets.
+//   - permission gating via <PermissionsProvider> (and isAdmin bypass).
+//   - isolated per-widget error: a throwing renderer shows its error card and
+//     the sibling widgets still render.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+
+// react-i18next: identity translator (returns the key) so specs' raw i18n keys
+// surface verbatim and we can assert on them.
+vi.mock('react-i18next', () => ({
+    useTranslation: () => ({ t: (k: string) => k }),
+}))
+
+// recharts' ResponsiveContainer relies on ResizeObserver; stub it for happy-dom.
+class ResizeObserverStub {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+}
+;(globalThis as any).ResizeObserver = (globalThis as any).ResizeObserver ?? ResizeObserverStub
+
+afterEach(cleanup)
+
+import { DashboardGrid, normalizeGroups } from '../dashboard-grid'
+import { PermissionsProvider } from '../permissions-context'
+import type {
+    DashboardWidgetSpec,
+    WidgetData,
+} from '../dashboard-types'
+
+const spec = (over: Partial<DashboardWidgetSpec>): DashboardWidgetSpec => ({
+    key: 'k',
+    title: 'Title',
+    kind: 'stat',
+    ...over,
+})
+
+const loaderOf =
+    (map: Record<string, WidgetData>) => async (keys: string[]) => {
+        const out: Record<string, WidgetData> = {}
+        for (const k of keys) if (map[k]) out[k] = map[k]
+        return out
+    }
+
+describe('normalizeGroups', () => {
+    it('returns explicit groups untouched', () => {
+        const groups = [{ title: 'g1', widgets: [spec({ key: 'a' })] }]
+        expect(normalizeGroups(groups, undefined)).toBe(groups)
+    })
+
+    it('groups flat widgets by `group` and sorts each by `order`', () => {
+        const widgets = [
+            spec({ key: 'b', group: 'sales', order: 20 }),
+            spec({ key: 'a', group: 'sales', order: 10 }),
+            spec({ key: 'c', group: 'stock' }),
+        ]
+        const out = normalizeGroups(undefined, widgets)
+        expect(out.map((g) => g.title)).toEqual(['sales', 'stock'])
+        expect(out[0].widgets.map((w) => w.key)).toEqual(['a', 'b'])
+    })
+
+    it('returns [] when there is nothing', () => {
+        expect(normalizeGroups(undefined, [])).toEqual([])
+    })
+})
+
+describe('DashboardGrid render', () => {
+    it('shows a skeleton while loading then the stat value', async () => {
+        let resolve!: (v: Record<string, WidgetData>) => void
+        const loadData = vi.fn(
+            () => new Promise<Record<string, WidgetData>>((r) => (resolve = r)),
+        )
+        render(
+            <DashboardGrid
+                widgets={[spec({ key: 'rev', kind: 'stat' })]}
+                loadData={loadData}
+            />,
+        )
+        // skeleton up first
+        expect(screen.getByTestId('widget-skeleton-rev')).toBeTruthy()
+        resolve({ rev: { value: 42 } })
+        await waitFor(() =>
+            expect(screen.getByTestId('widget-rev')).toBeTruthy(),
+        )
+        expect(screen.getByText('42')).toBeTruthy()
+    })
+
+    it('renders a currency stat with the org currency + delta chip', async () => {
+        render(
+            <DashboardGrid
+                widgets={[
+                    spec({ key: 'rev', kind: 'stat', format: 'currency' }),
+                ]}
+                currency="MXN"
+                locale="en-US"
+                loadData={loaderOf({ rev: { value: 1000, delta: 0.142 } })}
+            />,
+        )
+        await waitFor(() => expect(screen.getByTestId('widget-rev')).toBeTruthy())
+        // MX$1,000.00 (en-US + MXN) — assert the currency symbol + amount present
+        expect(screen.getByText(/1,000/)).toBeTruthy()
+        expect(screen.getByText(/\+14\.2%/)).toBeTruthy()
+    })
+
+    it('renders a list widget with each bucket label + value', async () => {
+        render(
+            <DashboardGrid
+                widgets={[spec({ key: 'top', kind: 'list' })]}
+                loadData={loaderOf({
+                    top: {
+                        series: [
+                            { key: 'a', label: 'Alpha', value: 10 },
+                            { key: 'b', label: 'Beta', value: 5 },
+                        ],
+                    },
+                })}
+            />,
+        )
+        await waitFor(() => expect(screen.getByText('Alpha')).toBeTruthy())
+        expect(screen.getByText('Beta')).toBeTruthy()
+    })
+
+    it('paints the card chrome (title) for chart kinds', async () => {
+        render(
+            <DashboardGrid
+                widgets={[spec({ key: 'chart', title: 'My Chart', kind: 'bar' })]}
+                loadData={loaderOf({
+                    chart: { series: [{ key: 'a', label: 'A', value: 3 }] },
+                })}
+            />,
+        )
+        await waitFor(() => expect(screen.getByTestId('widget-chart')).toBeTruthy())
+        expect(screen.getByText('My Chart')).toBeTruthy()
+    })
+
+    it('shows the per-widget empty state when data is missing', async () => {
+        render(
+            <DashboardGrid
+                widgets={[spec({ key: 'empty', kind: 'stat', empty: 'No stock' })]}
+                loadData={loaderOf({})}
+            />,
+        )
+        await waitFor(() => expect(screen.getByTestId('widget-empty')).toBeTruthy())
+        expect(screen.getByText('No stock')).toBeTruthy()
+    })
+
+    it('shows the global empty state when there are no widgets', () => {
+        render(<DashboardGrid widgets={[]} loadData={loaderOf({})} />)
+        expect(screen.getByTestId('dashboard-empty')).toBeTruthy()
+    })
+})
+
+describe('DashboardGrid permission gating', () => {
+    it('without a PermissionsProvider every widget is visible', async () => {
+        render(
+            <DashboardGrid
+                widgets={[spec({ key: 'p', kind: 'stat', permission: 'x.read' })]}
+                loadData={loaderOf({ p: { value: 1 } })}
+            />,
+        )
+        await waitFor(() => expect(screen.getByTestId('widget-p')).toBeTruthy())
+    })
+
+    it('hides widgets whose permission is not granted', () => {
+        render(
+            <PermissionsProvider permissions={['other.read']} isAdmin={false}>
+                <DashboardGrid
+                    widgets={[
+                        spec({ key: 'p', kind: 'stat', permission: 'secret.read' }),
+                    ]}
+                    loadData={loaderOf({ p: { value: 1 } })}
+                />
+            </PermissionsProvider>,
+        )
+        // gated out → whole grid is empty → global empty state
+        expect(screen.queryByTestId('widget-skeleton-p')).toBeNull()
+        expect(screen.getByTestId('dashboard-empty')).toBeTruthy()
+    })
+
+    it('shows granted widgets and respects isAdmin bypass', async () => {
+        render(
+            <PermissionsProvider permissions={[]} isAdmin={false}>
+                <DashboardGrid
+                    isAdmin
+                    widgets={[
+                        spec({ key: 'p', kind: 'stat', permission: 'secret.read' }),
+                    ]}
+                    loadData={loaderOf({ p: { value: 7 } })}
+                />
+            </PermissionsProvider>,
+        )
+        await waitFor(() => expect(screen.getByTestId('widget-p')).toBeTruthy())
+    })
+})
+
+describe('DashboardGrid error isolation', () => {
+    it('a throwing widget shows its error card; siblings still render', async () => {
+        // An unknown kind without a renderer falls to the error card path.
+        render(
+            <DashboardGrid
+                widgets={[
+                    spec({ key: 'ok', kind: 'stat' }),
+                    spec({ key: 'bad', kind: 'nonsense' as any }),
+                ]}
+                loadData={loaderOf({ ok: { value: 9 }, bad: { value: 1 } })}
+            />,
+        )
+        await waitFor(() => expect(screen.getByTestId('widget-ok')).toBeTruthy())
+        // sibling renders its value
+        expect(screen.getByText('9')).toBeTruthy()
+        // broken one shows the error card (not crashing the grid)
+        expect(screen.getByTestId('widget-bad')).toBeTruthy()
+        expect(screen.getByText('Could not load this widget.')).toBeTruthy()
+    })
+})