@asteby/metacore-runtime-react 18.16.1 → 18.17.0

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.1",
+  "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": {

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()
+    })
+})

package/src/dashboard-grid.tsx

@@ -0,0 +1,206 @@
+// DashboardGrid — the modular dashboard surface. Renders the union of
+// declarative + federated widgets in a responsive 4-column grid, grouped with
+// headings, honouring per-widget size, permission gating (useCan), batch data
+// loading with per-widget skeletons, isolated per-widget errors, and a pro
+// global empty state. See CONTRACT-dashboard-widgets.md §4.
+
+import * as React from 'react'
+import { useTranslation } from 'react-i18next'
+import { cn } from '@asteby/metacore-ui/lib'
+import { useCan, usePermissionsActive } from './permissions-context'
+import { DynamicIcon } from './dynamic-icon'
+import type {
+    DashboardGridProps,
+    DashboardGridStrings,
+    DashboardWidgetGroup,
+    DashboardWidgetSpec,
+} from './dashboard-types'
+import { WidgetRenderer, WidgetSkeleton, SIZE_CLASS } from './widgets/widget-renderer'
+
+const DEFAULT_STRINGS: DashboardGridStrings = {
+    emptyTitle: 'Your dashboard is empty',
+    emptyDescription:
+        'Install an addon with dashboard widgets to start seeing metrics here.',
+    widgetError: 'Could not load this widget.',
+    widgetEmpty: 'No data yet.',
+}
+
+/** Normalizes flat `widgets` + `groups` into an ordered group list. */
+export function normalizeGroups(
+    groups?: DashboardWidgetGroup[],
+    widgets?: DashboardWidgetSpec[],
+): DashboardWidgetGroup[] {
+    if (groups && groups.length > 0) return groups
+    if (!widgets || widgets.length === 0) return []
+    // Group flat widgets by `group` (preserve first-seen order), sort each
+    // group by `order` (default 100), keep insertion order across groups.
+    const map = new Map<string, DashboardWidgetSpec[]>()
+    for (const w of widgets) {
+        const key = w.group ?? ''
+        const arr = map.get(key) ?? []
+        arr.push(w)
+        map.set(key, arr)
+    }
+    return Array.from(map.entries()).map(([title, ws]) => ({
+        title,
+        widgets: [...ws].sort((a, b) => (a.order ?? 100) - (b.order ?? 100)),
+    }))
+}
+
+/** Collects every widget key across groups (for the batch loader). */
+function allKeys(groups: DashboardWidgetGroup[]): string[] {
+    const keys: string[] = []
+    for (const g of groups) for (const w of g.widgets) keys.push(w.key)
+    return keys
+}
+
+export function DashboardGrid({
+    groups,
+    widgets,
+    loadData,
+    isAdmin,
+    locale,
+    currency,
+    className,
+    strings,
+}: DashboardGridProps) {
+    const { t } = useTranslation()
+    const can = useCan()
+    const permissionsActive = usePermissionsActive()
+    const s = { ...DEFAULT_STRINGS, ...strings }
+
+    // i18n helper: translate a key, falling back to the raw key when missing
+    // (specs ship raw i18n keys; the host bundle may or may not have them).
+    const tr = React.useCallback(
+        (key?: string, fallback?: string): string => {
+            if (!key) return fallback ?? ''
+            const out = t(key)
+            return out === key ? fallback ?? key : out
+        },
+        [t],
+    )
+
+    // Permission gating: admin bypass; without a PermissionsProvider everything
+    // is visible (retrocompat). With one, honour each widget's `permission`.
+    const visibleGroups = React.useMemo(() => {
+        const norm = normalizeGroups(groups, widgets)
+        const gate = (w: DashboardWidgetSpec): boolean => {
+            if (isAdmin) return true
+            if (!permissionsActive) return true
+            if (!w.permission) return true
+            return can(w.permission)
+        }
+        return norm
+            .map((g) => ({ ...g, widgets: g.widgets.filter(gate) }))
+            .filter((g) => g.widgets.length > 0)
+    }, [groups, widgets, isAdmin, permissionsActive, can])
+
+    const keys = React.useMemo(() => allKeys(visibleGroups), [visibleGroups])
+    const keySig = keys.join(',')
+
+    const [data, setData] = React.useState<
+        Record<string, import('./dashboard-types').WidgetData> | null
+    >(null)
+    const [loading, setLoading] = React.useState(true)
+
+    React.useEffect(() => {
+        let cancelled = false
+        if (keys.length === 0) {
+            setLoading(false)
+            setData({})
+            return
+        }
+        setLoading(true)
+        loadData(keys)
+            .then((res) => {
+                if (!cancelled) {
+                    setData(res ?? {})
+                    setLoading(false)
+                }
+            })
+            .catch(() => {
+                // Batch failure: still render the grid; every widget falls to
+                // its empty/error state rather than blanking the page.
+                if (!cancelled) {
+                    setData({})
+                    setLoading(false)
+                }
+            })
+        return () => {
+            cancelled = true
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [keySig, loadData])
+
+    // Global empty state (no widgets at all / none visible after gating).
+    if (visibleGroups.length === 0) {
+        return (
+            <div
+                data-testid="dashboard-empty"
+                className={cn(
+                    'flex min-h-[40vh] flex-col items-center justify-center rounded-xl border border-dashed border-border/60 p-10 text-center',
+                    className,
+                )}
+            >
+                <div className="mb-4 flex size-14 items-center justify-center rounded-2xl bg-muted text-muted-foreground">
+                    <DynamicIcon name="LayoutDashboard" className="size-7" />
+                </div>
+                <h3 className="text-base font-semibold text-foreground">
+                    {tr(undefined, s.emptyTitle) || s.emptyTitle}
+                </h3>
+                <p className="mt-1 max-w-sm text-sm text-muted-foreground">
+                    {s.emptyDescription}
+                </p>
+            </div>
+        )
+    }
+
+    return (
+        <div data-testid="dashboard-grid" className={cn('flex flex-col gap-8', className)}>
+            {visibleGroups.map((group) => (
+                <section key={group.title || '__default'} className="flex flex-col gap-3">
+                    {group.title && (
+                        <h2 className="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                            {tr(group.title, group.title)}
+                        </h2>
+                    )}
+                    <div className="grid grid-cols-1 gap-4 sm:grid-cols-2 lg:grid-cols-4">
+                        {group.widgets.map((spec) => {
+                            const size = spec.size ?? 'sm'
+                            return (
+                                <div key={spec.key} className={SIZE_CLASS[size]}>
+                                    {loading ? (
+                                        <WidgetSkeleton
+                                            spec={{
+                                                ...spec,
+                                                title: tr(spec.title, spec.title),
+                                                subtitle: tr(spec.subtitle, spec.subtitle),
+                                            }}
+                                        />
+                                    ) : (
+                                        <WidgetRenderer
+                                            spec={{
+                                                ...spec,
+                                                title: tr(spec.title, spec.title),
+                                                subtitle: tr(spec.subtitle, spec.subtitle),
+                                            }}
+                                            data={data?.[spec.key]}
+                                            locale={locale}
+                                            currency={currency}
+                                            emptyText={
+                                                spec.empty
+                                                    ? tr(spec.empty, spec.empty)
+                                                    : s.widgetEmpty
+                                            }
+                                            errorText={s.widgetError}
+                                        />
+                                    )}
+                                </div>
+                            )
+                        })}
+                    </div>
+                </section>
+            ))}
+        </div>
+    )
+}