react-panel-layout 0.5.2 → 0.6.1

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

package/src/utils/dialogUtils.ts

@@ -0,0 +1,43 @@
+/**
+ * @file Dialog positioning utilities
+ */
+
+export type ViewportInfo = {
+  width: number;
+  height: number;
+};
+
+/**
+ * Get viewport dimensions
+ */
+export const getViewportInfo = (): ViewportInfo => {
+  if (typeof window === "undefined") {
+    return { width: 0, height: 0 };
+  }
+
+  return {
+    width: window.innerWidth,
+    height: window.innerHeight,
+  };
+};
+
+/**
+ * Calculate context menu position to keep it within viewport
+ */
+export const calculateContextMenuPosition = (
+  anchorX: number,
+  anchorY: number,
+  menuWidth: number,
+  menuHeight: number,
+  viewport: ViewportInfo,
+): { x: number; y: number } => {
+  // Adjust horizontal position if menu would overflow
+  const x =
+    anchorX + menuWidth > viewport.width ? Math.max(0, viewport.width - menuWidth) : anchorX;
+
+  // Adjust vertical position if menu would overflow
+  const y =
+    anchorY + menuHeight > viewport.height ? Math.max(0, viewport.height - menuHeight) : anchorY;
+
+  return { x, y };
+};

package/src/utils/math.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Primitive math helpers shared across modules.
+ */
+
+export const clampNumber = (
+  value: number,
+  min: number = Number.NEGATIVE_INFINITY,
+  max: number = Number.POSITIVE_INFINITY,
+): number => {
+  return Math.min(Math.max(value, min), max);
+};
+
+export const toFiniteNumberOr = (value: number | undefined, fallback: number): number => {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  return value;
+};

package/src/utils/polyfills/createDialogPolyfill.ts

@@ -0,0 +1,18 @@
+/**
+ * @file Dialog polyfill for browsers that don't support <dialog> element natively
+ */
+
+/**
+ * Ensure dialog polyfill is loaded if needed
+ * This is a placeholder - in production you might want to use a real polyfill like dialog-polyfill
+ */
+export const ensureDialogPolyfill = (): void => {
+  // Check if browser supports <dialog> element
+  if (typeof window === "undefined") {
+    return;
+  }
+
+  // Modern browsers already support dialog element
+  // If you need to support older browsers, you can load a polyfill here
+  // For now, we assume modern browser support
+};

package/src/utils/typedActions.ts

@@ -0,0 +1,103 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- Generic action helpers rely on 'any' to avoid over-constraining payload creators */
+/**
+ * @file Utilities for defining typed action creators and reducer handler maps without external dependencies.
+ */
+
+export type AnyAction = { type: string };
+
+export type AnyActionCreator = {
+  (...args: any[]): AnyAction;
+  readonly type: string;
+};
+
+type PayloadCreator = (...args: any[]) => any;
+
+type ActionFromPayload<Type extends string, Creator extends PayloadCreator> =
+  ReturnType<Creator> extends undefined | void
+    ? { type: Type }
+    : { type: Type; payload: Exclude<ReturnType<Creator>, undefined> };
+
+/**
+ * Creates a typed action creator with an attached literal `type` property.
+ */
+export function createAction<Type extends string>(type: Type): (() => { type: Type }) & { readonly type: Type };
+export function createAction<Type extends string, Creator extends PayloadCreator>(
+  type: Type,
+  payloadCreator: Creator,
+): ((...args: Parameters<Creator>) => ActionFromPayload<Type, Creator>) & { readonly type: Type };
+export function createAction<Type extends string, Creator extends PayloadCreator>(
+  type: Type,
+  payloadCreator?: Creator,
+) {
+  if (!payloadCreator) {
+    const actionCreator = (() => ({ type }) as const) as (() => { type: Type }) & { readonly type: Type };
+    Object.defineProperty(actionCreator, "type", {
+      value: type,
+      writable: false,
+      enumerable: true,
+    });
+    return actionCreator;
+  }
+  const actionCreator = ((...args: Parameters<Creator>) => {
+    const payload = payloadCreator(...args);
+    if (typeof payload === "undefined") {
+      return { type } as const;
+    }
+    return { type, payload } as const;
+  }) as ((...args: Parameters<Creator>) => ActionFromPayload<Type, Creator>) & { readonly type: Type };
+  Object.defineProperty(actionCreator, "type", {
+    value: type,
+    writable: false,
+    enumerable: true,
+  });
+  return actionCreator;
+}
+
+export type ActionCreatorsMap = Record<string, AnyActionCreator>;
+
+export type ActionUnion<Creators extends ActionCreatorsMap> = ReturnType<Creators[keyof Creators]>;
+
+export type CaseReducer<State, Action extends AnyAction, Extra> = (state: State, action: Action, extra: Extra) => State;
+
+export type BoundActionCreators<Creators extends ActionCreatorsMap> = {
+  [Key in keyof Creators]: (...args: Parameters<Creators[Key]>) => ReturnType<Creators[Key]>;
+};
+
+export const bindActionCreators = <Creators extends ActionCreatorsMap>(
+  creators: Creators,
+  dispatch: (action: ActionUnion<Creators>) => unknown,
+): BoundActionCreators<Creators> => {
+  const bound = {} as BoundActionCreators<Creators>;
+  (Object.keys(creators) as Array<keyof Creators>).forEach((key) => {
+    const creator = creators[key];
+    bound[key] = ((...args: Parameters<typeof creator>) => {
+      const action = creator(...args);
+      dispatch(action as ActionUnion<Creators>);
+      return action;
+    }) as BoundActionCreators<Creators>[keyof Creators];
+  });
+  return bound;
+};
+
+export const createActionHandlerMap = <State, Creators extends ActionCreatorsMap, Extra = undefined>(
+  creators: Creators,
+  handlers: {
+    [Key in keyof Creators]?: CaseReducer<State, ReturnType<Creators[Key]>, Extra>;
+  },
+): Record<string, CaseReducer<State, ReturnType<Creators[keyof Creators]>, Extra>> => {
+  const map: Record<string, CaseReducer<State, ReturnType<Creators[keyof Creators]>, Extra>> = {};
+
+  (Object.keys(handlers) as Array<keyof Creators>).forEach((key) => {
+    const handler = handlers[key];
+    if (!handler) {
+      return;
+    }
+    const creator = creators[key];
+    if (!creator) {
+      throw new Error(`Missing action creator for key "${String(key)}"`);
+    }
+    map[creator.type] = handler as CaseReducer<State, ReturnType<Creators[keyof Creators]>, Extra>;
+  });
+
+  return map;
+};

