@charcuterie/ui 0.1.1 → 1.0.0

package/src/LogViewer/LogViewer.stories.tsx

@@ -0,0 +1,169 @@
+import type { Meta, StoryObj } from "@storybook/react"
+
+import { Accordion } from "../Accordion/Accordion.tsx"
+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 },
+}
+
+/**
+ * The pane mounted inside a **collapsed** `Accordion` section, which
+ * is how the fleet actually renders a log and is the one arrangement
+ * where following used to fail.
+ *
+ * `AccordionSection` renders its panel with `hidden`, deliberately,
+ * so the pane keeps its scroll position and its subscriptions across
+ * a collapse. A `hidden` subtree has no layout, so a pane that
+ * measures itself on mount measures `scrollHeight 0` — and neither
+ * `isFollowing` nor `lines` changes when the section is opened.
+ *
+ * Expand it: the log opens on its **last** line, not its first.
+ */
+export const InsideDisclosure: Story = {
+  args: { label: "Bay 9 rip log", lines: LONG_LINES },
+  render: () => (
+    <Accordion
+      items={[
+        {
+          content: (
+            <LogViewer
+              label="Bay 9 rip log"
+              lines={LONG_LINES}
+            />
+          ),
+          key: "logs",
+          label: "Bay 9 output",
+        },
+      ]}
+    />
+  ),
+}

package/src/LogViewer/LogViewer.test.tsx

@@ -0,0 +1,236 @@
+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,
+  InsideDisclosure,
+  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)
+  })
+})
+
+/**
+ * The same defect, rebuilt out of two components that are each
+ * individually right — and the reason `LogViewer` watches its own box
+ * rather than trusting one mount measurement.
+ *
+ * `AccordionSection` renders `hidden` rather than unmounting, because
+ * the fleet's panels hold log panes and an unmounted panel loses its
+ * scroll position and its subscription. A `hidden` subtree has no
+ * layout box, so the mount effect reads `scrollHeight 0` and writes
+ * `scrollTop = 0` — and the effect's dependencies, `isFollowing` and
+ * the lines, are both unchanged by the reveal. Measured in mux-magic
+ * on a 60-line pane:
+ *
+ * ```
+ * while collapsed : scrollTop 0   scrollHeight 0     clientHeight 0
+ * after expanding : scrollTop 0   scrollHeight 976   clientHeight 254
+ * ```
+ *
+ * mux-magic worked around it downstream, in `DisclosedLogViewer`, by
+ * not mounting the pane until the section had been opened once. This
+ * test is that workaround becoming deletable.
+ */
+test("a pane revealed by a disclosure follows the tail", async () => {
+  const { canvas } = await mountStory(InsideDisclosure)
+
+  // `hidden: true` because that is the whole precondition: the pane
+  // is in the accessibility tree's shadow, and in the layout tree not
+  // at all.
+  const pane = canvas.getByRole("log", {
+    hidden: true,
+    name: "Bay 9 rip log",
+  })
+
+  // Not a rhetorical assertion. If a future `AccordionSection`
+  // unmounts its panel instead, or stops using `hidden`, this test
+  // silently stops testing anything — so it fails here instead.
+  await expect(pane.scrollHeight).toBe(0)
+
+  expectAgentDrivable(canvas, {
+    name: "Bay 9 output",
+    role: "button",
+  }).click()
+
+  await waitFor(() => {
+    expect(pane.scrollHeight).toBeGreaterThan(
+      pane.clientHeight,
+    )
+  })
+
+  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,261 @@
+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. A fifth, below the effects, is not
+ * theirs: it is defect 1 coming back through the front door, in this
+ * component, found by the first app to consume it.
+ *
+ * ### 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])
+
+  /**
+   * Defect 1 again, and the effect above cannot see it: **a pane can
+   * be measured before it has a box.**
+   *
+   * `AccordionSection` renders its panel with `hidden` rather than
+   * unmounting it, deliberately — "a panel that unmounts loses a
+   * scroll position, a partially typed form, and any subscription its
+   * content opened — and the fleet's log panes are exactly that." A
+   * `hidden` subtree has no layout, so the effect above runs on mount
+   * with `scrollHeight 0` and writes `scrollTop = 0`, and then never
+   * runs again: neither `isFollowing` nor `shownLines` changes when
+   * the section is opened. Measured in mux-magic on a 60-line pane:
+   *
+   * ```
+   * while collapsed : scrollTop 0   scrollHeight 0     clientHeight 0
+   * after expanding : scrollTop 0   scrollHeight 976   clientHeight 254
+   * ```
+   *
+   * That is this component's own `}, [])` bug, rebuilt out of two
+   * components whose individual decisions are both right, and
+   * invisible to both of their test suites — `LogViewer`'s mounted
+   * visible, `Accordion`'s holding content that never measures
+   * itself. mux-magic hit it in its first week as a consumer and
+   * worked around it downstream, in a `DisclosedLogViewer` that
+   * withheld the pane until the section had been opened once. This is
+   * that workaround coming into the library so it can be deleted.
+   *
+   * ### Why the box and not the viewport
+   *
+   * An `IntersectionObserver` answers "is it on screen", which is a
+   * different question with two wrong answers here: a pane below the
+   * fold on a long page is *not* intersecting and has perfectly good
+   * layout, and scrolling the page later would re-fire for no reason.
+   * `ResizeObserver` answers "does it have a box, and is that box
+   * still the same size" — which is the precondition the measurement
+   * above actually needs. Per spec it does not fire at `observe()`
+   * time for an element that is not being rendered, so gaining a box
+   * *is* the first callback, and that is the reveal.
+   *
+   * It pays for itself twice: a window resize re-wraps the lines and
+   * changes what is at the bottom, and a following pane should be at
+   * the new bottom rather than a few lines above it.
+   *
+   * Only while following. A user who scrolled up to read an error is
+   * not dragged back by resizing their window.
+   */
+  useEffect(() => {
+    const pane = paneRef.current
+
+    if (!pane || !isFollowing) {
+      return
+    }
+
+    const observer = new ResizeObserver(() => {
+      pane.scrollTop = pane.scrollHeight
+    })
+
+    observer.observe(pane)
+
+    return () => {
+      observer.disconnect()
+    }
+  }, [isFollowing])
+
+  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>
+  )
+}