@charcuterie/ui 2.9.0 → 2.10.0

package/src/Shell/contentWidth.ts

@@ -0,0 +1,89 @@
+/**
+ * How wide the content column is allowed to get — the one number
+ * the fleet has never agreed on.
+ *
+ * Ten repos hand-roll their page chrome and **no two of them cap
+ * the column at the same width**: `max-w-5xl` (board-games,
+ * portly), `max-w-6xl` and `max-w-3xl` mixed inside one app
+ * (mux-magic), `max-w-7xl` (gallery-downloader, spoolbuddy),
+ * `max-w-[90rem]` (mail-sifter), `80rem` (points-market), a raw
+ * `1400px` in plain CSS (plex-channels), a JS-computed one
+ * (rip-deck), and none at all in three more. It is the least
+ * standardized value in the entire fleet.
+ *
+ * Two shapes are accepted, because the fleet genuinely has two
+ * cases and collapsing them is what produced the mess:
+ *
+ *  1. A **`screen.*` step** — the ordinary page. Named, so a
+ *     reviewer reads `contentWidth="lg"` rather than deciding
+ *     whether `max-w-6xl` was chosen or inherited.
+ *  2. A **`${number}rem` literal** — the runtime-computed case.
+ *     rip-deck's `contentMaxWidthRem(columns)` widens the cap as
+ *     the grid gains columns (1 → 56rem, 2 → 72rem, 3 → 106rem),
+ *     and no fixed scale can express a number that is decided
+ *     after the viewport is measured.
+ *
+ * `"full"` is the third answer and it is deliberate rather than a
+ * hole: a wall of poster tiles wants the whole window, and an app
+ * that wants that today reaches the same place by *omitting* the
+ * cap, which is indistinguishable from having forgotten it.
+ *
+ * **`max-w-*` is not used and must not be.** Tailwind v4 owns
+ * `--container-*` for that scale at *different* sizes than our
+ * `screen.*`, which is the collision that renamed our
+ * container-query scale to `--cq-*`
+ * ([decision](../../../../docs/decisions/2026-07-29-container-query-scale-is-cq-not-container.md)).
+ * The cap is therefore an inline `max-inline-size` reading
+ * `var(--screen-*)`, so it stays a token rather than becoming a
+ * literal the moment it is written down.
+ */
+
+import { screen } from "@charcuterie/tokens"
+
+/** `sm` | `md` | `lg` | `xl` | `2xl`, from the token scale. */
+export type ScreenStep = keyof typeof screen
+
+export type ContentWidth =
+  | ScreenStep
+  | "full"
+  | `${number}rem`
+
+/**
+ * Derived from the scale rather than restated, so a step added to
+ * `screen.*` is accepted here without a second edit — and one
+ * removed stops typechecking at every call site.
+ */
+const SCREEN_STEPS = new Set<string>(Object.keys(screen))
+
+/**
+ * The `max-inline-size` a `contentWidth` resolves to, or
+ * `undefined` for `"full"` — which is the absence of the property
+ * rather than a very large value, so nothing has to be un-set.
+ */
+export const toMaxInlineSize = (
+  contentWidth: ContentWidth,
+): string | undefined => {
+  if (contentWidth === "full") {
+    return undefined
+  }
+
+  if (SCREEN_STEPS.has(contentWidth)) {
+    return `var(--screen-${contentWidth})`
+  }
+
+  return contentWidth
+}
+
+/**
+ * The cap an app gets without asking, and it is deliberately
+ * **narrower** than most of what the fleet ships.
+ *
+ * The owner's complaint, verbatim: *"All these apps seem to be
+ * really narrow with a very large max-width. By that I mean 1
+ * column, but waaaaaaay too wide."* A single column of prose or
+ * form fields at `max-w-7xl` is one line of text the eye has to
+ * track across a monitor. `screen.lg` is 64rem — wide enough for a
+ * two-up card grid, narrow enough to read — and an app whose
+ * content genuinely fills a window says so, once, in one place.
+ */
+export const DEFAULT_CONTENT_WIDTH: ContentWidth = "lg"

