@charcuterie/ui 3.22.0 → 3.23.0

package/src/ReorderList/ReorderList.stories.tsx

@@ -0,0 +1,149 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import { useState } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import type { ReorderListItem } from "./ReorderList.tsx"
+import { ReorderList } from "./ReorderList.tsx"
+
+/**
+ * **Invented, all of it** — the same rule `Board.stories.tsx` and
+ * `DropRail.stories.tsx` state, for the same reason. The lists this
+ * component was built for are a real household's, a published repo
+ * must never carry that, and a committed screenshot is worse than a
+ * committed string because no text scrub can reach inside a PNG.
+ */
+const CHECKLIST: ReorderListItem[] = [
+  { key: "measure", label: "Measure the alcove" },
+  { key: "cut", label: "Cut the shelf to width" },
+  { key: "sand", label: "Sand the cut edge" },
+  { key: "mount", label: "Mount the brackets" },
+  { key: "level", label: "Check it is level" },
+]
+
+/**
+ * The two buttons and the handle, drawn the way a host draws them.
+ *
+ * The **position is the handle**, which is not a stylistic choice: a
+ * list that is ordered wants its position printed anyway, so the
+ * number costs the row nothing — and this library ships no icons, so
+ * a `⠿` would render as an empty box in any font that lacks it.
+ */
+const StoryList = ({
+  initialItems = CHECKLIST,
+  isSingle = false,
+}: {
+  initialItems?: ReorderListItem[]
+  isSingle?: boolean
+}) => {
+  const [items, setItems] = useState(
+    isSingle ? initialItems.slice(0, 1) : initialItems,
+  )
+
+  return (
+    <ReorderList
+      className="flex max-w-md flex-col gap-1"
+      items={items}
+      itemClassName="list-none"
+      label="Shelf build"
+      onReorder={(fromIndex, toIndex) => {
+        setItems((current) => {
+          const next = [...current]
+
+          const [moved] = next.splice(fromIndex, 1)
+
+          if (moved) {
+            next.splice(toIndex, 0, moved)
+          }
+
+          return next
+        })
+      }}
+      renderItem={({
+        gripProps,
+        isDragged,
+        isFirst,
+        isLast,
+        item,
+        moveBy,
+        position,
+      }) => (
+        <div
+          className={toClassName(
+            "flex items-center gap-2 rounded-md border border-border-subtle bg-surface-raised p-2",
+            isDragged && "opacity-50",
+          )}
+        >
+          <button
+            aria-label={`Move ${item.label} earlier`}
+            className="rounded-sm px-1 text-content-secondary hover:bg-surface-sunken disabled:opacity-40"
+            disabled={isFirst}
+            onClick={() => {
+              moveBy(-1)
+            }}
+            type="button"
+          >
+            ↑
+          </button>
+
+          <span
+            className="cursor-grab select-none rounded-sm px-1 text-content-muted text-xs tabular-nums"
+            {...gripProps}
+          >
+            {position}
+          </span>
+
+          <button
+            aria-label={`Move ${item.label} later`}
+            className="rounded-sm px-1 text-content-secondary hover:bg-surface-sunken disabled:opacity-40"
+            disabled={isLast}
+            onClick={() => {
+              moveBy(1)
+            }}
+            type="button"
+          >
+            ↓
+          </button>
+
+          <span className="text-content-primary text-sm">
+            {item.label}
+          </span>
+        </div>
+      )}
+    />
+  )
+}
+
+const meta = {
+  title: "Components/Layout/ReorderList",
+  component: ReorderList,
+  parameters: { layout: "padded" },
+  args: {
+    items: CHECKLIST,
+    label: "Shelf build",
+    onReorder: () => {},
+    renderItem: ({ item }) => item.label,
+  },
+} satisfies Meta<typeof ReorderList<ReorderListItem>>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+/**
+ * A checklist in the order it will be worked through. Press ↑ or ↓,
+ * or press and hold the position and drag it somewhere else.
+ */
+export const Default: Story = {
+  render: () => <StoryList />,
+}
+
+/**
+ * **One row gets no controls at all.** A single item cannot be put
+ * anywhere else, so the handle is inert and the buttons are both
+ * disabled — the component says so through `gripProps` being empty,
+ * rather than leaving each host to remember it. Every hand-rolled
+ * copy of this shape forgot.
+ */
+export const SingleItem: Story = {
+  render: () => <StoryList isSingle />,
+}

package/src/ReorderList/ReorderList.test.tsx

