@charcuterie/ui 3.22.0 → 3.24.0

package/src/NavBar/NavBar.tsx

@@ -1,271 +1,85 @@
-import { useVisibility } from "@charcuterie/logic"
 import type { ControlSize } from "@charcuterie/tokens"
 import type { Placement } from "@floating-ui/react"
 import type { ReactNode } from "react"
 
-import { Button } from "../Button/Button.tsx"
-import { IconButton } from "../IconButton/IconButton.tsx"
-import { usePanelItemSize } from "../Overlay/usePanelItemSize.ts"
-import { Popover } from "../Popover/Popover.tsx"
-import { useToolbarOverflow } from "../Toolbar/useToolbarOverflow.ts"
-import { toClassName } from "../toClassName.ts"
-import { NavBarLink } from "./NavBarLink.tsx"
-import { getIsCurrentHref } from "./navBarCurrent.ts"
+import { Nav } from "../Nav/Nav.tsx"
+import type { NavItem } from "../Nav/navItems.ts"
 
-export type NavBarItem = {
-  /**
-   * Where it goes. Routed through the injected `RouterLink` when it
-   * is this app's own path, and left to the platform when it is not.
-   */
-  href: string
-  /** Decoration beside the label. Never the accessible name. */
-  icon?: ReactNode
-  /** Defaults to `href`, which is already unique in a nav. */
-  key?: string
-  /** The visible text, and the accessible name. */
-  label: string
-}
+/**
+ * @deprecated Use `Nav`'s `NavItem`. Removed in the next major.
+ */
+export type NavBarItem = NavItem
 
