feat(render): Dashboard UX improvements — 12-column grid, smart defaults, card styling

[jswir]

Summary

• Dual layout modes: Dashboards without explicit # span, # dashboard { columns }, or # dashboard { gap } tags use a flex layout where items size naturally based on content. When any of those tags are present, the dashboard switches to a 12-column CSS grid with smart default spans (measures → span 3, nests → span 4-12 based on weighted child content).
• Card styling: All dashboard items (KPIs, charts, tables) render in cards with shadow, border-radius, and hover effects. KPI measure labels match big_value styling (uppercase, letter-spacing, 32px value). KPIs self-size height instead of stretching to match adjacent items.
• # span = N tag: Explicit 12-column grid span (1-12) on any dashboard item, overrides defaults. Triggers grid mode.
• # break tag: Starts a new row before the annotated field.
• # subtitle tag: Adds subtitle text below the item title.
• # borderless tag: Opt out of card styling on any item type.
• # dashboard { columns = N } tag: Force N equal columns instead of 12-col grid.
• # dashboard { gap = N } tag: Custom gap spacing in pixels.
• # label tag: Custom display label; default is snake_case → Title Case conversion.
• Responsive breakpoints: @container queries collapse grid to single column at ≤600px, halve to 6 columns at ≤900px. Flex mode wraps naturally.
• Tables fill width via shouldFillWidth: true, no double scrollbars (overflow-x clipped only on fill-width tables, preserving scroll on wide tables with many columns).
• big_value integration: Flattened inner card when inside dashboard, hidden redundant header, centered layout.
• Tag validation: Semantic validation for span (1-12), columns (>0), gap (>=0). Dashboard tags resolved at setup time for headless validation support.
• KPI card fix: container-type: inline-size and cqi font scaling scoped to grid mode only. In flex mode, KPI cards size dynamically based on title/value content instead of collapsing due to the circular dependency between fit-content width and inline-size containment.
• Storybook fix: Pre-bundle heavy dependencies (@duckdb/duckdb-wasm, apache-arrow, etc.) via optimizeDeps.include to fix first-load failures from Vite runtime dep discovery.
• 20+ storybook stories covering all features plus legacy backwards-compat testing.

https://www.loom.com/share/581a55d7cc1c4cd487fec943555d2825

[mtoy-googly-moogly]

These three automated review comments I understand and agree with

1. Fix falsy numeric handling for dashboard tags
   ◦ In packages/malloy-render/src/component/dashboard/dashboard.tsx:
   ▪ Replace truthy checks with explicit undefined checks:
   ▪ if (gap) ... → if (gap !== undefined) ...
   ▪ if (columns || gap) ... → if (columns !== undefined || gap !== undefined) ...
   ▪ if (columns) ... → if (columns !== undefined) ...
   ◦ Why: # dashboard { gap = 0 } is currently ignored (no grid trigger, no gap override), despite validation allowing non-negative gap.

2. Remove new render-time label/tag reads introduced in dashboard, this breaks how validation works
   ◦ packages/malloy-render/src/component/field-label-utils.ts + dashboard.tsx currently read field.tag at render time (label, subtitle, borderless, span).
   ◦ Direction:
   ▪ Stop using getFieldLabel(...) in dashboard and use existing field.getLabel() (already part of the resolved-field contract in src/data_tree/fields/base.ts).
   ▪ Do not add new render-time tag parsing paths; resolve dashboard item metadata once during setup (same principle used elsewhere in renderer).
   ◦ Why: this is architectural drift and makes headless/virtualized behavior harder to reason about.

This one is outside my area of competence, I pass it on. It feels when reading this like an LLM made a change for you and it made an expedient but not thoughtful change ...

3. Reduce cross-component CSS coupling from big-value plugin
   ◦ packages/malloy-render/src/plugins/big-value/big-value.css now contains many .dashboard-item... selectors.
   ◦ Direction:
   ▪ Move dashboard-layout-specific overrides into dashboard-owned styling (or gate them tightly to dashboard scope) so big-value plugin styles don’t implicitly control dashboard container behavior.
   ◦ Why: this is scope leak and will create future regressions when dashboard/big-value evolve independently.

There are two more comments from the view session that I am going to think about before I pass them on, but I thought I would hand these back to you now.

[mtoy-googly-moogly]

My AI is pretty unhappy with the storybook deps loading fix. It feels they are expedient, poorly explained and possibly maintenance problem. Again this is not my area of expertise. But until both our AIs are happy that one is a problem.

[mtoy-googly-moogly]

The AI thinks there is missing "story" coverage:

