@charcuterie/ui 0.1.0 → 0.2.0

package/src/LogViewer/LogViewer.stories.tsx

@@ -0,0 +1,135 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import {
+  StoryCell,
+  StoryGrid,
+} from "../board.storyHelpers.tsx"
+import type { LogLine } from "./LogViewer.tsx"
+import { LogViewer } from "./LogViewer.tsx"
+
+const RIP_LINES: LogLine[] = [
+  {
+    key: "1",
+    text: "14:02:09 Opening /dev/sr0",
+  },
+  {
+    key: "2",
+    text: "14:02:11 AACS handshake complete, reading…",
+  },
+  {
+    intent: "warning",
+    key: "3",
+    text: "14:02:44 Title 4: 2 read errors, retrying",
+  },
+  {
+    key: "4",
+    text: "14:03:02 Title 4: recovered",
+  },
+  {
+    intent: "success",
+    key: "5",
+    text: "14:31:57 9 titles written to /mnt/rips",
+  },
+]
+
+/**
+ * Long enough to overflow the pane, which is the only way to story
+ * the behaviour that matters here.
+ */
+const LONG_LINES: LogLine[] = Array.from(
+  { length: 60 },
+  (_unused, index) => ({
+    key: String(index),
+    text: `14:${String(index).padStart(2, "0")}:00 Reading sector ${index * 2048}`,
+  }),
+)
+
+const meta = {
+  title: "Components/LogViewer",
+  component: LogViewer,
+  parameters: { layout: "padded" },
+  args: {
+    isAnnounced: false,
+    label: "Bay 3 rip log",
+    lines: RIP_LINES,
+    maxLines: 500,
+  },
+} satisfies Meta<typeof LogViewer>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: { label: "Bay 3 rip log", lines: RIP_LINES },
+}
+
+export const AllVariants: Story = {
+  args: { label: "Bay 3 rip log", lines: RIP_LINES },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="short">
+        <LogViewer
+          label="Bay 1 rip log"
+          lines={RIP_LINES}
+        />
+      </StoryCell>
+
+      <StoryCell label="overflowing">
+        <LogViewer
+          label="Bay 2 rip log"
+          lines={LONG_LINES}
+        />
+      </StoryCell>
+
+      <StoryCell label="capped at 10 lines">
+        <LogViewer
+          label="Bay 4 rip log"
+          lines={LONG_LINES}
+          maxLines={10}
+        />
+      </StoryCell>
+
+      <StoryCell label="announced">
+        <LogViewer
+          isAnnounced
+          label="Bay 5 result"
+          lines={RIP_LINES}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Empty is a state, not a blank box. mux-magic's pane says
+ * "Waiting for log lines…" and rip-deck's says nothing at all,
+ * which reads as a broken subscription.
+ */
+export const AllStates: Story = {
+  args: { label: "Bay 3 rip log", lines: RIP_LINES },
+  render: () => (
+    <StoryGrid columns={2}>
+      <StoryCell label="empty">
+        <LogViewer label="Bay 6 rip log" lines={[]} />
+      </StoryCell>
+
+      <StoryCell label="with intents">
+        <LogViewer
+          label="Bay 7 rip log"
+          lines={RIP_LINES}
+        />
+      </StoryCell>
+    </StoryGrid>
+  ),
+}
+
+/**
+ * Scroll the tall pane up and the **Jump to latest** button
+ * appears; scroll back to the bottom and it goes away. Following is
+ * pinned to the user's own position, which is the difference between
+ * a log that follows and one that fights you.
+ */
+export const Interactive: Story = {
+  args: { label: "Bay 8 rip log", lines: LONG_LINES },
+}

package/src/LogViewer/LogViewer.test.tsx

@@ -0,0 +1,173 @@
+import { composeStories } from "@storybook/react"
+import { expect, waitFor } 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 "./LogViewer.stories.tsx"
+
+const { AllStates, AllVariants, Default, Interactive } =
+  composeStories(stories)
+
+test("the pane is named, and is a log", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  // Found by its name, not by a `data-log-id`. mux-magic's pane
+  // carries one of those — a `data-testid` under a different name,
+  // which this package's `sourceRules.test.ts` bans as a practice
+  // rather than as a spelling.
+  const pane = expectAgentDrivable(canvas, {
+    name: "Bay 3 rip log",
+    role: "log",
+  })
+
+  await expect(pane).toHaveTextContent(
+    "AACS handshake complete",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+/**
+ * The fix for mux-magic's defect, asserted as the behaviour rather
+ * than as the precondition. Its auto-scroll runs in an effect with
+ * **empty deps** — once, on mount, when the pane is empty and
+ * `scrollHeight` is `clientHeight` — so every line after it arrives
+ * below the fold.
+ */
+test("a full pane is scrolled to the bottom", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const pane = expectAgentDrivable(canvas, {
+    name: "Bay 8 rip log",
+    role: "log",
+  })
+
+  // The precondition — that there *is* something to scroll. On its
+  // own this proves nothing, which is the lesson `Tabs` learned the
+  // expensive way from `scrollWidth > clientWidth`.
+  await expect(pane.scrollHeight).toBeGreaterThan(
+    pane.clientHeight,
+  )
+
+  // And the behaviour: it is actually at the end.
+  await waitFor(() => {
+    expect(
+      pane.scrollHeight -
+        pane.scrollTop -
+        pane.clientHeight,
+    ).toBeLessThan(4)
+  })
+})
+
+/**
+ * Following is pinned to the user's own position. Scrolling back to
+ * read the line that mentioned an error must not be undone twice a
+ * second — which is what the naive fix (scroll to bottom on every
+ * render) does.
+ */
+test("scrolling away stops the follow and offers a way back", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const pane = expectAgentDrivable(canvas, {
+    name: "Bay 8 rip log",
+    role: "log",
+  })
+
+  await expect(
+    canvas.queryAllByRole("button", {
+      name: "Jump to latest",
+    }),
+  ).toHaveLength(0)
+
+  pane.scrollTop = 0
+
+  pane.dispatchEvent(new Event("scroll", { bubbles: true }))
+
+  const jump = await waitFor(() =>
+    expectAgentDrivable(canvas, {
+      name: "Jump to latest",
+      role: "button",
+    }),
+  )
+
+  jump.click()
+
+  await waitFor(() => {
+    expect(
+      pane.scrollHeight -
+        pane.scrollTop -
+        pane.clientHeight,
+    ).toBeLessThan(4)
+  })
+})
+
+/**
+ * A live log emitting a line every 300 ms is a screen reader that
+ * cannot be interrupted. `role="log"` is correct; `aria-live` is off
+ * unless the lines *are* the outcome.
+ */
+test("a log does not announce itself unless asked", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Bay 1 rip log",
+      role: "log",
+    }),
+  ).toHaveAttribute("aria-live", "off")
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Bay 5 result",
+      role: "log",
+    }),
+  ).toHaveAttribute("aria-live", "polite")
+})
+
+test("maxLines drops the oldest lines from the DOM", async () => {
+  const { canvas } = await mountStory(AllVariants)
+
+  const capped = expectAgentDrivable(canvas, {
+    name: "Bay 4 rip log",
+    role: "log",
+  })
+
+  // A rip emits a line every few hundred milliseconds for an hour,
+  // and the browser keeps every node.
+  await expect(capped.querySelectorAll("p")).toHaveLength(
+    10,
+  )
+
+  // The *last* ten, not the first — a log you have to scroll up
+  // through to reach the newest line is backwards.
+  await expect(capped).toHaveTextContent(
+    "Reading sector 120832",
+  )
+})
+
+test("a scrollable pane is reachable by keyboard", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  // Chrome made scrollers focusable automatically in 2024; Firefox
+  // and Safari have not. Without it a keyboard user can see the pane
+  // and cannot scroll it.
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Bay 7 rip log",
+      role: "log",
+    }).tabIndex,
+  ).toBe(0)
+
+  await expect(
+    expectAgentDrivable(canvas, {
+      name: "Bay 6 rip log",
+      role: "log",
+    }),
+  ).toHaveTextContent("Waiting for output…")
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/LogViewer/LogViewer.tsx

