react-native-layout-dnd 0.1.0-alpha.0

package/src/engine/search.ts

@@ -0,0 +1,174 @@
+import type { CellPosition, GridItem, PositionedItem } from '../types';
+
+import { rectanglesOverlap } from './rectangles';
+
+export type PlacementSearchResult<T> =
+  | { status: 'ok'; placements: PositionedItem<T>[]; attempts: number }
+  | { status: 'impossible' | 'unresolved'; attempts: number };
+type PlacementSearchProgress<T> =
+  PlacementSearchResult<T> | { status: 'pending'; attempts: number };
+
+type SearchInput<T> = {
+  items: readonly GridItem<T>[];
+  fixedItems?: readonly PositionedItem<T>[];
+  rows: number;
+  columns: number;
+  searchBudget: number;
+};
+
+function* rowMajorCandidates(
+  maxRow: number,
+  maxCol: number,
+): Generator<CellPosition> {
+  for (let row = 0; row <= maxRow; row++) {
+    for (let col = 0; col <= maxCol; col++) {
+      yield { row, col };
+    }
+  }
+}
+
+/** Distance shells, then row/column order. No grid-sized array or sort. */
+export function* nearestCandidates(
+  maxRow: number,
+  maxCol: number,
+  origin: CellPosition,
+): Generator<CellPosition> {
+  const colReach = Math.max(origin.col, maxCol - origin.col);
+  const maxDistance = Math.min(
+    Number.MAX_SAFE_INTEGER,
+    Math.max(origin.row, maxRow - origin.row) + colReach,
+  );
+  for (let distance = 0; distance <= maxDistance; distance++) {
+    const minRowDistance = Math.max(0, distance - colReach);
+    const firstRow = distance > origin.row ? 0 : origin.row - distance;
+    const lastRow = origin.row + Math.min(distance, maxRow - origin.row);
+    for (let row = firstRow; row <= lastRow; row++) {
+      // Skip the middle of a wide shell when the grid has very few columns.
+      if (Math.abs(row - origin.row) < minRowDistance) {
+        if (minRowDistance > maxRow - origin.row) {
+          break;
+        }
+        row = origin.row + minRowDistance;
+      }
+      if (row > lastRow) {
+        break;
+      }
+      const colDistance = distance - Math.abs(row - origin.row);
+      if (colDistance <= origin.col) {
+        yield { row, col: origin.col - colDistance };
+      }
+      if (colDistance > 0 && colDistance <= maxCol - origin.col) {
+        yield { row, col: origin.col + colDistance };
+      }
+    }
+  }
+}
+
+function exceedsArea<T>(
+  items: readonly GridItem<T>[],
+  fixedItems: readonly PositionedItem<T>[],
+  rows: number,
+  columns: number,
+): boolean {
+  let remaining = rows * columns;
+  // Area is only a shortcut. Avoid a rounded product becoming a proof.
+  if (!Number.isSafeInteger(remaining)) {
+    return false;
+  }
+  for (const group of [fixedItems, items]) {
+    for (const item of group) {
+      const area = item.span.rows * item.span.cols;
+      if (area > remaining) {
+        return true;
+      }
+      remaining -= area;
+    }
+  }
+  return false;
+}
+
+/** Internal: inputs are validated by the caller; fixed rectangles never move. */
+export function createPlacementSearch<T>({
+  items,
+  fixedItems = [],
+  rows,
+  columns,
+  searchBudget,
+}: SearchInput<T>): {
+  advance: (maxAttempts: number) => PlacementSearchProgress<T>;
+} {
+  let attempts = 0;
+  let depth = 0;
+  let terminal: PlacementSearchResult<T> | undefined;
+  const placements: PositionedItem<T>[] = [];
+  const cursors: Generator<CellPosition>[] = [];
+  let nextPosition: CellPosition | undefined;
+
+  if (
+    items.some(item => item.span.rows > rows || item.span.cols > columns) ||
+    exceedsArea(items, fixedItems, rows, columns)
+  ) {
+    terminal = { status: 'impossible', attempts };
+  }
+
+  function createCursor(index: number): Generator<CellPosition> {
+    const item = items[index];
+    const maxRow = rows - item.span.rows;
+    const maxCol = columns - item.span.cols;
+    return rowMajorCandidates(maxRow, maxCol);
+  }
+
+  return {
+    advance(maxAttempts) {
+      if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 0) {
+        throw new RangeError(
+          'Search chunk size must be a nonnegative safe integer.',
+        );
+      }
+      let chunkAttempts = 0;
+      while (!terminal) {
+        if (depth === items.length) {
+          terminal = { status: 'ok', placements, attempts };
+          break;
+        }
+        cursors[depth] ??= createCursor(depth);
+        if (!nextPosition) {
+          const candidate = cursors[depth].next();
+          if (candidate.done) {
+            // Exhaustion is free to inspect: at an exact budget boundary this
+            // distinguishes a proof of impossibility from unfinished search.
+            cursors.pop();
+            if (depth === 0) {
+              terminal = { status: 'impossible', attempts };
+              break;
+            }
+            depth--;
+            placements.pop();
+            continue;
+          }
+          nextPosition = candidate.value;
+        }
+        if (attempts === searchBudget) {
+          terminal = { status: 'unresolved', attempts };
+          break;
+        }
+        if (chunkAttempts === maxAttempts) {
+          return { status: 'pending', attempts };
+        }
+        attempts++;
+        chunkAttempts++;
+        const candidate = { ...items[depth], position: nextPosition };
+        nextPosition = undefined;
+        if (
+          fixedItems.some(item => rectanglesOverlap(candidate, item)) ||
+          placements.some(item => rectanglesOverlap(candidate, item))
+        ) {
+          continue;
+        }
+        placements.push(candidate);
+        depth++;
+      }
+      return terminal;
+    },
+  };
+}

