@charcuterie/ui 3.8.0 → 3.9.0

package/src/Slider/Slider.tsx

@@ -0,0 +1,412 @@
+import { useUniqueId } from "@charcuterie/logic"
+import type { IntentName } from "@charcuterie/tokens"
+import type {
+  ComponentPropsWithRef,
+  KeyboardEvent,
+  PointerEvent,
+  ReactNode,
+} from "react"
+import { useRef, useState } from "react"
+
+import {
+  FOCUS_RING_CLASS,
+  INTENT_SOLID_FILL_CLASS,
+} from "../intentStyles.ts"
+import { toClassName } from "../toClassName.ts"
+import { VisuallyHidden } from "../VisuallyHidden/VisuallyHidden.tsx"
+import {
+  clampToRange,
+  fromFraction,
+  snapToStep,
+  toPercent,
+} from "./sliderValue.ts"
+
+export type SliderSize = "lg" | "md" | "sm"
+
+export type SliderProps = Omit<
+  ComponentPropsWithRef<"div">,
+  "children" | "defaultValue" | "onChange"
+> & {
+  intent?: IntentName
+  isDisabled?: boolean
+  isLabelVisible?: boolean
+  /**
+   * Read-only in the `aria-readonly` sense: focusable, full contrast,
+   * announced as unchangeable. A media scrubber for a stream with no
+   * seekable range is this, not `isDisabled` — the position is still
+   * worth reading.
+   */
+  isReadOnly?: boolean
+  isValueShown?: boolean
+  /** Required. A slider with no name is an unlabelled number. */
+  label: string
+  /**
+   * PageUp / PageDown. Defaults to ten steps, which is the APG's
+   * suggestion and the only sensible answer that does not need the
+   * caller to know the range.
+   */
+  largeStep?: number
+  max?: number
+  min?: number
+  /**
+   * Fires on every movement — each arrow key, and each pointer sample
+   * while dragging. Use it to paint. See `onChangeEnd` for committing.
+   */
+  onChange?: (value: number) => void
+  /**
+   * Fires once, when the interaction ends: pointer release, or key up.
+   *
+   * This exists because the expensive consumer of a slider is almost
+   * never the paint. A seek scrubber that issued its network call from
+   * `onChange` would send one request per pointer sample and arrive at
+   * the right offset last, after a queue of stale ones.
+   */
+  onChangeEnd?: (value: number) => void
+  size?: SliderSize
+  step?: number
+  value?: number
+  /**
+   * How the value reads aloud and, when `isValueShown`, on screen.
+   * Without it a scrubber announces "1274", which is a number of
+   * seconds nobody has.
+   */
+  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.
+ *
+ * The fleet had no way to ask for a value along a range, so QueuePilot's
+ * Now-playing bar could not have a scrubber
+ * ([decision](../../../../docs/decisions/2026-08-22-the-slider-is-a-div-with-role-slider-not-an-input-range.md)).
+ * `ProgressBar` looks like the answer and is not: it is output, it takes
+ * no input, and `role="progressbar"` tells assistive technology exactly
+ * that.
+ *
+ * ## Why a `div` and not `<input type="range">`
+ *
+ * The same reason `Select` is deprecated. A range input's thumb and
+ * track are UA pseudo-elements — `::-webkit-slider-thumb`,
+ * `::-moz-range-track` — and they are not one surface: the two engines
+ * disagree about which of them the track's fill even belongs to, so a
+ * token-styled range is two stylesheets that drift. Windows paints its
+ * own. `role="slider"` on a focusable `div` is the APG's own pattern,
+ * gets the same AT support, and every pixel of it is ours.
+ *
+ * ## Drag does not commit
+ *
+ * `onChange` fires per movement, `onChangeEnd` once on release. Both are
+ * optional and the component is fully controlled through `value`, so a
+ * caller that wants the simple thing passes `onChange` alone and a
+ * caller with a network call behind it splits them.
+ *
+ * While dragging, the component holds the value locally and paints from
+ * that rather than from the `value` prop. Without it a controlled
+ * scrubber whose owner only commits `onChangeEnd` would render the thumb
+ * pinned under the finger at the old position — the drag would look
+ * broken while behaving correctly.
+ */
+export const Slider = ({
+  className,
+  intent = "accent",
+  isDisabled = false,
+  isLabelVisible = false,
+  isReadOnly = false,
+  isValueShown = false,
+  label,
+  largeStep,
+  max = 100,
+  min = 0,
+  onChange,
+  onChangeEnd,
+  size = "md",
+  step = 1,
+  value = 0,
+  valueFormat,
+  ...divProps
+}: SliderProps): ReactNode => {
+  const labelId = useUniqueId()
+
+  const trackRef = useRef<HTMLDivElement>(null)
+
+  // Null means "not dragging" — distinct from a drag that happens to
+  // sit at 0, which a bare number could not express.
+  const [draggedValue, setDraggedValue] = useState<
+    number | null
+  >(null)
+
+  const isInert = isDisabled || isReadOnly
+
+  const committed = snapToStep(value, min, max, step)
+
+  const shown = draggedValue ?? committed
+
+  const percent = toPercent(shown, min, max)
+
+  const bigStep =
+    largeStep == null
+      ? (Math.max(min, max) - Math.min(min, max)) / 10
+      : largeStep
+
+  const emit = (next: number, isEnd: boolean): void => {
+    if (next !== shown) onChange?.(next)
+
+    if (isEnd) {
+      setDraggedValue(null)
+
+      onChangeEnd?.(next)
+
+      return
+    }
+
+    setDraggedValue(next)
+  }
+
+  /** The value the pointer at `clientX` is pointing at. */
+  const valueAt = (clientX: number): number => {
+    const track = trackRef.current
+
+    if (!track) return shown
+
+    const box = track.getBoundingClientRect()
+
+    if (box.width <= 0) return shown
+
+    // `left`/`right` here are physical, from the layout box, and stay
+    // physical on purpose — `isRtl` is what turns them into a value.
+    // The logical-properties rule is about `className`, not geometry.
+    const fraction = (clientX - box.left) / box.width
+
+    const isRtl =
+      getComputedStyle(track).direction === "rtl"
+
+    return fromFraction(fraction, min, max, step, isRtl)
+  }
+
+  const onPointerDown = (
+    event: PointerEvent<HTMLDivElement>,
+  ): void => {
+    if (isInert || event.button !== 0) return
+
+    // Capture on the TRACK, so a drag that leaves the element vertically
+    // (a thumb dragged off the bar, which is most of them) keeps
+    // reporting instead of stopping dead at the boundary.
+    event.currentTarget.setPointerCapture(event.pointerId)
+
+    event.currentTarget.focus()
+
+    emit(valueAt(event.clientX), false)
+  }
+
+  const onPointerMove = (
+    event: PointerEvent<HTMLDivElement>,
+  ): void => {
+    if (isInert || draggedValue == null) return
+
+    emit(valueAt(event.clientX), false)
+  }
+
+  const onPointerUp = (
+    event: PointerEvent<HTMLDivElement>,
+  ): void => {
+    if (isInert || draggedValue == null) return
+
+    event.currentTarget.releasePointerCapture(
+      event.pointerId,
+    )
+
+    emit(valueAt(event.clientX), true)
+  }
+
+  const onKeyDown = (
+    event: KeyboardEvent<HTMLDivElement>,
+  ): void => {
+    if (isInert) return
+
+    // Home/End are absolute; the rest are relative. `null` means the key
+    // is not ours and the event goes on its way — scrolling with the
+    // arrows off a focused slider is not something to swallow silently,
+    // but a slider that ignores its own arrow keys is worse.
+    const next = ((): number | null => {
+      switch (event.key) {
+        case "ArrowDown":
+        case "ArrowLeft":
+          return shown - step
+        case "ArrowRight":
+        case "ArrowUp":
+          return shown + step
+        case "End":
+          return Math.max(min, max)
+        case "Home":
+          return Math.min(min, max)
+        case "PageDown":
+          return shown - bigStep
+        case "PageUp":
+          return shown + bigStep
+        default:
+          return null
+      }
+    })()
+
+    if (next == null) return
+
+    event.preventDefault()
+
+    // Keys commit immediately. A key press is a discrete interaction —
+    // there is no release to wait for the way a drag has one, and an
+    // arrow key that only committed on `keyup` would feel lagged.
+    emit(snapToStep(next, min, max, step), true)
+  }
+
+  const valueText = valueFormat?.(
+    clampToRange(shown, min, max),
+  )
+
+  return (
+    <div
+      {...divProps}
+      className={toClassName(
+        "flex flex-col gap-1",
+        // A definite floor, because the root has no intrinsic width of
+        // its own: the track is `w-full` and the label is the only
+        // content, so a slider with no visible label in a shrink-to-fit
+        // parent (`items-start`, an inline-flex row) collapses to the
+        // width of the thumb. Every gate passed on exactly that —
+        // `role`, ARIA, keyboard and axe are all correct on a control
+        // 16px wide. `<input type="range">` has an intrinsic default
+        // width for the same reason; this is ours.
+        "min-w-40",
+        className,
+      )}
+    >
+      {isLabelVisible || isValueShown ? (
+        <div className="flex items-baseline justify-between gap-2 text-sm">
+          {isLabelVisible ? (
+            <span
+              className="text-content-secondary"
+              id={labelId}
+            >
+              {label}
+            </span>
+          ) : (
+            <VisuallyHidden id={labelId}>
+              {label}
+            </VisuallyHidden>
+          )}
+
+          {isValueShown ? (
+            <span className="text-content-muted tabular-nums">
+              {valueText ?? shown}
+            </span>
+          ) : null}
+        </div>
+      ) : (
+        <VisuallyHidden id={labelId}>
+          {label}
+        </VisuallyHidden>
+      )}
+
+      {/* The role, the tab stop and the pointer target are all the
+          track. Putting them on the thumb — which is what a hand-rolled
+          slider usually does, because the thumb is the thing that looks
+          draggable — gives the widget a 16px box, so a click on the bar
+          does nothing and a Playwright bounding box is the handle. */}
+      <div
+        aria-disabled={isDisabled || undefined}
+        aria-labelledby={labelId}
+        aria-orientation="horizontal"
+        aria-readonly={isReadOnly || undefined}
+        aria-valuemax={Math.max(min, max)}
+        aria-valuemin={Math.min(min, max)}
+        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",
+          FOCUS_RING_CLASS,
+          // NOT `ARIA_DISABLED_CLASS`. That constant paints a
+          // box-shaped control — `bg-surface-sunken` plus a border —
+          // which is right for `ButtonLink` and wrong here: a slider's
+          // visible body is a 2px track inside a 40px hit row, so the
+          // sunken fill lands on the whole row and draws a grey
+          // rectangle nothing else in the component has. Every gate
+          // passed on it; the screenshot is what showed it.
+          //
+          // `pointer-events-none` is the half that carries over, and it
+          // is load-bearing rather than cosmetic: without a real
+          // `:disabled` the hover rules still match.
+          isDisabled
+            ? "pointer-events-none opacity-55"
+            : "",
+          isReadOnly ? "cursor-default" : "",
+        )}
+        onKeyDown={onKeyDown}
+        onPointerCancel={onPointerUp}
+        onPointerDown={onPointerDown}
+        onPointerMove={onPointerMove}
+        onPointerUp={onPointerUp}
+        ref={trackRef}
+        role="slider"
+        tabIndex={isDisabled ? -1 : 0}
+      >
+        <span
+          className={toClassName(
+            "w-full overflow-hidden rounded-full bg-surface-sunken",
+            TRACK_SIZE_CLASS[size],
+          )}
+        >
+          <span
+            className={toClassName(
+              "block h-full rounded-full",
+              INTENT_SOLID_FILL_CLASS[intent],
+            )}
+            style={{ inlineSize: `${percent}%` }}
+          />
+        </span>
+
+        <span
+          aria-hidden="true"
+          className={toClassName(
+            "absolute rounded-full border-2 border-surface-raised shadow-sm",
+            THUMB_SIZE_CLASS[size],
+            INTENT_SOLID_FILL_CLASS[intent],
+          )}
+          // Pulled back by half its own width so it sits ON the
+          // position rather than starting at it, which is what keeps
+          // 100% from hanging off the end of the track.
+          //
+          // `margin-inline-start`, not `translate: -50%`. `translate`
+          // is physical, so in RTL it would shift the thumb the wrong
+          // way and 0% would hang off the start edge — the one bug a
+          // logical `inset-inline-start` looks like it already solved.
+          style={{
+            insetInlineStart: `${percent}%`,
+            marginInlineStart: THUMB_OFFSET[size],
+          }}
+        />
+      </div>
+    </div>
+  )
+}

