react-native-smart-grid 0.1.0

package/src/engine/GridEngine.ts

@@ -0,0 +1,148 @@
+import type { LayoutItem, TilePosition, TileSize } from '../types';
+
+// Sentinel value marking a cell as occupied by a tile with the given id.
+// The matrix stores tile ids so we can look up who owns a cell in O(1).
+type Cell = string | null; // null = empty, string = tile id
+
+export class GridEngine {
+  private matrix: Cell[][];
+  private columns: number;
+
+  constructor(columns: number, initialRows = 20) {
+    this.columns = columns;
+    this.matrix = GridEngine.createMatrix(columns, initialRows);
+  }
+
+  private static createMatrix(columns: number, rows: number): Cell[][] {
+    return Array.from({ length: rows }, () => Array(columns).fill(null));
+  }
+
+  // ── Accessors ────────────────────────────────────────────────────────────
+
+  get rowCount(): number {
+    return this.matrix.length;
+  }
+
+  get columnCount(): number {
+    return this.columns;
+  }
+
+  // ── Core operations ──────────────────────────────────────────────────────
+
+  isOccupied(pos: TilePosition, size: TileSize, ignoreId?: string): boolean {
+    for (let row = pos.y; row < pos.y + size.h; row++) {
+      for (let col = pos.x; col < pos.x + size.w; col++) {
+        if (col < 0 || col >= this.columns) return true; // out of bounds
+        this.growIfNeeded(row);
+        const cell = this.matrix[row]![col]!;
+        if (cell !== null && cell !== ignoreId) return true;
+      }
+    }
+    return false;
+  }
+
+  isInBounds(pos: TilePosition, size: TileSize): boolean {
+    return pos.x >= 0 && pos.x + size.w <= this.columns && pos.y >= 0;
+  }
+
+  placeAt(id: string, pos: TilePosition, size: TileSize): void {
+    for (let row = pos.y; row < pos.y + size.h; row++) {
+      this.growIfNeeded(row);
+      for (let col = pos.x; col < pos.x + size.w; col++) {
+        this.matrix[row]![col] = id;
+      }
+    }
+  }
+
+  removeFrom(pos: TilePosition, size: TileSize): void {
+    for (let row = pos.y; row < pos.y + size.h; row++) {
+      if (row >= this.matrix.length) break;
+      for (let col = pos.x; col < pos.x + size.w; col++) {
+        if (col < this.columns) this.matrix[row]![col] = null;
+      }
+    }
+  }
+
+  removeById(id: string): void {
+    for (let row = 0; row < this.matrix.length; row++) {
+      for (let col = 0; col < this.columns; col++) {
+        if (this.matrix[row]![col] === id) {
+          this.matrix[row]![col] = null;
+        }
+      }
+    }
+  }
+
+  // ── Placement search ─────────────────────────────────────────────────────
+
+  /**
+   * Scan top-left to bottom-right for the first position where `size` fits.
+   * Returns null if the grid (up to maxRows) is full.
+   */
+  findFirstFit(size: TileSize, maxRows = this.matrix.length + size.h): TilePosition | null {
+    for (let row = 0; row < maxRows; row++) {
+      this.growIfNeeded(row + size.h - 1);
+      for (let col = 0; col <= this.columns - size.w; col++) {
+        const pos: TilePosition = { x: col, y: row };
+        if (!this.isOccupied(pos, size)) return pos;
+      }
+    }
+    return null;
+  }
+
+  /**
+   * Returns ids of all tiles that overlap the given region, excluding ignoreId.
+   */
+  getCollisions(pos: TilePosition, size: TileSize, ignoreId?: string): Set<string> {
+    const hits = new Set<string>();
+    for (let row = pos.y; row < pos.y + size.h; row++) {
+      if (row >= this.matrix.length) break;
+      for (let col = pos.x; col < pos.x + size.w; col++) {
+        if (col >= this.columns) break;
+        const cell = this.matrix[row]![col]!;
+        if (cell !== null && cell !== ignoreId) hits.add(cell);
+      }
+    }
+    return hits;
+  }
+
+  // ── Serialization ────────────────────────────────────────────────────────
+
+  /**
+   * Rebuild the entire matrix from a layout snapshot.
+   * Call this when restoring a saved layout.
+   */
+  loadLayout(items: LayoutItem[]): void {
+    const maxRow = items.reduce((m, item) => Math.max(m, item.position.y + item.size.h), 0);
+    this.matrix = GridEngine.createMatrix(this.columns, Math.max(maxRow + 5, 20));
+    for (const item of items) {
+      this.placeAt(item.id, item.position, item.size);
+    }
+  }
+
+  /**
+   * Dump the positions of all occupied cells grouped by tile id.
+   * Useful for debugging — not the same as a layout snapshot.
+   */
+  debugDump(): Record<string, TilePosition[]> {
+    const out: Record<string, TilePosition[]> = {};
+    for (let row = 0; row < this.matrix.length; row++) {
+      for (let col = 0; col < this.columns; col++) {
+        const id = this.matrix[row]![col];
+        if (id) {
+          if (!out[id]) out[id] = [];
+          out[id]!.push({ x: col, y: row });
+        }
+      }
+    }
+    return out;
+  }
+
+  // ── Internal helpers ─────────────────────────────────────────────────────
+
+  private growIfNeeded(rowIndex: number): void {
+    while (this.matrix.length <= rowIndex) {
+      this.matrix.push(Array(this.columns).fill(null));
+    }
+  }
+}