@@ -0,0 +1,190 @@
+import { composeStories } from "@storybook/react"
+import {
+  expect,
+  userEvent,
+  type within,
+} from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import * as stories from "./ReorderList.stories.tsx"
+
+const { Default, SingleItem } = composeStories(stories)
+
+/**
+ * The rows come back in the DOM order the list draws them, which is
+ * the order under test. Reading the labels rather than the positions
+ * is deliberate: the printed number is derived from the index, so
+ * asserting on it would pass even if the rows had not moved.
+ */
+const getRowLabels = (canvas: ReturnType<typeof within>) =>
+  canvas
+    .getAllByRole("listitem")
+    .map((row: HTMLElement) => row.textContent ?? "")
+    .filter((text: string) => text !== "")
+
+test("moves a row later with the button, and says where it went", async () => {
+  const { canvas } = await mountStory(Default)
+
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: "Move Measure the alcove later",
+    }),
+  )
+
+  expect(getRowLabels(canvas)[0]).toContain(
+    "Cut the shelf to width",
+  )
+
+  expect(getRowLabels(canvas)[1]).toContain(
+    "Measure the alcove",
+  )
+
+  /*
+   * The POSITION, not just the fact of a move. "Moved" leaves a
+   * screen-reader user unable to tell the top of a list from the
+   * bottom of thirty.
+   */
+  expect(
+    canvas.getByRole("status", {
+      name: "Shelf build activity",
+    }),
+  ).toHaveTextContent(
+    "Moved Measure the alcove to position 2 of 5.",
+  )
+})
+
+test("moves a row earlier, and the ends stay disabled", async () => {
+  const { canvas } = await mountStory(Default)
+
+  expect(
+    canvas.getByRole("button", {
+      name: "Move Measure the alcove earlier",
+    }),
+  ).toBeDisabled()
+
+  expect(
+    canvas.getByRole("button", {
+      name: "Move Check it is level later",
+    }),
+  ).toBeDisabled()
+
+  await userEvent.click(
+    canvas.getByRole("button", {
+      name: "Move Sand the cut edge earlier",
+    }),
+  )
+
+  expect(getRowLabels(canvas)[1]).toContain(
+    "Sand the cut edge",
+  )
+})
+
+/**
+ * The handle is a pointer enhancement, so it must never be the only
+ * way to move a row — and on a list that cannot be reordered it must
+ * not advertise a gesture that does nothing.
+ */
+test("a one-row list offers no drag handle", async () => {
+  const { canvas } = await mountStory(SingleItem)
+
+  expect(canvas.queryByTitle("Drag to reorder")).toBeNull()
+})
+
+test("the handle takes the gesture away from the browser's scroll", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const grip = canvas.getAllByTitle("Drag to reorder")[0]
+
+  /*
+   * `touch-action: none` is the whole difference between a drag
+   * that works on a desktop and one that also works on the tablet
+   * this component was built for. Without it the browser claims
+   * the gesture for a scroll and the pointermove stream stops one
+   * frame in.
+   */
+  expect(grip).toHaveStyle({ touchAction: "none" })
+})
+
+/**
+ * The gesture itself, driven as a real pointer rather than as
+ * dispatched `PointerEvent`s.
+ *
+ * A hand-built event is not enough here, and the difference is not
+ * pedantry: `setPointerCapture` rejects an id that matches no
+ * ACTIVE pointer, so a synthetic sequence dies inside the handler
+ * before a single listener is registered — and the test then
+ * passes or fails for a reason the component does not have.
+ */
+test("drags a row past the one below it", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const grip = canvas.getAllByTitle("Drag to reorder")[0]
+
+  const secondRow = canvas.getAllByRole("listitem")[1]
+
+  if (!grip || !secondRow) {
+    throw new Error("The story drew no rows to drag.")
+  }
+
+  const to = secondRow.getBoundingClientRect()
+
+  await userEvent.pointer([
+    { keys: "[MouseLeft>]", target: grip },
+    {
+      coords: {
+        x: to.x + to.width / 2,
+        y: to.y + to.height - 2,
+      },
+    },
+    { keys: "[/MouseLeft]" },
+  ])
+
+  expect(getRowLabels(canvas)[0]).toContain(
+    "Cut the shelf to width",
+  )
+
+  expect(getRowLabels(canvas)[1]).toContain(
+    "Measure the alcove",
+  )
+})
+
+/**
+ * A press that goes nowhere must move nothing.
+ *
+ * The movement threshold is the reason the position can be both a
+ * printed number and a handle: without it, a handle is a control
+ * you cannot press by accident and then change your mind about,
+ * and every stray tap on a row reorders the list.
+ */
+test("a press with no movement reorders nothing", async () => {
+  const { canvas } = await mountStory(Default)
+
+  const grip = canvas.getAllByTitle("Drag to reorder")[0]
+
+  if (!grip) {
+    throw new Error("The story drew no rows to drag.")
+  }
+
+  await userEvent.pointer([
+    { keys: "[MouseLeft>]", target: grip },
+    { keys: "[/MouseLeft]", target: grip },
+  ])
+
+  expect(getRowLabels(canvas)[0]).toContain(
+    "Measure the alcove",
+  )
+
+  expect(
+    canvas.getByRole("status", {
+      name: "Shelf build activity",
+    }),
+  ).toHaveTextContent("")
+})
+
+test("has no axe violations", async () => {
+  const { canvasElement } = await mountStory(Default)
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/ReorderList/ReorderList.tsx

@@ -0,0 +1,331 @@
+import type { ReactNode, Ref } from "react"
+import { useCallback, useState } from "react"
+
+import {
+  getIsMoveMeaningful,
+  toSettledIndex,
+} from "../Board/boardMove.ts"
+import { useBoardDrag } from "../Board/useBoardDrag.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+/**
+ * The attribute the drag's hit test reads on a row. A `data-`
+ * attribute rather than a class, the same contract `BoardCard` and
+ * `DropRail` already write down: a class is a style and a
+ * consumer's tooling may rename it.
+ */
+const ITEM_ATTRIBUTE = "data-reorder-item"
+
+/**
+ * The single lane this component registers with the board's drag.
+ * A reorder list is a board with one lane and no lane picker, so
+ * the key is a constant and never leaves this file.
+ */
+const LANE_KEY = "reorder-list"
+
+export type ReorderListItem = {
+  key: string
+  /**
+   * Plain text, and it is not optional. Every accessible name the
+   * component writes is built from it — "Move <label> earlier" —
+   * and so is the sentence the live region reads after a move. A
+   * button announced as "↑" names nothing.
+   */
+  label: string
+}
+
+export type ReorderListRenderArguments<
+  TItem extends ReorderListItem,
+> = {
+  /**
+   * Spread onto whatever the host wants the drag to start FROM.
+   * Absent — as an empty object — when the list is too short to
+   * reorder, so a one-row list has no dead handle on it.
+   *
+   * It is a **handle**, never the whole row: a row holds links,
+   * and a link is draggable already.
+   */
+  gripProps: {
+    onPointerDown?: (event: {
+      clientX: number
+      clientY: number
+      currentTarget: EventTarget & Element
+      pointerId: number
+    }) => void
+    style?: { touchAction: "none" }
+    title?: string
+  }
+  index: number
+  isDragged: boolean
+  isFirst: boolean
+  isLast: boolean
+  item: TItem
+  /**
+   * The KEYBOARD path, and it is the primary one. The host draws
+   * the two buttons because only the host knows where they sit in
+   * its own row; the component supplies what they do and whether
+   * each end is disabled.
+   */
+  moveBy: (offset: -1 | 1) => void
+  /** 1-based, for printing. */
+  position: number
+}
+
+export type ReorderListProps<
+  TItem extends ReorderListItem,
+> = {
+  className?: string
+  /**
+   * The container element. `ul` by default, because an ordered
+   * pile of rows is a list; `div` for a host whose own CSS grid
+   * owns the shape and would have to undo list semantics to get
+   * it.
+   */
+  elementType?: "div" | "ol" | "ul"
+  /**
+   * The container element, for a host that needs it too.
+   *
+   * The component keeps its own hold on that element — the drag
+   * measures its rows off it — so this is MERGED rather than
+   * forwarded. Docket plays a FLIP animation off the same
+   * element, and without this the two uses would have to fight
+   * over one `ref`.
+   */
+  elementRef?: Ref<HTMLElement>
+  itemClassName?: string
+  items: readonly TItem[]
+  /** The list's accessible name. */
+  label: string
+  /**
+   * `fromIndex` and `toIndex` are both indexes into `items`, and
+   * `toIndex` is already corrected for the row's own removal — so
+   * a handler is `splice(from, 1)` then `splice(to, 0, row)` with
+   * no arithmetic of its own.
+   */
+  onReorder: (fromIndex: number, toIndex: number) => void
+  renderItem: (
+    renderArguments: ReorderListRenderArguments<TItem>,
+  ) => ReactNode
+}
+
+/**
+ * A vertical list whose rows can be put in a different order — by
+ * two buttons, or by dragging a handle.
+ *
+ * ### Why it is not a fourth hand-rolled reorder
+ *
+ * Docket wrote this twice: a subtask checklist on HTML5
+ * `draggable`, and a phase queue with the buttons and no drag at
+ * all. `Board` wrote a third, properly, on Pointer Events. Three
+ * implementations of one shape is the case the workspace's
+ * component rule exists for, so the geometry here is **`Board`'s
+ * own** — `useBoardDrag` with a single registered lane and the
+ * item selector pointed at this component's rows. Nothing about
+ * the measuring, the snapshot, the threshold or the pointer
+ * capture is written twice.
+ *
+ * ### The buttons are primary, the drag is the enhancement
+ *
+ * WCAG 2.5.7 requires a single-pointer alternative to any dragging
+ * movement, and the board's decision already argues the stronger
+ * version: the buttons are not a fallback bolted onto a drag, they
+ * are the only path that works from a keyboard, under a screen
+ * reader, or under a thumb in the Narrow View. So `renderItem`
+ * receives `moveBy` before it receives `gripProps`, and a host
+ * that draws no handle at all is a supported host.
+ *
+ * ### It takes no drag-and-drop dependency
+ *
+ * The board priced four libraries at 7–32 KB gzipped and took none
+ * of them, because a published library's dependency list is
+ * inherited by every consumer
+ * ([decision](../../../docs/decisions/2026-08-19-the-board-owns-the-move-and-takes-no-drag-and-drop-dependency.md)).
+ * This adds nothing to that arithmetic — it is the same 1.4 KB,
+ * called twice.
+ *
+ * ### `draggable="true"` is the instinct this replaces
+ *
+ * Native HTML5 drag-and-drop **does not fire on touch at all**, so
+ * the checklist Docket shipped on it cannot be reordered on the
+ * tablet its owner reads it on. Pointer Events are one code path
+ * for mouse, touch and pen, and `setPointerCapture` keeps the drag
+ * alive once the row has moved out from under the finger.
+ *
+ * ### What it deliberately does not do
+ *
+ * It renders no row, no handle, no buttons and no glyph. The host
+ * renders all four through `renderItem`, which is what lets one
+ * component serve a checklist, a queue and a card list whose CSS
+ * grids have nothing in common.
+ */
+export const ReorderList = <TItem extends ReorderListItem>({
+  className,
+  elementRef,
+  elementType = "ul",
+  itemClassName,
+  items,
+  label,
+  onReorder,
+  renderItem,
+}: ReorderListProps<TItem>): ReactNode => {
+  const [announcement, setAnnouncement] = useState("")
+
+  /**
+   * A single row cannot be put anywhere else, so it gets no grip
+   * and no buttons. This is checked here rather than in every
+   * host, because "hide the control when it can do nothing" is the
+   * part each hand-rolled copy forgot.
+   */
+  const isReorderable = items.length > 1
+
+  const commit = useCallback(
+    (fromIndex: number, toIndex: number) => {
+      setAnnouncement(
+        `Moved ${items[fromIndex]?.label ?? ""} to position ${String(toIndex + 1)} of ${String(items.length)}.`,
+      )
+
+      onReorder(fromIndex, toIndex)
+    },
+    [items, onReorder],
+  )
+
+  const { drag, registerLane, startDrag } = useBoardDrag({
+    itemSelector: `[${ITEM_ATTRIBUTE}]`,
+    onDrop: (origin, target) => {
+      if (
+        !getIsMoveMeaningful({
+          fromIndex: origin.fromIndex,
+          fromLaneKey: origin.fromLaneKey,
+          toIndex: target.index,
+          toLaneKey: target.laneKey,
+        })
+      ) {
+        return
+      }
+
+      commit(
+        origin.fromIndex,
+        toSettledIndex({
+          fromIndex: origin.fromIndex,
+          fromLaneKey: origin.fromLaneKey,
+          toIndex: target.index,
+          toLaneKey: target.laneKey,
+        }),
+      )
+    },
+  })
+
+  const ListElement = elementType
+
+  const ItemElement =
+    elementType === "div" ? "div" : ("li" as const)
+
+  return (
+    <>
+      <ListElement
+        aria-label={label}
+        className={toClassName("relative", className)}
+        ref={(element: HTMLElement | null) => {
+          registerLane(LANE_KEY)(element)
+
+          if (typeof elementRef === "function") {
+            elementRef(element)
+
+            return
+          }
+
+          if (elementRef) {
+            elementRef.current = element
+          }
+        }}
+      >
+        {items.map((item, index) => (
+          <ItemElement
+            className={itemClassName}
+            key={item.key}
+            {...{ [ITEM_ATTRIBUTE]: item.key }}
+          >
+            {renderItem({
+              gripProps: isReorderable
+                ? {
+                    onPointerDown: (pointerEvent) => {
+                      startDrag(pointerEvent, {
+                        fromIndex: index,
+                        fromLaneKey: LANE_KEY,
+                        itemKey: item.key,
+                      })
+                    },
+                    /*
+                     * Without it the browser claims the gesture
+                     * for a scroll and the `pointermove` stream
+                     * stops one frame in — which reads as "drag
+                     * works on the desktop and not on the
+                     * tablet", the exact bug this component
+                     * exists to end.
+                     */
+                    style: { touchAction: "none" },
+                    title: "Drag to reorder",
+                  }
+                : {},
+              index,
+              isDragged: drag?.itemKey === item.key,
+              isFirst: index === 0,
+              isLast: index === items.length - 1,
+              item,
+              moveBy: (offset) => {
+                const toIndex = index + offset
+
+                if (
+                  !isReorderable ||
+                  toIndex < 0 ||
+                  toIndex > items.length - 1
+                ) {
+                  return
+                }
+
+                commit(index, toIndex)
+              },
+              position: index + 1,
+            })}
+          </ItemElement>
+        ))}
+
+        {/*
+         * A real element rather than a border on a row, and
+         * absolutely positioned against a snapshot taken at grab.
+         * Inserting it must not move the rows below it: that
+         * feedback loop is what makes an indicator jump, and the
+         * reasoning is written out in `useBoardDrag.ts`.
+         */}
+        {drag?.indicatorOffset == null ? null : (
+          <ItemElement
+            aria-hidden="true"
+            className="pointer-events-none absolute end-0 start-0 h-0.5 rounded-full bg-intent-accent-solid"
+            style={{
+              insetBlockStart: `${String(drag.indicatorOffset)}px`,
+            }}
+          />
+        )}
+      </ListElement>
+
+      {/*
+       * `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 reader's attention
+       * is on a row rather than on the list.
+       *
+       * It names the POSITION, because "moved" leaves a
+       * screen-reader user unable to tell the top of a list from
+       * the bottom of thirty. That is the one piece of feedback a
+       * sighted user gets free from watching the row land.
+       */}
+      <VisuallyHidden
+        aria-label={`${label} activity`}
+        role="status"
+      >
+        {announcement}
+      </VisuallyHidden>
+    </>
+  )
+}

package/src/index.ts

@@ -316,6 +316,12 @@ export type {
   RailSide,
 } from "./Rail/Rail.tsx"
 export { Rail } from "./Rail/Rail.tsx"
+export type {
+  ReorderListItem,
+  ReorderListProps,
+  ReorderListRenderArguments,
+} from "./ReorderList/ReorderList.tsx"
+export { ReorderList } from "./ReorderList/ReorderList.tsx"
 export { AnchorLink } from "./RouterLink/AnchorLink.tsx"
 export {
   RouterLinkProvider,

package/src/sourceRules.test.ts

@@ -512,7 +512,20 @@ test("the barrel is the only place components are re-exported", async () => {
   // is too, while still being exported from the barrel — an app that
   // marks a destination current anywhere else must ask the same
   // question the same way.
-  expect(componentNames.length).toBe(58)
+  //
+  // `ReorderList` — a vertical list put in a different order, by
+  // two buttons or by dragging a handle — is +1 -> 59. It is the
+  // clearest case yet for the fleet's build-it-here rule: Docket
+  // had written the shape twice (a subtask checklist on HTML5
+  // `draggable`, which does not fire on touch at all, and a phase
+  // queue with the buttons and no drag), and `Board` had written
+  // it a third time correctly. So this one does not fork the
+  // geometry — it CALLS `useBoardDrag` with a single registered
+  // lane and the item selector pointed at its own rows, the way
+  // `VirtualizedGrid` calls `useAdaptiveColumns`. It renders no
+  // row, no handle and no buttons; `renderItem` is what lets one
+  // component serve three grids that have nothing in common.
+  expect(componentNames.length).toBe(59)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)