react-panel-layout 0.5.1 → 0.6.0

package/src/modules/stack/useStackSwipeInput.ts

@@ -0,0 +1,139 @@
+/**
+ * @file Hook for binding edge swipe input to Stack navigation.
+ *
+ * This hook connects edge swipe gesture detection to Stack's navigation API,
+ * enabling iOS-style "swipe to go back" navigation.
+ */
+import * as React from "react";
+import { useEdgeSwipeInput } from "../../hooks/gesture/useEdgeSwipeInput.js";
+import { useNativeGestureGuard } from "../../hooks/gesture/useNativeGestureGuard.js";
+import { mergeGestureContainerProps } from "../../hooks/gesture/utils.js";
+import { IDLE_SWIPE_INPUT_STATE } from "../../hooks/gesture/types.js";
+import type { SwipeInputState } from "../../hooks/gesture/types.js";
+import type { UseStackSwipeInputOptions, UseStackSwipeInputResult } from "./types.js";
+
+/**
+ * Hook for binding edge swipe input to Stack navigation.
+ *
+ * Detects swipe gestures from the specified edge and triggers navigation:
+ * - Left edge swipe → go(-1) (go back)
+ * - Right edge swipe → reveals parent or custom action
+ *
+ * During a swipe, provides progress for animation.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const navigation = useStackNavigation({ panels, displayMode: 'overlay' });
+ * const { isEdgeSwiping, progress, containerProps } = useStackSwipeInput({
+ *   containerRef,
+ *   navigation,
+ * });
+ *
+ * return (
+ *   <div ref={containerRef} {...containerProps}>
+ *     <navigation.Outlet />
+ *   </div>
+ * );
+ * ```
+ */
+export function useStackSwipeInput(options: UseStackSwipeInputOptions): UseStackSwipeInputResult {
+  const {
+    containerRef,
+    navigation,
+    edge = "left",
+    edgeWidth = 20,
+    enabled = true,
+  } = options;
+
+  // Track swipe state for progress calculation
+  const [swipeState, setSwipeState] = React.useState<SwipeInputState | null>(null);
+
+  // Handle swipe completion - navigate back
+  const handleSwipeEnd = React.useCallback(
+    (state: SwipeInputState) => {
+      setSwipeState(null);
+
+      // Left edge swipe going right = go back
+      if (edge === "left" && state.direction === 1) {
+        if (navigation.canGo(-1)) {
+          navigation.go(-1);
+        }
+      }
+      // Right edge swipe going left = custom action (optional)
+      // Could be used for forward navigation if the app supports it
+    },
+    [edge, navigation],
+  );
+
+  // Use edge swipe detection
+  const { isEdgeGesture, state: inputState, containerProps: swipeProps } = useEdgeSwipeInput({
+    containerRef,
+    edge,
+    edgeWidth,
+    enabled: enabled && navigation.canGo(-1), // Only enable if can go back
+    onSwipeEnd: handleSwipeEnd,
+  });
+
+  // Update swipe state for progress tracking
+  React.useEffect(() => {
+    if (isEdgeGesture && (inputState.phase === "swiping" || inputState.phase === "tracking")) {
+      setSwipeState(inputState);
+    } else if (inputState.phase === "idle") {
+      setSwipeState(null);
+    }
+  }, [isEdgeGesture, inputState]);
+
+  // Use native gesture guard during swipe
+  const { containerProps: guardProps } = useNativeGestureGuard({
+    containerRef,
+    active: isEdgeGesture,
+    preventEdgeBack: true,
+    preventOverscroll: true,
+    edgeWidth,
+  });
+
+  // Calculate swipe progress (0-1)
+  const progress = React.useMemo(() => {
+    if (!swipeState || !containerRef.current) {
+      return 0;
+    }
+
+    const containerWidth = containerRef.current.clientWidth;
+    if (containerWidth === 0) {
+      return 0;
+    }
+
+    // Use X displacement for horizontal swipe
+    const displacement = swipeState.displacement.x;
+
+    // Only count rightward movement for left edge swipe
+    if (edge === "left" && displacement <= 0) {
+      return 0;
+    }
+
+    // Only count leftward movement for right edge swipe
+    if (edge === "right" && displacement >= 0) {
+      return 0;
+    }
+
+    const absDisplacement = Math.abs(displacement);
+    return Math.min(absDisplacement / containerWidth, 1);
+  }, [swipeState, containerRef, edge]);
+
+  // Merge container props
+  const containerProps = React.useMemo(
+    () => mergeGestureContainerProps(swipeProps, guardProps),
+    [swipeProps, guardProps],
+  );
+
+  // Effective input state: only return actual state if it's an edge gesture
+  const effectiveInputState: SwipeInputState = isEdgeGesture ? inputState : IDLE_SWIPE_INPUT_STATE;
+
+  return {
+    isEdgeSwiping: isEdgeGesture,
+    progress,
+    inputState: effectiveInputState,
+    containerProps,
+  };
+}

