react-panel-layout 0.5.2 → 0.6.1

package/src/PanelSystemContext.tsx

@@ -0,0 +1,88 @@
+/**
+ * @file PanelSystemContext
+ *
+ * Core provider for panel definitions and registry. Grid-specific layout and
+ * interactions are composed by UI layers (e.g., GridLayout) on top of this.
+ *
+ * Includes content caching to preserve React component state across re-renders.
+ * This is essential for maintaining internal state when parent components
+ * re-create the layers array.
+ */
+import * as React from "react";
+import type { PanelLayoutConfig, LayerDefinition } from "./types";
+import { useContentCache } from "./hooks/useContentCache";
+
+export type PanelSystemContextValue = {
+  config: PanelLayoutConfig;
+  style?: React.CSSProperties;
+  layers: {
+    /** Raw panel definitions (no grid normalization). */
+    defs: LayerDefinition[];
+    /** Fast lookup map by id for consumers. */
+    layerById: Map<string, LayerDefinition>;
+  };
+  /**
+   * Get cached content for a layer. Returns the same ReactNode reference
+   * for the same layer ID to prevent remounting on parent re-renders.
+   */
+  getCachedContent: (layerId: string) => React.ReactNode | null;
+};
+
+const PanelSystemContext = React.createContext<PanelSystemContextValue | null>(null);
+
+export const usePanelSystem = (): PanelSystemContextValue => {
+  const ctx = React.useContext(PanelSystemContext);
+  if (!ctx) {
+    throw new Error("usePanelSystem must be used within a PanelSystemProvider.");
+  }
+  return ctx;
+};
+
+export type PanelSystemProviderProps = React.PropsWithChildren<{
+  config: PanelLayoutConfig;
+  layers: LayerDefinition[];
+  style?: React.CSSProperties;
+}>;
+
+export const PanelSystemProvider: React.FC<PanelSystemProviderProps> = ({ config, layers, style, children }) => {
+  const layerById = React.useMemo(() => {
+    const map = new Map<string, LayerDefinition>();
+    layers.forEach((layer) => {
+      map.set(layer.id, layer);
+    });
+    return map;
+  }, [layers]);
+
+  // Content resolver for useContentCache
+  const resolveContent = React.useCallback(
+    (layerId: string): React.ReactNode | null => {
+      const layer = layerById.get(layerId);
+      return layer?.component ?? null;
+    },
+    [layerById],
+  );
+
+  // Valid IDs for cache cleanup
+  const validIds = React.useMemo(() => layers.map((l) => l.id), [layers]);
+
+  // Use shared content cache hook
+  const { getCachedContent } = useContentCache({
+    resolveContent,
+    validIds,
+  });
+
+  const value = React.useMemo<PanelSystemContextValue>(
+    () => ({
+      config,
+      style,
+      layers: {
+        defs: layers,
+        layerById,
+      },
+      getCachedContent,
+    }),
+    [config, style, layers, layerById, getCachedContent],
+  );
+
+  return <PanelSystemContext.Provider value={value}>{children}</PanelSystemContext.Provider>;
+};

package/src/components/gesture/SwipeSafeZone.tsx

@@ -0,0 +1,69 @@
+/**
+ * @file SwipeSafeZone component
+ *
+ * A wrapper component that marks an area as exempt from swipe gesture detection.
+ * Content inside this zone will not trigger swipe-to-close or other swipe gestures.
+ *
+ * Use this for:
+ * - Scrollable content areas
+ * - Input fields and text areas
+ * - Interactive elements that need drag/swipe for their own purposes
+ */
+import * as React from "react";
+
+/**
+ * Data attribute used to identify swipe-safe zones.
+ * Swipe gesture handlers should check for this attribute on target elements.
+ */
+export const SWIPE_SAFE_ZONE_ATTR = "data-swipe-safe-zone";
+
+export type SwipeSafeZoneProps = {
+  /** Content to render inside the safe zone */
+  children: React.ReactNode;
+  /** Additional CSS class name */
+  className?: string;
+  /** Additional inline styles */
+  style?: React.CSSProperties;
+};
+
+/**
+ * SwipeSafeZone marks an area where swipe gestures should not be triggered.
+ *
+ * @example
+ * ```tsx
+ * <SwipeSafeZone>
+ *   <ScrollableList items={items} />
+ * </SwipeSafeZone>
+ * ```
+ */
+export const SwipeSafeZone: React.FC<SwipeSafeZoneProps> = ({
+  children,
+  className,
+  style,
+}) => {
+  return (
+    <div
+      className={className}
+      style={style}
+      data-swipe-safe-zone="true"
+    >
+      {children}
+    </div>
+  );
+};
+
+/**
+ * Check if an element is inside a SwipeSafeZone.
+ */
+export function isInSwipeSafeZone(element: HTMLElement, container: HTMLElement): boolean {
+  let current: HTMLElement | null = element;
+
+  while (current && current !== container) {
+    if (current.hasAttribute(SWIPE_SAFE_ZONE_ATTR)) {
+      return true;
+    }
+    current = current.parentElement;
+  }
+
+  return false;
+}

