@griddle/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trustybits
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @griddle/react
+
+React bindings for [Griddle](https://github.com/Trustybits/griddle) — a headless,
+zero-dependency grid/canvas engine. Provides a `<GriddleGrid />` component and a
+`useGriddle()` hook that wrap [`@griddle/core`](https://www.npmjs.com/package/@griddle/core)
+with virtualized rendering, drag/resize handles, and animations.
+
+## Install
+
+```sh
+npm install @griddle/react @griddle/core
+```
+
+`@griddle/core` and `react` are **peer dependencies**. On npm 7+ the peers are
+installed automatically; with Yarn or pnpm, add `@griddle/core` yourself (as
+shown above). `react` is expected to already be in your app (>=17).
+
+## Usage
+
+```tsx
+import { GriddleGrid, useGriddle } from '@griddle/react';
+
+export default function App() {
+  const api = useGriddle({
+    config: { cols: 12, rows: 12, unitWidth: 75, unitHeight: 75 },
+    tiles: [
+      { id: '1', col: 0, row: 0, w: 2, h: 2 },
+      { id: '2', col: 2, row: 0, w: 1, h: 1 },
+    ],
+  });
+
+  return (
+    <GriddleGrid
+      api={api}
+      renderTile={(tile, selected) => (
+        <div data-selected={selected}>#{tile.id}</div>
+      )}
+    />
+  );
+}
+```
+
+## Loop mode (infinite gallery)
+
+Enable `loop` in the config and the content repeats endlessly with drag-to-pan
+physics — no scrollbars:
+
+```tsx
+const api = useGriddle({
+  config: {
+    cols: 12, rows: 12, unitWidth: 120, unitHeight: 120,
+    loop: { enabled: true, interaction: 'pan' }, // 'pan' = viewer, 'edit' = ghost edit
+  },
+  tiles,
+});
+```
+
+`<GriddleGrid>` automatically switches to the loop renderer when
+`config.loop.enabled` is `true`, so most apps never touch the loop component
+directly. For advanced cases where you want to render the loop plane explicitly,
+`GriddleLoopGrid` is also exported and takes the same props as `GriddleGrid`:
+
+```tsx
+import { GriddleLoopGrid } from '@griddle/react';
+```
+
+See the [main repository](https://github.com/Trustybits/griddle) for full docs.
+
+## License
+
+MIT © Trustybits

package/dist/GriddleGrid.d.ts

@@ -0,0 +1,45 @@
+import { CSSProperties, ReactNode } from 'react';
+import type { GriddleApi } from './useGriddle.js';
+import type { CameraState, Tile } from '@griddle/core';
+export interface GriddleGridProps {
+    api: GriddleApi;
+    renderTile: (tile: Tile, selected: boolean) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    /** Optional container height; default '100%'. */
+    height?: number | string;
+    /** Whether to render the background grid lines. Default true. */
+    showGrid?: boolean;
+    /** Controlled selection state. If omitted, selection is managed internally. */
+    selection?: Set<string>;
+    /** Called whenever the selection changes. */
+    onSelectionChange?: (selection: Set<string>) => void;
+    /** Called when the user draw-creates a new tile rect on empty space. */
+    onDrawCreate?: (rect: {
+        col: number;
+        row: number;
+        w: number;
+        h: number;
+    }) => void;
+    /** Called when a drag gesture begins (pointer down on a tile). */
+    onDragStart?: (tileId: string) => void;
+    /** Called when a drag gesture ends. `committed` is true if the tile moved. */
+    onDragEnd?: (tileId: string, committed: boolean) => void;
+    /** Called when a resize gesture begins (pointer down on a handle). */
+    onResizeStart?: (tileId: string) => void;
+    /** Called when a resize gesture ends. `committed` is true if the tile resized. */
+    onResizeEnd?: (tileId: string, committed: boolean) => void;
+    /**
+     * Loop mode only: fires whenever the camera moves (offset, velocity,
+     * isMoving, isDragging). Use it to drive velocity-based visual effects.
+     * Called from the render loop — keep the handler cheap.
+     */
+    onCameraChange?: (camera: CameraState) => void;
+}
+/**
+ * Renders the grid. When `config.loop.enabled` is set, delegates to the
+ * loop-mode renderer (infinitely repeating plane); otherwise renders the
+ * standard scrollable grid. Toggling loop at runtime remounts the surface.
+ */
+export declare function GriddleGrid(props: GriddleGridProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=GriddleGrid.d.ts.map

package/dist/GriddleGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GriddleGrid.d.ts","sourceRoot":"","sources":["../src/GriddleGrid.tsx"],"names":[],"mappings":"AAUA,OAAO,EACL,aAAa,EACb,SAAS,EAQV,MAAM,OAAO,CAAC;AACf,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAU,IAAI,EAAE,MAAM,eAAe,CAAC;AAgB/D,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,UAAU,CAAC;IAChB,UAAU,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,KAAK,SAAS,CAAC;IACzD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,iDAAiD;IACjD,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB,6CAA6C;IAC7C,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IACrD,wEAAwE;IACxE,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAClF,kEAAkE;IAClE,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACvC,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IACzD,sEAAsE;IACtE,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,kFAAkF;IAClF,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3D;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,IAAI,CAAC;CAChD;AAqDD;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,2CAQlD"}