@charcuterie/ui 2.8.0 → 2.10.0

package/src/mountStory.testHelpers.ts

@@ -62,6 +62,67 @@ type MountableStory = {
  */
 const mountedCanvases: HTMLElement[] = []
 
+/**
+ * One frame past the mount, so post-mount effects have applied
+ * before anything reads the DOM.
+ *
+ * `storybook-addon-pseudo-states` applies its forced
+ * `:hover`/`:focus`/`:active` classes **a tick after render**, not
+ * during it — `vrtCapture.mjs` documents the same window and closes
+ * it with a settle, after "a real flake seen on `*--all-states`
+ * stories".
+ *
+ * This suite has the identical window and never closed it, and the
+ * consequence is worse here than a pixel diff: the a11y addon's
+ * `afterEach` runs axe the moment `run()` resolves, so a story
+ * whose forced state lands late is audited **un-forced**, and one
+ * whose state lands early is audited **hovered**. That is a
+ * contrast check reading `intent-accent-solid` on one run and
+ * `intent-accent-solid-hover` on the next — which is precisely the
+ * shape of `ButtonLink`'s intermittent `color-contrast` failure in
+ * CI, reported against `#6A64F0`, the daylight `solidHover`.
+ *
+ * Two frames rather than a fixed delay: React flushes effects and
+ * the addon applies classes within a frame, so this is a barrier
+ * tied to the browser's own scheduling instead of a millisecond
+ * count guessed against one machine. `vrtCapture` can afford its
+ * 400ms because it takes ~700 shots; this runs before every one of
+ * 222 tests.
+ */
+/**
+ * Captured at module load, **before any test can replace it**.
+ *
+ * `Toast.test.tsx` stubs `requestAnimationFrame` and *holds* the
+ * callbacks, deliberately, to prove that a dismiss arriving during
+ * the enter frame is not undone by it. A settle that called the
+ * live `globalThis.requestAnimationFrame` would hand its own
+ * continuation to that stub and never be released — which is
+ * exactly what happened: three Toast tests went from passing to a
+ * flat 15s timeout.
+ *
+ * Binding the native one keeps a true frame barrier while staying
+ * immune to a stub, and it does not disturb the test doing the
+ * stubbing: the component's frames still go to its stub, only this
+ * helper's do not.
+ */
+const requestNativeFrame =
+  globalThis.requestAnimationFrame?.bind(globalThis)
+
+const settlePostMountEffects = () =>
+  new Promise<void>((resolve) => {
+    if (!requestNativeFrame) {
+      globalThis.setTimeout(resolve, 0)
+
+      return
+    }
+
+    requestNativeFrame(() => {
+      requestNativeFrame(() => {
+        resolve()
+      })
+    })
+  })
+
 export const mountStory = async (
   story: MountableStory,
 ): Promise<{
@@ -87,6 +148,8 @@ export const mountStory = async (
 
   await story.run({ canvasElement })
 
+  await settlePostMountEffects()
+
   return {
     body: within(document.body),
     canvas: within(canvasElement),

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 }