package/src/modules/window/useDrawerState.ts

@@ -0,0 +1,81 @@
+/**
+ * @file Hook for managing drawer state (controlled/uncontrolled)
+ */
+import * as React from "react";
+import {
+  type TransitionMode,
+  type TransitionOptions,
+  runTransition,
+} from "../../hooks/useTransitionState";
+import type { LayerDefinition } from "../../types";
+
+const parseDuration = (value: string | undefined): number => {
+  if (!value) {return 300;}
+  const match = value.match(/(\d+)/);
+  return match ? parseInt(match[1], 10) : 300;
+};
+
+export const useDrawerState = (layers: LayerDefinition[]) => {
+  const [drawerStates, setDrawerStates] = React.useState<Record<string, boolean>>(() => {
+    const initial: Record<string, boolean> = {};
+    layers.forEach((layer) => {
+      if (layer.drawer) {
+        initial[layer.id] = layer.drawer.defaultOpen ?? false;
+      }
+    });
+    return initial;
+  });
+
+  const layerMap = React.useMemo(() => {
+    const map = new Map<string, LayerDefinition>();
+    layers.forEach((layer) => map.set(layer.id, layer));
+    return map;
+  }, [layers]);
+
+  const updateState = React.useCallback(
+    async (layerId: string, isOpen: boolean, options?: TransitionOptions) => {
+      const layer = layerMap.get(layerId);
+      if (!layer?.drawer) {return;}
+
+      const mode: TransitionMode = options?.mode ?? layer.drawer.transitionMode ?? "css";
+      const duration = options?.duration ?? parseDuration(layer.drawer.transitionDuration);
+      const element = options?.element?.current;
+
+      const applyState = () => {
+        if (layer.drawer?.open === undefined) {
+          setDrawerStates((prev) => {
+            if (prev[layerId] === isOpen) {return prev;}
+            return { ...prev, [layerId]: isOpen };
+          });
+        }
+        layer.drawer?.onStateChange?.(isOpen);
+      };
+
+      await runTransition(applyState, mode, element, duration);
+    },
+    [layerMap],
+  );
+
+  const state = React.useCallback(
+    (layerId: string): boolean => {
+      const layer = layerMap.get(layerId);
+      if (layer?.drawer?.open !== undefined) {
+        return layer.drawer.open;
+      }
+      return drawerStates[layerId] ?? false;
+    },
+    [layerMap, drawerStates],
+  );
+
+  const open = React.useCallback(
+    (id: string, options?: TransitionOptions) => updateState(id, true, options),
+    [updateState],
+  );
+
+  const close = React.useCallback(
+    (id: string, options?: TransitionOptions) => updateState(id, false, options),
+    [updateState],
+  );
+
+  return { state, open, close };
+};

package/src/modules/window/useFloatingState.spec.ts