package/src/engine/autoArrange.ts

@@ -0,0 +1,59 @@
+import { GridEngine } from './GridEngine';
+import type { PlacedTile, TilePosition, Gravity } from '../types';
+
+export function autoArrange<TData>(tiles: PlacedTile<TData>[], columns: number): PlacedTile<TData>[] {
+  const engine = new GridEngine(columns);
+
+  const sorted = [...tiles].sort(
+    (a, b) => b.size.w * b.size.h - a.size.w * a.size.h
+  );
+
+  const newPositions = new Map<string, TilePosition>();
+  for (const tile of sorted) {
+    const pos = engine.findFirstFit(tile.size) ?? tile.position;
+    engine.placeAt(tile.id, pos, tile.size);
+    newPositions.set(tile.id, pos);
+  }
+
+  return tiles.map((t) => ({ ...t, position: newPositions.get(t.id) ?? t.position }));
+}
+
+export function applyGravity<TData>(
+  tiles: PlacedTile<TData>[],
+  columns: number,
+  gravity: Gravity
+): PlacedTile<TData>[] {
+  if (gravity === 'none') return tiles;
+
+  const engine = new GridEngine(columns);
+
+  const sorted = [...tiles].sort(
+    gravity === 'up'
+      ? (a, b) => a.position.y - b.position.y || a.position.x - b.position.x
+      : (a, b) => a.position.x - b.position.x || a.position.y - b.position.y
+  );
+
+  const newPositions = new Map<string, TilePosition>();
+  for (const tile of sorted) {
+    const pos = slideToward(tile.position, tile.size, engine, gravity);
+    engine.placeAt(tile.id, pos, tile.size);
+    newPositions.set(tile.id, pos);
+  }
+
+  return tiles.map((t) => ({ ...t, position: newPositions.get(t.id) ?? t.position }));
+}
+
+function slideToward(
+  start: TilePosition,
+  size: { w: number; h: number },
+  engine: GridEngine,
+  gravity: 'up' | 'left'
+): TilePosition {
+  let { x, y } = start;
+  if (gravity === 'up') {
+    while (y > 0 && !engine.isOccupied({ x, y: y - 1 }, size)) y--;
+  } else {
+    while (x > 0 && !engine.isOccupied({ x: x - 1, y }, size)) x--;
+  }
+  return { x, y };
+}

package/src/engine/collisions.ts

