@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/fields/Slider/Slider.spec.tsx

@@ -1,11 +1,30 @@
 import { useForm } from "@tanstack/react-form";
-import { act, fireEvent, waitFor } from "@testing-library/react";
-import { YStack } from "tamagui";
-import { describe, expect, it, vi } from "vitest";
+import { act, fireEvent, renderHook, waitFor } from "@testing-library/react";
+import { getSize } from "@tamagui/get-token";
+import { YStack, getTokens, getVariableValue } from "tamagui";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { Button } from "../../Button";
 import { Form } from "../../Form";
 import { Slider } from "./index";
+import {
+  INSTANT_X_TRANSITION,
+  JUMP_RELEASE_THRESHOLD_PX,
+  NATIVE_JUMP_SETTLE_MS,
+  getClosestThumbIndex,
+  getJumpDelta,
+  getJumpSettleMs,
+  getNextSortedValues,
+  getSliderThumbRenderSize,
+  getSpringResidualPx,
+  getThumbBaseX,
+  hasMinStepsBetween,
+  snapSliderValue,
+  useSliderJumpMotion,
+} from "./jumpMotion";
+
+/** The repo's `quick` motion token physics (theme animationConfig). */
+const QUICK_SPRING = { type: "spring", damping: 20, mass: 1.2, stiffness: 250 } as const;
 
 describe("Slider", () => {
   describe("basic rendering", () => {
@@ -41,6 +60,31 @@ describe("Slider", () => {
       }
       expect(onValueChange).toHaveBeenCalled();
     });
+
+    it("fires canonical onChange and the deprecated onValueChange alias with the same payload", async () => {
+      const onChange = vi.fn();
+      const onValueChange = vi.fn();
+      const result = renderWithProviders(
+        <Slider
+          label="Canonical Slider"
+          name="canonical"
+          value={[30]}
+          onChange={onChange}
+          onValueChange={onValueChange}
+        />,
+      );
+      const slider = result.container.querySelector('[role="slider"]');
+      expect(slider).toBeTruthy();
+      if (slider) {
+        await act(async () => {
+          fireEvent.keyDown(slider, { key: "ArrowRight" });
+        });
+      }
+      expect(onChange).toHaveBeenCalled();
+      expect(onValueChange).toHaveBeenCalled();
+      expect(onChange.mock.calls.length).toBe(onValueChange.mock.calls.length);
+      expect(onChange.mock.lastCall).toEqual(onValueChange.mock.lastCall);
+    });
   });
 
   describe("styling and theming", () => {
@@ -207,7 +251,7 @@ describe("Slider", () => {
       const disabledMarker =
         slider?.getAttribute("aria-disabled") === "true" ||
         slider?.hasAttribute("data-disabled") ||
-        slider?.closest("[data-disabled]") != null;
+        Boolean(slider?.closest("[data-disabled]"));
       expect(disabledMarker).toBeTruthy();
     });
   });
@@ -254,4 +298,434 @@ describe("Slider", () => {
       expect(slider).toBeDefined();
     });
   });
