@snapgridjs/react 0.1.0 → 0.3.0

package/README.md

@@ -15,7 +15,7 @@ Draggable, resizable, responsive grid layouts for React — with pluggable packi
 ## Why snapgrid
 
 - **Controlled & predictable** — you own the layout array; every change comes back through `onLayoutChange`. No hidden state.
-- **Headless or drop-in** — `<GridLayout>` for the common case, or `SnapGridProvider` + hooks for full control of the markup. Ships **no CSS**.
+- **Headless-first** — compose `useGridContainer` + hooks under a dnd-kit `DragDropProvider` for full control of your markup — or drop in the turnkey [`<GridLayout>`](https://snapgrid.dev/docs/guides/component-layer) (react-grid-layout-style) when you don't need that. Ships **no CSS**.
 - **Pluggable packing** — `vertical` / `horizontal` / `none`, plus `masonry` / `gravity` / `shelf` from [`@snapgridjs/extras`](https://www.npmjs.com/package/@snapgridjs/extras), or your own `Compactor`.
 - **Cross-grid dragging** — wrap grids in a `<SnapGridGroup>` and drag tiles between them.
 - **Nested grids** — drop a grid inside a tile of another grid; each level keeps its own isolated drag session.
@@ -33,8 +33,11 @@ pnpm add @snapgridjs/react @dnd-kit/react @dnd-kit/dom
 
 ## Quick start
 
+snapgrid is **headless-first**: you compose hooks with a dnd-kit `DragDropProvider` and render your own markup.
+
 ```tsx
-import { GridLayout, useContainerWidth, type Layout } from "@snapgridjs/react";
+import { DragDropProvider } from "@dnd-kit/react";
+import { type Layout, useContainerWidth, useGridContainer, useGridItem } from "@snapgridjs/react";
 import { useState } from "react";
 
 export function Board() {
@@ -45,20 +48,53 @@ export function Board() {
     { i: "c", x: 8, y: 0, w: 4, h: 2 },
   ]);
 
+  // You supply the dnd-kit provider; useGridContainer runs inside it (in Surface).
   return (
     <div ref={containerRef}>
-      <GridLayout layout={layout} width={width} onLayoutChange={setLayout}>
-        {layout.map((item) => (
-          <div key={item.i} className="tile">
-            {item.i}
-          </div>
-        ))}
-      </GridLayout>
+      <DragDropProvider>
+        <Surface layout={layout} width={width} onLayoutChange={setLayout} />
+      </DragDropProvider>
+    </div>
+  );
+}
+
+function Surface({
+  layout,
+  width,
+  onLayoutChange,
+}: { layout: Layout; width: number; onLayoutChange: (next: Layout) => void }) {
+  const { containerProps, group } = useGridContainer({ layout, width, onLayoutChange });
+  return (
+    <div {...containerProps}>
+      {layout.map((it) => (
+        <Tile key={it.i} id={it.i} group={group} />
+      ))}
+    </div>
+  );
+}
+
+function Tile({ id, group }: { id: string; group: string }) {
+  const { ref, style } = useGridItem(id, group);
+  return (
+    <div ref={ref} style={style} className="tile">
+      {id}
     </div>
   );
 }
 ```
 
+**Prefer a ready-made component?** The turnkey [`<GridLayout>`](https://snapgrid.dev/docs/guides/component-layer) wraps these same hooks (and supplies the provider) in a react-grid-layout-style API:
+
+```tsx
+<GridLayout layout={layout} width={width} onLayoutChange={setLayout}>
+  {layout.map((item) => (
+    <div key={item.i} className="tile">
+      {item.i}
+    </div>
+  ))}
+</GridLayout>
+```
+
 → Full walkthrough in [**Getting Started**](https://snapgrid.dev/docs/getting-started).
 
 ## License