@griddle/core 0.1.0

package/src/repack.ts

@@ -0,0 +1,212 @@
+// 0-1 BFS repack solver.
+//
+// Called when Rules 1-5 fail and the grid has no infinite axis available for
+// the Rule-6 push direction. We search for a sequence of single-cell tile moves
+// that frees `target` for the dragged tile, preferring sequences with the fewest
+// total displacements (0-1 BFS: an edge that moves a tile into a previously-empty
+// cell costs 0, an edge that displaces another tile costs 1).
+//
+// This is bounded by `config.maxRepackHops` — if we can't solve within budget,
+// the move is rejected.
+//
+// Search state is the full positions-map of all tiles. To keep it manageable we:
+//   - only move tiles that are in the "affected set" (tiles we've had to touch)
+//   - limit move-candidate directions per tile to the 8 priority directions
+//   - use a stringified key of the positions of the affected set for visited checks.
+
+import type { CellPos, CellRect, Direction8, Tile } from './types.js';
+import type { Grid } from './grid.js';
+import {
+  directionStep,
+  priorityDirections,
+  rectsOverlap,
+  tileRect,
+} from './geometry.js';
+
+interface SearchState {
+  /** Positions of every tile, keyed by id. */
+  positions: Map<string, CellPos>;
+  /** Tiles we've displaced in the search so far. */
+  touched: Set<string>;
+  /** Accumulated cost (number of unique tiles moved). */
+  cost: number;
+}
+
+export function solvePushBFS(
+  grid: Grid,
+  tileId: string,
+  target: CellPos,
+  originRect: CellRect,
+): boolean {
+  const drag = grid.getTile(tileId);
+  if (!drag) return false;
+
+  const tilesArr = grid.tiles;
+  const byId = new Map<string, Tile>(tilesArr.map((t) => [t.id, t]));
+  const targetRect: CellRect = {
+    col: target.col,
+    row: target.row,
+    w: drag.w,
+    h: drag.h,
+  };
+  const priorityDirs = priorityDirections(originRect, targetRect);
+  const maxHops = grid.config.maxRepackHops ?? 64;
+
+  // Initial state: real grid positions.
+  const initial: SearchState = {
+    positions: new Map(
+      tilesArr.map((t) => [t.id, { col: t.col, row: t.row } as CellPos]),
+    ),
+    touched: new Set(),
+    cost: 0,
+  };
+
+  const visited = new Map<string, number>(); // key -> best cost
+
+  // 0-1 BFS uses a deque: 0-cost edges push_front, 1-cost edges push_back.
+  const deque: SearchState[] = [initial];
+
+  const goalSatisfied = (s: SearchState): boolean => {
+    for (const [id, pos] of s.positions) {
+      if (id === tileId) continue;
+      const t = byId.get(id)!;
+      const rect: CellRect = { col: pos.col, row: pos.row, w: t.w, h: t.h };
+      if (rectsOverlap(rect, targetRect)) return false;
+    }
+    return true;
+  };
+
+  while (deque.length > 0) {
+    const s = deque.shift()!;
+    const key = stateKey(s.positions, s.touched);
+    const prev = visited.get(key);
+    if (prev !== undefined && prev <= s.cost) continue;
+    visited.set(key, s.cost);
+
+    if (goalSatisfied(s)) {
+      // Commit. Apply all positions back to the grid, then move the dragger.
+      for (const [id, pos] of s.positions) {
+        if (id === tileId) continue;
+        grid._setTilePos(id, pos);
+      }
+      grid._setTilePos(tileId, target);
+      return true;
+    }
+
+    if (s.cost >= maxHops) continue;
+
+    // Find an overlapper on targetRect — that's what we must dislodge this step.
+    let occupier: Tile | null = null;
+    for (const [id, pos] of s.positions) {
+      if (id === tileId) continue;
+      const t = byId.get(id)!;
+      const rect: CellRect = { col: pos.col, row: pos.row, w: t.w, h: t.h };
+      if (rectsOverlap(rect, targetRect)) {
+        occupier = t;
+        break;
+      }
+    }
+    if (!occupier) continue;
+
+    // Try priority directions on the occupier.
+    for (const dir of priorityDirs) {
+      const child = tryMoveInState(
+        s,
+        occupier.id,
+        dir,
+        byId,
+        grid,
+        tileId,
+      );
+      if (!child) continue;
+      const wasTouched = s.touched.has(occupier.id);
+      const edgeCost = wasTouched ? 0 : 1;
+      const newCost = s.cost + edgeCost;
+      const nextKey = stateKey(child.positions, child.touched);
+      const prevBest = visited.get(nextKey);
+      if (prevBest !== undefined && prevBest <= newCost) continue;
+      child.cost = newCost;
+      if (edgeCost === 0) deque.unshift(child);
+      else deque.push(child);
+    }
+
+    // Also allow moving a *chain* overlapper — if the occupier can't be moved directly,
+    // try pushing a neighbor tile to free up its destination. Iterate all touched or
+    // occupier-adjacent tiles and try each in a priority direction.
+    const candidates = new Set<string>([occupier.id, ...s.touched]);
+    for (const candId of candidates) {
+      if (candId === tileId) continue;
+      for (const dir of priorityDirs) {
+        const child = tryMoveInState(s, candId, dir, byId, grid, tileId);
+        if (!child) continue;
+        const wasTouched = s.touched.has(candId);
+        const edgeCost = wasTouched ? 0 : 1;
+        const newCost = s.cost + edgeCost;
+        const nextKey = stateKey(child.positions, child.touched);
+        const prevBest = visited.get(nextKey);
+        if (prevBest !== undefined && prevBest <= newCost) continue;
+        child.cost = newCost;
+        if (edgeCost === 0) deque.unshift(child);
+        else deque.push(child);
+      }
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Attempt to move `moveId` one cell in `dir` in the given state. Returns a new
+ * state on success or null if the move is blocked (out of bounds or would overlap
+ * a non-moveable tile). For simplicity we only allow a single tile move per step;
+ * if another tile is in the way, that becomes the next BFS node to address rather
+ * than being recursively pushed here.
+ */
+function tryMoveInState(
+  s: SearchState,
+  moveId: string,
+  dir: Direction8,
+  byId: Map<string, Tile>,
+  grid: Grid,
+  draggerId: string,
+): SearchState | null {
+  const pos = s.positions.get(moveId);
+  if (!pos) return null;
+  const t = byId.get(moveId)!;
+  const { dx, dy } = directionStep(dir);
+  const newRect: CellRect = {
+    col: pos.col + dx,
+    row: pos.row + dy,
+    w: t.w,
+    h: t.h,
+  };
+  if (!grid.rectInBounds(newRect)) return null;
+
+  // Must not overlap any other tile (except self and the dragger's original spot — dragger is "floating")
+  for (const [id, p] of s.positions) {
+    if (id === moveId || id === draggerId) continue;
+    const ot = byId.get(id)!;
+    const oRect: CellRect = { col: p.col, row: p.row, w: ot.w, h: ot.h };
+    if (rectsOverlap(oRect, newRect)) return null;
+  }
+
+  const nextPositions = new Map(s.positions);
+  nextPositions.set(moveId, { col: newRect.col, row: newRect.row });
+  const nextTouched = new Set(s.touched);
+  nextTouched.add(moveId);
+  return {
+    positions: nextPositions,
+    touched: nextTouched,
+    cost: s.cost, // caller sets
+  };
+}
+
+function stateKey(positions: Map<string, CellPos>, touched: Set<string>): string {
+  const parts: string[] = [];
+  const ids = Array.from(positions.keys()).sort();
+  for (const id of ids) {
+    const p = positions.get(id)!;
+    parts.push(`${id}:${p.col},${p.row}`);
+  }
+  return parts.join('|') + '#' + Array.from(touched).sort().join(',');
+}

package/src/types.ts

@@ -0,0 +1,262 @@
+// Griddle core types
+// Zero runtime dependencies. Everything consumers touch is plain JSON-serializable.
+
+/** A corner identifier, used for resize handles. */
+export type Corner = 'nw' | 'ne' | 'sw' | 'se';
+
+/** Face direction. */
+export type Face = 'n' | 's' | 'e' | 'w';
+
+/** Priority slot direction returned by movement priority calc. */
+export type Direction8 = Face | Corner;
+
+/** Compaction / gravity target. */
+export type Gravity =
+  | 'none'
+  | 'top'
+  | 'bottom'
+  | 'left'
+  | 'right'
+  | { col: number; row: number };
+
+/** A grid position in cells. */
+export interface CellPos {
+  col: number;
+  row: number;
+}
+
+/** Footprint of a tile in cells. */
+export interface Footprint {
+  w: number;
+  h: number;
+}
+
+/**
+ * CSS-like positioning mode for a tile. Default 'static'.
+ *
+ * - static   - normal grid tile; participates in displacement and compaction.
+ * - relative - keeps its grid slot; renders with a visual offset that doesn't
+ *              affect layout. Other tiles still treat its grid cell as taken.
+ * - absolute - out of grid flow. Pinned at coordinates given by 'pinned'.
+ *              Other tiles can occupy its col/row. Engine ignores it.
+ * - fixed    - like absolute but anchored to the scrollable container's
+ *              viewport, so it stays put when the grid scrolls.
+ * - sticky   - in flow normally, but pins to a viewport edge once scrolled
+ *              past the configured threshold.
+ *
+ * Requires GridConfig.enablePositioning = true to take effect; otherwise
+ * adapters render every tile as static.
+ */
+export type TilePosition =
+  | 'static'
+  | 'relative'
+  | 'absolute'
+  | 'fixed'
+  | 'sticky';
+
+/** Edge a sticky tile pins to. */
+export type StickyEdge = 'top' | 'bottom' | 'left' | 'right';
+
+export interface StickyConfig {
+  /** Edge of the scroll viewport to stick to. */
+  edge: StickyEdge;
+  /** Distance from the edge in CSS pixels. Default 0. */
+  threshold?: number;
+}
+
+/** Tile state stored in the grid. */
+export interface Tile extends CellPos, Footprint {
+  /** Stable, unique string id. */
+  id: string;
+  /** Arbitrary consumer payload - not interpreted by core. */
+  data?: unknown;
+  /** If set, overrides the grid-level resize handles for this tile. */
+  resizeHandles?: Corner[];
+  /** If false, the tile cannot be dragged. Defaults to true. */
+  draggable?: boolean;
+  /** If false, the tile cannot be resized. Defaults to true. */
+  resizable?: boolean;
+  /** Min/max footprint clamps for resize. */
+  minW?: number;
+  minH?: number;
+  maxW?: number;
+  maxH?: number;
+  /** CSS-like positioning mode. Defaults to 'static'. */
+  position?: TilePosition;
+  /** For absolute/fixed: pinned coordinates (units per GridConfig.pinUnits). */
+  pinned?: { x: number; y: number };
+  /** For relative: visual offset that does NOT affect layout (units per GridConfig.relativeUnits). */
+  offset?: { x: number; y: number };
+  /** For sticky: edge + pixel threshold from that edge. */
+  sticky?: StickyConfig;
+}
+
+/**
+ * Physics knobs for drag-to-pan in loop mode. All rates are per-second so
+ * behavior is frame-rate independent.
+ */
+export interface LoopPhysicsConfig {
+  /**
+   * Whether drag-to-pan is active. Default true. In 'edit' mode tiles capture
+   * their own pointer drags, so drag-to-pan only engages from the background.
+   */
+  dragPan?: boolean;
+  /**
+   * Exponential decay rate of the inertia velocity after release (1/s).
+   * Higher stops sooner. Default 4.
+   */
+  friction?: number;
+  /**
+   * Rate at which the camera eases toward its target (1/s). Higher feels
+   * stiffer / more direct. Default 12.
+   */
+  ease?: number;
+  /** Clamp on fling velocity, in px/s. Default 6000. */
+  maxVelocity?: number;
+}
+
+/**
+ * Loop mode: the packed content (bounding box of the in-flow tiles) repeats
+ * infinitely in both axes ("object looping" — tiles wrap around the camera so
+ * the plane has no edges). There is no native scrolling: the viewport is
+ * overflow-hidden and wheel/drag input drives a transform camera.
+ *
+ * The loop off->on toggle (and only that toggle) packs tiles into a dense
+ * block so repeats are seamless; already-dense layouts are kept as arranged.
+ * Packing is independent of all other layout strategies — it never runs on
+ * tile moves, drags, creates, resizes, snapshot loads, or toggling loop off
+ * (the packed layout simply persists).
+ * Requires finite cols/rows; incompatible with infiniteX/infiniteY.
+ */
+export interface LoopConfig {
+  /** Master switch, like gravity. Default false. */
+  enabled: boolean;
+  /**
+   * - 'pan'  — view-only gallery: dragging anywhere pans the camera (with the
+   *            physics below); tile drag/resize/draw-create are disabled.
+   * - 'edit' — "ghost edit": the base copy of the content is an ordinary,
+   *            non-wrapped grid surface with normal drag/resize semantics;
+   *            the surrounding repeats render live but are non-interactive
+   *            (pointer-transparent ghosts). The camera moves via wheel or
+   *            by dragging anywhere outside the base copy.
+   * Default 'pan'.
+   */
+  interaction?: 'pan' | 'edit';
+  /**
+   * How repeats are laid out relative to each other:
+   * - 'grid'  — repeats aligned in both axes (default).
+   * - 'brick' — each successive repeat row shifts horizontally by
+   *             `offset` x period width (running-bond brickwork).
+   * - 'drop'  — each successive repeat column shifts vertically by
+   *             `offset` x period height (half-drop wallpaper).
+   */
+  pattern?: 'grid' | 'brick' | 'drop';
+  /**
+   * Shift fraction for 'brick'/'drop' patterns, 0..1 of the period (rounded
+   * to whole cells). 0.5 = classic half-brick / half-drop; other fractions
+   * produce staircase / diagonal tessellations. Default 0.5.
+   */
+  offset?: number;
+  /**
+   * When packing runs (see Grid.pack):
+   * - 'toggle'     — only on the loop off->on transition (default).
+   * - 'structural' — additionally after resize / add / remove while looping
+   *                  (never after plain moves, so arrangements made by
+   *                  dragging are not shuffled).
+   */
+  repack?: 'toggle' | 'structural';
+  /** Pan physics tuning. Only meaningful for 'pan' interaction. */
+  physics?: LoopPhysicsConfig;
+}
+
+/** Grid configuration. */
+export interface GridConfig {
+  /** Columns. Use Infinity for horizontally infinite canvas. */
+  cols: number;
+  /** Rows. Use Infinity for vertically infinite canvas. */
+  rows: number;
+  /** Width of one cell, in CSS pixels. */
+  unitWidth: number;
+  /** Height of one cell, in CSS pixels. */
+  unitHeight: number;
+  /** Explicit infinite flags (auto-inferred from cols/rows === Infinity otherwise). */
+  infiniteX?: boolean;
+  infiniteY?: boolean;
+  /** Optional pixel gap between cells (purely visual). */
+  gap?: number;
+  /** Compaction / gravity target. Default 'none'. */
+  gravity?: Gravity;
+  /** Default corner handles shown on tiles. Default ['se']. */
+  resizeHandles?: Corner[];
+  /** Whether the tile snaps to grid cells during drag. Default true. */
+  snapDuringDrag?: boolean;
+  /** Max hops for the 0-1 BFS repack fallback on fixed grids. Default 64. */
+  maxRepackHops?: number;
+  /**
+   * Border radius applied to each tile (and the drop indicator), in CSS
+   * pixels. Default 4. The adapter exposes this on the content container as
+   * the CSS custom property `--griddle-tile-radius`, so tile content
+   * components can read it with `var(--griddle-tile-radius)` to stay in sync.
+   */
+  tileRadius?: number;
+  /**
+   * Master switch for CSS-like tile positioning. When true, tiles can use
+   * the 'position' field (and 'pinned' / 'offset' / 'sticky'). When false
+   * (the default), adapters render every tile in static grid flow regardless
+   * of any 'position' value set on the tile data.
+   */
+  enablePositioning?: boolean;
+  /**
+   * Coordinate units used by 'pinned' on absolute / fixed tiles. Default
+   * 'pixels'. 'subcell' measures in cells with float precision (e.g.
+   * { x: 3.5, y: 2.25 }); 'cells' measures in whole-cell coordinates.
+   */
+  pinUnits?: 'pixels' | 'subcell' | 'cells';
+  /**
+   * Units used by 'offset' on relative tiles. Default 'pixels'. 'subcell'
+   * measures in cells with float precision so the offset scales with cell size.
+   */
+  relativeUnits?: 'pixels' | 'subcell';
+  /**
+   * CSS selector string passed to `Element.closest()` on the pointer-down
+   * target. If the target matches, the drag is suppressed so the element's
+   * native interaction (click, focus, text selection, etc.) works normally.
+   *
+   * Default: `'a, button, input, textarea, select, [contenteditable]'`
+   *
+   * Set to `''` to disable (entire tile surface starts a drag). Consumers
+   * can extend the default with app-specific selectors, e.g.
+   * `'a, button, input, textarea, select, [contenteditable], .my-caption'`.
+   */
+  dragIgnoreFrom?: string;
+  /**
+   * Loop mode — the finite grid tiles repeat infinitely in both axes.
+   * Off by default. See LoopConfig.
+   */
+  loop?: LoopConfig;
+}
+
+/** A rectangle in cells (inclusive col,row; exclusive col+w,row+h). */
+export interface CellRect extends CellPos, Footprint {}
+
+/** Event payload for change notifications. */
+export interface GridChangeEvent {
+  type:
+    | 'config'
+    | 'add'
+    | 'remove'
+    | 'move'
+    | 'resize'
+    | 'repack'
+    | 'compact'
+    | 'load';
+  /** Tile ids affected by this event (for animation diffing). */
+  tileIds: string[];
+}
+
+/** Serialized grid snapshot. */
+export interface GridSnapshot {
+  version: 1;
+  config: GridConfig;
+  tiles: Tile[];
+}

package/src/virtualize.ts

@@ -0,0 +1,77 @@
+// Virtualization helpers. Given a viewport (px) and scroll offset (px), compute
+// the range of cells that are visible plus a buffer. The adapters use this to
+// decide which tiles to actually render.
+
+import type { CellRect, GridConfig, Tile } from './types.js';
+import { rectsOverlap } from './geometry.js';
+
+export interface Viewport {
+  /** Pixel offset of the viewport relative to the grid origin (0,0 cell). */
+  scrollX: number;
+  scrollY: number;
+  /** Pixel size of the viewport. */
+  width: number;
+  height: number;
+}
+
+export interface VisibleRange extends CellRect {}
+
+/** Compute the visible cell rect for a given viewport, padded by `buffer` cells. */
+export function visibleRange(
+  config: GridConfig,
+  vp: Viewport,
+  buffer = 2,
+): VisibleRange {
+  const colSize = config.unitWidth + (config.gap ?? 0);
+  const rowSize = config.unitHeight + (config.gap ?? 0);
+  const col0 = Math.max(0, Math.floor(vp.scrollX / colSize) - buffer);
+  const row0 = Math.max(0, Math.floor(vp.scrollY / rowSize) - buffer);
+  const col1 = Math.ceil((vp.scrollX + vp.width) / colSize) + buffer;
+  const row1 = Math.ceil((vp.scrollY + vp.height) / rowSize) + buffer;
+
+  const maxCol = config.infiniteX || config.cols === Infinity ? col1 : Math.min(col1, config.cols);
+  const maxRow = config.infiniteY || config.rows === Infinity ? row1 : Math.min(row1, config.rows);
+
+  return {
+    col: col0,
+    row: row0,
+    w: Math.max(0, maxCol - col0),
+    h: Math.max(0, maxRow - row0),
+  };
+}
+
+/**
+ * Filter tiles to only those overlapping the visible range. Tiles that are NOT
+ * laid out by their grid cell (`absolute`, `fixed`, `sticky`) are always
+ * included — their on-screen position is independent of their `col/row`, so
+ * filtering by cell-overlap would incorrectly cull them when the user scrolls
+ * past their natural cell.
+ */
+export function visibleTiles(tiles: Tile[], range: VisibleRange): Tile[] {
+  return tiles.filter((t) => {
+    if (t.position && t.position !== 'static' && t.position !== 'relative') {
+      return true;
+    }
+    return rectsOverlap({ col: t.col, row: t.row, w: t.w, h: t.h }, range);
+  });
+}
+
+/** Compute the total pixel size of the grid content (for scroll container sizing). */
+export function gridContentSize(
+  config: GridConfig,
+  tiles: Tile[],
+): { width: number; height: number } {
+  const gap = config.gap ?? 0;
+  const colSize = config.unitWidth + gap;
+  const rowSize = config.unitHeight + gap;
+  let maxCol = config.infiniteX || config.cols === Infinity ? 0 : config.cols;
+  let maxRow = config.infiniteY || config.rows === Infinity ? 0 : config.rows;
+  for (const t of tiles) {
+    maxCol = Math.max(maxCol, t.col + t.w + 2);
+    maxRow = Math.max(maxRow, t.row + t.h + 2);
+  }
+  return {
+    width: maxCol * colSize,
+    height: maxRow * rowSize,
+  };
+}