package/src/vite-env.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file Vite environment type declarations
+ */
+/// <reference types="vite/client" />
+
+declare const __APP_VERSION__: string;

package/src/window/index.ts

@@ -0,0 +1,69 @@
+/**
+ * @file Window entry point - Floating window and drawer components
+ * @packageDocumentation
+ *
+ * This is a subpath export entry point for `react-panel-layout/window`.
+ *
+ * ## Overview
+ * Window provides floating panels, drawers, and dialog overlays for modal
+ * and non-modal UI patterns. Supports draggable windows, slide-in drawers,
+ * and popup portals.
+ *
+ * ## Installation
+ * ```ts
+ * import { Drawer, FloatingWindow, useDrawerState } from "react-panel-layout/window";
+ * ```
+ *
+ * ## Drawer Usage
+ * ```tsx
+ * function App() {
+ *   const [isOpen, setIsOpen] = useState(false);
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => setIsOpen(true)}>Open Drawer</button>
+ *       <Drawer
+ *         id="settings"
+ *         config={{ anchor: 'right', header: { title: 'Settings' } }}
+ *         isOpen={isOpen}
+ *         onClose={() => setIsOpen(false)}
+ *       >
+ *         <SettingsPanel />
+ *       </Drawer>
+ *     </>
+ *   );
+ * }
+ * ```
+ *
+ * ## Floating Window Usage
+ * ```tsx
+ * <FloatingWindow
+ *   id="inspector"
+ *   config={{
+ *     draggable: true,
+ *     chrome: true,
+ *     header: { title: 'Inspector', showCloseButton: true },
+ *   }}
+ *   onClose={handleClose}
+ * >
+ *   <InspectorContent />
+ * </FloatingWindow>
+ * ```
+ */
+
+// Components
+export { FloatingWindow } from "../components/window/FloatingWindow.js";
+export { Drawer } from "../components/window/Drawer.js";
+export { DrawerLayers } from "../components/window/DrawerLayers.js";
+export { DialogOverlay } from "../components/window/DialogOverlay.js";
+export { PopupLayerPortal } from "../components/window/PopupLayerPortal.js";
+export { SwipeSafeZone } from "../components/gesture/SwipeSafeZone.js";
+
+// Hooks
+export { useFloatingState } from "../modules/window/useFloatingState.js";
+export { useDrawerState } from "../modules/window/useDrawerState.js";
+
+// Types
+export type { FloatingWindowProps } from "../components/window/FloatingWindow.js";
+export type { DrawerProps } from "../components/window/Drawer.js";
+export type { SwipeSafeZoneProps } from "../components/gesture/SwipeSafeZone.js";