@charcuterie/ui 2.9.0 → 2.10.0

package/src/Shell/Shell.stories.tsx

@@ -0,0 +1,185 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { toStoryChoice } from "../argTypes.storyHelpers.ts"
+import { Header } from "../Header/Header.tsx"
+import { Main } from "../Main/Main.tsx"
+import { Rail } from "../Rail/Rail.tsx"
+import {
+  HeaderSchemeToggle,
+  OverflowingContent,
+  PageContent,
+  RailDetail,
+  RailNavigation,
+} from "../shell.storyHelpers.tsx"
+import { Shell } from "./Shell.tsx"
+
+/**
+ * `full` last, because it is the escape hatch rather than a step:
+ * everything before it is a `screen.*` token, and an app reaching
+ * for it is saying "this page is a wall of tiles", not picking a
+ * slightly larger number.
+ */
+const CONTENT_WIDTH_OPTIONS = [
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "2xl",
+  "full",
+] as const
+
+const meta = {
+  title: "Components/Shell",
+  component: Shell,
+  parameters: { layout: "fullscreen" },
+  argTypes: {
+    contentWidth: toStoryChoice(CONTENT_WIDTH_OPTIONS),
+  },
+  args: {
+    contentWidth: "lg",
+    skipLinkLabel: "Skip to main content",
+  },
+} satisfies Meta<typeof Shell>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * **Template 1 — header + main.** The shape eight of the fleet's
+ * ten hand-rolled shells are, and the whole of what most apps
+ * need. Copy it verbatim; only the contents of `actions` and
+ * `Main` differ per app.
+ */
+export const Default: Story = {
+  render: (shellProps) => (
+    <Shell {...shellProps}>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Rip Deck"
+      />
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * **Template 2 — header + a start rail.** The rail is the app's
+ * sections, so it is `landmark="navigation"` and gets a name an
+ * agent can scope to. Below `md` it becomes the strip above the
+ * content — the same element, not a second copy.
+ */
+export const WithStartRail: Story = {
+  render: (shellProps) => (
+    <Shell {...shellProps}>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Comic Ingest"
+      />
+
+      <Rail label="Sections" landmark="navigation">
+        <RailNavigation />
+      </Rail>
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * **Template 3 — header + both rails.** Sections on one side,
+ * the selected thing's detail on the other. Two rails is where
+ * naming stops being optional: two unnamed landmarks of the same
+ * type are indistinguishable to a screen reader and to an agent.
+ */
+export const WithBothRails: Story = {
+  render: (shellProps) => (
+    <Shell {...shellProps}>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Rip Deck"
+      />
+
+      <Rail label="Sections" landmark="navigation">
+        <RailNavigation />
+      </Rail>
+
+      <Main>
+        <PageContent />
+      </Main>
+
+      <Rail label="Job detail" side="end">
+        <RailDetail />
+      </Rail>
+    </Shell>
+  ),
+}
+
+/**
+ * The one the tests point a 390px viewport at.
+ *
+ * Both rails, plus the two shapes of content that make a page
+ * scroll sideways: an unbroken 130-character path, and a table
+ * wider than the phone it is on. Plex Channels' narrow view
+ * scrolls left and right today for the first reason; the second
+ * is what an `overflow-wrap` alone cannot save.
+ *
+ * `document.documentElement.scrollWidth <= clientWidth` at 390px
+ * is the assertion, and it is in `Shell.test.tsx` rather than
+ * here — a story is a demo.
+ */
+export const Responsive: Story = {
+  render: (shellProps) => (
+    <Shell {...shellProps}>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Transfers"
+      />
+
+      <Rail label="Sections" landmark="navigation">
+        <RailNavigation />
+      </Rail>
+
+      <Main>
+        <OverflowingContent />
+      </Main>
+
+      <Rail label="Job detail" side="end">
+        <RailDetail />
+      </Rail>
+    </Shell>
+  ),
+}
+
+/**
+ * What a keyboard user meets first. Tab once: the skip link
+ * appears at the top of the page and lands focus **inside**
+ * `<main>`, past the header and the rail.
+ *
+ * None of the fleet's ten hand-rolled shells has one, so on every
+ * one of those apps the first Tab starts a walk through the
+ * header — every page, every navigation.
+ */
+export const Interactive: Story = {
+  render: (shellProps) => (
+    <Shell {...shellProps}>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Rip Deck"
+      />
+
+      <Rail label="Sections" landmark="navigation">
+        <RailNavigation />
+      </Rail>
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}

package/src/Shell/Shell.test.tsx

@@ -0,0 +1,267 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent } from "storybook/test"
+import { afterAll, test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import {
+  DESKTOP,
+  PHONE,
+  setViewport,
+} from "../viewport.testHelpers.ts"
+import * as stories from "./Shell.stories.tsx"
+
+const {
+  Default,
+  Interactive,
+  Responsive,
+  WithBothRails,
+  WithStartRail,
+} = composeStories(stories)
+
+afterAll(async () => {
+  await setViewport(DESKTOP)
+})
+
+/**
+ * The page's own `<header>`, found structurally rather than by
+ * role — and the reason is worth writing down.
+ *
+ * `getByRole("banner")` returns **three** matches on any page with
+ * two `Card`s in it, because `Card` renders a `<header>` and
+ * testing-library's role mapping does not implement the HTML-AAM
+ * scoping rule that makes a `<header>` inside `<section>` generic
+ * rather than a banner. Chromium's real accessibility tree does
+ * implement it — which is what Playwright, a screen reader and an
+ * agent actually read, and why axe files no `landmark-unique` here
+ * — so this is a testing-library artefact and not a fault in the
+ * page.
+ *
+ * Asserting through the artefact would mean either shipping a page
+ * with no cards on it or teaching the shell to work around a
+ * query library. Neither is the component's problem, so the test
+ * takes the shell's first `<header>`, which is the one it renders.
+ */
+const getPageHeader = (canvasElement: HTMLElement) => {
+  const header = canvasElement.querySelector("header")
+
+  if (!header) {
+    throw new Error("The shell rendered no <header>.")
+  }
+
+  return header
+}
+
+/**
+ * The gate, stated as the browser sees it.
+ *
+ * `scrollWidth > clientWidth` on the documentElement is *exactly*
+ * "this page scrolls sideways" — no proxy, no computed-style
+ * inference. It is asserted rather than eyeballed because the
+ * causes are all invisible in a screenshot taken at the wrong
+ * width: a grid track that ignored `min-width: 0`, a `100vw` that
+ * counted the scrollbar gutter, a sticky header whose inner
+ * container is wider than the viewport.
+ */
+const expectNoHorizontalScroll = async () => {
+  const { documentElement } = document
+
+  await expect(
+    documentElement.scrollWidth,
+  ).toBeLessThanOrEqual(documentElement.clientWidth)
+}
+
+test("the shell does not scroll sideways at 390px, with content that tries", async () => {
+  await setViewport(PHONE)
+
+  const { canvas, canvasElement } =
+    await mountStory(Responsive)
+
+  // The fixture is only a fixture if it is really there: an
+  // unbroken 130-character path, plus a table wider than the
+  // phone. A regression that deleted the content would otherwise
+  // turn this into a green no-op.
+  await expect(
+    canvas.getByText(/Some-Very-Long-Show-Name-S01E01/),
+  ).toBeVisible()
+
+  await expect(
+    canvas.getByRole("table"),
+  ).toBeInTheDocument()
+
+  // The third fixture: a closed drawer parked at
+  // `translateX(110%)`. It has to be really parked past the
+  // inline edge, because a transform leaves the box in the
+  // document's scrollable overflow region — which is why this
+  // shape survives every `min-width: 0` in the tree, and why the
+  // assertion below is on `documentElement.scrollWidth` rather
+  // than on any element's bounding rect.
+  const parkedDrawer = canvasElement.querySelector(
+    "#parked-drawer",
+  ) as HTMLElement
+
+  await expect(
+    parkedDrawer.getBoundingClientRect().left,
+  ).toBeGreaterThan(PHONE.width)
+
+  const shellRoot =
+    canvasElement.firstElementChild as HTMLElement
+
+  // The drawer resolves against `Shell`, not the initial
+  // containing block — which is the only reason the clip below
+  // reaches it. `overflow-x: clip` clips descendants whose
+  // containing-block chain runs through the clipper, and an
+  // absolutely positioned box with no positioned ancestor has no
+  // such chain: it lands its overflow straight on
+  // `documentElement`, where `document.body.scrollWidth` still
+  // reads clean.
+  //
+  // Measured before `Shell` took `position: relative`:
+  // `shellScroll: 390`, `bodyScroll: 390`, `docScroll: 742`.
+  await expect(parkedDrawer.offsetParent).toBe(shellRoot)
+
+  await expect(
+    globalThis.getComputedStyle(shellRoot).overflowX,
+  ).toBe("clip")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("both rails and a full page do not scroll sideways at 390px either", async () => {
+  await setViewport(PHONE)
+
+  const { canvasElement } = await mountStory(WithBothRails)
+
+  await expectNoHorizontalScroll()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The other half of the same property. A shell that never
+ * overflows because it clipped everything would pass the test
+ * above; this is the assertion that the frame is actually laid
+ * out at the width it was given.
+ */
+test("the shell fills the viewport at desktop width without overflowing it", async () => {
+  await setViewport(DESKTOP)
+
+  await mountStory(WithBothRails)
+
+  await expectNoHorizontalScroll()
+})
+
+test("the shell is one banner, one main, and two uniquely-named rails", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(WithBothRails)
+
+  await expect(getPageHeader(canvasElement).tagName).toBe(
+    "HEADER",
+  )
+
+  expectAgentDrivable(canvas, { role: "main" })
+
+  // Named, so they are two things rather than two of the same
+  // thing — which is the whole reason `label` is required.
+  expectAgentDrivable(canvas, {
+    name: "Sections",
+    role: "navigation",
+  })
+
+  expectAgentDrivable(canvas, {
+    name: "Job detail",
+    role: "complementary",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The rail is in the document **once**, at every width.
+ *
+ * This is the assertion that would fail the `hidden`/`lg:hidden`
+ * implementation mux-magic and mail-sifter both ship — where every
+ * control exists twice in the DOM at every viewport, so a test has
+ * to be defensively scoped and an agent finds phantom controls.
+ * Four links narrow, four links wide.
+ */
+test("collapsing the rail does not duplicate its contents", async () => {
+  await setViewport(PHONE)
+
+  const phone = await mountStory(WithStartRail)
+
+  await expect(
+    phone.canvas.getAllByRole("link", { name: "Queue" }),
+  ).toHaveLength(1)
+
+  await setViewport(DESKTOP)
+
+  const desktop = await mountStory(WithStartRail)
+
+  await expect(
+    desktop.canvas.getAllByRole("link", { name: "Queue" }),
+  ).toHaveLength(1)
+})
+
+/**
+ * The skip link — missing from all ten of the fleet's hand-rolled
+ * shells, which is why it is the shell's job rather than the
+ * app's.
+ *
+ * The assertion is that it **moves focus into `<main>`**, not that
+ * an anchor exists. An `href` pointing at a non-focusable target
+ * scrolls the page and leaves the next Tab in the header, which
+ * looks like a working skip link and is not.
+ */
+test("the first Tab reaches a skip link that lands focus in main", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const skipLink = expectAgentDrivable(canvas, {
+    name: "Skip to main content",
+    role: "link",
+  })
+
+  const main = canvas.getByRole("main")
+
+  await expect(skipLink).toHaveAttribute(
+    "href",
+    `#${main.id}`,
+  )
+
+  await userEvent.click(skipLink)
+
+  await expect(main).toHaveFocus()
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("header and main are capped at the same width", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  // The inner rows, not the landmarks: the `<header>` and
+  // `<main>` are both full-bleed on purpose, and it is the row
+  // inside each that carries the cap.
+  const headerRow = getPageHeader(canvasElement)
+    .firstElementChild as HTMLElement
+
+  const mainRow = canvas.getByRole("main")
+    .firstElementChild as HTMLElement
+
+  // points-market ships these two disagreeing — its header row is
+  // capped at 80rem and its `<main>` is not capped at all — so on
+  // a wide monitor the title sits above content that starts to
+  // its left. One `contentWidth`, read from one context, is the
+  // fix.
+  await expect(
+    globalThis.getComputedStyle(headerRow).maxInlineSize,
+  ).toBe(globalThis.getComputedStyle(mainRow).maxInlineSize)
+
+  await expect(
+    headerRow.getBoundingClientRect().width,
+  ).toBe(mainRow.getBoundingClientRect().width)
+})

package/src/Shell/Shell.tsx

@@ -0,0 +1,170 @@
+import { useUniqueId } from "@charcuterie/logic"
+import {
+  type ComponentPropsWithRef,
+  type ReactNode,
+  useMemo,
+} from "react"
+
+import { toClassName } from "../toClassName.ts"
+import {
+  type ContentWidth,
+  DEFAULT_CONTENT_WIDTH,
+} from "./contentWidth.ts"
+import { ShellContext } from "./shellContext.ts"
+
+export type ShellProps = ComponentPropsWithRef<"div"> & {
+  contentWidth?: ContentWidth
+  skipLinkLabel?: string
+}
+
+/**
+ * The page frame: one `Header`, up to two `Rail`s, one `Main`.
+ *
+ * **The largest duplicated surface in the fleet.** Ten of twelve UI
+ * repos hand-roll this, and three of them have a file literally
+ * called `AppShell.tsx` — mail-sifter's and points-market's headers
+ * are a **byte-identical** string
+ * (`sticky top-0 z-40 border-b border-border-subtle bg-surface-base/90 backdrop-blur-md`),
+ * arrived at independently, and board-games' is the same structure
+ * with `sticky` dropped. The remaining seven spell it as
+ * `PageChrome`, `Header`, `DashboardHeader`, `Layout` (twice),
+ * `TitleBar`, and inline in `App.tsx`.
+ *
+ * Three things fall out of owning it once, and each is a bug
+ * somewhere in that list today:
+ *
+ *  - **A skip link.** All ten are missing one. A keyboard user
+ *    tabs through the whole header on every page.
+ *  - **One width, not two.** `Header` and `Main` read the same
+ *    `contentWidth` through context — see `shellContext.ts` for
+ *    the app where they disagree.
+ *  - **Sticky that is actually sticky.** mux-magic's `PageHeader`
+ *    is *described* as sticky and sets only `z-index`; it never
+ *    sets `position: sticky`, so the z-index does nothing and the
+ *    header scrolls away. `Header`'s `isSticky` sets both or
+ *    neither.
+ *
+ * ## The layout is one grid, and the rails do not duplicate
+ *
+ * Three columns at `md` and up — `auto minmax(0, 1fr) auto`, so an
+ * absent rail is a **zero-width track** rather than a conditional
+ * subtree — collapsing to a single column below it, where the
+ * children simply stack in DOM order. The same `Rail` element is
+ * in the document at every width; nothing is rendered twice behind
+ * `hidden`/`lg:hidden`.
+ *
+ * That matters beyond tidiness. mux-magic's `PageHeader` renders
+ * its entire control set twice (lines 290–345 and 356–410) and
+ * mail-sifter's `TriageQueue` does the same, so every action
+ * exists twice in the DOM at every viewport: tests have to be
+ * defensively scoped with `within(toolbar)`, and any agent driving
+ * the page sees phantom controls it cannot click.
+ *
+ * `minmax(0, 1fr)` on the middle track is the horizontal-scroll
+ * fix, not a formality. A grid track's automatic minimum is
+ * `min-content`, so **one long unbroken string in `Main` widens
+ * the whole page** — which is the bug plex-channels' narrow view
+ * has today. rip-deck's `BayGrid` documents the same fix from the
+ * other end.
+ *
+ * There is no `gap`: an empty `auto` track is 0 wide, but a `gap`
+ * beside it is not, so a shell with no rails would carry two
+ * mystery gutters. `Rail` and `Main` bring their own padding.
+ *
+ * ## `overflow-x: clip` — the structural guarantee
+ *
+ * `minmax(0, 1fr)` fixes the tracks and `Main`'s `wrap-anywhere`
+ * fixes the text, but neither reaches the shape that actually
+ * broke plex-channels: **a closed panel parked at
+ * `transform: translateX(110%)`**. A transform does not take a box
+ * out of the document's scrollable overflow region — and neither
+ * does `visibility: hidden` — so an off-screen drawer that looks
+ * absent still makes the page scroll to it. It is a favourite
+ * fleet pattern and no amount of `min-width: 0` touches it.
+ *
+ * `clip`, not `hidden`, and the two are not interchangeable here:
+ * `overflow: hidden` creates a **scroll container**, which would
+ * become the sticky containing block for `Header` and freeze it in
+ * place. `overflow-x: clip` creates no scrollport, so `Header`
+ * keeps sticking to the viewport, and `overflow-y` stays `visible`
+ * — a pair that is legal for `clip` and illegal for `hidden`,
+ * which would compute the other axis to `auto`.
+ *
+ * The trade is deliberate: content wider than the frame is
+ * **clipped rather than reachable by scrolling sideways**, which is
+ * exactly the outcome asked for. Content that genuinely needs to
+ * be wider owns a scroll container of its own — the pattern
+ * `Main.mdx` documents for tables.
+ *
+ * ### `relative` is what makes the clip reach anything
+ *
+ * `overflow-x: clip` only clips descendants whose **containing
+ * block chain passes through the clipping element**. An absolutely
+ * positioned element with no positioned ancestor resolves against
+ * the *initial* containing block instead, so it sails straight
+ * past every `overflow` in the tree and lands its overflow on
+ * `documentElement` — where `document.body.scrollWidth` still
+ * reads clean and only `document.documentElement.scrollWidth`
+ * shows it.
+ *
+ * That is not hypothetical: it is measured. Before this
+ * `relative`, the parked-drawer fixture reported `shellScroll:
+ * 390`, `bodyScroll: 390` and `docScroll: 742` at a 390px
+ * viewport — the shell dutifully clipping a box it had no
+ * authority over.
+ *
+ * The obvious candidate to own it, `Main`'s content column, does
+ * **not**: `container-type: inline-size` computes `contain` to
+ * `none` in Chromium and establishes no containing block for
+ * absolute positioning, which is measured too — the drawer's
+ * `offsetParent` was `BODY`. So `Shell` takes the job, which is
+ * also the honest place for it: the frame is what an app's parked
+ * chrome is parked against.
+ */
+export const Shell = ({
+  children,
+  className,
+  contentWidth = DEFAULT_CONTENT_WIDTH,
+  skipLinkLabel = "Skip to main content",
+  ...divProps
+}: ShellProps): ReactNode => {
+  const mainId = useUniqueId()
+
+  const shellContext = useMemo(
+    () => ({ contentWidth, mainId }),
+    [contentWidth, mainId],
+  )
+
+  return (
+    <ShellContext.Provider value={shellContext}>
+      <div
+        {...divProps}
+        className={toClassName(
+          "relative grid min-h-dvh grid-cols-1 grid-rows-[auto_auto_1fr_auto] overflow-x-clip bg-surface-base text-content-primary md:grid-cols-[auto_minmax(0,1fr)_auto] md:grid-rows-[auto_1fr]",
+          className,
+        )}
+      >
+        {/*
+          Hidden by transform rather than by `sr-only`, because
+          `focus-visible:not-sr-only` and `focus-visible:fixed`
+          both write `position` and which one wins is decided by
+          Tailwind's internal property order, not by the order they
+          are written in. A translate is one property, and a
+          keyboard user's first Tab landing on a visible control is
+          the entire feature.
+
+          `--layer-toast` rather than `--layer-sticky`: it has to
+          out-rank the header it is offering to skip past.
+        */}
+        <a
+          className="fixed top-0 start-0 z-[var(--layer-toast)] m-3 -translate-y-24 rounded-md border border-border-subtle bg-surface-raised px-3 py-2 font-medium text-content-primary text-sm shadow-medium focus-visible:translate-y-0"
+          href={`#${mainId}`}
+        >
+          {skipLinkLabel}
+        </a>
+
+        {children}
+      </div>
+    </ShellContext.Provider>
+  )
+}