react-panel-layout 0.6.1 → 0.7.1

package/src/modules/drawer/revealDrawerStateMachine.spec.ts

@@ -0,0 +1,558 @@
+/**
+ * @file Unit tests for revealDrawerStateMachine pure functions and reducer.
+ *
+ * Tests the state computation logic for reveal drawer animations,
+ * separated from React/DOM concerns.
+ */
+import {
+  computeProgressFromDisplacement,
+  computeSwipeEndTarget,
+  computePositionFromProgress,
+  computeTargetPosition,
+  shouldAnimate,
+  interpolatePosition,
+  createInitialState,
+  revealDrawerReducer,
+  revealDrawerActions,
+  type RevealDrawerConfig,
+} from "./revealDrawerStateMachine.js";
+import {
+  REVEAL_DRAWER_OPEN_DISTANCE_THRESHOLD,
+  REVEAL_DRAWER_DISMISS_RATIO,
+  REVEAL_DRAWER_CLOSED_OFFSET_PERCENT,
+} from "./revealDrawerConstants.js";
+
+describe("computeProgressFromDisplacement", () => {
+  const drawerSize = 300;
+
+  describe("opening direction", () => {
+    it("returns 0 when displacement is 0", () => {
+      expect(computeProgressFromDisplacement(0, drawerSize, "opening")).toBe(0);
+    });
+
+    it("returns 1 when displacement equals drawer size", () => {
+      expect(computeProgressFromDisplacement(300, drawerSize, "opening")).toBe(1);
+    });
+
+    it("returns correct ratio for partial displacement", () => {
+      expect(computeProgressFromDisplacement(150, drawerSize, "opening")).toBeCloseTo(0.5);
+    });
+
+    it("clamps at 1 for displacement exceeding drawer size", () => {
+      expect(computeProgressFromDisplacement(400, drawerSize, "opening")).toBe(1);
+    });
+  });
+
+  describe("closing direction", () => {
+    it("returns 1 when displacement is 0 (fully open)", () => {
+      expect(computeProgressFromDisplacement(0, drawerSize, "closing")).toBe(1);
+    });
+
+    it("returns 0 when displacement equals drawer size (fully closed)", () => {
+      expect(computeProgressFromDisplacement(300, drawerSize, "closing")).toBe(0);
+    });
+
+    it("returns correct ratio for partial displacement", () => {
+      expect(computeProgressFromDisplacement(150, drawerSize, "closing")).toBeCloseTo(0.5);
+    });
+  });
+
+  describe("null direction", () => {
+    it("returns 0 regardless of displacement", () => {
+      expect(computeProgressFromDisplacement(100, drawerSize, null)).toBe(0);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns 0 when drawer size is 0", () => {
+      expect(computeProgressFromDisplacement(100, 0, "opening")).toBe(0);
+    });
+
+    it("returns 0 for negative drawer size", () => {
+      expect(computeProgressFromDisplacement(100, -100, "opening")).toBe(0);
+    });
+  });
+});
+
+describe("computeSwipeEndTarget", () => {
+  const drawerSize = 300;
+
+  describe("opening direction", () => {
+    it("returns true when displacement >= 100px threshold", () => {
+      expect(computeSwipeEndTarget(100, drawerSize, "opening")).toBe(true);
+      expect(computeSwipeEndTarget(150, drawerSize, "opening")).toBe(true);
+    });
+
+    it("returns false when displacement < 100px threshold", () => {
+      expect(computeSwipeEndTarget(99, drawerSize, "opening")).toBe(false);
+      expect(computeSwipeEndTarget(50, drawerSize, "opening")).toBe(false);
+    });
+
+    it("uses REVEAL_DRAWER_OPEN_DISTANCE_THRESHOLD constant", () => {
+      expect(computeSwipeEndTarget(REVEAL_DRAWER_OPEN_DISTANCE_THRESHOLD, drawerSize, "opening")).toBe(true);
+      expect(computeSwipeEndTarget(REVEAL_DRAWER_OPEN_DISTANCE_THRESHOLD - 1, drawerSize, "opening")).toBe(false);
+    });
+  });
+
+  describe("closing direction", () => {
+    it("returns true (stays open) when ratio < 30% dismiss threshold", () => {
+      // 30% of 300 = 90
+      expect(computeSwipeEndTarget(89, drawerSize, "closing")).toBe(true);
+      expect(computeSwipeEndTarget(45, drawerSize, "closing")).toBe(true);
+    });
+
+    it("returns false (closes) when ratio >= 30% dismiss threshold", () => {
+      // 30% of 300 = 90
+      expect(computeSwipeEndTarget(90, drawerSize, "closing")).toBe(false);
+      expect(computeSwipeEndTarget(150, drawerSize, "closing")).toBe(false);
+    });
+
+    it("uses REVEAL_DRAWER_DISMISS_RATIO constant", () => {
+      const threshold = drawerSize * REVEAL_DRAWER_DISMISS_RATIO;
+      expect(computeSwipeEndTarget(threshold - 1, drawerSize, "closing")).toBe(true);
+      expect(computeSwipeEndTarget(threshold, drawerSize, "closing")).toBe(false);
+    });
+  });
+
+  describe("null direction", () => {
+    it("returns false", () => {
+      expect(computeSwipeEndTarget(100, drawerSize, null)).toBe(false);
+    });
+  });
+});
+
+describe("computePositionFromProgress", () => {
+  const config: RevealDrawerConfig = { placement: "left", drawerSize: 300 };
+
+  describe("left placement", () => {
+    it("returns closed position when progress is 0", () => {
+      const pos = computePositionFromProgress(0, config);
+      expect(pos.drawerPx).toBe(-90); // -30% of 300
+      expect(pos.contentPx).toBeCloseTo(0);
+    });
+
+    it("returns open position when progress is 1", () => {
+      const pos = computePositionFromProgress(1, config);
+      expect(pos.drawerPx).toBeCloseTo(0);
+      expect(pos.contentPx).toBe(300);
+    });
+
+    it("returns interpolated position for partial progress", () => {
+      const pos = computePositionFromProgress(0.5, config);
+      expect(pos.drawerPx).toBe(-45); // -15% of 300
+      expect(pos.contentPx).toBe(150);
+    });
+  });
+
+  describe("right placement", () => {
+    const rightConfig: RevealDrawerConfig = { placement: "right", drawerSize: 300 };
+
+    it("returns closed position when progress is 0", () => {
+      const pos = computePositionFromProgress(0, rightConfig);
+      expect(pos.drawerPx).toBe(90); // +30% of 300
+      expect(pos.contentPx).toBeCloseTo(0);
+    });
+
+    it("returns open position when progress is 1", () => {
+      const pos = computePositionFromProgress(1, rightConfig);
+      expect(pos.drawerPx).toBeCloseTo(0);
+      expect(pos.contentPx).toBe(-300);
+    });
+  });
+
+  describe("top placement", () => {
+    const topConfig: RevealDrawerConfig = { placement: "top", drawerSize: 200 };
+
+    it("returns closed position when progress is 0", () => {
+      const pos = computePositionFromProgress(0, topConfig);
+      expect(pos.drawerPx).toBe(-60); // -30% of 200
+      expect(pos.contentPx).toBeCloseTo(0);
+    });
+
+    it("returns open position when progress is 1", () => {
+      const pos = computePositionFromProgress(1, topConfig);
+      expect(pos.drawerPx).toBeCloseTo(0);
+      expect(pos.contentPx).toBe(200);
+    });
+  });
+
+  describe("bottom placement", () => {
+    const bottomConfig: RevealDrawerConfig = { placement: "bottom", drawerSize: 200 };
+
+    it("returns closed position when progress is 0", () => {
+      const pos = computePositionFromProgress(0, bottomConfig);
+      expect(pos.drawerPx).toBe(60); // +30% of 200
+      expect(pos.contentPx).toBeCloseTo(0);
+    });
+
+    it("returns open position when progress is 1", () => {
+      const pos = computePositionFromProgress(1, bottomConfig);
+      expect(pos.drawerPx).toBeCloseTo(0);
+      expect(pos.contentPx).toBe(-200);
+    });
+  });
+
+  it("uses REVEAL_DRAWER_CLOSED_OFFSET_PERCENT constant", () => {
+    const pos = computePositionFromProgress(0, config);
+    const expectedOffset = config.drawerSize * (REVEAL_DRAWER_CLOSED_OFFSET_PERCENT / 100);
+    expect(Math.abs(pos.drawerPx)).toBe(expectedOffset);
+  });
+});
+
+describe("computeTargetPosition", () => {
+  const config: RevealDrawerConfig = { placement: "left", drawerSize: 300 };
+
+  it("returns open position when isOpen is true", () => {
+    const pos = computeTargetPosition(true, config);
+    expect(pos.drawerPx).toBeCloseTo(0);
+    expect(pos.contentPx).toBe(300);
+  });
+
+  it("returns closed position when isOpen is false", () => {
+    const pos = computeTargetPosition(false, config);
+    expect(pos.drawerPx).toBe(-90);
+    expect(pos.contentPx).toBeCloseTo(0);
+  });
+});
+
+describe("shouldAnimate", () => {
+  it("returns true when positions differ by more than snap threshold", () => {
+    const from = { drawerPx: 0, contentPx: 0 };
+    const to = { drawerPx: 0, contentPx: 100 };
+    expect(shouldAnimate(from, to)).toBe(true);
+  });
+
+  it("returns false when positions differ by snap threshold or less", () => {
+    const from = { drawerPx: 0, contentPx: 100 };
+    const to = { drawerPx: 0, contentPx: 100.5 };
+    expect(shouldAnimate(from, to)).toBe(false);
+  });
+
+  it("returns false when positions are identical", () => {
+    const from = { drawerPx: -90, contentPx: 0 };
+    const to = { drawerPx: -90, contentPx: 0 };
+    expect(shouldAnimate(from, to)).toBe(false);
+  });
+});
+
+describe("interpolatePosition", () => {
+  const from = { drawerPx: -90, contentPx: 0 };
+  const to = { drawerPx: 0, contentPx: 300 };
+
+  it("returns from position when progress is 0", () => {
+    const pos = interpolatePosition(from, to, 0);
+    expect(pos.drawerPx).toBe(-90);
+    expect(pos.contentPx).toBe(0);
+  });
+
+  it("returns to position when progress is 1", () => {
+    const pos = interpolatePosition(from, to, 1);
+    expect(pos.drawerPx).toBe(0);
+    expect(pos.contentPx).toBe(300);
+  });
+
+  it("returns interpolated position for partial progress", () => {
+    const pos = interpolatePosition(from, to, 0.5);
+    expect(pos.drawerPx).toBe(-45);
+    expect(pos.contentPx).toBe(150);
+  });
+});
+
+describe("createInitialState", () => {
+  const config: RevealDrawerConfig = { placement: "left", drawerSize: 300 };
+
+  it("creates closed state when isOpen is false", () => {
+    const state = createInitialState(false, config);
+    expect(state.phase).toBe("closed");
+    expect(state.targetOpen).toBe(false);
+    expect(state.position.drawerPx).toBe(-90);
+    expect(state.position.contentPx).toBe(0);
+    expect(state.isOperating).toBe(false);
+    expect(state.swipeDirection).toBeNull();
+    expect(state.animation).toBeNull();
+  });
+
+  it("creates open state when isOpen is true", () => {
+    const state = createInitialState(true, config);
+    expect(state.phase).toBe("open");
+    expect(state.targetOpen).toBe(true);
+    expect(state.position.drawerPx).toBeCloseTo(0);
+    expect(state.position.contentPx).toBe(300);
+    expect(state.isOperating).toBe(false);
+    expect(state.swipeDirection).toBeNull();
+    expect(state.animation).toBeNull();
+  });
+});
+
+describe("revealDrawerReducer", () => {
+  const config: RevealDrawerConfig = { placement: "left", drawerSize: 300 };
+
+  describe("swipe flow: START -> UPDATE -> END", () => {
+    it("handles opening swipe that crosses threshold", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+
+      // Start swipe
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("opening"), config);
+      expect(state.isOperating).toBe(true);
+      expect(state.swipeDirection).toBe("opening");
+
+      // Update with displacement
+      state = revealDrawerReducer(state, revealDrawerActions.swipeUpdate(150), config);
+      expect(state.displacement).toBe(150);
+      expect(state.position.contentPx).toBeCloseTo(150);
+
+      // End swipe - should animate to open
+      state = revealDrawerReducer(state, revealDrawerActions.swipeEnd(), config);
+      expect(state.isOperating).toBe(false);
+      expect(state.targetOpen).toBe(true);
+      expect(state.phase).toBe("opening");
+      expect(state.animation).not.toBeNull();
+      expect(state.animation?.type).toBe("opening");
+    });
+
+    it("handles opening swipe that does not cross threshold", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("opening"), config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeUpdate(50), config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeEnd(), config);
+
+      expect(state.targetOpen).toBe(false);
+      expect(state.phase).toBe("closing");
+    });
+
+    it("handles closing swipe that crosses dismiss threshold", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(true, config);
+
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("closing"), config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeUpdate(100), config); // 33%
+      state = revealDrawerReducer(state, revealDrawerActions.swipeEnd(), config);
+
+      expect(state.targetOpen).toBe(false);
+      expect(state.phase).toBe("closing");
+    });
+
+    it("handles closing swipe that does not cross dismiss threshold", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(true, config);
+
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("closing"), config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeUpdate(50), config); // 16.6%
+      state = revealDrawerReducer(state, revealDrawerActions.swipeEnd(), config);
+
+      expect(state.targetOpen).toBe(true);
+      expect(state.phase).toBe("opening");
+    });
+  });
+
+  describe("animation flow: FRAME -> COMPLETE", () => {
+    it("interpolates position during animation frame", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+
+      // Trigger button open to start animation
+      state = revealDrawerReducer(state, revealDrawerActions.buttonOpen(), config);
+      expect(state.animation).not.toBeNull();
+
+      // Animation frame at 50%
+      state = revealDrawerReducer(state, revealDrawerActions.animationFrame(0.5), config);
+      expect(state.position.contentPx).toBeCloseTo(150);
+
+      // Animation complete
+      state = revealDrawerReducer(state, revealDrawerActions.animationComplete(), config);
+      expect(state.phase).toBe("open");
+      expect(state.animation).toBeNull();
+      expect(state.position.contentPx).toBe(300);
+    });
+  });
+
+  describe("button operations", () => {
+    it("buttonOpen starts animation when closed", () => {
+      const state = createInitialState(false, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.buttonOpen(), config);
+
+      expect(newState.phase).toBe("opening");
+      expect(newState.targetOpen).toBe(true);
+      expect(newState.animation).not.toBeNull();
+    });
+
+    it("buttonOpen is no-op when already open", () => {
+      const state = createInitialState(true, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.buttonOpen(), config);
+
+      expect(newState).toBe(state);
+    });
+
+    it("buttonOpen is no-op when already opening", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+      state = revealDrawerReducer(state, revealDrawerActions.buttonOpen(), config);
+      expect(state.phase).toBe("opening");
+
+      const newState = revealDrawerReducer(state, revealDrawerActions.buttonOpen(), config);
+      expect(newState).toBe(state);
+    });
+
+    it("buttonClose starts animation when open", () => {
+      const state = createInitialState(true, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.buttonClose(), config);
+
+      expect(newState.phase).toBe("closing");
+      expect(newState.targetOpen).toBe(false);
+      expect(newState.animation).not.toBeNull();
+    });
+
+    it("buttonClose is no-op when already closed", () => {
+      const state = createInitialState(false, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.buttonClose(), config);
+
+      expect(newState).toBe(state);
+    });
+
+    it("button operations are ignored during swipe", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("opening"), config);
+
+      const newState = revealDrawerReducer(state, revealDrawerActions.buttonOpen(), config);
+      expect(newState).toBe(state);
+    });
+  });
+
+  describe("syncOpenState", () => {
+    it("starts animation when state differs from target", () => {
+      const state = createInitialState(false, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.syncOpenState(true), config);
+
+      expect(newState.phase).toBe("opening");
+      expect(newState.targetOpen).toBe(true);
+      expect(newState.animation).not.toBeNull();
+    });
+
+    it("is no-op when already at target state", () => {
+      const state = createInitialState(true, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.syncOpenState(true), config);
+
+      expect(newState).toBe(state);
+    });
+
+    it("updates targetOpen during swipe but does not start animation", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("opening"), config);
+
+      const newState = revealDrawerReducer(state, revealDrawerActions.syncOpenState(true), config);
+      expect(newState.targetOpen).toBe(true);
+      expect(newState.animation).toBeNull();
+      expect(newState.isOperating).toBe(true);
+    });
+  });
+
+  describe("initialize", () => {
+    it("resets state to initial values", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("opening"), config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeUpdate(150), config);
+
+      const newState = revealDrawerReducer(state, revealDrawerActions.initialize(true), config);
+      expect(newState.phase).toBe("open");
+      expect(newState.isOperating).toBe(false);
+      expect(newState.displacement).toBe(0);
+      expect(newState.position.contentPx).toBe(300);
+    });
+  });
+
+  describe("placement variations", () => {
+    it.each([
+      ["left", 1],
+      ["right", -1],
+      ["top", 1],
+      ["bottom", -1],
+    ] as const)("%s placement has correct sign", (placement, expectedSign) => {
+      const placementConfig: RevealDrawerConfig = { placement, drawerSize: 300 };
+      const state = createInitialState(true, placementConfig);
+
+      // Content should move in the expected direction when open
+      expect(Math.sign(state.position.contentPx)).toBe(expectedSign);
+    });
+
+    it("horizontal placements use X axis", () => {
+      const leftConfig: RevealDrawerConfig = { placement: "left", drawerSize: 300 };
+      const rightConfig: RevealDrawerConfig = { placement: "right", drawerSize: 300 };
+
+      const leftState = createInitialState(true, leftConfig);
+      const rightState = createInitialState(true, rightConfig);
+
+      // Both should have non-zero content offset (just different directions)
+      expect(Math.abs(leftState.position.contentPx)).toBe(300);
+      expect(Math.abs(rightState.position.contentPx)).toBe(300);
+    });
+
+    it("vertical placements use Y axis", () => {
+      const topConfig: RevealDrawerConfig = { placement: "top", drawerSize: 200 };
+      const bottomConfig: RevealDrawerConfig = { placement: "bottom", drawerSize: 200 };
+
+      const topState = createInitialState(true, topConfig);
+      const bottomState = createInitialState(true, bottomConfig);
+
+      expect(Math.abs(topState.position.contentPx)).toBe(200);
+      expect(Math.abs(bottomState.position.contentPx)).toBe(200);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("swipeUpdate is no-op when not operating", () => {
+      const state = createInitialState(false, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.swipeUpdate(100), config);
+      expect(newState).toBe(state);
+    });
+
+    it("swipeEnd is no-op when not operating", () => {
+      const state = createInitialState(false, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.swipeEnd(), config);
+      expect(newState).toBe(state);
+    });
+
+    it("animationFrame is no-op when no animation", () => {
+      const state = createInitialState(false, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.animationFrame(0.5), config);
+      expect(newState).toBe(state);
+    });
+
+    it("animationComplete is no-op when no animation", () => {
+      const state = createInitialState(false, config);
+      const newState = revealDrawerReducer(state, revealDrawerActions.animationComplete(), config);
+      expect(newState).toBe(state);
+    });
+
+    it("swipeStart cancels running animation", () => {
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+      state = revealDrawerReducer(state, revealDrawerActions.buttonOpen(), config);
+      expect(state.animation).not.toBeNull();
+
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("closing"), config);
+      expect(state.animation).toBeNull();
+      expect(state.isOperating).toBe(true);
+    });
+  });
+
+  describe("snap behavior", () => {
+    it("snaps directly when positions are close enough", () => {
+      // Create a state very close to closed position
+      // eslint-disable-next-line no-restricted-syntax -- state machine testing requires reassignment
+      let state = createInitialState(false, config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeStart("opening"), config);
+      state = revealDrawerReducer(state, revealDrawerActions.swipeUpdate(0.5), config); // Tiny displacement
+      state = revealDrawerReducer(state, revealDrawerActions.swipeEnd(), config);
+
+      // Should snap directly to closed without animation
+      expect(state.phase).toBe("closed");
+      expect(state.animation).toBeNull();
+    });
+  });
+});