[crisfiorini-oss]

Important

Maintainer update: rebuilt on #1043's renderer (2026-10-11)

Latest maintainer head: d7b490183 (review fixes, directly below). The first round starts at "What happened".

Everything between this note and the horizontal rule below was added by a maintainer. The author's original description follows the rule, unchanged; it describes the branch before this update, so read its renderer sections (WidgetChart, MetricFigure, the BarList restyle, the lone-series colour, formatShare) as history.

Review fixes (second maintainer round, on top of 31cfe26d7)

An independent deep review at 31cfe26d7 returned LAND, 0 blockers. It found #1043 intact (kit.test.ts identical, refusal deletion holding on the new + menu path too), the percent share scaled exactly once, and nothing of the author's work lost. It asked for the fixes below. Each fix has tests, and each mechanism was removed in turn to confirm a test fails without it.

Commit	Finding	What changed
fe679cc43	m1 (offset)	The audit RPC keys time buckets in UTC (postgres_audit.go), keyed …T00:00:00+00 in any session zone. A session-zone key's offset moves across daylight saving, so a day the SDK fills could not know its offset, and the kit, which labels in UTC, already read a +02 midnight as the previous day. A UTC session (the default) gets identical keys. TestTimeBucketKeysAreUTCInAnySessionZone runs against real Postgres under Europe/Paris across the 2026 change and fails with the old expression.
50322d093	M1, m2, m1	SDK fill. • M1: a complete, time-grouped count / distinct count / sum is fillable, and a derived metric reads its missing day as that input's 0. A rate whose numerator starts later, or never happens, now reads 0 and stays complete. Keys go in time order, the days between two inputs' ranges are combined, and a sum or difference of fillable inputs can feed a rate. • m2: the fill runs through the end of the range, the bucket holding to, or today for an open query. • m1: keys that disagree about their offset are left unfilled rather than given a guessed one.
442896fc0	m3, m6, m7	Headings: a widget inside a section is <h4>, under the section's <h3>; outside sections it stays <h3>. Card gained titleAs, StatTile labelAs="h4", DashboardWidget heading, and renderWidget a second argument { heading }. Stories DashboardSections and SectionHeader were added, plus a kit README note of what a remote sees in 0.12.7.
0afad20aa	m3, adopted tests	The host passes the heading on. The ⓘ's data range ignores filled zeros (otherwise "latest event" became today). Adopted the review's + menu refusal tests and stale-layout tests.
6c96c133f	m5	@codefly/saas-plugin-manifest 0.1.2, with the root pin and the lockfile.
41766e2a2	docs	AUDIT_METRICS.md and docs/plugin-manifest-schema.md.

One deliberate divergence from the review. Its test "gives a filled day the offset the server would have given it" expects the SDK to infer +02 for 30 March from returned keys carrying +01 and +02. The keys alone cannot settle that: 29 March is +01, 30 March is +02, and nothing in them says where the change falls. So the fix is at the owner: UTC keys, constant by construction. The SDK refuses to fill mixed offsets, and a test pins that refusal. Run unchanged against this tree, the review's own suite passes 65 of 67. The 2 failures are this test, which exists in two of its files.

A behaviour change worth knowing. "Telemetry incomplete." no longer appears for a difference or rate whose count input simply had no events; that now reads 0. It still appears when an input is partial or has no value over no events, such as an average. The host test was moved to that case. A series now ends on the current, in-progress bucket, so its value there is the value so far.

Release note (kit 0.12.7, for remotes):

• A widget's format, compact and currency included, now reaches chart axes, readouts, data tables and table cells; before, only scalars used it.
• Widgets inside a section are titled <h4>.
• renderWidget receives { heading }.
• Card has titleAs.
• SortableBoard is exported.

Still open, stated rather than fixed (m4, m7):

• Two-row tiles answer A solution's dashboard cannot express layout, and the grid renders it badly: giant scalar values, dead regions beside short widgets, and buggy reordering #1044's dead regions in only one order. row-span-2 without dense packing fills [chart, number, number]. It still leaves an empty cell under the number in [number, chart], and a chart-sized empty cell beside the chart in [number, number, chart]. Dense packing would break the viewer's order, so the remaining layout model (span, columns) is A solution's dashboard cannot express layout, and the grid renders it badly: giant scalar values, dead regions beside short widgets, and buggy reordering #1044 / fix(dashboard): additive layout controls, compact defaults and stable ordering #1045's. This is reasoned from CSS grid placement; happy-dom has no layout and it was not seen in a browser.
• fix(dashboard): additive layout controls, compact defaults and stable ordering #1045 conflicts with this PR. It makes a widget's section optional on a sectioned dashboard (this validator requires it), adds per-section columns, and says a preference "cannot change membership" (this PR lets a viewer move tiles between sections). Whichever lands second reconciles, after the owner rules on cross-section moves.
• Publish the kit's chart vocabulary as an A2UI catalog, so every consumer names the same graphs (#1050) #1051's catalog must also describe DashboardView.sections, DashboardWidgetView.section and WidgetHeading's use in renderWidget, beside Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043's failure, format in percentage points, unit, higherIsBetter and nullable series. Nothing in the repo enforces that today; a type-level exhaustiveness test in Publish the kit's chart vocabulary as an A2UI catalog, so every consumer names the same graphs (#1050) #1051 would.
• Two drag-and-drop primitives in the kit. SortableBoard (ordered swap grid in groups; the caller supplies the keyboard path, as the host does with arrow keys) sits beside feat(ui): Markdown says which bytes it rendered, and a generic Board whose moves the consumer owns #1014's Board (unordered columns with a Move menu). An arrow-key move within a section is not announced; that was already true in Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043.