@@ -0,0 +1,252 @@
+/**
+ * @file Tests for useFloatingState hook
+ */
+import { renderHook, act } from "@testing-library/react";
+import { useFloatingState } from "./useFloatingState";
+import type { LayerDefinition, WindowPosition, WindowSize } from "../../types";
+
+/**
+ * Creates a tracked callback for testing.
+ * Tracks all calls and their arguments.
+ */
+const createTrackedCallback = <T,>() => {
+  const calls: T[] = [];
+  const fn = (arg: T) => {
+    calls.push(arg);
+  };
+  return { fn, calls };
+};
+
+describe("useFloatingState", () => {
+  const createLayer = (overrides: Partial<LayerDefinition> = {}): LayerDefinition => ({
+    id: "test-layer",
+    component: null,
+    floating: {
+      defaultPosition: { left: 100, top: 100 },
+      defaultSize: { width: 300, height: 200 },
+      draggable: true,
+    },
+    ...overrides,
+  });
+
+  describe("getPosition", () => {
+    it("should return defaultPosition for uncontrolled mode", () => {
+      const layers = [createLayer()];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      const position = result.current.getPosition("test-layer");
+
+      expect(position).toEqual({ left: 100, top: 100 });
+    });
+
+    it("should return controlled position when provided", () => {
+      const layers = [
+        createLayer({
+          floating: {
+            position: { left: 200, top: 200 },
+            defaultPosition: { left: 100, top: 100 },
+            defaultSize: { width: 300, height: 200 },
+          },
+        }),
+      ];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      const position = result.current.getPosition("test-layer");
+
+      expect(position).toEqual({ left: 200, top: 200 });
+    });
+
+    it("should return default position for unknown layer", () => {
+      const layers = [createLayer()];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      const position = result.current.getPosition("unknown-layer");
+
+      expect(position).toEqual({ left: 0, top: 0 });
+    });
+  });
+
+  describe("getSize", () => {
+    it("should return defaultSize for uncontrolled mode", () => {
+      const layers = [createLayer()];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      const size = result.current.getSize("test-layer");
+
+      expect(size).toEqual({ width: 300, height: 200 });
+    });
+
+    it("should return controlled size when provided", () => {
+      const layers = [
+        createLayer({
+          floating: {
+            size: { width: 500, height: 400 },
+            defaultPosition: { left: 100, top: 100 },
+            defaultSize: { width: 300, height: 200 },
+          },
+        }),
+      ];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      const size = result.current.getSize("test-layer");
+
+      expect(size).toEqual({ width: 500, height: 400 });
+    });
+  });
+
+  describe("getZIndex", () => {
+    it("should return zIndex from floating config", () => {
+      const layers = [
+        createLayer({
+          floating: {
+            defaultPosition: { left: 100, top: 100 },
+            defaultSize: { width: 300, height: 200 },
+            zIndex: 10,
+          },
+        }),
+      ];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      const zIndex = result.current.getZIndex("test-layer");
+
+      expect(zIndex).toBe(10);
+    });
+
+    it("should return undefined when zIndex not set", () => {
+      const layers = [createLayer()];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      const zIndex = result.current.getZIndex("test-layer");
+
+      expect(zIndex).toBeUndefined();
+    });
+  });
+
+  describe("updatePosition", () => {
+    it("should update internal state in uncontrolled mode", () => {
+      const layers = [createLayer()];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      act(() => {
+        result.current.updatePosition("test-layer", { left: 150, top: 150 });
+      });
+
+      const position = result.current.getPosition("test-layer");
+      expect(position).toEqual({ left: 150, top: 150 });
+    });
+
+    it("should call onMove callback", () => {
+      const tracked = createTrackedCallback<WindowPosition>();
+      const layers = [
+        createLayer({
+          floating: {
+            defaultPosition: { left: 100, top: 100 },
+            defaultSize: { width: 300, height: 200 },
+            onMove: tracked.fn,
+          },
+        }),
+      ];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      act(() => {
+        result.current.updatePosition("test-layer", { left: 150, top: 150 });
+      });
+
+      expect(tracked.calls).toEqual([{ left: 150, top: 150 }]);
+    });
+
+    it("should not update internal state in controlled mode", () => {
+      const tracked = createTrackedCallback<WindowPosition>();
+      const layers = [
+        createLayer({
+          floating: {
+            position: { left: 200, top: 200 },
+            defaultPosition: { left: 100, top: 100 },
+            defaultSize: { width: 300, height: 200 },
+            onMove: tracked.fn,
+          },
+        }),
+      ];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      act(() => {
+        result.current.updatePosition("test-layer", { left: 150, top: 150 });
+      });
+
+      // In controlled mode, position should still come from the prop
+      const position = result.current.getPosition("test-layer");
+      expect(position).toEqual({ left: 200, top: 200 });
+      // But callback should still be called
+      expect(tracked.calls).toEqual([{ left: 150, top: 150 }]);
+    });
+  });
+
+  describe("updateSize", () => {
+    it("should update internal state in uncontrolled mode", () => {
+      const layers = [createLayer()];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      act(() => {
+        result.current.updateSize("test-layer", { width: 400, height: 300 });
+      });
+
+      const size = result.current.getSize("test-layer");
+      expect(size).toEqual({ width: 400, height: 300 });
+    });
+
+    it("should call onResize callback", () => {
+      const tracked = createTrackedCallback<WindowSize>();
+      const layers = [
+        createLayer({
+          floating: {
+            defaultPosition: { left: 100, top: 100 },
+            defaultSize: { width: 300, height: 200 },
+            onResize: tracked.fn,
+          },
+        }),
+      ];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      act(() => {
+        result.current.updateSize("test-layer", { width: 400, height: 300 });
+      });
+
+      expect(tracked.calls).toEqual([{ width: 400, height: 300 }]);
+    });
+  });
+
+  describe("close", () => {
+    it("should call onClose callback", () => {
+      const closeTracker = { called: false };
+      const layers = [
+        createLayer({
+          floating: {
+            defaultPosition: { left: 100, top: 100 },
+            defaultSize: { width: 300, height: 200 },
+            onClose: () => {
+              closeTracker.called = true;
+            },
+          },
+        }),
+      ];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      act(() => {
+        result.current.close("test-layer");
+      });
+
+      expect(closeTracker.called).toBe(true);
+    });
+
+    it("should not throw when layer has no onClose callback", () => {
+      const layers = [createLayer()];
+      const { result } = renderHook(() => useFloatingState(layers));
+
+      expect(() => {
+        act(() => {
+          result.current.close("test-layer");
+        });
+      }).not.toThrow();
+    });
+  });
+});

