@griddle/core 0.1.0

package/src/compaction.ts

@@ -0,0 +1,80 @@
+// Compaction (gravity) — pull tiles toward a configured edge or anchor cell.
+//
+// Runs after moves/adds/removes when gravity is not 'none'. Iteratively moves
+// each tile one step toward the gravity anchor until no tile can move any closer.
+
+import type { CellPos, CellRect, Gravity, Tile } from './types.js';
+import type { Grid } from './grid.js';
+import { rectsOverlap, tileRect } from './geometry.js';
+import { isInFlow } from './positioning.js';
+
+export function compact(grid: Grid): string[] {
+  const gravity = grid.config.gravity ?? 'none';
+  if (gravity === 'none') return [];
+
+  const moved = new Set<string>();
+  // Iteratively move tiles one cell toward anchor; stop when no tile moves.
+  for (let iter = 0; iter < 10_000; iter++) {
+    let anyMoved = false;
+
+    // Order tiles so that those closest to the anchor move first — otherwise
+    // a further tile may try to move into a cell not yet vacated by the closer
+    // one. Out-of-flow tiles (absolute/fixed) are skipped entirely by gravity.
+    const ordered = [...grid.tiles]
+      .filter((t) => isInFlow(t))
+      .sort((a, b) =>
+        distanceToAnchor(a, gravity) - distanceToAnchor(b, gravity),
+      );
+
+    for (const t of ordered) {
+      const step = stepToward(t, gravity);
+      if (!step) continue;
+      const newRect: CellRect = {
+        col: t.col + step.dx,
+        row: t.row + step.dy,
+        w: t.w,
+        h: t.h,
+      };
+      if (!grid.rectInBounds(newRect)) continue;
+      const overlap = grid.tiles.filter(
+        (o) => o.id !== t.id && isInFlow(o) && rectsOverlap(tileRect(o), newRect),
+      );
+      if (overlap.length > 0) continue;
+      grid._setTilePos(t.id, { col: newRect.col, row: newRect.row });
+      moved.add(t.id);
+      anyMoved = true;
+    }
+
+    if (!anyMoved) break;
+  }
+
+  return Array.from(moved);
+}
+
+function stepToward(t: Tile, gravity: Gravity): { dx: number; dy: number } | null {
+  if (gravity === 'none') return null;
+  if (gravity === 'top') return t.row > 0 ? { dx: 0, dy: -1 } : null;
+  if (gravity === 'left') return t.col > 0 ? { dx: -1, dy: 0 } : null;
+  if (gravity === 'bottom') return { dx: 0, dy: 1 };
+  if (gravity === 'right') return { dx: 1, dy: 0 };
+  // Anchor cell
+  const dx = Math.sign(gravity.col - t.col);
+  const dy = Math.sign(gravity.row - t.row);
+  // Move along the axis with the greater distance first so we take the shortest path.
+  const adx = Math.abs(gravity.col - t.col);
+  const ady = Math.abs(gravity.row - t.row);
+  if (adx === 0 && dy === 0) return null;
+  if (adx >= ady && dx !== 0) return { dx, dy: 0 };
+  if (dy !== 0) return { dx: 0, dy };
+  if (dx !== 0) return { dx, dy: 0 };
+  return null;
+}
+
+function distanceToAnchor(t: Tile, gravity: Gravity): number {
+  if (gravity === 'none') return 0;
+  if (gravity === 'top') return t.row;
+  if (gravity === 'bottom') return -t.row;
+  if (gravity === 'left') return t.col;
+  if (gravity === 'right') return -t.col;
+  return Math.abs(gravity.col - t.col) + Math.abs(gravity.row - t.row);
+}

package/src/drag.ts