package/src/Shell/shellContext.ts

@@ -0,0 +1,41 @@
+/**
+ * What `Shell` tells `Header` and `Main` so they cannot disagree.
+ *
+ * This context exists because of one specific bug, present in the
+ * fleet today: **points-market's header is width-constrained and
+ * its `<main>` is not.** `AppShell.tsx` wraps the header row in
+ * `.pm-constrained` (80rem) and then renders
+ * `<main className="px-4 py-6 sm:px-6">` with no cap 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, both values
+ * are individually reasonable, and the two were simply written on
+ * different days.
+ *
+ * A width that has to be stated twice will eventually be stated
+ * twice differently. So it is stated **once**, on `Shell`, and the
+ * two elements that have to agree read it from here. Either can
+ * still override for a genuine reason — a full-bleed hero `Main`
+ * under a constrained `Header` is a real design — but that now
+ * takes a prop somebody wrote on purpose.
+ *
+ * `mainId` rides along for the same reason: the skip link's `href`
+ * and the `<main>` it lands on are one value, generated once.
+ */
+
+import { createContext } from "react"
+
+import type { ContentWidth } from "./contentWidth.ts"
+
+export type ShellContextValue = {
+  contentWidth: ContentWidth
+  mainId: string
+}
+
+/**
+ * `null` rather than a default object, so `Header` and `Main` can
+ * tell "no `Shell` above me" from "a `Shell` that chose the
+ * defaults" — the first case has to generate its own `<main>` id,
+ * the second must not.
+ */
+export const ShellContext =
+  createContext<ShellContextValue | null>(null)

package/src/index.ts

@@ -113,6 +113,8 @@ export type { FieldGroupProps } from "./Field/FieldGroup.tsx"
 export { FieldGroup } from "./Field/FieldGroup.tsx"
 export type { FileDropZoneProps } from "./FileDropZone/FileDropZone.tsx"
 export { FileDropZone } from "./FileDropZone/FileDropZone.tsx"
+export type { HeaderProps } from "./Header/Header.tsx"
+export { Header } from "./Header/Header.tsx"
 export type { IconButtonProps } from "./IconButton/IconButton.tsx"
 export { IconButton } from "./IconButton/IconButton.tsx"
 export type { IntentAppearance } from "./intentStyles.ts"
@@ -142,6 +144,8 @@ export type {
   LogViewerProps,
 } from "./LogViewer/LogViewer.tsx"
 export { LogViewer } from "./LogViewer/LogViewer.tsx"