package/src/engine/spatial.ts

@@ -0,0 +1,36 @@
+import type { PositionedItem } from '../types';
+
+import type { GridMovementPolicy } from './movementPolicy';
+import type { PlacementSearchResult } from './search';
+import { exchangeSpatialRegions } from './spatialExchange';
+import { insertSpatialItem } from './spatialInsertion';
+import { rotateSpatialRows } from './spatialRotation';
+import { selectSpatialMove } from './spatialPolicy';
+
+export type SpatialMoveInput<T> = {
+  items: readonly PositionedItem<T>[];
+  active: PositionedItem<T>;
+  /** Original active item, only when the source and target are the same zone. */
+  origin?: PositionedItem<T>;
+  rows: number;
+  columns: number;
+  searchBudget: number;
+  movementPolicy?: GridMovementPolicy;
+};
+
+/** Internal: target input is valid, and items excludes the active item. */
+export function resolveSpatialMove<T>(
+  input: SpatialMoveInput<T>,
+): PlacementSearchResult<T> {
+  const { move, kind, colliders } = selectSpatialMove(input);
+  if (kind === 'row-rotation') return rotateSpatialRows(move)!;
+  if (kind === 'insert') return insertSpatialItem(move, colliders);
+  if (kind === 'exchange') return exchangeSpatialRegions(move);
+  if (kind === 'vacancy')
+    return {
+      status: 'ok',
+      placements: [...move.items, move.active],
+      attempts: 0,
+    };
+  return { status: 'impossible', attempts: 0 };
+}

package/src/engine/spatialAppRotation.ts

