react-panel-layout 0.5.2 → 0.6.0

package/src/modules/stack/types.ts

@@ -0,0 +1,226 @@
+/**
+ * @file Type definitions for the Stack navigation component system.
+ *
+ * Stack manages hierarchical navigation where panels stack as you drill down.
+ * Similar to iOS/iPadOS navigation controllers.
+ */
+import type * as React from "react";
+import type { SwipeInputState } from "../../hooks/gesture/types.js";
+
+/**
+ * Display mode for stack panels.
+ * - "overlay": Panels fully overlap (mobile style)
+ * - "slide": Panels slide in from edge
+ * - "stack": Panels stack with visual depth (tablet style)
+ */
+export type StackDisplayMode = "overlay" | "slide" | "stack";
+
+/**
+ * Transition mode for stack animations.
+ * - "css": Uses CSS transitions/animations
+ * - "none": No transitions (uses React.Activity for memory optimization)
+ */
+export type StackTransitionMode = "css" | "none";
+
+/**
+ * A panel in the stack.
+ */
+export type StackPanel<TId extends string = string> = {
+  /** Unique identifier for this panel */
+  id: TId;
+  /** Human-readable title for the panel (used in headers, back buttons) */
+  title?: string;
+  /** The content to render */
+  content: React.ReactNode;
+  /**
+   * Enable content caching to preserve React component state.
+   * When disabled (default), content is re-created on each render.
+   * @default false
+   */
+  cache?: boolean;
+};
+
+/**
+ * State of the stack navigation.
+ */
+export type StackNavigationState<TId extends string = string> = {
+  /** Stack of panel IDs representing the navigation hierarchy */
+  stack: ReadonlyArray<TId>;
+  /** Current depth in the stack (0-indexed) */
+  depth: number;
+  /** Whether a parent panel is being revealed (peeking) */
+  isRevealing: boolean;
+  /** Depth of the revealed parent, if any */
+  revealDepth: number | null;
+};
+
+/**
+ * Props returned by getPanelProps for panel elements.
+ */
+export type StackPanelProps = {
+  "data-stack-panel": string;
+  "data-depth": number;
+  "data-active": "true" | "false";
+  "aria-hidden": boolean;
+};
+
+/**
+ * Props returned by getBackButtonProps for back navigation.
+ */
+export type StackBackButtonProps = {
+  onClick: () => void;
+  disabled: boolean;
+  "aria-label": string;
+};
+
+/**
+ * Options for useStackNavigation hook.
+ */
+export type UseStackNavigationOptions<TId extends string = string> = {
+  /** Array of available panels */
+  panels: ReadonlyArray<StackPanel<TId>>;
+  /** Initial panel ID to display. @default first panel */
+  initialPanelId?: TId;
+  /** Display mode for panels */
+  displayMode: StackDisplayMode;
+  /** Transition mode for animations. @default "css" */
+  transitionMode?: StackTransitionMode;
+  /** Callback when panel changes */
+  onPanelChange?: (id: TId, depth: number) => void;
+};
+
+/**
+ * Result from useStackNavigation hook.
+ */
+export type UseStackNavigationResult<TId extends string = string> = {
+  /** Current navigation state */
+  state: StackNavigationState<TId>;
+
+  // Navigation operations
+
+  /**
+   * Push a new panel onto the stack.
+   * @param id - Panel ID to push
+   */
+  push: (id: TId) => void;
+
+  /**
+   * Navigate in a direction relative to current depth.
+   * @param direction - Number of steps: -1=back, -2=back2, etc.
+   */
+  go: (direction: number) => void;
+
+  /**
+   * Move to an absolute depth in the stack.
+   * @param depth - Target depth (0-indexed)
+   */
+  move: (depth: number) => void;
+
+  /**
+   * Replace the current panel with a new one.
+   * @param id - Panel ID to replace with
+   */
+  replace: (id: TId) => void;
+
+  // Parent reveal operations
+
+  /**
+   * Temporarily reveal a parent panel.
+   * @param depth - Depth to reveal to (defaults to depth-1)
+   */
+  revealParent: (depth?: number) => void;
+
+  /**
+   * Reveal the root panel.
+   */
+  revealRoot: () => void;
+
+  /**
+   * Dismiss the parent reveal and return to current panel.
+   */
+  dismissReveal: () => void;
+
+  // Props and state getters
+
+  /**
+   * Get props for a panel element.
+   * @param id - Panel ID
+   */
+  getPanelProps: (id: TId) => StackPanelProps;
+
+  /**
+   * Get props for a back button.
+   */
+  getBackButtonProps: () => StackBackButtonProps;
+
+  /**
+   * Check if navigation in a direction is possible.
+   * @param direction - Direction to check
+   */
+  canGo: (direction: number) => boolean;
+
+  /** Current panel ID (top of stack) */
+  currentPanelId: TId;
+
+  /** Previous panel ID (one step back), or null if at root */
+  previousPanelId: TId | null;
+
+  // Rendering
+
+  /** Outlet component that renders the stack content */
+  Outlet: React.FC;
+};
+
+/**
+ * Options for useStackSwipeInput hook.
+ */
+export type UseStackSwipeInputOptions = {
+  /** Reference to the swipe container element */
+  containerRef: React.RefObject<HTMLElement | null>;
+  /** Stack navigation result from useStackNavigation */
+  navigation: Pick<UseStackNavigationResult, "go" | "canGo" | "revealParent" | "dismissReveal" | "state">;
+  /** Edge to detect swipes from. @default "left" */
+  edge?: "left" | "right";
+  /** Width of the edge detection zone. @default 20 */
+  edgeWidth?: number;
+  /** Whether swipe input is enabled. @default true */
+  enabled?: boolean;
+};
+
+/**
+ * Result from useStackSwipeInput hook.
+ */
+export type UseStackSwipeInputResult = {
+  /** Whether currently swiping from edge */
+  isEdgeSwiping: boolean;
+  /** Swipe progress (0-1) for animation */
+  progress: number;
+  /** Full swipe input state for direct DOM manipulation */
+  inputState: SwipeInputState;
+  /** Props to spread on the container element */
+  containerProps: React.HTMLAttributes<HTMLElement> & {
+    style: React.CSSProperties;
+  };
+};
+
+/**
+ * Props for StackContent component.
+ */
+export type StackContentProps = {
+  /** Panel ID */
+  id: string;
+  /** Panel depth in the stack */
+  depth: number;
+  /** Whether this panel is currently active (top of stack) */
+  isActive: boolean;
+  /** Display mode */
+  displayMode: StackDisplayMode;
+  /** Transition mode */
+  transitionMode: StackTransitionMode;
+  /** Current navigation state */
+  navigationState: StackNavigationState;
+  /** Swipe progress for animation (0-1) */
+  swipeProgress?: number;
+  /** Content to render */
+  children: React.ReactNode;
+};