Verification at the new head (Node 24.21.0; frontend steps from module/services/frontend/code):

• npm ci passed.
• tsc --noEmit exited 0.
• npm run lint reported 0 errors and 39 warnings, main's count.
• npm run test:pure passed 322 files, 4,467 tests.
• npm run build exited 0.
• The kit suite passed 1,443 tests, the SDK 106, and the manifest 141.
• The preview stylesheet --check passed.
• test:published-ui and check:plugin-allowlist passed.
• Repo gates passed: naming, boundaries, kit-version and its tests (16), release-gate tests (111), module-verify, interface-docs, and story-trace.
• In accounts, go test -race ./pkg/infra/auditmetricstest passed against postgres:17-alpine with AUDIT_METRICS_REQUIRE_DB=1, as CI runs it, and go test -tags pure ./pkg/infra passed.
• The review's .review-958 suite, run unchanged against this tree, passed 65 of 67; the 2 failures are the divergence above.

Not verified:

• Still no browser run.
• codefly ci run was not run, nor was the pipeline project.
• Accounts suites other than auditmetricstest and the pure pkg/infra tests were not run locally. Their sessions run in UTC, where the keys are unchanged.
• No deployed database's zone was checked.

What happened

#1043 merged as 0f696ba3f, by owner decision, instead of this PR's renderer. It rewrote the same files (the kit's dashboard.tsx, types.ts, metric-tiles.tsx, index.ts, charts.tsx, SolutionDashboard.tsx and its test, the package manifests). Its design is the base and stays: the kit's <Dashboard> draws the metric tier, SolutionDashboard composes it through slots, the checker-backed gate in src/components/__tests__/kit.test.ts refuses a second renderer, failure?: "failed" | "refused", refusals that delete retained snapshots at the read, availability apart from freshness, the accent on --chart-1, titled scalars as <h3>.

origin/main was merged into the branch (43f97c027); nothing was rebased or force-pushed, and the author's commits are untouched. Every conflict was resolved to main's side, and this PR's features were then rebuilt on #1043's renderer in five commits on top:

Commit	What
43f97c027	merge of main, conflicts resolved to #1043 (does not type-check alone; says so)
c779cc963	drop this branch's second renderer
98564bf44	kit: sections in the view model, DashboardSectionHeader, every mark written in the widget's format
7e2b3faae	SDK: the one percent conversion, sections carried
95766c125	host: the viewer's arrangement composed through the kit's slots
31cfe26d7	docs

Dropped, because #1043 already does it or contradicts it

• widget-chart.tsx (WidgetChart): a widget-to-mark dispatch, which is <Dashboard>'s job and what the gate refuses. Its ui-inventory.json entry goes too.
• MetricFigure, and the host's WidgetCard/WidgetBody/WidgetValues: the kit's StatTile/DashboardWidget draw these now.
• The lone-series colour (chartSeriesColor(i, count) → --chart-5, accent on --chart-5): contradicts Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043's accent, which is the first series' --chart-1.
• formatShare and the formatValue props on the deprecated basic charts, and the audit page's BarList restyle with its Bars removal: they served the old percent path and the "match the audit log" goal that Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043 reached by moving both pages onto the metric tier.

Kept as the author wrote it

