@charcuterie/ui 3.21.0 → 3.23.0

package/src/NavBar/NavBarLink.tsx

@@ -0,0 +1,139 @@
+import type { ControlSize } from "@charcuterie/tokens"
+import type { MouseEvent, ReactNode } from "react"
+
+import {
+  CONTROL_SIZE_CLASS,
+  PANEL_ITEM_SIZE_CLASS,
+} from "../controlStyles.ts"
+import { FOCUS_RING_CLASS } from "../intentStyles.ts"
+import { useRouterLink } from "../RouterLink/RouterLinkProvider.tsx"
+import { getIsRoutedHref } from "../RouterLink/routerLink.ts"
+import { toClassName } from "../toClassName.ts"
+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 const NavBarLink = ({
+  isCurrent,
+  item,
+  onNavigate,
+  placement,
+  size,
+  trackElement,
+}: NavBarLinkProps): ReactNode => {
+  const RouterLink = useRouterLink()
+
+  const LinkElement = getIsRoutedHref(item.href)
+    ? RouterLink
+    : "a"
+
+  const className =
+    placement === "bar"
+      ? toClassName(
+          "inline-flex shrink-0 items-center rounded-md border border-transparent whitespace-nowrap transition-colors duration-(--duration-fast) ease-standard",
+          CONTROL_SIZE_CLASS[size],
+          // Two written-out entries rather than one interpolated
+          // string, the same rule `SegmentedOption` follows:
+          // Tailwind's scanner cannot see a class that exists only
+          // at runtime, and `tailwindCandidates.test.ts` rejects a
+          // template literal in a className outright.
+          isCurrent
+            ? "bg-intent-neutral-surface font-medium text-content-primary"
+            : "text-content-secondary hover:bg-intent-neutral-surface hover:text-content-primary",
+          FOCUS_RING_CLASS,
+        )
+      : toClassName(
+          "flex w-full items-center rounded-sm text-start transition-colors duration-(--duration-fast) ease-standard",
+          PANEL_ITEM_SIZE_CLASS[size],
+          // `-hover`, not the plain surface: the panel is drawn on
+          // `surface-overlay`, which every dark scheme paints
+          // *lighter* than the base tint, so the plain one reads as
+          // no change at all. Same correction `MenuAction` carries.
+          isCurrent
+            ? "bg-intent-neutral-surface-hover font-medium text-content-primary"
+            : "text-content-primary hover:bg-intent-neutral-surface-hover",
+          FOCUS_RING_CLASS,
+        )
+
+  return (
+    <LinkElement
+      // The platform's own "you are here", and the reason the paint
+      // above is never the only signal: a highlight is invisible to
+      // a screen reader and to anyone who cannot tell the two
+      // surfaces apart.
+      aria-current={isCurrent ? "page" : undefined}
+      className={className}
+      href={item.href}
+      onClick={(event: MouseEvent<HTMLAnchorElement>) => {
+        if (
+          event.defaultPrevented ||
+          event.button !== 0 ||
+          event.altKey ||
+          event.ctrlKey ||
+          event.metaKey ||
+          event.shiftKey
+        ) {
+          return
+        }
+
+        onNavigate?.()
+      }}
+      ref={(element: HTMLAnchorElement | null) => {
+        trackElement?.(item.key ?? item.href, element)
+      }}
+    >
+      {item.icon === undefined ? null : (
+        // Decoration beside the item's own text. An icon that
+        // announces itself turns "Settings" into "gear Settings".
+        <span
+          aria-hidden="true"
+          className="shrink-0 text-content-secondary"
+        >
+          {item.icon}
+        </span>
+      )}
+
+      {item.label}
+    </LinkElement>
+  )
+}

package/src/NavBar/navBarCurrent.test.ts