@@ -0,0 +1,53 @@
+import { rectanglesOverlap } from './rectangles';
+import type { SpatialMoveInput } from './spatial';
+
+/** Resolve an adjacent app drag through the same move as dragging its widget. */
+export function normalizeAppWidgetMove<T>(
+  input: SpatialMoveInput<T>,
+): SpatialMoveInput<T> | null {
+  'worklet';
+  const { items, active, origin } = input;
+  if (
+    !origin ||
+    active.placement !== 'insert' ||
+    active.span.rows !== 1 ||
+    active.span.cols !== 1
+  )
+    return null;
+
+  const widget = items.find(
+    item => item.placement !== 'insert' && rectanglesOverlap(active, item),
+  );
+  if (!widget) return null;
+  const withinColumns =
+    origin.position.col >= widget.position.col &&
+    origin.position.col < widget.position.col + widget.span.cols;
+  const withinRows =
+    origin.position.row >= widget.position.row &&
+    origin.position.row < widget.position.row + widget.span.rows;
+  const above =
+    withinColumns && origin.position.row === widget.position.row - 1;
+  const below =
+    withinColumns &&
+    origin.position.row === widget.position.row + widget.span.rows;
+  const left = withinRows && origin.position.col === widget.position.col - 1;
+  const right =
+    withinRows &&
+    origin.position.col === widget.position.col + widget.span.cols;
+  if (!above && !below && !left && !right) return null;
+
+  // Restore the picked-up app before resolving the widget's one-cell move.
+  // The ordinary widget policy then owns neighbor movement and boundary checks.
+  return {
+    ...input,
+    items: [...items.filter(item => item !== widget), origin],
+    origin: widget,
+    active: {
+      ...widget,
+      position: {
+        row: widget.position.row + (above ? -1 : below ? 1 : 0),
+        col: widget.position.col + (left ? -1 : right ? 1 : 0),
+      },
+    },
+  };
+}

package/src/engine/spatialExchange.ts

