@charcuterie/ui 3.33.0 → 4.0.0

package/src/RangeSlider/rangeSliderValue.test.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from "vitest"
+
+import {
+  getNearerThumb,
+  getThumbBounds,
+  moveThumb,
+  snapRange,
+} from "./rangeSliderValue.ts"
+
+const bounds = { max: 100, min: 0, step: 1 }
+
+describe("snapRange", () => {
+  test("it snaps both ends onto the step grid", () => {
+    expect(
+      snapRange(
+        { end: 78, start: 22 },
+        { max: 100, min: 0, step: 5 },
+      ),
+    ).toEqual({ end: 80, start: 20 })
+  })
+
+  /**
+   * `value` seeds rather than controls, so a backwards pair is a state
+   * an app can genuinely be in for a frame — a typed start committing
+   * before its end catches up. A negative-width fill paints nothing,
+   * so the pair is put in order here instead.
+   */
+  test("a backwards pair comes back in order", () => {
+    expect(
+      snapRange({ end: 20, start: 80 }, bounds),
+    ).toEqual({ end: 80, start: 20 })
+  })
+
+  test("neither end escapes the range, and a NaN does not reach the style attribute", () => {
+    expect(
+      snapRange({ end: 400, start: -40 }, bounds),
+    ).toEqual({ end: 100, start: 0 })
+
+    expect(
+      snapRange(
+        { end: Number.NaN, start: Number.NaN },
+        bounds,
+      ),
+    ).toEqual({ end: 0, start: 0 })
+  })
+})
+
+describe("moveThumb", () => {
+  test("it moves the thumb it is given and leaves the other alone", () => {
+    expect(
+      moveThumb({
+        bounds,
+        next: 30,
+        range: { end: 80, start: 20 },
+        thumb: "start",
+      }),
+    ).toEqual({ end: 80, start: 30 })
+
+    expect(
+      moveThumb({
+        bounds,
+        next: 60,
+        range: { end: 80, start: 20 },
+        thumb: "end",
+      }),
+    ).toEqual({ end: 60, start: 20 })
+  })
+
+  /**
+   * The crossing rule, and the whole reason this module exists. A
+   * thumb pushed past its partner stops **on** it: the range collapses
+   * to zero width and the two handles keep their identities.
+   */
+  test("a thumb stops on the other one rather than crossing it", () => {
+    expect(
+      moveThumb({
+        bounds,
+        next: 95,
+        range: { end: 80, start: 20 },
+        thumb: "start",
+      }),
+    ).toEqual({ end: 80, start: 80 })
+
+    expect(
+      moveThumb({
+        bounds,
+        next: 5,
+        range: { end: 80, start: 20 },
+        thumb: "end",
+      }),
+    ).toEqual({ end: 20, start: 20 })
+  })
+
+  test("a collapsed range opens again from either side", () => {
+    const collapsed = { end: 40, start: 40 }
+
+    expect(
+      moveThumb({
+        bounds,
+        next: 25,
+        range: collapsed,
+        thumb: "start",
+      }),
+    ).toEqual({ end: 40, start: 25 })
+
+    expect(
+      moveThumb({
+        bounds,
+        next: 55,
+        range: collapsed,
+        thumb: "end",
+      }),
+    ).toEqual({ end: 55, start: 40 })
+  })
+
+  /**
+   * The snap happens on the global grid and the clamp happens after
+   * it. Snapping against the other thumb as an anchor would put the
+   * two handles on different ladders — 7–19 by 4 is the range that
+   * shows it, since neither end of it is on a zero-anchored grid.
+   */
+  test("both thumbs stay on one grid, anchored on min", () => {
+    const coarse = { max: 19, min: 7, step: 4 }
+
+    expect(
+      moveThumb({
+        bounds: coarse,
+        next: 10,
+        range: { end: 19, start: 7 },
+        thumb: "start",
+      }),
+    ).toEqual({ end: 19, start: 11 })
+
+    expect(
+      moveThumb({
+        bounds: coarse,
+        next: 14,
+        range: { end: 19, start: 11 },
+        thumb: "end",
+      }),
+    ).toEqual({ end: 15, start: 11 })
+  })
+
+  test("a float step does not accumulate drift", () => {
+    expect(
+      moveThumb({
+        bounds: { max: 1, min: 0, step: 0.1 },
+        next: 0.30000000000000004,
+        range: { end: 0.8, start: 0.2 },
+        thumb: "start",
+      }),
+    ).toEqual({ end: 0.8, start: 0.3 })
+  })
+})
+
+describe("getNearerThumb", () => {
+  test("the nearer end picks up the press", () => {
+    const range = { end: 80, start: 20 }
+
+    expect(getNearerThumb({ at: 25, range })).toBe("start")
+
+    expect(getNearerThumb({ at: 75, range })).toBe("end")
+  })
+
+  /**
+   * Two thumbs on the same value is the state the clamping rule makes
+   * reachable, so the tie rule is what stops a collapsed range being
+   * stuck. The press's side decides.
+   */
+  test("a collapsed pair is opened by the side the press landed on", () => {
+    const collapsed = { end: 40, start: 40 }
+
+    expect(
+      getNearerThumb({ at: 10, range: collapsed }),
+    ).toBe("start")
+
+    expect(
+      getNearerThumb({ at: 90, range: collapsed }),
+    ).toBe("end")
+  })
+
+  test("a press outside the span picks the end it is outside of", () => {
+    const range = { end: 80, start: 20 }
+
+    expect(getNearerThumb({ at: 0, range })).toBe("start")
+
+    expect(getNearerThumb({ at: 100, range })).toBe("end")
+  })
+})
+
+describe("getThumbBounds", () => {
+  /**
+   * How the clamping rule reaches a screen reader: a slider's only
+   * vocabulary for "this handle stops here" is `aria-valuemax`.
+   */
+  test("each thumb reports the other as its own bound", () => {
+    const range = { end: 80, start: 20 }
+
+    expect(
+      getThumbBounds({ bounds, range, thumb: "start" }),
+    ).toEqual({ max: 80, min: 0 })
+
+    expect(
+      getThumbBounds({ bounds, range, thumb: "end" }),
+    ).toEqual({ max: 100, min: 20 })
+  })
+
+  test("a reversed range still reports two ordered bounds", () => {
+    expect(
+      getThumbBounds({
+        bounds: { max: 0, min: 100, step: 1 },
+        range: { end: 20, start: 80 },
+        thumb: "start",
+      }),
+    ).toEqual({ max: 80, min: 0 })
+  })
+})