@@ -0,0 +1,81 @@
+import { expect, test } from "vitest"
+
+import { getIsCurrentHref } from "./navBarCurrent.ts"
+
+const isCurrent = (currentHref: string, href: string) =>
+  getIsCurrentHref({ currentHref, href })
+
+test("a destination is current on its own path", () => {
+  expect(isCurrent("/backlog", "/backlog")).toBe(true)
+
+  expect(isCurrent("/backlog", "/board")).toBe(false)
+})
+
+/**
+ * A nav item names a **section**, and a section does not stop being
+ * the one you are in when you open something inside it.
+ */
+test("a parent path is current for its children", () => {
+  expect(isCurrent("/tasks/41", "/tasks")).toBe(true)
+
+  expect(isCurrent("/tasks/41/edit", "/tasks")).toBe(true)
+})
+
+/**
+ * The match is on whole segments. A bare `startsWith` marks `/task`
+ * as current for `/tasks`, which is a highlight on the wrong item
+ * and nothing to see in a review.
+ */
+test("a partial segment is not a match", () => {
+  expect(isCurrent("/tasks", "/task")).toBe(false)
+
+  expect(isCurrent("/backlogged", "/backlog")).toBe(false)
+})
+
+/**
+ * react-router's `<NavLink to="/">` is active on every route unless
+ * the caller remembers `end` — the footgun behind every "why is Home
+ * always highlighted" bug. The root matches only itself here, and
+ * there is no prop to change it.
+ */
+test("the root is exact", () => {
+  expect(isCurrent("/", "/")).toBe(true)
+
+  expect(isCurrent("/backlog", "/")).toBe(false)
+})
+
+/**
+ * Sorting a list does not move the reader to a different
+ * destination.
+ */
+test("the query string and the fragment are not part of the answer", () => {
+  expect(
+    isCurrent("/backlog?focus=search", "/backlog"),
+  ).toBe(true)
+
+  expect(isCurrent("/backlog#top", "/backlog")).toBe(true)
+
+  expect(
+    isCurrent("/backlog", "/backlog?focus=search"),
+  ).toBe(true)
+})
+
+test("a trailing slash is the same place", () => {
+  expect(isCurrent("/backlog/", "/backlog")).toBe(true)
+
+  expect(isCurrent("/backlog", "/backlog/")).toBe(true)
+})
+
+/**
+ * `undefined` is what a caller passes when it does not know, and the
+ * honest reading of that is that nothing is current — not that
+ * everything is.
+ */
+test("no current path marks nothing", () => {
+  expect(
+    getIsCurrentHref({
+      currentHref: undefined,
+      href: "/backlog",
+    }),
+  ).toBe(false)
+})

package/src/NavBar/navBarCurrent.ts