@@ -0,0 +1,87 @@
+import { GridEngine } from './GridEngine';
+import type { PlacedTile, TilePosition, CollisionBehavior } from '../types';
+
+export function resolveCollisions<TData>(
+  tiles: PlacedTile<TData>[],
+  draggedId: string,
+  targetPosition: TilePosition,
+  behavior: CollisionBehavior,
+  columns: number
+): PlacedTile<TData>[] {
+  if (behavior === 'swap') return resolveSwap(tiles, draggedId, targetPosition);
+  return resolvePush(tiles, draggedId, targetPosition, columns);
+}
+
+function resolveSwap<TData>(
+  tiles: PlacedTile<TData>[],
+  draggedId: string,
+  targetPosition: TilePosition
+): PlacedTile<TData>[] {
+  const dragged = tiles.find((t) => t.id === draggedId);
+  if (!dragged) return tiles;
+
+  const cx = targetPosition.x + dragged.size.w / 2;
+  const cy = targetPosition.y + dragged.size.h / 2;
+
+  const swapTarget = tiles.find(
+    (t) =>
+      t.id !== draggedId &&
+      cx > t.position.x &&
+      cx < t.position.x + t.size.w &&
+      cy > t.position.y &&
+      cy < t.position.y + t.size.h
+  );
+
+  const fromPos = dragged.position;
+  return tiles.map((t) => {
+    if (t.id === draggedId) return { ...t, position: targetPosition };
+    if (swapTarget && t.id === swapTarget.id) return { ...t, position: fromPos };
+    return t;
+  });
+}
+
+function resolvePush<TData>(
+  tiles: PlacedTile<TData>[],
+  draggedId: string,
+  targetPosition: TilePosition,
+  columns: number
+): PlacedTile<TData>[] {
+  const dragged = tiles.find((t) => t.id === draggedId);
+  if (!dragged) return tiles;
+
+  const engine = new GridEngine(columns);
+  const others = tiles.filter((t) => t.id !== draggedId);
+
+  for (const t of others) {
+    engine.placeAt(t.id, t.position, t.size);
+  }
+
+  const collisions = engine.getCollisions(targetPosition, dragged.size);
+
+  if (collisions.size === 0) {
+    return tiles.map((t) => (t.id === draggedId ? { ...t, position: targetPosition } : t));
+  }
+
+  // Claim the target space, then re-home displaced tiles in top-left order.
+  for (const id of collisions) {
+    engine.removeById(id);
+  }
+  engine.placeAt(draggedId, targetPosition, dragged.size);
+
+  const displaced = others
+    .filter((t) => collisions.has(t.id))
+    .sort((a, b) => a.position.y - b.position.y || a.position.x - b.position.x);
+
+  const newPositions = new Map<string, TilePosition>();
+  for (const t of displaced) {
+    const pos = engine.findFirstFit(t.size) ?? t.position;
+    engine.placeAt(t.id, pos, t.size);
+    newPositions.set(t.id, pos);
+  }
+
+  return tiles.map((t) => {
+    if (t.id === draggedId) return { ...t, position: targetPosition };
+    const pos = newPositions.get(t.id);
+    return pos ? { ...t, position: pos } : t;
+  });
+}

package/src/hooks/useTileGesture.ts

@@ -0,0 +1,88 @@
+import { Gesture } from 'react-native-gesture-handler';
+import { runOnJS } from 'react-native-reanimated';
+import type { PlacedTile, GridConfig } from '../types';
+import type { PixelRect } from '../layout/LayoutCalculator';
+import { useGridDrag } from '../context/GridDragContext';
+import { pixelToGrid } from '../utils/pixelToGrid';
+
+type Options = {
+  tile: PlacedTile;
+  rect: PixelRect;
+  config: GridConfig;
+  containerWidth: number;
+};
+
+export function useTileGesture({ tile, rect, config, containerWidth }: Options) {
+  const drag = useGridDrag();
+
+  const canDrag = drag.draggable && tile.draggable !== false;
+  const canSelect = drag.selectable && tile.selectable !== false;
+
+  function onDragStart() {
+    drag.startDrag(tile, rect);
+  }
+
+  function onDragMove(absX: number, absY: number) {
+    const pos = pixelToGrid(
+      absX,
+      absY,
+      drag.containerPageX.current,
+      drag.containerPageY.current,
+      drag.scrollYRef.current,
+      config,
+      tile.size,
+      containerWidth
+    );
+    drag.updateGhost(pos);
+  }
+
+  function onDragEnd() {
+    drag.endDrag(drag.ghostPosition ?? tile.position);
+  }
+
+  function onLongPressSelect() {
+    drag.selectTile(tile);
+  }
+
+  function onPress() {
+    drag.onTilePress(tile);
+  }
+
+  const tap = Gesture.Tap()
+    .maxDuration(200) // must complete before the 300ms long-press activates drag
+    .onEnd(() => {
+      runOnJS(onPress)();
+    });
+
+  const pan = Gesture.Pan()
+    .enabled(canDrag || canSelect)
+    .activateAfterLongPress(300)
+    .onStart(() => {
+      if (canDrag) {
+        runOnJS(onDragStart)();
+      } else {
+        // draggable=false: select immediately on long-press activation, not on release
+        runOnJS(onLongPressSelect)();
+      }
+    })
+    .onUpdate((e) => {
+      if (!canDrag) return;
+      drag.dragAbsX.value = e.absoluteX;
+      drag.dragAbsY.value = e.absoluteY;
+      runOnJS(onDragMove)(e.absoluteX, e.absoluteY);
+    })
+    .onEnd(() => {
+      if (canDrag) {
+        runOnJS(onDragEnd)();
+      }
+    })
+    .onFinalize(() => {
+      if (canDrag && drag.isDragging.value) {
+        runOnJS(onDragEnd)();
+      }
+    });
+
+  const gesture = Gesture.Simultaneous(pan, tap);
+
+  return { gesture };
+}