package/src/RangeSlider/rangeSliderValue.ts

@@ -0,0 +1,185 @@
+/**
+ * The arithmetic behind `RangeSlider`: everything the second thumb
+ * adds to `Slider`'s, and nothing `Slider` already answers.
+ *
+ * The single-value functions are **called**, never re-derived —
+ * `snapToStep` and `clampToRange` come from `../Slider/sliderValue.ts`
+ * — so a range slider snaps on exactly the grid a plain slider snaps
+ * on. Anchoring on `min` rather than on zero, the re-clamp after a
+ * snap, and the float-step rounding are all already right there, and
+ * a second copy of them is a second set of edge cases to keep in
+ * agreement.
+ *
+ * Every function here is total. A caller may hand over a reversed
+ * range, a `NaN`, or a start past its end, and the answer is still a
+ * pair of numbers inside `[min, max]` with `start <= end`. A range
+ * that renders `inline-size: NaN%` paints nothing and the DOM says
+ * nothing about it.
+ */
+
+import {
+  clampToRange,
+  snapToStep,
+} from "../Slider/sliderValue.ts"
+
+/** Which end of the range a movement is about. */
+export type RangeSliderThumb = "end" | "start"
+
+export type RangeSliderValue = {
+  end: number
+  start: number
+}
+
+export type RangeSliderBounds = {
+  max: number
+  min: number
+  step: number
+}
+
+/**
+ * Both ends snapped to the step grid, clamped into the range, and put
+ * in order.
+ *
+ * The ordering is not a nicety. `value` **seeds** rather than
+ * controls, exactly as `Slider`'s does, so the pair arrives from an
+ * app's state and an app can hold `{ end: 20, start: 80 }` for a
+ * frame — a text field committing a typed start before the end
+ * catches up is the ordinary way to reach it. A backwards pair paints
+ * a fill of negative width, which is invisible rather than wrong-
+ * looking, so it is corrected here instead.
+ */
+export const snapRange = (
+  range: RangeSliderValue,
+  { max, min, step }: RangeSliderBounds,
+): RangeSliderValue => {
+  const first = snapToStep(range.start, min, max, step)
+
+  const second = snapToStep(range.end, min, max, step)
+
+  return {
+    end: Math.max(first, second),
+    start: Math.min(first, second),
+  }
+}
+
+/**
+ * The range with one thumb moved to `next`, clamped at the other one.
+ *
+ * **The thumbs clamp; they do not swap.** A thumb pushed past its
+ * partner stops on it, keeps its own identity, and the range collapses
+ * to zero width rather than turning inside out. Swapping is the other
+ * defensible answer and is the wrong one for the first consumer: the
+ * thumbs are a clip's start and its end, a QueuePilot user drags them
+ * against a `TimecodeInput` showing which is which, and a drag that
+ * silently renamed the handle under the pointer would move a number
+ * the user is reading somewhere else. Keyboard makes it plainer still
+ * — swapping means one ArrowRight moves the *other* thumb, and the
+ * focused element is no longer the value that changed.
+ *
+ * The snap happens on the **global** grid before the clamp, never on
+ * a grid anchored at the other thumb: the partner is already on the
+ * grid, so clamping to it lands on the grid too, while snapping
+ * against a moving anchor would put the two thumbs on different
+ * ladders.
+ */
+export const moveThumb = ({
+  bounds,
+  next,
+  range,
+  thumb,
+}: {
+  bounds: RangeSliderBounds
+  next: number
+  range: RangeSliderValue
+  thumb: RangeSliderThumb
+}): RangeSliderValue => {
+  const ordered = snapRange(range, bounds)
+
+  const snapped = snapToStep(
+    next,
+    bounds.min,
+    bounds.max,
+    bounds.step,
+  )
+
+  if (thumb === "start") {
+    return {
+      end: ordered.end,
+      start: clampToRange(
+        snapped,
+        Math.min(bounds.min, bounds.max),
+        ordered.end,
+      ),
+    }
+  }
+
+  return {
+    end: clampToRange(
+      snapped,
+      ordered.start,
+      Math.max(bounds.min, bounds.max),
+    ),
+    start: ordered.start,
+  }
+}
+
+/**
+ * The thumb a press at `at` should pick up.
+ *
+ * The nearer one, and the tie is the interesting half: two thumbs
+ * sitting on the same value are the state the clamping rule makes
+ * reachable, and a rule that always picked the same one would leave a
+ * collapsed range stuck against whichever end it collapsed on. So a
+ * tie is broken by **which side of them the press landed on** —
+ * below picks the start, on or above picks the end — which is what
+ * lets a collapsed pair be pulled open in either direction.
+ */
+export const getNearerThumb = ({
+  at,
+  range,
+}: {
+  at: number
+  range: RangeSliderValue
+}): RangeSliderThumb => {
+  const toStart = Math.abs(at - range.start)
+
+  const toEnd = Math.abs(at - range.end)
+
+  if (toStart < toEnd) return "start"
+
+  if (toEnd < toStart) return "end"
+
+  return at < range.start ? "start" : "end"
+}
+
+/**
+ * What one thumb may report as its own `aria-valuemin` /
+ * `aria-valuemax`.
+ *
+ * The other thumb is the bound, which is how the clamping rule
+ * reaches assistive technology at all: a screen reader reading
+ * "12 of 0 to 30" on the start thumb is being told, in the only
+ * vocabulary a slider has, that 30 is where this handle stops. The
+ * APG's multi-thumb pattern asks for exactly this.
+ */
+export const getThumbBounds = ({
+  bounds,
+  range,
+  thumb,
+}: {
+  bounds: RangeSliderBounds
+  range: RangeSliderValue
+  thumb: RangeSliderThumb
+}): { max: number; min: number } => {
+  const ordered = snapRange(range, bounds)
+
+  return thumb === "start"
+    ? {
+        max: ordered.end,
+        min: Math.min(bounds.min, bounds.max),
+      }
+    : {
+        max: Math.max(bounds.min, bounds.max),
+        min: ordered.start,
+      }
+}