package/src/modules/stack/useStackAnimationState.spec.ts

@@ -0,0 +1,186 @@
+import { describe, it, expect } from "vitest";
+import { computeAnimatedPanels, type AnimatedPanel } from "./useStackAnimationState.js";
+
+describe("computeAnimatedPanels", () => {
+  describe("initial state", () => {
+    it("should mark all panels as active when there is no previous stack", () => {
+      const prevPanels: AnimatedPanel[] = [];
+      const prevStack: string[] = [];
+      const currentStack = ["root"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([{ id: "root", depth: 0, phase: "active" }]);
+    });
+
+    it("should handle multiple initial panels", () => {
+      const prevPanels: AnimatedPanel[] = [];
+      const prevStack: string[] = [];
+      const currentStack = ["root", "general"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "active" },
+      ]);
+    });
+  });
+
+  describe("push operation", () => {
+    it("should mark new panel as entering when pushed", () => {
+      const prevPanels: AnimatedPanel[] = [{ id: "root", depth: 0, phase: "active" }];
+      const prevStack = ["root"];
+      const currentStack = ["root", "general"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "entering" },
+      ]);
+    });
+
+    it("should mark deeply nested push as entering", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "active" },
+      ];
+      const prevStack = ["root", "general"];
+      const currentStack = ["root", "general", "about"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "active" },
+        { id: "about", depth: 2, phase: "entering" },
+      ]);
+    });
+  });
+
+  describe("pop operation", () => {
+    it("should mark popped panel as exiting", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "active" },
+      ];
+      const prevStack = ["root", "general"];
+      const currentStack = ["root"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "exiting" },
+      ]);
+    });
+
+    it("should handle multiple panels popped at once", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "active" },
+        { id: "about", depth: 2, phase: "active" },
+      ];
+      const prevStack = ["root", "general", "about"];
+      const currentStack = ["root"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "exiting" },
+        { id: "about", depth: 2, phase: "exiting" },
+      ]);
+    });
+
+    it("should preserve depth for exiting panels", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "active" },
+        { id: "about", depth: 2, phase: "active" },
+        { id: "name", depth: 3, phase: "active" },
+      ];
+      const prevStack = ["root", "general", "about", "name"];
+      const currentStack = ["root", "general"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toContainEqual({ id: "about", depth: 2, phase: "exiting" });
+      expect(result).toContainEqual({ id: "name", depth: 3, phase: "exiting" });
+    });
+  });
+
+  describe("exiting panel persistence", () => {
+    it("should keep already exiting panels", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "exiting" },
+      ];
+      const prevStack = ["root"];
+      const currentStack = ["root"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toContainEqual({ id: "general", depth: 1, phase: "exiting" });
+    });
+
+    it("should keep multiple exiting panels", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "exiting" },
+        { id: "about", depth: 2, phase: "exiting" },
+      ];
+      const prevStack = ["root"];
+      const currentStack = ["root"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toContainEqual({ id: "general", depth: 1, phase: "exiting" });
+      expect(result).toContainEqual({ id: "about", depth: 2, phase: "exiting" });
+    });
+  });
+
+  describe("entering panel transition", () => {
+    it("should keep entering phase on subsequent renders", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "entering" },
+      ];
+      const prevStack = ["root", "general"];
+      const currentStack = ["root", "general"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "entering" },
+      ]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle empty stacks", () => {
+      const prevPanels: AnimatedPanel[] = [];
+      const prevStack: string[] = [];
+      const currentStack: string[] = [];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual([]);
+    });
+
+    it("should handle no change in stack", () => {
+      const prevPanels: AnimatedPanel[] = [
+        { id: "root", depth: 0, phase: "active" },
+        { id: "general", depth: 1, phase: "active" },
+      ];
+      const prevStack = ["root", "general"];
+      const currentStack = ["root", "general"];
+
+      const result = computeAnimatedPanels(prevPanels, prevStack, currentStack);
+
+      expect(result).toEqual(prevPanels);
+    });
+  });
+});