@@ -0,0 +1,212 @@
+import type { CellPosition, CellSpan, PositionedItem } from '../types';
+
+import { rectanglesOverlap } from './rectangles';
+import { nearestCandidates, type PlacementSearchResult } from './search';
+import type { SpatialMoveInput } from './spatial';
+
+type Region = { position: CellPosition; span: CellSpan };
+
+function contains(region: Region, item: Region): boolean {
+  return (
+    item.position.row >= region.position.row &&
+    item.position.col >= region.position.col &&
+    item.position.row - region.position.row <=
+      region.span.rows - item.span.rows &&
+    item.position.col - region.position.col <= region.span.cols - item.span.cols
+  );
+}
+
+/** Include complete target items; expanding one edge may encounter another item. */
+function closeTargetRegion<T>(
+  active: PositionedItem<T>,
+  items: readonly PositionedItem<T>[],
+): Region {
+  let region: Region = { position: active.position, span: active.span };
+  let expanded = true;
+  while (expanded) {
+    expanded = false;
+    for (const item of items) {
+      if (!rectanglesOverlap(region, item) || contains(region, item)) continue;
+      const row = Math.min(region.position.row, item.position.row);
+      const col = Math.min(region.position.col, item.position.col);
+      // Validated items and the active target fit in the zone, so ends stay safe.
+      const endRow = Math.max(
+        region.position.row + region.span.rows,
+        item.position.row + item.span.rows,
+      );
+      const endCol = Math.max(
+        region.position.col + region.span.cols,
+        item.position.col + item.span.cols,
+      );
+      region = {
+        position: { row, col },
+        span: { rows: endRow - row, cols: endCol - col },
+      };
+      expanded = true;
+    }
+  }
+  return region;
+}
+
+function translated<T>(
+  item: PositionedItem<T>,
+  from: Region,
+  to: Region,
+): PositionedItem<T> {
+  return {
+    ...item,
+    position: {
+      row: to.position.row + (item.position.row - from.position.row),
+      col: to.position.col + (item.position.col - from.position.col),
+    },
+  };
+}
+
+/**
+ * Rotate entering items through an overlapping translation into the vacated edge.
+ * A whole item must follow one cycle; an item whose cells would split is rejected.
+ */
+function exchangeOverlappingRegions<T>(
+  items: readonly PositionedItem<T>[],
+  active: PositionedItem<T>,
+  origin: PositionedItem<T>,
+  target: Region,
+): PlacementSearchResult<T> {
+  const attempts = 1;
+  // Expanded mixed-item regions have no unambiguous overlapping source region.
+  if (
+    target.position.row !== active.position.row ||
+    target.position.col !== active.position.col ||
+    target.span.rows !== active.span.rows ||
+    target.span.cols !== active.span.cols
+  )
+    return { status: 'impossible', attempts };
+
+  const rowStep = origin.position.row - active.position.row;
+  const colStep = origin.position.col - active.position.col;
+  const placements: PositionedItem<T>[] = [];
+  for (const item of items) {
+    if (!rectanglesOverlap(target, item)) {
+      placements.push(item);
+      continue;
+    }
+    // Compute the first translation wholly outside the target, without a loop
+    // proportional to grid dimensions (which may be very large safe integers).
+    const rowSteps =
+      rowStep > 0
+        ? Math.ceil(
+            (target.position.row + target.span.rows - item.position.row) /
+              rowStep,
+          )
+        : rowStep < 0
+          ? Math.ceil(
+              (item.position.row + item.span.rows - target.position.row) /
+                -rowStep,
+            )
+          : Infinity;
+    const colSteps =
+      colStep > 0
+        ? Math.ceil(
+            (target.position.col + target.span.cols - item.position.col) /
+              colStep,
+          )
+        : colStep < 0
+          ? Math.ceil(
+              (item.position.col + item.span.cols - target.position.col) /
+                -colStep,
+            )
+          : Infinity;
+    const steps = Math.min(rowSteps, colSteps);
+    const moved = {
+      ...item,
+      position: {
+        row: item.position.row + steps * rowStep,
+        col: item.position.col + steps * colStep,
+      },
+    };
+    if (
+      !Number.isSafeInteger(moved.position.row) ||
+      !Number.isSafeInteger(moved.position.col) ||
+      !contains(origin, moved) ||
+      rectanglesOverlap(target, moved)
+    )
+      return { status: 'impossible', attempts };
+    // Containment in origin = target + step also means the entire previous
+    // translation was inside target. Thus no part of this item exits early.
+    // These cycles are disjoint and origin contains no other original items.
+    placements.push(moved);
+  }
+  placements.push(active);
+  return { status: 'ok', placements, attempts };
+}
+
+/** Exchange equal regions, preserving whole items and their empty cells. */
+export function exchangeSpatialRegions<T>({
+  items,
+  active,
+  origin,
+  rows,
+  columns,
+  searchBudget,
+}: SpatialMoveInput<T>): PlacementSearchResult<T> {
+  if (!origin) return { status: 'impossible', attempts: 0 };
+  const target = closeTargetRegion(active, items);
+  if (rectanglesOverlap(origin, active))
+    return exchangeOverlappingRegions(items, active, origin, target);
+  const firstRow = Math.max(
+    0,
+    origin.position.row - (target.span.rows - origin.span.rows),
+  );
+  const firstCol = Math.max(
+    0,
+    origin.position.col - (target.span.cols - origin.span.cols),
+  );
+  const lastRow = Math.min(origin.position.row, rows - target.span.rows);
+  const lastCol = Math.min(origin.position.col, columns - target.span.cols);
+  // Choosing a source near this anchor puts the active item near its requested
+  // target. Clamping each axis adds a constant distance to every valid candidate.
+  const preferred = {
+    row: origin.position.row + (target.position.row - active.position.row),
+    col: origin.position.col + (target.position.col - active.position.col),
+  };
+  const candidates = nearestCandidates(lastRow - firstRow, lastCol - firstCol, {
+    row: Math.max(firstRow, Math.min(lastRow, preferred.row)) - firstRow,
+    col: Math.max(firstCol, Math.min(lastCol, preferred.col)) - firstCol,
+  });
+  let attempts = 0;
+  for (const position of candidates) {
+    if (attempts === searchBudget) return { status: 'unresolved', attempts };
+    attempts++;
+    const source: Region = {
+      position: {
+        row: firstRow + position.row,
+        col: firstCol + position.col,
+      },
+      span: target.span,
+    };
+    if (rectanglesOverlap(source, target)) continue;
+    if (
+      items.some(
+        item => rectanglesOverlap(source, item) && !contains(source, item),
+      )
+    )
+      continue;
+
+    // Each touched item is wholly contained in exactly one disjoint region.
+    // Translation therefore cannot collide with fixed items or lose any holes.
+    const placements = items.map(item => {
+      if (contains(source, item)) return translated(item, source, target);
+      if (contains(target, item)) return translated(item, target, source);
+      return item;
+    });
+    const moved = translated(origin, source, target);
+    placements.push(
+      moved.position.row === active.position.row &&
+        moved.position.col === active.position.col
+        ? active
+        : moved,
+    );
+    return { status: 'ok', placements, attempts };
+  }
+  return { status: 'impossible', attempts };
+}

