Repository navigation
Description
Summary
PageLayout resource={…} (the ResourceHeader block from #228 / PR #233) is the kit's version of a Cloudflare dashboard resource page: crumbs and an optional switcher in the top bar, a tab bar, and the page actions on the tab row. Building resource pages on it surfaced four gaps. They all touch packages/ui/src/blocks/ResourceHeader.tsx, PageLayout.tsx, the PageLayout resource mode suite in packages/ui/test/dashboard-blocks.test.tsx and docs/design/DESIGN.md §2aj, and they share one focus order (crumbs → switcher → tabs → actions → content), so they are filed together. Each part can land on its own.
Part 1 is a bug (nothing visible names the resource on a phone); parts 2-4 are enhancements.
Checked against cloudhal-dev/cloudhal main at b4bd79bae41845fcc75cc06490e61c3226f61171 (2026-11-15). ResourceHeader.tsx was last changed in b48f67b (2026-11-14) and nothing on main since then changes the behaviour below. No app in the monorepo uses resource mode yet, so today these show up first in consumers; Studio's shell is the documented reference, though.
1. On phones, the resource's name and the switcher disappear (bug)
Evidence
ResourceHeader.tsx:44: in resource mode the title is only<h1 className="sr-only">; no visible title is rendered (by design, DESIGN.md §2aj).PageLayout.tsx:123-133:crumbsandresource.switcherare combined and portaled intoPageCrumbsSlot. With a frame present they are not rendered anywhere else (line 156 renders them inline only without a frame).apps/studio/src/components/AppFrame.tsx:147:<PageCrumbsSlot className="hidden flex-1 sm:flex" />, so belowsm(640 px) the slot isdisplay: none. DESIGN.md §1 tells apps to build their shell this way, and downstream apps copy that line.- DESIGN.md §2aj (lines 501-508) describes the 390 px layout of the resource header but not where the name or the switcher appear at that width.
- Kumo
Breadcrumbsalready has a phone layout: belowsmit renders a collapsed trail (<div className="contents sm:hidden">: an ellipsis, then the parent and the current crumb). Seepackages/kumo/src/components/breadcrumbs/breadcrumbs.tsx(cloudflare/kumomain@eaa9e173), present since 2.14.0. The shell'shidden sm:flexthrows that away.
On normal pages the visible PageHeader title still names the page when the crumbs are hidden, so only resource mode is affected.
Why it matters: a phone visitor cannot tell which resource they are on (which Worker, which installation); the dashboard keeps the current crumb visible at narrow widths. resource.switcher cannot be reached at all below 640 px, by pointer or keyboard, so the documented focus order does not hold.
Proposal (the first is smaller):
- (a) Keep the crumbs slot visible at every width, since Kumo
Breadcrumbscollapses itself belowsm: change the reference shell to something likeflex min-w-0 flex-1and make the slot truncate so the right-hand top-bar actions keep their room. Update DESIGN.md §1. - (b) Or have
ResourceHeaderrender a compact visible line below@3xl/pagewith the resource name andresource.switcher, above the tabs, keeping exactly oneh1(the visible line becomes theh1at narrow widths, or thesr-onlyh1stays and the line isaria-hidden).
Acceptance criteria
- At 390 px, inside the reference shell, a resource page shows the resource's name, and
resource.switcheris visible and keyboard-reachable. - The page still has exactly one
h1. - The resource-mode test suite has a narrow-width case, and DESIGN.md §1 and §2aj describe the phone behaviour.
2. A ready-made top-bar switcher for resource.switcher
Evidence
ResourceHeader.tsxL10-11:switcher?: ReactNode, documented as "An environment switcher shown after the breadcrumbs in the top bar (production, preview)".PageLayout.tsxL122-131 places it in aflex items-center gap-2row after the crumbs; the component itself is left to the caller.- The kit's only switcher,
SidebarSwitcher, does not fit there: its trigger is a full-width row (w-full … px-3 py-2, L41) keyed togroup-data-[state=collapsed]/sidebar, its caret hides when the sidebar collapses (L49), and its menu isw-(--anchor-width)(L53), so a short trigger gives a menu too narrow for the item names. - DESIGN.md L505 describes the slot only as "a small
SelectorDropdownMenusuch as Production / Preview";dashboard-blocks.test.tsxL208 fills it with a plain<Button size="sm">Production</Button>. - The dashboard's Worker page draws this control as part of the breadcrumb trail (observed November 2026):
Workers & Pages › my-worker › (globe) Production ⇅, the current item's icon and name with an up/down caret, opening a menu of the alternatives. - Kumo (
main@eaa9e173, npm 2.18.1) hasBreadcrumbs.Link/Current/Separator/Clipboardbut no breadcrumb dropdown; its account switchers exist only in sidebar demos. So this belongs in@cloudhal/ui, next toSidebarSwitcher.
Why it matters: without a block, every consumer decides the trigger's shape, size, icon, caret, menu width, current-item mark, accessible name and tooltip on its own, decisions the kit already made once for SidebarSwitcher. A downstream consumer had to hand-build this control.
Proposal: export a top-bar switcher (name open, for example TopBarSwitcher or ResourceSwitcher) taking the existing SidebarSwitcherProps (current, items, onSelect, extra, ariaLabel), so one data hook can feed either switcher.
- Trigger drawn like the dashboard's breadcrumb switcher: optional
icon,name,CaretUpDown, crumb-sized text and padding; not full width, independent of the sidebar's state; accessible name fromariaLabel. - Menu:
DropdownMenu.Contentaligned to the start and sized to its content (a minimum width, not--anchor-width); each item with icon and name, the current oneselectedand ticked, thenextra. - Open question: should the label be optional (icon-only ⇅ with a tooltip) when the crumb before it already shows the current name? The dashboard always shows it.
Acceptance criteria
- The switcher and its props are exported from
src/index.ts. - In resource mode it sits on the crumbs' baseline without stretching the top bar, and its menu fits the item names whatever the trigger's width.
- The current item is marked (
selectedplus a check),extrafollows the items, and the trigger has an accessible name. It is reachable after the crumbs in the focus-order test; Enter or Space opens it and arrow keys move through it. - The
ResourceMode.switcherJSDoc and DESIGN.md §2aj name the block, and the kit's test uses it in place of the plainButton.
3. A segmented tab style, with translatable scroll labels
Evidence
ResourceHeader.tsxL49-56 hard-codes<Tabs variant="underline" … listClassName="border-b-0" />; L41 and L46 draw the hairline the underline indicator sits on.ResourceMode(L4-12) has no style option and no way to pass Kumo'slabels.- The dashboard draws a resource page's tab bar (Workers & Pages → a Worker: Overview, Metrics, Deployments, …, Settings; observed November 2026) as a segmented track: a recessed track where the selected tab is a raised pill, left-aligned, the page actions on the right of the same row, and no underline rule. Kumo ships this as
Tabs variant="segmented", its default. - In
@cloudflare/kumo2.14.0 and 2.18.1 (dist Tabs chunk and types), only the segmented variant renders overflow controls (TabsOverflowControl). Their accessible names come fromlabels.scrollStart/labels.scrollEnd, default to the English "Scroll tabs left" / "Scroll tabs right", and can only be changed through thelabelsprop. When visible they aretabIndex: 0. - DESIGN.md §2aj says "Underline tabs have no scroll buttons", which is correct today and is why a segmented option needs more than a variant switch.
Why it matters: resource pages on the kit look different from the dashboard they are meant to match, and the only way to get the segmented track is a hand-built lookalike. Adopting the segmented variant naively would leave the narrow-screen scroll buttons in English in every locale.
Proposal
ResourceMode.variant?: "underline" | "segmented"(or switch the default to"segmented"and keep"underline"as an option).ResourceMode.labels?: TabsLabels, passed straight to Kumo'sTabs labels.- In segmented mode, drop the header hairline; actions stay right-aligned on the same row when wide, below the tabs when narrow.
Acceptance criteria
-
variant: "segmented"renders Kumo's segmentedTabswith the actions on the same row when wide and below when narrow; no horizontal page scroll at 390 px. -
labelsreaches Kumo'sTabs, and a test asserts the overflow buttons use the provided names. - Both variants pass the existing tab tests (one tab stop, arrow keys, manual activation, L243ff) and the focus-order test (L231ff), which documents where visible overflow buttons fall.
- The underline variant behaves exactly as today (L280ff: one rule, never wraps).
4. A place for a note under the header actions
Evidence
ResourceHeader.tsx:59: the actions container isflex min-w-0 shrink-0 flex-wrap items-center gap-2 @3xl/page:flex-nowrap @3xl/page:pb-2. From@3xl/page(48 rem) up it does not wrap, so abasis-fullchild (for example a short note explaining why some actions are disabled) is squeezed into the button row.ResourceHeader.tsx:34-38explains why the row must never wrap: a wrapped row would put the hairline under the actions, and the tabs and their active indicator would lose their rule. That reason still holds.- Outside resource mode this works: the kit's copy of Kumo
PageHeader(packages/ui/src/blocks/kumo/page-header/page-header.tsx:109) wraps its actions (flex max-w-full min-w-0 shrink-0 flex-wrap items-center gap-2), so the same note drops onto its own line. - Neither
ResourceModenorPageLayoutPropshas a slot for text that belongs to the actions but sits outside the button row.
Why it matters: admin pages often gate actions on state or role (for example "Deploy" disabled while a job runs). A disabled button alone does not say why, and its title tooltip shows only on mouse hover: not on touch, and not by keyboard, since a disabled button takes no focus. The accessible pattern is the reason as secondary text next to the controls. On a resource page at desktop width there is no clean place for it today; consumers squeeze it into the row, move it into the body away from the controls, or override the header's classes.
Proposal: an optional ResourceMode.actionsNote?: ReactNode (or a PageLayout prop), rendered right-aligned and tied to the actions: on wide pages on its own line under the header row (between the rule and the content, so the rule still runs directly under the tabs); on narrow pages directly after the actions line. It comes after the actions in the DOM. Letting the actions container wrap while keeping the rule under the tab line is a fallback, but given lines 34-38 it looks harder to get right.
Acceptance criteria
- At ≥ 48 rem, an
actionsNoterenders right-aligned on its own line under the actions, and the hairline with the active-tab indicator stays directly under the tabs. - Below 48 rem, the note follows the actions line and the tab line keeps its full-width rule.
- Nothing (and no extra gap) is rendered when
actionsNoteis absent ornull. - DOM order is tabs → actions → note; the note is plain secondary text and not focusable.
Shared acceptance criteria
- At every width the focus order is crumbs → switcher → tab bar (one stop, plus any visible overflow buttons) → actions → content, and the note is not a stop.
- DESIGN.md §1 and §2aj describe all of the above.
Found by: a downstream consumer (Clavius control plane) that builds its resource detail pages on PageLayout resource with the reference shell pattern.
Activity