@charcuterie/ui 3.0.0 → 3.1.0

package/src/Board/useBoardDrag.ts

@@ -0,0 +1,413 @@
+import {
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react"
+
+import type {
+  BoardDropLane,
+  BoardDropTarget,
+  BoardRect,
+} from "./boardMove.ts"
+import { chooseDropTarget } from "./boardMove.ts"
+
+/**
+ * Pointer dragging for the board — **on Pointer Events, with no
+ * drag-and-drop dependency**, and the reasoning is written down in
+ * `docs/decisions/2026-08-19-the-board-owns-the-move-and-takes-no-drag-and-drop-dependency.md`.
+ *
+ * The short version: a published design system's dependency list is
+ * inherited by every consumer, `castkit/packages/slatecast` has 60 KB
+ * gzipped to spend in total, and the two candidates cost 12–30 KB
+ * before a card has been drawn. What they buy is sensors, collision
+ * strategies, and sortable animation — a general solution to a
+ * problem this component has a specific version of: one card, from
+ * one lane, into one other lane.
+ *
+ * ### Pointer Events rather than HTML5 drag-and-drop
+ *
+ * `draggable="true"` is the zero-dependency instinct and it is the
+ * wrong one. It does not fire on touch at all — so the Narrow View,
+ * the kiosk density, and the tablet the owner actually reads this on
+ * get nothing — 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.
+ * Pointer Events are one code path for mouse, touch and pen, and
+ * `setPointerCapture` means the drag survives the pointer leaving the
+ * card, the lane, and the window.
+ *
+ * ### Every rectangle is measured once, at grab
+ *
+ * Re-measuring on each `pointermove` reads more correct and is
+ * worse. The drop indicator is a real element; inserting it moves
+ * the cards below it; the next move measures the moved cards and
+ * computes a different index; the indicator jumps back. That
+ * feedback loop is why the indicator here is `position: absolute`
+ * against a snapshot taken at grab — the layout under the pointer
+ * is frozen for the length of the drag, so the number the person
+ * sees and the number that gets committed are the same number.
+ *
+ * The cost is honest and small: a lane that reflows mid-drag (a live
+ * agent-run line wrapping to two lines) is measured stale. A board
+ * where that matters wants a re-snapshot on `ResizeObserver`, which
+ * is a change to this file and to nothing else.
+ */
+
+/**
+ * How far the pointer has to travel before a press becomes a drag.
+ *
+ * Without it the handle is a button that cannot be clicked: every
+ * mouse-down/up pair carries a pixel or two of movement, and a
+ * "drag" of one pixel would commit a move and swallow the click that
+ * was meant to open the move menu. Four device-independent pixels is
+ * the usual figure and it is comfortably below a deliberate drag.
+ */
+const DRAG_THRESHOLD_PX = 4
+
+export type BoardDragOrigin = {
+  fromIndex: number
+  fromLaneKey: string
+  itemKey: string
+}
+
+export type BoardDragState = BoardDragOrigin & {
+  /**
+   * Where the indicator is drawn, in pixels from the top of the
+   * target lane's list box. `null` while the pointer is over no
+   * lane the snapshot knows about.
+   */
+  indicatorOffset: number | null
+  target: BoardDropTarget | null
+}
+
+type LaneSnapshot = BoardDropLane & {
+  gap: number
+  listTop: number
+}
+
+const toRect = (element: Element): BoardRect => {
+  const rect = element.getBoundingClientRect()
+
+  return {
+    height: rect.height,
+    left: rect.left,
+    top: rect.top,
+    width: rect.width,
+  }
+}
+
+/**
+ * Where the line goes for a given insertion index — the midpoint of
+ * the gap the card would be dropped into, in the list's own
+ * coordinates.
+ *
+ * Split out and exported because it is the one piece of this file
+ * that is pure arithmetic over the snapshot, and the three cases
+ * (before everything, between two, after everything) are exactly
+ * where an off-by-one lives.
+ */
+export const getIndicatorOffset = (
+  lane: LaneSnapshot,
+  index: number,
+): number => {
+  const { cardRects, gap, listTop } = lane
+
+  if (cardRects.length === 0) {
+    return 0
+  }
+
+  const previous = cardRects[index - 1]
+
+  const next = cardRects[index]
+
+  if (!previous) {
+    return (
+      (cardRects[0]?.top ?? listTop) - listTop - gap / 2
+    )
+  }
+
+  if (!next) {
+    return (
+      previous.top + previous.height - listTop + gap / 2
+    )
+  }
+
+  return (
+    (previous.top + previous.height + next.top) / 2 -
+    listTop
+  )
+}
+
+export const useBoardDrag = ({
+  onDrop,
+}: {
+  onDrop: (
+    origin: BoardDragOrigin,
+    target: BoardDropTarget,
+  ) => void
+}): {
+  drag: BoardDragState | null
+  registerLane: (
+    laneKey: string,
+  ) => (element: HTMLElement | null) => void
+  startDrag: (
+    pointerEvent: {
+      clientX: number
+      clientY: number
+      currentTarget: EventTarget & Element
+      pointerId: number
+    },
+    origin: BoardDragOrigin,
+  ) => void
+} => {
+  const laneElements = useRef(
+    new Map<string, HTMLElement>(),
+  )
+
+  const snapshot = useRef<LaneSnapshot[]>([])
+
+  const [drag, setDrag] = useState<BoardDragState | null>(
+    null,
+  )
+
+  /**
+   * The live drag, readable from a listener that was registered
+   * once. The listeners below are attached for the whole life of the
+   * component rather than added and removed per drag — re-attaching
+   * on every state change is how a `pointerup` gets missed — so they
+   * cannot close over `drag` itself.
+   */
+  const dragRef = useRef<BoardDragState | null>(null)
+
+  const setDragState = useCallback(
+    (next: BoardDragState | null) => {
+      dragRef.current = next
+
+      setDrag(next)
+    },
+    [],
+  )
+
+  const registerLane = useCallback(
+    (laneKey: string) => (element: HTMLElement | null) => {
+      if (element) {
+        laneElements.current.set(laneKey, element)
+
+        return
+      }
+
+      laneElements.current.delete(laneKey)
+    },
+    [],
+  )
+
+  const takeSnapshot = useCallback(() => {
+    snapshot.current = Array.from(
+      laneElements.current,
+      ([key, element]) => {
+        const cardElements = Array.from(
+          element.querySelectorAll("[data-board-card]"),
+        )
+
+        return {
+          cardRects: cardElements.map(toRect),
+          gap:
+            Number.parseFloat(
+              globalThis.getComputedStyle(element).rowGap,
+            ) || 0,
+          key,
+          listTop: element.getBoundingClientRect().top,
+          rect: toRect(element),
+        }
+      },
+    )
+  }, [])
+
+  const moveTo = useCallback(
+    (point: { x: number; y: number }) => {
+      const origin = dragRef.current
+
+      if (!origin) {
+        return
+      }
+
+      const target = chooseDropTarget(
+        snapshot.current,
+        point,
+      )
+
+      const lane = snapshot.current.find(
+        (one) => one.key === target?.laneKey,
+      )
+
+      setDragState({
+        ...origin,
+        indicatorOffset:
+          lane && target
+            ? getIndicatorOffset(lane, target.index)
+            : null,
+        target,
+      })
+    },
+    [setDragState],
+  )
+
+  const startDrag = useCallback(
+    (
+      pointerEvent: {
+        clientX: number
+        clientY: number
+        currentTarget: EventTarget & Element
+        pointerId: number
+      },
+      origin: BoardDragOrigin,
+    ) => {
+      const handle = pointerEvent.currentTarget
+
+      const startX = pointerEvent.clientX
+
+      const startY = pointerEvent.clientY
+
+      // The capture goes on the handle, so `pointermove` keeps
+      // arriving after the pointer has left it — which it does
+      // immediately, because the card it is dragging moves out from
+      // under it.
+      if (handle instanceof HTMLElement) {
+        handle.setPointerCapture?.(pointerEvent.pointerId)
+      }
+
+      const onPointerMove = (moveEvent: PointerEvent) => {
+        if (
+          moveEvent.pointerId !== pointerEvent.pointerId
+        ) {
+          return
+        }
+
+        if (
+          !dragRef.current &&
+          Math.hypot(
+            moveEvent.clientX - startX,
+            moveEvent.clientY - startY,
+          ) < DRAG_THRESHOLD_PX
+        ) {
+          return
+        }
+
+        if (!dragRef.current) {
+          takeSnapshot()
+
+          setDragState({
+            ...origin,
+            indicatorOffset: null,
+            target: null,
+          })
+        }
+
+        // A touch drag scrolls the page unless something says
+        // otherwise, and `touch-action: none` on the handle only
+        // covers the handle. This covers the rest of the gesture.
+        moveEvent.preventDefault()
+
+        moveTo({
+          x: moveEvent.clientX,
+          y: moveEvent.clientY,
+        })
+      }
+
+      const finish = (isCommitted: boolean) => {
+        globalThis.removeEventListener(
+          "pointermove",
+          onPointerMove,
+        )
+
+        globalThis.removeEventListener("pointerup", onUp)
+
+        globalThis.removeEventListener(
+          "pointercancel",
+          onCancel,
+        )
+
+        const live = dragRef.current
+
+        setDragState(null)
+
+        if (!live) {
+          return
+        }
+
+        /**
+         * A pointer sequence that ends on the element it started
+         * from still fires a `click`, and the element it started
+         * from is a button that opens the move menu. Without this,
+         * every completed drag lands the card and then opens a menu
+         * on top of it.
+         *
+         * Swallowed in the **capture** phase and `once`, so it
+         * consumes exactly the synthetic click this gesture
+         * produced and nothing after it. A `hasDragged` flag on the
+         * card would be the same idea with a lifetime nobody owns.
+         */
+        globalThis.addEventListener(
+          "click",
+          (clickEvent) => {
+            clickEvent.preventDefault()
+
+            clickEvent.stopPropagation()
+          },
+          { capture: true, once: true },
+        )
+
+        if (isCommitted && live.target) {
+          onDrop(origin, live.target)
+        }
+      }
+
+      const onUp = (upEvent: PointerEvent) => {
+        if (upEvent.pointerId === pointerEvent.pointerId) {
+          finish(true)
+        }
+      }
+
+      const onCancel = () => {
+        finish(false)
+      }
+
+      globalThis.addEventListener(
+        "pointermove",
+        onPointerMove,
+        { passive: false },
+      )
+
+      globalThis.addEventListener("pointerup", onUp)
+
+      globalThis.addEventListener("pointercancel", onCancel)
+    },
+    [moveTo, onDrop, setDragState, takeSnapshot],
+  )
+
+  /**
+   * Escape abandons the drag, and it is registered for the life of
+   * the component rather than for the life of a drag. A listener
+   * added when a drag starts is a listener that leaks when the
+   * component unmounts mid-drag — which is exactly what a route
+   * change during a drag does.
+   */
+  useEffect(() => {
+    const onKeyDown = (keyEvent: KeyboardEvent) => {
+      if (keyEvent.key === "Escape" && dragRef.current) {
+        keyEvent.preventDefault()
+
+        setDragState(null)
+      }
+    }
+
+    globalThis.addEventListener("keydown", onKeyDown)
+
+    return () => {
+      globalThis.removeEventListener("keydown", onKeyDown)
+    }
+  }, [setDragState])
+
+  return { drag, registerLane, startDrag }
+}

package/src/Checkbox/Checkbox.tsx

@@ -157,9 +157,18 @@ export const Checkbox = ({
           // No `disabled:` colour override; the wrapper's `opacity-60`
           // does the dimming, and doubling it on the box is what made a
           // disabled checkbox vanish.
+          // `indeterminate:` wears the same fill as `checked:`. It is
+          // the state a *group* box is in when some of its members are
+          // ticked, and it cannot be written in markup at all —
+          // `indeterminate` is a DOM property with no HTML attribute —
+          // so the only way to reach it is a consumer writing to the
+          // input. `DataTable`'s select-all box does exactly that, and
+          // before this line it painted **nothing**: the property was
+          // set, screen readers announced "mixed", and the box on
+          // screen was indistinguishable from empty.
           isReadOnly
-            ? "border-border-default checked:border-intent-neutral-solid checked:bg-intent-neutral-solid"
-            : "border-border-strong checked:border-intent-accent-solid checked:bg-intent-accent-solid",
+            ? "border-border-default checked:border-intent-neutral-solid checked:bg-intent-neutral-solid indeterminate:border-intent-neutral-solid indeterminate:bg-intent-neutral-solid"
+            : "border-border-strong checked:border-intent-accent-solid checked:bg-intent-accent-solid indeterminate:border-intent-accent-solid indeterminate:bg-intent-accent-solid",
           isDisabled
             ? "cursor-not-allowed"
             : isReadOnly
@@ -202,7 +211,7 @@ export const Checkbox = ({
       <svg
         aria-hidden="true"
         className={toClassName(
-          "pointer-events-none invisible absolute peer-checked:visible",
+          "pointer-events-none invisible absolute peer-checked:visible peer-indeterminate:invisible",
           // Matches whichever fill the box wears, so the tick keeps its
           // guaranteed on-solid contrast in either intent.
           isReadOnly
@@ -219,6 +228,28 @@ export const Checkbox = ({
       >
         <path d="M20 6 9 17l-5-5" />
       </svg>
+
+      {/* The mixed mark — a dash, not a tick. Its own element rather
+          than a second `<path>` in the tick's `<svg>`, because the
+          two states have to be able to hide independently and a
+          `<path>` cannot carry a `peer-*` variant of its own. */}
+      <svg
+        aria-hidden="true"
+        className={toClassName(
+          "pointer-events-none invisible absolute peer-indeterminate:visible",
+          isReadOnly
+            ? "text-intent-neutral-on-solid"
+            : "text-intent-accent-on-solid",
+          CHECK_SIZE_CLASS[size],
+        )}
+        fill="none"
+        stroke="currentColor"
+        strokeLinecap="round"
+        strokeWidth={3}
+        viewBox="0 0 24 24"
+      >
+        <path d="M6 12h12" />
+      </svg>
     </span>
 
     <span>{label}</span>

package/src/DataTable/DataTable.mdx

@@ -0,0 +1,123 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as DataTableStories from "./DataTable.stories";
+
+<Meta of={DataTableStories} />
+
+# DataTable
+
+**A table that reflows instead of scrolling, sized by its container.** Columns, rows, an
+optional selection column, and the sort *announcement* — the data itself stays the
+consumer's.
+
+<Canvas of={DataTableStories.Default} />
+
+## Props
+
+<Controls />
+
+## It composes `SortableTableHeader`
+
+Every sortable column renders [`SortableTableHeader`](?path=/docs/components-sortabletableheader--docs),
+which shipped first and stays shipped. It is in a published `1.0.0` with a consumer of its
+own, so subsuming it would have been a breaking change bought for nothing — and there is
+value in exactly one place in the fleet knowing that `aria-sort` belongs on the `<th>` while
+the click target is a `<button>` inside it.
+
+That composition is also why this is a **real `<table>`** rather than a grid of
+`<div role="row">`s: a div grid cannot host a `<th>` at all, so it would have meant either
+duplicating the header component or breaking it.
+
+| | `<table>` | `<div role="grid">` |
+| --- | --- | --- |
+| Hosts `SortableTableHeader` | yes | no |
+| Column widths | the browser's auto layout, free | you write the track list |
+| Screen-reader table mode | native | depends on the roles being complete |
+| Keyboard model | ordinary controls in document order | a roving focus you now own |
+
+A `grid` is the right answer for a spreadsheet — cell-by-cell arrow navigation, editable
+cells. This is a **table**: rows of data with the odd control in them.
+
+## Narrow means reflow, never a sideways scroll
+
+<Canvas of={DataTableStories.Responsive} />
+
+Below `--cq-md` (32rem) each row becomes a labelled block — the column name beside its
+value — and the header row wraps into a strip of sort controls that stays reachable. Above
+it, an ordinary table.
+
+The two alternatives, and why neither:
+
+- **Horizontal scroll.** WCAG 2.2 SC 1.4.10 (Reflow) exists because of it, and the consumer
+  this was built for bans it outright: *"No horizontal scroll, ever."* A pan surface also
+  hides the *existence* of the off-screen columns.
+- **Dropping low-priority columns.** Cheapest to build, and the only option that loses data:
+  the assignee column does not come back, and no gesture asks for it.
+
+## Container queries, never a media query
+
+The width that decides the layout is **this element's**, not the window's. A table in a
+three-up board lane is narrow on a 4K monitor, and a reader browsing at 175% zoom has ~860
+effective pixels in a 1500px window — so a `@media (max-width: …)` here is measuring
+something that is not the question.
+
+The `@container` is declared on the wrapper and queried by its descendants, because
+[a container query never matches the element that declares it](?path=/docs/guides-building-an-app--docs).
+`Responsive` is the only honest way to see it: three widths, one window, no viewport change
+at all.
+
+## What it does not own
+
+<Canvas of={DataTableStories.AllVariants} />
+
+**Sorting the data.** `sort` says which column is sorted; `onSortChange` asks for a
+different one; the rows arrive already ordered. Comparing two values is per-column app logic
+— `priority` in the stories sorts high → medium → low, which is not its alphabetical order —
+and a table that sorted itself would need a comparator per column to do it, which is the
+same code in a worse place.
+
+**The selected set.** `selection.selectedRowKeys` is authoritative and lives with the
+consumer, because every *use* of a selection — the count in a toolbar, the bulk action, the
+undo — is outside this component. That is the opposite of
+[`Checkbox`](?path=/docs/components-checkbox--docs), and for a stated reason: the platform
+owns one checkbox's checkedness, and nothing at all owns "these five rows".
+
+**Column widths.** No drag handle and no measured layout. The browser's own auto table
+layout sizes columns to their content, and `column.className` overrides it — `w-32` on a
+column lands on that column's `<th>` and every one of its `<td>`s. Drag-to-resize is a
+*persistence* question (whose widths, stored where, keyed on what) that a component cannot
+answer for its consumer.
+
+**Virtualisation.** Deliberately absent. Every row is in the DOM, which is what keeps the
+accessibility tree honest and the auto column layout possible; the measurements and the
+cliff are in
+[the decision record](https://github.com/Sawtaytoes/charcuterie/blob/master/docs/decisions/2026-08-19-the-data-table-composes-sortabletableheader-reflows-and-does-not-virtualise.md).
+Past a few thousand rows, filter or page — a virtualised table is a different component,
+because it has to fix row heights and column widths to work at all.
+
+## Selection is written to the input, not re-mounted
+
+<Canvas of={DataTableStories.AllStates} />
+
+`Checkbox` is uncontrolled by design — `isChecked` seeds the first paint and the `<input>`
+is the store from then on. Keeping a controlled `selectedRowKeys` authoritative therefore
+means **writing to the store**: an effect sets `input.checked` on every render. The
+alternative, a state-bearing `key` that re-mounts the box, throws the focus away one row
+into a keyboard pass down the column.
+
+It is also the only way to express the header box's third state: `indeterminate` is a DOM
+property with **no HTML attribute at all**, so no markup could have set it.
+
+The row carries `data-is-selected` for the paint, and **not** `aria-selected`: that property
+belongs to `grid` and `treegrid` rows. In a `table`, the row's own checkbox is what states
+the fact — and it is a control that can also change it.
+
+## Keyboard
+
+<Canvas of={DataTableStories.Interactive} />
+
+There is no custom key handling, and that is the design. `Tab` reaches each sortable
+header's button and each row's checkbox in document order; `Enter`/`Space` sorts; `Space`
+ticks. A table is not a `grid`, so there is no roving focus and no arrow-key cell
+navigation — a screen reader's own table mode moves through the data, and everything
+interactive is a real control the browser already knows how to reach.