package/src/engine/spatialInsertion.ts

@@ -0,0 +1,157 @@
+import type { CellPosition, CellSpan, PositionedItem } from '../types';
+
+import { rectanglesOverlap } from './rectangles';
+import type { PlacementSearchResult } from './search';
+import type { SpatialMoveInput } from './spatial';
+
+function comparePositions(left: CellPosition, right: CellPosition): number {
+  return left.row - right.row || left.col - right.col;
+}
+
+function isSlotAligned(item: PositionedItem<unknown>, span: CellSpan): boolean {
+  return (
+    item.span.rows === span.rows &&
+    item.span.cols === span.cols &&
+    item.position.row % span.rows === 0 &&
+    item.position.col % span.cols === 0
+  );
+}
+
+function withPosition<T>(
+  item: PositionedItem<T>,
+  position: CellPosition,
+): PositionedItem<T> {
+  return { ...item, position: { ...position } };
+}
+
+function applyInsertion<T>(
+  items: readonly PositionedItem<T>[],
+  active: PositionedItem<T>,
+  moved: ReadonlyMap<string, PositionedItem<T>>,
+  attempts: number,
+): PlacementSearchResult<T> {
+  return {
+    status: 'ok',
+    placements: [...items.map(item => moved.get(item.id) ?? item), active],
+    attempts,
+  };
+}
+
+/** Shift intervening occupied slots; keep the requested target even when it was empty. */
+function insertWithinZone<T>(
+  {
+    items,
+    active,
+    origin,
+  }: SpatialMoveInput<T> & {
+    origin: PositionedItem<T>;
+  },
+  vacantTarget = false,
+): PlacementSearchResult<T> {
+  const forward = comparePositions(origin.position, active.position) < 0;
+  const start = forward ? origin.position : active.position;
+  const end = forward ? active.position : origin.position;
+  const displaced = items
+    .filter(
+      item =>
+        item.placement === 'insert' &&
+        comparePositions(item.position, start) >= 0 &&
+        comparePositions(item.position, end) <= 0,
+    )
+    .sort((left, right) =>
+      forward
+        ? comparePositions(left.position, right.position)
+        : comparePositions(right.position, left.position),
+    );
+  if (
+    !isSlotAligned(active, active.span) ||
+    !isSlotAligned(origin, active.span) ||
+    displaced.some(item => !isSlotAligned(item, active.span))
+  ) {
+    // An empty target remains usable even when larger insertion items do not
+    // share aligned slots. Only compatible slots participate in insertion.
+    if (vacantTarget)
+      return { status: 'ok', placements: [...items, active], attempts: 0 };
+    return { status: 'impossible', attempts: 1 };
+  }
+  let vacant = origin.position;
+  const moved = new Map<string, PositionedItem<T>>();
+  for (const item of displaced) {
+    moved.set(item.id, withPosition(item, vacant));
+    vacant = item.position;
+  }
+  return applyInsertion(items, active, moved, 1);
+}
+
+/** An incoming item shifts insertion slots forward until a free slot is reached. */
+function insertFromAnotherZone<T>({
+  items,
+  active,
+  rows,
+  columns,
+  searchBudget,
+}: SpatialMoveInput<T>): PlacementSearchResult<T> {
+  const displaced: PositionedItem<T>[] = [];
+  const maxRow = rows - active.span.rows;
+  const maxCol = columns - active.span.cols;
+  let { row, col } = active.position;
+  let attempts = 0;
+  while (row <= maxRow) {
+    if (attempts === searchBudget) return { status: 'unresolved', attempts };
+    attempts++;
+    const slot = { span: active.span, position: { row, col } };
+    const occupants = items.filter(item => rectanglesOverlap(item, slot));
+    if (occupants.length === 0) {
+      const moved = new Map<string, PositionedItem<T>>();
+      for (let index = 0; index < displaced.length; index++) {
+        moved.set(
+          displaced[index].id,
+          withPosition(
+            displaced[index],
+            displaced[index + 1]?.position ?? slot.position,
+          ),
+        );
+      }
+      return applyInsertion(items, active, moved, attempts);
+    }
+    if (
+      occupants.some(
+        item =>
+          item.placement === 'insert' && !isSlotAligned(item, active.span),
+      )
+    )
+      return { status: 'impossible', attempts };
+    if (occupants.length === 1 && occupants[0].placement === 'insert') {
+      displaced.push(occupants[0]);
+    }
+    // Do not multiply the number of rows and columns or increment past safe ends.
+    if (col <= maxCol - active.span.cols) {
+      col += active.span.cols;
+    } else if (row <= maxRow - active.span.rows) {
+      row += active.span.rows;
+      col = 0;
+    } else {
+      break;
+    }
+  }
+  return { status: 'impossible', attempts };
+}
+
+export function insertSpatialItem<T>(
+  input: SpatialMoveInput<T>,
+  colliders: readonly PositionedItem<T>[],
+): PlacementSearchResult<T> {
+  const { active, origin } = input;
+  if (origin && colliders.length === 0)
+    return insertWithinZone({ ...input, origin }, true);
+  if (
+    colliders.length !== 1 ||
+    !isSlotAligned(active, active.span) ||
+    !isSlotAligned(colliders[0], active.span) ||
+    comparePositions(colliders[0].position, active.position) !== 0
+  )
+    return { status: 'impossible', attempts: 0 };
+  return origin
+    ? insertWithinZone({ ...input, origin })
+    : insertFromAnotherZone(input);
+}