package/src/modules/stack/useStackAnimationState.ts

@@ -0,0 +1,138 @@
+/**
+ * @file Hook for managing stack animation state.
+ *
+ * Tracks panel lifecycle: entering → active → exiting → removed
+ * Provides stable state for animations regardless of React render timing.
+ */
+import * as React from "react";
+
+export type PanelAnimationPhase = "entering" | "active" | "exiting";
+
+export type AnimatedPanel = {
+  id: string;
+  depth: number;
+  phase: PanelAnimationPhase;
+};
+
+export type UseStackAnimationStateOptions = {
+  /** Current stack from navigation */
+  stack: ReadonlyArray<string>;
+  /** Called when an exiting panel's animation completes */
+  onExitComplete?: (id: string) => void;
+};
+
+export type UseStackAnimationStateResult = {
+  /** All panels to render (active + exiting) */
+  panels: ReadonlyArray<AnimatedPanel>;
+  /** Mark a panel's enter animation as complete */
+  markEnterComplete: (id: string) => void;
+  /** Mark a panel's exit animation as complete */
+  markExitComplete: (id: string) => void;
+};
+
+/**
+ * Computes animated panels from current and previous stack.
+ * Pure function for easy testing.
+ */
+export function computeAnimatedPanels(
+  prevPanels: ReadonlyArray<AnimatedPanel>,
+  prevStack: ReadonlyArray<string>,
+  currentStack: ReadonlyArray<string>,
+): ReadonlyArray<AnimatedPanel> {
+  const result: AnimatedPanel[] = [];
+  const currentStackSet = new Set(currentStack);
+
+  // Add panels from current stack
+  for (let i = 0; i < currentStack.length; i++) {
+    const id = currentStack[i];
+    const wasInPrevStack = prevStack.includes(id);
+    const prevPanel = prevPanels.find((p) => p.id === id);
+
+    let phase: PanelAnimationPhase;
+    if (!wasInPrevStack && prevStack.length > 0) {
+      // New panel pushed onto stack
+      phase = "entering";
+    } else if (prevPanel?.phase === "entering") {
+      // Was entering, keep entering until animation completes
+      phase = "entering";
+    } else {
+      phase = "active";
+    }
+
+    result.push({ id, depth: i, phase });
+  }
+
+  // Add exiting panels (were in prev stack but not in current)
+  for (let i = 0; i < prevStack.length; i++) {
+    const id = prevStack[i];
+    if (!currentStackSet.has(id)) {
+      // This panel was popped
+      const prevPanel = prevPanels.find((p) => p.id === id);
+      // Keep depth from previous position for animation
+      const depth = prevPanel?.depth ?? i;
+      result.push({ id, depth, phase: "exiting" });
+    }
+  }
+
+  // Also keep any panels that were already exiting
+  for (const panel of prevPanels) {
+    if (panel.phase === "exiting" && !result.some((p) => p.id === panel.id)) {
+      result.push(panel);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Hook for managing stack animation state.
+ *
+ * Uses a ref-based approach to compute panels synchronously during render,
+ * avoiding the flash that would occur with useEffect.
+ */
+export function useStackAnimationState(
+  options: UseStackAnimationStateOptions,
+): UseStackAnimationStateResult {
+  const { stack, onExitComplete } = options;
+
+  // Use refs for synchronous computation during render
+  const prevStackRef = React.useRef<ReadonlyArray<string>>(stack);
+  const panelsRef = React.useRef<ReadonlyArray<AnimatedPanel>>(
+    stack.map((id, i) => ({ id, depth: i, phase: "active" as const })),
+  );
+
+  // Compute panels synchronously during render
+  const prevStack = prevStackRef.current;
+  const stackChanged =
+    prevStack.length !== stack.length || prevStack.some((id, i) => stack[i] !== id);
+
+  if (stackChanged) {
+    panelsRef.current = computeAnimatedPanels(panelsRef.current, prevStack, stack);
+    prevStackRef.current = stack;
+  }
+
+  // Force re-render when panels change (for animation completion callbacks)
+  const [, forceUpdate] = React.useReducer((x) => x + 1, 0);
+
+  const markEnterComplete = React.useCallback((id: string) => {
+    panelsRef.current = panelsRef.current.map((p) =>
+      p.id === id && p.phase === "entering" ? { ...p, phase: "active" } : p,
+    );
+    forceUpdate();
+  }, []);
+
+  const markExitComplete = React.useCallback(
+    (id: string) => {
+      panelsRef.current = panelsRef.current.filter((p) => p.id !== id);
+      onExitComplete?.(id);
+      forceUpdate();
+    },
+    [onExitComplete],
+  );
+
+  return {
+    panels: panelsRef.current,
+    markEnterComplete,
+    markExitComplete,
+  };
+}