react-panel-layout 0.5.2 → 0.6.1

package/src/modules/drawer/useDrawerSwipeInput.ts

@@ -0,0 +1,399 @@
+/**
+ * @file Hook for detecting swipe gestures to open/close a drawer.
+ *
+ * Combines:
+ * - Edge swipe detection for opening (Stack pattern)
+ * - Drag-to-close within drawer (Dialog pattern)
+ * - Native gesture guard for browser back prevention
+ */
+import * as React from "react";
+import { useEdgeSwipeInput } from "../../hooks/gesture/useEdgeSwipeInput.js";
+import { useNativeGestureGuard } from "../../hooks/gesture/useNativeGestureGuard.js";
+import { usePointerTracking } from "../../hooks/gesture/usePointerTracking.js";
+import {
+  mergeGestureContainerProps,
+  isScrollableInDirection,
+} from "../../hooks/gesture/utils.js";
+import { isInSwipeSafeZone } from "../../components/gesture/SwipeSafeZone.js";
+import {
+  type ContinuousOperationState,
+  IDLE_CONTINUOUS_OPERATION_STATE,
+} from "../../hooks/gesture/types.js";
+import type { UseDrawerSwipeInputOptions, UseDrawerSwipeInputResult } from "./types.js";
+import { getDrawerAnimationAxis, getDrawerCloseSwipeSign, getDrawerOpenSwipeSign } from "./types.js";
+
+/**
+ * Default dismiss threshold (30% of container size).
+ */
+const DEFAULT_DISMISS_THRESHOLD = 0.3;
+
+/**
+ * Velocity threshold for quick flick dismissal (px/ms).
+ */
+const VELOCITY_THRESHOLD = 0.5;
+
+// ============================================================================
+// Helper functions (extracted to avoid ternary violations)
+// ============================================================================
+
+function getContainerSize(container: HTMLElement, axis: "x" | "y"): number {
+  if (axis === "x") {
+    return container.clientWidth;
+  }
+  return container.clientHeight;
+}
+
+function getAxisDelta(
+  start: { x: number; y: number },
+  current: { x: number; y: number },
+  axis: "x" | "y",
+): number {
+  if (axis === "x") {
+    return current.x - start.x;
+  }
+  return current.y - start.y;
+}
+
+const PHASE_MAP: Record<string, "idle" | "operating" | "ended"> = {
+  idle: "idle",
+  ended: "ended",
+};
+
+function normalizePhase(phase: string): "idle" | "operating" | "ended" {
+  return PHASE_MAP[phase] ?? "operating";
+}
+
+function computeDisplacementValue(
+  closeSwipeSign: 1 | -1,
+  axis: "x" | "y",
+  closeDisplacement: number,
+): { x: number; y: number } {
+  const signedDisplacement = closeSwipeSign * closeDisplacement;
+  if (axis === "x") {
+    return { x: signedDisplacement, y: 0 };
+  }
+  return { x: 0, y: signedDisplacement };
+}
+
+function computeAxisDisplacement(
+  displacement: { x: number; y: number },
+  axis: "x" | "y",
+): number {
+  if (axis === "x") {
+    return Math.abs(displacement.x);
+  }
+  return Math.abs(displacement.y);
+}
+
+function isEdgeSwipeEnabled(enableEdgeSwipeOpen: boolean, isOpen: boolean): boolean {
+  if (!enableEdgeSwipeOpen) {
+    return false;
+  }
+  return !isOpen;
+}
+
+function isCloseSwipeEnabled(enableSwipeClose: boolean, isOpen: boolean): boolean {
+  if (!enableSwipeClose) {
+    return false;
+  }
+  return isOpen;
+}
+
+function isDrawerOpening(isEdgeGesture: boolean, isOpen: boolean): boolean {
+  if (!isEdgeGesture) {
+    return false;
+  }
+  return !isOpen;
+}
+
+function isDrawerClosing(closePhase: "idle" | "operating" | "ended", isOpen: boolean): boolean {
+  if (closePhase === "idle") {
+    return false;
+  }
+  return isOpen;
+}
+
+function computeVelocity(
+  start: { x: number; y: number; timestamp: number } | null,
+  current: { x: number; y: number; timestamp: number } | null,
+  displacement: number,
+): number {
+  if (!start || !current) {
+    return 0;
+  }
+  const timeDelta = Math.max(1, current.timestamp - start.timestamp);
+  return displacement / timeDelta;
+}
+
+/**
+ * Hook for detecting swipe gestures to open/close a drawer.
+ *
+ * When drawer is closed:
+ * - Detects edge swipe from the anchor edge to trigger open
+ *
+ * When drawer is open:
+ * - Detects drag gesture within drawer to trigger close
+ * - Respects scrollable content boundaries
+ *
+ * @example
+ * ```tsx
+ * const { state, edgeContainerProps, drawerContentProps } = useDrawerSwipeInput({
+ *   edgeContainerRef: gridLayoutRef,
+ *   drawerContentRef: drawerRef,
+ *   direction: "left",
+ *   isOpen,
+ *   onSwipeOpen: () => setOpen(true),
+ *   onSwipeClose: () => setOpen(false),
+ * });
+ * ```
+ */
+export function useDrawerSwipeInput(
+  options: UseDrawerSwipeInputOptions,
+): UseDrawerSwipeInputResult {
+  const {
+    edgeContainerRef,
+    drawerContentRef,
+    direction,
+    isOpen,
+    onSwipeOpen,
+    onSwipeClose,
+    enableEdgeSwipeOpen = true,
+    enableSwipeClose = true,
+    edgeWidth = 20,
+    dismissThreshold = DEFAULT_DISMISS_THRESHOLD,
+  } = options;
+
+  const axis = getDrawerAnimationAxis(direction);
+  const closeSwipeSign = getDrawerCloseSwipeSign(direction);
+  const openSwipeSign = getDrawerOpenSwipeSign(direction);
+
+  // Track container size for progress calculation
+  const containerSizeRef = React.useRef(0);
+
+  // Measure drawer content size
+  React.useLayoutEffect(() => {
+    const container = drawerContentRef.current;
+    if (!container) {
+      return;
+    }
+
+    const updateSize = () => {
+      containerSizeRef.current = getContainerSize(container, axis);
+    };
+
+    updateSize();
+
+    const observer = new ResizeObserver(updateSize);
+    observer.observe(container);
+
+    return () => observer.disconnect();
+  }, [drawerContentRef, axis]);
+
+  // =========== Edge swipe to OPEN ===========
+  const handleOpenSwipeEnd = React.useCallback(
+    (state: { direction: 1 | -1 | 0 }) => {
+      // Open when swiping in the correct direction (away from edge)
+      if (state.direction === openSwipeSign) {
+        onSwipeOpen();
+      }
+    },
+    [openSwipeSign, onSwipeOpen],
+  );
+
+  const {
+    isEdgeGesture,
+    state: edgeSwipeState,
+    containerProps: edgeSwipeProps,
+  } = useEdgeSwipeInput({
+    containerRef: edgeContainerRef,
+    edge: direction,
+    edgeWidth,
+    enabled: isEdgeSwipeEnabled(enableEdgeSwipeOpen, isOpen),
+    onSwipeEnd: handleOpenSwipeEnd,
+  });
+
+  // Native gesture guard for edge swipe
+  const { containerProps: guardProps } = useNativeGestureGuard({
+    containerRef: edgeContainerRef,
+    active: isEdgeGesture,
+    preventEdgeBack: true,
+    preventOverscroll: true,
+    edgeWidth,
+  });
+
+  // =========== Drag to CLOSE (Dialog pattern) ===========
+  const { state: closeTracking, onPointerDown: baseClosePointerDown } = usePointerTracking({
+    enabled: isCloseSwipeEnabled(enableSwipeClose, isOpen),
+  });
+
+  const [closePhase, setClosePhase] = React.useState<"idle" | "operating" | "ended">("idle");
+  const lastCloseDisplacementRef = React.useRef(0);
+
+  // Wrap pointer down with scroll check and safe zone check
+  const onClosePointerDown = React.useCallback(
+    (event: React.PointerEvent) => {
+      if (!enableSwipeClose || !isOpen) {
+        return;
+      }
+
+      const container = drawerContentRef.current;
+      if (!container) {
+        return;
+      }
+
+      const target = event.target as HTMLElement;
+
+      // Check if target is in a SwipeSafeZone
+      if (isInSwipeSafeZone(target, container)) {
+        return; // Don't start close swipe if inside safe zone
+      }
+
+      // Check if target is in a scrollable area that would block swipe
+      if (isScrollableInDirection(target, container, axis, closeSwipeSign)) {
+        return; // Don't start close swipe if inside scrollable content
+      }
+
+      baseClosePointerDown(event);
+    },
+    [enableSwipeClose, isOpen, drawerContentRef, axis, closeSwipeSign, baseClosePointerDown],
+  );
+
+  // Calculate close displacement
+  const closeDisplacement = React.useMemo(() => {
+    if (!closeTracking.isDown || !closeTracking.start || !closeTracking.current) {
+      return lastCloseDisplacementRef.current;
+    }
+
+    const delta = getAxisDelta(closeTracking.start, closeTracking.current, axis);
+
+    // Only count movement in close direction
+    const signedDelta = delta * closeSwipeSign;
+    return Math.max(0, signedDelta);
+  }, [closeTracking.isDown, closeTracking.start, closeTracking.current, axis, closeSwipeSign]);
+
+  // Track displacement while dragging
+  React.useEffect(() => {
+    if (closeTracking.isDown && closeTracking.current) {
+      lastCloseDisplacementRef.current = closeDisplacement;
+    }
+  }, [closeTracking.isDown, closeTracking.current, closeDisplacement]);
+
+  // Handle close drag start
+  React.useEffect(() => {
+    if (closeTracking.isDown && closePhase === "idle") {
+      setClosePhase("operating");
+    }
+  }, [closeTracking.isDown, closePhase]);
+
+  // Handle close drag end
+  React.useEffect(() => {
+    if (!closeTracking.isDown && closePhase === "operating") {
+      const displacement = lastCloseDisplacementRef.current;
+      const hasMovement = displacement > 1;
+
+      if (hasMovement) {
+        setClosePhase("ended");
+
+        // Check if should close
+        const containerSize = containerSizeRef.current;
+        if (containerSize > 0) {
+          const ratio = displacement / containerSize;
+          const velocity = computeVelocity(closeTracking.start, closeTracking.current, displacement);
+
+          if (ratio >= dismissThreshold || velocity >= VELOCITY_THRESHOLD) {
+            onSwipeClose();
+          }
+        }
+      } else {
+        setClosePhase("idle");
+        lastCloseDisplacementRef.current = 0;
+      }
+    }
+  }, [closeTracking.isDown, closePhase, dismissThreshold, onSwipeClose, closeTracking.start, closeTracking.current]);
+
+  // Transition from ended to idle
+  React.useEffect(() => {
+    if (closePhase === "ended") {
+      queueMicrotask(() => {
+        setClosePhase("idle");
+        lastCloseDisplacementRef.current = 0;
+      });
+    }
+  }, [closePhase]);
+
+  // Reset close state when drawer closes
+  React.useEffect(() => {
+    if (!isOpen) {
+      setClosePhase("idle");
+      lastCloseDisplacementRef.current = 0;
+    }
+  }, [isOpen]);
+
+  // =========== Combined state ===========
+  const isOpening = isDrawerOpening(isEdgeGesture, isOpen);
+  const isClosing = isDrawerClosing(closePhase, isOpen);
+
+  // Determine primary displacement based on current operation
+  const displacement = React.useMemo(() => {
+    if (isOpening) {
+      return computeAxisDisplacement(edgeSwipeState.displacement, axis);
+    }
+    if (isClosing) {
+      return closeDisplacement;
+    }
+    return 0;
+  }, [isOpening, isClosing, axis, edgeSwipeState.displacement, closeDisplacement]);
+
+  // Progress calculation
+  const progress = React.useMemo(() => {
+    const containerSize = containerSizeRef.current;
+    if (containerSize <= 0) {
+      return 0;
+    }
+    return Math.min(displacement / containerSize, 1);
+  }, [displacement]);
+
+  // Combined operation state
+  const state = React.useMemo<ContinuousOperationState>(() => {
+    if (isOpening) {
+      return {
+        phase: normalizePhase(edgeSwipeState.phase),
+        displacement: edgeSwipeState.displacement,
+        velocity: edgeSwipeState.velocity,
+      };
+    }
+    if (isClosing) {
+      return {
+        phase: closePhase,
+        displacement: computeDisplacementValue(closeSwipeSign, axis, closeDisplacement),
+        velocity: { x: 0, y: 0 },
+      };
+    }
+    return IDLE_CONTINUOUS_OPERATION_STATE;
+  }, [isOpening, isClosing, edgeSwipeState, closePhase, closeDisplacement, axis, closeSwipeSign]);
+
+  // Container props
+  const edgeContainerProps = React.useMemo(
+    () => mergeGestureContainerProps(edgeSwipeProps, guardProps),
+    [edgeSwipeProps, guardProps],
+  );
+
+  const drawerContentProps = React.useMemo(() => ({
+    onPointerDown: onClosePointerDown,
+    style: {
+      touchAction: "none" as const,
+      userSelect: "none" as const,
+      WebkitUserSelect: "none" as const,
+    },
+  }), [onClosePointerDown]);
+
+  return {
+    state,
+    isOpening,
+    isClosing,
+    progress,
+    displacement,
+    edgeContainerProps,
+    drawerContentProps,
+  };
+}

