react-panel-layout 0.5.1 → 0.6.0

package/src/hooks/useSwipeContentTransform.ts

@@ -0,0 +1,235 @@
+/**
+ * @file Shared hook for DOM-based swipe content transform.
+ *
+ * This hook provides immediate DOM manipulation for swipe gestures,
+ * with smooth snap-back animation when the swipe ends.
+ *
+ * Used by both Pivot and Stack for consistent swipe behavior.
+ */
+import * as React from "react";
+import { useAnimationFrame, interpolate, easings } from "./useAnimationFrame.js";
+import type { GestureAxis } from "./gesture/types.js";
+
+const DEFAULT_ANIMATION_DURATION = 300;
+
+/**
+ * Options for useSwipeContentTransform hook.
+ */
+export type UseSwipeContentTransformOptions = {
+  /** Ref to the element to transform */
+  elementRef: React.RefObject<HTMLElement | null>;
+  /** Target position in pixels (where element should be at rest) */
+  targetPx: number;
+  /** Current swipe displacement in pixels */
+  displacement: number;
+  /** Whether swipe gesture is active */
+  isSwiping: boolean;
+  /** Axis of transformation */
+  axis?: GestureAxis;
+  /** Duration of snap animation in ms */
+  animationDuration?: number;
+  /** Container size in pixels (used for snap on resize) */
+  containerSize?: number;
+  /**
+   * Whether to animate when targetPx changes (without swipe).
+   * Use this for tab bar animations triggered by click/button.
+   * @default false
+   */
+  animateOnTargetChange?: boolean;
+  /**
+   * Initial position in pixels when first mounted.
+   * If different from targetPx, will animate from initialPx to targetPx.
+   * Use this for push animations where new panel comes from off-screen.
+   */
+  initialPx?: number;
+};
+
+/**
+ * Animation direction information.
+ */
+export type AnimationDirection = {
+  /** Source position in pixels */
+  from: number;
+  /** Target position in pixels */
+  to: number;
+};
+
+/**
+ * Result from useSwipeContentTransform hook.
+ */
+export type UseSwipeContentTransformResult = {
+  /** Whether snap animation is currently running */
+  isAnimating: boolean;
+  /** Current position in pixels (for visibility calculations) */
+  currentPx: number;
+  /** Animation direction info, or null if not animating */
+  animationDirection: AnimationDirection | null;
+};
+
+/**
+ * Get CSS transform function name for axis.
+ */
+const getTransformFn = (axis: GestureAxis): "translateX" | "translateY" => {
+  return axis === "horizontal" ? "translateX" : "translateY";
+};
+
+/**
+ * Hook for DOM-based swipe content transform.
+ *
+ * During swipe: immediately updates element.style.transform to follow finger.
+ * After swipe: animates from current position to target position.
+ *
+ * @example
+ * ```tsx
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const { isAnimating, currentPx } = useSwipeContentTransform({
+ *   elementRef: containerRef,
+ *   targetPx: 0,
+ *   displacement: inputState.displacement.x,
+ *   isSwiping: inputState.phase === "swiping",
+ * });
+ * ```
+ */
+export function useSwipeContentTransform(
+  options: UseSwipeContentTransformOptions,
+): UseSwipeContentTransformResult {
+  const {
+    elementRef,
+    targetPx,
+    displacement,
+    isSwiping,
+    axis = "horizontal",
+    animationDuration = DEFAULT_ANIMATION_DURATION,
+    containerSize,
+    animateOnTargetChange = false,
+    initialPx,
+  } = options;
+
+  // Use initialPx if provided, otherwise use targetPx
+  const effectiveInitialPx = initialPx ?? targetPx;
+  const currentPxRef = React.useRef<number>(effectiveInitialPx);
+  const animRef = React.useRef<{ from: number; to: number } | null>(null);
+  const prevTargetPxRef = React.useRef<number>(targetPx);
+  const prevContainerSizeRef = React.useRef<number | undefined>(containerSize);
+  const pendingAnimationRef = React.useRef<{ from: number; to: number } | null>(null);
+  const isFirstMountRef = React.useRef<boolean>(true);
+
+  // Schedule animation on first mount if initialPx differs from targetPx
+  if (isFirstMountRef.current && initialPx !== undefined && initialPx !== targetPx) {
+    pendingAnimationRef.current = { from: initialPx, to: targetPx };
+    isFirstMountRef.current = false;
+  } else if (isFirstMountRef.current) {
+    isFirstMountRef.current = false;
+  }
+
+  // Handle target changes when not swiping
+  if (targetPx !== prevTargetPxRef.current && !isSwiping && animRef.current === null) {
+    if (animateOnTargetChange) {
+      // Schedule animation from current position to new target
+      const distance = Math.abs(currentPxRef.current - targetPx);
+      if (distance > 1) {
+        pendingAnimationRef.current = { from: currentPxRef.current, to: targetPx };
+      } else {
+        currentPxRef.current = targetPx;
+      }
+    } else {
+      // Snap immediately (default behavior for resize, etc.)
+      currentPxRef.current = targetPx;
+    }
+    prevTargetPxRef.current = targetPx;
+  }
+
+  // Snap when container size changes (resize)
+  if (containerSize !== undefined && containerSize !== prevContainerSizeRef.current && containerSize > 0) {
+    currentPxRef.current = targetPx;
+    prevContainerSizeRef.current = containerSize;
+  }
+
+  // Animation frame handler
+  const handleFrame = React.useCallback(
+    ({ easedProgress }: { easedProgress: number }) => {
+      const element = elementRef.current;
+      const anim = animRef.current;
+      if (!element || !anim) {
+        return;
+      }
+      const value = interpolate(anim.from, anim.to, easedProgress);
+      currentPxRef.current = value;
+      element.style.transform = `${getTransformFn(axis)}(${value}px)`;
+    },
+    [axis, elementRef],
+  );
+
+  const handleComplete = React.useCallback(() => {
+    animRef.current = null;
+    currentPxRef.current = targetPx;
+    prevTargetPxRef.current = targetPx;
+  }, [targetPx]);
+
+  const { isAnimating, start, cancel } = useAnimationFrame({
+    duration: animationDuration,
+    easing: easings.easeOutExpo,
+    onFrame: handleFrame,
+    onComplete: handleComplete,
+  });
+
+  // When swipe ends or target changes with animateOnTargetChange, animate to target
+  React.useLayoutEffect(() => {
+    if (isSwiping) {
+      cancel();
+      animRef.current = null;
+      pendingAnimationRef.current = null;
+      return;
+    }
+
+    // Check for pending animation (from target change or initial mount)
+    if (pendingAnimationRef.current) {
+      const pending = pendingAnimationRef.current;
+      animRef.current = pending;
+      pendingAnimationRef.current = null;
+      // Set initial position before animation starts
+      const element = elementRef.current;
+      if (element) {
+        element.style.transform = `${getTransformFn(axis)}(${pending.from}px)`;
+      }
+      start();
+      return;
+    }
+
+    const currentPx = currentPxRef.current;
+    const distance = Math.abs(currentPx - targetPx);
+
+    if (distance > 1) {
+      // Need to animate from current to target
+      animRef.current = { from: currentPx, to: targetPx };
+      start();
+    } else {
+      // Close enough, snap directly
+      currentPxRef.current = targetPx;
+      prevTargetPxRef.current = targetPx;
+    }
+  }, [isSwiping, targetPx, start, cancel]);
+
+  // Direct DOM update during swipe
+  React.useLayoutEffect(() => {
+    const element = elementRef.current;
+    if (!element) {
+      return;
+    }
+
+    // Skip if animation is running, about to start, or pending
+    if (isAnimating || animRef.current !== null || pendingAnimationRef.current !== null) {
+      return;
+    }
+
+    const displayPx = targetPx + displacement;
+    currentPxRef.current = displayPx;
+    element.style.transform = `${getTransformFn(axis)}(${displayPx}px)`;
+  }, [targetPx, displacement, axis, isAnimating, elementRef]);
+
+  return {
+    isAnimating,
+    currentPx: currentPxRef.current,
+    animationDirection: animRef.current,
+  };
+}

