@charcuterie/ui 2.8.0 → 2.10.0

package/src/Header/Header.test.tsx

@@ -0,0 +1,122 @@
+import { composeStories } from "@storybook/react"
+import { expect, within } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Header.stories.tsx"
+
+const {
+  AllStates,
+  AllVariants,
+  Interactive,
+  NotSticky,
+  Responsive,
+} = composeStories(stories)
+
+const getHeader = (canvasElement: HTMLElement) => {
+  const header = canvasElement.querySelector("header")
+
+  if (!header) {
+    throw new Error("The story rendered no <header>.")
+  }
+
+  return header
+}
+
+/**
+ * **The mux-magic bug, as a red/green test.**
+ *
+ * `PageHeader.tsx:173` sets a z-index and calls itself sticky. It
+ * never sets `position: sticky`, so the header scrolls away and
+ * the z-index has nothing to stack against — valid CSS, a comment
+ * stating the intent, and no way to see it without scrolling a
+ * running app.
+ *
+ * Both halves are asserted together because it is the *pairing*
+ * that was wrong, and either half alone passes on the broken
+ * implementation.
+ */
+test("isSticky sets position and z-index together", async () => {
+  const { canvasElement } = await mountStory(AllVariants)
+
+  const styles = globalThis.getComputedStyle(
+    getHeader(canvasElement),
+  )
+
+  await expect(styles.position).toBe("sticky")
+
+  // `--layer-sticky`, not a hand-picked number. The fleet's
+  // headers currently sit at z-40, z-50, z-10 and z-[100] with no
+  // ordering guarantee between them and anything else.
+  await expect(styles.zIndex).toBe("100")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("isSticky={false} sets neither", async () => {
+  const { canvasElement } = await mountStory(NotSticky)
+
+  const styles = globalThis.getComputedStyle(
+    getHeader(canvasElement),
+  )
+
+  await expect(styles.position).toBe("static")
+
+  // Not merely "some other number": a `z-index` on a static
+  // element is inert, and leaving one behind is how a stacking
+  // context outlives the thing that needed it.
+  await expect(styles.zIndex).toBe("auto")
+})
+
+/**
+ * The reason a header is a landmark at all. Two "Settings"
+ * buttons on the page, and an agent can still say which one it
+ * means.
+ */
+test("the header is a banner an agent can scope queries to", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const banner = expectAgentDrivable(canvas, {
+    role: "banner",
+  })
+
+  // Unscoped, this is ambiguous on purpose — the story renders one
+  // in the header and one in the page.
+  await expect(
+    canvas.getAllByRole("button", { name: "Settings" }),
+  ).toHaveLength(2)
+
+  expectAgentDrivable(within(banner), {
+    name: "Settings",
+    role: "button",
+  })
+
+  // And the fleet's scheme control lives in the actions slot,
+  // which is the composition `Shell` promises.
+  expectAgentDrivable(within(banner), {
+    name: /colour scheme/i,
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("the heading is the page's h1 by default", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Responsive)
+
+  await expect(
+    canvas.getByRole("heading", { level: 1 }),
+  ).toHaveTextContent("Narrow by contract")
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("every slot arrangement the fleet ships is clean under axe", async () => {
+  const { canvasElement } = await mountStory(AllStates)
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Header/Header.tsx

@@ -0,0 +1,118 @@
+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 HeaderProps =
+  ComponentPropsWithRef<"header"> & {
+    actions?: ReactNode
+    contentWidth?: ContentWidth
+    heading?: string
+    headingLevel?: 1 | 2
+    isSticky?: boolean
+  }
+
+/**
+ * The page header — the `<header>` landmark, the app's name, and
+ * the controls that belong to the frame rather than to the page.
+ *
+ * **`isSticky` defaults to true, and it sets `position` as well as
+ * `z-index`.** That pairing is the whole point. mux-magic's
+ * `PageHeader` is documented as a sticky header and sets only
+ * `z-index` (`PageHeader.tsx:173`) — it is a flex-column shell that
+ * scrolls away like any other block, and the z-index it carries
+ * has nothing to stack against. The bug is invisible: the CSS is
+ * valid, the intent is stated in a comment, and nobody scrolls a
+ * component in a review. Here the two cannot come apart, because
+ * one boolean writes both.
+ *
+ * The z-index is `--layer-sticky` from the token scale, never a
+ * hand-picked number. The fleet's headers currently sit at `z-40`
+ * (mail-sifter, points-market), `z-50` (rip-deck), `z-10`
+ * (spoolbuddy) and `z-[100]` (mux-magic), with no ordering
+ * guarantee between a header and anything else — which is exactly
+ * what the scale exists to settle: `sticky` (100) is below
+ * `dropdown` (200), `modal` (400) and `toast` (500), so a menu
+ * opened *from* the header paints over it.
+ *
+ * ## The width comes from `Shell`
+ *
+ * The `<header>` itself is full-bleed — the border and the
+ * translucent fill run edge to edge — and only its **inner row** is
+ * capped, which is what makes a constrained header look right on an
+ * ultrawide. That cap is `Shell`'s `contentWidth`, not a second
+ * opinion: see `shellContext.ts` for the shipped app whose header
+ * and `<main>` disagree by 80rem.
+ *
+ * ## No invented colours
+ *
+ * `bg-surface-raised/85` + `backdrop-blur-md` + `border-border-subtle`.
+ * The fleet's copy of this line is `bg-surface-base/90`, which puts
+ * the header at the *same* colour as the page behind it and leans
+ * entirely on the blur to separate them — so it vanishes against a
+ * page that is not scrolled. `raised` means *more separated from
+ * base*, which is the role this element actually wants.
+ */
+export const Header = ({
+  actions,
+  children,
+  className,
+  contentWidth,
+  heading,
+  headingLevel = 1,
+  isSticky = true,
+  ...headerProps
+}: HeaderProps): ReactNode => {
+  const shell = useContext(ShellContext)
+
+  const Heading = `h${headingLevel}` as const
+
+  const maxInlineSize = toMaxInlineSize(
+    contentWidth ??
+      shell?.contentWidth ??
+      DEFAULT_CONTENT_WIDTH,
+  )
+
+  return (
+    <header
+      {...headerProps}
+      className={toClassName(
+        "col-span-full row-start-1 border-border-subtle border-b bg-surface-raised/85 backdrop-blur-md",
+        isSticky && "sticky top-0 z-[var(--layer-sticky)]",
+        className,
+      )}
+    >
+      <div
+        className="mx-auto flex w-full min-w-0 flex-wrap items-center gap-3 px-4 py-3 sm:px-6"
+        style={{ maxInlineSize }}
+      >
+        {heading ? (
+          <Heading className="min-w-0 truncate font-semibold text-lg leading-tight">
+            {heading}
+          </Heading>
+        ) : null}
+
+        {children ? (
+          <div className="flex min-w-0 flex-1 items-center gap-2">
+            {children}
+          </div>
+        ) : null}
+
+        {actions ? (
+          <div className="ms-auto flex shrink-0 items-center gap-2">
+            {actions}
+          </div>
+        ) : null}
+      </div>
+    </header>
+  )
+}

package/src/Main/Main.mdx

@@ -0,0 +1,149 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MainStories from "./Main.stories";
+
+<Meta of={MainStories} />
+
+# Main
+
+The `<main>` landmark and the content column. **Its width is the crux of the whole shell.**
+
+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."
+
+<Canvas of={MainStories.Default} />
+
+## Props
+
+<Controls />
+
+## The width is a value, not a constant
+
+The cap is the least standardized number in the fleet: `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.
+
+`contentWidth` accepts three shapes, and the third is why this is a value rather than a
+constant:
+
+| Shape | Example | For |
+| --- | --- | --- |
+| A `screen.*` step | `contentWidth="lg"` | The ordinary page. `lg` (64rem) is the default. |
+| `"full"` | `contentWidth="full"` | A wall of tiles that genuinely wants the window. |
+| A `rem` literal | ``contentWidth={`${rem}rem`}`` | A cap computed at runtime. |
+
+<Canvas of={MainStories.AllVariants} />
+
+**`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 the
+container-query scale to `--cq-*`. The cap is an inline `max-inline-size` reading
+`var(--screen-*)`, so it stays a token instead of becoming a literal.
+
+## How it composes with the adaptive-columns hook
+
+rip-deck's `useLayoutColumns` — lifted into this library separately — decides a column count
+from the viewport, then folds it into a page cap with `contentMaxWidthRem(columns)`: one
+column → 56rem, two → 72rem, three → 106rem. It returns a **number of rem**, which is
+exactly the third shape above:
+
+```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 one prop and no import in either direction: this package does not depend on a
+layout hook to lay out a page, and the hook does not know a `Shell` exists. The value goes
+on **`Shell`** rather than on `Main` so the header's cap stays in step with the column's as
+the count changes — which is the same reason the two share one `contentWidth` at all.
+
+## `@container` is on the column, not on `<main>`
+
+A grid inside the content column answers to **the column's** width. A poster grid beside an
+open rail and the same grid full-bleed are the pair a media query cannot tell apart, and
+getting that wrong at intermediate widths is what the fleet's grids do today.
+
+The container is declared on the capped inner column rather than on `<main>` deliberately.
+`<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`. A container on `<main>` measures a
+width the content never has: a grid would go three-up at `--cq-xl` while sitting in 976px
+of space.
+
+**`container-type: inline-size` implies `contain: layout style inline-size`**, and both
+halves have consequences:
+
+- **The element may not be sized by its own contents.** Here that is wanted — the column
+  has a definite inline size from its parent, 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 fixed chrome *inside* `Main` gets it positioned against the column rather
+  than the viewport. Every overlay in this library portals to `document.body` and is
+  unaffected; an app's own fixed chrome belongs in `Shell`, beside `Main`.
+
+## Two kinds of overflow, two different answers
+
+<Canvas of={MainStories.Responsive} />
+
+`wrap-anywhere` on the column handles content that *can* wrap and does not — a filesystem
+path, a hash, a URL, none of which contain a break opportunity.
+
+**`anywhere`, not `break-word`.** Both break the long word onto the next line, so the two are
+indistinguishable 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 force its own column wider. Under
+`break-word` the ink wraps while the intrinsic contribution stays the full token length, so
+the page can still scroll sideways with **no overflowing element box anywhere in the tree**
+for a `getBoundingClientRect()` assertion to catch. That is why the gate asserts
+`document.documentElement.scrollWidth`, and why `Main.test.tsx` pins the computed value.
+
+That is the cheap half of the horizontal-scroll fix; the other halves are `minmax(0, 1fr)`
+and `overflow-x: clip` on `Shell`.
+
+A `<table>` is the one thing neither can save. Table columns have min-content widths that no
+`overflow-wrap` reaches, so a wide table goes in a scroll container:
+
+```tsx
+<section
+  aria-label="Transfer log, scrollable"
+  className="charcuterie-scrollbar overflow-x-auto rounded-lg border border-border-subtle"
+>
+  <table>…</table>
+</section>
+```
+
+Because that container scrolls, the columns off screen have to be reachable **without a
+mouse** — axe's `scrollable-region-focusable`, which is WCAG 2.1.1. There are two ways to
+satisfy it and the choice is not a matter of taste:
+
+1. **The content contains something focusable.** A row that ends in a link is enough:
+   tabbing to it scrolls the container into view. This is the case above and the one the
+   `Responsive` story ships, because a log row with no way into the record is a poor table
+   anyway.
+2. **`tabIndex={0}` on the container.** The answer for a table of pure text, and the one
+   most guidance quotes. Note that Biome's `noNoninteractiveTabindex` rejects it on a
+   non-interactive element and its **unsafe fix removes the attribute before a suppression
+   is evaluated** — so `yarn lint` will silently turn a compliant table into a
+   keyboard-trap. Prefer (1) where the data allows it.
+
+`aria-label` on the container is worth it either way: it turns the scroller into a named
+region, so the table is announced as a thing rather than as loose content.
+
+## `tabIndex={-1}`
+
+<Canvas of={MainStories.Interactive} />
+
+`<main>` accepts focus so `Shell`'s skip link moves **focus** and not merely the scroll
+position. Without it, Safari and Firefox scroll to `<main>` and leave the next Tab back up
+in the header — which looks exactly like a skip link that works.

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