package/src/components/grid/GridLayerList.tsx

@@ -0,0 +1,172 @@
+/**
+ * @file Layer list rendering inside the grid layout.
+ *
+ * Uses content caching from PanelSystemContext to preserve component state
+ * when parent components re-render and recreate the layers array.
+ */
+import * as React from "react";
+import type { LayerDefinition } from "../../types";
+import { useGridLayoutContext } from "../../modules/grid/GridLayoutContext";
+import type { ResizeHandleConfig } from "../../modules/grid/GridLayoutContext";
+import { LayerInstanceProvider } from "../../modules/grid/LayerInstanceContext";
+import { usePanelSystem } from "../../PanelSystemContext";
+import { PopupLayerPortal } from "../window/PopupLayerPortal";
+import { FloatingWindow } from "../window/FloatingWindow";
+import { GridLayerResizeHandles } from "./GridLayerResizeHandles";
+import { PivotLayer } from "../pivot/PivotLayer";
+
+type GridLayerListProps = {
+  layers: LayerDefinition[];
+};
+
+/**
+ * Resolves layer content based on pivot and cache settings.
+ * Pivot layers use PivotLayer component, others use cache or direct content.
+ */
+const resolveLayerContent = (
+  layer: LayerDefinition,
+  getCachedContent: (layerId: string) => React.ReactNode | null,
+): React.ReactNode => {
+  if (layer.pivot) {
+    return <PivotLayer pivot={layer.pivot} />;
+  }
+  if (layer.cache) {
+    return getCachedContent(layer.id);
+  }
+  return layer.component;
+};
+
+/**
+ * Renders layer content with optional FloatingWindow chrome.
+ * Handles both chrome and non-chrome layers.
+ * Uses cached content only when layer.cache is true.
+ */
+const LayerContentRenderer = React.memo<{
+  layer: LayerDefinition;
+  onClose: () => void;
+}>(({ layer, onClose }) => {
+  const { getCachedContent } = usePanelSystem();
+
+  const content = resolveLayerContent(layer, getCachedContent);
+
+  if (!layer.floating?.chrome) {
+    return content;
+  }
+
+  return (
+    <FloatingWindow id={layer.id} config={layer.floating} onClose={onClose}>
+      {content}
+    </FloatingWindow>
+  );
+});
+LayerContentRenderer.displayName = "LayerContentRenderer";
+
+/**
+ * Renders resize handles if the layer is resizable.
+ */
+const LayerResizeHandles = React.memo<{
+  layerId: string;
+  isResizable: boolean;
+  onPointerDown: (config: ResizeHandleConfig, event: React.PointerEvent<HTMLDivElement>) => void;
+}>(({ layerId, isResizable, onPointerDown }) => {
+  if (!isResizable) {
+    return null;
+  }
+  return <GridLayerResizeHandles layerId={layerId} onPointerDown={onPointerDown} />;
+});
+LayerResizeHandles.displayName = "LayerResizeHandles";
+
+/**
+ * Determines the overflow style for a layer based on scrollable flag and floating status.
+ * - scrollable: auto (enable scrolling within container)
+ * - floating: visible (allow box-shadow to render outside bounds)
+ * - Not scrollable and not floating: hidden (prevent overflow)
+ */
+const resolveOverflowStyle = (
+  scrollable: boolean | undefined,
+  isFloating: boolean,
+): React.CSSProperties["overflow"] => {
+  if (scrollable) {
+    return "auto";
+  }
+  if (isFloating) {
+    return "visible";
+  }
+  return "hidden";
+};
+
+/**
+ * Renders a single embedded layer (non-popup).
+ */
+const EmbeddedLayer = React.memo<{
+  layer: LayerDefinition;
+  handleLayerPointerDown: (e: React.PointerEvent<HTMLDivElement>) => void;
+}>(({ layer, handleLayerPointerDown }) => {
+  const { getLayerRenderState } = useGridLayoutContext();
+  const { style, isResizable, isResizing, onResizeHandlePointerDown } = getLayerRenderState(layer);
+
+  const gridPlacementStyle = React.useMemo<React.CSSProperties>(() => {
+    const placement: React.CSSProperties = {};
+    if (layer.gridArea) {
+      placement.gridArea = layer.gridArea;
+    }
+    if (layer.gridRow) {
+      placement.gridRow = layer.gridRow;
+    }
+    if (layer.gridColumn) {
+      placement.gridColumn = layer.gridColumn;
+    }
+    return placement;
+  }, [layer.gridArea, layer.gridRow, layer.gridColumn]);
+
+  const combinedStyle = React.useMemo<React.CSSProperties>(() => {
+    // min-width/height: 0 allows grid items to shrink below content size
+    const isFloating = Boolean(layer.floating);
+    const overflow = resolveOverflowStyle(layer.scrollable, isFloating);
+    const baseStyle: React.CSSProperties = {
+      ...style,
+      ...gridPlacementStyle,
+      minWidth: 0,
+      minHeight: 0,
+      overflow,
+    };
+    return isResizable ? { ...baseStyle, position: "relative" } : baseStyle;
+  }, [style, gridPlacementStyle, isResizable, layer.scrollable, layer.floating]);
+
+  const handleClose = React.useCallback(() => {
+    layer.floating?.onClose?.();
+  }, [layer.floating]);
+
+  return (
+    <div
+      data-layer-id={layer.id}
+      data-draggable={Boolean(layer.floating?.draggable)}
+      data-resizable={isResizable}
+      data-resizing={isResizing}
+      style={combinedStyle}
+      onPointerDown={handleLayerPointerDown}
+    >
+      <LayerInstanceProvider layerId={layer.id}>
+        <LayerContentRenderer layer={layer} onClose={handleClose} />
+      </LayerInstanceProvider>
+      <LayerResizeHandles layerId={layer.id} isResizable={isResizable} onPointerDown={onResizeHandlePointerDown} />
+    </div>
+  );
+});
+EmbeddedLayer.displayName = "EmbeddedLayer";
+
+export const GridLayerList: React.FC<GridLayerListProps> = ({ layers }) => {
+  const { handleLayerPointerDown } = useGridLayoutContext();
+
+  return (
+    <>
+      {layers.map((layer) => {
+        const floatingMode = layer.floating?.mode ?? "embedded";
+        if (layer.floating && floatingMode === "popup") {
+          return <PopupLayerPortal key={layer.id} layer={layer} />;
+        }
+        return <EmbeddedLayer key={layer.id} layer={layer} handleLayerPointerDown={handleLayerPointerDown} />;
+      })}
+    </>
+  );
+};