+export type { MainProps } from "./Main/Main.tsx"
+export { Main } from "./Main/Main.tsx"
 export type {
   MediaTileProps,
   MediaTileRatio,
@@ -174,6 +178,12 @@ export type {
   RadioItem,
 } from "./RadioGroup/RadioGroup.tsx"
 export { RadioGroup } from "./RadioGroup/RadioGroup.tsx"
+export type {
+  RailLandmark,
+  RailProps,
+  RailSide,
+} from "./Rail/Rail.tsx"
+export { Rail } from "./Rail/Rail.tsx"
 export { AnchorLink } from "./RouterLink/AnchorLink.tsx"
 export {
   RouterLinkProvider,
@@ -196,6 +206,12 @@ export type {
   SelectProps,
 } from "./Select/Select.tsx"
 export { Select } from "./Select/Select.tsx"
+export type {
+  ContentWidth,
+  ScreenStep,
+} from "./Shell/contentWidth.ts"
+export type { ShellProps } from "./Shell/Shell.tsx"
+export { Shell } from "./Shell/Shell.tsx"
 export type {
   SkeletonProps,
   SkeletonShape,

package/src/shell.storyHelpers.tsx

@@ -0,0 +1,258 @@
+import type { ColorSchemeMode } from "@charcuterie/logic"
+import { type ReactNode, useState } from "react"
+
+import { Badge } from "./Badge/Badge.tsx"
+import { Button } from "./Button/Button.tsx"
+import { Card } from "./Card/Card.tsx"
+import { ColorSchemeToggle } from "./ColorSchemeToggle/ColorSchemeToggle.tsx"
+import {
+  MonitorIcon,
+  MoonIcon,
+  SunIcon,
+} from "./icons.storyHelpers.tsx"
+
+/**
+ * The furniture the four shell stories share: a rail's worth of
+ * links, a page's worth of cards, the scheme control that lives in
+ * the header, and the three things that make a page scroll
+ * sideways.
+ *
+ * `.storyHelpers.tsx` rather than `.tsx` because `react/no-multi-comp`
+ * is switched off for that suffix, and it is excluded from the
+ * package build so none of this ships.
+ */
+
+/**
+ * A scheme control with its own state — `ColorSchemeToggle` rather
+ * than `ColorSchemeSwitcher`, deliberately.
+ *
+ * The connected switcher writes `data-scheme` onto `<html>` and a
+ * mode into `localStorage`. In a shell story that is a component
+ * reaching outside its own canvas to re-theme Storybook and leave
+ * a value behind for the next test, which is exactly the kind of
+ * cross-test coupling `mountStory` exists to prevent. The
+ * presentational half proves the same thing about `Header` — that
+ * the actions slot holds the fleet's scheme control — and touches
+ * nothing.
+ */
+export const HeaderSchemeToggle = (): ReactNode => {
+  const [mode, setMode] =
+    useState<ColorSchemeMode>("system")
+
+  return (
+    <ColorSchemeToggle
+      icons={{
+        dark: <MoonIcon />,
+        light: <SunIcon />,
+        system: <MonitorIcon />,
+      }}
+      mode={mode}
+      onCycle={setMode}
+      size="sm"
+    />
+  )
+}
+
+/** What a start rail holds: the app's sections. */
+export const RailNavigation = (): ReactNode => (
+  <>
+    {["Queue", "Library", "Transfers", "Settings"].map(
+      (section) => (
+        <a
+          className="rounded-md px-3 py-2 text-content-secondary text-sm hover:bg-intent-neutral-surface hover:text-content-primary"
+          href={`#${section.toLowerCase()}`}
+          key={section}
+        >
+          {section}
+        </a>
+      ),
+    )}
+  </>
+)
+
+/** What an end rail holds: the detail of whatever is selected. */
+export const RailDetail = (): ReactNode => (
+  <>
+    <span className="font-semibold text-content-primary text-sm">
+      Selected job
+    </span>
+
+    <span className="text-content-secondary text-sm">
+      Disc 3 of 9 · reading at 6.0x
+    </span>
+
+    <Badge intent="success">Healthy</Badge>
+  </>
+)
+
+/** An ordinary page, so a template shows something. */
+export const PageContent = (): ReactNode => (
+  <>
+    <Card heading="Tonight's queue">
+      <p className="text-content-secondary text-sm">
+        Nine discs, three bays. The column stays readable at
+        any window width because the cap is a token rather
+        than a number somebody typed.
+      </p>
+    </Card>
+
+    <Card
+      actions={<Button size="sm">Start</Button>}
+      heading="Bay 3"
+    >
+      <p className="text-content-secondary text-sm">
+        Idle since 21:04.
+      </p>
+    </Card>
+  </>
+)
+
+/**
+ * Enough page to scroll, with **no landmarks in it**.
+ *
+ * `<PageContent />` twice would be the obvious way to make a tall
+ * page and it is an accessibility violation: `Card` takes a
+ * `region` landmark from its heading, so two copies are two pairs
+ * of identically-named regions — axe's `landmark-unique`, and the
+ * same "which one did the agent mean" ambiguity in a test. A
+ * sticky-header demo needs height, not more landmarks.
+ */
+export const ScrollFiller = (): ReactNode => (
+  <>
+    {[
+      "Bays are polled every two seconds.",
+      "A stalled bay is one that has not moved a byte in forty.",
+      "Verification runs after the last title, never during.",
+      "The tower's USB hub is the single point of failure.",
+      "Discs are ejected only once the hash matches.",
+      "A retry lands in a different bay when one is free.",
+      "Nothing here is a landmark, which is the point.",
+      "Scroll to watch the header stay where it is.",
+    ].map((line) => (
+      <p
+        className="text-content-secondary text-sm"
+        key={line}
+      >
+        {line}
+      </p>
+    ))}
+  </>
+)
+
+/**
+ * The three things that actually make a page scroll sideways, and
+ * each needs a different answer.
+ *
+ * The **path** is content that *can* wrap and does not, because
+ * nothing in it is a break opportunity. `Main`'s `wrap-anywhere`
+ * handles it, so it is dropped in raw on purpose — if the shell
+ * regresses, this is the fixture that notices.
+ *
+ * The **table** is content that genuinely cannot wrap: a table's
+ * columns have min-content widths and no amount of
+ * `overflow-wrap` reaches them. The only correct answer is a
+ * scroll container around it — and because that container
+ * scrolls, the columns off screen have to be reachable without a
+ * mouse, which is axe's `scrollable-region-focusable`.
+ *
+ * There are two ways to satisfy it and this fixture takes the
+ * better one: the row ends in a **link**, so tabbing to it
+ * scrolls the container into view and the region needs nothing
+ * else. The other way is `tabIndex={0}` on the container itself,
+ * which is what a table of pure text needs — and which Biome's
+ * `noNoninteractiveTabindex` rejects, unsafely-fixing the
+ * attribute away before a suppression is even evaluated.
+ * `Main.mdx` states both.
+ */
+export const OverflowingContent = (): ReactNode => (
+  <>
+    {/*
+      The third shape, and the one that broke plex-channels: a
+      closed drawer parked off the inline edge by a transform.
+
+      It is still laid out, still painted, and still part of the
+      document's scrollable overflow region — a transform does not
+      remove a box from it, and neither does `visibility: hidden`.
+      So the page scrolls sideways to reach a panel nobody can see,
+      and every `min-width: 0` in the tree is irrelevant. `Shell`'s
+      `overflow-x: clip` is what actually answers it.
+    */}
+    <div
+      aria-hidden="true"
+      className="pointer-events-none absolute top-0 end-0 h-40 w-80 translate-x-[110%] rounded-lg border border-border-subtle bg-surface-raised"
+      id="parked-drawer"
+    />
+
+    <p className="text-content-secondary text-sm">
+      /mnt/Bunnies/Family/Media/Television/Some-Very-Long-Show-Name/Season-01/Some-Very-Long-Show-Name-S01E01-Pilot-2160p-HDR-DTS-HD-MA.mkv
+    </p>
+
+    <section
+      aria-label="Transfer log, scrollable"
+      className="charcuterie-scrollbar overflow-x-auto rounded-lg border border-border-subtle"
+    >
+      <table className="w-max border-collapse text-sm">
+        <caption className="p-2 text-content-muted text-xs">
+          Wider than a phone, on purpose.
+        </caption>
+
+        <thead>
+          <tr>
+            {[
+              "Started",
+              "Source volume",
+              "Destination dataset",
+              "Bytes moved",
+              "Throughput",
+              "Verified",
+              "Job",
+            ].map((column) => (
+              <th
+                className="whitespace-nowrap border-border-subtle border-b p-2 text-start text-content-secondary"
+                key={column}
+                scope="col"
+              >
+                {column}
+              </th>
+            ))}
+          </tr>
+        </thead>
+
+        <tbody>
+          <tr>
+            {[
+              "21:04:11",
+              "/mnt/Bunnies/Kevin/Incoming",
+              "/mnt/Bunnies/Family/Media/Television",
+              "48,912,338,112",
+              "612 MB/s",
+              "sha256 ok",
+            ].map((cell) => (
+              <td
+                className="whitespace-nowrap p-2 text-content-primary"
+                key={cell}
+              >
+                {cell}
+              </td>
+            ))}
+
+            {/*
+              The keyboard route into the off-screen columns.
+              Tabbing to it scrolls the container, which is what
+              axe's `scrollable-region-focusable` accepts and what
+              makes the wide table usable without a mouse.
+            */}
+            <td className="whitespace-nowrap p-2">
+              <a
+                className="text-intent-accent-content underline"
+                href="#transfer-4812"
+              >
+                Open
+              </a>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </section>
+  </>
+)

package/src/sourceRules.test.ts

@@ -201,10 +201,19 @@ test("a container-query component is never storied in a shrink-to-fit cell", ()
 
   // A canary on the derivation itself: if this ever comes back
   // empty the rule silently passes forever.
+  // `Main` joins them with the app shell. It is the one whose
+  // `contain: inline-size` is *wanted* rather than tolerated —
+  // content may no longer widen the content column, which is half
+  // of why the shell does not scroll sideways at 390px — and the
+  // `contain: layout` that rides along with it is documented in
+  // `Main.tsx` and `Main.mdx`, because it makes `<main>` the
+  // containing block for any `position: fixed` an app renders
+  // inside it.
   expect(containerComponents).toEqual([
     "Alert",
     "Card",
     "EmptyState",
+    "Main",
     "MediaTile",
   ])
 
@@ -342,7 +351,14 @@ test("the barrel is the only place components are re-exported", async () => {
   // than components anybody stories, and live in `RouterLink/` and
   // `reactRouter/` — outside this count by the `<Name>/<Name>.tsx`
   // rule, exactly as `Overlay/`'s parts are.
-  expect(componentNames.length).toBe(38)
+  // The unified app shell adds four: `Shell`, `Header`, `Rail`,
+  // `Main` — the fleet's largest single duplication, where ten of
+  // twelve UI repos hand-roll the page chrome and three of them
+  // have a file called `AppShell.tsx`: +4 -> 42, on top of the link family's 38. `contentWidth.ts`
+  // and `shellContext.ts` are `Shell`'s members and stay out of
+  // this count by the `<Name>/<Name>.tsx` rule, exactly as
+  // `mediaStatus.ts` does.
+  expect(componentNames.length).toBe(42)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)

package/src/viewport.testHelpers.ts

@@ -0,0 +1,47 @@
+import { page } from "@vitest/browser/context"
+
+/**
+ * Resize the browser and **wait until the page agrees**.
+ *
+ * `page.viewport()` resolves when the driver has asked for the
+ * resize, not when the tester frame has been laid out at the new
+ * size. On the first resize in a file that gap is real: the
+ * assertion runs against the *previous* width, so a
+ * horizontal-scroll test at 390px silently measures a 1440px page
+ * and reports a number nobody can explain. It is a race, so it
+ * fails intermittently — which is the worst possible property for
+ * the one gate that says the shell does not scroll sideways.
+ *
+ * Polling `innerWidth` is the honest wait: it is the same number
+ * the media queries and the layout resolved against, so when it
+ * matches, the thing under test really is at the width the test
+ * claims.
+ */
+export const setViewport = async ({
+  height,
+  width,
+}: {
+  height: number
+  width: number
+}): Promise<void> => {
+  await page.viewport(width, height)
+
+  const deadline = Date.now() + 2000
+
+  while (globalThis.innerWidth !== width) {
+    if (Date.now() > deadline) {
+      throw new Error(
+        `The viewport never reached ${width}px — it is ${globalThis.innerWidth}px. Every width assertion after this point would be measuring the wrong page.`,
+      )
+    }
+
+    await new Promise((resolve) => {
+      globalThis.requestAnimationFrame(resolve)
+    })
+  }
+}
+
+/** A phone in portrait — the width plex-channels scrolls at. */
+export const PHONE = { height: 844, width: 390 }
+
+export const DESKTOP = { height: 900, width: 1440 }