@ambientcss/components 2.1.0 → 3.0.0

package/src/core/useBank.ts

@@ -0,0 +1,163 @@
+import { useCallback, useRef } from "react";
+import type { KeyboardEvent, ReactNode } from "react";
+import { useControllableValue } from "./controllable";
+
+export type BankOption = {
+  value: string;
+  /** Key legend — a numeral in the referent, but any node works. */
+  label?: ReactNode | undefined;
+  /** Accessible name, and the hover title. Needed whenever the legend is a
+   *  glyph or an icon: a key reading "*" has no name otherwise. */
+  ariaLabel?: string | undefined;
+  /** Overrides the bank's lamp colour for this key only. */
+  color?: string | undefined;
+  disabled?: boolean | undefined;
+};
+
+export type BankOrientation = "vertical" | "horizontal";
+
+export type UseBankOptions = {
+  options: BankOption[];
+  value?: string | string[] | undefined;
+  defaultValue?: string | string[] | undefined;
+  onChange?: ((value: string | string[]) => void) | undefined;
+  /** Let more than one lamp be lit at a time. */
+  multiple?: boolean | undefined;
+  orientation?: BankOrientation | undefined;
+  disabled?: boolean | undefined;
+};
+
+function toArray(value: string | string[] | undefined): string[] {
+  if (value === undefined) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/** N presses sharing a selection model.
+ *
+ *  The roving tabindex, the radiogroup-versus-checkbox-group keyboard
+ *  difference and the selection-follows-focus rule are the reason this
+ *  mechanism exists: they are the part nobody should have to re-derive in
+ *  order to change what a key looks like. */
+export function useBank(options: UseBankOptions) {
+  const { options: items, multiple = false, orientation = "vertical", disabled = false } = options;
+
+  const [raw, setRaw] = useControllableValue<string | string[]>(
+    options.value,
+    options.defaultValue ?? (multiple ? [] : ""),
+    options.onChange
+  );
+  const selected = toArray(raw);
+  const keyRefs = useRef<Array<HTMLButtonElement | null>>([]);
+
+  const commit = useCallback(
+    (next: string[]) => setRaw(multiple ? next : (next[0] ?? "")),
+    [setRaw, multiple]
+  );
+
+  const select = useCallback(
+    (option: BankOption | undefined) => {
+      if (!option || option.disabled || disabled) return;
+      if (!multiple) return commit([option.value]);
+      commit(
+        selected.includes(option.value)
+          ? selected.filter((v) => v !== option.value)
+          : [...selected, option.value]
+      );
+    },
+    [commit, multiple, selected, disabled]
+  );
+
+  const enabled = items.filter((o) => !o.disabled);
+  /* Roving tabindex: exactly one key is tab-reachable. The lit one owns the
+     stop, so Tab lands where the eye already is; with nothing lit (or in
+     multiple mode, where every lamp is independent) the first enabled key
+     takes it. */
+  const litIndex = items.findIndex((o) => selected.includes(o.value) && !o.disabled);
+  const firstEnabled = items.findIndex((o) => !o.disabled);
+  const tabStop = multiple ? -1 : litIndex >= 0 ? litIndex : firstEnabled;
+
+  const focusAt = (index: number) => keyRefs.current[index]?.focus();
+
+  const step = (from: number, delta: number) => {
+    if (enabled.length === 0) return;
+    let i = from;
+    for (let guard = 0; guard < items.length; guard += 1) {
+      i = (i + delta + items.length) % items.length;
+      if (!items[i]?.disabled) break;
+    }
+    focusAt(i);
+    /* A radio group moves selection with focus (WAI-ARIA radiogroup
+       pattern); a checkbox group only moves focus, since each lamp toggles
+       on its own. */
+    if (!multiple) select(items[i]);
+  };
+
+  const edge = (which: "first" | "last") => {
+    const i =
+      which === "first" ? firstEnabled : items.map((o) => !o.disabled).lastIndexOf(true);
+    if (i < 0) return;
+    focusAt(i);
+    if (!multiple) select(items[i]);
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLButtonElement>, index: number) => {
+    const back = orientation === "vertical" ? "ArrowUp" : "ArrowLeft";
+    const forward = orientation === "vertical" ? "ArrowDown" : "ArrowRight";
+    switch (event.key) {
+      case back:
+        event.preventDefault();
+        step(index, -1);
+        break;
+      case forward:
+        event.preventDefault();
+        step(index, 1);
+        break;
+      case "Home":
+        event.preventDefault();
+        edge("first");
+        break;
+      case "End":
+        event.preventDefault();
+        edge("last");
+        break;
+      case " ":
+      case "Enter":
+        event.preventDefault();
+        select(items[index]);
+        break;
+      default:
+        break;
+    }
+  };
+
+  const rootProps = {
+    role: multiple ? ("group" as const) : ("radiogroup" as const),
+    "aria-orientation": multiple ? undefined : orientation,
+    "aria-disabled": disabled || undefined,
+    "data-orientation": orientation,
+    "data-disabled": disabled ? "" : undefined
+  };
+
+  /** Props for the key at `index`, including its own state channel. */
+  const keyProps = (option: BankOption, index: number) => {
+    const on = selected.includes(option.value);
+    return {
+      key: option.value,
+      type: "button" as const,
+      ref: (node: HTMLButtonElement | null) => {
+        keyRefs.current[index] = node;
+      },
+      role: multiple ? ("checkbox" as const) : ("radio" as const),
+      "aria-checked": on,
+      "aria-label": option.ariaLabel,
+      title: option.ariaLabel,
+      disabled: option.disabled || disabled,
+      tabIndex: multiple ? 0 : index === tabStop ? 0 : -1,
+      "data-on": on ? "" : undefined,
+      onClick: () => select(option),
+      onKeyDown: (event: KeyboardEvent<HTMLButtonElement>) => onKeyDown(event, index)
+    };
+  };
+
+  return { selected, select, rootProps, keyProps };
+}

package/src/core/useLatch.ts

@@ -0,0 +1,54 @@
+import { useMemo } from "react";
+import type { CSSProperties } from "react";
+import { useControllableValue } from "./controllable";
+import { stateData, stateStyle } from "./types";
+import type { ControlState } from "./types";
+
+export type UseLatchOptions = {
+  value?: boolean | undefined;
+  defaultValue?: boolean | undefined;
+  onChange?: ((next: boolean) => void) | undefined;
+  disabled?: boolean | undefined;
+};
+
+/** A two-position travel. Kept distinct from Press because its actuator
+ *  genuinely slides rather than sinking, and because its ARIA is
+ *  `role="switch"` — a switch is a state, not an action. */
+export function useLatch(options: UseLatchOptions) {
+  const { disabled = false } = options;
+  const [on, setOn] = useControllableValue(
+    options.value,
+    options.defaultValue ?? false,
+    options.onChange
+  );
+
+  const state: ControlState = useMemo(
+    () => ({
+      value: on ? 1 : 0,
+      min: 0,
+      max: 1,
+      percent: on ? 1 : 0,
+      angle: 0,
+      travelStart: 0,
+      travelSweep: 0,
+      detents: 2,
+      dragging: false,
+      disabled,
+      atMin: !on,
+      atMax: on
+    }),
+    [on, disabled]
+  );
+
+  const rootProps = {
+    type: "button" as const,
+    role: "switch" as const,
+    "aria-checked": on,
+    disabled,
+    style: stateStyle(state) as CSSProperties,
+    ...stateData(state),
+    onClick: () => setOn(!on)
+  };
+
+  return { state, rootProps, on, setOn };
+}

package/src/core/usePress.ts

@@ -0,0 +1,120 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { CSSProperties, PointerEvent } from "react";
+import { useControllableValue } from "./controllable";
+import { stateData, stateStyle } from "./types";
+import type { ControlState } from "./types";
+
+/** A transport key, a latching mute and an auto-repeating nudge button are
+ *  the same object with three state machines and identical paint. */
+export type PressMode = "momentary" | "toggle" | "repeat";
+
+export type UsePressOptions = {
+  mode?: PressMode | undefined;
+  /** `toggle` mode only: the pressed-in state. */
+  value?: boolean | undefined;
+  defaultValue?: boolean | undefined;
+  onChange?: ((next: boolean) => void) | undefined;
+  /** Fires once per activation, and repeatedly in `repeat` mode. */
+  onPress?: (() => void) | undefined;
+  /** `repeat` mode: delay before repeating starts, then its interval. */
+  repeatDelay?: number | undefined;
+  repeatInterval?: number | undefined;
+  disabled?: boolean | undefined;
+};
+
+export function usePress(options: UsePressOptions) {
+  const {
+    mode = "momentary",
+    repeatDelay = 400,
+    repeatInterval = 60,
+    disabled = false
+  } = options;
+
+  const [on, setOn] = useControllableValue(
+    options.value,
+    options.defaultValue ?? false,
+    options.onChange
+  );
+  const [held, setHeld] = useState(false);
+
+  const onPressRef = useRef(options.onPress);
+  onPressRef.current = options.onPress;
+  const timers = useRef<{ delay?: ReturnType<typeof setTimeout>; tick?: ReturnType<typeof setInterval> }>(
+    {}
+  );
+
+  const stopRepeat = useCallback(() => {
+    if (timers.current.delay) clearTimeout(timers.current.delay);
+    if (timers.current.tick) clearInterval(timers.current.tick);
+    timers.current = {};
+  }, []);
+
+  /* A held key that unmounts must not keep firing. */
+  useEffect(() => stopRepeat, [stopRepeat]);
+
+  const activate = useCallback(() => {
+    if (mode === "toggle") setOn(!on);
+    onPressRef.current?.();
+  }, [mode, on, setOn]);
+
+  const pressed = mode === "toggle" ? on : held;
+
+  const state: ControlState = useMemo(
+    () => ({
+      value: pressed ? 1 : 0,
+      min: 0,
+      max: 1,
+      percent: pressed ? 1 : 0,
+      angle: 0,
+      travelStart: 0,
+      travelSweep: 0,
+      detents: 2,
+      dragging: held,
+      disabled,
+      atMin: !pressed,
+      atMax: pressed
+    }),
+    [pressed, held, disabled]
+  );
+
+  const rootProps = {
+    type: "button" as const,
+    disabled,
+    "aria-pressed": mode === "toggle" ? on : undefined,
+    style: stateStyle(state) as CSSProperties,
+    "data-pressed": pressed ? "" : undefined,
+    "data-mode": mode,
+    ...stateData(state),
+    onPointerDown: (event: PointerEvent<HTMLButtonElement>) => {
+      if (disabled || event.button !== 0) return;
+      setHeld(true);
+      if (mode !== "repeat") return;
+      /* Repeat fires immediately, then accelerates into its interval —
+         the same shape a keyboard's own auto-repeat has, so a held nudge
+         button does not feel like a different kind of control. */
+      onPressRef.current?.();
+      timers.current.delay = setTimeout(() => {
+        timers.current.tick = setInterval(() => onPressRef.current?.(), repeatInterval);
+      }, repeatDelay);
+    },
+    onPointerUp: () => {
+      setHeld(false);
+      stopRepeat();
+    },
+    onPointerCancel: () => {
+      setHeld(false);
+      stopRepeat();
+    },
+    onPointerLeave: () => {
+      setHeld(false);
+      stopRepeat();
+    },
+    onClick: () => {
+      /* Repeat already fired on the press; firing again on click would
+         double every tap. */
+      if (mode !== "repeat") activate();
+    }
+  };
+
+  return { state, rootProps, pressed, on, setOn };
+}

package/src/core/useRotary.ts

@@ -0,0 +1,253 @@
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { CSSProperties, KeyboardEvent, PointerEvent } from "react";
+import { useControllableValue } from "./controllable";
+import { clamp, commit, denormalise, normalise, valueKeyHandler } from "./numeric";
+import { stateData, stateStyle } from "./types";
+import { isDev } from "./dev";
+import type { ControlState } from "./types";
+
+/** How pointer movement becomes value.
+ *
+ *  These are three different mappings, not one with a parameter, and the
+ *  library was ambiguous about which it implemented: the code did `angle`
+ *  while knob.md documented `drag`. Naming it makes that drift impossible.
+ *
+ *  - `drag`  pointer DISTANCE -> value delta. The v3 default: it is what the
+ *            docs always described, what most audio software does, and the
+ *            only one that behaves on touch, where a finger covers the knob.
+ *  - `angle` pointer POSITION -> absolute angle -> value. Needs a dead zone,
+ *            and needs a sweep under a full turn to be unambiguous.
+ *  - `delta` accumulated angular change. The endless-encoder mapping: no
+ *            ends, no dead zone, and the value may wrap independently of
+ *            where the pointer happens to be. */
+export type RotaryInput = "drag" | "angle" | "delta";
+
+/** The pot's travel in degrees clockwise from 12 o'clock. A bare number is
+ *  a sweep centred on 12 o'clock, so `270` is the default 8-to-4 pot. */
+export type RotaryTravel = number | { start: number; sweep: number };
+
+export type UseRotaryOptions = {
+  value?: number | undefined;
+  defaultValue?: number | undefined;
+  min?: number | undefined;
+  max?: number | undefined;
+  /** Quantises the VALUE. `0` leaves it continuous. */
+  step?: number | undefined;
+  /** Quantises the TRAVEL: rest positions along the arc. Defaults to the
+   *  step grid, but the two are independent — an endless encoder can have
+   *  24 detents per turn while its value stays continuous. */
+  detents?: number | undefined;
+  travel?: RotaryTravel | undefined;
+  input?: RotaryInput | undefined;
+  /** Pixels of drag for one full range, in `drag` mode. */
+  dragDistance?: number | undefined;
+  /** `delta` mode only: run past the ends and come round again. */
+  wrap?: boolean | undefined;
+  disabled?: boolean | undefined;
+  onChange?: ((next: number) => void) | undefined;
+};
+
+const DEFAULT_TRAVEL = { start: -135, sweep: 270 };
+
+/** Fold an angle into (-180, 180]. */
+function wrapDeg(deg: number): number {
+  return ((((deg + 180) % 360) + 360) % 360) - 180;
+}
+
+function resolveTravel(travel: RotaryTravel | undefined) {
+  if (travel === undefined) return DEFAULT_TRAVEL;
+  if (typeof travel === "number") return { start: -travel / 2, sweep: travel };
+  return travel;
+}
+
+let warnedFullTurn = false;
+
+/** Pointer capture, but survivable.
+ *
+ *  `setPointerCapture` throws NotFoundError for a pointer id the browser
+ *  does not currently have down, and is missing outright in jsdom. Neither
+ *  happens with a real finger, but both happen constantly in tests — and an
+ *  exception here would abort the handler before the drag ever starts,
+ *  making the control look broken rather than untestable. */
+export function capturePointer(target: Element, pointerId: number): void {
+  try {
+    target.setPointerCapture?.(pointerId);
+  } catch {
+    /* Without capture the drag still tracks; it just stops at the edge of
+       the element instead of following the pointer off it. */
+  }
+}
+
+export function useRotary(options: UseRotaryOptions) {
+  const {
+    min = 0,
+    max = 100,
+    step = 1,
+    dragDistance = 200,
+    wrap = false,
+    disabled = false
+  } = options;
+
+  const { start, sweep } = resolveTravel(options.travel);
+
+  /* A full turn cannot be read as an absolute angle: 0 and max land on the
+     same screen position, and the dead-zone clamp has no end to snap to.
+     Fall back rather than misbehave silently. */
+  let input = options.input ?? "drag";
+  if (input === "angle" && Math.abs(sweep) >= 360) {
+    if (isDev && !warnedFullTurn) {
+      warnedFullTurn = true;
+      console.warn(
+        `[@ambientcss/components] input="angle" needs a sweep under a full turn ` +
+          `(got ${sweep}deg): an absolute angle is ambiguous at 360deg, where the ` +
+          `first and last values share a screen position. Falling back to "drag".`
+      );
+    }
+    input = "drag";
+  }
+
+  const [value, setValue] = useControllableValue(
+    options.value,
+    options.defaultValue ?? min,
+    options.onChange
+  );
+
+  /* `dragging` is state because the root publishes it as data-dragging, and
+     a REF because the move handler has to gate on it. Reading the state in
+     the handler drops every move that fires before React re-renders after
+     the press — which is most of them on a fast drag. */
+  const [dragging, setDragging] = useState(false);
+  const draggingRef = useRef(false);
+  const rootRef = useRef<HTMLDivElement | null>(null);
+  /* Drag bookkeeping. Deltas are accumulated rather than measured from the
+     press point so that toggling the fine-mode modifier mid-drag changes
+     the gearing from here on instead of jumping the value. */
+  const drag = useRef({ value: 0, clientY: 0, angle: 0, accum: 0 });
+
+  const range = max - min;
+  const keyStep = step > 0 ? step : range / 100 || 1;
+  const percent = clamp(normalise(value, min, max), 0, 1);
+  const angle = start + percent * sweep;
+
+  const set = useCallback(
+    (next: number) => setValue(commit(next, min, max, step)),
+    [setValue, min, max, step]
+  );
+
+  /** Pointer position as an angle in degrees clockwise from 12 o'clock. */
+  const pointerAngle = (event: PointerEvent<HTMLElement>): number | null => {
+    const rect = rootRef.current?.getBoundingClientRect();
+    if (!rect) return null;
+    const dx = event.clientX - (rect.left + rect.width / 2);
+    const dy = event.clientY - (rect.top + rect.height / 2);
+    // atan2 in screen coords reads 0 at 3 o'clock and grows clockwise; +90
+    // rotates the origin to 12 o'clock.
+    return Math.atan2(dy, dx) * (180 / Math.PI) + 90;
+  };
+
+  const fromAngle = (event: PointerEvent<HTMLElement>) => {
+    const raw = pointerAngle(event);
+    if (raw === null) return;
+    /* Fold the reading into the half-turn either side of the sweep's own
+       midpoint, so a sweep whose end passes 180deg stays reachable. */
+    const mid = start + sweep / 2;
+    let a = mid + wrapDeg(raw - mid);
+    const end = start + sweep;
+    if (a < Math.min(start, end) || a > Math.max(start, end)) {
+      /* In the dead zone: hold at whichever end is angularly nearer. The
+         pre-v3 code chose by which half the value was in, which threw the
+         knob to the far end whenever a drag crossed the gap. */
+      const toStart = Math.abs(wrapDeg(a - start));
+      const toEnd = Math.abs(wrapDeg(a - end));
+      a = toStart <= toEnd ? start : end;
+    }
+    set(denormalise((a - start) / (sweep || 1), min, max));
+  };
+
+  const fromDrag = (event: PointerEvent<HTMLElement>) => {
+    const dy = drag.current.clientY - event.clientY;
+    drag.current.clientY = event.clientY;
+    drag.current.accum += dy * (event.shiftKey ? 0.25 : 1);
+    set(drag.current.value + (drag.current.accum / dragDistance) * range);
+  };
+
+  const fromDelta = (event: PointerEvent<HTMLElement>) => {
+    const raw = pointerAngle(event);
+    if (raw === null) return;
+    drag.current.accum += wrapDeg(raw - drag.current.angle);
+    drag.current.angle = raw;
+    const next = drag.current.value + (drag.current.accum / (sweep || 360)) * range;
+    set(wrap && range > 0 ? min + (((next - min) % range) + range) % range : next);
+  };
+
+  const track = (event: PointerEvent<HTMLElement>) => {
+    if (input === "angle") fromAngle(event);
+    else if (input === "delta") fromDelta(event);
+    else fromDrag(event);
+  };
+
+  const state: ControlState = useMemo(
+    () => ({
+      value,
+      min,
+      max,
+      percent,
+      angle,
+      travelStart: start,
+      travelSweep: sweep,
+      detents: options.detents ?? (step > 0 && range > 0 ? Math.round(range / step) : 0),
+      dragging,
+      disabled,
+      atMin: value <= min,
+      atMax: value >= max
+    }),
+    [value, min, max, percent, angle, start, sweep, options.detents, step, range, dragging, disabled]
+  );
+
+  const onKeyDown = valueKeyHandler({ value, min, max, step: keyStep, disabled, onChange: setValue });
+
+  const rootProps = {
+    ref: rootRef,
+    role: "slider" as const,
+    "aria-valuemin": min,
+    "aria-valuemax": max,
+    "aria-valuenow": value,
+    "aria-orientation": "vertical" as const,
+    "aria-disabled": disabled || undefined,
+    tabIndex: disabled ? -1 : 0,
+    style: stateStyle(state) as CSSProperties,
+    ...stateData(state),
+    onPointerDown: (event: PointerEvent<HTMLDivElement>) => {
+      if (disabled || event.button !== 0) return;
+      capturePointer(event.currentTarget, event.pointerId);
+      draggingRef.current = true;
+      setDragging(true);
+      drag.current = {
+        value,
+        clientY: event.clientY,
+        angle: pointerAngle(event) ?? 0,
+        accum: 0
+      };
+      /* Only the absolute mapping jumps to the press point; the relative
+         ones would lurch, which is the whole reason to prefer them. */
+      if (input === "angle") fromAngle(event);
+    },
+    onPointerMove: (event: PointerEvent<HTMLDivElement>) => {
+      if (!draggingRef.current || disabled) return;
+      track(event);
+    },
+    onPointerUp: () => {
+      draggingRef.current = false;
+      setDragging(false);
+    },
+    onPointerCancel: () => {
+      draggingRef.current = false;
+      setDragging(false);
+    },
+    onKeyDown: (event: KeyboardEvent<HTMLDivElement>) => {
+      onKeyDown(event);
+    }
+  };
+
+  return { state, rootProps, setValue: set };
+}