package/src/Slider/sliderValue.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, test } from "vitest"
+
+import {
+  clampToRange,
+  fromFraction,
+  roundToStepPrecision,
+  snapToStep,
+  toPercent,
+} from "./sliderValue.ts"
+
+describe("clampToRange", () => {
+  test("it holds a value inside the range", () => {
+    expect(clampToRange(5, 0, 10)).toBe(5)
+
+    expect(clampToRange(-3, 0, 10)).toBe(0)
+
+    expect(clampToRange(30, 0, 10)).toBe(10)
+  })
+
+  test("a reversed range still has two ends", () => {
+    expect(clampToRange(5, 10, 0)).toBe(5)
+
+    expect(clampToRange(-1, 10, 0)).toBe(0)
+  })
+
+  // A NaN reaching the style attribute renders `inline-size: NaN%`,
+  // which paints nothing and reports nothing. An infinity is ordered,
+  // so it clamps to the end it is nearest rather than to the floor.
+  test("a NaN falls to the floor and an infinity clamps", () => {
+    expect(clampToRange(Number.NaN, 4, 10)).toBe(4)
+
+    expect(
+      clampToRange(Number.POSITIVE_INFINITY, 4, 10),
+    ).toBe(10)
+
+    expect(
+      clampToRange(Number.NEGATIVE_INFINITY, 4, 10),
+    ).toBe(4)
+  })
+})
+
+describe("snapToStep", () => {
+  test("it lands on the nearest step", () => {
+    expect(snapToStep(7, 0, 10, 5)).toBe(5)
+
+    expect(snapToStep(8, 0, 10, 5)).toBe(10)
+  })
+
+  /**
+   * The anchoring rule. Stepping a 7–19 range by 4 must be able to
+   * reach 7 — anchored on zero its reachable values are 8, 12 and 16,
+   * and neither end of its own range is one of them.
+   */
+  test("steps are anchored on min, not on zero", () => {
+    expect(snapToStep(7, 7, 19, 4)).toBe(7)
+
+    expect(snapToStep(10, 7, 19, 4)).toBe(11)
+
+    expect(snapToStep(19, 7, 19, 4)).toBe(19)
+  })
+
+  test("a snap never escapes the range", () => {
+    // 0–10 by 4: the nearest step to 10 is 12, which is not a value
+    // this slider has.
+    expect(snapToStep(10, 0, 10, 4)).toBe(10)
+  })
+
+  test("a zero or non-finite step means continuous", () => {
+    expect(snapToStep(7.3, 0, 10, 0)).toBe(7.3)
+
+    expect(snapToStep(7.3, 0, 10, Number.NaN)).toBe(7.3)
+
+    expect(snapToStep(-2, 0, 10, 0)).toBe(0)
+  })
+
+  test("a float step does not accumulate drift", () => {
+    // 0.1 * 3 is 0.30000000000000004 in IEEE 754, and that reaches
+    // aria-valuenow and the visible value both.
+    expect(snapToStep(0.3, 0, 1, 0.1)).toBe(0.3)
+
+    expect(snapToStep(0.25, 0, 1, 0.1)).toBe(0.3)
+  })
+})
+
+describe("roundToStepPrecision", () => {
+  test("it rounds to the decimals the step declares", () => {
+    expect(
+      roundToStepPrecision(0.30000000000000004, 0.1),
+    ).toBe(0.3)
+
+    expect(roundToStepPrecision(2.5, 1)).toBe(3)
+  })
+
+  // "1e-7" has no visible decimal point, so counting characters after
+  // a "." would report zero decimals and round it to an integer.
+  test("an exponential step is left alone", () => {
+    expect(roundToStepPrecision(0.00000012, 1e-7)).toBe(
+      0.00000012,
+    )
+  })
+})
+
+describe("toPercent", () => {
+  test("it maps the range onto 0-100", () => {
+    expect(toPercent(0, 0, 200)).toBe(0)
+
+    expect(toPercent(100, 0, 200)).toBe(50)
+
+    expect(toPercent(200, 0, 200)).toBe(100)
+  })
+
+  test("an offset range starts at its own floor", () => {
+    expect(toPercent(7, 7, 19)).toBe(0)
+
+    expect(toPercent(19, 7, 19)).toBe(100)
+  })
+
+  // A single-valued slider is degenerate but legal, and it should paint
+  // at the start rather than divide by zero and disappear.
+  test("a zero-width range is 0 rather than NaN", () => {
+    expect(toPercent(5, 5, 5)).toBe(0)
+  })
+})
+
+describe("fromFraction", () => {
+  test("it reads a position along the track", () => {
+    expect(fromFraction(0, 0, 100, 1)).toBe(0)
+
+    expect(fromFraction(0.5, 0, 100, 1)).toBe(50)
+
+    expect(fromFraction(1, 0, 100, 1)).toBe(100)
+  })
+
+  test("a pointer past either end is still in range", () => {
+    expect(fromFraction(-0.4, 0, 100, 1)).toBe(0)
+
+    expect(fromFraction(1.8, 0, 100, 1)).toBe(100)
+  })
+
+  /**
+   * `getBoundingClientRect()` is physical and knows nothing about
+   * writing direction, so without this a right-to-left slider runs
+   * backwards under the pointer while its keyboard path is correct.
+   */
+  test("right-to-left inverts the track", () => {
+    expect(fromFraction(0, 0, 100, 1, true)).toBe(100)
+
+    expect(fromFraction(0.25, 0, 100, 1, true)).toBe(75)
+
+    expect(fromFraction(1, 0, 100, 1, true)).toBe(0)
+  })
+
+  test("it snaps to the step like everything else", () => {
+    expect(fromFraction(0.44, 0, 10, 5)).toBe(5)
+  })
+})

