@charcuterie/ui 2.9.0 → 2.10.1

package/src/Main/Main.stories.tsx

@@ -0,0 +1,164 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { toStoryChoice } from "../argTypes.storyHelpers.ts"
+import { Card } from "../Card/Card.tsx"
+import { Header } from "../Header/Header.tsx"
+import { Rail } from "../Rail/Rail.tsx"
+import { toMaxInlineSize } from "../Shell/contentWidth.ts"
+import { Shell } from "../Shell/Shell.tsx"
+import {
+  HeaderSchemeToggle,
+  OverflowingContent,
+  PageContent,
+  RailNavigation,
+} from "../shell.storyHelpers.tsx"
+import { Main } from "./Main.tsx"
+
+const CONTENT_WIDTH_OPTIONS = [
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "2xl",
+  "full",
+] as const
+
+const meta = {
+  title: "Components/Main",
+  component: Main,
+  parameters: { layout: "fullscreen" },
+  argTypes: {
+    contentWidth: toStoryChoice(CONTENT_WIDTH_OPTIONS),
+  },
+  args: {},
+} satisfies Meta<typeof Main>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * A page whose grid answers to **the column**, not the window.
+ *
+ * `Main` establishes a container query, so the tile grid below
+ * goes one-up, two-up, three-up as the *content column* changes —
+ * which is a different number from the window's the moment a rail
+ * is open. Open the rail and the same window width gives a
+ * narrower grid, which is the case a `md:` media query cannot
+ * tell apart and the reason the fleet's poster grids look wrong
+ * at intermediate widths.
+ */
+export const Default: Story = {
+  render: (mainProps) => (
+    <Shell>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Library"
+      />
+
+      <Rail label="Sections" landmark="navigation">
+        <RailNavigation />
+      </Rail>
+
+      <Main {...mainProps}>
+        <div className="grid grid-cols-1 gap-4 cq-md:grid-cols-2 cq-xl:grid-cols-3">
+          {[
+            "Adventure Time",
+            "Cowboy Bebop",
+            "Deep Space Nine",
+            "Twin Peaks",
+            "Utopia",
+            "Yellowjackets",
+          ].map((title) => (
+            <Card heading={title} key={title} padding="sm">
+              <p className="text-content-secondary text-sm">
+                4 seasons
+              </p>
+            </Card>
+          ))}
+        </div>
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * The width scale, drawn — because the fleet's real answer to
+ * "how wide is the content column" is eight different numbers.
+ *
+ * Each bar is the actual `max-inline-size` a `contentWidth`
+ * resolves to, taken from `toMaxInlineSize` rather than restated,
+ * so a change to the `screen.*` scale moves the drawing.
+ *
+ * There is one bar per step and **no second `<main>`**: `<main>`
+ * is the page's one main landmark, so a board that rendered six
+ * of them to compare them would be an accessibility violation
+ * demonstrating an accessibility component.
+ */
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-3 p-6">
+      <h3 className="font-semibold text-content-secondary text-sm">
+        `screen.*` steps, plus the `full` escape hatch. `lg`
+        is the default.
+      </h3>
+
+      {CONTENT_WIDTH_OPTIONS.map((step) => (
+        <div className="flex items-center gap-3" key={step}>
+          <span className="w-12 shrink-0 font-mono text-content-muted text-xs">
+            {step}
+          </span>
+
+          <div
+            className="h-6 w-full rounded-md border border-border-subtle bg-surface-raised"
+            style={{ maxInlineSize: toMaxInlineSize(step) }}
+          />
+        </div>
+      ))}
+    </div>
+  ),
+}
+
+/**
+ * The 390px fixture. An unbroken 130-character path and a table
+ * wider than the phone it is on, in one column.
+ *
+ * The path wraps because `Main` sets `overflow-wrap: break-word`;
+ * the table cannot wrap at all and lives in a labelled,
+ * keyboard-reachable scroll container. Neither widens the page,
+ * which is the assertion `Main.test.tsx` makes at a real 390px
+ * viewport.
+ */
+export const Responsive: Story = {
+  render: (mainProps) => (
+    <Shell>
+      <Header heading="Transfers" />
+
+      <Main {...mainProps}>
+        <OverflowingContent />
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * Where the skip link lands. `<main>` carries `tabIndex={-1}` so
+ * activating it moves **focus** and not merely the scroll
+ * position — without that, Safari and Firefox scroll the page and
+ * leave the next Tab back up in the header, which reads as the
+ * skip link not working.
+ */
+export const Interactive: Story = {
+  render: (mainProps) => (
+    <Shell>
+      <Header
+        actions={<HeaderSchemeToggle />}
+        heading="Rip Deck"
+      />
+
+      <Main {...mainProps}>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}

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)`.