react-grid-layout 2.0.0 → 2.1.0

package/README.md

@@ -57,15 +57,15 @@ Version 2 is a complete TypeScript rewrite with a modernized API:
 
 See the [RFC](./rfcs/0001-v2-typescript-rewrite.md#breaking-changes-in-v2) for detailed migration examples.
 
-| Change                                                                                                               | Description                                                                                       |
-| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| [`width` prop required](./rfcs/0001-v2-typescript-rewrite.md#breaking-changes-in-v2)                                 | Use `useContainerWidth` hook or provide your own measurement                                      |
-| [`onDragStart` threshold](./rfcs/0001-v2-typescript-rewrite.md#1-ondragstart-no-longer-fires-on-click-only-events)   | Now fires after 3px movement, not on mousedown. Use `onMouseDown` for immediate response          |
-| [Immutable callbacks](./rfcs/0001-v2-typescript-rewrite.md#2-immutable-callback-parameters)                          | Callback parameters are read-only. Use `onLayoutChange` or constraints instead of mutation        |
-| [`data-grid` in legacy only](./rfcs/0001-v2-typescript-rewrite.md#3-data-grid-prop-only-available-in-legacy-wrapper) | v2 requires explicit `layout` prop. Use legacy wrapper for `data-grid`                            |
-| [Fast compaction](./rfcs/0001-v2-typescript-rewrite.md#4-fast-compaction-algorithm-by-default)                       | O(n log n) algorithm may differ in edge cases. Use `compact()` from `/core` for exact v1 behavior |
-| UMD bundle removed                                                                                                   | Use a bundler (Vite, webpack, esbuild)                                                            |
-| `verticalCompact` removed                                                                                            | Use `compactType={null}` or `compactor={noCompactor}`                                             |
+| Change                                                                                                               | Description                                                                                            |
+| -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| [`width` prop required](./rfcs/0001-v2-typescript-rewrite.md#breaking-changes-in-v2)                                 | Use `useContainerWidth` hook or provide your own measurement                                           |
+| [`onDragStart` threshold](./rfcs/0001-v2-typescript-rewrite.md#1-ondragstart-no-longer-fires-on-click-only-events)   | Now fires after 3px movement, not on mousedown. Use `onMouseDown` for immediate response               |
+| [Immutable callbacks](./rfcs/0001-v2-typescript-rewrite.md#2-immutable-callback-parameters)                          | Callback parameters are read-only. Use `onLayoutChange` or constraints instead of mutation             |
+| [`data-grid` in legacy only](./rfcs/0001-v2-typescript-rewrite.md#3-data-grid-prop-only-available-in-legacy-wrapper) | v2 requires explicit `layout` prop. Use legacy wrapper for `data-grid`                                 |
+| [Pluggable compaction](./rfcs/0001-v2-typescript-rewrite.md#4-pluggable-compaction-algorithms)                       | Compaction is now pluggable via `Compactor` interface. Optional fast O(n log n) algorithm in `/extras` |
+| UMD bundle removed                                                                                                   | Use a bundler (Vite, webpack, esbuild)                                                                 |
+| `verticalCompact` removed                                                                                            | Use `compactType={null}` or `compactor={noCompactor}`                                                  |
 
 ## Migrating from v1
 
@@ -124,17 +124,17 @@ function MyGrid() {
 1. [Saving a Responsive Layout to LocalStorage](https://react-grid-layout.github.io/react-grid-layout/examples/08-localstorage-responsive.html)
 1. [Minimum and Maximum Width/Height](https://react-grid-layout.github.io/react-grid-layout/examples/09-min-max-wh.html)
 1. [Dynamic Minimum and Maximum Width/Height](https://react-grid-layout.github.io/react-grid-layout/examples/10-dynamic-min-max-wh.html)
-1. [No Vertical Compacting (Free Movement)](https://react-grid-layout.github.io/react-grid-layout/examples/11-no-vertical-compact.html)
-1. [Prevent Collision](https://react-grid-layout.github.io/react-grid-layout/examples/12-prevent-collision.html)
-1. [Error Case](https://react-grid-layout.github.io/react-grid-layout/examples/13-error-case.html)
-1. [Toolbox](https://react-grid-layout.github.io/react-grid-layout/examples/14-toolbox.html)
-1. [Drag From Outside](https://react-grid-layout.github.io/react-grid-layout/examples/15-drag-from-outside.html)
-1. [Bounded Layout](https://react-grid-layout.github.io/react-grid-layout/examples/16-bounded.html)
-1. [Responsive Bootstrap-style Layout](https://react-grid-layout.github.io/react-grid-layout/examples/17-responsive-bootstrap-style.html)
-1. [Scaled Containers](https://react-grid-layout.github.io/react-grid-layout/examples/18-scale.html)
-1. [Allow Overlap](https://react-grid-layout.github.io/react-grid-layout/examples/19-allow-overlap.html)
-1. [All Resizable Handles](https://react-grid-layout.github.io/react-grid-layout/examples/20-resizable-handles.html)
-1. [Single Row Horizontal](https://react-grid-layout.github.io/react-grid-layout/examples/21-horizontal.html)
+1. [Toolbox](https://react-grid-layout.github.io/react-grid-layout/examples/11-toolbox.html)
+1. [Drag From Outside](https://react-grid-layout.github.io/react-grid-layout/examples/12-drag-from-outside.html)
+1. [Bounded Layout](https://react-grid-layout.github.io/react-grid-layout/examples/13-bounded.html)
+1. [Responsive Bootstrap-style Layout](https://react-grid-layout.github.io/react-grid-layout/examples/14-responsive-bootstrap-style.html)
+1. [Scaled Containers](https://react-grid-layout.github.io/react-grid-layout/examples/15-scale.html)
+1. [Allow Overlap](https://react-grid-layout.github.io/react-grid-layout/examples/16-allow-overlap.html)
+1. [All Resizable Handles](https://react-grid-layout.github.io/react-grid-layout/examples/17-resizable-handles.html)
+1. [Compactor Showcase](https://react-grid-layout.github.io/react-grid-layout/examples/18-compactors.html)
+1. [Pluggable Constraints](https://react-grid-layout.github.io/react-grid-layout/examples/19-constraints.html)
+1. [Aspect Ratio Constraints](https://react-grid-layout.github.io/react-grid-layout/examples/20-aspect-ratio.html)
+1. [Custom Constraints](https://react-grid-layout.github.io/react-grid-layout/examples/21-custom-constraints.html)
 
 #### Projects Using React-Grid-Layout
 
@@ -449,9 +449,9 @@ interface UseGridLayoutOptions {
   cols: number;
   /** Compaction type: 'vertical', 'horizontal', or null */
   compactType?: CompactType;
-  /** Allow items to overlap */
+  /** Allow items to overlap (stack on top of each other) */
   allowOverlap?: boolean;
-  /** Prevent collisions when moving items */
+  /** Block movement into occupied space instead of pushing items (no effect if allowOverlap is true) */
   preventCollision?: boolean;
   /** Called when layout changes */
   onLayoutChange?: (layout: Layout) => void;
@@ -811,10 +811,30 @@ interface Compactor {
   /** Identifies the compaction type */
   type: "vertical" | "horizontal" | null | string;
 
-  /** Whether this compactor allows overlapping items */
+  /**
+   * Whether items can overlap each other.
+   *
+   * When true:
+   * - Items can be placed on top of other items
+   * - Dragging into another item does NOT push it away
+   * - Compaction is skipped after drag/resize
+   *
+   * Use for: layered dashboards, free-form layouts
+   */
   allowOverlap: boolean;
 
-  /** Prevent items from moving when another item is dragged into them */
+  /**
+   * Whether to block movement that would cause collision.
+   *
+   * When true (and allowOverlap is false):
+   * - Dragging into another item is blocked (item snaps back)
+   * - Other items are NOT pushed away
+   * - Only affects movement, not compaction
+   *
+   * Use with noCompactor for: fixed grids, slot-based layouts
+   *
+   * Note: Has no effect when allowOverlap is true.
+   */
   preventCollision?: boolean;
 
   /**
@@ -1090,7 +1110,7 @@ The `react-grid-layout/extras` entry point provides optional components that ext
 
 Renders an SVG grid background that aligns with GridLayout cells. Use this to visualize the grid structure behind your layout.
 
-> Based on [PR #2175](https://github.com/react-grid-layout/react-grid-layout/pull/2175) by [@nicosayer](https://github.com/nicosayer).
+> Based on [PR #2175](https://github.com/react-grid-layout/react-grid-layout/pull/2175) by [@dmj900501](https://github.com/dmj900501).
 
 ```tsx
 import { GridBackground } from "react-grid-layout/extras";
@@ -1146,6 +1166,58 @@ interface GridBackgroundProps {
 }
 ```
 
+### Fast Compactors
+
+For large layouts (200+ items), the standard compactors can become slow due to O(n²) collision resolution. The fast compactors use optimized algorithms with O(n log n) complexity.
+
+> Based on the "rising tide" algorithm from [PR #2152](https://github.com/react-grid-layout/react-grid-layout/pull/2152) by [@morris](https://github.com/morris).
+
+```tsx
+import {
+  fastVerticalCompactor,
+  fastHorizontalCompactor,
+  fastVerticalOverlapCompactor,
+  fastHorizontalOverlapCompactor
+} from "react-grid-layout/extras";
+
+<ReactGridLayout
+  compactor={fastVerticalCompactor}
+  // or compactor={fastHorizontalCompactor}
+  layout={layout}
+  width={width}
+/>;
+```
+
+**Performance Benchmarks:**
+
+| Items | Standard Vertical | Fast Vertical | Speedup |
+| ----- | ----------------- | ------------- | ------- |
+| 50    | 112 µs            | 19 µs         | **6x**  |
+| 100   | 203 µs            | 36 µs         | **6x**  |
+| 200   | 821 µs            | 51 µs         | **16x** |
+| 500   | 5.7 ms            | 129 µs        | **45x** |
+
+| Items | Standard Horizontal | Fast Horizontal | Speedup |
+| ----- | ------------------- | --------------- | ------- |
+| 50    | 164 µs              | 12 µs           | **14x** |
+| 100   | 477 µs              | 25 µs           | **19x** |
+| 200   | 1.1 ms              | 42 µs           | **26x** |
+| 500   | 9.5 ms              | 128 µs          | **74x** |
+
+**Correctness:**
+
+The fast compactors produce layouts identical to the standard compactors:
+
+- **Vertical**: 0% height difference on deterministic 100-item layouts
+- **Horizontal**: 0% width difference on deterministic 100-item layouts
+- Both pass all correctness tests: no overlaps, idempotent, static item handling
+
+**When to use:**
+
+- Use fast compactors for dashboards with 200+ widgets
+- For smaller layouts (<100 items), standard compactors work equally well
+- Both standard and fast compactors produce valid, non-overlapping layouts
+
 ### calcGridCellDimensions (Core Utility)
 
 For building custom grid overlays or backgrounds, use the `calcGridCellDimensions` utility from `react-grid-layout/core`:

package/css/styles.css

@@ -5,7 +5,6 @@
 .react-grid-item {
   transition: all 200ms ease;
   transition-property: left, top, width, height;
-  user-select: none;
 }
 .react-grid-item img {
   pointer-events: none;

package/dist/{ResponsiveGridLayout-D6lFRE3f.d.mts → ResponsiveGridLayout-BkHF9YHa.d.mts}

@@ -1,5 +1,5 @@
 import React__default, { CSSProperties, DragEvent, ReactElement } from 'react';
-import { j as GridConfig, k as DragConfig, l as ResizeConfig, m as DropConfig, i as PositionStrategy, c as Compactor, L as Layout, a as LayoutItem, B as Breakpoint, b as Breakpoints, R as ResponsiveLayouts } from './types-Cxf4nHNr.mjs';
+import { l as GridConfig, m as DragConfig, n as ResizeConfig, o as DropConfig, k as PositionStrategy, c as Compactor, f as LayoutConstraint, L as Layout, a as LayoutItem, B as Breakpoint, b as Breakpoints, R as ResponsiveLayouts } from './types-CokovIMH.mjs';
 
 /**
  * GridLayout component
@@ -45,6 +45,13 @@ interface GridLayoutProps {
      * @see Compactor
      */
     compactor?: Compactor;
+    /**
+     * Layout constraints for position and size limiting.
+     * Applied during drag/resize operations.
+     * Default: [gridBounds, minMaxSize]
+     * @see LayoutConstraint
+     */
+    constraints?: LayoutConstraint[];
     /** Layout definition */
     layout?: Layout;
     /** Item to use when dropping from outside */
@@ -77,6 +84,8 @@ interface GridLayoutProps {
     onDropDragOver?: (e: DragEvent) => {
         w?: number;
         h?: number;
+        dragOffsetX?: number;
+        dragOffsetY?: number;
     } | false | void;
 }
 /**

package/dist/{ResponsiveGridLayout-CH4s0tKj.d.ts → ResponsiveGridLayout-CLn16-X3.d.ts}

@@ -1,5 +1,5 @@
 import React__default, { CSSProperties, DragEvent, ReactElement } from 'react';
-import { j as GridConfig, k as DragConfig, l as ResizeConfig, m as DropConfig, i as PositionStrategy, c as Compactor, L as Layout, a as LayoutItem, B as Breakpoint, b as Breakpoints, R as ResponsiveLayouts } from './types-Cxf4nHNr.js';
+import { l as GridConfig, m as DragConfig, n as ResizeConfig, o as DropConfig, k as PositionStrategy, c as Compactor, f as LayoutConstraint, L as Layout, a as LayoutItem, B as Breakpoint, b as Breakpoints, R as ResponsiveLayouts } from './types-CokovIMH.js';
 
 /**
  * GridLayout component
@@ -45,6 +45,13 @@ interface GridLayoutProps {
      * @see Compactor
      */
     compactor?: Compactor;
+    /**
+     * Layout constraints for position and size limiting.
+     * Applied during drag/resize operations.
+     * Default: [gridBounds, minMaxSize]
+     * @see LayoutConstraint
+     */
+    constraints?: LayoutConstraint[];
     /** Layout definition */
     layout?: Layout;
     /** Item to use when dropping from outside */
@@ -77,6 +84,8 @@ interface GridLayoutProps {
     onDropDragOver?: (e: DragEvent) => {
         w?: number;
         h?: number;
+        dragOffsetX?: number;
+        dragOffsetY?: number;
     } | false | void;
 }
 /**

package/dist/{calculate-CwYDW8na.d.mts → calculate-DsVTldEE.d.ts}

@@ -1,4 +1,4 @@
-import { P as Position, d as ResizeHandleAxis } from './types-Cxf4nHNr.mjs';
+import { P as Position, d as ResizeHandleAxis } from './types-CokovIMH.js';
 
 /**
  * Grid calculation utilities.
@@ -74,6 +74,20 @@ declare function calcXY(positionParams: PositionParams, top: number, left: numbe
     x: number;
     y: number;
 };
+/**
+ * Translate pixel coordinates to grid units without clamping.
+ *
+ * Use this with the constraint system for custom boundary control.
+ *
+ * @param positionParams - Grid parameters
+ * @param top - Top position in pixels (relative to parent)
+ * @param left - Left position in pixels (relative to parent)
+ * @returns x and y in grid units (unclamped)
+ */
+declare function calcXYRaw(positionParams: PositionParams, top: number, left: number): {
+    x: number;
+    y: number;
+};
 /**
  * Calculate grid units from pixel dimensions.
  *
@@ -89,6 +103,20 @@ declare function calcWH(positionParams: PositionParams, width: number, height: n
     w: number;
     h: number;
 };
+/**
+ * Calculate grid units from pixel dimensions without clamping.
+ *
+ * Use this with the constraint system for custom size control.
+ *
+ * @param positionParams - Grid parameters
+ * @param width - Width in pixels
+ * @param height - Height in pixels
+ * @returns w, h in grid units (unclamped, minimum 1)
+ */
+declare function calcWHRaw(positionParams: PositionParams, width: number, height: number): {
+    w: number;
+    h: number;
+};
 /**
  * Clamp a number between bounds.
  *
@@ -165,4 +193,4 @@ interface GridCellConfig {
  */
 declare function calcGridCellDimensions(config: GridCellConfig): GridCellDimensions;
 
-export { type GridCellDimensions as G, type PositionParams as P, calcXY as a, calcWH as b, calcGridItemPosition as c, type GridCellConfig as d, calcGridColWidth as e, calcGridItemWHPx as f, clamp as g, calcGridCellDimensions as h };
+export { type GridCellDimensions as G, type PositionParams as P, calcXY as a, calcWH as b, calcGridItemPosition as c, type GridCellConfig as d, calcGridColWidth as e, calcGridItemWHPx as f, calcXYRaw as g, calcWHRaw as h, clamp as i, calcGridCellDimensions as j };

package/dist/{calculate-mgLpNJ5O.d.ts → calculate-DwbL1D06.d.mts}

@@ -1,4 +1,4 @@
-import { P as Position, d as ResizeHandleAxis } from './types-Cxf4nHNr.js';
+import { P as Position, d as ResizeHandleAxis } from './types-CokovIMH.mjs';
 
 /**
  * Grid calculation utilities.
@@ -74,6 +74,20 @@ declare function calcXY(positionParams: PositionParams, top: number, left: numbe
     x: number;
     y: number;
 };
+/**
+ * Translate pixel coordinates to grid units without clamping.
+ *
+ * Use this with the constraint system for custom boundary control.
+ *
+ * @param positionParams - Grid parameters
+ * @param top - Top position in pixels (relative to parent)
+ * @param left - Left position in pixels (relative to parent)
+ * @returns x and y in grid units (unclamped)
+ */
+declare function calcXYRaw(positionParams: PositionParams, top: number, left: number): {
+    x: number;
+    y: number;
+};
 /**
  * Calculate grid units from pixel dimensions.
  *
@@ -89,6 +103,20 @@ declare function calcWH(positionParams: PositionParams, width: number, height: n
     w: number;
     h: number;
 };
+/**
+ * Calculate grid units from pixel dimensions without clamping.
+ *
+ * Use this with the constraint system for custom size control.
+ *
+ * @param positionParams - Grid parameters
+ * @param width - Width in pixels
+ * @param height - Height in pixels
+ * @returns w, h in grid units (unclamped, minimum 1)
+ */
+declare function calcWHRaw(positionParams: PositionParams, width: number, height: number): {
+    w: number;
+    h: number;
+};
 /**
  * Clamp a number between bounds.
  *
@@ -165,4 +193,4 @@ interface GridCellConfig {
  */
 declare function calcGridCellDimensions(config: GridCellConfig): GridCellDimensions;
 
-export { type GridCellDimensions as G, type PositionParams as P, calcXY as a, calcWH as b, calcGridItemPosition as c, type GridCellConfig as d, calcGridColWidth as e, calcGridItemWHPx as f, clamp as g, calcGridCellDimensions as h };
+export { type GridCellDimensions as G, type PositionParams as P, calcXY as a, calcWH as b, calcGridItemPosition as c, type GridCellConfig as d, calcGridColWidth as e, calcGridItemWHPx as f, calcXYRaw as g, calcWHRaw as h, clamp as i, calcGridCellDimensions as j };