package/src/modules/grid/GridLayoutContext.tsx

@@ -0,0 +1,57 @@
+/**
+ * @file Context provider for grid layer rendering helpers.
+ */
+import * as React from "react";
+import type { LayerDefinition } from "../../types";
+
+export type GridLayerHandleProps = React.HTMLAttributes<HTMLElement> & {
+  "data-drag-handle": "true";
+};
+
+export type ResizeHandleConfig =
+  | {
+      key: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+      variant: "corner";
+      horizontal: "left" | "right";
+      vertical: "top" | "bottom";
+    }
+  | {
+      key: "left" | "right" | "top" | "bottom";
+      variant: "edge";
+      horizontal?: "left" | "right";
+      vertical?: "top" | "bottom";
+    };
+
+export type GridLayerRenderState = {
+  style: React.CSSProperties;
+  isResizable: boolean;
+  isResizing: boolean;
+  onResizeHandlePointerDown: (config: ResizeHandleConfig, event: React.PointerEvent<HTMLDivElement>) => void;
+};
+
+export type GridLayoutContextValue = {
+  handleLayerPointerDown: (event: React.PointerEvent<HTMLDivElement>) => void;
+  getLayerRenderState: (layer: LayerDefinition) => GridLayerRenderState;
+  getLayerHandleProps: (layerId: string) => GridLayerHandleProps;
+  /**
+   * Whether the GridLayout is mounted at root level.
+   * When true, scrollable layers should delegate to browser's native scroll.
+   */
+  isRootLevel: boolean;
+};
+
+const GridLayoutContext = React.createContext<GridLayoutContextValue | null>(null);
+
+export const GridLayoutProvider: React.FC<
+  React.PropsWithChildren<{ value: GridLayoutContextValue }>
+> = ({ value, children }) => {
+  return <GridLayoutContext.Provider value={value}>{children}</GridLayoutContext.Provider>;
+};
+
+export const useGridLayoutContext = (): GridLayoutContextValue => {
+  const context = React.useContext(GridLayoutContext);
+  if (!context) {
+    throw new Error("useGridLayoutContext must be used within a GridLayoutProvider.");
+  }
+  return context;
+};