package/src/RouterLink/RouterLink.mdx

@@ -27,38 +27,68 @@ point — so an app that never imports this path never resolves it.
 yarn add @charcuterie/ui react-router
 ```
 
+**One component at the root**, and it must sit **inside** the router:
+
 ```tsx
 // src/main.tsx
-import { RouterLinkProvider } from "@charcuterie/ui"
-import { ReactRouterLink } from "@charcuterie/ui/react-router"
+import { ReactRouterAdapter } from "@charcuterie/ui/react-router"
 import { StrictMode } from "react"
 import { createRoot } from "react-dom/client"
-import {
-  createBrowserRouter,
-  RouterProvider,
-} from "react-router"
+import { BrowserRouter } from "react-router"
 
-import { routes } from "./routes.tsx"
-
-const router = createBrowserRouter(routes)
+import { App } from "./App.tsx"
 
 createRoot(document.getElementById("root")).render(
   <StrictMode>
-    <RouterLinkProvider link={ReactRouterLink}>
-      <RouterProvider router={router} />
-    </RouterLinkProvider>
+    <BrowserRouter>
+      <ReactRouterAdapter>
+        <App />
+      </ReactRouterAdapter>
+    </BrowserRouter>
   </StrictMode>,
 )
 ```
 
-`RouterLinkProvider` goes **outside** `RouterProvider` here on purpose: it is plain React
-context and needs no router of its own, and putting it outermost means a link rendered by a
-route element and a link rendered by an app-level chrome component both see it.
+Inside, because it reads `useLocation()`. Above the routes, because what it provides belongs
+to the whole app — a link rendered by a route element and a link rendered by app-level
+chrome both see it.
 
 Already on `react-router-dom` v7, as bambuddy is? Nothing changes. `react-router-dom` v7 is
 a re-export shim over `react-router`, and the adapter imports `Link` from the latter, so one
 import covers both installs.
 
+### Two seams, and why they arrive together
+
+The adapter wires the **link seam** and the **scroll memory**, because a per-seam opt-in is
+what the fleet has already failed at. `Main`'s scroll memory shipped as a `scrollKey` prop;
+one app wired it, and the other three carried on losing the reader's place with the library
+sitting right there supporting it. One name at the root means a seam added later arrives in
+every app that already renders this, on its next release.
+
+`RouterLinkProvider`, `ReactRouterLink` and `ScrollMemoryProvider` all stay exported for an
+app that wants one half.
+
+### On `createBrowserRouter`
+
+`RouterProvider` takes no children, so the adapter goes in the root route's element:
+
+```tsx
+const routes = [
+  {
+    element: (
+      <ReactRouterAdapter>
+        <Outlet />
+      </ReactRouterAdapter>
+    ),
+    children: appRoutes,
+  },
+]
+```
+
+An app that wants only the link seam can keep `RouterLinkProvider` outside `RouterProvider`
+instead, as it did before this adapter existed — that provider is plain React context and
+needs no router of its own.
+
 That is the whole integration. Every link in the app is now soft:
 
 ```tsx