package/src/modules/window/useFloatingState.ts

@@ -0,0 +1,141 @@
+/**
+ * @file Hook for managing floating window state (controlled/uncontrolled)
+ * Pattern based on useDrawerState.ts
+ */
+import * as React from "react";
+import type { LayerDefinition, WindowPosition, WindowSize } from "../../types";
+
+type FloatingState = {
+  position: WindowPosition;
+  size: WindowSize;
+};
+
+const DEFAULT_POSITION: WindowPosition = { left: 0, top: 0 };
+const DEFAULT_SIZE: WindowSize = { width: 400, height: 300 };
+
+export const useFloatingState = (layers: LayerDefinition[]) => {
+  const [floatingStates, setFloatingStates] = React.useState<Record<string, FloatingState>>(() => {
+    const initial: Record<string, FloatingState> = {};
+    layers.forEach((layer) => {
+      if (layer.floating) {
+        const floating = layer.floating;
+        initial[layer.id] = {
+          position: floating.defaultPosition ?? DEFAULT_POSITION,
+          size: floating.defaultSize ?? DEFAULT_SIZE,
+        };
+      }
+    });
+    return initial;
+  });
+
+  const layerMap = React.useMemo(() => {
+    const map = new Map<string, LayerDefinition>();
+    layers.forEach((layer) => map.set(layer.id, layer));
+    return map;
+  }, [layers]);
+
+  const getPosition = React.useCallback(
+    (layerId: string): WindowPosition => {
+      const layer = layerMap.get(layerId);
+      // Controlled mode: use position prop directly
+      if (layer?.floating?.position !== undefined) {
+        return layer.floating.position;
+      }
+      // Uncontrolled mode: use internal state
+      return floatingStates[layerId]?.position ?? DEFAULT_POSITION;
+    },
+    [layerMap, floatingStates],
+  );
+
+  const getSize = React.useCallback(
+    (layerId: string): WindowSize => {
+      const layer = layerMap.get(layerId);
+      // Controlled mode: use size prop directly
+      if (layer?.floating?.size !== undefined) {
+        return layer.floating.size;
+      }
+      // Uncontrolled mode: use internal state
+      return floatingStates[layerId]?.size ?? DEFAULT_SIZE;
+    },
+    [layerMap, floatingStates],
+  );
+
+  const getZIndex = React.useCallback(
+    (layerId: string): number | undefined => {
+      const layer = layerMap.get(layerId);
+      return layer?.floating?.zIndex;
+    },
+    [layerMap],
+  );
+
+  const updatePosition = React.useCallback(
+    (layerId: string, position: WindowPosition) => {
+      const layer = layerMap.get(layerId);
+      if (!layer?.floating) {
+        return;
+      }
+
+      // Update internal state only if uncontrolled
+      if (layer.floating.position === undefined) {
+        setFloatingStates((prev) => {
+          const currentState = prev[layerId];
+          if (!currentState) {
+            return prev;
+          }
+          return {
+            ...prev,
+            [layerId]: { ...currentState, position },
+          };
+        });
+      }
+
+      // Always call callback
+      layer.floating.onMove?.(position);
+    },
+    [layerMap],
+  );
+
+  const updateSize = React.useCallback(
+    (layerId: string, size: WindowSize) => {
+      const layer = layerMap.get(layerId);
+      if (!layer?.floating) {
+        return;
+      }
+
+      // Update internal state only if uncontrolled
+      if (layer.floating.size === undefined) {
+        setFloatingStates((prev) => {
+          const currentState = prev[layerId];
+          if (!currentState) {
+            return prev;
+          }
+          return {
+            ...prev,
+            [layerId]: { ...currentState, size },
+          };
+        });
+      }
+
+      // Always call callback
+      layer.floating.onResize?.(size);
+    },
+    [layerMap],
+  );
+
+  const close = React.useCallback(
+    (layerId: string) => {
+      const layer = layerMap.get(layerId);
+      layer?.floating?.onClose?.();
+    },
+    [layerMap],
+  );
+
+  return {
+    getPosition,
+    getSize,
+    getZIndex,
+    updatePosition,
+    updateSize,
+    close,
+  };
+};