@@ -0,0 +1,146 @@
+// DragController — live-preview state machine for drag-to-rearrange.
+//
+// Models the storyboard semantics: as the user drags a tile, the engine
+// continuously runs the candidate move against a snapshot of the grid taken
+// at pickup. Whenever the cursor crosses a cell boundary, any prior preview
+// is rewound and the new candidate is attempted. The dragged tile and any
+// displaced victims animate into their new positions via the adapter's FLIP
+// loop while the drag is still in progress; on release the latest preview
+// is committed. If the user releases over an invalid cell (out of bounds or
+// rejected by the move engine), the snapshot is restored.
+//
+// This module is pure cell-space — pixel-to-cell conversion is the adapter's
+// responsibility. That keeps the core engine free of any DOM concepts.
+
+import type { CellPos, Tile } from './types.js';
+import type { Grid } from './grid.js';
+
+type Snapshot = Map<string, Tile>;
+
+export interface DragUpdateResult {
+  /** Whether the most recent candidate cell was successfully committed. */
+  committed: boolean;
+  /** Cell where the drop indicator should render (null if no valid target). */
+  indicatorCell: CellPos | null;
+  /** Did the candidate cell change since the previous update? */
+  changed: boolean;
+}
+
+/**
+ * Holds the snapshot/preview state for a single drag gesture. One controller
+ * instance can be reused across drags — call `start()` to begin a new gesture
+ * and `end()` or `cancel()` to finish.
+ */
+export class DragController {
+  private grid: Grid;
+  private tileId: string | null = null;
+  private snapshot: Snapshot | null = null;
+  private pickup: CellPos = { col: 0, row: 0 };
+  private lastCandidate: CellPos | null = null;
+  private lastCommitted: CellPos | null = null;
+
+  constructor(grid: Grid) {
+    this.grid = grid;
+  }
+
+  /** True if a drag gesture is currently in progress. */
+  isActive(): boolean {
+    return this.tileId !== null;
+  }
+
+  /** ID of the tile currently being dragged, or null. */
+  draggerId(): string | null {
+    return this.tileId;
+  }
+
+  /** Cell where the drag was picked up (the dragger's pre-drag position). */
+  pickupCell(): CellPos {
+    return { col: this.pickup.col, row: this.pickup.row };
+  }
+
+  /**
+   * Begin a drag gesture for `tileId`. Snapshots the grid so we can rewind on
+   * each candidate change. Returns false if the tile doesn't exist.
+   */
+  start(tileId: string): boolean {
+    const tile = this.grid.getTile(tileId);
+    if (!tile) return false;
+    this.tileId = tileId;
+    this.snapshot = this.grid.snapshotTiles();
+    this.pickup = { col: tile.col, row: tile.row };
+    this.lastCandidate = { col: tile.col, row: tile.row };
+    this.lastCommitted = { col: tile.col, row: tile.row };
+    return true;
+  }
+
+  /**
+   * The cursor is now over `candidate`. If it's the same cell as last update,
+   * this is a no-op. If it changed, rewind any prior preview and attempt the
+   * new candidate. Returns the resulting render hints.
+   */
+  update(candidate: CellPos): DragUpdateResult {
+    if (!this.tileId || !this.snapshot) {
+      return { committed: false, indicatorCell: null, changed: false };
+    }
+
+    const same =
+      this.lastCandidate !== null &&
+      this.lastCandidate.col === candidate.col &&
+      this.lastCandidate.row === candidate.row;
+    if (same) {
+      return {
+        committed: this.lastCommitted !== null,
+        indicatorCell: this.lastCommitted,
+        changed: false,
+      };
+    }
+    this.lastCandidate = { col: candidate.col, row: candidate.row };
+
+    // Always rewind to pickup state before attempting the new candidate, so
+    // each preview is independent and we can't compound errors.
+    this.grid.restoreTiles(this.snapshot);
+
+    if (candidate.col === this.pickup.col && candidate.row === this.pickup.row) {
+      // Back at pickup — nothing to commit, indicator at pickup.
+      this.lastCommitted = { col: this.pickup.col, row: this.pickup.row };
+      return { committed: true, indicatorCell: this.lastCommitted, changed: true };
+    }
+
+    const ok = this.grid.moveTile(this.tileId, candidate);
+    this.lastCommitted = ok ? { col: candidate.col, row: candidate.row } : null;
+    return {
+      committed: ok,
+      indicatorCell: this.lastCommitted,
+      changed: true,
+    };
+  }
+
+  /**
+   * End the drag. The current preview state stays committed if it was a valid
+   * move; otherwise the snapshot is restored. Returns the final state.
+   */
+  end(): { committed: boolean; finalCell: CellPos | null } {
+    const result = {
+      committed: this.lastCommitted !== null,
+      finalCell: this.lastCommitted,
+    };
+    // If the last attempt was rejected, ensure we're back at the original state.
+    if (!this.lastCommitted && this.snapshot) {
+      this.grid.restoreTiles(this.snapshot);
+    }
+    this.tileId = null;
+    this.snapshot = null;
+    this.lastCandidate = null;
+    this.lastCommitted = null;
+    return result;
+  }
+
+  /** Abort the drag and restore the pre-drag grid state. */
+  cancel(): void {
+    if (this.snapshot) this.grid.restoreTiles(this.snapshot);
+    this.tileId = null;
+    this.snapshot = null;
+    this.lastCandidate = null;
+    this.lastCommitted = null;
+  }
+}