package/src/hooks/useTransitionState.ts

@@ -0,0 +1,95 @@
+/**
+ * @file Generic transition state management with animation support.
+ */
+import * as React from "react";
+
+export type TransitionMode = "none" | "css";
+
+export type TransitionOptions = {
+  mode?: TransitionMode;
+  element?: React.RefObject<HTMLElement>;
+  duration?: number;
+};
+
+export type UseTransitionStateOptions = {
+  onOpen?: (id: string) => void;
+  onClose?: (id: string) => void;
+  onTransitionEnd?: (id: string, isOpen: boolean) => void;
+};
+
+const waitForTransitionEnd = (el: HTMLElement, timeout: number): Promise<void> =>
+  new Promise((resolve) => {
+    // eslint-disable-next-line no-restricted-syntax -- mutable flag needed for deduplication
+    let resolved = false;
+    const done = () => {
+      if (resolved) {return;}
+      resolved = true;
+      el.removeEventListener("transitionend", handler);
+      resolve();
+    };
+    const handler = (e: TransitionEvent) => {
+      if (e.target === el) {done();}
+    };
+    el.addEventListener("transitionend", handler);
+    setTimeout(done, timeout + 50);
+  });
+
+export const runTransition = async (
+  update: () => void,
+  mode: TransitionMode,
+  el: HTMLElement | null | undefined,
+  duration: number,
+): Promise<void> => {
+  switch (mode) {
+    case "none":
+      update();
+      return;
+
+    case "css":
+      update();
+      if (el) {await waitForTransitionEnd(el, duration);}
+      return;
+  }
+};
+
+export const useTransitionState = (options?: UseTransitionStateOptions) => {
+  const [states, setStates] = React.useState<Record<string, boolean>>({});
+  const optionsRef = React.useRef(options);
+  optionsRef.current = options;
+
+  const update = React.useCallback(
+    async (id: string, isOpen: boolean, transitionOptions?: TransitionOptions) => {
+      const { mode = "none", element, duration = 300 } = transitionOptions ?? {};
+
+      const applyState = () => {
+        setStates((prev) => {
+          if (prev[id] === isOpen) {return prev;}
+          return { ...prev, [id]: isOpen };
+        });
+      };
+
+      await runTransition(applyState, mode, element?.current, duration);
+
+      const opts = optionsRef.current;
+      if (isOpen) {
+        opts?.onOpen?.(id);
+      } else {
+        opts?.onClose?.(id);
+      }
+      opts?.onTransitionEnd?.(id, isOpen);
+    },
+    [],
+  );
+
+  const state = React.useCallback((id: string): boolean => states[id] ?? false, [states]);
+  const open = React.useCallback(
+    (id: string, opts?: TransitionOptions) => update(id, true, opts),
+    [update],
+  );
+  const close = React.useCallback(
+    (id: string, opts?: TransitionOptions) => update(id, false, opts),
+    [update],
+  );
+
+  return { state, open, close };
+};