The manifest schema, validator and conformance tests (Dashboard.sections, MetricWidget.section, unique ids, a widget's section must be declared, no section on a dashboard without sections, metric format); the per-day zero fill in runMetric and the derived-metric handling of filled zeros; dashboard-layout.ts version 2 and its tests; the kit's DropdownMenuItem hint; the SortableGroups and MenuHints stories.

SortableBoard is kept in the kit. It does not duplicate #1043's renderer: it is the kit's own SortableGrid generalised to several groups (SortableGrid is now a one-group board with unchanged props), and it is reached through #1043's layout slot. One overlap a reviewer may want to rule on: the kit's ./board Board (#1014) also moves cards between groups, but it is unordered columns keyed by a field with no swap and no group reordering, so neither can stand in for the other today.

Rebuilt on #1043's renderer

• Kit view model (types.ts): DashboardView.sections?: DashboardSectionView[] ({ id, title, description? }, drawn in the order listed) and DashboardWidgetView.section?: string; fromDashboardData carries both.
• Kit renderer (dashboard.tsx): the default layout heads each section with the new exported DashboardSectionHeader (an <h3> under the dashboard's <h2>), lays each section's widgets out exactly as Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043 does, draws a widget naming no section first and untitled, and keeps a declared section with no widgets ("No widgets in this section."). A view with sections never shows the "No widgets" empty state, and the layout slot is called with each tile's section. A view without sections renders as before (tested).
• Host (SolutionDashboard.tsx): the viewer's layout is resolved into the view the kit draws (the viewer's sections, order and titles; each widget in the section the viewer put it in). The host's controls go into the slots: layout is the kit's SortableBoard, each group headed by DashboardSectionHeader with the grip, the rename title, the section's + and its options menu; renderWidget is still Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043's SolutionWidget mounting DashboardWidget; actions is the dashboard's + when it declares no sections. Moving tiles across sections, renaming, reordering and removing sections, adding empty ones, per-section + menus offering only removed declared widgets, the muted "No data yet." / "Telemetry incomplete." hints, and the arrow-key announcements all work as the author described. The layout remains under the existing STOPGAP browser-storage label.
• The + menu's query is useWidgetSeries, the same hook and key as the tile's (and so the same refusal handling that deletes snapshots), enabled only while the menu is open.

The percent contract (decided here)

There is one conversion boundary, and both meanings are now explicit:

• A data graph's format: "percent" (manifest and SDK schema) means the metric's value is a share from 0 to 1, because that is what a ratio produces and the host cannot infer it.
• The kit's DashboardWidgetView.format: "percent" means the value is already in percentage points (unchanged from Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043; its test still pins 45 → "45%").
• runDashboard is the only place they meet. A widget whose metric is declared percent carries its points and total multiplied by 100 and format: "percent" (ResolvedWidget.format: WidgetValueFormat); byMetric keeps the shares. runDashboard is the only producer of ResolvedWidget, so the host and a remote using fromDashboardData both receive scaled values, and nothing after it scales again.
• Display goes through one function: the kit now writes a widget's format on a chart's axis, readout and data table and on a table's values through formatMetricValue, the function StatTile already uses. Before, only scalars honoured it.

The branch before this update put the share meaning on ResolvedWidget.format, which fromDashboardData forwards structurally, so a remote would have drawn 0.4 as "0.4%". This change fixes that. The scaling does not live in the kit because the kit's percent already means percentage points for every StatTile caller. It does not live in fromDashboardData because the host never calls it.

Regression tests: the SDK resolves a 2/5 ratio to 40 on the widget and 0.4 on byMetric. The kit writes "40%" in the line, area and bar data tables and in a table, and leaves a plain number alone. The host renders a declared percent ratio as "40%" on the tile, the bar chart's data table and a table widget through the real SDK path, a plain ratio as 2.5, and never "0.4" or "0.4%". Removing the SDK scaling reds the SDK test and the host test, and removing the kit formatter reds four kit tests and the host test.

Two-row tiles, and #1044 / #1045

The rule is a host-only itemClassName on the SortableBoard grid. A line, area, bar or table tile gets row-span-2 and every tile fills its cell, so two number tiles stack beside a chart; a stack layout is untouched. The kit's default layout geometry is unchanged, and this PR adds no span or columns to the manifest, so it does not touch #1044's layout model in code. Removing the class reds the host test.

Open PR #1045 (for #1044) proposes the same sections / section vocabulary plus Dashboard.columns, MetricWidget.span and per-section columns. It also states that a preference "cannot change membership" of a section, which contradicts this PR's viewer arrangement as specified. Whichever lands second has to reconcile that rule, its lenient-validator change against this strict validator, and the { id, title, description? } section shape, which both PRs already share.

Obligation for #1051 (the A2UI catalog)

This PR grows the kit's view model again. #1051's catalog.ts and data schema must describe:

• DashboardView.sections?: { id, title, description? }[] and DashboardWidgetView.section?: string (new here);
• the fields Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043 left: failure?: "failed" | "refused", format (the kit's MetricFormat, with percent in percentage points and now applied to every mark, not just scalars), unit, higherIsBetter, and series: WidgetSeries | null. Its schema tests must cover the nullability and the accepted failure values.

The SDK side also gained ResolvedWidget.section, DashboardData.sections and WidgetValueFormat.

Classification

• Percent conversion in runDashboard: a fix at the owner. The SDK is the only producer that knows the data graph's share meaning.
• Sections in the kit's view model, renderer and header: a feature at the owner. The kit draws; the host composes through Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043's slots.
• Browser-storage layout: the existing labelled STOPGAP, unchanged in scope (ADR 0007 user_settings field still missing).
• No hacks. The duplication gate is unchanged: no new ALLOWED or DISPATCHERS entries, and kit.test.ts is byte-identical to main.

Verification (Node 24.21.0, module/services/frontend/code, at 31cfe26d7)

• npm ci passed.
• npx tsc --noEmit exited 0.
• npm run lint reported 0 errors and 39 warnings, the same count as main and none in changed files.
• npm run test:pure passed 321 files, 4,444 tests. Among them, kit.test.ts passed 64 tests and the host's SolutionDashboard.test.tsx passed 67: Draw every dashboard with the kit's metric tier, and refuse re-implementing it (#1041) #1043's 36 plus the ported ones.
• npm run build (next build) exited 0.
• The codefly-ui package suite passed 1,441 tests, saas-sdk passed 95, and saas-plugin-manifest passed 141.
• npm run test:published-ui and npm run check:plugin-allowlist passed.
• Biome is clean on every file this update changed.
• The kit's preview stylesheet was regenerated after a no-change control: the generator run on main's sources reproduced main's committed bytes exactly. The new classes are those of SortableBoard, the menu hint and the section layout.
• Repo gates passed: node module/tools/naming-gate.mjs check, scripts/check-boundaries.sh, node scripts/ci/kit-version.mjs check, node --test scripts/ci/kit-version.test.mjs (16) and scripts/ci/release-gates.test.mjs (111), module/tools/module-verify.mjs, interface-docs-gate.mjs check, and story-trace-gate.mjs tests.
• Versions: no bump was needed. main already carries the unreleased @codefly-dev/ui / @codefly-dev/saas-ui 0.12.7 and @codefly-dev/saas-sdk 0.3.25, above what v0.0.94 published, and the kit-version gate passes. @codefly/saas-plugin-manifest stays at main's 0.1.1.

Host tests ported from the author's branch were adapted where they read the old card markup. Section headings are now found by the kit's dashboard-section-title slot. A tile's emptiness is read from the kit's "No data" / "Partial data" badges rather than the old card's sentences. The test that titled a number tile like the audit log was dropped, because #1043's StatTile owns that title.

Not verified

• No browser run. Nothing in this update was looked at in a browser. Dragging within and across sections, dragging a section, touch, focus return after a move, the two-row geometry and the SortableGroups story are covered only by happy-dom tests.
• codefly ci run, the canonical service gate, was not run. Neither was the pipeline vitest project, which needs live services.
• A percent line or area chart's axis ticks were not checked visually. The data tables are asserted; the axis gets the same formatter.

Docs updated

• module/AUDIT_METRICS.md: the zero fill and its limits, the percent boundary, and how sections are drawn.
• module/docs/plugin-manifest-schema.md: the percent boundary and the zero fill beside format. Sections were already described there.
• module/services/frontend/AGENTS.md: the viewer's arrangement through the slots, and why a widget's format is bound from the resolved answer.
• packages/codefly-ui/README.md: sections, DashboardSectionHeader, SortableBoard, and the format reaching every mark.

---

Summary

A solution can now group its dashboard's widgets into titled sections, declared in its manifest's data graph: Dashboard.sections ({ id, title, description? }[], drawn in declared order) and MetricWidget.section. Until now the validator refused the key (dashboard has unknown field 'sections'), so /api/solutions/register answered 422 invalid_manifest.

This fits ADR 0007. The solution declares the sections. A viewer only groups and arranges the tiles in their own view: they move tiles between sections, rename, reorder and remove sections, and add empty sections of their own that they fill by dragging tiles in. Each + menu (the dashboard's, and each section's) still offers only the declared widgets the viewer removed, and a section's + puts the widget back into that section. No preference adds a metric the dashboard has no widget for. Beside each removed widget, a + menu now says, muted, when its tile would have nothing to show ("No data yet.", or "Telemetry incomplete." for a derived metric missing an input), and it asks only once it is opened. The layout stays in browser storage under the existing STOPGAP label.

A metric may also name a format. percent reads its value as a share from 0 to 1 and writes it as a percentage, so a rate of 0.4 reads "40%" instead of "0.4". The host cannot infer this, because a ratio is not always a share ("versions per memo" is one). number, the default, writes the value as it is.

A per-day count now shows a 0 on each day with no events. Before, those days vanished and the line ran straight over them, so ten events on ten days of a 24-day span drew as a flat line at 1.

A chart, bar list or table tile is now two rows tall, so two number tiles stack beside it. Before, a number beside a chart left about 160px empty under it.

A solution dashboard now draws its tiles with the same charts as the audit log page. Before, a solution dashboard drew with the kit's first chart set: one colour, no readout when you hover, no legend. The audit log page draws with the metric charts. Both pages now draw with the same components.

A dashboard without sections, or a metric without a format, validates, renders and saves as before.

Changes

Manifest schema and validator (feat(manifest))

• saas-plugin-manifest/src/data-graph.ts gains DashboardSection, Dashboard.sections and MetricWidget.section. The validator checks each section's shape and that section ids are unique within a dashboard. A widget must name a declared section when its dashboard declares sections, and must name none when it declares none. An empty sections list is refused.
• plugin.codefly.schema.json carries the same field rules, including the cross-field rule (an if/then/else on sections). The conformance suite checks that the schema and the validator agree on acceptance and on five new rejections.
• saas-sdk/src/schema.ts mirrors the same shapes, and both packages export the section types.
• The host registry parse now has tests showing it carries a sectioned graph through and refuses a widget that names an undeclared section. That refusal is the 422 path.
• docs/plugin-manifest-schema.md documents the new keys and cross-field rules.
• Nothing else in the repo validates these keys. The Go accounts service reads only dashboard.events (for declared audit types), and the dashboard-authoring spec (features/dashboard/model/validate.ts) is a separate shape. No Python code reads the data graph.

Kit: SortableBoard (feat(ui))

• codefly-ui/src/dashboard/sortable-grid.tsx: SortableBoard holds tiles in groups under one drag context. You can swap tiles across groups. With onMove, a slot at the end of each group appears during a drag. With onMoveGroup, a group is dragged by a handle in its header. The groups sit in one column and only the pointer's height counts, so a drop above the first group lands before it and a drop below the last lands after it. A group can be fixed, and the board glides groups and tiles into place when they move.
• SortableGrid is now a board with one group; its props and behaviour are unchanged. It keeps main's renderOverlay and its item list keyed by content, and both now also apply to the board.
• New SortableGroups story, listed in ui-inventory.json.

Host dashboard (feat(frontend))

• src/solutions/dashboard-layout.ts, layout version 2: a list of sections, each with its tiles and, if the viewer renamed it, the viewer's title. It also stores the widgets and sections the layout was made against (seen, seenSections), so a section or widget the solution declares later still appears, while one the viewer removed stays removed.
  • A version-1 layout (the flat list main writes today) is read by putting each tile in its declared section.
  • Any id the dashboard does not declare is dropped. That includes a metric: tile saved before ADR 0007 applied.
  • A viewer's section id is custom: plus 16 hex characters. Titles are trimmed and capped at 60 characters, and a new section is titled "New section".
• src/solutions/SolutionDashboard.tsx:
  • Section headers show the title (click it to rename), the description, a grip for dragging or arrow keys, a + menu and an options menu (rename, remove).
  • An "Add section" button adds a section, and screen-reader announcements report section changes.
  • The single-widget graph each tile resolves drops section, because its throwaway dashboard declares no sections.
  • Each + menu item for a removed widget runs the tile's own query, through the same useWidgetSeries hook and query key, and only while the menu is open. It shows the tile's no-values rule (withoutValues, now shared by the tile and the menu) as a muted hint: "No data yet.", "Telemetry incomplete." (the tile says "Telemetry unavailable or incomplete.", or "Incomplete telemetry; total unavailable."), or "Total unavailable." for a number with no total across groups. It shows nothing while loading, on a query error, or when there is data, and the item stays selectable. The hint is a new optional hint prop on the kit's DropdownMenuItem. The kit knows nothing about metrics: the item keeps its label as its accessible name and uses the hint as its description. There is a new MenuHints story, listed in ui-inventory.json.
• docs/plugin-manifest-schema.md gains one paragraph on what viewers can do with sections.

Metric value format (feat(manifest))

• data-graph.ts and plugin.codefly.schema.json allow format (number or percent) on source and derived metrics and refuse any other value. The conformance suite checks that both accept it and both refuse an unsupported value on either kind. saas-sdk/src/schema.ts mirrors the type as MetricValueFormat.
• runDashboard puts each widget's metric format on the resolved widget, and the kit's fromDashboardData carries it to DashboardWidgetView.
• The kit's StatChart, BarList, LineChart and AreaChart take an optional formatValue for the tile's number, each bar's value and the y-axis ticks. The new formatShare writes a share as a percentage, to one decimal (0.4 → "40%", 17/22 → "77.3%"). The kit's shared <Dashboard> and the host's SolutionDashboard use it for a percent widget, tables included, and pass nothing for a plain number, so each chart keeps its own default. They now draw through WidgetChart (see Same charts as the audit log), which passes it on; the formatValue props on the old charts remain.
• docs/plugin-manifest-schema.md names the key.

Per-day zeros (fix(sdk))

• saas-sdk/src/datagraph/run.ts: runMetric fills a time-grouped count, distinct count or sum with a 0 at every bucket between the first and the last the RPC returned. The RPC returns no bucket for a day with no rows, and the kit's line chart spaces points by position, so with every bucket present its spacing is by date. Week and month buckets step by a week and a month.
• An avg, min, max or percentile has no value over no events, so its empty buckets stay out, as before. A bucket the RPC returned whose value was dropped as unknown stays out and keeps the series partial. A key that is not a date, or is off the bucket's step, leaves the points as they came. Totals do not change. Days before the first bucket and after the last are not filled.
• A derived metric over the zeros reads a day no input had events on as it did before them, not as missing telemetry (fix(sdk)). Before this, a ratio of two per-day counts read 0/0 on such a day and marked the whole series "Partial telemetry", and a count combined with an avg did the same. combineDerived now treats a key where every operand is a filled zero, or missing, as a day with no events: a ratio there has no value and the series stays complete, and a sum or difference of the zeros is 0. A day with events in the denominator and none in the numerator reads 0.

Arrow keys on a tile's grip (fix(frontend))

• A press that cannot move the tile (up on the first, down on the last) no longer saves the layout, so it does not pin the viewer to their own layout. A press that takes a tile into another section now tells a screen reader where it went ("Total logins moved to the start of Trends.").

Two-row tiles (feat(frontend))

• The kit's SortableBoard gains an optional itemClassName(id): classes for one tile's list item, which is its group's grid item. It knows nothing about charts.
• SolutionDashboard.tsx gives a line, area, bar or table tile row-span-2, and every card h-full. The grid works out the row heights from what the tiles hold, so no height is fixed. The grid does not pack later tiles into earlier holes, so the tiles keep the viewer's order, and a section with an odd cell count still ends on a half-empty row.

Same charts as the audit log (fix(frontend))

• codefly-ui/src/dashboard/widget-chart.tsx: WidgetChart draws one resolved widget with the metric charts. A line widget draws with MetricLineChart, an area widget with MetricAreaChart, a bar widget with BarList, a number widget with MetricFigure, and a table as a table. The kit's <Dashboard> and the host's SolutionDashboard both draw a tile's values with it; each still says for itself what a tile with no values shows.
• MetricFigure (metric-tiles.tsx) is StatTile's value, delta and sparkline without the card, for a tile that already has its own header. StatTile now draws its body with it.
• BarList (charts.tsx) takes the audit log's look: the label and the value above the bar, a thinner bar. The audit page's top lists (src/components/dashboard.tsx) use it instead of a copy in the host, and that copy (Bars) is removed.
• LineChart, AreaChart and StatChart stay exported, marked @deprecated, with a pointer to the chart that replaces each.
• percent: the figure's percent expects 45 for 45%, and a percent metric is a share from 0 to 1. WidgetChart scales the share once, so a ratio of 0.4 reads "40%".
• A number tile's title (SolutionDashboard.tsx) takes the size and weight the audit log's StatTile labels a figure with, the small body text, not a card heading, in the foreground colour rather than StatTile's muted grey, which read too faint beside the figure. Chart, bar and table tiles keep the card heading, as the audit log's chart cards do. A declared line still draws as a line and area as a filled area: the manifest makes that the solution's choice, so the host does not draw a line as an area to match the audit log's chart.
• ui-inventory.json gains an entry for widget-chart.tsx, and the entry for the kit's dashboard.tsx imports it in place of charts.js.

Review fixes (fix(sdk), fix(frontend), fix(ui))

• A per-day sum whose days with events all had an unknown value read a total of 0, because the filled zero on the day between them became the series' only point. toSeries (saas-sdk/src/datagraph/run.ts) now gives a series whose points are all filled zeros no total, as it had none before the fill.
• When a solution retired the last section a viewer had kept, parseLayout (src/solutions/dashboard-layout.ts) fell back to the declared default and brought back every widget the viewer had removed. It now gets the default's first section back, puts the viewer's tiles there, and keeps their removals.
• A dashboard's accent set only --primary, which the bar list colours from, while a line or area widget's metric chart colours its one series from a chart token. The kit's <Dashboard> now sets both from the accent (--primary and --chart-5, below).
• A chart of one series drew it in --chart-1, the lightest grey in the default skin's light-to-dark palette, so a solution's line was faint beside the audit log's chart, whose dark outline is its topmost series in the last colour. chartSeriesColor (metric-chart.tsx) now gives a lone series the palette's last colour; two series or more keep the palette order. This applies to every metric chart with one series, the audit log's included when it is filtered to one category.

Versions: @codefly-dev/ui and @codefly-dev/saas-ui go to 0.12.5 (they share a version) and @codefly-dev/saas-sdk to 0.3.17, one above main's, with the root pins and lockfile updated to match. @codefly/saas-plugin-manifest stays at 0.1.0: the kit-version gate does not cover it, and earlier changes to it were not bumped either.

Testing

All runs used Node 24.17.0, from module/services/frontend/code unless another directory is named. The branch is rebased onto main at 7fecf40; the rebase had no conflicts.

• npx vitest run --project pure: 294 files, 3742 tests passed. Two new host tests check that an arrow key that moves nothing leaves storage empty, and that an arrow-key move into another section is announced; both failed before the grip fix.
• packages/codefly-ui: npx vitest run src/dashboard: 9 files, 104 tests passed. One checks that itemClassName lands on the tile's list item; the host checks that a line and a bar tile span two rows and a number does not. The board tests cover:
  • swapping tiles across groups, and dropping on a group's slot;
  • dropping a group above the first group, below the last, and off to the side;
  • fixed groups;
  • renderOverlay and its default.
• packages/saas-plugin-manifest: npx vitest run: 141 tests passed. Cases added:
  • the validator accepts sections, including an empty one;
  • it refuses a section on a dashboard with none, a missing section, an unknown section, a duplicate id, a bad id, an empty title, an unknown field and an empty list;
  • the schema and the validator agree on each case;
  • both accept format on a source and a derived metric, and both refuse an unsupported format on either.
• packages/saas-sdk: npx vitest run: 92 tests passed. They include one that checks runDashboard carries each widget's metric format, and none for a metric without one. Ten check the per-day zeros:
  • a count gets a 0 on each missing day, with its total unchanged;
  • a distinct count and a sum are filled too;
  • an avg, min, max and percentile are not;
  • a day the RPC returned with an unknown value gets no 0 and the series stays partial;
  • week and month buckets step by a week and a month;
  • a key off the step, or an impossible date, leaves the points as they came.
    With the fill switched off, the five tests that expect zeros fail and the rest pass.
    One more test checks that a per-day ratio and a difference over a day no input had events on stay complete, and that a day with events only in the denominator reads 0. It failed before the derived-metric fix ("partial"); main gives "complete" for the same graph.
• The format tests check that:
  • formatShare writes 0.4 as "40%", 17/22 as "77.3%", 0 as "0%" and 1 as "100%";
  • StatChart and BarList write values with the caller's formatter, and LineChart hands it to its y axis;
  • fromDashboardData carries the format, and the kit's <Dashboard> writes a percent number and percent bars as percentages and a plain number as a number;
  • the host draws a percent ratio as "40%" and a plain ratio as 2.5, and never as "0.4";
  • the registry parse carries a metric's format through and refuses an unsupported one (the 422 path).
• The layout and dashboard tests cover:
  • version-2 layouts written and read back, and migration from version 1 (main's current stored shape), including one that holds metric: tiles;
  • adding, renaming, removing and reordering sections;
  • dragging and arrow-key moves across sections;
  • dropping a section above the first or below the last;
  • each section's + offering only removed widgets and putting them back in that section;
  • a viewer's section adding nothing.
• The + menu tests (SolutionDashboard.test.tsx, "what a + menu says about a removed widget", 6 tests) check that:
  • a removed widget whose metric returns no rows is described "No data yet.", and adding it back draws its tile at once from the answer the menu got;
  • a removed derived widget missing an input is described "Telemetry incomplete.", and its tile says "Telemetry unavailable or incomplete.";
  • a removed widget with data has no hint;
  • there is no hint and no spinner while the answer is loading, and the hint appears once the answer arrives;
  • there is no hint when the query fails;
  • nothing is asked about a removed widget until a menu opens.
    I broke the feature on purpose and ran the tests, then restored it:
  • with the feature removed, all 6 fail;
  • reading "loading or failed" as no data fails the loading and error tests;
  • labelling a widget that has data fails the with-data test;
  • giving a derived metric's gap the no-data words fails the derived test;
  • querying removed widgets on page load fails the before-open test;
  • giving the menu its own query key fails the two tests that add a tile back.
• packages/codefly-ui: one new test in src/layout/__tests__/compound-controls.test.tsx checks that a hinted item keeps its label as its name and gets the hint as its description. It fails if the hint is not hidden from the name, or if the description link is removed. The same file had 7 tests pass.
• For the format commit, npx eslint over its changed files: 0 errors. For the earlier commits, npm run lint: 0 errors. The 30 warnings are all patterns already on main (anonymous story default exports, react-hooks/incompatible-library on tables); none is in new code.
• npm run typecheck: passed. After the format commit, npx tsc --noEmit with the packages rebuilt: passed.
• npx biome check over the files the format commit changes: its new lines are clean. Every file with findings has the same count on the commit before it: the files named below, plus codefly-ui/src/dashboard/charts.tsx, dashboard.tsx, format.ts and __tests__/charts.test.tsx and __tests__/types.test.ts, which carry long lines and import order from main. For the earlier commits, over their changed files: 17 of 24 files are clean. The other seven (codefly-ui/src/dashboard/index.ts, saas-sdk/src/index.ts, plugin.codefly.schema.json, ui-inventory.json, src/solutions/__tests__/registry.test.ts, codefly-ui/src/layout/__tests__/compound-controls.test.tsx, codefly-ui/stories/primitives.stories.tsx) fail the same way on origin/main: whole-file import ordering or formatting, and in the last two, lint findings on lines this PR does not touch. The new lines follow each file's existing style.
• For the chart commit, from module/services/frontend/code under Node 24:
  • npx vitest run --project pure: 294 files, 3747 tests passed. The host test that read a tile's title now reads the tile's own title, because a chart also names its hidden data table after it.
  • npm run typecheck: passed. npm run test:published-ui: passed.
  • npx eslint over the changed files: clean.
  • npx biome check: no new findings beyond those already on the unchanged files. One noArrayIndexKey finding moved with the bar list from the host into the kit.
  • The naming gate and the kit-version gate passed.
• npm run check:plugin-allowlist: passed. npm run prepare:frontend leaves the tree clean.
• npm run test:published-ui: passed ("Packed UI declarations and generic consumer rendering passed").
• node --test scripts/ci/kit-version.test.mjs passed (16 tests), and node scripts/ci/kit-version.mjs check passed, reporting @codefly-dev/ui@0.11.5, @codefly-dev/saas-ui@0.11.5, @codefly-dev/saas-sdk@0.3.16.
• scripts/check-boundaries.sh: clean. node module/tools/naming-gate.mjs check: clean. The message mode passed on each commit message and on this body.
• No Go or Python validator of these keys exists, so no Go or Python tests were affected.
• On a local stack running this branch as the host, with a solution whose graph declares sections:
  • every tile's number matched a SQL count over the same audit rows;
  • after the format commit, with six rates declared percent, the solution registered and the rates read 40%, 77.3%, 71.4%, 77.3%, 81.1% and 81.8%, while "versions per memo" read 2.227;
  • after the per-day fix, a per-day count with ten events on ten days of a 24-day span drops to 0 on the empty days, instead of drawing a flat line at 1;
  • after the two-row change, at 1440px wide, no tile is shorter than the space it sits in, and the only empty cells are the last cell of a section with an odd cell count. Before it, every number tile beside a chart or bar list had a gap under it.
• Before the format commit, in the in-app browser (Chromium), with a mouse:
  • removing a tile and opening its section's + showed the tile with "No data yet." beside it when its metric had no rows, and with nothing beside it when it had data;
  • adding it back drew it with its data;
  • dragging one tile onto another in the same section swapped them;
  • the arrow keys on a grip moved a tile one place;
  • removing a section moved its tiles into the next one;
  • the arrangement survived a reload;
  • at phone width (375 px), the page did not scroll sideways.
• After the chart commit, on a local stack, a reference solution's dashboard (a line, a bar list and a number) and the audit log page draw with the same charts, and dragging tiles still works.
• After merging main (its own commit, plus one that regenerates the kit's committed preview stylesheet for the classes the dashboard components use), under Node 24:
  • npx vitest run --project pure: 310 files, 4072 tests passed. Before the stylesheet commit, the preview-stylesheet test failed twice (stale, and a missing opacity-70); it passes on main alone.
  • npm run typecheck, npm run test:published-ui, npm run check:plugin-allowlist, the kit-version gate, the naming gate and scripts/check-boundaries.sh passed.
  • eslint: no errors on the changed files. biome: the same findings as main's copies of those files, none new.
  • Versions: @codefly-dev/ui and @codefly-dev/saas-ui 0.12.5, @codefly-dev/saas-sdk 0.3.17, each one above main's; the lockfile is main's, regenerated.
• After merging main again (its shared navigation and lifecycle primitives; the only extra conflict was ui-inventory.json, where both entries are kept), under Node 24: npx vitest run --project pure: 312 files, 4146 tests passed; typecheck, published-ui, plugin allowlist, kit-version gate, naming gate and scripts/check-boundaries.sh passed; eslint and biome report nothing new.
• For the lone-series colour: a chart test checks a lone series strokes in var(--chart-5) and two series keep --chart-1 and --chart-2; it fails without the change. npx vitest run --project pure: 312 files, 4148 tests passed; typecheck and npm run test:published-ui passed; eslint is clean and biome reports nothing new. Checked on the local stack beside the audit log.
• For the number tile titles: a host test checks that a number tile's title carries the metric label style, not muted, and a chart tile's does not. npx vitest run --project pure: 310 files, 4076 tests passed; npm run typecheck and the naming gate passed; eslint and biome are clean on the two changed files. Checked on the local stack at desktop width beside the audit log.
• For the review fixes, under Node 24: each fix has a test that fails without it (a total of 0 where none was observed; the default layout, with the removed widget, where one section was expected; no --chart-1 on the accented dashboard) and passes with it. npx vitest run --project pure: 310 files, 4075 tests passed. npm run typecheck, npm run test:published-ui, the kit-version gate and the naming gate passed; eslint is clean on the changed files and biome reports nothing new on them.

Not verified

• A review suspects the board's slot changes height when a drag starts, making the tiles jump; happy-dom cannot show it, so it needs a check in a real browser.
• In a real browser I dragged only within one section, with a mouse. Dragging across sections, dragging a section, touch activation and the SortableGroups story in the explorer are unexercised outside happy-dom.
• I did not check keyboard focus return after a move against a real browser. happy-dom keeps focus on a node React moves, where a browser drops it.
• The 422 path for a malformed sectioned or formatted graph is covered only at the registry-parse level. The accepted path ran end to end on the local stack.
• I did not check visual baselines under external skins, and did not look at a percent line or area chart's y axis in a browser; it is covered only by the test that the formatter reaches the axis.
• I saw the hint in the in-app browser but did not check its colour when an item is focused. The app's query client keeps an answer fresh for 30 seconds, so a tile added back within that window draws without asking again. The tests use no fresh window: there, the tile draws at once from the cache and then refetches.
• I did not run the pipeline test project; it needs live services.

Known behaviour

• A viewer's saved layout wins over later declaration changes, on purpose. A widget the solution moves to another section stays where the viewer's saved layout has it. If the solution drops every section the viewer kept, the layout gets the declared default's first section back with the viewer's tiles in it, and the widgets the viewer removed stay removed.

Open questions

• A dashboard with declared sections has no + in its own header, only one per section, as in the original design. Should the header also get a + that puts a removed widget back into its declared section?
• The layout is still the labelled browser-storage stopgap. When the ADR 0007 user_settings field lands, the version-2 shape moves there as it is. There is no tracking issue for that field yet.

🤖 Generated with Claude Code

[antoinetoussaint-byte]

lazybox has finished working on this. claude (Opus 5.5) held it from 2026-10-12 00:54 UTC until 2026-10-14 15:03 UTC. The working label has been removed; this comment is the record.

claim detail

Lazybox-Claim-Device: effacd542b611010656e
Lazybox-Claim-Session: 015d4a49b1
Lazybox-Claim-Workspace: github-codefly-dev-module-saas-starter-958
Lazybox-Claim-Agent: claude
Lazybox-Claim-Model: Opus 5.5
Lazybox-Claim-Started: 2026-10-12T00:54:14Z
Lazybox-Claim-Heartbeat: 2026-10-14T15:03:35Z
Lazybox-Claim-Expires: 2026-10-12T08:07:15Z
Lazybox-Claim-Released: 2026-10-14T15:03:35Z