react-panel-layout 0.5.2 → 0.6.0

package/src/types.ts

@@ -0,0 +1,323 @@
+/**
+ * @file Unified public type definitions for the panel layout system.
+ * Single source of truth for grid, window, and drawer related types.
+ */
+import * as React from "react";
+
+// ============================================================================
+// Window / Popup / Drawer types (formerly src/modules/types.ts)
+// ============================================================================
+
+// Basic coordinates used by overlays and anchors
+export type Position = {
+  x: number;
+  y: number;
+};
+
+// Offset value used when positioning floating windows
+export type WindowOffset = number | string;
+
+// CSS-like position offsets for floating windows
+export type WindowPosition = {
+  top?: WindowOffset;
+  right?: WindowOffset;
+  bottom?: WindowOffset;
+  left?: WindowOffset;
+};
+
+// Explicit dimensions for floating windows
+export type WindowSize = {
+  width: number;
+  height: number;
+};
+
+// Complete bounds definition for floating windows
+export type WindowBounds = {
+  position?: WindowPosition;
+  size: WindowSize;
+};
+
+// Size constraints that can be applied to floating/drawer surfaces
+export type WindowConstraints = {
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  maxHeight?: number;
+};
+
+// Browser popup window features
+export type PopupWindowFeatures = {
+  toolbar?: boolean;
+  menubar?: boolean;
+  location?: boolean;
+  status?: boolean;
+  resizable?: boolean;
+  scrollbars?: boolean;
+};
+
+// Extra configuration for browser popup windows
+export type PopupWindowOptions = {
+  name?: string;
+  features?: PopupWindowFeatures;
+  focus?: boolean;
+  closeOnUnmount?: boolean;
+  createWindow?: (config: PopupWindowFactoryConfig) => Window | null;
+};
+
+// Parameters for creating popup windows via a custom factory
+export type PopupWindowFactoryConfig = {
+  name: string;
+  features: string;
+  bounds: WindowBounds;
+};
+
+// Display mode for floating windows
+export type FloatingWindowMode = "embedded" | "popup";
+
+// Floating window header configuration
+export type FloatingHeaderConfig = {
+  /** Header title text */
+  title?: string;
+  /** Show close button (requires onClose callback) */
+  showCloseButton?: boolean;
+};
+
+// Unified configuration for floating windows with controlled/uncontrolled support
+export type FloatingBehavior = {
+  // === Position (controlled/uncontrolled) ===
+  /** Controlled position - when defined, component uses this value directly */
+  position?: WindowPosition;
+  /** Initial position for uncontrolled mode */
+  defaultPosition?: WindowPosition;
+
+  // === Size (controlled/uncontrolled) ===
+  /** Controlled size - when defined, component uses this value directly */
+  size?: WindowSize;
+  /** Initial size for uncontrolled mode */
+  defaultSize?: WindowSize;
+
+  // === Stacking ===
+  /** Z-index for stacking order */
+  zIndex?: number;
+
+  // === Interaction ===
+  /** Enable drag-to-move functionality */
+  draggable?: boolean;
+  /** Enable resize handles */
+  resizable?: boolean;
+  /** Size constraints for resizing */
+  constraints?: WindowConstraints;
+
+  // === Callbacks ===
+  /** Called when position changes (drag/move) */
+  onMove?: (position: WindowPosition) => void;
+  /** Called when size changes (resize) */
+  onResize?: (size: WindowSize) => void;
+  /** Called when close button is clicked */
+  onClose?: () => void;
+
+  // === Chrome (like DrawerBehavior) ===
+  /**
+   * Use built-in chrome (FloatingPanelFrame with border, shadow, background).
+   * When true and header is provided, header auto-enables drag handle.
+   * Defaults to false.
+   */
+  chrome?: boolean;
+  /**
+   * Header configuration (renders header when provided).
+   * When chrome is true and header is provided, header becomes the drag handle.
+   */
+  header?: FloatingHeaderConfig;
+  /** Accessible label when header.title is not provided */
+  ariaLabel?: string;
+
+  // === Transitions ===
+  /**
+   * Transition mode for position/size changes.
+   * - "css" uses CSS transitions.
+   * - "none" disables transitions.
+   */
+  transitionMode?: "css" | "none";
+  /** Override transition duration (e.g., "200ms") */
+  transitionDuration?: string;
+  /** Override transition easing (e.g., "ease-out") */
+  transitionEasing?: string;
+
+  // === Display mode ===
+  /** Display mode: "embedded" (default) or "popup" (browser window) */
+  mode?: FloatingWindowMode;
+  /** Popup-specific options when mode is "popup" */
+  popup?: PopupWindowOptions;
+};
+
+// Pivot item definition for content switching
+export type PivotBehaviorItem = {
+  /** Unique identifier for this content item */
+  id: string;
+  /** Human-readable label (optional) */
+  label?: string;
+  /** The actual content to render when this item is active */
+  content: React.ReactNode;
+  /** Whether this item can be selected */
+  disabled?: boolean;
+  /**
+   * Enable content caching to preserve React component state across re-renders.
+   * When disabled (default), content is re-created on each render.
+   * @default false
+   */
+  cache?: boolean;
+};
+
+// Pivot behavior configuration for content switching
+export type PivotBehavior = {
+  /** Array of content items to switch between */
+  items: PivotBehaviorItem[];
+  /** Currently active item ID (controlled mode) */
+  activeId?: string;
+  /** Default active item ID (uncontrolled mode) */
+  defaultActiveId?: string;
+  /** Callback when active item changes */
+  onActiveChange?: (id: string) => void;
+  /**
+   * Transition mode for content switching.
+   * - "css" (default) uses CSS transitions via design tokens.
+   * - "none" disables transitions (uses React.Activity for memory optimization).
+   */
+  transitionMode?: "css" | "none";
+};
+
+// Drawer behavior configuration for mobile-friendly slide-in panels
+export type DrawerBehavior = {
+  /** Optional controlled state */
+  defaultOpen?: boolean;
+  open?: boolean;
+  /** Whether clicking backdrop dismisses the drawer */
+  dismissible?: boolean;
+  /**
+   * Anchor edge for the drawer.
+   * - "left", "right", "top", "bottom"
+   * - When not specified, inferred from position prop
+   */
+  anchor?: "left" | "right" | "top" | "bottom";
+  /**
+   * Transition mode for drawer visibility.
+   * - "css" (default) uses CSS transform transitions.
+   * - "none" disables transitions.
+   */
+  transitionMode?: "css" | "none";
+  /** Override transform transition duration (e.g., "240ms"). */
+  transitionDuration?: string;
+  /** Override transform transition easing (e.g., "cubic-bezier(0.22,1,0.36,1)"). */
+  transitionEasing?: string;
+  onStateChange?: (open: boolean) => void;
+  /** Use the built-in chrome (background, header padding). Defaults to true. */
+  chrome?: boolean;
+  /**
+   * Render the drawer relative to its parent container instead of the viewport.
+   * Defaults to false (fixed to viewport).
+   */
+  inline?: boolean;
+  /**
+   * Accessible label when header.title is not provided or when rendering without a header.
+   */
+  ariaLabel?: string;
+  header?: {
+    title?: string;
+    showCloseButton?: boolean;
+  };
+};
+
+// ============================================================================
+// Grid / Panel layout types (formerly src/panel-system/types.ts)
+// ============================================================================
+
+// Grid track definition with optional resize capability
+export type GridTrack = {
+  size: string;
+  resizable?: boolean;
+  minSize?: number;
+  maxSize?: number;
+};
+
+// Grid-based layout configuration for the editor
+export type PanelLayoutConfig = {
+  areas: string[][];
+  rows: GridTrack[];
+  columns: GridTrack[];
+  gap?: string;
+  style?: React.CSSProperties;
+};
+
+// Layer positioning mode
+export type LayerPositionMode = "grid" | "absolute" | "relative" | "fixed";
+
+// Layer definition for panel system
+export type LayerDefinition = {
+  id: string;
+  component: React.ReactNode;
+  visible?: boolean;
+
+  // Grid positioning
+  gridArea?: string;
+  gridRow?: string;
+  gridColumn?: string;
+
+  // Absolute/Fixed/Relative positioning
+  /**
+   * Positioning mode: when omitted, derived automatically.
+   * If `floating` is present, behaves as absolute (embedded) or relative (popup).
+   */
+  positionMode?: LayerPositionMode;
+  /**
+   * Position offsets for non-floating layers (drawer, absolute positioned).
+   * For floating layers, use `floating.position` or `floating.defaultPosition` instead.
+   */
+  position?: WindowPosition;
+
+  /**
+   * Stacking order for non-floating layers.
+   * For floating layers, use `floating.zIndex` instead.
+   */
+  zIndex?: number;
+  /**
+   * Width for non-floating layers.
+   * For floating layers, use `floating.size` or `floating.defaultSize` instead.
+   */
+  width?: string | number;
+  /**
+   * Height for non-floating layers.
+   * For floating layers, use `floating.size` or `floating.defaultSize` instead.
+   */
+  height?: string | number;
+  pointerEvents?: boolean | "auto" | "none";
+  /** Optional backdrop style (used by DrawerBehaviour) */
+  backdropStyle?: React.CSSProperties;
+
+  // Behaviors
+  drawer?: DrawerBehavior;
+  /** Floating window behavior configuration */
+  floating?: FloatingBehavior;
+  pivot?: PivotBehavior;
+
+  // Styling
+  style?: React.CSSProperties;
+
+  /**
+   * When true, enables scrolling within this panel (overflow: auto).
+   * When false or omitted, content overflow is hidden (default behavior).
+   */
+  scrollable?: boolean;
+
+  /**
+   * Enable content caching to preserve React component state across re-renders.
+   * When disabled (default), content is re-created on each render.
+   * @default false
+   */
+  cache?: boolean;
+};
+
+// Props for top-level layout components
+export type PanelLayoutProps = {
+  config: PanelLayoutConfig;
+  layers: LayerDefinition[];
+};

