@crievo/omni 0.1.2 → 0.1.4

package/studio/web/components/bencho/SloshSlider.tsx

@@ -0,0 +1,394 @@
+/* A slider whose value has mass. Ported from bencho.dev (MIT).
+
+   The handle is rigid: it is under your finger and anything under a finger that lags it is broken. The fill is a second
+   spring behind it, softer and barely damped, so a fast drag throws it past the handle, into the end stop, and rocks it
+   back two or three times before it settles. Release halfway and the handle coasts on the velocity it actually had.
+   The tilt is what sells it as liquid: a bar whose leading edge leans in the direction it is travelling is a surface
+   with a meniscus on it, where a bar that only lags is a laggy bar.
+
+   Nothing here goes through React. The loop writes width, a custom property and one attribute straight onto the
+   elements, and it stops the moment everything is at rest. */
+
+import { type CSSProperties, type KeyboardEvent, type PointerEvent, type ReactNode, useEffect, useRef } from "react";
+
+const clamp = (v: number, lo: number, hi: number) => Math.min(hi, Math.max(lo, v));
+
+/* a preference, not a live input: read once */
+const still = () => typeof window !== "undefined" && !!window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
+
+/* The track's corner. 13 is what it was drawn at and 20 is half of its 40px height: the pill, as round as a 40px
+   track can be. The knob inside stays a circle: it is a ball in a slot. */
+const SLO_CORNER = 20;
+const SLO_MAX = 20;
+
+/* decimals of a step (0.005 -> 3), so quantizing does not leave 0.30000000000000004 in what the caller reads */
+const decimals = (n: number) => (String(n).split(".")[1] ?? "").length;
+
+/* A mark within this share of the range pulls the reported value onto it, as the Radix slider here always has */
+const SNAP = 0.03;
+
+/* Gaps longer than this between the last pointer move and the release mean the finger had stopped: no coast */
+const STALE_MS = 80;
+
+export function SloshSlider({
+  /* 0 is a rigid fill, 100 is loose liquid. 15 is a little give rather than a wave in a glass. */
+  viscosity = 15,
+  /* how far it coasts after release, 0..100 */
+  momentum = 55,
+  /* lean on the leading edge, 0..100 */
+  tilt = 45,
+  /* the corner it is cut with */
+  corner = SLO_CORNER,
+  /* controlled use. Values are in the min..max scale and travel as a one-entry array, the way the Radix slider that
+     this replaces reports them. Without them it is the demo: 0..100, starting at 62, continuous, reporting nowhere. */
+  value,
+  defaultValue,
+  min = 0,
+  max = 100,
+  /* what the caller reads is quantized to this; the handle and the liquid stay smooth, and the handle settles onto the
+     quantized position once it is let go. Undefined is continuous. */
+  step,
+  disabled = false,
+  onValueChange,
+  /* on release, and again if the handle then coasts somewhere else */
+  onValueCommit,
+  /* text inside the track */
+  label,
+  /* a dashed line at this value, and with snapToMark the reported value sticks to it when the handle is close */
+  markValue,
+  snapToMark = false,
+  /* fills the width it is given instead of the demo's 320px */
+  fluid = false,
+  className,
+  id,
+  ariaLabel = "Fluxo",
+  ariaLabelledBy,
+  ariaDescribedBy,
+  ...rest
+}: {
+  viscosity?: number;
+  momentum?: number;
+  tilt?: number;
+  corner?: number;
+  value?: number[];
+  defaultValue?: number[];
+  min?: number;
+  max?: number;
+  step?: number;
+  disabled?: boolean;
+  onValueChange?: (value: number[]) => void;
+  onValueCommit?: (value: number[]) => void;
+  label?: ReactNode;
+  markValue?: number;
+  snapToMark?: boolean;
+  fluid?: boolean;
+  className?: string;
+  id?: string;
+  ariaLabel?: string;
+  ariaLabelledBy?: string;
+  ariaDescribedBy?: string;
+  /* data-* and the like, which the studio's slider wrapper puts on the root */
+  [attr: `data-${string}`]: string | undefined;
+} = {}) {
+  const track = useRef<HTMLDivElement | null>(null);
+  const fillEl = useRef<HTMLDivElement | null>(null);
+  const knobEl = useRef<HTMLDivElement | null>(null);
+  const reduced = still();
+
+  /* what the caller has said, live: the loop and the handlers outlive any one render */
+  const props = useRef({ value: value?.[0], min, max, step, markValue, snapToMark, onValueChange, onValueCommit });
+  props.current = { value: value?.[0], min, max, step, markValue, snapToMark, onValueChange, onValueCommit };
+
+  /* the value as the caller reads it from a position on the track (0..100): the handle's true position, quantized and
+     snapped. Never the fill, which lags and overshoots on purpose. */
+  const report = (pos: number, snap = true) => {
+    const p = props.current;
+    const span = p.max - p.min;
+    let v = p.min + (pos / 100) * span;
+    if (p.step) v = Number((p.min + Math.round((v - p.min) / p.step) * p.step).toFixed(decimals(p.step)));
+    v = clamp(v, p.min, p.max);
+    if (snap && p.snapToMark && p.markValue !== undefined && Math.abs(v - p.markValue) <= span * SNAP)
+      return p.markValue;
+    return v;
+  };
+  const posOf = (v: number) => (max === min ? 0 : clamp(((v - min) / (max - min)) * 100, 0, 100));
+
+  /* the handle, its velocity after release, and the fill chasing it with a velocity of its own */
+  const start = value?.[0] ?? defaultValue?.[0] ?? (min === 0 && max === 100 ? 62 : min);
+  const val = useRef(posOf(start));
+  const hv = useRef(0);
+  const fill = useRef(posOf(start));
+  const fv = useRef(0);
+  const held = useRef(false);
+  const raf = useRef(0);
+  /* the last two samples, which is all a release velocity is */
+  const last = useRef({ v: val.current, t: 0 });
+  /* the last value the caller was told, so an echo of it from a controlled parent is not mistaken for a new one */
+  const told = useRef(start);
+  /* where the handle eases to after it is let go, so it sits on the value the caller holds and not between two steps */
+  const settle = useRef<number | null>(null);
+  /* a release that is still travelling has not committed yet */
+  const commitAtRest = useRef(false);
+  const range = useRef({ min, max });
+
+  /* live, so the loop reads what the panel is currently set to without restarting on every drag of a knob */
+  const knobs = useRef({ viscosity, momentum, tilt, reduced });
+  knobs.current = { viscosity, momentum, tilt, reduced };
+
+  /* the loop parks itself when everything is at rest, so every handler below needs a way to wake it back up */
+  const run = useRef<() => void>(() => {});
+
+  const emit = (snap = true) => {
+    const v = report(val.current, snap);
+    if (v === told.current) return;
+    told.current = v;
+    props.current.onValueChange?.([v]);
+  };
+  const commit = () => props.current.onValueCommit?.([told.current]);
+  const armSettle = () => {
+    if (!props.current.step) return;
+    const to = posOf(report(val.current));
+    settle.current = Math.abs(to - val.current) > 0.005 ? to : null;
+  };
+
+  useEffect(() => {
+    const paint = () => {
+      const f = fillEl.current;
+      const k = knobEl.current;
+      const t = track.current;
+      if (!f || !k || !t) return;
+      f.style.width = `${fill.current.toFixed(2)}%`;
+      k.style.left = `${val.current.toFixed(2)}%`;
+      /* the meniscus: proportional to how fast the fill is actually moving, so it is upright at rest */
+      const lean = knobs.current.reduced ? 0 : clamp((knobs.current.tilt / 100) * fv.current * 3, -20, 20);
+      f.style.setProperty("--lean", `${lean.toFixed(2)}px`);
+      t.setAttribute("aria-valuenow", String(Math.round(report(val.current) * 100) / 100));
+    };
+
+    const rest = () =>
+      !held.current &&
+      Math.abs(hv.current) < 0.01 &&
+      settle.current === null &&
+      Math.abs(fv.current) < 0.01 &&
+      Math.abs(val.current - fill.current) < 0.02;
+
+    let prev = 0;
+    const tick = (t: number) => {
+      const dt = prev ? clamp((t - prev) / 16.67, 0, 2.5) : 1;
+      prev = t;
+      const { viscosity: v, momentum: m, reduced: flat } = knobs.current;
+
+      /* the coast: friction is per frame, so it is raised to dt rather than multiplied by it, and a dropped frame
+         does not double the deceleration */
+      if (!held.current && hv.current) {
+        val.current += hv.current * dt;
+        hv.current *= (0.86 + (m / 100) * 0.115) ** dt;
+        if (val.current <= 0 || val.current >= 100) {
+          val.current = clamp(val.current, 0, 100);
+          hv.current = 0;
+        }
+        if (Math.abs(hv.current) < 0.01) hv.current = 0;
+        emit();
+        if (!hv.current) armSettle();
+      } else if (!held.current && settle.current !== null) {
+        val.current += (settle.current - val.current) * Math.min(1, 0.3 * dt);
+        if (Math.abs(settle.current - val.current) < 0.02) {
+          val.current = settle.current;
+          settle.current = null;
+        }
+        emit();
+      }
+
+      const soft = flat ? 0 : v / 100;
+      if (soft === 0) {
+        /* 0 is an ordinary slider and has to be exactly that, not a very stiff spring that still rings */
+        fill.current = val.current;
+        fv.current = 0;
+      } else {
+        /* stiffness falls and damping rises together: thin liquid is slow to answer and slow to forget, which is the
+           same thing said twice and is why these are one knob rather than two */
+        const stiff = 0.34 - soft * 0.29;
+        const damp = 0.74 + soft * 0.22;
+        fv.current += (val.current - fill.current) * stiff * dt;
+        fv.current *= damp ** dt;
+        fill.current += fv.current * dt;
+        /* the end stop is a wall, and a wall gives some back: without this the overshoot at the top of the track is
+           swallowed and the liquid stops behaving like liquid exactly where you are looking */
+        if (fill.current > 100) {
+          fill.current = 100;
+          fv.current = -fv.current * 0.42;
+        } else if (fill.current < 0) {
+          fill.current = 0;
+          fv.current = -fv.current * 0.42;
+        }
+        if (Math.abs(val.current - fill.current) < 0.02 && Math.abs(fv.current) < 0.02) {
+          fill.current = val.current;
+          fv.current = 0;
+        }
+      }
+
+      paint();
+      if (rest()) {
+        raf.current = 0;
+        prev = 0;
+        if (commitAtRest.current) {
+          commitAtRest.current = false;
+          commit();
+        }
+        /* a parent that answered with something other than what it was told (a clamp, a refusal) has the last word */
+        const want = props.current.value;
+        if (want !== undefined && want !== told.current) {
+          told.current = want;
+          val.current = posOf(want);
+          raf.current = requestAnimationFrame(tick);
+        }
+        return;
+      }
+      raf.current = requestAnimationFrame(tick);
+    };
+
+    run.current = () => {
+      if (!raf.current) raf.current = requestAnimationFrame(tick);
+    };
+    paint();
+    return () => {
+      cancelAnimationFrame(raf.current);
+      raf.current = 0;
+    };
+  }, []);
+
+  /* A value changed from outside moves the handle there and lets the liquid catch up, the same way Home does. While a
+     finger is on it, or the handle is still travelling from one, the parent is only echoing what it was told and the
+     user is the one in charge. A new range is a new position for the same value. */
+  useEffect(() => {
+    const moved = range.current.min !== min || range.current.max !== max;
+    range.current = { min, max };
+    if (held.current || hv.current) return;
+    const want = value?.[0];
+    if (want === undefined || (want === told.current && !moved)) return;
+    told.current = want;
+    settle.current = null;
+    val.current = posOf(want);
+    run.current();
+  }, [value?.[0], min, max]);
+
+  /* offset maths, then divided by the zoom, so a scaled ancestor does not skew the reading */
+  const readAt = (clientX: number) => {
+    const t = track.current;
+    if (!t) return 0;
+    const box = t.getBoundingClientRect();
+    const k = box.width / (t.offsetWidth || box.width) || 1;
+    return clamp(((clientX - box.left) / k / t.offsetWidth) * 100, 0, 100);
+  };
+
+  const grab = (e: PointerEvent) => {
+    if (disabled || (e.pointerType === "mouse" && e.button !== 0)) return;
+    e.currentTarget.setPointerCapture?.(e.pointerId);
+    held.current = true;
+    hv.current = 0;
+    settle.current = null;
+    commitAtRest.current = false;
+    val.current = readAt(e.clientX);
+    last.current = { v: val.current, t: e.timeStamp };
+    emit();
+    run.current();
+  };
+
+  const move = (e: PointerEvent) => {
+    if (!held.current) return;
+    const v = readAt(e.clientX);
+    const dt = Math.max(1, e.timeStamp - last.current.t);
+    /* per frame, not per ms: the whole loop is in frames and a release velocity in the other unit is a hundred times
+       too big */
+    hv.current = ((v - last.current.v) / dt) * 16.67;
+    last.current = { v, t: e.timeStamp };
+    val.current = v;
+    emit();
+    run.current();
+  };
+
+  const drop = (e: PointerEvent) => {
+    if (!held.current) return;
+    held.current = false;
+    /* it leaves along the velocity it actually had, capped so a flick across the whole track does not simply pin it.
+       A finger that had stopped before it lifted had none: the last move is old news, and a precision control must not
+       wander off from where it was put. */
+    hv.current = clamp(hv.current, -6, 6);
+    if (knobs.current.reduced || e.timeStamp - last.current.t > STALE_MS) hv.current = 0;
+    if (!hv.current) armSettle();
+    commit();
+    commitAtRest.current = hv.current !== 0 || settle.current !== null;
+    run.current();
+  };
+
+  const key = (e: KeyboardEvent) => {
+    if (disabled) return;
+    const p = props.current;
+    const unit = p.step ?? (p.max - p.min) / 100;
+    const big = e.shiftKey || e.key === "PageUp" || e.key === "PageDown";
+    const now = told.current;
+    const to =
+      e.key === "ArrowRight" || e.key === "ArrowUp" || e.key === "PageUp"
+        ? now + unit * (big ? 10 : 1)
+        : e.key === "ArrowLeft" || e.key === "ArrowDown" || e.key === "PageDown"
+          ? now - unit * (big ? 10 : 1)
+          : e.key === "Home"
+            ? p.min
+            : e.key === "End"
+              ? p.max
+              : null;
+    if (to === null) return;
+    e.preventDefault();
+    hv.current = 0;
+    settle.current = null;
+    /* from the value the caller holds, with no snapping: next to a mark the arrow would otherwise land on it forever */
+    val.current = posOf(to);
+    emit(false);
+    commit();
+    run.current();
+  };
+
+  const markPos = markValue !== undefined ? posOf(markValue) : null;
+
+  return (
+    <div
+      {...rest}
+      className={`bn-slo${fluid ? " bn-slo--fluid" : ""}${className ? ` ${className}` : ""}`}
+      style={{ "--slo-r": `${clamp(corner, 0, SLO_MAX)}px` } as CSSProperties}
+      data-disabled={disabled ? "" : undefined}
+    >
+      {/* nothing but the track: a caption and a readout bracketing it is what every slider looks like, and the number
+          would read the fill, which lags, a second telling of what the liquid is already saying */}
+      <div
+        className="bn-slo-track"
+        data-slot="slider-track"
+        ref={track}
+        id={id}
+        role="slider"
+        tabIndex={disabled ? -1 : 0}
+        aria-label={ariaLabelledBy || !ariaLabel ? undefined : ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        aria-disabled={disabled || undefined}
+        aria-valuemin={min}
+        aria-valuemax={max}
+        aria-valuenow={start}
+        aria-orientation="horizontal"
+        onPointerDown={grab}
+        onPointerMove={move}
+        onPointerUp={drop}
+        onPointerCancel={drop}
+        onKeyDown={key}
+      >
+        <div className="bn-slo-fill" ref={fillEl} style={{ width: `${fill.current.toFixed(2)}%` }} />
+        {markPos !== null && <span aria-hidden className="bn-slo-mark" style={{ left: `${markPos}%` }} />}
+        <div className="bn-slo-knob" ref={knobEl} style={{ left: `${val.current.toFixed(2)}%` }} />
+        {label !== undefined && (
+          <span aria-hidden className="bn-slo-label">
+            {label}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}