@charcuterie/ui 3.20.0 → 3.22.0

package/src/DropRail/DropRail.tsx

@@ -0,0 +1,496 @@
+import {
+  useLatestRef,
+  useRovingFocus,
+  useUniqueId,
+} from "@charcuterie/logic"
+import type { ReactNode } from "react"
+import { useEffect, useRef, useState } from "react"
+
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+
+export type DropRailTarget = {
+  /**
+   * A number after the label — a lane's size, a project's open
+   * count. Optional, and absent is a real answer: a rail of
+   * destinations that have no size should not print a zero on every
+   * chip.
+   */
+  count?: number
+  /**
+   * Where the thing being moved already is. It stays **visible and
+   * unofferable** rather than being filtered out, because a rail
+   * whose contents change depending on what you grabbed is a rail
+   * whose chips move under the pointer between one move and the
+   * next — and muscle memory is the only reason this control is
+   * faster than a menu.
+   */
+  isCurrent?: boolean
+  isDisabled?: boolean
+  key: string
+  label: string
+  /** A leading glyph the app owns — an emoji, a dot, an icon. */
+  mark?: ReactNode
+}
+
+export type DropRailProps = {
+  className?: string
+  /**
+   * Whether the rail is showing. The host owns this, because only
+   * the host knows a move started — and it is the same boolean
+   * whether the move began as a pointer drag or as a tap on a
+   * handle.
+   */
+  isOpen: boolean
+  /** The rail's accessible name. Required — it is a listbox. */
+  label: string
+  onDismiss?: () => void
+  onPick: (targetKey: string) => void
+  targets: readonly DropRailTarget[]
+}
+
+/**
+ * The attribute the pointer hit test reads. A `data-` attribute
+ * rather than a class, for the same reason `Board` marks its cards
+ * with one: a class is a style and may be renamed by a consumer's
+ * tooling, and this is a contract with a hit test.
+ */
+const TARGET_ATTRIBUTE = "data-drop-rail-target"
+
+const TARGET_SELECTOR = "[data-drop-rail-target]"
+
+/**
+ * Every destination at once, brought to the pointer instead of the
+ * pointer being carried to it.
+ *
+ * ### The measurement this exists for
+ *
+ * `Board` moves a card with a `Menu` on the card, and that is the
+ * right control for a board: three or four lanes, all on screen, and
+ * the menu opens where your hand already is. It stops being the
+ * right control at the size the fleet's real lists reach. Docket's
+ * Backlog draws **34 project groups down one page**, of which about
+ * four fit on a display. Dragging a card from the first to the
+ * thirty-fourth means holding a pointer down while the page scrolls,
+ * and a menu of 34 items is a scrolling list inside a popup — the
+ * same problem in a smaller box.
+ *
+ * A rail answers both. It pins to the top for the length of the
+ * move, so nothing is ever off screen, and there is no travel: every
+ * destination is the same short distance away.
+ *
+ * ### One control, three drivers, and that is the whole design
+ *
+ * WCAG 2.5.7 requires a single-pointer alternative to any dragging
+ * movement, and `FileDropZone` next door says the same thing about
+ * its own gesture: build the accessible path first and let the drag
+ * be the enhancement. So the rail is **not** a drag affordance with
+ * a fallback bolted on. It is a listbox that three things drive:
+ *
+ *  1. **Pointer.** While a button is held, the chip under the
+ *     pointer is active and releasing over it commits.
+ *  2. **Tap.** Opened with no button held, it is a list you touch.
+ *     Identical markup, identical commit.
+ *  3. **Keyboard.** Arrow keys walk it, Enter commits, Escape
+ *     abandons. `useRovingFocus` owns which chip is tabbable, so
+ *     there is no second keyboard model in this file to drift out of
+ *     step with `Listbox`.
+ *
+ * The rail does not know which of the three opened it, and the host
+ * does not have to say. It reads `event.buttons` on the first
+ * pointer event it sees: a button already down means a drag is in
+ * flight, and nothing else needs threading through.
+ *
+ * ### It takes no drag-and-drop dependency, and it hit-tests chips
+ *
+ * The board's decision priced four libraries and took none of them,
+ * because a published library's dependency list is inherited by
+ * every consumer — including one with 60 KB gzipped to spend in
+ * total. Nothing here changes that arithmetic, and this needs far
+ * less than `Board` does: a chip is a box under the pointer, so
+ * `elementFromPoint` answers the only geometric question there is.
+ * No snapshot, no collision strategy, no sortable transform.
+ *
+ * ### It is not `Rail`, and the two must not be confused
+ *
+ * `Rail` is the app shell's side rail — a landmark, an `<aside>` or
+ * a `<nav>`, permanent furniture down one edge of a page. This is a
+ * horizontal strip of drop targets that exists only for the length
+ * of a move, and it is a `listbox`. They share four letters and
+ * nothing else. `FileDropZone` sets the precedent for the prefix
+ * carrying the distinction.
+ *
+ * ### What it deliberately does not do
+ *
+ * It does not render the thing being dragged, own the handle, or
+ * know what a move means. The host keeps all three, which is what
+ * lets the same rail sit above a board, a card grid, or a list of
+ * accordions without any of them being modelled here.
+ */
+export const DropRail = ({
+  className,
+  isOpen,
+  label,
+  onDismiss,
+  onPick,
+  targets,
+}: DropRailProps): ReactNode => {
+  const baseId = useUniqueId()
+
+  const railRef = useRef<HTMLDivElement>(null)
+
+  /**
+   * A pointer button was already down when the rail opened, so this
+   * move is a drag and it commits on release. A tap-opened rail
+   * commits on click instead, and the two must not both fire — a
+   * released drag also produces a `click`.
+   */
+  const isPointerDriven = useRef(false)
+
+  /**
+   * Focus is moved into the rail once per open, not once per render.
+   * Without the latch the effect below re-runs whenever the host
+   * re-renders and drags focus back to the first chip, which
+   * undoes every arrow key the moment anything above updates.
+   */
+  const hasTakenFocus = useRef(false)
+
+  const [announcement, setAnnouncement] = useState("")
+
+  const offerableKeys = targets
+    .filter(
+      (target) => !target.isCurrent && !target.isDisabled,
+    )
+    .map((target) => target.key)
+
+  /**
+   * The offerable keys as one string, because the effects below
+   * depend on *which* destinations are offerable and none of them
+   * may depend on the array's identity.
+   *
+   * `targets` is almost always a literal in the host's render, so
+   * the array is new on every render. An effect keyed on it
+   * re-registers every chip each time, and re-registering loses the
+   * active one — which during a keyboard walk means the arrow keys
+   * stop moving for no reason a consumer could ever debug.
+   */
+  const offerableKeysText = offerableKeys.join(" ")
+
+  const firstOfferableKey = offerableKeys[0]
+
+  const {
+    activeValue,
+    next,
+    previous,
+    register,
+    setActiveValue,
+  } = useRovingFocus<string>({ isWrapping: true })
+
+  /**
+   * Read by the global listeners, which are registered once per
+   * open rather than once per render. Without them the pointer
+   * handler closes over a stale `activeValue`, and Enter commits
+   * whichever chip was active when the rail opened.
+   */
+  const activeValueRef = useLatestRef(activeValue)
+
+  const offerableKeysRef = useLatestRef(offerableKeys)
+
+  const onDismissRef = useLatestRef(onDismiss)
+
+  const onPickRef = useLatestRef(onPick)
+
+  const targetsRef = useLatestRef(targets)
+
+  useEffect(() => {
+    const releases = offerableKeysText
+      .split(" ")
+      .filter((key) => key !== "")
+      .map((key) => register(key))
+
+    return () => {
+      for (const release of releases) {
+        release()
+      }
+    }
+  }, [offerableKeysText, register])
+
+  /**
+   * Closing resets everything a reopen must not inherit. Without it
+   * a rail reopened for a different card starts on whatever the last
+   * move chose, and the first arrow key moves from a place the
+   * person never went.
+   */
+  useEffect(() => {
+    if (isOpen) {
+      return
+    }
+
+    setActiveValue(null)
+
+    isPointerDriven.current = false
+
+    hasTakenFocus.current = false
+
+    setAnnouncement("")
+  }, [isOpen, setActiveValue])
+
+  useEffect(() => {
+    if (!isOpen) {
+      return undefined
+    }
+
+    const commit = (targetKey: string) => {
+      const target = targetsRef.current.find(
+        (one) => one.key === targetKey,
+      )
+
+      if (target) {
+        setAnnouncement(`Moved to ${target.label}.`)
+      }
+
+      onPickRef.current(targetKey)
+    }
+
+    const getKeyAt = (clientX: number, clientY: number) => {
+      const chip = globalThis.document
+        .elementFromPoint(clientX, clientY)
+        ?.closest(TARGET_SELECTOR)
+
+      return chip?.getAttribute(TARGET_ATTRIBUTE) ?? null
+    }
+
+    const getIsOfferable = (key: string | null) =>
+      key !== null && offerableKeysRef.current.includes(key)
+
+    const onPointerMove = (pointerEvent: PointerEvent) => {
+      if (pointerEvent.buttons === 0) {
+        return
+      }
+
+      isPointerDriven.current = true
+
+      const key = getKeyAt(
+        pointerEvent.clientX,
+        pointerEvent.clientY,
+      )
+
+      // `null` when the pointer is between chips or off the rail
+      // entirely, and that has to clear the highlight. A rail that
+      // keeps the last chip lit is telling you it will land
+      // somewhere it will not.
+      setActiveValue(getIsOfferable(key) ? key : null)
+    }
+
+    const onPointerUp = (pointerEvent: PointerEvent) => {
+      if (!isPointerDriven.current) {
+        return
+      }
+
+      const key = getKeyAt(
+        pointerEvent.clientX,
+        pointerEvent.clientY,
+      )
+
+      if (getIsOfferable(key) && key !== null) {
+        commit(key)
+
+        return
+      }
+
+      onDismissRef.current?.()
+    }
+
+    const onKeyDown = (keyEvent: KeyboardEvent) => {
+      if (keyEvent.key === "Escape") {
+        keyEvent.preventDefault()
+
+        onDismissRef.current?.()
+
+        return
+      }
+
+      if (
+        keyEvent.key === "ArrowRight" ||
+        keyEvent.key === "ArrowDown"
+      ) {
+        keyEvent.preventDefault()
+
+        next()
+
+        return
+      }
+
+      if (
+        keyEvent.key === "ArrowLeft" ||
+        keyEvent.key === "ArrowUp"
+      ) {
+        keyEvent.preventDefault()
+
+        previous()
+
+        return
+      }
+
+      const isCommitKey =
+        keyEvent.key === "Enter" || keyEvent.key === " "
+
+      if (isCommitKey && activeValueRef.current !== null) {
+        keyEvent.preventDefault()
+
+        commit(activeValueRef.current)
+      }
+    }
+
+    globalThis.addEventListener(
+      "pointermove",
+      onPointerMove,
+    )
+
+    globalThis.addEventListener("pointerup", onPointerUp)
+
+    globalThis.addEventListener("keydown", onKeyDown)
+
+    return () => {
+      globalThis.removeEventListener(
+        "pointermove",
+        onPointerMove,
+      )
+
+      globalThis.removeEventListener(
+        "pointerup",
+        onPointerUp,
+      )
+
+      globalThis.removeEventListener("keydown", onKeyDown)
+    }
+  }, [
+    activeValueRef,
+    isOpen,
+    next,
+    offerableKeysRef,
+    onDismissRef,
+    onPickRef,
+    previous,
+    setActiveValue,
+    targetsRef,
+  ])
+
+  /**
+   * Focus enters the rail only when a pointer is NOT driving it.
+   * Stealing focus mid-drag scrolls the page to the rail on some
+   * browsers, which is the one thing this control exists to avoid.
+   */
+  useEffect(() => {
+    if (
+      !isOpen ||
+      isPointerDriven.current ||
+      hasTakenFocus.current ||
+      firstOfferableKey === undefined
+    ) {
+      return
+    }
+
+    hasTakenFocus.current = true
+
+    setActiveValue(firstOfferableKey)
+
+    railRef.current
+      ?.querySelector<HTMLElement>(
+        "[data-drop-rail-target]:not([aria-disabled='true'])",
+      )
+      ?.focus()
+  }, [firstOfferableKey, isOpen, setActiveValue])
+
+  if (!isOpen) {
+    return null
+  }
+
+  return (
+    <>
+      <div
+        aria-label={label}
+        className={toClassName(
+          "sticky top-0 z-20 flex flex-wrap items-center gap-2 rounded-md border border-border-default bg-surface-overlay p-2 shadow-(--elevation-medium)",
+          className,
+        )}
+        id={baseId}
+        ref={railRef}
+        role="listbox"
+      >
+        {targets.map((target) => {
+          const isOfferable =
+            !target.isCurrent && !target.isDisabled
+
+          const isActive =
+            isOfferable && activeValue === target.key
+
+          return (
+            <button
+              aria-disabled={isOfferable ? undefined : true}
+              aria-selected={isActive}
+              className={toClassName(
+                "flex max-w-80 items-center gap-1.5 rounded-full border px-3 py-1 text-sm transition-colors duration-(--duration-fast) ease-standard",
+                isOfferable
+                  ? "cursor-pointer border-border-default bg-surface-raised text-content-primary hover:bg-surface-sunken"
+                  : "cursor-not-allowed border-border-subtle bg-surface-sunken text-content-disabled",
+                isActive &&
+                  "border-intent-accent-border bg-intent-accent-surface text-intent-accent-content outline-solid outline-(length:--focus-ring-width) outline-focus-ring",
+              )}
+              data-drop-rail-target={target.key}
+              key={target.key}
+              onClick={() => {
+                // A released drag also fires a click. The pointer path
+                // has already committed by then, so this guard is what
+                // stops a drag committing twice.
+                if (
+                  isPointerDriven.current ||
+                  !isOfferable
+                ) {
+                  return
+                }
+
+                onPick(target.key)
+              }}
+              role="option"
+              tabIndex={isActive ? 0 : -1}
+              type="button"
+            >
+              {target.mark === undefined ? null : (
+                <span aria-hidden>{target.mark}</span>
+              )}
+
+              <span className="truncate">
+                {target.label}
+              </span>
+
+              {target.count === undefined ? null : (
+                <span className="text-content-secondary text-xs">
+                  {target.count}
+                </span>
+              )}
+
+              {target.isCurrent ? (
+                // Said out loud, not shown by dimming alone. WCAG
+                // 1.4.1: the one chip a person must not aim for is
+                // exactly the one that must not be marked by colour.
+                <VisuallyHidden>
+                  — where it is now
+                </VisuallyHidden>
+              ) : null}
+            </button>
+          )
+        })}
+      </div>
+
+      {/* OUTSIDE the listbox, and that is not a style choice. A
+          `role="listbox"` may contain only `option` children, so a
+          live region inside it is an axe `aria-required-children`
+          violation — which is how this was found. It is `sr-only`,
+          so being a sibling costs no layout. */}
+      <output aria-live="polite" className="sr-only">
+        {announcement}
+      </output>
+    </>
+  )
+}

