@charcuterie/ui 3.32.0 → 3.34.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/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

package/src/Slider/Slider.tsx

@@ -12,6 +12,15 @@ import {
   FOCUS_RING_CLASS,
   INTENT_SOLID_FILL_CLASS,
 } from "../intentStyles.ts"
+import type { SliderSize } from "../sliderStyles.ts"
+import {
+  SLIDER_ROW_CLASS,
+  SLIDER_THUMB_CLASS,
+  SLIDER_THUMB_OFFSET,
+  SLIDER_THUMB_SIZE_CLASS,
+  SLIDER_TRACK_CLASS,
+  SLIDER_TRACK_SIZE_CLASS,
+} from "../sliderStyles.ts"
 import { toClassName } from "../toClassName.ts"
 import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
 import {
@@ -21,7 +30,11 @@ import {
   toPercent,
 } from "./sliderValue.ts"
 
-export type SliderSize = "lg" | "md" | "sm"
+/**
+ * Re-exported rather than declared here: the three sizes are the bar's,
+ * and `RangeSlider` paints the same bar from `../sliderStyles.ts`.
+ */
+export type { SliderSize }
 
 export type SliderProps = Omit<
   ComponentPropsWithRef<"div">,
@@ -73,25 +86,6 @@ export type SliderProps = Omit<
   valueFormat?: (value: number) => string
 }
 
-const TRACK_SIZE_CLASS: Record<SliderSize, string> = {
-  sm: "h-1",
-  md: "h-2",
-  lg: "h-3",
-}
-
-const THUMB_SIZE_CLASS: Record<SliderSize, string> = {
-  sm: "size-3",
-  md: "size-4",
-  lg: "size-5",
-}
-
-/** Half of each `THUMB_SIZE_CLASS`, as the inline-start pull-back. */
-const THUMB_OFFSET: Record<SliderSize, string> = {
-  sm: "-0.375rem",
-  md: "-0.5rem",
-  lg: "-0.625rem",
-}
-
 /**
  * A single-value range control: the thing `<input type="range">` is,
  * without the OS painting it.
@@ -341,10 +335,10 @@ export const Slider = ({
         aria-valuenow={shown}
         aria-valuetext={valueText}
         className={toClassName(
-          "relative flex w-full touch-none items-center rounded-full",
-          // The hit area is the row, which is taller than the bar: a
-          // 2px track is not a pointer target, and a finger is 44px.
-          "min-h-(--control-height-sm) cursor-pointer",
+          // The bar, shared with `RangeSlider` through
+          // `../sliderStyles.ts` — including the hit area being the
+          // row rather than the 2px track.
+          SLIDER_ROW_CLASS,
           FOCUS_RING_CLASS,
           // NOT `ARIA_DISABLED_CLASS`. That constant paints a
           // box-shaped control — `bg-surface-sunken` plus a border —
@@ -373,8 +367,8 @@ export const Slider = ({
       >
         <span
           className={toClassName(
-            "w-full overflow-hidden rounded-full bg-surface-sunken",
-            TRACK_SIZE_CLASS[size],
+            SLIDER_TRACK_CLASS,
+            SLIDER_TRACK_SIZE_CLASS[size],
           )}
         >
           <span
@@ -389,8 +383,8 @@ export const Slider = ({
         <span
           aria-hidden="true"
           className={toClassName(
-            "absolute rounded-full border-2 border-surface-raised shadow-sm",
-            THUMB_SIZE_CLASS[size],
+            SLIDER_THUMB_CLASS,
+            SLIDER_THUMB_SIZE_CLASS[size],
             INTENT_SOLID_FILL_CLASS[intent],
           )}
           // Pulled back by half its own width so it sits ON the
@@ -403,7 +397,7 @@ export const Slider = ({
           // logical `inset-inline-start` looks like it already solved.
           style={{
             insetInlineStart: `${percent}%`,
-            marginInlineStart: THUMB_OFFSET[size],
+            marginInlineStart: SLIDER_THUMB_OFFSET[size],
           }}
         />
       </div>