@asteby/metacore-runtime-react 18.17.1 → 18.17.3

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @asteby/metacore-runtime-react
 
+## 18.17.3
+
+### Patch Changes
+
+- d2c92e1: Fix React #310: move flatten/order useMemo before the empty-state early return (conditional hook crashed on empty→populated)
+
+## 18.17.2
+
+### Patch Changes
+
+- 714cc34: Dashboard: masonry (balanced CSS columns) layout — no blank cells; charts fixed-height, compact stat cards
+
 ## 18.17.1
 
 ### Patch Changes

package/dist/dashboard-grid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dashboard-grid.d.ts","sourceRoot":"","sources":["../src/dashboard-grid.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,OAAO,KAAK,EACR,kBAAkB,EAElB,oBAAoB,EACpB,mBAAmB,EACtB,MAAM,mBAAmB,CAAA;AAW1B,uEAAuE;AACvE,wBAAgB,eAAe,CAC3B,MAAM,CAAC,EAAE,oBAAoB,EAAE,EAC/B,OAAO,CAAC,EAAE,mBAAmB,EAAE,GAChC,oBAAoB,EAAE,CAgBxB;AASD,wBAAgB,aAAa,CAAC,EAC1B,MAAM,EACN,OAAO,EACP,QAAQ,EACR,OAAO,EACP,MAAM,EACN,QAAQ,EACR,SAAS,EACT,OAAO,GACV,EAAE,kBAAkB,qBA2IpB"}
+{"version":3,"file":"dashboard-grid.d.ts","sourceRoot":"","sources":["../src/dashboard-grid.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAK9B,OAAO,KAAK,EACR,kBAAkB,EAElB,oBAAoB,EACpB,mBAAmB,EACtB,MAAM,mBAAmB,CAAA;AAW1B,uEAAuE;AACvE,wBAAgB,eAAe,CAC3B,MAAM,CAAC,EAAE,oBAAoB,EAAE,EAC/B,OAAO,CAAC,EAAE,mBAAmB,EAAE,GAChC,oBAAoB,EAAE,CAgBxB;AASD,wBAAgB,aAAa,CAAC,EAC1B,MAAM,EACN,OAAO,EACP,QAAQ,EACR,OAAO,EACP,MAAM,EACN,QAAQ,EACR,SAAS,EACT,OAAO,GACV,EAAE,kBAAkB,qBAiJpB"}

package/dist/dashboard-grid.js

@@ -9,7 +9,7 @@ import { useTranslation } from 'react-i18next';
 import { cn } from '@asteby/metacore-ui/lib';
 import { useCan, usePermissionsActive } from './permissions-context';
 import { DynamicIcon } from './dynamic-icon';
-import { WidgetRenderer, WidgetSkeleton, spanClass } from './widgets/widget-renderer';
+import { WidgetRenderer, WidgetSkeleton, isTallWidget } from './widgets/widget-renderer';
 const DEFAULT_STRINGS = {
     emptyTitle: 'Your dashboard is empty',
     emptyDescription: 'Install an addon with dashboard widgets to start seeing metrics here.',
@@ -106,21 +106,33 @@ export function DashboardGrid({ groups, widgets, loadData, isAdmin, locale, curr
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [keySig, loadData]);
+    // Flatten every group into ONE ordered list (compact KPIs before charts) for
+    // the masonry grid. MUST run before any early return — it is a hook, and a
+    // conditional hook (placed after the empty-state return) trips React #310
+    // when the dashboard transitions empty → populated.
+    const ordered = React.useMemo(() => {
+        const flat = visibleGroups.flatMap((g) => g.widgets);
+        return flat
+            .map((w, i) => ({ w, i }))
+            .sort((a, b) => (isTallWidget(a.w) ? 1 : 0) - (isTallWidget(b.w) ? 1 : 0) ||
+            a.i - b.i)
+            .map((x) => x.w);
+    }, [visibleGroups]);
     // Global empty state (no widgets at all / none visible after gating).
     if (visibleGroups.length === 0) {
         return (_jsxs("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), children: [_jsx("div", { className: "mb-4 flex size-14 items-center justify-center rounded-2xl bg-muted text-muted-foreground", children: _jsx(DynamicIcon, { name: "LayoutDashboard", className: "size-7" }) }), _jsx("h3", { className: "text-base font-semibold text-foreground", children: tr(undefined, s.emptyTitle) || s.emptyTitle }), _jsx("p", { className: "mt-1 max-w-sm text-sm text-muted-foreground", children: s.emptyDescription })] }));
     }
-    return (_jsx("div", { "data-testid": "dashboard-grid", className: cn('flex flex-col gap-8', className), children: visibleGroups.map((group) => (_jsxs("section", { className: "flex flex-col gap-3", children: [group.title && (_jsx("h2", { className: "text-sm font-semibold uppercase tracking-wide text-muted-foreground", children: tr(group.title, group.title) })), _jsx("div", { className: "grid grid-flow-row-dense auto-rows-[116px] grid-cols-2 gap-4 lg:grid-cols-4", children: group.widgets.map((spec) => {
-                        return (_jsx("div", { className: cn(spanClass(spec), 'min-h-0'), children: loading ? (_jsx(WidgetSkeleton, { spec: {
-                                    ...spec,
-                                    title: tr(spec.title, spec.title),
-                                    subtitle: tr(spec.subtitle, spec.subtitle),
-                                } })) : (_jsx(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 })) }, spec.key));
-                    }) })] }, group.title || '__default'))) }));
+    return (_jsx("div", { "data-testid": "dashboard-grid", className: cn(
+        // Masonry: balanced CSS columns. Cards take their natural height
+        // (compact stats, taller charts) and flow to equalize column
+        // height, so there are NO blank cells — the gaps a fixed grid
+        // leaves around mixed 1×1 / 2×2 tiles simply don't exist here.
+        'columns-1 gap-4 md:columns-2 xl:columns-3', className), children: ordered.map((spec) => {
+            const rspec = {
+                ...spec,
+                title: tr(spec.title, spec.title),
+                subtitle: tr(spec.subtitle, spec.subtitle),
+            };
+            return (_jsx("div", { className: "mb-4 break-inside-avoid", children: loading ? (_jsx(WidgetSkeleton, { spec: rspec })) : (_jsx(WidgetRenderer, { spec: rspec, data: data?.[spec.key], locale: locale, currency: currency, emptyText: spec.empty ? tr(spec.empty, spec.empty) : s.widgetEmpty, errorText: s.widgetError })) }, spec.key));
+        }) }));
 }

package/dist/widgets/renderers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderers.d.ts","sourceRoot":"","sources":["../../src/widgets/renderers.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAkB9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAazE,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,mBAAmB,CAAA;IACzB,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;CACpB;AA4CD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBA6B9C;AAGD,wBAAgB,SAAS,CAAC,CAAC,EAAE,iBAAiB,qBAsC7C;AAgDD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBAE9C;AACD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBAE9C;AAuDD,wBAAgB,SAAS,CAAC,CAAC,EAAE,iBAAiB,qBAE7C;AACD,wBAAgB,WAAW,CAAC,CAAC,EAAE,iBAAiB,qBAE/C;AAGD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBAqC9C;AAKD,wBAAgB,cAAc,CAAC,CAAC,EAAE,iBAAiB,qBAkClD"}
+{"version":3,"file":"renderers.d.ts","sourceRoot":"","sources":["../../src/widgets/renderers.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAA;AAkB9B,OAAO,KAAK,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAazE,MAAM,WAAW,iBAAiB;IAC9B,IAAI,EAAE,mBAAmB,CAAA;IACzB,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAA;CACpB;AA8CD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBA+B9C;AAGD,wBAAgB,SAAS,CAAC,CAAC,EAAE,iBAAiB,qBAsC7C;AAgDD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBAE9C;AACD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBAE9C;AAuDD,wBAAgB,SAAS,CAAC,CAAC,EAAE,iBAAiB,qBAE7C;AACD,wBAAgB,WAAW,CAAC,CAAC,EAAE,iBAAiB,qBAE/C;AAGD,wBAAgB,UAAU,CAAC,CAAC,EAAE,iBAAiB,qBAqC9C;AAKD,wBAAgB,cAAc,CAAC,CAAC,EAAE,iBAAiB,qBAkClD"}

package/dist/widgets/renderers.js

@@ -5,11 +5,13 @@ import { WidgetCard, DeltaChip, WidgetEmpty } from './widget-card';
 import { accentClasses, paletteColor, formatWidgetValue, formatAxisTick, formatDelta, CHART_GRID, CHART_MUTED, } from './widget-format';
 const fmtCtx = (spec, locale, currency) => ({ format: spec.format, locale, currency });
 const hasSeries = (d) => Array.isArray(d?.series) && d.series.length > 0;
-// Chart body that fills the card's flexible height. The dashboard grid gives
-// each chart cell a definite height (fixed auto-rows × row-span), so height:100%
-// resolves cleanly and charts scale with the card instead of a fixed stub.
+// Fixed-height chart body. In the masonry (CSS columns) layout cards take their
+// natural height, so charts need a definite height for ResponsiveContainer to
+// resolve. This height + the card chrome gives every chart card a consistent,
+// taller footprint that balances cleanly against compact stat cards.
+const CHART_H = 'h-[190px]';
 function ChartArea({ children }) {
-    return (_jsx("div", { className: "min-h-0 flex-1", children: _jsx(ResponsiveContainer, { width: "100%", height: "100%", children: children }) }));
+    return (_jsx("div", { className: cn(CHART_H, 'w-full'), children: _jsx(ResponsiveContainer, { width: "100%", height: "100%", children: children }) }));
 }
 // Compact recharts tooltip styled with theme tokens.
 function ChartTooltip({ ctx }) {
@@ -28,7 +30,7 @@ export function StatWidget(p) {
     const value = p.data?.value;
     const delta = p.data?.delta;
     const hasValue = typeof value === 'number' && !Number.isNaN(value);
-    return (_jsx(WidgetCard, { "data-testid": `widget-${p.spec.key}`, title: p.spec.title, subtitle: p.spec.subtitle, icon: p.spec.icon, accent: p.spec.accent, headerExtra: typeof delta === 'number' ? (_jsx(DeltaChip, { delta: delta, text: formatDelta(delta, p.locale) })) : undefined, children: hasValue ? (_jsx("div", { className: "flex min-h-0 flex-1 flex-col justify-center", children: _jsx("div", { className: "text-[2rem] font-semibold leading-none tabular-nums tracking-tight text-foreground", children: formatWidgetValue(value, ctx) }) })) : (_jsx(WidgetEmpty, { message: p.emptyText })) }));
+    return (_jsx(WidgetCard, { "data-testid": `widget-${p.spec.key}`, title: p.spec.title, subtitle: p.spec.subtitle, icon: p.spec.icon, accent: p.spec.accent, headerExtra: typeof delta === 'number' ? (_jsx(DeltaChip, { delta: delta, text: formatDelta(delta, p.locale) })) : undefined, children: hasValue ? (_jsx("div", { className: "flex min-h-[2.5rem] items-end", children: _jsx("div", { className: "text-[2rem] font-semibold leading-none tabular-nums tracking-tight text-foreground", children: formatWidgetValue(value, ctx) }) })) : (_jsx("div", { className: "flex min-h-[2.5rem] items-center text-sm text-muted-foreground", children: p.emptyText })) }));
 }
 // --- bar ------------------------------------------------------------------
 export function BarWidget(p) {
@@ -52,7 +54,7 @@ export function AreaWidget(p) {
 // --- pie / donut (shared) -------------------------------------------------
 function CircularWidget(p) {
     const ctx = fmtCtx(p.spec, p.locale, p.currency);
-    return (_jsx(WidgetCard, { "data-testid": `widget-${p.spec.key}`, title: p.spec.title, subtitle: p.spec.subtitle, icon: p.spec.icon, accent: p.spec.accent, children: hasSeries(p.data) ? (_jsxs("div", { className: "flex min-h-0 flex-1 items-center gap-3", children: [_jsx("div", { className: "h-full min-h-0 w-[46%] shrink-0", children: _jsx(ResponsiveContainer, { width: "100%", height: "100%", children: _jsxs(PieChart, { children: [_jsx(ChartTooltip, { ctx: ctx }), _jsx(Pie, { data: p.data.series, dataKey: "value", nameKey: "label", innerRadius: p.variant === 'donut' ? '55%' : 0, outerRadius: "92%", paddingAngle: p.variant === 'donut' ? 2 : 0, stroke: "var(--background, #fff)", strokeWidth: 2, children: p.data.series.map((_, i) => (_jsx(Cell, { fill: paletteColor(i) }, i))) })] }) }) }), _jsx("ul", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: p.data.series.slice(0, 6).map((pt, i) => (_jsxs("li", { className: "flex items-center gap-2 text-xs", children: [_jsx("span", { className: "size-2.5 shrink-0 rounded-sm", style: { background: paletteColor(i) } }), _jsx("span", { className: "truncate text-muted-foreground", children: pt.label }), _jsx("span", { className: "ml-auto shrink-0 font-medium tabular-nums text-foreground", children: formatWidgetValue(pt.value, ctx) })] }, pt.key))) })] })) : (_jsx(WidgetEmpty, { message: p.emptyText })) }));
+    return (_jsx(WidgetCard, { "data-testid": `widget-${p.spec.key}`, title: p.spec.title, subtitle: p.spec.subtitle, icon: p.spec.icon, accent: p.spec.accent, children: hasSeries(p.data) ? (_jsxs("div", { className: cn(CHART_H, 'flex items-center gap-3'), children: [_jsx("div", { className: "h-full min-h-0 w-[46%] shrink-0", children: _jsx(ResponsiveContainer, { width: "100%", height: "100%", children: _jsxs(PieChart, { children: [_jsx(ChartTooltip, { ctx: ctx }), _jsx(Pie, { data: p.data.series, dataKey: "value", nameKey: "label", innerRadius: p.variant === 'donut' ? '55%' : 0, outerRadius: "92%", paddingAngle: p.variant === 'donut' ? 2 : 0, stroke: "var(--background, #fff)", strokeWidth: 2, children: p.data.series.map((_, i) => (_jsx(Cell, { fill: paletteColor(i) }, i))) })] }) }) }), _jsx("ul", { className: "flex min-w-0 flex-1 flex-col gap-1.5", children: p.data.series.slice(0, 6).map((pt, i) => (_jsxs("li", { className: "flex items-center gap-2 text-xs", children: [_jsx("span", { className: "size-2.5 shrink-0 rounded-sm", style: { background: paletteColor(i) } }), _jsx("span", { className: "truncate text-muted-foreground", children: pt.label }), _jsx("span", { className: "ml-auto shrink-0 font-medium tabular-nums text-foreground", children: formatWidgetValue(pt.value, ctx) })] }, pt.key))) })] })) : (_jsx(WidgetEmpty, { message: p.emptyText })) }));
 }
 export function PieWidget(p) {
     return _jsx(CircularWidget, { ...p, variant: "pie" });

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

@@ -11,6 +11,9 @@ export declare function defaultSize(spec: DashboardWidgetSpec): WidgetSize;
 /** Combined col + row span for a widget's grid cell. Row-span drives the
  * height contrast (chart=2, stat=1) that makes the layout feel designed. */
 export declare function spanClass(spec: DashboardWidgetSpec): string;
+/** True for chart/list widgets that occupy 2 rows. Used to order compact KPIs
+ * before charts in the unified grid so the top reads as a metric band. */
+export declare function isTallWidget(spec: DashboardWidgetSpec): boolean;
 export interface WidgetRendererProps {
     spec: DashboardWidgetSpec;
     data?: WidgetData;

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

@@ -1 +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;6EAC6E;AAC7E,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAKjD,CAAA;AAMD;kFACkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,UAAU,CAGjE;AAED;4EAC4E;AAC5E,wBAAgB,SAAS,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAG3D;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"}
+{"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;6EAC6E;AAC7E,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,CAKjD,CAAA;AAMD;kFACkF;AAClF,wBAAgB,WAAW,CAAC,IAAI,EAAE,mBAAmB,GAAG,UAAU,CAGjE;AAED;4EAC4E;AAC5E,wBAAgB,SAAS,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAG3D;AAED;0EAC0E;AAC1E,wBAAgB,YAAY,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAE/D;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

@@ -37,6 +37,11 @@ export function spanClass(spec) {
     const col = SIZE_CLASS[defaultSize(spec)];
     return `${col} ${TALL_KINDS.has(spec.kind) ? 'row-span-2' : 'row-span-1'}`;
 }
+/** True for chart/list widgets that occupy 2 rows. Used to order compact KPIs
+ * before charts in the unified grid so the top reads as a metric band. */
+export function isTallWidget(spec) {
+    return TALL_KINDS.has(spec.kind);
+}
 const RENDERERS = {
     stat: StatWidget,
     bar: BarWidget,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "18.17.1",
+  "version": "18.17.3",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",

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

@@ -155,6 +155,24 @@ describe('DashboardGrid render', () => {
         render(<DashboardGrid widgets={[]} loadData={loaderOf({})} />)
         expect(screen.getByTestId('dashboard-empty')).toBeTruthy()
     })
+
+    it('survives an empty → populated transition (React #310 regression)', async () => {
+        // The flatten/order useMemo must run BEFORE the empty-state early return.
+        // When it sat after the return, an empty render called one fewer hook
+        // than the populated render → "Rendered more hooks" (React #310) crash.
+        const { rerender } = render(
+            <DashboardGrid widgets={[]} loadData={loaderOf({})} />,
+        )
+        expect(screen.getByTestId('dashboard-empty')).toBeTruthy()
+        rerender(
+            <DashboardGrid
+                widgets={[spec({ key: 'rev', kind: 'stat' })]}
+                loadData={loaderOf({ rev: { value: 5 } })}
+            />,
+        )
+        await waitFor(() => expect(screen.getByTestId('widget-rev')).toBeTruthy())
+        expect(screen.getByText('5')).toBeTruthy()
+    })
 })
 
 describe('DashboardGrid permission gating', () => {

package/src/dashboard-grid.tsx

@@ -15,7 +15,7 @@ import type {
     DashboardWidgetGroup,
     DashboardWidgetSpec,
 } from './dashboard-types'
-import { WidgetRenderer, WidgetSkeleton, spanClass } from './widgets/widget-renderer'
+import { WidgetRenderer, WidgetSkeleton, isTallWidget } from './widgets/widget-renderer'
 
 const DEFAULT_STRINGS: DashboardGridStrings = {
     emptyTitle: 'Your dashboard is empty',
@@ -132,6 +132,22 @@ export function DashboardGrid({
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [keySig, loadData])
 
+    // Flatten every group into ONE ordered list (compact KPIs before charts) for
+    // the masonry grid. MUST run before any early return — it is a hook, and a
+    // conditional hook (placed after the empty-state return) trips React #310
+    // when the dashboard transitions empty → populated.
+    const ordered = React.useMemo(() => {
+        const flat = visibleGroups.flatMap((g) => g.widgets)
+        return flat
+            .map((w, i) => ({ w, i }))
+            .sort(
+                (a, b) =>
+                    (isTallWidget(a.w) ? 1 : 0) - (isTallWidget(b.w) ? 1 : 0) ||
+                    a.i - b.i,
+            )
+            .map((x) => x.w)
+    }, [visibleGroups])
+
     // Global empty state (no widgets at all / none visible after gating).
     if (visibleGroups.length === 0) {
         return (
@@ -156,50 +172,40 @@ export function DashboardGrid({
     }
 
     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-flow-row-dense auto-rows-[116px] grid-cols-2 gap-4 lg:grid-cols-4">
-                        {group.widgets.map((spec) => {
-                            return (
-                                <div key={spec.key} className={cn(spanClass(spec), 'min-h-0')}>
-                                    {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
+            data-testid="dashboard-grid"
+            className={cn(
+                // Masonry: balanced CSS columns. Cards take their natural height
+                // (compact stats, taller charts) and flow to equalize column
+                // height, so there are NO blank cells — the gaps a fixed grid
+                // leaves around mixed 1×1 / 2×2 tiles simply don't exist here.
+                'columns-1 gap-4 md:columns-2 xl:columns-3',
+                className,
+            )}
+        >
+            {ordered.map((spec) => {
+                const rspec = {
+                    ...spec,
+                    title: tr(spec.title, spec.title),
+                    subtitle: tr(spec.subtitle, spec.subtitle),
+                }
+                return (
+                    <div key={spec.key} className="mb-4 break-inside-avoid">
+                        {loading ? (
+                            <WidgetSkeleton spec={rspec} />
+                        ) : (
+                            <WidgetRenderer
+                                spec={rspec}
+                                data={data?.[spec.key]}
+                                locale={locale}
+                                currency={currency}
+                                emptyText={spec.empty ? tr(spec.empty, spec.empty) : s.widgetEmpty}
+                                errorText={s.widgetError}
+                            />
+                        )}
                     </div>
-                </section>
-            ))}
+                )
+            })}
         </div>
     )
 }

package/src/widgets/renderers.tsx

@@ -53,12 +53,14 @@ const fmtCtx = (
 const hasSeries = (d?: WidgetData): d is WidgetData & { series: NonNullable<WidgetData['series']> } =>
     Array.isArray(d?.series) && d!.series!.length > 0
 
-// Chart body that fills the card's flexible height. The dashboard grid gives
-// each chart cell a definite height (fixed auto-rows × row-span), so height:100%
-// resolves cleanly and charts scale with the card instead of a fixed stub.
+// Fixed-height chart body. In the masonry (CSS columns) layout cards take their
+// natural height, so charts need a definite height for ResponsiveContainer to
+// resolve. This height + the card chrome gives every chart card a consistent,
+// taller footprint that balances cleanly against compact stat cards.
+const CHART_H = 'h-[190px]'
 function ChartArea({ children }: { children: React.ReactElement }) {
     return (
-        <div className="min-h-0 flex-1">
+        <div className={cn(CHART_H, 'w-full')}>
             <ResponsiveContainer width="100%" height="100%">
                 {children}
             </ResponsiveContainer>
@@ -105,13 +107,15 @@ export function StatWidget(p: WidgetRenderProps) {
             }
         >
             {hasValue ? (
-                <div className="flex min-h-0 flex-1 flex-col justify-center">
+                <div className="flex min-h-[2.5rem] items-end">
                     <div className="text-[2rem] font-semibold leading-none tabular-nums tracking-tight text-foreground">
                         {formatWidgetValue(value!, ctx)}
                     </div>
                 </div>
             ) : (
-                <WidgetEmpty message={p.emptyText} />
+                <div className="flex min-h-[2.5rem] items-center text-sm text-muted-foreground">
+                    {p.emptyText}
+                </div>
             )}
         </WidgetCard>
     )
@@ -223,7 +227,7 @@ function CircularWidget(p: WidgetRenderProps & { variant: 'pie' | 'donut' }) {
             accent={p.spec.accent}
         >
             {hasSeries(p.data) ? (
-                <div className="flex min-h-0 flex-1 items-center gap-3">
+                <div className={cn(CHART_H, 'flex items-center gap-3')}>
                     <div className="h-full min-h-0 w-[46%] shrink-0">
                         <ResponsiveContainer width="100%" height="100%">
                             <PieChart>

package/src/widgets/widget-renderer.tsx

@@ -53,6 +53,12 @@ export function spanClass(spec: DashboardWidgetSpec): string {
     return `${col} ${TALL_KINDS.has(spec.kind) ? 'row-span-2' : 'row-span-1'}`
 }
 
+/** True for chart/list widgets that occupy 2 rows. Used to order compact KPIs
+ * before charts in the unified grid so the top reads as a metric band. */
+export function isTallWidget(spec: DashboardWidgetSpec): boolean {
+    return TALL_KINDS.has(spec.kind)
+}
+
 const RENDERERS: Record<
     string,
     (p: WidgetRenderProps) => React.ReactElement