package/src/NavBar/NavBar.mdx

@@ -0,0 +1,157 @@
+import { Canvas, Controls, Meta } from "@storybook/addon-docs/blocks";
+
+import * as NavBarStories from "./NavBar.stories";
+
+<Meta of={NavBarStories} />
+
+# NavBar
+
+The app's destinations as real links, in one line — folding into a single menu button,
+**whole**, when that line does not fit.
+
+<Canvas of={NavBarStories.Default} />
+
+## Props
+
+<Controls />
+
+## It folds whole, and that is the decision
+
+`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
+work moves along — Triage → Backlog → Phases → Lanes → Board → Archives — and a
+half-collapsed bar splits that shape across two places with no rule a 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 is the complete list in
+the product's own order.
+
+<Canvas of={NavBarStories.AllVariants} />
+
+## Why this is not a folded `Toolbar`
+
+`Toolbar` already solves collapse-into-an-overflow, and this component **reuses its
+measurement** — `useToolbarOverflow`, the same tape measure — 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`, which is also `{ label, onSelect }`. A nav folded into
+one is a row of `<button>`s:
+
+| | `<button onClick={navigate}>` | `<a href>` |
+| --- | --- | --- |
+| Middle-click, ctrl-click | nothing | opens a tab |
+| "Open link in new tab" | absent from the menu | there |
+| "Copy link address" | absent | there |
+| Status bar on hover | blank | the destination |
+| Visited styling, the back button's idea of history | none | the platform's |
+
+`BuildingAnApp.mdx` names `<button onClick={navigate}>` as the fleet's most common
+navigation defect. A collapse mechanism that introduced it below a certain width would be
+that defect on a timer — and it screenshots identically, which is how it would survive
+review.
+
+The panel 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**.
+
+## Measured, not breakpointed
+
+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, `data-density="kiosk"`, or a reader at 175% browser zoom each move the fold on
+their own.
+
+mux-magic collapses at a hardcoded `480px` and plex-channels at `760px`. Neither number has
+a reason, and both are wrong the first time anything about the content changes.
+
+<Canvas of={NavBarStories.Responsive} />
+
+## ⚠️ 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: fewer links → a narrower box → fewer links.
+
+The root carries `min-w-0 flex-1`, which is the whole fix inside a flex row. A grid track is
+the caller's to declare:
+
+```css
+grid-template-columns: auto minmax(0, 1fr) auto; /* brand, nav, actions */
+```
+
+`auto` on that middle track is the bug — it floors at the nav's min-content width, which is
+the sum of every link.
+
+## Which destination is current
+
+The library is router-agnostic (see `RouterLinkProvider`), so it cannot ask a router which
+link is active. The app hands it one string:
+
+```tsx
+<NavBar currentHref={useLocation().pathname} items={DESTINATIONS} label="Main" />
+```
+
+`getIsCurrentHref` decides the rest, and it is exported so an app can ask the same question
+elsewhere:
+
+- **A parent path is current for its children.** `/tasks` is current 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, so `/task` is not
+  current for `/tasks`.
+- **`/` is exact.** 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. There is no prop to change it here: a nav with two current items has
+  stopped saying anything.
+- **The query string and the fragment are not part of the answer.**
+  `/backlog?focus=search` is still the Backlog.
+
+The current destination gets `aria-current="page"` as well as the fill, because a highlight
+is invisible to a screen reader and to anyone who cannot separate the two surfaces.
+
+## 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.
+Every link is then 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, the two copies drift, and every test has to
+be defensively scoped.
+
+<Canvas of={NavBarStories.AllStates} />
+
+## A fold control belongs at an edge
+
+`menuAlign="end"` puts the trigger beside the header's own actions rather than leaving it
+hugging the wordmark with the whole track empty after it. It reaches **only** the folded
+row, which holds exactly one item — so where the links sit when the bar is whole is not a
+prop, and cannot be made inconsistent with the rest of the header.
+
+## The trigger's glyph is the app's
+
+The library ships no icons, so `menuIcon` has no default — U+2630 renders as nothing where
+the font lacks it, which includes this sandbox's chromium and the kiosk image. With no icon
+the trigger is a text button reading `menuLabel`, which works everywhere.
+
+`menuLabel` names the trigger **and** the panel it opens: a `role="dialog"` takes no
+accessible name from its content.
+
+## Keyboard
+
+Every link in the bar is its own tab stop, which is what a `<nav>` is — this is not a
+`role="toolbar"`, and there is no roving focus to learn.
+
+Folded, it is one tab stop: Enter or Space opens the panel, focus moves into it, Escape
+closes it and hands focus back to the trigger. Choosing a destination closes it too —
+unless the click was modified, because a ctrl-click leaves the reader exactly where they
+were and shutting the menu they are still reading is how people stop ctrl-clicking.
+
+<Canvas of={NavBarStories.Interactive} />
+
+## In a shell
+
+<Canvas of={NavBarStories.InAppShell} />