@@ -0,0 +1,195 @@
+import type { IntentName } from "@charcuterie/tokens"
+import type { ReactNode } from "react"
+import { useEffect, useRef, useState } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { INTENT_CONTENT_CLASS } from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+
+export type LogLine = {
+  intent?: IntentName
+  key: string
+  text: string
+}
+
+export type LogViewerProps = {
+  className?: string
+  /**
+   * Announce new lines to a screen reader. **Off by default**, and
+   * that is a considered choice rather than an oversight — see
+   * below.
+   */
+  isAnnounced?: boolean
+  /** The pane's accessible name. Required. */
+  label: string
+  lines: LogLine[]
+  /**
+   * Oldest lines past this are dropped from the DOM. A rip in
+   * progress emits a line every few hundred milliseconds for an
+   * hour, and the browser keeps every node.
+   */
+  maxLines?: number
+}
+
+/**
+ * Three repos render a scrolling log pane —
+ * mux-magic's `JobLogsDisclosure` and `StepLogs`, rip-deck's
+ * `LogModal` — and between them they have four defects that this
+ * component exists to not have.
+ *
+ * ### 1. The one that follows nothing
+ *
+ * ```tsx
+ * useEffect(() => {
+ *   const pane = paneRef.current
+ *   if (pane) pane.scrollTop = pane.scrollHeight
+ * }, [])          // ← empty deps
+ * ```
+ *
+ * That is mux-magic's auto-scroll, and it runs **once**, on mount,
+ * when the pane is empty and `scrollHeight` is `clientHeight`. Every
+ * line after it arrives below the fold. It reads as correct, it is
+ * the shape everyone writes, and the log simply never follows.
+ *
+ * ### 2. Following that cannot be escaped
+ *
+ * The naive fix — scroll to the bottom on every render — is worse:
+ * a user scrolling back to read the line that mentioned an error is
+ * yanked to the end twice a second. Following has to be *pinned to
+ * the user's own position*, which is what `isFollowing` below is: it
+ * turns off the moment the user scrolls away and back on when they
+ * return to the bottom, and there is a button for when they do not
+ * want to scroll all that way.
+ *
+ * ### 3. `data-log-id`
+ *
+ * mux-magic's pane carries one. It is a `data-testid` under a
+ * different name — a handle only the test suite can see — and this
+ * package's `sourceRules.test.ts` bans the practice rather than the
+ * spelling. The pane here is found by its `label`, the same query
+ * Playwright makes.
+ *
+ * ### 4. Announcing an hour of build output
+ *
+ * `role="log"` is the correct role and `aria-live` is off unless
+ * asked for. A live log pane emitting a line every 300 ms is a
+ * screen reader that cannot be interrupted and a user who cannot
+ * read anything else on the page — the accessible answer for a
+ * long-running job is a `LiveStatusIndicator` announcing *state*
+ * and a log that is there to be read when wanted. `isAnnounced`
+ * exists for the short case: a five-line result panel where the
+ * lines *are* the outcome.
+ *
+ * ### Not every boolean is a state kind
+ *
+ * `isFollowing` is `useState`, not `useVisibility`, and this is the
+ * first component in the library to say so out loud. The kinds in
+ * `@charcuterie/logic` earn their keep when state is **registered**
+ * (members join a group), **composed** (focus and selection
+ * disagreeing), or **shared** (a trigger and a panel at opposite
+ * ends of a tree). None of that is true here: one component reads
+ * one boolean it wrote itself. Reaching for `useVisibility` because
+ * it is also a boolean would make `isVisible` mean "is following",
+ * which is how a state layer stops meaning anything.
+ */
+export const LogViewer = ({
+  className,
+  isAnnounced = false,
+  label,
+  lines,
+  maxLines = 500,
+}: LogViewerProps): ReactNode => {
+  const paneRef = useRef<HTMLDivElement>(null)
+
+  const [isFollowing, setIsFollowing] = useState(true)
+
+  const shownLines =
+    lines.length > maxLines
+      ? lines.slice(lines.length - maxLines)
+      : lines
+
+  // biome-ignore lint/correctness/useExhaustiveDependencies: `shownLines` is read through the DOM, not through the closure — `pane.scrollHeight` is a *consequence* of the lines having rendered, so the linter sees a dependency it cannot trace and calls it unnecessary. Removing it is not a style change: the effect then runs only when `isFollowing` flips, which is mux-magic's `}, [])` bug rebuilt exactly. `yarn lint` runs `--write --unsafe`, so this was applied silently once already and the log stopped following.
+  useEffect(() => {
+    const pane = paneRef.current
+
+    if (!pane || !isFollowing) {
+      return
+    }
+
+    pane.scrollTop = pane.scrollHeight
+    // `shownLines` rather than an empty array — this is the whole fix
+    // for defect 1, and the dependency *is* the fix.
+  }, [isFollowing, shownLines])
+
+  return (
+    <div
+      className={toClassName(
+        "relative flex flex-col",
+        className,
+      )}
+    >
+      <div
+        aria-label={label}
+        // `off` unless asked. See the note above; this is the
+        // difference between an accessible log and an unusable page.
+        aria-live={isAnnounced ? "polite" : "off"}
+        className="max-h-64 overflow-y-auto rounded-md border border-border-subtle bg-surface-sunken p-2 font-mono text-content-secondary text-xs"
+        onScroll={(scrollEvent) => {
+          const pane = scrollEvent.currentTarget
+
+          // A few pixels of slack, because a fractional device pixel
+          // ratio means `scrollTop + clientHeight` never lands
+          // exactly on `scrollHeight` — an equality test here
+          // un-pins the pane on a 125% display and on nothing else,
+          // which is the kind of bug that gets reported as "it works
+          // on my machine".
+          const isPinnedToBottom =
+            pane.scrollHeight -
+              pane.scrollTop -
+              pane.clientHeight <
+            4
+
+          setIsFollowing(isPinnedToBottom)
+        }}
+        ref={paneRef}
+        role="log"
+        // biome-ignore lint/a11y/noNoninteractiveTabindex: a scroll container must be focusable or a keyboard user can see the pane and cannot scroll it — axe's `scrollable-region-focusable`, which fails this component without the line. Chrome started doing it automatically in 2024; Firefox and Safari have not. The rule is right about `<div>`s in general and wrong about scrollers.
+        tabIndex={0}
+      >
+        {shownLines.length === 0 ? (
+          <p className="text-content-muted">
+            Waiting for output…
+          </p>
+        ) : (
+          shownLines.map((line) => (
+            <p
+              className={toClassName(
+                "whitespace-pre-wrap break-all",
+                line.intent === undefined
+                  ? null
+                  : INTENT_CONTENT_CLASS[line.intent],
+              )}
+              key={line.key}
+            >
+              {line.text}
+            </p>
+          ))
+        )}
+      </div>
+
+      {isFollowing ? null : (
+        <Button
+          appearance="soft"
+          className="absolute inset-x-0 bottom-2 mx-auto w-fit"
+          intent="neutral"
+          onClick={() => {
+            setIsFollowing(true)
+          }}
+          size="sm"
+        >
+          Jump to latest
+        </Button>
+      )}
+    </div>
+  )
+}