package/src/components/grid/GridLayerResizeHandles.tsx

@@ -0,0 +1,145 @@
+/**
+ * @file Presentational resize handles for floating layers (corner + edge).
+ */
+import * as React from "react";
+import { GRID_LAYER_CORNER_HIT_SIZE, GRID_LAYER_EDGE_HIT_THICKNESS } from "../../constants/styles";
+
+const resizeHandleBaseStyle: React.CSSProperties = {
+  position: "absolute",
+  pointerEvents: "auto",
+  boxSizing: "border-box",
+  background: "transparent",
+  border: "none",
+};
+
+const cornerHandleStyle: React.CSSProperties = {
+  ...resizeHandleBaseStyle,
+  width: GRID_LAYER_CORNER_HIT_SIZE,
+  height: GRID_LAYER_CORNER_HIT_SIZE,
+  zIndex: 2,
+};
+
+const edgeHandleStyle: React.CSSProperties = {
+  ...resizeHandleBaseStyle,
+  zIndex: 1,
+};
+
+const cornerPositions: Record<string, React.CSSProperties> = {
+  "top-left": {
+    top: 0,
+    left: 0,
+    transform: "translate(-50%, -50%)",
+    cursor: "nwse-resize",
+  },
+  "top-right": {
+    top: 0,
+    right: 0,
+    transform: "translate(50%, -50%)",
+    cursor: "nesw-resize",
+  },
+  "bottom-left": {
+    bottom: 0,
+    left: 0,
+    transform: "translate(-50%, 50%)",
+    cursor: "nesw-resize",
+  },
+  "bottom-right": {
+    bottom: 0,
+    right: 0,
+    transform: "translate(50%, 50%)",
+    cursor: "nwse-resize",
+  },
+};
+
+const edgePositions: Record<string, React.CSSProperties> = {
+  left: {
+    top: GRID_LAYER_CORNER_HIT_SIZE,
+    bottom: GRID_LAYER_CORNER_HIT_SIZE,
+    left: 0,
+    width: GRID_LAYER_EDGE_HIT_THICKNESS,
+    transform: "translateX(-50%)",
+    cursor: "ew-resize",
+  },
+  right: {
+    top: GRID_LAYER_CORNER_HIT_SIZE,
+    bottom: GRID_LAYER_CORNER_HIT_SIZE,
+    right: 0,
+    width: GRID_LAYER_EDGE_HIT_THICKNESS,
+    transform: "translateX(50%)",
+    cursor: "ew-resize",
+  },
+  top: {
+    left: GRID_LAYER_CORNER_HIT_SIZE,
+    right: GRID_LAYER_CORNER_HIT_SIZE,
+    top: 0,
+    height: GRID_LAYER_EDGE_HIT_THICKNESS,
+    transform: "translateY(-50%)",
+    cursor: "ns-resize",
+  },
+  bottom: {
+    left: GRID_LAYER_CORNER_HIT_SIZE,
+    right: GRID_LAYER_CORNER_HIT_SIZE,
+    bottom: 0,
+    height: GRID_LAYER_EDGE_HIT_THICKNESS,
+    transform: "translateY(50%)",
+    cursor: "ns-resize",
+  },
+};
+
+export type HorizontalEdge = "left" | "right";
+export type VerticalEdge = "top" | "bottom";
+
+export type ResizeHandleConfig =
+  | {
+      key: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+      variant: "corner";
+      horizontal: HorizontalEdge;
+      vertical: VerticalEdge;
+    }
+  | {
+      key: "left" | "right" | "top" | "bottom";
+      variant: "edge";
+      horizontal?: HorizontalEdge;
+      vertical?: VerticalEdge;
+    };
+
+const RESIZE_HANDLE_CONFIGS: ReadonlyArray<ResizeHandleConfig> = [
+  { key: "top-left", variant: "corner", horizontal: "left", vertical: "top" },
+  { key: "top-right", variant: "corner", horizontal: "right", vertical: "top" },
+  { key: "bottom-left", variant: "corner", horizontal: "left", vertical: "bottom" },
+  { key: "bottom-right", variant: "corner", horizontal: "right", vertical: "bottom" },
+  { key: "left", variant: "edge", horizontal: "left" },
+  { key: "right", variant: "edge", horizontal: "right" },
+  { key: "top", variant: "edge", vertical: "top" },
+  { key: "bottom", variant: "edge", vertical: "bottom" },
+];
+
+export type GridLayerResizeHandlesProps = {
+  layerId: string;
+  onPointerDown: (config: ResizeHandleConfig, event: React.PointerEvent<HTMLDivElement>) => void;
+};
+
+export const GridLayerResizeHandles: React.FC<GridLayerResizeHandlesProps> = ({ layerId, onPointerDown }) => {
+  return (
+    <>
+      {RESIZE_HANDLE_CONFIGS.map((config) => {
+        const baseStyle = config.variant === "corner" ? cornerHandleStyle : edgeHandleStyle;
+        const positionStyle = config.variant === "corner" ? cornerPositions[config.key] : edgePositions[config.key];
+        const combinedStyle = { ...baseStyle, ...positionStyle };
+        const datasetProps =
+          config.variant === "corner" ? { "data-resize-corner": config.key } : { "data-resize-edge": config.key };
+        return (
+          <div
+            key={config.key}
+            role="presentation"
+            aria-hidden="true"
+            style={combinedStyle}
+            {...datasetProps}
+            data-layer-id={layerId}
+            onPointerDown={(event) => onPointerDown(config, event)}
+          />
+        );
+      })}
+    </>
+  );
+};