@charcuterie/ui 3.0.0 → 3.2.0

package/src/Board/Board.test.tsx

@@ -0,0 +1,310 @@
+import { composeStories } from "@storybook/react"
+import {
+  expect,
+  userEvent,
+  waitFor,
+  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 "./Board.stories.tsx"
+
+const {
+  AllStates,
+  Default,
+  InBoardScreen,
+  Interactive,
+  Responsive,
+} = composeStories(stories)
+
+/**
+ * The board is the landmark; the lanes are **groups** inside it.
+ *
+ * A lane that were a `region` would put three landmarks on a page
+ * that has one job — and two boards on one page, or three copies of
+ * one in a container-width story, would put two landmarks called
+ * "Todo" in the document. That is axe's `landmark-unique`, and it
+ * was a real failure here before the lane became a group.
+ */
+test("the board is a named landmark and its lanes are named groups", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const board = expectAgentDrivable(canvas, {
+    name: "Today, mixed lanes",
+    role: "region",
+  })
+
+  for (const laneLabel of [
+    "Todo",
+    "In Progress",
+    "Needs Review",
+  ]) {
+    expectAgentDrivable(canvas, {
+      name: laneLabel,
+      role: "group",
+    })
+  }
+
+  await expectNoAxeViolations(board)
+})
+
+/**
+ * Three lanes at once is a **container** decision. The story frames
+ * the board at a fixed 72rem, so this passes or fails on the
+ * board's own box and not on however wide the test runner's window
+ * happens to be — which is the whole claim the component makes.
+ */
+test("a board wider than cq-lg shows every lane at once", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  await expect(canvas.getAllByRole("group")).toHaveLength(3)
+
+  // And the lane picker, which only exists for the narrow layout,
+  // is not in the accessibility tree at all — `display: none`
+  // rather than hidden-but-present.
+  await expect(
+    canvas.queryAllByRole("radiogroup"),
+  ).toHaveLength(0)
+})
+
+/**
+ * The count is the lane's **real** size, not the number of rows
+ * painted. A board that truncates and then reports the truncated
+ * number is a board that quietly lies about how much work there is,
+ * which is the one number the lane exists to carry.
+ */
+test("a truncated lane reports its true size and says what is missing", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  const review = expectAgentDrivable(canvas, {
+    name: "Needs Review",
+    role: "group",
+  })
+
+  // By the **title link** rather than the `<li>`. A list item takes
+  // no accessible name from its content, so `getByRole("listitem",
+  // { name })` can never match — and the title is what an agent or a
+  // person actually clicks anyway.
+  await expect(
+    within(review).getByRole("link", {
+      name: /Merge manager rename/,
+    }),
+  ).toBeInTheDocument()
+
+  // Eight rendered, nineteen real.
+  await expect(
+    within(review).getAllByRole("listitem"),
+  ).toHaveLength(8)
+
+  await expect(
+    within(review).getByText("19"),
+  ).toBeInTheDocument()
+
+  await expect(
+    within(review).getByText("+ 11 more in Needs Review"),
+  ).toBeInTheDocument()
+})
+
+/**
+ * A colour bar is a WCAG 1.4.1 failure on its own and invisible to
+ * every screen reader, so the priority it encodes is stated in
+ * words too. This is the assertion that would have caught Docket's
+ * first board, where the bars were painted with a token family that
+ * does not exist and rendered transparent while every "is it
+ * rendered" check passed.
+ */
+test("the priority bar's meaning is available as text", async () => {
+  const { canvas } = await mountStory(Interactive)
+
+  const todo = expectAgentDrivable(canvas, {
+    name: "Todo",
+    role: "group",
+  })
+
+  await expect(
+    within(todo).getAllByText("Priority 0").length,
+  ).toBeGreaterThan(0)
+
+  await expect(
+    within(todo).getAllByText("Priority 1").length,
+  ).toBeGreaterThan(0)
+})
+
+/**
+ * A read-only board carries no affordances. Not a cosmetic
+ * difference: a handle that opens a menu whose every item does
+ * nothing is worse than no handle, because it costs a tab stop and
+ * a promise.
+ */
+test("a board with no onMove has no move handles", async () => {
+  const { canvas } = await mountStory(Default)
+
+  await expect(
+    canvas.queryAllByRole("button", { name: /^Move / }),
+  ).toHaveLength(0)
+})
+
+/**
+ * The whole keyboard path, and the one the component treats as
+ * primary. Tab to a handle, Enter to open, arrow to a lane, Enter to
+ * commit — every step through `Menu`, which already owns the
+ * roving-focus model, so there is no second keyboard implementation
+ * here to drift.
+ */
+test("a card moves between lanes from the keyboard alone", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  const todo = expectAgentDrivable(canvas, {
+    name: "Todo",
+    role: "group",
+  })
+
+  const handle = within(todo).getByRole("button", {
+    name: /^Move Retire the second scheduler/,
+  })
+
+  handle.focus()
+
+  await expect(handle).toHaveFocus()
+
+  await userEvent.keyboard("{Enter}")
+
+  const menuItem = await waitFor(() =>
+    body.getByRole("menuitem", { name: "In Progress" }),
+  )
+
+  // The panel, not the whole document: floating-ui's own focus
+  // guards are `aria-hidden` and focusable by design, so auditing
+  // `body` audits the overlay library rather than this component.
+  // Same scope `Menu`'s own tests use.
+  await expectNoAxeViolations(body.getByRole("menu"))
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await userEvent.click(menuItem)
+
+  const inProgress = expectAgentDrivable(canvas, {
+    name: "In Progress",
+    role: "group",
+  })
+
+  await waitFor(() => {
+    expect(
+      within(inProgress).getByRole("link", {
+        name: /Retire the second scheduler/,
+      }),
+    ).toBeInTheDocument()
+  })
+
+  // And it left the lane it came from, rather than being copied.
+  await waitFor(() => {
+    expect(
+      within(todo).queryByRole("link", {
+        name: /Retire the second scheduler/,
+      }),
+    ).toBeNull()
+  })
+})
+
+/**
+ * The feedback a sighted user gets free from watching the card land,
+ * said out loud — and it names the **position**, not only the lane.
+ * "Moved to In Progress" leaves a screen-reader user unable to tell
+ * the top of a lane from the bottom of thirty.
+ */
+test("the move is announced with its destination and position", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Interactive)
+
+  const todo = expectAgentDrivable(canvas, {
+    name: "Todo",
+    role: "group",
+  })
+
+  await userEvent.click(
+    within(todo).getByRole("button", {
+      name: /^Move One composed Storybook/,
+    }),
+  )
+
+  await userEvent.click(
+    await waitFor(() =>
+      within(document.body).getByRole("menuitem", {
+        name: "Needs Review",
+      }),
+    ),
+  )
+
+  const status = await waitFor(() => {
+    const region = canvasElement.querySelector(
+      '[role="status"]',
+    )
+
+    expect(region?.textContent).toMatch(
+      /^Moved One composed Storybook for every app in the fleet to Needs Review, position \d+ of \d+\.$/,
+    )
+
+    return region
+  })
+
+  await expect(status).toHaveAttribute(
+    "aria-label",
+    "Today, movable activity",
+  )
+})
+
+/**
+ * The narrow layout is one lane plus a `radiogroup`, and the
+ * radiogroup is a **container** decision — this story is three fixed
+ * widths inside one unchanged window, so the viewport cannot be what
+ * chose it.
+ */
+test("the narrow layout picks lanes with a named radiogroup", async () => {
+  const { canvas } = await mountStory(Responsive)
+
+  const pickers = canvas.getAllByRole("radiogroup")
+
+  // One per panel: the same board, three container widths, one
+  // browser window that never moved.
+  await expect(pickers).toHaveLength(3)
+
+  const [narrowest] = pickers
+
+  const inProgress = within(narrowest).getByRole("radio", {
+    name: /In Progress/,
+  })
+
+  await userEvent.click(inProgress)
+
+  await waitFor(() => {
+    expect(inProgress).toBeChecked()
+  })
+})
+
+/**
+ * An empty lane says something a person can act on, and it is a real
+ * heading rather than a grey word — so it is findable by role, which
+ * "Empty" in a `<div>` never is.
+ */
+test("an empty lane renders a real, findable empty state", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  expectAgentDrivable(canvas, {
+    name: "Nothing chosen yet",
+    role: "heading",
+  })
+})
+
+/**
+ * The composition the docs page recommends, audited as a whole: the
+ * cross-lane banner is an `Alert` above the board rather than a
+ * fourth lane inside it, and the two together still pass.
+ */
+test("the board sits under a separate attention banner, and the page is clean", async () => {
+  const { canvasElement } = await mountStory(InBoardScreen)
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Board/Board.tsx

@@ -0,0 +1,333 @@
+import type { ReactNode } from "react"
+import { useCallback, useState } from "react"
+
+import { SegmentedControl } from "../SegmentedControl/SegmentedControl.tsx"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+import type { BoardLane } from "./BoardLaneList.tsx"
+import { BoardLaneList } from "./BoardLaneList.tsx"
+import {
+  describeMove,
+  getIsMoveMeaningful,
+  toSettledIndex,
+} from "./boardMove.ts"
+import { useBoardDrag } from "./useBoardDrag.ts"
+
+export type BoardMove = {
+  /** Where the card was, in `fromLane.items`. */
+  fromIndex: number
+  fromLaneKey: string
+  itemKey: string
+  /**
+   * Where it goes, **already corrected for its own removal** — so a
+   * consumer's handler is `splice(fromIndex, 1)` then
+   * `splice(toIndex, 0, item)` with no arithmetic of its own. A
+   * within-lane move quoted against the un-spliced list is one too
+   * high for every position below the origin, and that off-by-one is
+   * the single most common bug in a hand-rolled board.
+   */
+  toIndex: number
+  toLaneKey: string
+}
+
+export type BoardProps = {
+  className?: string
+  /**
+   * What level the lane headings are. The caller's, because only the
+   * caller knows what the board sits under: a board directly below a
+   * page `<h1>` wants `2`, and one inside an already-deep section
+   * wants `4`. Getting it wrong is an axe `heading-order` failure and
+   * a broken screen-reader outline.
+   */
+  headingLevel?: 2 | 3 | 4 | 5
+  /** The board's accessible name. Required — it is a landmark. */
+  label: string
+  lanes: readonly BoardLane[]
+  /**
+   * What the move handle shows instead of the word "Move". The
+   * library ships no icons and no symbol glyphs in a default —
+   * they render as nothing where the font lacks them, which
+   * includes this sandbox's chromium, the kiosk image and the
+   * ePaper build — so the default is a word and an app that owns a
+   * glyph set passes one. On a dense board it is worth ~55px a row.
+   */
+  moveIcon?: ReactNode
+  /**
+   * Which lane is on screen below `cq-lg`. **Initial only** — the
+   * segmented control owns it from then on, matching every other
+   * uncontrolled control in this library.
+   */
+  narrowLaneKey?: string
+  /**
+   * The one thing that makes a board a board. **Absent means
+   * read-only**: no handles, no menus, no drag, and nothing
+   * announcing itself. A board with no `onMove` is a legitimate
+   * thing — a dashboard, an ePaper render — and it should not be
+   * carrying affordances that do nothing.
+   */
+  onMove?: (move: BoardMove) => void
+}
+
+/**
+ * Lanes of cards, sized by their **container**, moved by keyboard or
+ * by pointer.
+ *
+ * ### The container rule, which is the whole point
+ *
+ * There is no media query in this component, and adding one would be
+ * a defect rather than a shortcut. Two facts make window width
+ * useless here and they compound:
+ *
+ *  - **A lane in a three-up board is narrow on any monitor.** Three
+ *    lanes across 1600px is ~500px each, which is a phone's worth of
+ *    room, on a 4K display, in a maximised window.
+ *  - **The owner browses zoomed in.** A 1500px window at 175% zoom
+ *    is ~860 effective CSS pixels, so the number a media query reads
+ *    is not the number of pixels anything actually has.
+ *
+ * So there are **two nested containers**, and they answer two
+ * different questions:
+ *
+ *  - The board's own box decides *how many lanes are on screen* —
+ *    three-up at `cq-lg` and wider, one lane plus a segmented
+ *    control below it.
+ *  - Each lane's list decides *what shape a card is* — two lines,
+ *    one line, or its own card. See `BoardCard`.
+ *
+ * Both are `@container`, and neither is queried by the element that
+ * declares it, because a container query matches descendants only.
+ *
+ * ### There is no horizontal scroll, at any width
+ *
+ * *"No horizontal scroll, ever. The board becomes a segmented
+ * control, never a pan surface."* A board that pans sideways hides
+ * lanes behind a gesture with no affordance, and on a trackpad it
+ * fights the browser's own back-navigation. So the narrow layout
+ * shows one lane at a time and names the others in a `radiogroup`
+ * that says how many cards each holds.
+ *
+ * ### Moving a card is a first-class operation, and it is not a drag
+ *
+ * The move is a **`Menu` on every card**, listing the other lanes.
+ * That is the primary path, not an accessibility fallback: it is the
+ * only one that works from the keyboard, the only one a screen
+ * reader can drive, and the only one available in the Narrow View
+ * where the other lanes are not on screen to drop onto. Pointer
+ * dragging is layered on the same handle and commits through the
+ * same callback.
+ *
+ * **No drag-and-drop dependency is taken.** The reasoning — licence,
+ * provenance, bundle cost, and what a general DnD library would
+ * actually be buying for one card going into one lane — is in
+ * [the decision](../../../docs/decisions/2026-08-19-the-board-owns-the-move-and-takes-no-drag-and-drop-dependency.md).
+ *
+ * ### What this component deliberately does not do
+ *
+ * Lanes, counts, truncation, empty states and the move; **not**
+ * data, not virtualisation, and not the cross-lane "needs attention"
+ * summary. A board is a view of a list the consumer owns, the lane
+ * truncates by construction so there is nothing to virtualise, and a
+ * panel that reaches across every lane is not a lane — it is an
+ * `Alert` above the board, which is how the docs page composes it.
+ */
+export const Board = ({
+  className,
+  headingLevel = 3,
+  label,
+  lanes,
+  moveIcon,
+  narrowLaneKey,
+  onMove,
+}: BoardProps): ReactNode => {
+  const [visibleLaneKey, setVisibleLaneKey] = useState(
+    narrowLaneKey ?? lanes[0]?.key ?? "",
+  )
+
+  /**
+   * What the live region last said. A string rather than a boolean
+   * plus a lookup, because the region's job is to have the sentence
+   * ready the moment it changes — and because a move announced as
+   * "moved" with no destination tells a screen-reader user strictly
+   * less than watching the card land tells everyone else.
+   */
+  const [moveAnnouncement, setMoveAnnouncement] =
+    useState("")
+
+  const commitMove = useCallback(
+    (move: BoardMove) => {
+      const toLane = lanes.find(
+        (one) => one.key === move.toLaneKey,
+      )
+
+      if (!toLane) {
+        return
+      }
+
+      const item = lanes
+        .flatMap((one) => one.items)
+        .find((one) => one.key === move.itemKey)
+
+      setMoveAnnouncement(
+        describeMove({
+          index: move.toIndex,
+          laneLabel: toLane.label,
+          laneSize:
+            move.fromLaneKey === move.toLaneKey
+              ? (toLane.itemCount ?? toLane.items.length)
+              : (toLane.itemCount ?? toLane.items.length) +
+                1,
+          title: item?.title ?? move.itemKey,
+        }),
+      )
+
+      onMove?.(move)
+    },
+    [lanes, onMove],
+  )
+
+  const { drag, registerLane, startDrag } = useBoardDrag({
+    onDrop: (origin, target) => {
+      if (
+        !getIsMoveMeaningful({
+          fromIndex: origin.fromIndex,
+          fromLaneKey: origin.fromLaneKey,
+          toIndex: target.index,
+          toLaneKey: target.laneKey,
+        })
+      ) {
+        return
+      }
+
+      commitMove({
+        fromIndex: origin.fromIndex,
+        fromLaneKey: origin.fromLaneKey,
+        itemKey: origin.itemKey,
+        toIndex: toSettledIndex({
+          fromIndex: origin.fromIndex,
+          fromLaneKey: origin.fromLaneKey,
+          toIndex: target.index,
+          toLaneKey: target.laneKey,
+        }),
+        toLaneKey: target.laneKey,
+      })
+    },
+  })
+
+  return (
+    <section
+      aria-label={label}
+      className={toClassName("@container", className)}
+    >
+      <div className="flex flex-col gap-3">
+        {/*
+         * Hidden rather than unmounted above `cq-lg`, and that is
+         * not laziness. Rendering it conditionally would need the
+         * board's own width in JavaScript, which means a
+         * `ResizeObserver`, which means the first paint is wrong and
+         * a kiosk Pi shows it. `display: none` is invisible to
+         * assistive technology as well as to the eye, so the wide
+         * board has no stray radiogroup in it.
+         */}
+        <SegmentedControl
+          className="max-w-full flex-wrap cq-lg:hidden"
+          items={lanes.map((lane) => ({
+            // Stacked rather than `Todo (6)`, because the count is
+            // the reason to look: a lane picker that reads
+            // "In Progress (5)" on one line is a long label with a
+            // number in it, and at 15rem three of them do not fit
+            // on any line at all.
+            label: (
+              <span className="flex flex-col items-center leading-tight">
+                <span>{lane.label}</span>
+
+                <span className="font-normal text-content-muted text-xs">
+                  {String(
+                    lane.itemCount ?? lane.items.length,
+                  )}
+                </span>
+              </span>
+            ),
+            value: lane.key,
+          }))}
+          label={`${label} lanes`}
+          onChange={(value) => {
+            setVisibleLaneKey(value ?? "")
+          }}
+          selectedValue={visibleLaneKey}
+        />
+
+        <div className="flex flex-col gap-4 cq-lg:flex-row cq-lg:items-start">
+          {lanes.map((lane) => (
+            <BoardLaneList
+              headingLevel={headingLevel}
+              dropIndicatorOffset={
+                drag?.target?.laneKey === lane.key
+                  ? drag.indicatorOffset
+                  : null
+              }
+              isVisibleWhenNarrow={
+                lane.key === visibleLaneKey
+              }
+              key={lane.key}
+              lane={lane}
+              moveIcon={moveIcon}
+              moveTargets={lanes
+                .filter((one) => one.key !== lane.key)
+                .map((one) => ({
+                  key: one.key,
+                  label: one.label,
+                }))}
+              onMoveToLane={
+                onMove
+                  ? (itemKey, toLaneKey) => {
+                      const toLane = lanes.find(
+                        (one) => one.key === toLaneKey,
+                      )
+
+                      commitMove({
+                        fromIndex: lane.items.findIndex(
+                          (one) => one.key === itemKey,
+                        ),
+                        fromLaneKey: lane.key,
+                        itemKey,
+                        // A menu move appends. There is no pointer
+                        // to read a position off, and "the end of
+                        // the lane you just sent it to" is the one
+                        // answer that needs no second question.
+                        toIndex: toLane?.items.length ?? 0,
+                        toLaneKey,
+                      })
+                    }
+                  : undefined
+              }
+              onStartDrag={
+                onMove
+                  ? (pointerEvent, origin) => {
+                      startDrag(pointerEvent, {
+                        ...origin,
+                        fromLaneKey: lane.key,
+                      })
+                    }
+                  : undefined
+              }
+              registerListElement={registerLane(lane.key)}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/*
+       * `aria-label` on a `role="status"`, per the library's own
+       * rule — a live region with no name is announced with no
+       * context, and this one fires while the user's attention is on
+       * a card rather than on the board.
+       */}
+      <VisuallyHidden
+        aria-label={`${label} activity`}
+        role="status"
+      >
+        {moveAnnouncement}
+      </VisuallyHidden>
+    </section>
+  )
+}