package/src/events.ts

@@ -0,0 +1,25 @@
+// Minimal event emitter — no dependencies.
+
+export type Listener<T> = (payload: T) => void;
+
+export class Emitter<T> {
+  private listeners = new Set<Listener<T>>();
+
+  on(fn: Listener<T>): () => void {
+    this.listeners.add(fn);
+    return () => this.listeners.delete(fn);
+  }
+
+  off(fn: Listener<T>): void {
+    this.listeners.delete(fn);
+  }
+
+  emit(payload: T): void {
+    // Copy to array so listeners can safely unsubscribe during emit.
+    for (const l of Array.from(this.listeners)) l(payload);
+  }
+
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/geometry.ts

@@ -0,0 +1,199 @@
+// Rect / footprint / priority math. Pure functions only — no state.
+
+import type {
+  CellPos,
+  CellRect,
+  Direction8,
+  Face,
+  Corner,
+  Footprint,
+  Tile,
+} from './types.js';
+
+/** Does rect `a` overlap rect `b`? */
+export function rectsOverlap(a: CellRect, b: CellRect): boolean {
+  return (
+    a.col < b.col + b.w &&
+    a.col + a.w > b.col &&
+    a.row < b.row + b.h &&
+    a.row + a.h > b.row
+  );
+}
+
+/** Does rect `outer` fully contain rect `inner`? */
+export function rectContains(outer: CellRect, inner: CellRect): boolean {
+  return (
+    inner.col >= outer.col &&
+    inner.row >= outer.row &&
+    inner.col + inner.w <= outer.col + outer.w &&
+    inner.row + inner.h <= outer.row + outer.h
+  );
+}
+
+export function rectEquals(a: CellRect, b: CellRect): boolean {
+  return a.col === b.col && a.row === b.row && a.w === b.w && a.h === b.h;
+}
+
+/** Two tiles are "adjacent" if their rects share at least a corner touch (8-neighbor). */
+export function rectsAdjacent(a: CellRect, b: CellRect): boolean {
+  if (rectsOverlap(a, b)) return false;
+  const horizTouch =
+    (a.col + a.w === b.col || b.col + b.w === a.col) &&
+    a.row < b.row + b.h &&
+    a.row + a.h > b.row;
+  const vertTouch =
+    (a.row + a.h === b.row || b.row + b.h === a.row) &&
+    a.col < b.col + b.w &&
+    a.col + a.w > b.col;
+  const cornerTouch =
+    (a.col + a.w === b.col || b.col + b.w === a.col) &&
+    (a.row + a.h === b.row || b.row + b.h === a.row);
+  return horizTouch || vertTouch || cornerTouch;
+}
+
+export function tileRect(t: Tile): CellRect {
+  return { col: t.col, row: t.row, w: t.w, h: t.h };
+}
+
+/** Delta from origin's center to target's center, both as cell centers. */
+function centerDelta(origin: CellRect, target: CellRect): { dx: number; dy: number } {
+  const ox = origin.col + origin.w / 2;
+  const oy = origin.row + origin.h / 2;
+  const tx = target.col + target.w / 2;
+  const ty = target.row + target.h / 2;
+  return { dx: tx - ox, dy: ty - oy };
+}
+
+/** Face closest to origin from target's perspective. */
+export function faceClosestToOrigin(origin: CellRect, target: CellRect): Face {
+  const { dx, dy } = centerDelta(origin, target);
+  // target->origin: negate
+  const ox = -dx;
+  const oy = -dy;
+  if (Math.abs(ox) >= Math.abs(oy)) {
+    return ox >= 0 ? 'e' : 'w';
+  }
+  return oy >= 0 ? 's' : 'n';
+}
+
+/** Opposite face. */
+export function oppositeFace(f: Face): Face {
+  if (f === 'n') return 's';
+  if (f === 's') return 'n';
+  if (f === 'e') return 'w';
+  return 'e';
+}
+
+/** Classify origin -> target geometry. */
+export type OriginKind = 'horizontal' | 'vertical' | 'corner';
+export function classifyOrigin(origin: CellRect, target: CellRect): OriginKind {
+  const { dx, dy } = centerDelta(origin, target);
+  const horiz = Math.abs(dx) > 1e-9;
+  const vert = Math.abs(dy) > 1e-9;
+  if (horiz && vert) return 'corner';
+  if (horiz) return 'horizontal';
+  return 'vertical';
+}
+
+/** Is corner `c` on the side of origin? */
+function cornerDistToOrigin(
+  origin: CellRect,
+  target: CellRect,
+  c: Corner,
+): number {
+  // Corner position as the center of the 1x1 slot diagonally adjacent.
+  const cx =
+    c === 'nw' || c === 'sw'
+      ? target.col - 0.5
+      : target.col + target.w + 0.5;
+  const cy =
+    c === 'nw' || c === 'ne'
+      ? target.row - 0.5
+      : target.row + target.h + 0.5;
+  const ox = origin.col + origin.w / 2;
+  const oy = origin.row + origin.h / 2;
+  const dx = cx - ox;
+  const dy = cy - oy;
+  return dx * dx + dy * dy;
+}
+
+/**
+ * Return the 8 displacement directions for a tile at `target` being pushed
+ * by a drag originating at `origin`, ordered by the priority spec.
+ */
+export function priorityDirections(origin: CellRect, target: CellRect): Direction8[] {
+  const faceClosest = faceClosestToOrigin(origin, target);
+  const faceOpposite = oppositeFace(faceClosest);
+  const kind = classifyOrigin(origin, target);
+
+  // 3rd priority: upwards face if origin horizontal, right face otherwise
+  // but excluding already-chosen faces
+  const allFaces: Face[] = ['n', 's', 'e', 'w'];
+  const used = new Set<Face>([faceClosest, faceOpposite]);
+  let third: Face;
+  if (kind === 'horizontal') {
+    third = used.has('n') ? pickRemaining(allFaces, used) : 'n';
+  } else {
+    third = used.has('e') ? pickRemaining(allFaces, used) : 'e';
+  }
+  used.add(third);
+  const fourth = pickRemaining(allFaces, used);
+
+  // Corners: rank closest-2 then furthest-2
+  const corners: Corner[] = ['nw', 'ne', 'sw', 'se'];
+  const cornerRanked = corners
+    .map((c) => ({ c, d: cornerDistToOrigin(origin, target, c) }))
+    .sort((a, b) => a.d - b.d);
+  const closeCorners = cornerRanked.slice(0, 2).map((x) => x.c);
+  const farCorners = cornerRanked.slice(2).map((x) => x.c);
+
+  return [
+    faceClosest,
+    faceOpposite,
+    third,
+    fourth,
+    closeCorners[0]!,
+    closeCorners[1]!,
+    farCorners[0]!,
+    farCorners[1]!,
+  ];
+}
+
+function pickRemaining(all: Face[], used: Set<Face>): Face {
+  for (const f of all) if (!used.has(f)) return f;
+  return all[0]!;
+}
+
+/** Translate a rect by a direction (one unit). */
+export function translateRect(r: CellRect, dir: Direction8): CellRect {
+  let dcol = 0;
+  let drow = 0;
+  if (dir === 'n' || dir === 'nw' || dir === 'ne') drow = -1;
+  if (dir === 's' || dir === 'sw' || dir === 'se') drow = 1;
+  if (dir === 'w' || dir === 'nw' || dir === 'sw') dcol = -1;
+  if (dir === 'e' || dir === 'ne' || dir === 'se') dcol = 1;
+  return { col: r.col + dcol, row: r.row + drow, w: r.w, h: r.h };
+}
+
+/** Translate by arbitrary cell offset. */
+export function offsetRect(
+  r: CellRect,
+  dcol: number,
+  drow: number,
+): CellRect {
+  return { col: r.col + dcol, row: r.row + drow, w: r.w, h: r.h };
+}
+
+/** Stepwise offset for a direction (dx, dy in cells, -1..1). */
+export function directionStep(dir: Direction8): { dx: number; dy: number } {
+  const r = translateRect({ col: 0, row: 0, w: 0, h: 0 }, dir);
+  return { dx: r.col, dy: r.row };
+}
+
+export function footprintEquals(a: Footprint, b: Footprint): boolean {
+  return a.w === b.w && a.h === b.h;
+}
+
+export function clonePos(p: CellPos): CellPos {
+  return { col: p.col, row: p.row };
+}