package/src/utils/CSSMatrix.ts

@@ -0,0 +1,321 @@
+/**
+ * @file CSSMatrix - Immutable 4x4 matrix for CSS 3D transforms
+ *
+ * Each operation returns a new instance, preserving the original matrix.
+ *
+ * @example
+ * const mtrx = matrix().translate(0, 10);
+ * const a = mtrx.rotateX(Math.PI / 2);
+ * const b = mtrx.rotateY(Math.PI);
+ * // a and b are independent transformations from mtrx
+ */
+
+/**
+ * Matrix type with transformation methods
+ */
+export type CSSMatrix = {
+  readonly translate: (x?: number, y?: number, z?: number) => CSSMatrix;
+  readonly translate3d: (x: number, y: number, z: number) => CSSMatrix;
+  readonly translateX: (x: number) => CSSMatrix;
+  readonly translateY: (y: number) => CSSMatrix;
+  readonly translateZ: (z: number) => CSSMatrix;
+  readonly scale: (x?: number, y?: number, z?: number) => CSSMatrix;
+  readonly scale3d: (x: number, y: number, z: number) => CSSMatrix;
+  readonly scaleX: (x: number) => CSSMatrix;
+  readonly scaleY: (y: number) => CSSMatrix;
+  readonly scaleZ: (z: number) => CSSMatrix;
+  readonly rotateX: (angle: number) => CSSMatrix;
+  readonly rotateY: (angle: number) => CSSMatrix;
+  readonly rotateZ: (angle: number) => CSSMatrix;
+  readonly rotate: (angle: number, x: number, y: number, z: number) => CSSMatrix;
+  readonly rotate3d: (x: number, y: number, z: number, angle: number) => CSSMatrix;
+  readonly skew: (angleX?: number, angleY?: number) => CSSMatrix;
+  readonly skewX: (angle: number) => CSSMatrix;
+  readonly skewY: (angle: number) => CSSMatrix;
+  readonly perspective: (distance: number) => CSSMatrix;
+  readonly toCSS: () => string;
+  readonly toArray: () => readonly number[];
+  readonly toString: () => string;
+};
+
+/**
+ * Multiply two 4x4 matrices (a * b)
+ * Matrices are in column-major order
+ */
+const multiplyMatrices = (a: readonly number[], b: readonly number[]): number[] => {
+  const result = new Array(16);
+
+  for (let col = 0; col < 4; col++) {
+    for (let row = 0; row < 4; row++) {
+      result[col * 4 + row] =
+        a[0 * 4 + row] * b[col * 4 + 0] +
+        a[1 * 4 + row] * b[col * 4 + 1] +
+        a[2 * 4 + row] * b[col * 4 + 2] +
+        a[3 * 4 + row] * b[col * 4 + 3];
+    }
+  }
+
+  return result;
+};
+
+/**
+ * Create a CSSMatrix object from raw values
+ * Values are stored in column-major order (OpenGL/CSS convention)
+ */
+const createMatrix = (values: readonly number[]): CSSMatrix => {
+  if (values.length !== 16) {
+    throw new Error('Matrix must have exactly 16 values');
+  }
+
+  // Freeze the values to ensure immutability
+  const m = Object.freeze([...values]);
+
+  /**
+   * Helper to create a new matrix by multiplying with a transform matrix
+   */
+  const applyTransform = (transformValues: number[]): CSSMatrix => {
+    const result = multiplyMatrices(m, transformValues);
+    return createMatrix(result);
+  };
+
+  return Object.freeze({
+    translate: (x = 0, y = 0, z = 0) => {
+      return applyTransform([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        x, y, z, 1,
+      ]);
+    },
+
+    translate3d: (x, y, z) => {
+      return applyTransform([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        x, y, z, 1,
+      ]);
+    },
+
+    translateX: (x) => {
+      return applyTransform([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        x, 0, 0, 1,
+      ]);
+    },
+
+    translateY: (y) => {
+      return applyTransform([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        0, y, 0, 1,
+      ]);
+    },
+
+    translateZ: (z) => {
+      return applyTransform([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        0, 0, z, 1,
+      ]);
+    },
+
+    scale: (x = 1, y = 1, z = 1) => {
+      return applyTransform([
+        x, 0, 0, 0,
+        0, y, 0, 0,
+        0, 0, z, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    scale3d: (x, y, z) => {
+      return applyTransform([
+        x, 0, 0, 0,
+        0, y, 0, 0,
+        0, 0, z, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    scaleX: (x) => {
+      return applyTransform([
+        x, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    scaleY: (y) => {
+      return applyTransform([
+        1, 0, 0, 0,
+        0, y, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    scaleZ: (z) => {
+      return applyTransform([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, z, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    rotateX: (angle) => {
+      const c = Math.cos(angle);
+      const s = Math.sin(angle);
+      return applyTransform([
+        1, 0, 0, 0,
+        0, c, s, 0,
+        0, -s, c, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    rotateY: (angle) => {
+      const c = Math.cos(angle);
+      const s = Math.sin(angle);
+      return applyTransform([
+        c, 0, -s, 0,
+        0, 1, 0, 0,
+        s, 0, c, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    rotateZ: (angle) => {
+      const c = Math.cos(angle);
+      const s = Math.sin(angle);
+      return applyTransform([
+        c, s, 0, 0,
+        -s, c, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    rotate: (angle, x, y, z) => {
+      // Normalize the axis
+      const len = Math.sqrt(x * x + y * y + z * z);
+      if (len === 0) {
+        return createMatrix(m);
+      }
+
+      x /= len;
+      y /= len;
+      z /= len;
+
+      const c = Math.cos(angle);
+      const s = Math.sin(angle);
+      const t = 1 - c;
+
+      return applyTransform([
+        t * x * x + c,     t * x * y + s * z, t * x * z - s * y, 0,
+        t * x * y - s * z, t * y * y + c,     t * y * z + s * x, 0,
+        t * x * z + s * y, t * y * z - s * x, t * z * z + c,     0,
+        0,                 0,                 0,                 1,
+      ]);
+    },
+
+    rotate3d: (x, y, z, angle) => {
+      // Normalize the axis
+      const len = Math.sqrt(x * x + y * y + z * z);
+      if (len === 0) {
+        return createMatrix(m);
+      }
+
+      x /= len;
+      y /= len;
+      z /= len;
+
+      const c = Math.cos(angle);
+      const s = Math.sin(angle);
+      const t = 1 - c;
+
+      return applyTransform([
+        t * x * x + c,     t * x * y + s * z, t * x * z - s * y, 0,
+        t * x * y - s * z, t * y * y + c,     t * y * z + s * x, 0,
+        t * x * z + s * y, t * y * z - s * x, t * z * z + c,     0,
+        0,                 0,                 0,                 1,
+      ]);
+    },
+
+    skew: (angleX = 0, angleY = 0) => {
+      const tanX = Math.tan(angleX);
+      const tanY = Math.tan(angleY);
+      return applyTransform([
+        1, tanY, 0, 0,
+        tanX, 1, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    skewX: (angle) => {
+      const tanX = Math.tan(angle);
+      return applyTransform([
+        1, 0, 0, 0,
+        tanX, 1, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    skewY: (angle) => {
+      const tanY = Math.tan(angle);
+      return applyTransform([
+        1, tanY, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, 0,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    perspective: (distance) => {
+      if (distance === 0) {
+        throw new Error('Perspective distance cannot be zero');
+      }
+      return applyTransform([
+        1, 0, 0, 0,
+        0, 1, 0, 0,
+        0, 0, 1, -1 / distance,
+        0, 0, 0, 1,
+      ]);
+    },
+
+    toCSS: () => {
+      return `matrix3d(${m.join(', ')})`;
+    },
+
+    toArray: () => m,
+
+    toString: () => {
+      return [
+        `[${m[0]}, ${m[4]}, ${m[8]}, ${m[12]}]`,
+        `[${m[1]}, ${m[5]}, ${m[9]}, ${m[13]}]`,
+        `[${m[2]}, ${m[6]}, ${m[10]}, ${m[14]}]`,
+        `[${m[3]}, ${m[7]}, ${m[11]}, ${m[15]}]`,
+      ].join('\n');
+    },
+  });
+};
+
+/**
+ * Factory function to create a new identity matrix
+ */
+export const matrix = (): CSSMatrix => {
+  return createMatrix([
+    1, 0, 0, 0,
+    0, 1, 0, 0,
+    0, 0, 1, 0,
+    0, 0, 0, 1,
+  ]);
+};

package/src/utils/css.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Generic CSS parsing and measurement utilities.
+ */
+
+export type ParsedGap = {
+  rowGap: number;
+  columnGap: number;
+};
+
+/**
+ * Parses a CSS gap value string into row and column gap numbers.
+ * Supports single value (applied to both) or two values (row column).
+ * Only handles px units; other units return 0.
+ */
+export const parseGapValue = (gapValue?: string): ParsedGap => {
+  if (!gapValue) {
+    return { rowGap: 0, columnGap: 0 };
+  }
+
+  const tokens = gapValue
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter(Boolean);
+
+  const parseToken = (token: string): number => {
+    const match = token.match(/^(-?\d+(?:\.\d+)?)px$/);
+    if (!match) {
+      return 0;
+    }
+    return Number.parseFloat(match[1]);
+  };
+
+  if (tokens.length === 1) {
+    const parsed = parseToken(tokens[0]);
+    return { rowGap: parsed, columnGap: parsed };
+  }
+
+  return {
+    rowGap: parseToken(tokens[0]),
+    columnGap: parseToken(tokens[1]),
+  };
+};
+
+export type GridDirection = "col" | "row";
+
+/**
+ * Measures actual rendered grid track sizes from computed style.
+ * Returns pixel values parsed from gridTemplateColumns or gridTemplateRows.
+ */
+export const measureGridTrackSizes = (
+  containerEl: HTMLElement | null,
+  direction: GridDirection,
+): number[] => {
+  if (!containerEl) {
+    return [];
+  }
+  const style = getComputedStyle(containerEl);
+  const template = direction === "col" ? style.gridTemplateColumns : style.gridTemplateRows;
+
+  // Computed style returns resolved pixel values like "370px 500px"
+  return template
+    .split(/\s+/)
+    .map((s) => parseFloat(s))
+    .filter((n) => !Number.isNaN(n));
+};