Skip to content

@cloudhal/ui: PageLayout resource mode follow-ups to #228 (phone name and switcher, top-bar switcher block, segmented tabs, note under the actions) #254

Open

Description

@Madraka

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: crumbs and resource.switcher are combined and portaled into PageCrumbsSlot. 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 below sm (640 px) the slot is display: 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 Breadcrumbs already has a phone layout: below sm it renders a collapsed trail (<div className="contents sm:hidden">: an ellipsis, then the parent and the current crumb). See packages/kumo/src/components/breadcrumbs/breadcrumbs.tsx (cloudflare/kumo main @ eaa9e173), present since 2.14.0. The shell's hidden sm:flex throws 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 Breadcrumbs collapses itself below sm: change the reference shell to something like flex min-w-0 flex-1 and make the slot truncate so the right-hand top-bar actions keep their room. Update DESIGN.md §1.
  • (b) Or have ResourceHeader render a compact visible line below @3xl/page with the resource name and resource.switcher, above the tabs, keeping exactly one h1 (the visible line becomes the h1 at narrow widths, or the sr-only h1 stays and the line is aria-hidden).

Acceptance criteria

  • At 390 px, inside the reference shell, a resource page shows the resource's name, and resource.switcher is 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.tsx L10-11: switcher?: ReactNode, documented as "An environment switcher shown after the breadcrumbs in the top bar (production, preview)". PageLayout.tsx L122-131 places it in a flex items-center gap-2 row 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 to group-data-[state=collapsed]/sidebar, its caret hides when the sidebar collapses (L49), and its menu is w-(--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 Select or DropdownMenu such as Production / Preview"; dashboard-blocks.test.tsx L208 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) has Breadcrumbs.Link/Current/Separator/Clipboard but no breadcrumb dropdown; its account switchers exist only in sidebar demos. So this belongs in @cloudhal/ui, next to SidebarSwitcher.

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 from ariaLabel.
  • Menu: DropdownMenu.Content aligned to the start and sized to its content (a minimum width, not --anchor-width); each item with icon and name, the current one selected and ticked, then extra.
  • 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 (selected plus a check), extra follows 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.switcher JSDoc and DESIGN.md §2aj name the block, and the kit's test uses it in place of the plain Button.

3. A segmented tab style, with translatable scroll labels

Evidence

  • ResourceHeader.tsx L49-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's labels.
  • 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/kumo 2.14.0 and 2.18.1 (dist Tabs chunk and types), only the segmented variant renders overflow controls (TabsOverflowControl). Their accessible names come from labels.scrollStart / labels.scrollEnd, default to the English "Scroll tabs left" / "Scroll tabs right", and can only be changed through the labels prop. When visible they are tabIndex: 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's Tabs 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 segmented Tabs with the actions on the same row when wide and below when narrow; no horizontal page scroll at 390 px.
  • labels reaches Kumo's Tabs, 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 is flex 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 a basis-full child (for example a short note explaining why some actions are disabled) is squeezed into the button row.
  • ResourceHeader.tsx:34-38 explains 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 ResourceMode nor PageLayoutProps has 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 actionsNote renders 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 actionsNote is absent or null.
  • 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

  1. added
    accessibilityBarrier affecting people with disabilities
    bugSomething isn't working
    enhancementNew feature or request
    on Nov 15, 2026
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 disabilitiesbugSomething isn't workingenhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions