@charcuterie/ui 2.9.0 → 2.10.1

package/src/Header/Header.stories.tsx

@@ -0,0 +1,221 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { Badge } from "../Badge/Badge.tsx"
+import { Button } from "../Button/Button.tsx"
+import {
+  StoryCell,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import { Main } from "../Main/Main.tsx"
+import { Shell } from "../Shell/Shell.tsx"
+import {
+  HeaderSchemeToggle,
+  PageContent,
+  ScrollFiller,
+} from "../shell.storyHelpers.tsx"
+import { Header } from "./Header.tsx"
+
+const meta = {
+  title: "Components/Header",
+  component: Header,
+  parameters: { layout: "fullscreen" },
+  argTypes: {
+    headingLevel: {
+      control: { type: "radio" },
+      options: [1, 2],
+    },
+  },
+  args: {
+    headingLevel: 1,
+    isSticky: true,
+  },
+} satisfies Meta<typeof Header>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * The fleet's header, as one component: the app's name, the
+ * controls that belong to the frame, a real `<header>` landmark,
+ * and a fill that is `surface-raised` rather than the page's own
+ * colour.
+ */
+export const Default: Story = {
+  args: { heading: "Rip Deck" },
+  render: (headerProps) => (
+    <Shell>
+      <Header
+        {...headerProps}
+        actions={<HeaderSchemeToggle />}
+      />
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * The three slots, in the order they render: the heading, the
+ * middle (`children` — a search field, a breadcrumb, a status
+ * pill), and `actions`, which is pushed to the far end.
+ *
+ * Every one is optional. A header with only actions is the
+ * image-viewer's `TitleBar`; a header with only a heading is
+ * board-games'.
+ */
+export const AllStates: Story = {
+  render: (headerProps) => (
+    <StorySection title="Ten repos hand-roll this row. These are the four shapes they hand-roll it into.">
+      <StoryCell align="stretch" label="heading only">
+        <Header {...headerProps} heading="Board Games" />
+      </StoryCell>
+
+      <StoryCell align="stretch" label="heading + actions">
+        <Header
+          {...headerProps}
+          actions={<HeaderSchemeToggle />}
+          heading="Points Market"
+        />
+      </StoryCell>
+
+      <StoryCell
+        align="stretch"
+        label="heading + middle + actions"
+      >
+        <Header
+          {...headerProps}
+          actions={<HeaderSchemeToggle />}
+          heading="Mail Sifter"
+        >
+          <Badge intent="info">412 unread</Badge>
+        </Header>
+      </StoryCell>
+
+      <StoryCell align="stretch" label="actions only">
+        <Header {...headerProps}>
+          <Button appearance="ghost" size="sm">
+            Open
+          </Button>
+        </Header>
+      </StoryCell>
+    </StorySection>
+  ),
+}
+
+/**
+ * **`isSticky` sets `position` and `z-index` together, and that
+ * is the point.** mux-magic's `PageHeader` is documented as a
+ * sticky header and sets only the z-index, so it scrolls away
+ * like any other block — valid CSS, stated intent, no effect.
+ *
+ * Scroll the panel below. The z-index is `--layer-sticky` (100)
+ * from the token scale, so a `Menu` opened from the header — at
+ * `--layer-modal` (400) — still paints over it.
+ */
+export const AllVariants: Story = {
+  render: (headerProps) => (
+    <div className="h-96 overflow-y-auto border border-border-subtle">
+      <Shell>
+        <Header
+          {...headerProps}
+          actions={<HeaderSchemeToggle />}
+          heading="Scroll me"
+        />
+
+        <Main>
+          <PageContent />
+
+          <ScrollFiller />
+        </Main>
+      </Shell>
+    </div>
+  ),
+}
+
+/**
+ * `isSticky={false}` — the header scrolls away with the page, and
+ * takes its z-index with it rather than leaving a stacking
+ * context nobody asked for. board-games' `AppShell.tsx` is this
+ * one: the same structure as mail-sifter's and points-market's,
+ * minus `sticky`.
+ */
+export const NotSticky: Story = {
+  args: { heading: "Board Games", isSticky: false },
+  render: (headerProps) => (
+    <div className="h-96 overflow-y-auto border border-border-subtle">
+      <Shell>
+        <Header
+          {...headerProps}
+          actions={<HeaderSchemeToggle />}
+        />
+
+        <Main>
+          <PageContent />
+
+          <ScrollFiller />
+        </Main>
+      </Shell>
+    </div>
+  ),
+}
+
+/**
+ * The width contract. **The `<header>` is full-bleed and only its
+ * inner row is capped**, which is what stops a constrained header
+ * from looking like a floating island on an ultrawide — and the
+ * cap it uses is `Shell`'s, so the title always sits directly
+ * above the content it names.
+ *
+ * points-market is the app where those two disagree: its header
+ * row is capped at 80rem and its `<main>` is not capped at all.
+ */
+export const Responsive: Story = {
+  render: (headerProps) => (
+    <Shell contentWidth="sm">
+      <Header
+        {...headerProps}
+        actions={<HeaderSchemeToggle />}
+        heading="Narrow by contract"
+      />
+
+      <Main>
+        <PageContent />
+      </Main>
+    </Shell>
+  ),
+}
+
+/**
+ * What an agent reaches for. The header is a landmark, so
+ * `getByRole("banner")` scopes every query inside it — which is
+ * how one of the three "Settings" buttons on a page becomes
+ * addressable.
+ */
+export const Interactive: Story = {
+  args: { heading: "Rip Deck" },
+  render: (headerProps) => (
+    <Shell>
+      <Header
+        {...headerProps}
+        actions={
+          <>
+            <Button appearance="outline" size="sm">
+              Settings
+            </Button>
+
+            <HeaderSchemeToggle />
+          </>
+        }
+      />
+
+      <Main>
+        <Button appearance="outline" size="sm">
+          Settings
+        </Button>
+      </Main>
+    </Shell>
+  ),
+}

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.