package/src/Menu/Menu.mdx

@@ -0,0 +1,103 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as MenuStories from "./Menu.stories";
+
+<Meta of={MenuStories} />
+
+# Menu
+
+A menu is **not** a listbox, and mux-magic's `TypePicker` is the fleet's one attempt at
+telling them apart — it renders `role="menu"` over items that set a value, which is a
+listbox wearing the wrong role.
+
+<Canvas of={MenuStories.Default} />
+
+## Props
+
+<Controls />
+
+## `menuitem` versus `option`
+
+| | `menuitem` | `option` |
+| --- | --- | --- |
+| What it is | an **action** — Retry, Skip, Eject | a **value** you are choosing |
+| Announced as | "menu, 3 items" | "listbox, selected, 2 of 4" |
+| Leaves state behind | no | yes |
+| Lives in | this component | `Select` |
+
+The last row is why it matters to an agent driving the app: after choosing an `option` it
+needs to know what the control now holds. After invoking a `menuitem` there is nothing to
+read back. Getting the role wrong is invisible in a browser and invisible to axe.
+
+## A `[popover]` that was never shown is `display: none`
+
+The panel calls `showPopover()` from its ref callback, like `Popover` does — plus an
+`isConnected` guard and an effect that `Popover` does not need.
+
+`FloatingFocusManager` renders a pair of focus guards around its child, so React commits this
+subtree in an order where the ref can fire while the node is still **detached**.
+`showPopover()` on a disconnected element throws `InvalidStateError`, which surfaces as an
+unhandled rejection rather than a failing assertion — and if it is simply swallowed, the menu
+renders, typechecks, and is invisible to `getByRole` and to a user alike.
+
+The effect is the backstop, because effects run after the tree is connected. Both are
+idempotent: `:popover-open` is the same question.
+
+## There is no `label` prop, and that corrects a lesson
+
+`Spinner` (M3), `Popover` and `Modal` (M4) all take a **required** name, because a
+`role="status"` and a `role="dialog"` take none from their content. The obvious move here was
+a `label` prop doing the same job — it was written that way first, and then measured as
+doing **nothing**.
+
+`useRole(context, { role: "menu" })` puts `aria-labelledby` on the panel pointing at the
+trigger, and `aria-labelledby` beats `aria-label`. The menu was already named "Bay 3", from
+the button, and the prop was silently discarded. That is also the APG menu-button pattern.
+
+So the rule the other three teach is narrower than it looked:
+
+> An overlay with **no trigger relationship** needs its own name.
+
+A menu has one, so the requirement moves to the trigger — which `Button` and `IconButton`
+already enforce.
+
+## One kind, and that is the other half of the `Tabs` argument
+
+`Tabs` needed **two** state kinds because a tab is chosen *and* focused, and in `manual`
+activation those two disagree on purpose. A menu needs **one** — `RovingFocus` — because a
+menu item is never selected, only invoked.
+
+Two components, opposite conclusions, same model. That is the composition claim being paid
+off rather than asserted.
+
+<Canvas of={MenuStories.AllVariants} />
+
+## Focus moves in, once
+
+A menu is one of the few patterns where focus must jump on open, or the keyboard user who
+pressed Enter is still on the trigger with a menu they cannot reach.
+
+It happens in the panel's own effect rather than through `FloatingFocusManager`'s
+`initialFocus`, because the element to focus is whichever one `RovingFocus` says is active —
+and that is not known until the items have registered. `initialFocus={-1}` turns the
+manager's own aim off, so there is one owner for the caret.
+
+`modal={false}`, so Tab **leaves** the menu and lands on the next control in the page, which
+is what closes it. A trapped menu is a dialog.
+
+<Canvas of={MenuStories.AllStates} />
+
+## Registration is membership
+
+A disabled item never registers with the roving group, so the arrow keys skip it with
+nothing in `RovingFocus` knowing what "disabled" means. It stays in the DOM and stays
+announced — "not right now", rather than "does not exist".
+
+## No type-ahead, deliberately
+
+The APG lists type-ahead as **optional** for a menu and **required** for a listbox, and none
+of the fleet's menus are long enough to need it — the largest has six items. Adding it means
+a keystroke buffer and a timer in a component that has neither, for a menu you can cross in
+three arrow presses.
+
+<Canvas of={MenuStories.Interactive} />