@charcuterie/ui 2.8.0 → 2.10.0

package/src/Main/Main.test.tsx

@@ -0,0 +1,167 @@
+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 "./Main.stories.tsx"
+
+const { Default, Interactive, Responsive } =
+  composeStories(stories)
+
+afterAll(async () => {
+  await setViewport(DESKTOP)
+})
+
+test("the content column is capped at the token, not at the window", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(Default)
+
+  const column = canvas.getByRole("main")
+    .firstElementChild as HTMLElement
+
+  // `screen.lg` — 64rem at the root 16px font size. The number is
+  // spelled out here rather than read back from the same
+  // `var()` the component wrote, because a test that asks the
+  // component what it did agrees with it by construction.
+  await expect(
+    globalThis.getComputedStyle(column).maxInlineSize,
+  ).toBe("1024px")
+
+  await expect(
+    column.getBoundingClientRect().width,
+  ).toBeLessThanOrEqual(1024)
+})
+
+/**
+ * The `@container` claim, asserted rather than assumed.
+ *
+ * A grid inside `Main` answers to the **content column**, which is
+ * a different width from the window's the moment a rail is open —
+ * the pair a media query cannot tell apart, and the reason the
+ * fleet's poster grids look wrong at intermediate widths.
+ */
+test("main is the query container its content responds to", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas } = await mountStory(Default)
+
+  const column = canvas.getByRole("main")
+    .firstElementChild as HTMLElement
+
+  // On the column, not on `<main>`. `<main>` is as wide as its
+  // grid track (1184px beside the rail here); the column is
+  // capped at 1024px. A container declared on the wrong one of
+  // those measures a width the content never has.
+  await expect(
+    globalThis.getComputedStyle(column).containerType,
+  ).toBe("inline-size")
+
+  const grid = column.firstElementChild as HTMLElement
+
+  // Two-up, and that is the whole argument. The column's content
+  // box is 976px — past `--cq-md` (32rem), short of `--cq-xl`
+  // (64rem) — while the *window* is 1440px, so a `lg:grid-cols-3`
+  // media query would have drawn three slivers in 976px of space.
+  await expect(
+    globalThis
+      .getComputedStyle(grid)
+      .gridTemplateColumns.split(" "),
+  ).toHaveLength(2)
+})
+
+test("neither an unbroken path nor a wide table widens the page at 390px", async () => {
+  await setViewport(PHONE)
+
+  const { canvas, canvasElement } =
+    await mountStory(Responsive)
+
+  const path = canvas.getByText(
+    /Some-Very-Long-Show-Name-S01E01/,
+  )
+
+  // It wraps rather than overflowing. Without it the element is
+  // one 1,000px line.
+  await expect(
+    path.getBoundingClientRect().width,
+  ).toBeLessThanOrEqual(PHONE.width)
+
+  // `anywhere`, not `break-word` — a drift gate, because the two
+  // are indistinguishable in a screenshot and only `anywhere`
+  // shrinks the **min-content size** a flex or grid item's
+  // automatic minimum resolves against. Under `break-word` the ink
+  // wraps while the intrinsic contribution stays the full token
+  // length, so the string can still force a column open with **no
+  // overflowing element box** for a bounding-rect assertion to
+  // see. That is the failure shape found in plex-channels, and
+  // this line is what stops somebody "tidying" the utility back.
+  const column = canvas.getByRole("main")
+    .firstElementChild as HTMLElement
+
+  await expect(
+    globalThis.getComputedStyle(column).overflowWrap,
+  ).toBe("anywhere")
+
+  const scroller = canvas.getByRole("region", {
+    name: "Transfer log, scrollable",
+  })
+
+  // The table genuinely does not fit — otherwise the page-level
+  // assertion below passes for the wrong reason.
+  await expect(scroller.scrollWidth).toBeGreaterThan(
+    scroller.clientWidth,
+  )
+
+  const { documentElement } = document
+
+  await expect(
+    documentElement.scrollWidth,
+  ).toBeLessThanOrEqual(documentElement.clientWidth)
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * `tabIndex={-1}` is the difference between a skip link that
+ * works and one that only scrolls. It must not put `<main>` in
+ * the tab order, and it must accept focus when sent there.
+ */
+test("main takes focus from a skip link without joining the tab order", async () => {
+  await setViewport(DESKTOP)
+
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const main = canvas.getByRole("main")
+
+  await expect(main).toHaveAttribute("tabindex", "-1")
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Skip to main content",
+      role: "link",
+    }),
+  )
+
+  await expect(main).toHaveFocus()
+
+  // The next Tab leaves `<main>` rather than cycling back into
+  // the header, because the skip link put focus *inside* the page
+  // rather than merely scrolling to it.
+  await userEvent.tab()
+
+  await expect(main).not.toHaveFocus()
+
+  await expect(main.contains(document.activeElement)).toBe(
+    true,
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Main/Main.tsx

@@ -0,0 +1,174 @@
+import { useUniqueId } from "@charcuterie/logic"
+import {
+  type ComponentPropsWithRef,
+  type ReactNode,
+  useContext,
+} from "react"
+
+import {
+  type ContentWidth,
+  DEFAULT_CONTENT_WIDTH,
+  toMaxInlineSize,
+} from "../Shell/contentWidth.ts"
+import { ShellContext } from "../Shell/shellContext.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type MainProps = ComponentPropsWithRef<"main"> & {
+  contentWidth?: ContentWidth
+}
+
+/**
+ * The `<main>` landmark and the content column.
+ *
+ * ## The width is the whole component
+ *
+ * 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. In
+ * > almost all cases, what I really want is something like Rip-Deck
+ * > where the app has a narrower main column but the wrapping grids
+ * > are all full-width in most of these apps only when you have too
+ * > many items."
+ *
+ * That is two requirements, and they pull opposite ways: a
+ * **narrow** column by default, which **widens** when the content
+ * is a grid with enough items to justify it. A fixed `max-w-7xl`
+ * answers neither — it is too wide for the one-column case, which
+ * is the complaint, and it is a hard ceiling on the many-items
+ * case.
+ *
+ * So the cap is a *value*, not a constant, and it arrives from
+ * three places in priority order: this component's own
+ * `contentWidth`, then `Shell`'s (the usual answer, so the header
+ * matches), then `screen.lg`.
+ *
+ * ### How it composes with the adaptive-columns hook
+ *
+ * rip-deck's `useLayoutColumns` — being lifted into this library
+ * separately — decides a column count from the viewport and folds
+ * it into a page cap with `contentMaxWidthRem(columns)`: 1 column →
+ * 56rem, 2 → 72rem, 3 → 106rem. It returns a **number of rem**, and
+ * `ContentWidth` accepts `` `${number}rem` `` for exactly this:
+ *
+ * ```tsx
+ * const { columns } = useLayoutColumns({ cardCount: bays.length })
+ *
+ * <Shell contentWidth={`${contentMaxWidthRem(columns)}rem`}>
+ *   <Header heading="Rip Deck" />
+ *   <Main>
+ *     <BayGrid columns={columns} />
+ *   </Main>
+ * </Shell>
+ * ```
+ *
+ * The seam is deliberately one prop and no hook import: this
+ * package must not depend on a layout hook to lay out a page, and
+ * the hook must not know that a `Shell` exists. Putting the value
+ * on `Shell` rather than on `Main` is what keeps the header's cap
+ * in step with the column's as the count changes.
+ *
+ * ## `@container`, and what `contain: inline-size` costs
+ *
+ * The content column establishes a container query, so an app's
+ * grids inside it respond to **the column's** width rather than
+ * the window's — a poster grid beside an open rail and the same
+ * grid full-bleed are the pair a media query cannot tell apart,
+ * and getting it wrong at intermediate widths is what the fleet's
+ * grids do today.
+ *
+ * `container-type: inline-size` implies `contain: layout style
+ * inline-size`, and both halves have consequences worth stating:
+ *
+ *  - **The element may not be sized by its own contents.** Here
+ *    that is free and in fact wanted: the column has a definite
+ *    inline size from its parent — itself a grid item with
+ *    `minmax(0, 1fr)` — so wide content can no longer widen it,
+ *    which is half of why the page does not scroll sideways.
+ *  - **`contain: layout` makes it a containing block for
+ *    `position: fixed` descendants.** An app rendering a fixed
+ *    element *inside* `Main` gets it positioned against the
+ *    column, not the viewport. Every overlay in this library
+ *    portals to `document.body` and is therefore unaffected
+ *    ([decision](../../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md));
+ *    an app's own fixed chrome belongs in `Shell`, beside `Main`
+ *    rather than in it.
+ *
+ * ## Two more things it does, both one line
+ *
+ * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
+ * merely the reading cursor — without it, Safari and Firefox scroll
+ * to `<main>` and leave the next Tab back in the header.
+ *
+ * `wrap-anywhere` so an unbroken string — a filesystem path, a
+ * hash, a URL — wraps instead of widening the page.
+ *
+ * **`anywhere`, not `break-word`, and the difference is the whole
+ * point.** Both break a long word onto the next line, so they look
+ * identical in a screenshot. Only `anywhere` also shrinks the
+ * element's **min-content size** — which is what a flex or grid
+ * item's automatic minimum resolves against, and therefore what
+ * decides whether the string can push its own column wider. With
+ * `break-word` the ink wraps while the intrinsic contribution
+ * stays the full length of the token, so the layout above it can
+ * still be forced open. This is the second of the two overflow
+ * sources found in plex-channels, and the nastier one: it produces
+ * **no overflowing element box at all**, so every
+ * `getBoundingClientRect()` in a test reads clean while the page
+ * scrolls sideways.
+ *
+ * It is the cheap half of the horizontal-scroll fix; the other
+ * halves are `minmax(0, 1fr)` and `overflow-x: clip` in `Shell`. A
+ * `<table>` is the one thing none of them can save: tables do not
+ * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
+ * `Main.mdx` shows.
+ */
+export const Main = ({
+  children,
+  className,
+  contentWidth,
+  id,
+  ...mainProps
+}: MainProps): ReactNode => {
+  const shell = useContext(ShellContext)
+
+  // Always called, never conditionally: a `Main` outside a `Shell`
+  // still needs an id an app can point its own skip link at.
+  const fallbackId = useUniqueId()
+
+  const maxInlineSize = toMaxInlineSize(
+    contentWidth ??
+      shell?.contentWidth ??
+      DEFAULT_CONTENT_WIDTH,
+  )
+
+  return (
+    <main
+      {...mainProps}
+      className={toClassName(
+        "col-start-1 row-start-3 min-w-0 md:col-start-2 md:row-start-2",
+        className,
+      )}
+      id={id ?? shell?.mainId ?? fallbackId}
+      tabIndex={-1}
+    >
+      {/*
+        `@container` is on the **capped column**, not on `<main>`,
+        and the difference is not cosmetic. `<main>` is as wide as
+        its grid track — 1184px beside an open rail on a 1440px
+        window — while the column inside it is capped at
+        `contentWidth`. Declaring the container on `<main>` makes
+        every `cq-*` inside answer to a width the content never
+        has: a grid would go three-up at `--cq-xl` while sitting in
+        976px of space. The container has to be the box the content
+        is actually laid out in.
+      */}
+      <div
+        className="@container mx-auto flex w-full min-w-0 flex-col gap-6 wrap-anywhere px-4 py-6 sm:px-6"
+        style={{ maxInlineSize }}
+      >
+        {children}
+      </div>
+    </main>
+  )
+}

package/src/Rail/Rail.mdx

@@ -0,0 +1,75 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as RailStories from "./Rail.stories";
+
+<Meta of={RailStories} />
+
+# Rail
+
+A side column — the app's sections, a filter panel, the selected job's detail. `side` places
+it, `landmark` decides what it is, and `label` is required.
+
+<Canvas of={RailStories.Default} />
+
+## Props
+
+<Controls />
+
+## `label` is required, and that is not pedantry
+
+<Canvas of={RailStories.AllVariants} />
+
+Two rails in one page are two landmarks of the same type. Unnamed, a screen reader
+announces "complementary" twice with no way to tell them apart, axe files
+`landmark-unique`, and `getByRole("navigation")` returns two matches — which is worse for an
+agent than the rail not existing, because it picks one at random.
+
+Named, the rail becomes the scope: `getByRole("navigation", { name: "Sections" })` is what
+distinguishes its "Settings" link from the header's "Settings" button. Same trick `Card`'s
+heading plays for one of nine identical "Start" buttons on a bay tower.
+
+`landmark="navigation"` renders `<nav>`; the default `"complementary"` renders `<aside>`.
+Pick the one the content actually is — a filter panel is not navigation.
+
+## It collapses without duplicating itself
+
+<Canvas of={RailStories.Responsive} />
+
+Below `md` (48rem, which is `screen.md`) the shell is one column and the rail becomes a
+horizontally-scrolling strip: above the content for `side="start"`, below it for
+`side="end"`. Above `md` it is a fixed-width column in the grid.
+
+**The same element, restyled.** The fleet's habit is to render the whole thing twice behind
+`hidden` and `lg:hidden` — mux-magic's `PageHeader` across two ~55-line blocks,
+mail-sifter's `TriageQueue` again. The cost is not bytes: every control is in the DOM
+**twice at every viewport**, so tests have to be defensively scoped with `within(toolbar)`,
+any agent driving the page sees phantom controls it cannot click, and the two copies drift
+apart. `Rail.test.tsx` counts the links at 390px and at 1440px and gets twelve both times.
+
+A media query is enough 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.
+
+The `md` breakpoint and `screen.md` agree by construction: Tailwind v4's default
+`--breakpoint-*` scale and this repo's `screen.*` carry the same five values.
+
+## The strip scrolls itself
+
+Twelve sections on a phone is what makes a naive rail widen the page. `overflow-x-auto`
+keeps the overflow inside an element that scrolls, and `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, so one long unbroken string otherwise pushes the layout out of the viewport.
+
+A scrolling region has to be keyboard-reachable. It is here because it is a landmark full of
+links, which is what axe's `scrollable-region-focusable` accepts — **a rail of plain
+non-focusable text would not be**, and that is the honest limit of the pattern. Content
+like that belongs in `Main`.
+
+<Canvas of={RailStories.Interactive} />
+
+## Width
+
+`md:w-64` (16rem) by default, which is what the fleet's nav columns settle on. Override it
+with `className` — the rail's track is `auto`, so it takes whatever definite width the
+element is given, and the content column absorbs the difference through its `minmax(0, 1fr)`.

package/src/Rail/Rail.stories.tsx

@@ -0,0 +1,177 @@
+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 { Shell } from "../Shell/Shell.tsx"
+import {
+  HeaderSchemeToggle,
+  PageContent,
+  RailDetail,
+  RailNavigation,
+} from "../shell.storyHelpers.tsx"
+import { Rail } from "./Rail.tsx"
+
+const meta = {
+  title: "Components/Rail",
+  component: Rail,
+  parameters: { layout: "fullscreen" },
+  argTypes: {
+    landmark: toStoryChoice([
+      "complementary",
+      "navigation",
+    ] as const),
+    side: toStoryChoice(["start", "end"] as const),
+  },
+  args: {
+    landmark: "complementary",
+    side: "start",
+  },
+} satisfies Meta<typeof Rail>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The sections column. `landmark="navigation"` because that is
+ * what it is, and `label` because a rail nobody can name is a
+ * rail an agent cannot scope to — `getByRole("navigation", {
+ * name: "Sections" })` is what distinguishes its "Settings" link
+ * from the header's "Settings" button.
+ */
+export const Default: Story = {
+  args: {
+    label: "Sections",
+    landmark: "navigation",
+  },
+  render: (railProps) => (
+    <Shell>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Comic Ingest"
+      />
+
+      <Rail {...railProps}>
+        <RailNavigation />
+      </Rail>
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * Both sides at once, and both kinds of landmark: a `<nav>` at
+ * the start for the app's sections, an `<aside>` at the end for
+ * the selected thing's detail.
+ *
+ * Two rails is where the required `label` stops being pedantry.
+ * Two unnamed landmarks of the same type are the same announcement
+ * twice to a screen reader and two identical matches to an agent,
+ * which is worse than one of them not existing.
+ */
+export const AllVariants: Story = {
+  args: { label: "Sections", landmark: "navigation" },
+  render: (railProps) => (
+    <Shell>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Rip Deck"
+      />
+
+      <Rail {...railProps}>
+        <RailNavigation />
+      </Rail>
+
+      <Main>
+        <PageContent />
+      </Main>
+
+      <Rail label="Job detail" side="end">
+        <RailDetail />
+      </Rail>
+    </Shell>
+  ),
+}
+
+/**
+ * **The collapse, and what it is not.** Narrow the window past
+ * 48rem (`screen.md`): the rail stops being a column and becomes
+ * a horizontally-scrolling strip above the content.
+ *
+ * It is the **same element**, restyled. The fleet's habit is to
+ * render the whole thing twice behind `hidden` / `lg:hidden` —
+ * mux-magic's `PageHeader` across two ~55-line blocks,
+ * mail-sifter's `TriageQueue` again — which puts every control in
+ * the DOM twice at every viewport. Count the links here at any
+ * width and there are four.
+ *
+ * The strip scrolls itself rather than widening the page, which
+ * is why twelve sections on a phone still leave
+ * `document.documentElement.scrollWidth` where it was.
+ */
+export const Responsive: Story = {
+  args: { label: "Sections", landmark: "navigation" },
+  render: (railProps) => (
+    <Shell>
+      <Header heading="Twelve sections" />
+
+      <Rail {...railProps}>
+        {[
+          "Queue",
+          "Library",
+          "Transfers",
+          "Settings",
+          "Devices",
+          "Schedules",
+          "Notifications",
+          "Integrations",
+          "Storage",
+          "Diagnostics",
+          "Backups",
+          "About",
+        ].map((section) => (
+          <a
+            className="whitespace-nowrap 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>
+        ))}
+      </Rail>
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * What an agent drives. The rail is a named landmark, so its
+ * links are reachable *through* it — the same trick `Card`'s
+ * heading plays for a bay's "Start" button.
+ */
+export const Interactive: Story = {
+  args: { label: "Sections", landmark: "navigation" },
+  render: (railProps) => (
+    <Shell>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Rip Deck"
+      />
+
+      <Rail {...railProps}>
+        <RailNavigation />
+      </Rail>
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}