+/**
+ * @deprecated Use `NavProps` with `layout="bar"`. Removed in the
+ * next major.
+ */
 export type NavBarProps = {
   className?: string
-  /**
-   * Where the reader is — `useLocation().pathname` in a
-   * react-router app. `aria-current="page"` is derived from it by
-   * `getIsCurrentHref`, which matches a parent path for its
-   * children and treats `/` as exact.
-   *
-   * Omitted means nothing is current, which is the honest answer on
-   * a route no destination owns.
-   */
   currentHref?: string
-  /**
-   * **Initial** only, and the bar owns it from then on — the same
-   * uncontrolled contract every other component here has. It exists
-   * so a story (and a screenshot) can show the menu open; an app
-   * almost never passes it.
-   */
   isMenuVisible?: boolean
   items: readonly NavBarItem[]
-  /**
-   * Required, and it becomes the `<nav>`'s `aria-label`. Two unnamed
-   * navigation landmarks in one page is axe's `landmark-unique`, and
-   * more to the point it is a screen reader announcing "navigation"
-   * twice with no way to tell which is the main one.
-   */
   label: string
-  /**
-   * Where the trigger sits in the bar's track once the row has
-   * folded. `"end"` when the header puts its own actions at the
-   * far edge, so the fold control joins them instead of hugging
-   * the wordmark with the whole track empty after it.
-   *
-   * It reaches **only** the folded row, which holds exactly one
-   * item — so it cannot disturb where the links sit when the bar
-   * is whole, and there is deliberately no prop that can.
-   */
   menuAlign?: "end" | "start"
-  /**
-   * The collapsed trigger's glyph. **No default** — the library
-   * ships no icons, and `☰` renders as nothing where the font lacks
-   * it. With no icon the trigger is a text button reading
-   * `menuLabel`, which works everywhere.
-   */
   menuIcon?: ReactNode
-  /**
-   * Names the trigger and, through it, the panel it opens. A
-   * `role="dialog"` takes no accessible name from its content.
-   */
   menuLabel?: string
   menuPlacement?: Placement
   size?: ControlSize
 }
 
 /**
- * The app's destinations as real links, in one line — folding into a
- * single menu button, whole, when that line does not fit.
- *
- * ## Why this is not `Toolbar`
- *
- * `Toolbar` already solves collapse-into-an-overflow, and this
- * component **reuses its measurement** (`useToolbarOverflow`) rather
- * than growing a second one. What it cannot reuse is the rendering:
- * a `ToolbarAction` is `{ label, onSelect }` and a collapsed one
- * becomes a `MenuItem`, so a nav folded into a `Toolbar` is a row of
- * `<button>`s. Navigation is an `<a href>` — see `NavBarLink`.
- *
- * The overflow is a `Popover` (`role="dialog"`) rather than a `Menu`
- * for the same reason: `role="menu"` permits only the `menuitem`
- * family, and a `menuitem` is something you *do*, not somewhere you
- * *go*.
- *
- * ## It folds WHOLE, and that is the decision
+ * @deprecated Use `Nav` with `layout="bar"` — which is `Nav`'s
+ * default, so `<Nav activeHref={…} items={…} label="Main" />` is the
+ * whole migration. **Removed in the next major.**
  *
- * `Toolbar` collapses **progressively** — items drop off the end one
- * at a time — because its items are ranked: the two things you do to
- * a running job matter more than the two you do to the deck. A nav
- * is not ranked. Its order is the shape of the product (Docket's
- * reads as the pipeline: Triage → Backlog → Phases → Board →
- * Archives), and a half-collapsed one splits that shape across two
- * places with no rule the reader can learn — "some of the app is up
- * here and the rest is behind a button" is worse than either whole
- * answer. So the bar shows **every** destination or **none**, and
- * the menu, when it opens, is the complete list in the product's own
- * order.
+ * This is now a thin adapter over `Nav` and keeps every behaviour it
+ * shipped with: the measured whole-row fold, the real `<a href>` in
+ * both the bar and the panel, and the same props under the same
+ * names. Only two things differ, and both are fixes:
  *
- * ## Measured, not breakpointed
+ * 1. `currentHref` is `activeHref` on `Nav`.
+ * 2. **Two items can no longer both be current.** This component
+ *    asked the question once per item, so a bar holding `/settings`
+ *    and `/settings/labels` marked *both* while the reader was on
+ *    the deeper one — against its own decision record, which says a
+ *    nav with two current items has stopped saying anything. `Nav`
+ *    takes the deepest match. If an app was relying on the parent
+ *    also lighting up, it was relying on a defect.
  *
- * There is no `collapseAt` prop and no media query. The bar reads
- * the width its links actually have and folds when their sum stops
- * fitting, so a longer label, a tenth destination, a
- * `data-density="kiosk"` or a reader at 175% browser zoom each move
- * the fold on their own. A hardcoded pixel number is wrong the first
- * time any of those changes — mux-magic collapses at `480px` and
- * plex-channels at `760px`, and neither number has a reason.
+ * ## Why it went away
  *
- * ⚠️ **The bar must not be sized by its own contents.** It measures
- * its own box to decide what to draw in it, so a container that
- * shrink-wraps makes the answer its own input: put it in a
- * `minmax(0, 1fr)` grid track or a `flex-1 min-w-0` row. The root
- * carries `min-w-0 flex-1` for the flex case; a grid track is the
- * caller's to declare. Same trap `useAdaptiveColumns` documents from
- * the other end.
- *
- * ## Mounted exactly once
- *
- * A destination is in the bar or in the panel, never both. The
- * fleet's habit is to render the whole nav twice and hide one copy
- * with `hidden md:flex` — mux-magic's `PageHeader` across two
- * ~55-line blocks, mail-sifter's `TriageQueue` again — which puts
- * every link in the DOM at every width, so an agent driving the page
- * finds two of each and cannot tell which one a human can see.
+ * It answered half the question. A horizontal row that folds is one
+ * shape an app's destinations take; a labelled side rail, a
+ * collapsed icon rail and a Narrow-View bottom strip are the others,
+ * and this component could not become any of them — so an app that
+ * wanted a rail was back to hand-rolling, which is the state this
+ * was built to end. `Nav` is the same list drawn in whichever of the
+ * five places fits, and `useNavLayout` is the width rule that says
+ * which.
  */
 export const NavBar = ({
   className,
   currentHref,
-  isMenuVisible = false,
+  isMenuVisible,
   items,
   label,
-  menuAlign = "start",
+  menuAlign,
   menuIcon,
-  menuLabel = "Menu",
-  menuPlacement = "bottom-start",
-  size = "sm",
-}: NavBarProps): ReactNode => {
-  const itemKeys = items.map(
-    (item) => item.key ?? item.href,
-  )
-
-  const { containerRef, trackItem, visibleCount } =
-    useToolbarOverflow({ itemKeys })
-
-  /**
-   * All or nothing. `visibleCount` is the progressive answer and
-   * this is the only thing read off it: the moment one link stops
-   * fitting, every link goes into the menu together.
-   *
-   * The hook's `trackTrigger` is deliberately not wired up, and the
-   * missing measurement costs nothing here. It exists so a
-   * progressive bar can ask "how many fit **beside a trigger**",
-   * which is a question this bar never asks: either every link fits
-   * with no trigger at all, or the row is one trigger and nothing
-   * else. `chooseVisibleCount` tests the whole-row case first and
-   * with the trigger costed at zero, so that branch is exact.
-   */
-  const isCollapsed = visibleCount < items.length
-
-  const { hide, isVisible, toggle } = useVisibility({
-    isVisible: isMenuVisible,
-  })
-
-  const panelItemSize = usePanelItemSize("lg")
-
-  const renderLink = (
-    item: NavBarItem,
-    placement: "bar" | "panel",
-  ) => (
-    <NavBarLink
-      isCurrent={getIsCurrentHref({
-        currentHref,
-        href: item.href,
-      })}
-      item={item}
-      key={item.key ?? item.href}
-      onNavigate={placement === "panel" ? hide : undefined}
-      placement={placement}
-      size={placement === "bar" ? size : panelItemSize}
-      trackElement={
-        placement === "bar" ? trackItem : undefined
-      }
-    />
-  )
-
-  const trigger =
-    menuIcon === undefined ? (
-      <Button
-        appearance="ghost"
-        intent="neutral"
-        onClick={toggle}
-        size={size}
-      >
-        {menuLabel}
-      </Button>
-    ) : (
-      <IconButton
-        appearance="ghost"
-        intent="neutral"
-        label={menuLabel}
-        onClick={toggle}
-        size={size}
-      >
-        {menuIcon}
-      </IconButton>
-    )
-
-  return (
-    <nav
-      aria-label={label}
-      className={toClassName(
-        "flex min-w-0 flex-1 items-center gap-1",
-        // Two written-out entries rather than one interpolated
-        // string: Tailwind's scanner cannot see a class that
-        // exists only at runtime.
-        isCollapsed && menuAlign === "end"
-          ? "justify-end"
-          : "justify-start",
-        className,
-      )}
-      ref={containerRef}
-    >
-      {isCollapsed ? (
-        <Popover
-          // The default panel is `max-w-xs p-3` — sized for a
-          // paragraph of prose. This one holds full-bleed rows that
-          // bring their own inset, so the padding shrinks to the
-          // gutter around them and the width is left to the list.
-          className="max-w-none p-1"
-          heading={menuLabel}
-          isVisible={isVisible}
-          onDismiss={hide}
-          placement={menuPlacement}
-          trigger={trigger}
-        >
-          {/*
-            A list, so a screen reader says how many destinations
-            there are before the reader starts down them — the one
-            thing the bar's own row communicates by simply being
-            visible all at once.
-          */}
-          <ul className="flex min-w-48 list-none flex-col gap-0.5">
-            {items.map((item) => (
-              <li key={item.key ?? item.href}>
-                {renderLink(item, "panel")}
-              </li>
-            ))}
-          </ul>
-        </Popover>
-      ) : (
-        items.map((item) => renderLink(item, "bar"))
-      )}
-    </nav>
-  )
-}
+  menuLabel,
+  menuPlacement,
+  size,
+}: NavBarProps): ReactNode => (
+  <Nav
+    activeHref={currentHref}
+    className={className}
+    isMenuVisible={isMenuVisible}
+    items={items}
+    label={label}
+    layout="bar"
+    menuAlign={menuAlign}
+    menuIcon={menuIcon}
+    menuLabel={menuLabel}
+    menuPlacement={menuPlacement}
+    size={size}
+  />
+)

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