package/src/modules/grid/LayerInstanceContext.tsx

@@ -0,0 +1,56 @@
+/**
+ * @file Context exposing the current grid layer id and helpers to child components.
+ */
+import * as React from "react";
+import type { LayerDefinition } from "../../types";
+import { usePanelSystem } from "../../PanelSystemContext";
+import { useGridLayoutContext, type GridLayerHandleProps } from "./GridLayoutContext";
+
+type LayerInstanceContextValue = {
+  layerId: string;
+};
+
+const LayerInstanceContext = React.createContext<LayerInstanceContextValue | null>(null);
+
+export type LayerInstanceProviderProps = React.PropsWithChildren<LayerInstanceContextValue>;
+
+export const LayerInstanceProvider: React.FC<LayerInstanceProviderProps> = ({ layerId, children }) => {
+  const value = React.useMemo(() => ({ layerId }), [layerId]);
+  return <LayerInstanceContext.Provider value={value}>{children}</LayerInstanceContext.Provider>;
+};
+
+export const useLayerInstance = (): LayerInstanceContextValue => {
+  const value = React.useContext(LayerInstanceContext);
+  if (!value) {
+    throw new Error("useLayerInstance must be used within a LayerInstanceProvider.");
+  }
+  return value;
+};
+
+/**
+ * Convenience: read the current layer definition from the core registry.
+ */
+export const useCurrentLayerDefinition = (): LayerDefinition => {
+  const { layerId } = useLayerInstance();
+  const { layers } = usePanelSystem();
+  const def = layers.layerById.get(layerId);
+  if (!def) {
+    throw new Error(`Layer definition not found for id: ${layerId}`);
+  }
+  return def;
+};
+
+/**
+ * Convenience: get drag handle props, pre-bound to the current layer.
+ */
+export const useCurrentLayerHandleProps = (): GridLayerHandleProps => {
+  const { layerId } = useLayerInstance();
+  const { getLayerHandleProps } = useGridLayoutContext();
+  return React.useMemo(() => getLayerHandleProps(layerId), [getLayerHandleProps, layerId]);
+};
+
+/**
+ * Compatibility helper for existing code using useLayerDragHandle.
+ * Prefer useCurrentLayerHandleProps for direct access.
+ */
+export const useLayerDragHandleProps = useCurrentLayerHandleProps;

