Skip to content

@cloudhal/ui: dashboard-block follow-ups to #228 (StatTile empty state and link, scrolling StatTileGroup, CopyId tooltip, UsageMeterRow without a limit, external docs pill) #256

Open

Description

@Madraka

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):

  • Sparkline returns null for 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.
  • emptyLabel is 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: number is required.
  • Lines 11-15: usageState(used, limit) returns "danger" when limit <= 0 && used > 0, and dashboard-blocks.test.tsx line 95 checks this on purpose (usageState(1, 0) is "danger"), so 0 already means "a zero quota, exceeded".
  • Line 62: max falls back to 1, and lines 83-92 always render a Kumo Meter.

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.tsx L76-79: the props are only docsHref?: string and docsLabel?: string. L135-146: the pill is <LinkButton href={docsHref} size="xs" variant="outline" icon={<BookOpen size={14} />} className="rounded-full">, with no external, so no target/rel and no outbound affordance.
  • docs/design/DESIGN.md L25 specifies "LinkButton size="xs", a 14 px book icon, same tab"; dashboard-blocks.test.tsx L169-179 tests only a relative href (/docs/workers).
  • Kumo's LinkButton already has external?: boolean ("opens in a new tab with rel="noopener noreferrer"") in 2.14.0 and 2.18.1.
  • The kit's other outbound links follow a convention the pill does not: PreviewPanel.tsx L333-342 (LinkButton external with ArrowSquareOut and an accessible "open in new tab" label), NavigationPreview.tsx L32-33 and L76-79 (an aria-hidden ArrowUpRight plus a screen-reader-only "new tab" suffix), PlaygroundBar.tsx L56-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/noDataLabel and href, and renders exactly as today without them. The chip renders for noData and 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 is labels.copyAction.
  • UsageMeterRow: limit={null} renders no role="meter" and no badge, with data-usage-state="none"; the label, toggletip (accessible name label then text) and valueText lay out like a metered row. 80 % warning, danger at the limit, fractional limits and usageState(1, 0) === "danger" are unchanged.
  • Docs pill: docsHref="https://docs.example.com/x" renders target="_blank", rel="noopener noreferrer" and a visible outbound icon; docsHref="/docs/x" renders as today; docsExternal overrides the default either way; with docsNewTabLabel the accessible name includes the hint.
  • Tests in packages/ui/test/ (dashboard-blocks.test.tsx and 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    accessibilityBarrier affecting people with disabilitiesenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions