react-panel-layout 0.5.2 → 0.6.0

package/src/hooks/useCSSMatrix.spec.ts

@@ -0,0 +1,214 @@
+/**
+ * @file Tests for useCSSMatrix hook
+ */
+
+import { renderHook } from '@testing-library/react';
+import { useCSSMatrix, useCSSMatrixObject, type MatrixOperation } from './useCSSMatrix';
+import { matrix } from '../utils/CSSMatrix';
+
+describe('useCSSMatrix', () => {
+  it('should return identity matrix CSS for empty operations', () => {
+    const { result } = renderHook(() => useCSSMatrix([]));
+    expect(result.current).toBe(matrix().toCSS());
+  });
+
+  it('should apply single translation', () => {
+    const operations: MatrixOperation[] = [['translate', 100, 50]];
+    const { result } = renderHook(() => useCSSMatrix(operations));
+
+    const expected = matrix().translate(100, 50).toCSS();
+    expect(result.current).toBe(expected);
+  });
+
+  it('should apply multiple operations in sequence', () => {
+    const operations: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', Math.PI / 4],
+      ['scale', 2, 2],
+    ];
+    const { result } = renderHook(() => useCSSMatrix(operations));
+
+    const expected = matrix()
+      .translate(100, 50)
+      .rotateZ(Math.PI / 4)
+      .scale(2, 2)
+      .toCSS();
+    expect(result.current).toBe(expected);
+  });
+
+  it('should handle 3D operations', () => {
+    const operations: MatrixOperation[] = [
+      ['perspective', 1000],
+      ['translate3d', 0, 0, -500],
+      ['rotateY', Math.PI / 6],
+    ];
+    const { result } = renderHook(() => useCSSMatrix(operations));
+
+    const expected = matrix()
+      .perspective(1000)
+      .translate3d(0, 0, -500)
+      .rotateY(Math.PI / 6)
+      .toCSS();
+    expect(result.current).toBe(expected);
+  });
+
+  it('should efficiently update when operations change at the end', () => {
+    const operations1: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', 0],
+    ];
+    const operations2: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', Math.PI / 4],
+    ];
+
+    const { result, rerender } = renderHook(
+      ({ ops }) => useCSSMatrix(ops),
+      { initialProps: { ops: operations1 } }
+    );
+
+    const result1 = result.current;
+
+    // Change only the last operation
+    rerender({ ops: operations2 });
+    const result2 = result.current;
+
+    // Results should be different
+    expect(result1).not.toBe(result2);
+
+    // Result should match expected
+    const expected = matrix()
+      .translate(100, 50)
+      .rotateZ(Math.PI / 4)
+      .toCSS();
+    expect(result2).toBe(expected);
+  });
+
+  it('should efficiently update when operations change at the beginning', () => {
+    const operations1: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', Math.PI / 4],
+    ];
+    const operations2: MatrixOperation[] = [
+      ['translate', 200, 100],
+      ['rotateZ', Math.PI / 4],
+    ];
+
+    const { result, rerender } = renderHook(
+      ({ ops }) => useCSSMatrix(ops),
+      { initialProps: { ops: operations1 } }
+    );
+
+    const result1 = result.current;
+
+    // Change the first operation
+    rerender({ ops: operations2 });
+    const result2 = result.current;
+
+    expect(result1).not.toBe(result2);
+
+    const expected = matrix()
+      .translate(200, 100)
+      .rotateZ(Math.PI / 4)
+      .toCSS();
+    expect(result2).toBe(expected);
+  });
+
+  it('should handle adding operations', () => {
+    const operations1: MatrixOperation[] = [
+      ['translate', 100, 50],
+    ];
+    const operations2: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', Math.PI / 4],
+    ];
+
+    const { result, rerender } = renderHook(
+      ({ ops }) => useCSSMatrix(ops),
+      { initialProps: { ops: operations1 } }
+    );
+
+    rerender({ ops: operations2 });
+
+    const expected = matrix()
+      .translate(100, 50)
+      .rotateZ(Math.PI / 4)
+      .toCSS();
+    expect(result.current).toBe(expected);
+  });
+
+  it('should handle removing operations', () => {
+    const operations1: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', Math.PI / 4],
+      ['scale', 2, 2],
+    ];
+    const operations2: MatrixOperation[] = [
+      ['translate', 100, 50],
+    ];
+
+    const { result, rerender } = renderHook(
+      ({ ops }) => useCSSMatrix(ops),
+      { initialProps: { ops: operations1 } }
+    );
+
+    rerender({ ops: operations2 });
+
+    const expected = matrix().translate(100, 50).toCSS();
+    expect(result.current).toBe(expected);
+  });
+
+  it('should not recompute when operations array reference changes but content is same', () => {
+    const operations1: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', Math.PI / 4],
+    ];
+    const operations2: MatrixOperation[] = [
+      ['translate', 100, 50],
+      ['rotateZ', Math.PI / 4],
+    ];
+
+    const { result, rerender } = renderHook(
+      ({ ops }) => useCSSMatrix(ops),
+      { initialProps: { ops: operations1 } }
+    );
+
+    const result1 = result.current;
+
+    // Different array reference, same content
+    rerender({ ops: operations2 });
+    const result2 = result.current;
+
+    // Should return same result due to memoization
+    expect(result1).toBe(result2);
+  });
+});
+
+describe('useCSSMatrixObject', () => {
+  it('should return CSSMatrix object', () => {
+    const operations: MatrixOperation[] = [['translate', 100, 50]];
+    const { result } = renderHook(() => useCSSMatrixObject(operations));
+
+    expect(result.current).toBeDefined();
+    expect(typeof result.current.toCSS).toBe('function');
+    expect(typeof result.current.toArray).toBe('function');
+  });
+
+  it('should return correct matrix values', () => {
+    const operations: MatrixOperation[] = [['translate', 100, 50]];
+    const { result } = renderHook(() => useCSSMatrixObject(operations));
+
+    const expected = matrix().translate(100, 50);
+    expect(result.current.toCSS()).toBe(expected.toCSS());
+  });
+
+  it('should allow chaining additional operations', () => {
+    const operations: MatrixOperation[] = [['translate', 100, 50]];
+    const { result } = renderHook(() => useCSSMatrixObject(operations));
+
+    const final = result.current.rotateZ(Math.PI / 4);
+    const expected = matrix().translate(100, 50).rotateZ(Math.PI / 4);
+
+    expect(final.toCSS()).toBe(expected.toCSS());
+  });
+});

package/src/hooks/useCSSMatrix.ts

@@ -0,0 +1,262 @@
+/**
+ * @file useCSSMatrix - Efficient CSS matrix transformation hook with incremental updates
+ */
+
+import { useRef, useMemo } from 'react';
+import { matrix, type CSSMatrix } from '../utils/CSSMatrix';
+
+/**
+ * Matrix operation types
+ */
+export type MatrixOperation =
+  | ['translate', number?, number?, number?]
+  | ['translate3d', number, number, number]
+  | ['translateX', number]
+  | ['translateY', number]
+  | ['translateZ', number]
+  | ['scale', number?, number?, number?]
+  | ['scale3d', number, number, number]
+  | ['scaleX', number]
+  | ['scaleY', number]
+  | ['scaleZ', number]
+  | ['rotateX', number]
+  | ['rotateY', number]
+  | ['rotateZ', number]
+  | ['rotate', number, number, number, number]
+  | ['rotate3d', number, number, number, number]
+  | ['skew', number?, number?]
+  | ['skewX', number]
+  | ['skewY', number]
+  | ['perspective', number];
+
+/**
+ * Cache entry for computed matrices
+ */
+type CacheEntry = {
+  operation: MatrixOperation;
+  result: CSSMatrix;
+};
+
+/**
+ * Apply a single operation to a matrix
+ */
+const applyOperation = (m: CSSMatrix, op: MatrixOperation): CSSMatrix => {
+  const [name, ...params] = op;
+
+  switch (name) {
+    case 'translate':
+      return m.translate(params[0], params[1], params[2]);
+    case 'translate3d':
+      return m.translate3d(params[0]!, params[1]!, params[2]!);
+    case 'translateX':
+      return m.translateX(params[0]!);
+    case 'translateY':
+      return m.translateY(params[0]!);
+    case 'translateZ':
+      return m.translateZ(params[0]!);
+    case 'scale':
+      return m.scale(params[0], params[1], params[2]);
+    case 'scale3d':
+      return m.scale3d(params[0]!, params[1]!, params[2]!);
+    case 'scaleX':
+      return m.scaleX(params[0]!);
+    case 'scaleY':
+      return m.scaleY(params[0]!);
+    case 'scaleZ':
+      return m.scaleZ(params[0]!);
+    case 'rotateX':
+      return m.rotateX(params[0]!);
+    case 'rotateY':
+      return m.rotateY(params[0]!);
+    case 'rotateZ':
+      return m.rotateZ(params[0]!);
+    case 'rotate':
+      return m.rotate(params[0]!, params[1]!, params[2]!, params[3]!);
+    case 'rotate3d':
+      return m.rotate3d(params[0]!, params[1]!, params[2]!, params[3]!);
+    case 'skew':
+      return m.skew(params[0], params[1]);
+    case 'skewX':
+      return m.skewX(params[0]!);
+    case 'skewY':
+      return m.skewY(params[0]!);
+    case 'perspective':
+      return m.perspective(params[0]!);
+    default:
+      return m;
+  }
+};
+
+/**
+ * Compare two operations for equality
+ */
+const operationsEqual = (a: MatrixOperation, b: MatrixOperation): boolean => {
+  if (a.length !== b.length) {
+    return false;
+  }
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] !== b[i]) {
+      return false;
+    }
+  }
+  return true;
+};
+
+/**
+ * Find the first index where operations differ
+ */
+const findDiffIndex = (
+  prev: MatrixOperation[],
+  current: MatrixOperation[]
+): number => {
+  const minLength = Math.min(prev.length, current.length);
+  for (let i = 0; i < minLength; i++) {
+    if (!operationsEqual(prev[i]!, current[i]!)) {
+      return i;
+    }
+  }
+  // If all compared operations are equal, check length difference
+  if (prev.length !== current.length) {
+    return minLength;
+  }
+  return -1; // No difference
+};
+
+/**
+ * Efficient CSS matrix transformation hook with incremental updates
+ *
+ * Constructs a computation tree and only recalculates from the point of change,
+ * caching intermediate results for optimal performance.
+ *
+ * @param operations - Array of matrix operations to apply
+ * @returns CSS transform string (matrix3d format)
+ *
+ * @example
+ * ```tsx
+ * const transform = useCSSMatrix([
+ *   ['translate', 100, 50],
+ *   ['rotateZ', angle],
+ *   ['scale', 2, 2]
+ * ]);
+ * return <div style={{ transform }} />;
+ * ```
+ */
+export const useCSSMatrix = (operations: MatrixOperation[]): string => {
+  // Cache for intermediate computation results
+  const cacheRef = useRef<CacheEntry[]>([]);
+  const prevOperationsRef = useRef<MatrixOperation[]>([]);
+
+  const result = useMemo(() => {
+    const prevOps = prevOperationsRef.current;
+    const cache = cacheRef.current;
+
+    // Find where operations differ from previous render
+    const diffIndex = findDiffIndex(prevOps, operations);
+
+    // If no difference and lengths match, return cached result
+    if (diffIndex === -1 && cache.length === operations.length) {
+      return cache[cache.length - 1]?.result.toCSS() ?? matrix().toCSS();
+    }
+
+    // Start from the last valid cached result or identity matrix
+    // eslint-disable-next-line no-restricted-syntax -- Performance: avoid function call overhead
+    let currentMatrix: CSSMatrix;
+    // eslint-disable-next-line no-restricted-syntax -- Performance: avoid function call overhead
+    let startIndex: number;
+
+    if (diffIndex > 0 && cache[diffIndex - 1]) {
+      // Use cached result up to the point of change
+      currentMatrix = cache[diffIndex - 1]!.result;
+      startIndex = diffIndex;
+    } else {
+      // Start from identity matrix
+      currentMatrix = matrix();
+      startIndex = 0;
+    }
+
+    // Rebuild cache from the point of change
+    const newCache: CacheEntry[] = cache.slice(0, startIndex);
+
+    for (let i = startIndex; i < operations.length; i++) {
+      const operation = operations[i]!;
+      currentMatrix = applyOperation(currentMatrix, operation);
+      newCache.push({
+        operation,
+        result: currentMatrix,
+      });
+    }
+
+    // Update refs for next render
+    cacheRef.current = newCache;
+    prevOperationsRef.current = [...operations];
+
+    return currentMatrix.toCSS();
+  }, [operations]);
+
+  return result;
+};
+
+/**
+ * Hook variant that returns the CSSMatrix object instead of CSS string
+ *
+ * Useful when you need access to the raw matrix values or want to
+ * apply additional operations.
+ *
+ * @param operations - Array of matrix operations to apply
+ * @returns CSSMatrix object
+ *
+ * @example
+ * ```tsx
+ * const matrixObj = useCSSMatrixObject([
+ *   ['translate', 100, 50],
+ *   ['rotateZ', angle]
+ * ]);
+ * const values = matrixObj.toArray();
+ * ```
+ */
+export const useCSSMatrixObject = (operations: MatrixOperation[]): CSSMatrix => {
+  const cacheRef = useRef<CacheEntry[]>([]);
+  const prevOperationsRef = useRef<MatrixOperation[]>([]);
+
+  const result = useMemo(() => {
+    const prevOps = prevOperationsRef.current;
+    const cache = cacheRef.current;
+
+    const diffIndex = findDiffIndex(prevOps, operations);
+
+    if (diffIndex === -1 && cache.length === operations.length) {
+      return cache[cache.length - 1]?.result ?? matrix();
+    }
+
+    // eslint-disable-next-line no-restricted-syntax -- Performance: avoid function call overhead
+    let currentMatrix: CSSMatrix;
+    // eslint-disable-next-line no-restricted-syntax -- Performance: avoid function call overhead
+    let startIndex: number;
+
+    if (diffIndex > 0 && cache[diffIndex - 1]) {
+      currentMatrix = cache[diffIndex - 1]!.result;
+      startIndex = diffIndex;
+    } else {
+      currentMatrix = matrix();
+      startIndex = 0;
+    }
+
+    const newCache: CacheEntry[] = cache.slice(0, startIndex);
+
+    for (let i = startIndex; i < operations.length; i++) {
+      const operation = operations[i]!;
+      currentMatrix = applyOperation(currentMatrix, operation);
+      newCache.push({
+        operation,
+        result: currentMatrix,
+      });
+    }
+
+    cacheRef.current = newCache;
+    prevOperationsRef.current = [...operations];
+
+    return currentMatrix;
+  }, [operations]);
+
+  return result;
+};