Please fill in/confirm only the unresolved rows in this verification matrix:

• gap = 0 behavior (edge case): no explicit story/test currently identified.
• Responsive breakpoint behavior (<=600, 601–900 container widths): currently manual-only; no explicit verification artifact identified.
• New validator branches (span bounds, columns > 0, gap >= 0, and “span ignored in columns mode” warning): no dedicated tests currently identified.

[mtoy-googly-moogly]

When generating error messages, to make validation work better for an LLM responding to vlaidation, it would be great if the errors followed something like this pattern (i.e. this is not the rule, just a guideline)

Invalid <tag-path> on '<field>': expected <constraint>, got <value>. Fix: <example> (or <fallback>).

[mtoy-googly-moogly]

This pr seems to accidentally include #2746 -- you need to rebase it so it can be judged separately.

I think grid dashboards stress the validation framework in a way which makes them impossible to correctly validate and I am working on PR to extend validation which will help this.

Also the AI suggests: "Invalid layout values should not still drive layout. Right now # span, # dashboard { columns=... }, and # dashboard { gap=... } are validated, but the raw values are still consumed by the dashboard layout code. Those should log and then fall back to default behavior, not feed broken CSS/layout.

[mtoy-googly-moogly]

Ok #2750 is merged to main now.

I think this PR should be updated to use that new validation ownership machinery for the dashboard child tags. In particular, # span, # subtitle, and # borderless look like dashboard-owned child tags in the same sense that # break is, and I think they should be validated and consumed through the new renderer validation ownership mechanism rather than being resolved globally up front. That would let this PR keep the nice short dashboard markup while fitting cleanly into the new validation architecture.

[mtoy-googly-moogly]

In collaboration with Claude -- I have read or written all of this ... a little more verbose than I would reply myself but I am letting Claude decide how much to write:

First off — this is looking great. The setup-time resolution, the defensive fallbacks, and the error-message wording are all exactly what I was hoping for, and the responsiveness to the earlier rounds shows. Thank you.

A couple of the things I flagged earlier I communicated badly, and you (reasonably) did extra work to satisfy contradictory asks. Let me clear those up. And there's one new thing that recent renderer work has me thinking about that I'd like to get ahead of in this PR.

1. Ownership vs. setup-time resolution — my fault, two asks that pulled opposite ways

Back in March I said "resolve dashboard item metadata at setup time, stop reading tags at render time." Then in April I said "consume span/subtitle/borderless through the #2750 ownership mechanism rather than resolving globally up front." Those two notes point in opposite directions, and you ended up doing both: resolving the child tags at setup time in resolveBuiltInTags and declaring them in childOwnedPaths. That's on me for not reconciling them.

The setup-time resolution is the one I actually want — it's what docs/validation.md calls the default. Given that, the childOwnedPaths entries are now redundant: the setup-time reads already mark those tags as read, so the unread-tag detector never fires on them. I confirmed this — emptying childOwnedPaths entirely leaves the "no warnings for # span / # subtitle / # borderless / # break" tests green.

So: keep the setup-time resolution, and drop the span/subtitle/borderless/break entries from renderer-validation-specs.ts (the dashboard spec can go back to empty). One mechanism, not two.

Smaller related thought, not a blocker: the resolved values currently live as four new fields on FieldBase (_resolvedSpan, _resolvedBorderless, …). Those are dashboard-only concepts sitting on the universal field base. If it's cheap, I'd lean toward stashing them in a per-child config object rather than growing the base class — but I don't want to over-rotate on this if the base-class route is genuinely simpler, so your call.

2. The big-value CSS coupling — also imprecise on my part

When I said "move the dashboard overrides into dashboard-owned styling," that got actioned as relocating the .dashboard-item… selectors out of big-value.css and into dashboard.css — which is good, but dashboard.css now reaches the other way into big-value's internals (.malloy-big-value-card, -value-row, -comparison, …). The leak moved sides rather than closing.

What I was actually after is reducing how much either component knows about the other's internal class names, not just which file the selectors live in. The clean shape is big-value exposing an "embedded/flattened" mode that dashboard opts into, instead of dashboard overriding big-value's guts. That's more than a CSS shuffle, so I don't want to block the PR on it — but let's name it as known debt so it doesn't quietly become a regression source when the two evolve apart.

3. New issue: grid/flex is an inferred mode you can't cleanly override

This is the one from recent experience. I was copying and re-theming dashboards by extending views, and hit a wall that this PR should get ahead of.

