@charcuterie/ui 2.8.0 → 2.10.0

package/src/Rail/Rail.test.tsx

@@ -0,0 +1,150 @@
+import { composeStories } from "@storybook/react"
+import { expect, within } 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 "./Rail.stories.tsx"
+
+const { AllVariants, Default, Interactive, Responsive } =
+  composeStories(stories)
+
+afterAll(async () => {
+  await setViewport(DESKTOP)
+})
+
+test("landmark decides the element, and both are named", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllVariants)
+
+  const navigation = expectAgentDrivable(canvas, {
+    name: "Sections",
+    role: "navigation",
+  })
+
+  await expect(navigation.tagName).toBe("NAV")
+
+  const complementary = expectAgentDrivable(canvas, {
+    name: "Job detail",
+    role: "complementary",
+  })
+
+  await expect(complementary.tagName).toBe("ASIDE")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The collapse is a restyle, not a second render.
+ *
+ * Twelve links at 390px and twelve links at 1440px — the number
+ * that would be twenty-four in the `hidden`/`lg:hidden`
+ * implementation mux-magic and mail-sifter both ship, at every
+ * viewport, where an agent cannot tell the visible copy from the
+ * hidden one.
+ */
+test("the same links exist once at both widths", async () => {
+  await setViewport(PHONE)
+
+  const phone = await mountStory(Responsive)
+
+  const phoneRail = expectAgentDrivable(phone.canvas, {
+    name: "Sections",
+    role: "navigation",
+  })
+
+  await expect(
+    within(phoneRail).getAllByRole("link"),
+  ).toHaveLength(12)
+
+  // A strip, not a column: the flex axis is what actually
+  // changed. Asserting the axis rather than a height is the
+  // lesson from `Alert`'s container-query test, where comparing
+  // heights passed with the responsive rule deleted.
+  await expect(
+    globalThis.getComputedStyle(phoneRail).flexDirection,
+  ).toBe("row")
+
+  await setViewport(DESKTOP)
+
+  const desktop = await mountStory(Responsive)
+
+  const desktopRail = expectAgentDrivable(desktop.canvas, {
+    name: "Sections",
+    role: "navigation",
+  })
+
+  await expect(
+    within(desktopRail).getAllByRole("link"),
+  ).toHaveLength(12)
+
+  await expect(
+    globalThis.getComputedStyle(desktopRail).flexDirection,
+  ).toBe("column")
+})
+
+/**
+ * Twelve sections on a phone is the case that makes a naive rail
+ * widen the page. The strip owns its overflow instead.
+ */
+test("a rail too long for a phone scrolls itself, not the page", async () => {
+  await setViewport(PHONE)
+
+  const { canvas, canvasElement } =
+    await mountStory(Responsive)
+
+  const rail = expectAgentDrivable(canvas, {
+    name: "Sections",
+    role: "navigation",
+  })
+
+  // The fixture really does overflow — otherwise the assertion
+  // below is true for the wrong reason.
+  await expect(rail.scrollWidth).toBeGreaterThan(
+    rail.clientWidth,
+  )
+
+  const { documentElement } = document
+
+  await expect(
+    documentElement.scrollWidth,
+  ).toBeLessThanOrEqual(documentElement.clientWidth)
+
+  // A scrolling region has to be reachable without a mouse. It is
+  // here because it is a landmark full of links, which is what
+  // axe's `scrollable-region-focusable` accepts — a rail of plain
+  // text would not be, and that is the honest limit of the
+  // pattern.
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the rail scopes its own links away from the header's", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const rail = expectAgentDrivable(canvas, {
+    name: "Sections",
+    role: "navigation",
+  })
+
+  expectAgentDrivable(within(rail), {
+    name: "Settings",
+    role: "link",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("a single start rail is clean under axe", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Rail/Rail.tsx

@@ -0,0 +1,102 @@
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { toClassName } from "../toClassName.ts"
+
+export type RailLandmark = "complementary" | "navigation"
+
+export type RailSide = "end" | "start"
+
+export type RailProps = ComponentPropsWithRef<"aside"> & {
+  label: string
+  landmark?: RailLandmark
+  side?: RailSide
+}
+
+const LANDMARK_ELEMENT: Record<
+  RailLandmark,
+  "aside" | "nav"
+> = {
+  complementary: "aside",
+  navigation: "nav",
+}
+
+/**
+ * A side rail — the nav column, the filter panel, the drive list.
+ *
+ * `side` places it, `landmark` decides what it *is*, and `label`
+ * is required for a reason: two unnamed rails in one page are two
+ * landmarks of the same type with no way to tell them apart, which
+ * is axe's `landmark-unique` and, more to the point, is a screen
+ * reader announcing "complementary" twice. It is also what makes
+ * the rail scopeable — `getByRole("navigation", { name: "Sections" })`
+ * disambiguates a "Settings" link that also exists in the header.
+ *
+ * ## It collapses without duplicating itself
+ *
+ * Below `md` the shell is one column and the rail becomes a
+ * horizontally-scrolling strip above (`side="start"`) or below
+ * (`side="end"`) the content. Above it, the rail is a fixed-width
+ * column in the grid.
+ *
+ * **The same element, restyled — not a second copy.** The fleet's
+ * habit is to render the whole thing twice behind `hidden` and
+ * `lg:hidden`: mux-magic's `PageHeader` does it across two ~55-line
+ * blocks and mail-sifter's `TriageQueue` does it again. The cost is
+ * not bytes, it is that every control exists **twice in the DOM at
+ * every viewport** — so tests must be defensively scoped, an agent
+ * driving the page finds two of each button and cannot tell which
+ * is the visible one, and the two copies drift.
+ *
+ * A media query gets the whole job done here because only the
+ * rail's *position* changes, never its contents. plex-channels'
+ * `App.tsx` shows the pattern for when that is not true — a
+ * `useMediaQuery` over `matchMedia` through `useSyncExternalStore`,
+ * mounting exactly one instance and relocating it — and it is
+ * strictly more machinery for the same guarantee, so it is not what
+ * this component uses.
+ *
+ * The `md` breakpoint is 48rem, which is `screen.md`: Tailwind v4's
+ * default `--breakpoint-*` scale and this repo's `screen.*` scale
+ * carry the same five values, so `md:` and the token agree by
+ * construction rather than by coincidence maintained by hand.
+ *
+ * ## The narrow strip scrolls itself
+ *
+ * `overflow-x-auto` on the rail is what keeps a twelve-item nav
+ * from widening the *page* at 390px: the overflow is contained in
+ * an element that scrolls, which is the sanctioned answer for
+ * content that genuinely cannot wrap. `min-w-0` is on it for the
+ * same reason `Shell`'s middle track is `minmax(0, 1fr)` — a flex
+ * or grid child's automatic minimum is its content, and one long
+ * unbroken string otherwise pushes the whole layout out of the
+ * viewport.
+ */
+export const Rail = ({
+  children,
+  className,
+  label,
+  landmark = "complementary",
+  side = "start",
+  ...railProps
+}: RailProps): ReactNode => {
+  const Element = LANDMARK_ELEMENT[landmark]
+
+  return (
+    <Element
+      {...railProps}
+      aria-label={label}
+      className={toClassName(
+        "flex min-w-0 gap-2 overflow-x-auto border-border-subtle p-4 md:row-start-2 md:w-64 md:flex-col md:overflow-x-visible",
+        side === "start"
+          ? "row-start-2 border-b md:col-start-1 md:border-b-0 md:border-e"
+          : "row-start-4 border-t md:col-start-3 md:border-t-0 md:border-s",
+        className,
+      )}
+    >
+      {children}
+    </Element>
+  )
+}

package/src/Shell/Shell.mdx

@@ -0,0 +1,186 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ShellStories from "./Shell.stories";
+
+<Meta of={ShellStories} />
+
+# Shell
+
+**The fleet's largest duplicated surface.** Ten of twelve UI repos hand-roll the page
+chrome, and three of them have a file literally named `AppShell.tsx` — mail-sifter's and
+points-market's headers are a *byte-identical* string, arrived at independently:
+
+```tsx
+<header className="sticky top-0 z-40 border-b border-border-subtle bg-surface-base/90 backdrop-blur-md">
+```
+
+board-games' is the same structure with `sticky` dropped. The other seven spell the same
+idea as `PageChrome`, `Header`, `DashboardHeader`, `Layout` (twice), `TitleBar`, and
+inline in `App.tsx`.
+
+The owner's ask, verbatim:
+
+> "We need a header component. Apps are all doing it differently, and there's no
+> standardized way to do a sticky header + narrow view... A Unified App Shell basically."
+
+<Canvas of={ShellStories.Default} />
+
+## Props
+
+<Controls />
+
+## The three templates
+
+The controls differ per app. The structure does not — so these are meant to be copied
+whole, and the only edits are what goes in `actions`, in the rails, and in `Main`.
+
+### 1. Header + main
+
+Eight of the fleet's ten hand-rolled shells are this shape, and most apps need nothing
+else.
+
+```tsx
+<Shell>
+  <Header actions={<ColorSchemeSwitcher icons={ICONS} />} heading="Rip Deck" />
+
+  <Main>
+    <PageContent />
+  </Main>
+</Shell>
+```
+
+### 2. Header + a start rail
+
+<Canvas of={ShellStories.WithStartRail} />
+
+```tsx
+<Shell>
+  <Header actions={<ColorSchemeSwitcher icons={ICONS} />} heading="Comic Ingest" />
+
+  <Rail label="Sections" landmark="navigation">
+    <NavLinks />
+  </Rail>
+
+  <Main>
+    <PageContent />
+  </Main>
+</Shell>
+```
+
+`label` is required, and `landmark="navigation"` makes it a `<nav>`. Both matter the
+moment there are two rails.
+
+### 3. Header + both rails
+
+<Canvas of={ShellStories.WithBothRails} />
+
+```tsx
+<Shell>
+  <Header actions={<ColorSchemeSwitcher icons={ICONS} />} heading="Rip Deck" />
+
+  <Rail label="Sections" landmark="navigation">
+    <NavLinks />
+  </Rail>
+
+  <Main>
+    <PageContent />
+  </Main>
+
+  <Rail label="Job detail" side="end">
+    <JobDetail />
+  </Rail>
+</Shell>
+```
+
+Order the children the way they should be **read**: header, start rail, main, end rail.
+Below `md` the grid is one column and that DOM order is the reading order; above it, the
+`side` prop places each rail in its own track.
+
+## One width, not two
+
+`contentWidth` is stated once, on `Shell`, and `Header` and `Main` both read it. That is a
+bug fix, not tidiness: **points-market's header is capped at 80rem and its `<main>` is not
+capped at all**, so on a wide monitor the page title sits above content that starts to its
+left and runs past its right. Nothing errors; the two values were simply written on
+different days.
+
+Either component still takes its own `contentWidth` for a real reason — a full-bleed hero
+under a constrained header — but that now takes a prop somebody wrote on purpose.
+
+The scale and how it composes with a runtime-computed cap are on the
+[`Main`](?path=/docs/components-main--docs) page.
+
+## The rails collapse without duplicating
+
+Below `md` the shell is a single column and each `Rail` becomes a horizontally-scrolling
+strip. **The same element, restyled — never a second copy.** mux-magic's `PageHeader`
+renders its entire control set twice (lines 290–345 and 356–410) behind `hidden` /
+`lg:hidden`, and mail-sifter's `TriageQueue` does it again. The cost is not bytes: every
+action exists twice in the DOM at *every* viewport, so tests must be defensively scoped
+with `within(toolbar)`, an agent driving the page finds two of each button with no way to
+tell which is visible, and the two copies drift.
+
+plex-channels' `App.tsx` shows the pattern for when the contents genuinely have to differ
+— a `useMediaQuery` over `matchMedia` through `useSyncExternalStore`, mounting exactly one
+instance and relocating it. It is strictly more machinery for the same guarantee, so a
+rail that only changes *position* uses a media query and nothing else.
+
+<Canvas of={ShellStories.Responsive} />
+
+## It does not scroll sideways, and that is a test
+
+Plex Channels' narrow view scrolls left and right as wide as its content area. The usual
+causes are all shell faults: a grid track that ignores `min-width: 0`, a `100vw` that
+counts the scrollbar gutter, or a sticky header whose inner container is wider than the
+viewport.
+
+There are **three** shapes of it, and each needs a different answer:
+
+| Shape | Answer |
+| --- | --- |
+| A grid track sized to `min-content` | `minmax(0, 1fr)` on the middle track |
+| Text ink from a long unbroken token | `wrap-anywhere` on `Main`'s column |
+| A box parked off-screen by a transform | `position: relative` + `overflow-x: clip` here |
+
+The third is the one that broke plex-channels: a closed panel at
+`transform: translateX(110%)`. **A transform does not remove a box from the document's
+scrollable overflow region**, and neither does `visibility: hidden` — so a drawer nobody can
+see still makes the page scroll to it.
+
+`clip`, not `hidden`: `overflow: hidden` creates a scroll container, which would become the
+sticky containing block for `Header` and freeze it. `clip` creates no scrollport, and it is
+the one value that may pair with `overflow-y: visible`.
+
+The `relative` is not decoration. `overflow-x: clip` only clips descendants whose containing
+block chain runs through the clipper, and an absolutely positioned box with no positioned
+ancestor resolves against the *initial* containing block instead — sailing past every
+`overflow` in the tree. Measured, before `Shell` took `relative`: `shellScroll: 390`,
+`bodyScroll: 390`, **`docScroll: 742`** at a 390px viewport. The obvious candidate to own it
+— `Main`'s content column — does not, because `container-type: inline-size` computes
+`contain` to `none` in Chromium and establishes no containing block for absolute
+positioning; the drawer's `offsetParent` was `BODY`.
+
+`Shell.test.tsx` and `Main.test.tsx` assert
+`document.documentElement.scrollWidth <= clientWidth` at a real 390px viewport against a
+story carrying all three shapes at once, with each fixture separately asserted to actually
+overflow. **`documentElement`, not `body`** — the parked-drawer case leaves
+`document.body.scrollWidth` reading a clean 390 while the page scrolls, and it leaves no
+overflowing element box for a `getBoundingClientRect()` assertion to catch either.
+
+There is no grid `gap`: an absent rail is a zero-width `auto` track, 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.
+
+## The skip link
+
+<Canvas of={ShellStories.Interactive} />
+
+All ten hand-rolled shells are missing one, so on every one of those apps a keyboard user
+starts each page by tabbing through the header. `Shell` renders it, points it at the
+`<main>` it generated the id for, and `Main` carries `tabIndex={-1}` so activating it moves
+**focus** rather than only the scroll position — an `href` at a non-focusable target leaves
+the next Tab back in the header, which looks like a working skip link and is not.
+
+It is hidden by a 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 rather than by the order they are written in.

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>
+  ),
+}