package/src/index.tsx

@@ -0,0 +1,88 @@
+/**
+ * @file Main entry point for the React Panel Layout library
+ */
+
+// ============================================================================
+// Core Type Definitions
+// ============================================================================
+export type {
+  // Grid / panel
+  GridTrack,
+  PanelLayoutConfig,
+  LayerPositionMode,
+  LayerDefinition,
+  PanelLayoutProps,
+  // Window / popup / drawer
+  Position,
+  WindowOffset,
+  WindowPosition,
+  WindowSize,
+  WindowBounds,
+  WindowConstraints,
+  PopupWindowFeatures,
+  PopupWindowOptions,
+  PopupWindowFactoryConfig,
+  FloatingWindowMode,
+  FloatingBehavior,
+  FloatingHeaderConfig,
+  DrawerBehavior,
+} from "./types";
+
+// ============================================================================
+// Main Layout Component
+// ============================================================================
+export { GridLayout } from "./components/grid/GridLayout";
+export type { GridLayoutProps } from "./components/grid/GridLayout";
+
+// ============================================================================
+// Drawer Components
+// ============================================================================
+export { Drawer } from "./components/window/Drawer";
+export type { DrawerProps } from "./components/window/Drawer";
+export { DrawerLayers } from "./components/window/DrawerLayers";
+export type { DrawerLayersProps } from "./components/window/DrawerLayers";
+
+// ============================================================================
+// Floating Window Components
+// ============================================================================
+export { FloatingWindow } from "./components/window/FloatingWindow";
+export type { FloatingWindowProps } from "./components/window/FloatingWindow";
+
+// ============================================================================
+// Panel Components
+// ============================================================================
+export { HorizontalDivider } from "./components/resizer/HorizontalDivider";
+export type { HorizontalDividerProps } from "./components/resizer/HorizontalDivider";
+
+export { ResizeHandle } from "./components/resizer/ResizeHandle";
+export type { ResizeHandleProps } from "./components/resizer/ResizeHandle";
+
+// ============================================================================
+// Public Hooks
+// ============================================================================
+export { useLayerDragHandle } from "./modules/grid/useLayerDragHandle";
+export { useFloatingState } from "./modules/window/useFloatingState";
+export { useTransitionState, runTransition } from "./hooks/useTransitionState";
+export type { TransitionMode, TransitionOptions, UseTransitionStateOptions } from "./hooks/useTransitionState";
+
+// ============================================================================
+// Style Constants
+// ============================================================================
+export { CSS_VAR_PREFIX } from "./constants/styles";
+
+// ============================================================================
+// Panel System (tabs + splits)
+// ============================================================================
+export { PanelSystem } from "./modules/panels/system/PanelSystem";
+export { buildInitialState } from "./modules/panels";
+export type {
+  PanelSystemProps,
+  PanelSystemState,
+  GroupModel,
+  TabDefinition,
+  SplitDirection,
+  TabBarRenderProps,
+  PanelGroupRenderProps,
+  PanelSplitLimits,
+} from "./modules/panels/state/types";
+

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;
+};