package/src/engine/spatialPolicy.ts

@@ -0,0 +1,48 @@
+import { DEFAULT_GRID_MOVEMENT_POLICY } from './movementPolicy';
+import type { GridMoveCandidate } from './movementPolicy';
+import { rectanglesOverlap } from './rectangles';
+import type { SpatialMoveInput } from './spatial';
+import { normalizeAppWidgetMove } from './spatialAppRotation';
+
+/** Shared rule selection only: no packing, search, or caller callbacks on the UI thread. */
+export function selectSpatialMove<T>(input: SpatialMoveInput<T>) {
+  'worklet';
+  const policy = input.movementPolicy ?? DEFAULT_GRID_MOVEMENT_POLICY;
+  const move =
+    policy.adjacentInsertExchange === 'single-cell'
+      ? (normalizeAppWidgetMove(input) ?? input)
+      : input;
+  const { active, origin, items, columns } = move;
+  const colliders = items.filter(item => rectanglesOverlap(active, item));
+  let kind: GridMoveCandidate | 'vacancy' | 'blocked' =
+    colliders.length === 0 ? 'vacancy' : 'blocked';
+  for (const candidate of policy.candidateOrder ??
+    DEFAULT_GRID_MOVEMENT_POLICY.candidateOrder) {
+    if (
+      candidate === 'row-rotation' &&
+      policy.rowRotation === 'full-width' &&
+      origin &&
+      active.placement !== 'insert' &&
+      active.span.cols === columns &&
+      active.position.col === origin.position.col &&
+      active.position.row !== origin.position.row
+    ) {
+      kind = candidate;
+      break;
+    }
+    if (
+      candidate === 'insert' &&
+      active.placement === 'insert' &&
+      (origin !== undefined || colliders.length > 0) &&
+      colliders.every(item => item.placement === 'insert')
+    ) {
+      kind = candidate;
+      break;
+    }
+    if (candidate === 'exchange' && colliders.length > 0) {
+      kind = candidate;
+      break;
+    }
+  }
+  return { move, kind, colliders };
+}