package/src/modules/grid/resizeHandles.ts

@@ -0,0 +1,157 @@
+/**
+ * @file Resize handle configuration computation for grid tracks.
+ */
+import type { GridTrack } from "../../types";
+
+export type TrackHandleConfig = {
+  trackIndex: number;
+  align: "start" | "end";
+  span: { start: number; end: number };
+};
+
+/**
+ * Computes the valid row span for a column boundary.
+ * Returns the contiguous range of rows where the adjacent areas differ.
+ */
+const computeColumnBoundarySpan = (
+  areas: string[][],
+  boundaryIndex: number,
+): { start: number; end: number } => {
+  const rowCount = areas.length;
+
+  // Find rows where left and right areas differ at this boundary
+  const validRows: number[] = [];
+  for (let rowIndex = 0; rowIndex < rowCount; rowIndex++) {
+    const row = areas[rowIndex];
+    const leftArea = row[boundaryIndex];
+    const rightArea = row[boundaryIndex + 1];
+    if (leftArea !== rightArea) {
+      validRows.push(rowIndex);
+    }
+  }
+
+  if (validRows.length === 0) {
+    // Fallback: full span if no valid rows found (shouldn't happen for resizable columns)
+    return { start: 1, end: rowCount + 1 };
+  }
+
+  // Convert to 1-indexed grid lines
+  const minRow = Math.min(...validRows);
+  const maxRow = Math.max(...validRows);
+  return { start: minRow + 1, end: maxRow + 2 };
+};
+
+/**
+ * Computes the valid column span for a row boundary.
+ * Returns the contiguous range of columns where the adjacent areas differ.
+ */
+const computeRowBoundarySpan = (
+  areas: string[][],
+  boundaryIndex: number,
+): { start: number; end: number } => {
+  const topRow = areas[boundaryIndex];
+  const bottomRow = areas[boundaryIndex + 1];
+  const colCount = topRow?.length ?? 0;
+
+  // Find columns where top and bottom areas differ at this boundary
+  const validCols: number[] = [];
+  for (let colIndex = 0; colIndex < colCount; colIndex++) {
+    const topArea = topRow?.[colIndex];
+    const bottomArea = bottomRow?.[colIndex];
+    if (topArea !== bottomArea) {
+      validCols.push(colIndex);
+    }
+  }
+
+  if (validCols.length === 0) {
+    // Fallback: full span if no valid columns found
+    return { start: 1, end: colCount + 1 };
+  }
+
+  // Convert to 1-indexed grid lines
+  const minCol = Math.min(...validCols);
+  const maxCol = Math.max(...validCols);
+  return { start: minCol + 1, end: maxCol + 2 };
+};
+
+export const computeColumnResizeHandles = (
+  tracks: GridTrack[],
+  areas: string[][],
+): TrackHandleConfig[] => {
+  if (tracks.length === 0) {
+    return [];
+  }
+
+  const rowCount = areas.length;
+
+  if (tracks.length === 1) {
+    const onlyTrack = tracks[0];
+    if (onlyTrack?.resizable) {
+      const fullSpan = { start: 1, end: rowCount + 1 };
+      return [{ trackIndex: 0, align: "end", span: fullSpan }];
+    }
+    return [];
+  }
+
+  const handles: TrackHandleConfig[] = [];
+
+  const boundaryIndexes = Array.from({ length: tracks.length - 1 }, (_, index) => index);
+  boundaryIndexes.forEach((boundaryIndex) => {
+    const leftTrack = tracks[boundaryIndex];
+    const rightTrack = tracks[boundaryIndex + 1];
+
+    if (rightTrack?.resizable) {
+      const span = computeColumnBoundarySpan(areas, boundaryIndex);
+      handles.push({ trackIndex: boundaryIndex + 1, align: "start", span });
+      return;
+    }
+
+    if (leftTrack?.resizable) {
+      const span = computeColumnBoundarySpan(areas, boundaryIndex);
+      handles.push({ trackIndex: boundaryIndex, align: "end", span });
+    }
+  });
+
+  return handles;
+};
+
+export const computeRowResizeHandles = (
+  tracks: GridTrack[],
+  areas: string[][],
+): TrackHandleConfig[] => {
+  if (tracks.length === 0) {
+    return [];
+  }
+
+  const colCount = areas[0]?.length ?? 0;
+
+  if (tracks.length === 1) {
+    const onlyTrack = tracks[0];
+    if (onlyTrack?.resizable) {
+      const fullSpan = { start: 1, end: colCount + 1 };
+      return [{ trackIndex: 0, align: "end", span: fullSpan }];
+    }
+    return [];
+  }
+
+  const handles: TrackHandleConfig[] = [];
+
+  const boundaryIndexes = Array.from({ length: tracks.length - 1 }, (_, index) => index);
+  boundaryIndexes.forEach((boundaryIndex) => {
+    const topTrack = tracks[boundaryIndex];
+    const bottomTrack = tracks[boundaryIndex + 1];
+
+    if (bottomTrack?.resizable) {
+      const span = computeRowBoundarySpan(areas, boundaryIndex);
+      handles.push({ trackIndex: boundaryIndex + 1, align: "start", span });
+      return;
+    }
+
+    if (topTrack?.resizable) {
+      const span = computeRowBoundarySpan(areas, boundaryIndex);
+      handles.push({ trackIndex: boundaryIndex, align: "end", span });
+    }
+  });
+
+  return handles;
+};