package/src/hooks/useClonedElementPreview.ts

@@ -0,0 +1,28 @@
+/**
+ * @file Clone a DOM element for preview while keeping SSR safe.
+ * Provides the cloned element as HTML string plus its measured size.
+ */
+import * as React from "react";
+import { useIsomorphicLayoutEffect } from "./useIsomorphicLayoutEffect";
+
+const isBrowser = typeof window !== "undefined" && typeof document !== "undefined";
+
+export const useClonedElementPreview = (
+  sourceEl: HTMLElement | null,
+): { html: string | null; size: { width: number; height: number } | null } => {
+  const [size, setSize] = React.useState<{ width: number; height: number } | null>(null);
+  const [html, setHtml] = React.useState<string | null>(null);
+
+  useIsomorphicLayoutEffect(() => {
+    if (!isBrowser || !sourceEl) {
+      setSize(null);
+      setHtml(null);
+      return;
+    }
+    const rect = sourceEl.getBoundingClientRect();
+    setSize({ width: rect.width, height: rect.height });
+    setHtml(sourceEl.outerHTML);
+  }, [sourceEl]);
+
+  return { html, size };
+};

package/src/hooks/useContainerScroll.ts

@@ -0,0 +1,78 @@
+/**
+ * @file useContainerScroll - Track scroll position of a container or document
+ *
+ * Tracks scroll position for either a specific scroll container element
+ * or the document (when container is null).
+ */
+import * as React from "react";
+
+export type ScrollPosition = {
+  /** Vertical scroll position */
+  scrollTop: number;
+  /** Horizontal scroll position */
+  scrollLeft: number;
+};
+
+/**
+ * Track scroll position of a container element or the document.
+ *
+ * @param container - Scroll container element, or null for document scroll
+ * @returns Current scroll position
+ *
+ * @example
+ * ```tsx
+ * // For document scroll
+ * const scroll = useContainerScroll(null);
+ *
+ * // For container scroll
+ * const containerRef = useRef<HTMLDivElement>(null);
+ * const scroll = useContainerScroll(containerRef.current);
+ * ```
+ */
+export function useContainerScroll(container: HTMLElement | null): ScrollPosition {
+  const [position, setPosition] = React.useState<ScrollPosition>(() => {
+    if (typeof window === "undefined") {
+      return { scrollTop: 0, scrollLeft: 0 };
+    }
+
+    if (container) {
+      return {
+        scrollTop: container.scrollTop,
+        scrollLeft: container.scrollLeft,
+      };
+    }
+
+    return {
+      scrollTop: window.scrollY,
+      scrollLeft: window.scrollX,
+    };
+  });
+
+  React.useEffect(() => {
+    const handleScroll = () => {
+      if (container) {
+        setPosition({
+          scrollTop: container.scrollTop,
+          scrollLeft: container.scrollLeft,
+        });
+      } else {
+        setPosition({
+          scrollTop: window.scrollY,
+          scrollLeft: window.scrollX,
+        });
+      }
+    };
+
+    // Initialize position
+    handleScroll();
+
+    const target = container ?? window;
+    target.addEventListener("scroll", handleScroll, { passive: true });
+
+    return () => {
+      target.removeEventListener("scroll", handleScroll);
+    };
+  }, [container]);
+
+  return position;
+}