+
+  describe("LC-25 jump motion", () => {
+    describe("jump math", () => {
+      it("snaps raw pointer values to step and clamps to range", () => {
+        expect(snapSliderValue(25.4, 0, 100, 1)).toBe(25);
+        expect(snapSliderValue(25.6, 0, 100, 1)).toBe(26);
+        expect(snapSliderValue(140, 0, 100, 1)).toBe(100);
+        expect(snapSliderValue(-10, 0, 100, 1)).toBe(0);
+        expect(snapSliderValue(0.34, 0, 1, 0.1)).toBe(0.3);
+      });
+
+      it("picks the closest thumb for a track press", () => {
+        expect(getClosestThumbIndex([50], 10)).toBe(0);
+        expect(getClosestThumbIndex([20, 80], 40)).toBe(0);
+        expect(getClosestThumbIndex([20, 80], 70)).toBe(1);
+      });
+
+      it("measures the visual pixel distance between two values", () => {
+        const context = { min: 0, max: 100, trackWidth: 400, thumbSize: 20 };
+        // visualX(p) = trackW·p/100 + baseX(p) ⇒ Δ = Δp/100 · (trackW − S/2)
+        expect(getJumpDelta(50, 25, context)).toBeCloseTo(97.5);
+        expect(getJumpDelta(25, 50, context)).toBeCloseTo(-97.5);
+        expect(getJumpDelta(50, 50, context)).toBe(0);
+      });
+
+      it("mirrors tamagui's quarter-width in-bounds thumb offset", () => {
+        // baseX = quarter − (quarter/50)·percent − size/2 (LTR horizontal)
+        expect(getThumbBaseX(0, 20)).toBe(-5);
+        expect(getThumbBaseX(50, 20)).toBe(-10);
+        expect(getThumbBaseX(100, 20)).toBe(-15);
+      });
+
+      it("resolves the RENDERED thumb size: circular renders the UNSHIFTED token", () => {
+        // The ThemeableStack `circular` variant renders width =
+        // tokens.size[props.size] (unshifted) and is applied after the thumb's
+        // own size variant (getSize shift -1), so it wins. Tamagui's internal
+        // x-offset uses the MEASURED (rendered) size — the replica must too.
+        const tokens = getTokens();
+        const token = tokens.size["$1.5" as keyof typeof tokens.size] as any;
+        const unshifted = getVariableValue(token) as number;
+        const shifted = getVariableValue(getSize(token, { shift: -1 })) as number;
+        expect(getSliderThumbRenderSize("$1.5", true)).toBe(unshifted);
+        expect(getSliderThumbRenderSize("$1.5", false)).toBe(shifted);
+        // With the repo config this is 24 vs 20 — the 4px conflation behind the
+        // sweep's 1-4pt settle pop and the +2.5pt non-target thumb shift:
+        // Δ(p) = 4·(1/4 + p/200) = 2.5pt at p = 75%.
+        expect(unshifted).toBe(24);
+        expect(shifted).toBe(20);
+        const wrongBase = getThumbBaseX(75, shifted);
+        const trueBase = getThumbBaseX(75, unshifted);
+        expect(wrongBase - trueBase).toBeCloseTo(2.5);
+      });
+
+      it("adjusts values with tamagui's snap/sort/min-steps semantics (a11y actions)", () => {
+        // increment/decrement step math used by onAccessibilityAction
+        expect(getNextSortedValues([50], snapSliderValue(50 + 1, 0, 100, 1), 0)).toEqual([51]);
+        expect(getNextSortedValues([100], snapSliderValue(100 + 1, 0, 100, 1), 0)).toEqual([100]);
+        expect(getNextSortedValues([0], snapSliderValue(0 - 1, 0, 100, 1), 0)).toEqual([0]);
+        // range: adjusting the min thumb past the max re-sorts (tamagui semantics)
+        expect(getNextSortedValues([75, 75], snapSliderValue(76, 0, 100, 1), 0)).toEqual([75, 76]);
+        // min-steps rejection mirrors tamagui updateValues
+        expect(hasMinStepsBetween([70, 75], 10)).toBe(false);
+        expect(hasMinStepsBetween([60, 75], 10)).toBe(true);
+      });
+    });
+
+    describe("spring settle analytics", () => {
+      it("computes a settle window from the spring physics that grows with jump size", () => {
+        const short = getJumpSettleMs(QUICK_SPRING, 50);
+        const long = getJumpSettleMs(QUICK_SPRING, 350);
+        expect(long).toBeGreaterThan(short);
+        expect(long).toBeLessThanOrEqual(2000);
+        // the fixed 550ms window provably released long jumps early
+        expect(long).toBeGreaterThan(NATIVE_JUMP_SETTLE_MS);
+      });
+
+      it("residual at the computed settle time is below the pop threshold", () => {
+        for (const delta of [30, 130, 350]) {
+          const settleMs = getJumpSettleMs(QUICK_SPRING, delta);
+          expect(Math.abs(getSpringResidualPx(QUICK_SPRING, delta, settleMs))).toBeLessThan(
+            JUMP_RELEASE_THRESHOLD_PX + 1e-6,
+          );
+        }
+      });
+
+      it("reproduces the sweep's pop: a ~127pt jump is still >1pt from base at 550ms", () => {
+        expect(
+          Math.abs(getSpringResidualPx(QUICK_SPRING, 127, NATIVE_JUMP_SETTLE_MS)),
+        ).toBeGreaterThan(1);
+      });
+
+      it("starts at the full delta and decays toward zero", () => {
+        expect(getSpringResidualPx(QUICK_SPRING, 100, 0)).toBe(100);
+        expect(Math.abs(getSpringResidualPx(QUICK_SPRING, 100, 300))).toBeLessThan(10);
+        expect(Math.abs(getSpringResidualPx(QUICK_SPRING, 100, 1500))).toBeLessThan(0.01);
+      });
+
+      it("covers timing configs, unknown tokens, and overdamped springs", () => {
+        expect(getJumpSettleMs({ type: "timing", duration: 300 }, 200)).toBe(350);
+        expect(getJumpSettleMs(undefined, 200)).toBe(NATIVE_JUMP_SETTLE_MS);
+        expect(getJumpSettleMs("ease-in 100ms", 200)).toBe(NATIVE_JUMP_SETTLE_MS);
+        expect(getSpringResidualPx({ type: "timing", duration: 100 }, 80, 50)).toBeCloseTo(40);
+        expect(getSpringResidualPx({ type: "timing", duration: 100 }, 80, 150)).toBe(0);
+        // `lazy` (damping 18, stiffness 50, mass 1) is overdamped (ζ≈1.27):
+        // monotone decay, settle below threshold at its own settle time
+        const lazy = { type: "spring", damping: 18, stiffness: 50 };
+        const settleMs = getJumpSettleMs(lazy, 200);
+        expect(Math.abs(getSpringResidualPx(lazy, 200, settleMs))).toBeLessThan(0.5);
+      });
+    });
+
+    describe("native FLIP lifecycle (hook)", () => {
+      const options = (overrides: Record<string, unknown> = {}) => ({
+        enabled: true,
+        min: 0,
+        max: 100,
+        step: 1,
+        transitionToken: "quick",
+        initialValues: [50],
+        getTrackWidth: () => 400,
+        thumbSize: 20,
+        ...overrides,
+      });
+
+      afterEach(() => {
+        vi.useRealTimers();
+      });
+
+      it("track press applies the FLIP delta instantly, glides next frame, then clears", () => {
+        vi.useFakeTimers();
+        const { result } = renderHook(() => useSliderJumpMotion(options() as any));
+
+        // mount: no transform residue, no armed token
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+
+        act(() => {
+          result.current.onTrackPress(25);
+        });
+        // phase "apply": layout snaps to 25, transform holds the old visual
+        // position (base + delta) with an instant per-property transition
+        const baseX = getThumbBaseX(25, 20); // -7.5
+        const delta = getJumpDelta(50, 25, {
+          min: 0,
+          max: 100,
+          trackWidth: 400,
+          thumbSize: 20,
+        }); // 97.5
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+          x: baseX + delta,
+        });
+
+        // next frame: phase "animate" — transform tweens back to base with the token
+        act(() => {
+          vi.advanceTimersByTime(16);
+        });
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: { x: "quick" },
+          x: baseX,
+        });
+
+        // the trailing internal sync with the jump target keeps the session alive
+        act(() => {
+          result.current.onInternalValueChange([25]);
+        });
+        expect(result.current.getThumbMotionProps(0).x).toBe(baseX);
+
+        // settle window elapses: override removed, back to instant transform
+        act(() => {
+          vi.advanceTimersByTime(NATIVE_JUMP_SETTLE_MS);
+        });
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+      });
+
+      it("drag sessions never arm the transform tween", () => {
+        const { result } = renderHook(() => useSliderJumpMotion(options() as any));
+        act(() => {
+          result.current.onDragStart();
+          result.current.onInternalValueChange([51]);
+          result.current.onInternalValueChange([55]);
+        });
+        expect(result.current.flip).toBeNull();
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+      });
+
+      it("demotes to a 1:1 drag when the pointer keeps moving after a track press", () => {
+        vi.useFakeTimers();
+        const { result } = renderHook(() => useSliderJumpMotion(options() as any));
+        act(() => {
+          result.current.onTrackPress(25);
+        });
+        expect(result.current.flip).not.toBeNull();
+        // trailing sync with the target keeps the session
+        act(() => {
+          result.current.onInternalValueChange([25]);
+        });
+        expect(result.current.flip).not.toBeNull();
+        // a diverging value = drag-after-press → session dies, transform instant
+        act(() => {
+          result.current.onInternalValueChange([31]);
+        });
+        expect(result.current.flip).toBeNull();
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+      });
+
+      it("grabbing the thumb mid-glide cancels the tween immediately", () => {
+        vi.useFakeTimers();
+        const { result } = renderHook(() => useSliderJumpMotion(options() as any));
+        act(() => {
+          result.current.onTrackPress(25);
+        });
+        act(() => {
+          vi.advanceTimersByTime(16); // phase "animate"
+        });
+        expect(result.current.getThumbMotionProps(0).transition).toEqual({ x: "quick" });
+        act(() => {
+          result.current.onDragStart();
+        });
+        expect(result.current.flip).toBeNull();
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+      });
+
+      it("skips no-op, unmeasured, disabled, and min-steps-rejected presses", () => {
+        // same value → no visual distance → no session
+        const { result: samePress } = renderHook(() => useSliderJumpMotion(options() as any));
+        act(() => samePress.current.onTrackPress(50));
+        expect(samePress.current.flip).toBeNull();
+
+        // track not measured yet → no session
+        const { result: unmeasured } = renderHook(() =>
+          useSliderJumpMotion(options({ getTrackWidth: () => 0 }) as any),
+        );
+        act(() => unmeasured.current.onTrackPress(25));
+        expect(unmeasured.current.flip).toBeNull();
+
+        // disabled (web / vertical / rtl) → inert, component owns transitions
+        const { result: disabled } = renderHook(() =>
+          useSliderJumpMotion(options({ enabled: false }) as any),
+        );
+        act(() => disabled.current.onTrackPress(25));
+        expect(disabled.current.flip).toBeNull();
+        expect(disabled.current.getThumbMotionProps(0)).toEqual({});
+
+        // tamagui rejects updates violating minStepsBetweenThumbs → no motion
+        const { result: minSteps } = renderHook(() =>
+          useSliderJumpMotion(
+            options({ initialValues: [20, 30], minStepsBetweenThumbs: 15 }) as any,
+          ),
+        );
+        act(() => minSteps.current.onTrackPress(26));
+        expect(minSteps.current.flip).toBeNull();
+      });
+
+      it("scopes the session strictly to the thumb whose value jumped", () => {
+        vi.useFakeTimers();
+        const { result } = renderHook(() =>
+          useSliderJumpMotion(options({ initialValues: [20, 80] }) as any),
+        );
+        act(() => {
+          result.current.onTrackPress(40);
+        });
+        const context = { min: 0, max: 100, trackWidth: 400, thumbSize: 20 };
+        expect(result.current.flip?.movedIndex).toBe(0);
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+          x: getThumbBaseX(40, 20) + getJumpDelta(20, 40, context),
+        });
+        // Non-target thumb: NO override at all, in either phase — it can
+        // neither shift when the session arms nor pop back at release (the
+        // sweep measured a +2.5pt session shift from the old base-x pin).
+        expect(result.current.getThumbMotionProps(1)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+        act(() => {
+          vi.advanceTimersByTime(16); // phase "animate"
+        });
+        expect(result.current.getThumbMotionProps(1)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+        expect(result.current.getThumbMotionProps(1).x).toBeUndefined();
+      });
+
+      it("holds the override past the fixed window until the spring has settled", () => {
+        vi.useFakeTimers();
+        const { result } = renderHook(() =>
+          useSliderJumpMotion(options({ resolveAnimationConfig: () => QUICK_SPRING }) as any),
+        );
+        act(() => {
+          result.current.onTrackPress(90); // 50 → 90, |delta| = 156px
+        });
+        act(() => {
+          vi.advanceTimersByTime(16); // promote to "animate" (spring starts)
+        });
+        const delta = getJumpDelta(50, 90, { min: 0, max: 100, trackWidth: 400, thumbSize: 20 });
+        const settleMs = getJumpSettleMs(QUICK_SPRING, delta);
+        expect(settleMs).toBeGreaterThan(NATIVE_JUMP_SETTLE_MS);
+        // at the OLD fixed release point the spring is still >0.25pt out —
+        // the override must still be armed (this was the visible pop)
+        act(() => {
+          vi.advanceTimersByTime(NATIVE_JUMP_SETTLE_MS);
+        });
+        expect(result.current.flip).not.toBeNull();
+        // at the analytic settle time the residual is sub-threshold: release
+        act(() => {
+          vi.advanceTimersByTime(settleMs - NATIVE_JUMP_SETTLE_MS);
+        });
+        expect(result.current.flip).toBeNull();
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+        });
+      });
+
+      it("re-anchors a re-tap mid-glide to the in-flight position (no teleport)", () => {
+        vi.useFakeTimers();
+        const { result } = renderHook(() =>
+          useSliderJumpMotion(options({ resolveAnimationConfig: () => QUICK_SPRING }) as any),
+        );
+        act(() => {
+          result.current.onTrackPress(25); // 50 → 25
+        });
+        act(() => {
+          vi.advanceTimersByTime(16); // spring starts
+        });
+        act(() => {
+          result.current.onInternalValueChange([25]);
+        });
+        act(() => {
+          vi.advanceTimersByTime(100); // mid-flight
+        });
+        act(() => {
+          result.current.onTrackPress(75); // re-tap while still gliding
+        });
+        const context = { min: 0, max: 100, trackWidth: 400, thumbSize: 20 };
+        const inFlightResidual = getSpringResidualPx(
+          QUICK_SPRING,
+          getJumpDelta(50, 25, context),
+          100,
+        );
+        expect(Math.abs(inFlightResidual)).toBeGreaterThan(1); // genuinely mid-flight
+        expect(result.current.flip?.phase).toBe("apply");
+        // the new session pins the thumb where it visually IS (old-session
+        // residual folded in), not where the old glide would have ended
+        expect(result.current.getThumbMotionProps(0)).toEqual({
+          transition: INSTANT_X_TRANSITION,
+          x: getThumbBaseX(75, 20) + getJumpDelta(25, 75, context) + inFlightResidual,
+        });
+      });
+    });
+
+    describe("native a11y (web guard)", () => {
+      it("web thumbs carry no native accessibility props and keep per-thumb aria labels", () => {
+        const result = renderWithProviders(<Slider label="Guard" name="guard" value={[25, 75]} />);
+        const thumbs = Array.from(result.container.querySelectorAll('[role="slider"]'));
+        expect(thumbs.length).toBe(2);
+        for (const thumb of thumbs) {
+          // native-only props must never leak into the web DOM (byte-identical)
+          expect(thumb.hasAttribute("accessibilitylabel")).toBe(false);
+          expect(thumb.hasAttribute("accessibilityrole")).toBe(false);
+          expect(thumb.hasAttribute("accessibilityactions")).toBe(false);
+          expect(thumb.hasAttribute("accessibilityvalue")).toBe(false);
+        }
+        expect(thumbs[0].getAttribute("aria-label")).toContain("Minimum");
+        expect(thumbs[1].getAttribute("aria-label")).toContain("Maximum");
+      });
+    });
+
+    describe("web session (dom)", () => {
+      const getTrack = (container: HTMLElement, thumb: Element) =>
+        Array.from(container.querySelectorAll('[data-orientation="horizontal"]')).find(
+          (el) => el !== thumb && !el.contains(thumb),
+        ) as HTMLElement;
+
+      it("mounts without an armed transition or transform residue", () => {
+        const result = renderWithProviders(<Slider label="Mount" name="mount" value={[50]} />);
+        const thumb = result.container.querySelector('[role="slider"]') as HTMLElement;
+        expect(thumb.style.transition).toBe("");
+        expect(Array.from(thumb.classList)).toContain("_transition-none");
+      });
+
+      it("track click arms the left/transform tween then disarms after the jump window", async () => {
+        const result = renderWithProviders(
+          // min > 0 so the degenerate unmeasured-layout pointer value stays truthy
+          <Slider label="Jump" name="jump" value={[60]} min={10} max={110} />,
+        );
+        const thumb = result.container.querySelector('[role="slider"]') as HTMLElement;
+        const track = getTrack(result.container, thumb);
+        expect(track).toBeDefined();
+
+        await act(async () => {
+          fireEvent.mouseDown(track);
+        });
+        // jump happened and the session armed a real transition covering left
+        expect(thumb.getAttribute("aria-valuenow")).toBe("10");
+        expect(thumb.style.transition).toContain("left");
+        expect(thumb.style.transition).not.toContain("none");
+
+        // session disarms after the jump window so later layout cannot re-tween
+        await waitFor(
+          () => {
+            expect(thumb.style.transition).toBe("");
+          },
+          { timeout: 1500 },
+        );
+      });
+
+      it("thumb drag start keeps the transition off", async () => {
+        const result = renderWithProviders(<Slider label="Drag" name="drag" value={[40]} />);
+        const thumb = result.container.querySelector('[role="slider"]') as HTMLElement;
+        await act(async () => {
+          fireEvent.mouseDown(thumb);
+          fireEvent.mouseMove(thumb, { clientX: 50 });
+        });
+        expect(thumb.style.transition).not.toContain("left");
+        await act(async () => {
+          fireEvent.mouseUp(thumb);
+        });
+        expect(thumb.style.transition).not.toContain("left");
+      });
+    });
+  });
 });

package/src/fields/Slider/Slider.stories.tsx

@@ -246,3 +246,8 @@ export const Comparison: Story = {
     return <ComparisonExample />;
   },
 };
+
+/** Loading placeholder — the skeleton mirrors the track anatomy (LC-20 / DG-ST-02). */
+export const SkeletonState: Story = {
+  args: { label: "Volume", skeleton: true },
+};