@@ -166,6 +196,10 @@ asserts `getByRole("link", { name: … })` and its `href` with no router in the
 With a provider, inject a stand-in that marks what it was handed — `TextLink.stories.tsx`'s
 `Routed` story is exactly that, and `TextLink.test.tsx` reads it.
 
+The scroll memory is the same: no provider, no memory. A test that wants it renders
+`ScrollMemoryProvider` with a `{ key, path }` it controls, rather than a router — which is
+what `Main.stories.tsx` does.
+
 ## API
 
 | Export | From | What |
@@ -175,4 +209,7 @@ With a provider, inject a stand-in that marks what it was handed — `TextLink.s
 | `RouterLinkComponent` / `RouterLinkProps` | `@charcuterie/ui` | The contract: `ComponentPropsWithRef<"a">` with `href` required. |
 | `AnchorLink` | `@charcuterie/ui` | The plain `<a href>` default. |
 | `getIsRoutedHref(href)` | `@charcuterie/ui` | The destination test above. |
-| `ReactRouterLink` | `@charcuterie/ui/react-router` | The one shipped adapter. Optional peer. |
+| `ScrollMemoryProvider` | `@charcuterie/ui` | The scroll seam. `entry` is `{ key, path }` for the current history entry. |
+| `ScrollEntry` | `@charcuterie/ui` | That pair's type. |
+| `ReactRouterAdapter` | `@charcuterie/ui/react-router` | Both seams, wired. The one thing an app renders. Optional peer. |
+| `ReactRouterLink` | `@charcuterie/ui/react-router` | The link adapter alone. Optional peer. |

package/src/SegmentedControl/SegmentedControl.stories.tsx

@@ -139,6 +139,56 @@ export const Responsive: Story = {
   ),
 }
 
+/**
+ * A board's lane selector is a route selector, not a compact
+ * preference. It reaches the board's edges and each route gets the
+ * same hit area. At a cramped width, two targets share the first
+ * row and the final target takes the full second row, so no label
+ * wraps or clips.
+ */
+export const FullWidth: Story = {
+  args: {
+    isFullWidth: true,
+    items: [
+      {
+        label: (
+          <span className="block whitespace-nowrap">
+            Todo
+          </span>
+        ),
+        value: "todo",
+      },
+      {
+        label: (
+          <span className="block whitespace-nowrap">
+            In Progress
+          </span>
+        ),
+        value: "in-progress",
+      },
+      {
+        label: (
+          <span className="block whitespace-nowrap">
+            Needs Review
+          </span>
+        ),
+        value: "needs-review",
+      },
+    ],
+    label: "Board lanes",
+  },
+  render: (controlProps) => (
+    <ContainerBoard>
+      {(width) => (
+        <SegmentedControl
+          {...controlProps}
+          label={`Board lanes at ${width}`}
+        />
+      )}
+    </ContainerBoard>
+  ),
+}
+
 /**
  * The complete keyboard path. Tab enters the group **once** — the
  * roving-tabindex rule — then the arrow keys move and check

package/src/SegmentedControl/SegmentedControl.test.tsx

@@ -7,7 +7,7 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./SegmentedControl.stories.tsx"
 
-const { AllStates, Default, Interactive } =
+const { AllStates, Default, FullWidth, Interactive } =
   composeStories(stories)
 
 /**
@@ -206,3 +206,38 @@ test("selectedValue decides the first render and nothing after", async () => {
     ).toHaveTextContent("3")
   })
 })
+
+test("full-width mode fills its container without wrapping labels", async () => {
+  const { canvas } = await mountStory(FullWidth)
+
+  for (const group of canvas.getAllByRole("radiogroup", {
+    name: /Board lanes at/,
+  })) {
+    const options = getOptions(group)
+    const widths = options.map(
+      (option) => option.getBoundingClientRect().width,
+    )
+
+    if (
+      group.getAttribute("aria-label")?.includes("15rem")
+    ) {
+      // Two equal targets fit on the first row. The third fills the
+      // second row, so every label stays intact and there is no gap.
+      expect(widths[0]).toBeCloseTo(widths[1] ?? 0, 0)
+      expect(widths[2]).toBeGreaterThan(widths[0] ?? 0)
+      expect(
+        group.getBoundingClientRect().width -
+          (widths[2] ?? 0),
+      ).toBeLessThanOrEqual(8)
+    } else {
+      expect(
+        group.getBoundingClientRect().width,
+      ).toBeGreaterThan(
+        widths.reduce((sum, width) => sum + width, 0),
+      )
+      expect(
+        Math.max(...widths) - Math.min(...widths),
+      ).toBeLessThan(1)
+    }
+  }
+})

package/src/SegmentedControl/SegmentedControl.tsx

@@ -24,6 +24,17 @@ export type SegmentedItem = {
 
 export type SegmentedControlProps = {
   className?: string
+  /**
+   * Fill the available inline space, with every option claiming an
+   * equal share. A board's Narrow View selector needs this: its
+   * options name the only lane on screen, so a content-width strip
+   * leaves the rest of the board looking disconnected.
+   *
+   * The default stays content-width. Most segmented controls choose
+   * a compact view or density, where stretching three short words
+   * across a whole toolbar would weaken their grouping.
+   */
+  isFullWidth?: boolean
   items: readonly SegmentedItem[]
   /** The group's accessible name. Required. */
   label: string
@@ -75,6 +86,7 @@ const GAP_CLASS: Record<ControlSize, string> = {
  */
 export const SegmentedControl = ({
   className,
+  isFullWidth = false,
   items,
   label,
   onChange,
@@ -152,6 +164,7 @@ export const SegmentedControl = ({
       aria-label={label}
       className={toClassName(
         "inline-flex items-center rounded-md border border-border-subtle bg-surface-sunken p-0.5",
+        isFullWidth && "w-full flex-wrap",
         GAP_CLASS[size],
         className,
       )}
@@ -194,6 +207,7 @@ export const SegmentedControl = ({
       {items.map((item) => (
         <SegmentedOption
           isChecked={checkedValue === item.value}
+          isFullWidth={isFullWidth}
           item={item}
           key={item.value}
           onChoose={chooseOption}

package/src/SegmentedControl/SegmentedOption.tsx

@@ -9,6 +9,7 @@ import type { SegmentedItem } from "./SegmentedControl.tsx"
 
 export type SegmentedOptionProps = {
   isChecked: boolean
+  isFullWidth: boolean
   item: SegmentedItem
   onChoose: (value: string) => void
   /** `RovingFocus.register` — membership of the arrow-key group. */
@@ -36,6 +37,7 @@ export type SegmentedOptionProps = {
  */
 export const SegmentedOption = ({
   isChecked,
+  isFullWidth,
   item,
   onChoose,
   registerFocus,
@@ -65,6 +67,11 @@ export const SegmentedOption = ({
       aria-checked={isChecked}
       className={toClassName(
         "cursor-pointer rounded-sm border border-transparent font-medium tabular-nums transition-colors duration-(--duration-fast) ease-standard",
+        // In a very narrow board, three full labels cannot share
+        // one row. The minimum lets two fit, then the final option
+        // takes a full second row instead of wrapping its label or
+        // leaving unused space beside it.
+        isFullWidth && "min-w-28 flex-1 basis-28",
         CONTROL_SIZE_CLASS[size],
         // Two entries rather than one interpolated string:
         // `tailwindCandidates.test.ts` rejects a template literal in