package/src/index.tsx

@@ -0,0 +1,29 @@
+export type {
+  Tile,
+  PlacedTile,
+  TileSize,
+  TilePosition,
+  GridConfig,
+  CollisionBehavior,
+  Gravity,
+  HapticEvent,
+  LayoutItem,
+  SerializedLayout,
+} from './types';
+
+export { GridEngine } from './engine/GridEngine';
+export { resolveCollisions } from './engine/collisions';
+export { autoArrange, applyGravity } from './engine/autoArrange';
+
+export type { PixelRect } from './layout/LayoutCalculator';
+export {
+  columnWidth,
+  tileToPixelRect,
+  gridTotalHeight,
+  isInViewport,
+} from './layout/LayoutCalculator';
+
+export { pixelToGrid } from './utils/pixelToGrid';
+
+export type { SmartGridRef, RenderTileInfo, SmartGridProps } from './components/SmartGrid';
+export { SmartGrid } from './components/SmartGrid';

package/src/layout/LayoutCalculator.ts

@@ -0,0 +1,50 @@
+import type { TilePosition, TileSize, GridConfig } from '../types';
+
+export type PixelRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+
+export function columnWidth(config: GridConfig, containerWidth: number): number {
+  const available = containerWidth - config.padding * 2 - config.gap * (config.columns - 1);
+  return available / config.columns;
+}
+
+export function tileToPixelRect(
+  position: TilePosition,
+  size: TileSize,
+  config: GridConfig,
+  containerWidth: number
+): PixelRect {
+  const colW = columnWidth(config, containerWidth);
+  const { gap, padding, rowHeight } = config;
+  return {
+    x: padding + position.x * (colW + gap),
+    y: padding + position.y * (rowHeight + gap),
+    width: size.w * colW + (size.w - 1) * gap,
+    height: size.h * rowHeight + (size.h - 1) * gap,
+  };
+}
+
+export function gridTotalHeight(
+  tiles: Array<{ position: TilePosition; size: TileSize }>,
+  config: GridConfig
+): number {
+  if (tiles.length === 0) return config.padding * 2;
+  const maxRow = tiles.reduce((m, t) => Math.max(m, t.position.y + t.size.h), 0);
+  return config.padding * 2 + maxRow * config.rowHeight + Math.max(0, maxRow - 1) * config.gap;
+}
+
+export function isInViewport(
+  rect: PixelRect,
+  scrollY: number,
+  viewportHeight: number,
+  overscan = 200
+): boolean {
+  return (
+    rect.y + rect.height >= scrollY - overscan &&
+    rect.y <= scrollY + viewportHeight + overscan
+  );
+}

package/src/types.ts

