@charcuterie/ui 3.22.0 → 3.24.0

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

@@ -276,12 +276,31 @@ export type {
 export { Menu } from "./Menu/Menu.tsx"
 export type { ModalProps } from "./Modal/Modal.tsx"
 export { Modal } from "./Modal/Modal.tsx"
+export type {
+  NavLayout,
+  NavProps,
+} from "./Nav/Nav.tsx"
+export { Nav } from "./Nav/Nav.tsx"
+export type {
+  NavItem,
+  NavRailItem,
+} from "./Nav/navItems.ts"
+export {
+  getIsCurrentHref,
+  resolveActiveKey,
+} from "./Nav/navItems.ts"
+export type {
+  NavLayoutMode,
+  NavLayoutState,
+  ResolvedNavLayout,
+  UseNavLayoutOptions,
+} from "./Nav/useNavLayout.ts"
+export { useNavLayout } from "./Nav/useNavLayout.ts"
 export type {
   NavBarItem,
   NavBarProps,
 } from "./NavBar/NavBar.tsx"
 export { NavBar } from "./NavBar/NavBar.tsx"
-export { getIsCurrentHref } from "./NavBar/navBarCurrent.ts"
 export type {
   PickerOption,
   PickerProps,
@@ -316,6 +335,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,32 @@ 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.
+  //
+  // `Nav` — the destinations as a rail, a collapsed icon rail or a
+  // bottom strip — is +1 -> 60. It is the other half of `NavBar`,
+  // which folds a horizontal row and cannot become a vertical one:
+  // no media query moves an element across `Shell`'s grid, so the
+  // rail is a different corner of the page rather than a restyling
+  // of the same one. Two members stay out of this count by the
+  // `<Name>/<Name>.tsx` rule and are exported from the barrel
+  // anyway — `navItems.ts`, because `resolveActiveKey` is the
+  // active-path rule an app's tests want to assert directly, and
+  // `useNavLayout.ts`, because the app has to read the width rule to
+  // know which corner to render into.
+  expect(componentNames.length).toBe(60)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)

package/dist/NavBar/NavBarLink.d.ts

@@ -1,43 +0,0 @@
-import type { ControlSize } from "@charcuterie/tokens";
-import type { ReactNode } from "react";
-import type { NavBarItem } from "./NavBar.tsx";
-export type NavBarLinkProps = {
-    isCurrent: boolean;
-    item: NavBarItem;
-    /**
-     * Fires when the reader activates this link **in a way that keeps
-     * them on the page** — a plain left click, Enter, Space. It is
-     * what closes the collapsed panel behind them.
-     *
-     * A modified click (ctrl, meta, shift, alt) opens a new tab and
-     * leaves this document exactly where it was, so it deliberately
-     * does not fire: shutting the menu the reader is still working
-     * through is the behaviour that makes people stop ctrl-clicking.
-     */
-    onNavigate?: () => void;
-    /** Where it is drawn. A bar row and a panel row paint differently. */
-    placement: "bar" | "panel";
-    size: ControlSize;
-    /** Hands the bar row's box to the measuring hook. Bar only. */
-    trackElement?: (key: string, element: HTMLElement | null) => void;
-};
-/**
- * One destination, drawn either in the bar or in the collapsed
- * panel — and it is a real `<a href>` in both.
- *
- * That is the whole reason this component exists rather than the
- * `Menu` a collapsed `Toolbar` opens: `MenuItem` is `{ label,
- * onSelect }`, so a nav folded into one becomes a row of
- * `<button>`s. It looks identical in a screenshot and it loses
- * middle-click, ctrl-click, "open in a new tab", "copy link
- * address", the status bar, and the browser's own visited styling.
- * `BuildingAnApp.mdx` names `<button onClick={navigate}>` as the
- * fleet's most common navigation defect; a collapse mechanism that
- * introduced it at narrow widths would be that defect on a timer.
- *
- * The router seam is `ButtonLink`'s, unchanged: an external
- * destination or a fragment falls back to a plain anchor rather than
- * being pushed onto a history stack that has no route for it.
- */
-export declare const NavBarLink: ({ isCurrent, item, onNavigate, placement, size, trackElement, }: NavBarLinkProps) => ReactNode;
-//# sourceMappingURL=NavBarLink.d.ts.map

package/dist/NavBar/NavBarLink.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"NavBarLink.d.ts","sourceRoot":"","sources":["../../src/NavBar/NavBarLink.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AACtD,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,OAAO,CAAA;AAUlD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAE9C,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,IAAI,EAAE,UAAU,CAAA;IAChB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,IAAI,CAAA;IACvB,sEAAsE;IACtE,SAAS,EAAE,KAAK,GAAG,OAAO,CAAA;IAC1B,IAAI,EAAE,WAAW,CAAA;IACjB,+DAA+D;IAC/D,YAAY,CAAC,EAAE,CACb,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,WAAW,GAAG,IAAI,KACxB,IAAI,CAAA;CACV,CAAA;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,UAAU,GAAI,iEAOxB,eAAe,KAAG,SA4EpB,CAAA"}