@@ -0,0 +1,64 @@
+/**
+ * Which destination the reader is on — the rule behind
+ * `aria-current="page"`, kept pure so it can be checked in Node.
+ *
+ * The library is router-agnostic (see `RouterLinkProvider`), so it
+ * cannot ask a router which link is active. The app hands it one
+ * string — `useLocation().pathname`, `window.location.pathname`,
+ * whatever it has — and this decides the rest.
+ *
+ * ## A parent path is current for its children
+ *
+ * `/tasks` is current while the reader is on `/tasks/41`, because a
+ * nav item names a **section** and a section does not stop being the
+ * one you are in when you open something inside it. The match is on
+ * whole segments: `/task` is *not* current for `/tasks`, which a bare
+ * `startsWith` would get wrong.
+ *
+ * ## `/` is exact, and that is deliberately not react-router
+ *
+ * react-router's `<NavLink to="/">` is active on **every** route
+ * unless the caller remembers `end`, which is the footgun behind
+ * every "why is Home always highlighted" bug in the fleet. The root
+ * matches only itself here, and there is no prop to change it: a nav
+ * with two current items is a nav that has stopped saying anything.
+ *
+ * ## The query string and the fragment are not part of the answer
+ *
+ * `/backlog?focus=search` is still the Backlog. Sorting a list does
+ * not move the reader to a different destination.
+ */
+
+const toComparablePath = (href: string): string => {
+  const path = href.split(/[#?]/u)[0] ?? ""
+
+  // A trailing slash is the same place, so it must not change the
+  // answer — but `/` itself has to survive being trimmed.
+  return path.length > 1 ? path.replace(/\/+$/u, "") : path
+}
+
+export const getIsCurrentHref = ({
+  currentHref,
+  href,
+}: {
+  /** Where the reader is. `undefined` means "nothing is current". */
+  currentHref: string | undefined
+  /** Where this destination goes. */
+  href: string
+}): boolean => {
+  if (currentHref === undefined) {
+    return false
+  }
+
+  const current = toComparablePath(currentHref)
+
+  const target = toComparablePath(href)
+
+  if (target === "" || target === "/") {
+    return current === target
+  }
+
+  return (
+    current === target || current.startsWith(`${target}/`)
+  )
+}

package/src/ReorderList/ReorderList.mdx

@@ -0,0 +1,83 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as ReorderListStories from "./ReorderList.stories";
+
+<Meta of={ReorderListStories} />
+
+# ReorderList
+
+A vertical list put in a different order — by two buttons, or by dragging a handle.
+
+<Canvas of={ReorderListStories.Default} />
+
+## Props
+
+<Controls />
+
+## Why the library owns this
+
+The shape had been written four times before this file existed. Docket wrote it twice: a
+subtask checklist on HTML5 `draggable`, and a phase queue with the buttons and no drag at
+all. `Board` wrote it once, properly, on Pointer Events. Four implementations of one
+behaviour is the case the fleet's build-it-here rule exists for.
+
+So this component does not fork the geometry — it **calls** `useBoardDrag` with a single
+registered lane and the item selector pointed at its own rows, the same way
+`VirtualizedGrid` calls `useAdaptiveColumns`. The snapshot, the movement threshold, the
+pointer capture and the drop-index arithmetic exist once in this package, and a fix to any
+of them reaches the board and the list together.
+
+## 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](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-19-the-board-owns-the-move-and-takes-no-drag-and-drop-dependency.md)
+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.
+
+`renderItem` therefore receives `moveBy`, `isFirst` and `isLast` **before** it receives
+`gripProps`, and a host that draws no handle at all is a supported host.
+
+## `draggable="true"` is the instinct this replaces
+
+Native HTML5 drag-and-drop costs nothing and is the wrong answer. It **does not fire on
+touch at all**, so a checklist built on it cannot be reordered on a tablet; its drag image is
+a browser-drawn ghost with no styling hook worth using; and `dataTransfer` is readable only
+inside a real `drop`, which makes a live drop indicator awkward for no gain.
+
+Pointer Events cost the same — nothing — and are one code path for mouse, touch and pen.
+`setPointerCapture` keeps the drag alive after the row has moved out from under the finger.
+
+The handle carries `touch-action: none`. Without it the browser claims the gesture for a
+scroll and the `pointermove` stream stops one frame in, which reads as "the drag works on my
+desktop and not on my tablet".
+
+## One row gets no controls
+
+<Canvas of={ReorderListStories.SingleItem} />
+
+A single item cannot be put anywhere else. `gripProps` comes back empty and `moveBy` does
+nothing, so a host cannot leave a dead handle on a one-row list by forgetting to check —
+which is the part every hand-rolled copy of this shape did forget.
+
+## What it deliberately does not render
+
+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 phase queue and a card list whose CSS
+grids have nothing in common. The library ships no icons either, so the position number
+doubling as the handle is the pattern to copy: a list that is ordered wants the number
+printed anyway.
+
+## The move is announced, with its position
+
+Every commit writes a sentence into a named `role="status"` region: *"Moved Sand the cut
+edge to position 2 of 5."* The **position** is there because "moved" leaves a screen-reader
+user unable to tell the top of a list from the bottom of thirty — the one piece of feedback
+a sighted user gets free from watching the row land, and the one every drag implementation
+forgets to say out loud.
+
+## `toIndex` is already corrected
+
+`onReorder(fromIndex, toIndex)` hands back an index into `items` that has already accounted
+for the row's own removal, so a handler is `splice(from, 1)` then `splice(to, 0, row)` with
+no arithmetic of its own. That is `toSettledIndex`, shared with `Board`.

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 />,
+}