Right now the grid-vs-flex decision is inferred: grid if columns set, OR gap set, OR any item has span, OR any item has break. That makes the mode hard to override when you copy a dashboard:

flex → grid is fine — add # dashboard { columns = 3 } to the copy and you're in grid.
grid → flex only works if grid came from columns/gap (negate with # dashboard { -columns }). If grid was triggered by per-item span/break, you can't turn it off from an extension — those triggers live on inherited child fields, and a refinement can't reach back to negate them. I confirmed both: # -span in a refinement only affects fields you redeclare there, and negating columns while a child still has a span leaves you in grid.

I think the real fix isn't a new mode tag — it's that span and break shouldn't be mode triggers at all:

break is meaningful in flex. The row-grouping already runs in both modes (nonDimensionsGrouped splits on break regardless of grid/flex), so in flex a break just forces a new wrapping row. It doesn't need grid and shouldn't switch you into it.
span is meaningless outside grid. It's "N of 12 columns" — flex has no column track, and nothing in the flex CSS path reads it. So span should be a grid-scoped hint: ignored with a warning when there's no grid, not a silent mode switch.

So my proposal: narrow the grid signal to columns/gap only. Make span a grid-scoped sizing hint (warn if used without a grid). Let break work in both modes. The payoff is that the mode is then controlled entirely at the view level, which is cleanly negatable — so grid↔flex round-trips on a copy with a single annotation, and stray spans become harmless no-ops in flex instead of forcing a layout you can't escape.

(Happy to share the little probe I ran if it'd help — it walks the resolved tags for each override case.)

Minor / logistics

The new validator tests are good and cover the right branches. One gap: they assert that an error/warning fires, not what it says. Since I asked for the Invalid on '': expected … got … Fix: … shape, could you add one assertion that pins Fix: (or the "expected … got") so a regression back to a terse message gets caught? And a gap = 0 "no error" assertion would close the last row of that verification matrix.
The branch is a good way behind main and won't build on the current TypeScript toolchain (moduleResolution=node10 is now a hard error). It merges cleanly, so a main merge/rebase should sort it. Looks like #2746 is properly separated out now — thanks for that.

[mlennie]

@mtoy-googly-moogly round 2 is merged into feat/dashboard-ux (via jswir#2), so it's in this PR now. Walking your points:

Ownership vs. setup-time resolution

Kept the setup-time resolution and dropped the span/subtitle/break/borderless entries from the dashboard spec in renderer-validation-specs.ts, so childOwnedPaths is back to []. The "no warnings for # span / # subtitle / # borderless / # break" tests stay green. One mechanism now.

I also took the per-child config route you suggested: the four resolved values no longer live on FieldBase. resolveBuiltInTags builds a single DashboardChildConfig per child and stashes it via setDashboardChildConfig, and the dashboard reads it back with getDashboardChildConfig<DashboardChildConfig>(). FieldBase keeps only _resolvedLabel.

Big-value coupling

Closed it rather than just flagging it as debt. big-value now has an embedded/flattened mode (.malloy-big-value--embedded in big-value.css), and the dashboard opts in via customProps ({ big_value: { embedded: true } }) instead of overriding big-value's internals. dashboard.css no longer references .malloy-big-value-card / -value-row / -comparison; the only big-value mentions left are :has(.malloy-big-value) presence-conditions on the dashboard's own elements. Standalone big-value is unchanged (embedded defaults off).

Grid/flex mode

Narrowed the grid signal to columns/gap only: useGrid is now just columns !== undefined || gap !== undefined. span and break are no longer mode triggers. break works in both modes (the row grouping was already mode-agnostic). span is a grid-scoped hint that warns when there's no grid instead of silently switching into one. Net effect is the one you described: the mode is view-level and cleanly negatable, so a copied dashboard round-trips grid/flex with a single annotation and a stray span is a harmless warned no-op. Thanks for the probe offer; I worked through the override cases (negating columns with a child span still present, # -span in a refinement) and believe they're covered.

Validator tests

Pinned the message text: the span-range test asserts the expected ... got ... Fix: # span=6 shape, so a regression to a terse message fails. Added the gap=0 no-error case, plus span-without-grid-warns and span-with-grid-stays-clean.

Build / main

Resolved. feat/dashboard-ux is synced with main now, so the branch builds on the current toolchain and the round-2 work is rebased cleanly on top.

One thing I noticed and left alone: a span out of range under columns mode (e.g. # span=15 with columns=3) emits both the range error and the "ignored in columns mode" warning. It's pre-existing, both messages are true, and suppressing one turns it into a two-step fix, so I left it. Easy to tidy if you'd rather see only one.