Repository navigation
Description
Summary
#228 / PR #233 added the dashboard-pattern blocks (ListToolbar, StatusIndicator, UsageMeterRow, the docs pill, resource mode). Apps that follow the current Cloudflare dashboard on @cloudhal/ui still miss a few small patterns, and today rebuild them locally or do without. Each item below is independent and small; they are filed together as a checklist. (Resource mode is #254 and ListToolbar is #255.)
Evidence refers to cloudhal-dev/cloudhal main at b4bd79bae41845fcc75cc06490e61c3226f61171 (2026-11-15). Kumo is pinned at 2.14.0 in pnpm-workspace.yaml. Every visible or spoken word below is a prop, as elsewhere in the kit.
1. StatTile: a visible "No data" state for an empty series
Today (packages/ui/src/blocks/StatTile.tsx, last changed 2026-10-12):
Sparklinereturnsnullfor fewer than two points (line 107), so a tile whose source returned nothing loses its sparkline row, and its height no longer matches its neighbours.emptyLabelis read only by screen readers, next to the "—" value (line 197). Sighted users cannot tell "no data" from "not applicable".
Dashboard: on a Worker's Metrics and Overview tabs, a tile whose series is empty shows a flat baseline with a small "No data" chip centred on it, even when the value reads 0 (for example, Errors).
Proposal: an explicit noData flag plus noDataLabel. When set, the tile draws the flat baseline at the sparkline's height with a neutral chip. A sparkline with fewer than two points shows the same state. An all-zero series stays a real measurement and keeps its line.
2. StatTile: an optional link to the deeper view
Dashboard: the Overview's Metrics card leads to the Metrics tab; apps want each tile to lead to its chart.
Proposal: href (and a router-friendly render/linkComponent, matching how other blocks take links). The tile renders a dt/dd pair inside the group's dl and can contain the hint button, so wrapping it in an <a> would break both. A stretched link on the label (::after covering the tile) keeps the dl semantics and makes the label the link's accessible name; the hint button stays a separate control above the link's hit area.
3. StatTileGroup: one row that scrolls sideways
Today: StatTileGroup (lines 229-254) is a container-query grid of 2, then 3 or 4 columns; further tiles wrap onto new rows.
Dashboard: the Metrics tab's KPI strip is one row of eight or more equal tiles. When they do not fit, the row scrolls sideways inside its frame, with a "next" chevron at the edge. The page itself never scrolls sideways.
Proposal: layout="row": equal minimum tile width, overflow-x: auto with scroll snap; previous/next buttons that appear only while there is more to scroll, labelled by props; a keyboard-reachable scroll region named by the group's label. The default stays the current grid.
4. Truncated ids: the full value in a tooltip
Kumo's InlineCopyText (present since 2.14.0, re-exported by @cloudhal/ui) already renders mono, truncates by default, shows a copy icon, takes a localisable labels.copyAction, and announces "Copied" through a live region. What is missing for long ids (job, account, database ids) is a way to read the whole value: once truncated it can only be copied, not seen.
Proposal: a thin CopyId block on InlineCopyText that adds a Tooltip with the full value when the text is truncated, keeps Kumo's labels as props, and adds nothing else. Studio's id cells (DESIGN.md uses InlineCopyText for site, request, actor and skill ids) could adopt it. If maintainers prefer, this could go to Kumo as an InlineCopyText option instead.
5. UsageMeterRow: a form for a figure without a limit
Today (packages/ui/src/blocks/UsageMeterRow.tsx):
- Line 21:
limit: numberis required. - Lines 11-15:
usageState(used, limit)returns"danger"whenlimit <= 0 && used > 0, anddashboard-blocks.test.tsxline 95 checks this on purpose (usageState(1, 0)is"danger"), so0already means "a zero quota, exceeded". - Line 62:
maxfalls back to1, and lines 83-92 always render a KumoMeter.
So a figure with no quota (or no limit set yet) can only pass 0 (a full red bar and the "limit reached" badge) or a made-up limit (a meaningless bar). The usage rail this block copies (DESIGN.md §2aj, line 518) mixes metered rows with value-only rows: label, optional info toggletip and value (or an em dash), no bar, no badge. Consumers hand-build a second row next to the block for that, and the two drift apart (spacing, the toggletip's accessible name, tabular figures).
Proposal: limit: number | null, keeping 0 as today. limit: null renders the label, the optional info toggletip and valueText, with no Meter and no badge, and sets data-usage-state="none". warningLabel/dangerLabel become optional for null (a discriminated props type keeps them required for metered rows). usageState either accepts null and returns "none", or stays as is with the block checking null first; either way usageState(1, 0) stays "danger".
6. PageLayout docs pill: open cross-origin docs as an external link
Today:
packages/ui/src/blocks/PageLayout.tsxL76-79: the props are onlydocsHref?: stringanddocsLabel?: string. L135-146: the pill is<LinkButton href={docsHref} size="xs" variant="outline" icon={<BookOpen size={14} />} className="rounded-full">, with noexternal, so notarget/reland no outbound affordance.docs/design/DESIGN.mdL25 specifies "LinkButton size="xs", a 14 px book icon, same tab";dashboard-blocks.test.tsxL169-179 tests only a relativehref(/docs/workers).- Kumo's
LinkButtonalready hasexternal?: boolean("opens in a new tab withrel="noopener noreferrer"") in 2.14.0 and 2.18.1. - The kit's other outbound links follow a convention the pill does not:
PreviewPanel.tsxL333-342 (LinkButton externalwithArrowSquareOutand an accessible "open in new tab" label),NavigationPreview.tsxL32-33 and L76-79 (an aria-hiddenArrowUpRightplus a screen-reader-only "new tab" suffix),PlaygroundBar.tsxL56-64 (LinkButton … external).
An app's docs usually live on another origin, so clicking the pill leaves the app in the current tab and loses the person's place (filters, scroll, unsaved form state), with no visual or accessible sign that it leaves.
Proposal: docsExternal?: boolean, defaulting to true when docsHref is an absolute http(s) URL (and, where window exists, on another origin), false otherwise, so relative paths keep today's behaviour. When external, pass external to the LinkButton and add the kit's outbound marker (a trailing aria-hidden ArrowUpRight). An optional docsNewTabLabel?: string renders as sr-only text so screen-reader users hear that the link opens a new tab.
Acceptance criteria
- StatTile: accepts
noData/noDataLabelandhref, and renders exactly as today without them. The chip renders fornoDataand for a series of fewer than two points, not for an all-zero series. The tile link's accessible name is its label; tab order is tile link, then hint button. - StatTileGroup: accepts
layout="row", and the default grid is unchanged. The scroll buttons' names come from props, the buttons and the scroll region are keyboard-reachable, and a row with more tiles than fit does not widen the page at 390 px. - CopyId: exported from
@cloudhal/ui; the tooltip opens on hover and focus when the id is truncated; the copy button's name islabels.copyAction. - UsageMeterRow:
limit={null}renders norole="meter"and no badge, withdata-usage-state="none"; the label, toggletip (accessible namelabelthentext) andvalueTextlay out like a metered row. 80 % warning, danger at the limit, fractional limits andusageState(1, 0) === "danger"are unchanged. - Docs pill:
docsHref="https://docs.example.com/x"renderstarget="_blank",rel="noopener noreferrer"and a visible outbound icon;docsHref="/docs/x"renders as today;docsExternaloverrides the default either way; withdocsNewTabLabelthe accessible name includes the hint. - Tests in
packages/ui/test/(dashboard-blocks.test.tsxand the StatTile tests) cover each item, and DESIGN.md (L25, §2v, §2aj) describes the new props.
Found by: a downstream consumer (Clavius control plane), whose panel follows the Cloudflare dashboard on @cloudhal/ui. It currently uses InlineCopyText without a tooltip, wraps tiles instead of scrolling them, keeps a hand-built copy of the usage row for figures without a limit, and links its docs pill to a docs site on another origin.
Activity