@@ -0,0 +1,113 @@
+/** Width and height of a tile in grid units. */
+export type TileSize = {
+  /** Number of grid columns spanned. */
+  w: number;
+  /** Number of grid rows spanned. */
+  h: number;
+};
+
+/** Column/row position of a tile's top-left corner (0-based). */
+export type TilePosition = {
+  /** Column index (0-based). */
+  x: number;
+  /** Row index (0-based). */
+  y: number;
+};
+
+/**
+ * A single tile in the grid.
+ *
+ * `position` and `size` are both optional:
+ * - Both provided → tile is placed exactly where specified (use when restoring a saved layout).
+ * - `size` only   → tile is auto-placed via bin-packing.
+ * - Neither       → tile defaults to 1×1 and is auto-placed in order.
+ *
+ * @example
+ * ```ts
+ * // Explicit position + size (restored from storage)
+ * { id: '1', position: { x: 0, y: 0 }, size: { w: 2, h: 2 }, data: { label: 'Music' } }
+ *
+ * // Size only — grid chooses placement
+ * { id: '2', size: { w: 2, h: 1 }, data: { label: 'Photos' } }
+ *
+ * // No position, no size — defaults to 1×1, auto-placed in order
+ * { id: '3', data: { label: 'Notes' } }
+ *
+ * // Pinned tile — cannot be dragged
+ * { id: '4', data: { label: 'Header' }, draggable: false }
+ *
+ * // Non-selectable tile — long press fires onTilePress instead of entering selection
+ * { id: '5', data: { label: 'Info' }, selectable: false }
+ * ```
+ */
+export type Tile<TData = unknown> = {
+  /** Unique identifier. Must be stable across re-renders. */
+  id: string;
+  /** Tile dimensions in grid units. Omit to default to 1×1. */
+  size?: TileSize;
+  /** Top-left position in the grid. Omit to let the grid auto-place. */
+  position?: TilePosition;
+  /** Your custom data — passed back to `renderTile` as `item.data`. */
+  data: TData;
+  /** When `true`, prevents both dragging and resizing. @default false */
+  locked?: boolean;
+  /** Smallest size the tile can be resized to. Only enforced when `isEditing` is true. */
+  minSize?: TileSize;
+  /** Largest size the tile can be resized to. Only enforced when `isEditing` is true. */
+  maxSize?: TileSize;
+  /** When `false`, the tile ignores the drag gesture and stays in place. @default true */
+  draggable?: boolean;
+  /** When `false`, long-pressing this tile fires `onTilePress` instead of entering selection. @default true */
+  selectable?: boolean;
+};
+
+/** A `Tile` with `position` and `size` guaranteed to be present. Used internally after auto-placement. */
+export type PlacedTile<TData = unknown> = Tile<TData> & {
+  position: TilePosition;
+  size: TileSize;
+};
+
+/** Internal grid configuration passed through context. */
+export type GridConfig = {
+  columns: number;
+  rowHeight: number;
+  gap: number;
+  padding: number;
+};
+
+/**
+ * How a dragged tile interacts with tiles it overlaps on drop.
+ * - `'push'` — displaced tiles are moved to the next available slot.
+ * - `'swap'` — the dragged tile and the tile at the drop center exchange positions.
+ */
+export type CollisionBehavior = 'push' | 'swap';
+
+/**
+ * Interaction moments passed to `onHaptic` so you can trigger device feedback.
+ * - `'pick-up'` — tile long-press activated (drag started or tile selected).
+ * - `'snap'`    — ghost tile snapped to a new grid position mid-drag.
+ * - `'drop'`    — tile released.
+ * - `'resize'`  — tile resize committed.
+ */
+export type HapticEvent = 'pick-up' | 'snap' | 'drop' | 'resize';
+
+/**
+ * Direction tiles compact toward after every drop.
+ * - `'none'`  — tiles stay exactly where dropped.
+ * - `'up'`    — tiles slide upward to fill empty rows.
+ * - `'left'`  — tiles slide left to fill empty columns.
+ */
+export type Gravity = 'none' | 'up' | 'left';
+
+/** Position and size of a single tile — the serializable unit returned by `serializeLayout`. */
+export type LayoutItem = {
+  /** Tile id — matches the `id` on the original `Tile`. */
+  id: string;
+  /** Current top-left grid position. */
+  position: TilePosition;
+  /** Current size in grid units. */
+  size: TileSize;
+};
+
+/** Array of `LayoutItem` — the format used by `serializeLayout` and `restoreLayout`. */
+export type SerializedLayout = LayoutItem[];

package/src/utils/pixelToGrid.ts

@@ -0,0 +1,31 @@
+import type { GridConfig, TilePosition, TileSize } from '../types';
+import { columnWidth } from '../layout/LayoutCalculator';
+
+/**
+ * Convert an absolute screen position (from gesture handler) to a grid cell,
+ * accounting for the container's page offset and the current scroll position.
+ *
+ * The returned position is clamped so the tile stays within grid bounds.
+ */
+export function pixelToGrid(
+  absX: number,
+  absY: number,
+  containerPageX: number,
+  containerPageY: number,
+  scrollY: number,
+  config: GridConfig,
+  size: TileSize,
+  containerWidth: number
+): TilePosition {
+  const colW = columnWidth(config, containerWidth);
+  const relX = absX - containerPageX - config.padding;
+  const relY = absY - containerPageY + scrollY - config.padding;
+
+  const x = Math.floor(relX / (colW + config.gap));
+  const y = Math.floor(relY / (config.rowHeight + config.gap));
+
+  return {
+    x: Math.max(0, Math.min(x, config.columns - size.w)),
+    y: Math.max(0, y),
+  };
+}