package/src/Slider/sliderValue.ts

@@ -0,0 +1,149 @@
+/**
+ * The arithmetic behind `Slider`, kept out of the component so it can be
+ * tested in the node project rather than driven through a pointer.
+ *
+ * Every function here is total: a caller may pass a `NaN`, a reversed
+ * range or a zero step, and the answer is still a number inside the
+ * range. A slider that renders a thumb at `NaN%` is invisible, and the
+ * DOM says nothing about it.
+ */
+
+/** `value` forced into `[min, max]`, whichever way round they arrive. */
+export const clampToRange = (
+  value: number,
+  min: number,
+  max: number,
+): number => {
+  const low = Math.min(min, max)
+
+  const high = Math.max(min, max)
+
+  // NaN only. An infinity is an ORDERED value and clamps like any
+  // other — `Math.min`/`Math.max` already put it at the right end, and
+  // sending +Infinity to the floor would be the wrong end of the range.
+  if (Number.isNaN(value)) return low
+
+  return Math.min(high, Math.max(low, value))
+}
+
+/**
+ * `value` snapped to the nearest `min + n * step`, then clamped.
+ *
+ * Anchored on `min` rather than on zero, which is the difference
+ * between a 0–100 slider (where both agree) and a 7–19 one stepping by
+ * 4: anchored on zero its reachable values are 8, 12, 16 and neither
+ * end of its own range is one of them.
+ *
+ * A non-positive or non-finite `step` means "continuous" and snaps
+ * nothing — it must not divide by zero and hand back `NaN`.
+ */
+export const snapToStep = (
+  value: number,
+  min: number,
+  max: number,
+  step: number,
+): number => {
+  const clamped = clampToRange(value, min, max)
+
+  if (!Number.isFinite(step) || step <= 0) return clamped
+
+  const low = Math.min(min, max)
+
+  const snapped =
+    low + Math.round((clamped - low) / step) * step
+
+  // Re-clamp: the last step can land past `max` when the range is not
+  // a whole number of steps (0–10 by 3 snaps 10 to 9, but 0–10 by 4
+  // would snap 10 to 12 without this).
+  const bounded = clampToRange(snapped, min, max)
+
+  // Float steps accumulate: 0.1 * 3 is 0.30000000000000004, and that
+  // reaches `aria-valuenow` and the visible value both. Round to the
+  // decimals the step itself declares.
+  return roundToStepPrecision(bounded, step)
+}
+
+/**
+ * `value` rounded to as many decimals as `step` has.
+ *
+ * `Number.EPSILON` scaling is deliberately not used — the input here is
+ * always already a multiple of `step` give or take float drift, so the
+ * decimal count of `step` is exactly the precision that can be real.
+ */
+export const roundToStepPrecision = (
+  value: number,
+  step: number,
+): number => {
+  if (!Number.isFinite(step) || step <= 0) return value
+
+  const text = String(step)
+
+  // An exponential step ("1e-7") has no visible decimal point, so
+  // `split(".")` would report zero decimals and round it to an integer.
+  if (text.includes("e") || text.includes("E")) return value
+
+  const decimals = text.split(".")[1]?.length ?? 0
+
+  if (decimals === 0) return Math.round(value)
+
+  const scale = 10 ** decimals
+
+  return Math.round(value * scale) / scale
+}
+
+/**
+ * Where the thumb sits, 0–100, for `inline-size` / `inset-inline-start`.
+ *
+ * A zero-width range is 0% rather than `NaN`: `min === max` is a
+ * degenerate but legal slider (a single-valued one), and it should
+ * paint at the start instead of disappearing.
+ */
+export const toPercent = (
+  value: number,
+  min: number,
+  max: number,
+): number => {
+  const low = Math.min(min, max)
+
+  const high = Math.max(min, max)
+
+  const span = high - low
+
+  if (span <= 0) return 0
+
+  return (
+    ((clampToRange(value, low, high) - low) / span) * 100
+  )
+}
+
+/**
+ * The value a pointer at `fraction` (0–1 along the track) is asking for.
+ *
+ * `isRtl` inverts it. The caller measures with `getBoundingClientRect()`,
+ * which is physical and knows nothing about writing direction, so a
+ * right-to-left slider would otherwise run backwards.
+ */
+export const fromFraction = (
+  fraction: number,
+  min: number,
+  max: number,
+  step: number,
+  isRtl = false,
+): number => {
+  const safe = Number.isFinite(fraction) ? fraction : 0
+
+  const bounded = Math.min(1, Math.max(0, safe))
+
+  const along = isRtl ? 1 - bounded : bounded
+
+  const low = Math.min(min, max)
+
+  const high = Math.max(min, max)
+
+  return snapToStep(
+    low + along * (high - low),
+    min,
+    max,
+    step,
+  )
+}