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

package/src/engine/move.ts

@@ -0,0 +1,274 @@
+import {
+  diagnosticNow,
+  type DiagnosticObserver,
+  emitDiagnostic,
+  type TimingDiagnostic,
+} from '../diagnostics';
+import { DEFAULT_SEARCH_BUDGET } from '../defaults';
+import type {
+  GridItem,
+  GridValue,
+  GridZone,
+  ItemLocation,
+  MoveInput,
+  MoveResult,
+  PositionedItem,
+  ValidationIssue,
+} from '../types';
+
+import { hasSameLayout } from './sameLayout';
+import { validateGridMovementPolicy } from './movementPolicy';
+import { resolveSpatialMove } from './spatial';
+import {
+  isCellPosition,
+  isPositiveInteger,
+  isRecord,
+  validateValue,
+} from './validation';
+
+function invalid<T>(
+  code: ValidationIssue['code'],
+  message: string,
+  ids: Pick<ValidationIssue, 'itemId' | 'zoneId'> = {},
+): MoveResult<T> {
+  return { status: 'invalid', issues: [{ code, message, ...ids }] };
+}
+
+/**
+ * Compute one atomic candidate from the input snapshot. The engine remembers no
+ * earlier preview; the session decides whether that snapshot is the committed
+ * value or the latest same-zone preview. Drop permission, pointer geometry,
+ * sessions and animation belong to the controller.
+ */
+export function computeMove<T>(
+  input: MoveInput<T>,
+  onDiagnostic?: DiagnosticObserver,
+): MoveResult<T> {
+  if (typeof onDiagnostic !== 'function') return calculateMove(input);
+  const timings: TimingDiagnostic[] = [];
+  const startedAt = diagnosticNow();
+  let result: MoveResult<T> | undefined;
+  try {
+    result = calculateMove(input, timings);
+    return result;
+  } finally {
+    timings.push({
+      type: 'timing',
+      name: 'compute-move',
+      durationMs: diagnosticNow() - startedAt,
+      status: result?.status ?? 'error',
+      ...(result && 'attempts' in result ? { attempts: result.attempts } : {}),
+    });
+    // Deliver after the calculation so observer cost is not part of its timing.
+    for (const event of timings) emitDiagnostic(onDiagnostic, event);
+  }
+}
+
+function timedValidation<T>(
+  value: GridValue<T>,
+  name: 'input-validation' | 'candidate-validation',
+  timings: TimingDiagnostic[],
+) {
+  const startedAt = diagnosticNow();
+  const result = validateValue(value);
+  timings.push({
+    type: 'timing',
+    name,
+    durationMs: diagnosticNow() - startedAt,
+    status: result.valid ? 'valid' : 'invalid',
+  });
+  return result;
+}
+
+function calculateMove<T>(
+  input: MoveInput<T>,
+  timings?: TimingDiagnostic[],
+): MoveResult<T> {
+  if (!isRecord(input))
+    return invalid('invalid-structure', 'Expected a move input object.');
+  const validation = timings
+    ? timedValidation(input.value, 'input-validation', timings)
+    : validateValue(input.value);
+  if (!validation.valid)
+    return { status: 'invalid', issues: validation.issues };
+  const policyValidation = validateGridMovementPolicy(input.movementPolicy);
+  if (!policyValidation.valid)
+    return { status: 'invalid', issues: policyValidation.issues };
+  const searchBudget =
+    input.searchBudget === undefined
+      ? DEFAULT_SEARCH_BUDGET
+      : input.searchBudget;
+  if (!isPositiveInteger(searchBudget))
+    return invalid(
+      'invalid-budget',
+      'searchBudget must be a positive safe integer.',
+    );
+  if (typeof input.itemId !== 'string')
+    return invalid('invalid-structure', 'itemId must be a string.');
+  const { value, itemId, to } = input;
+  if (!isRecord(to) || typeof to.zoneId !== 'string')
+    return invalid('invalid-structure', 'A target zone is required.', {
+      itemId,
+    });
+
+  const source = value.zones.find(zone =>
+    zone.items.some(item => item.id === itemId),
+  );
+  const target = value.zones.find(zone => zone.id === to.zoneId);
+  if (!source || !target)
+    return invalid(
+      'invalid-structure',
+      'The item and target zone must exist.',
+      {
+        itemId,
+        zoneId: to.zoneId,
+      },
+    );
+  if (to.strategy !== target.strategy)
+    return invalid(
+      'invalid-structure',
+      'Target strategy must match its zone.',
+      {
+        itemId,
+        zoneId: target.id,
+      },
+    );
+
+  const sourceIndex = source.items.findIndex(item => item.id === itemId);
+  const active = source.items[sourceIndex];
+  const from: ItemLocation =
+    source.strategy === 'ordered'
+      ? { zoneId: source.id, strategy: 'ordered', index: sourceIndex }
+      : {
+          zoneId: source.id,
+          strategy: 'spatial',
+          position: source.items[sourceIndex].position,
+        };
+  const sameZone = source.id === target.id;
+  let nextTarget: GridZone<T>;
+  let resolvedTo = to as ItemLocation;
+  let attempts = 0;
+
+  if (target.strategy === 'ordered' && to.strategy === 'ordered') {
+    const remaining = target.items.filter(item => item.id !== itemId);
+    if (
+      !Number.isSafeInteger(to.index) ||
+      to.index < 0 ||
+      to.index > remaining.length
+    )
+      return invalid(
+        'invalid-position',
+        'Insertion index must address the array after removal.',
+        {
+          itemId,
+          zoneId: target.id,
+        },
+      );
+    const slotsPerRow = Math.floor(target.columns / target.itemSpan.cols);
+    const slotRows = Math.floor(target.rows / target.itemSpan.rows);
+    if (
+      active.span.rows !== target.itemSpan.rows ||
+      active.span.cols !== target.itemSpan.cols ||
+      slotsPerRow === 0 ||
+      slotRows === 0 ||
+      Math.ceil((remaining.length + 1) / slotsPerRow) > slotRows
+    )
+      return { status: 'impossible', attempts };
+    // Spatial position has no meaning in an ordered zone. Preserve opaque data by reference.
+    const inserted: GridItem<T> = {
+      id: active.id,
+      span: active.span,
+      ...(active.placement === undefined
+        ? {}
+        : { placement: active.placement }),
+      data: active.data,
+    };
+    remaining.splice(to.index, 0, inserted);
+    nextTarget = { ...target, items: remaining };
+  } else if (target.strategy === 'spatial' && to.strategy === 'spatial') {
+    if (!isCellPosition(to.position))
+      return invalid(
+        'invalid-position',
+        'A spatial target requires safe integer coordinates.',
+        {
+          itemId,
+          zoneId: target.id,
+        },
+      );
+    if (
+      to.position.row < 0 ||
+      to.position.col < 0 ||
+      to.position.row > target.rows - active.span.rows ||
+      to.position.col > target.columns - active.span.cols
+    )
+      return { status: 'impossible', attempts };
+    const moved: PositionedItem<T> = {
+      id: active.id,
+      span: active.span,
+      ...(active.placement === undefined
+        ? {}
+        : { placement: active.placement }),
+      data: active.data,
+      position: { ...to.position },
+    };
+    const result = resolveSpatialMove({
+      items: target.items.filter(item => item.id !== itemId),
+      active: moved,
+      origin:
+        sameZone && source.strategy === 'spatial'
+          ? source.items[sourceIndex]
+          : undefined,
+      rows: target.rows,
+      columns: target.columns,
+      searchBudget,
+      movementPolicy: input.movementPolicy,
+    });
+    if (result.status !== 'ok') return result;
+    attempts = result.attempts;
+    const placements = new Map(result.placements.map(item => [item.id, item]));
+    resolvedTo = {
+      zoneId: target.id,
+      strategy: 'spatial',
+      position: placements.get(itemId)!.position,
+    };
+    const items = target.items.map(item => placements.get(item.id)!);
+    if (!sameZone) items.push(placements.get(itemId)!);
+    nextTarget = { ...target, items };
+  } else {
+    return invalid('invalid-structure', 'Unsupported target strategy.', {
+      itemId,
+    });
+  }
+
+  const zones = value.zones.map(zone => {
+    if (zone.id === target.id) return nextTarget;
+    if (zone.id !== source.id) return zone;
+    const remaining = { ...zone };
+    remaining.items = zone.items.filter(item => item.id !== itemId);
+    return remaining;
+  });
+  // Deliberately omit the previous proposalResponse from every candidate.
+  const nextValue: GridValue<T> = { zones };
+  const candidateValidation = timings
+    ? timedValidation(nextValue, 'candidate-validation', timings)
+    : validateValue(nextValue);
+  if (!candidateValidation.valid)
+    return { status: 'invalid', issues: candidateValidation.issues };
+  const changed = !hasSameLayout(value, nextValue);
+  if (value.revision !== undefined) {
+    if (changed && value.revision === Number.MAX_SAFE_INTEGER)
+      return invalid(
+        'invalid-configuration',
+        'The layout revision cannot exceed a safe integer.',
+      );
+    nextValue.revision = value.revision + Number(changed);
+  }
+  return {
+    status: 'ok',
+    value: changed ? nextValue : { ...nextValue, zones: value.zones },
+    from,
+    to: resolvedTo,
+    changed,
+    attempts,
+  };
+}

package/src/engine/movementPolicy.ts

@@ -0,0 +1,151 @@
+import type { ValidationResult } from '../types';
+
+export type GridMoveCandidate = 'row-rotation' | 'insert' | 'exchange';
+
+/** Declarative configuration shared by the JS engine and UI worklets. */
+export type GridMovementPolicy = {
+  /** Full-width exchange items may rotate every item in their vertical corridor. */
+  rowRotation?: 'disabled' | 'full-width';
+  /** Home compatibility: a one-cell insert item can pull an adjacent exchange item. */
+  adjacentInsertExchange?: 'disabled' | 'single-cell';
+  /** First applicable rule wins. Rejection never falls through to another rule. */
+  candidateOrder?: readonly GridMoveCandidate[];
+  pointer?: {
+    /** Extra distance beyond half a cell pitch, in [0, 0.5]. Default 0.12. */
+    cellHysteresis?: number;
+    /** Cell-pitch fraction required when displacing exchange items, in [0.5, 1]. */
+    exchangeThreshold?: number;
+    /** Zone entry and ordered-slot margin in React Native logical pixels. */
+    boundaryHysteresis?: number;
+  };
+};
+
+export type ResolvedGridMovementPolicy = {
+  rowRotation: NonNullable<GridMovementPolicy['rowRotation']>;
+  adjacentInsertExchange: NonNullable<
+    GridMovementPolicy['adjacentInsertExchange']
+  >;
+  candidateOrder: readonly GridMoveCandidate[];
+  pointer: Required<NonNullable<GridMovementPolicy['pointer']>>;
+};
+
+const DEFAULT_CANDIDATES: readonly GridMoveCandidate[] = Object.freeze([
+  'row-rotation',
+  'insert',
+  'exchange',
+]);
+
+/** Neutral placement rules; caller data and item size never imply home behavior. */
+export const DEFAULT_GRID_MOVEMENT_POLICY: ResolvedGridMovementPolicy =
+  Object.freeze({
+    rowRotation: 'disabled',
+    adjacentInsertExchange: 'disabled',
+    candidateOrder: DEFAULT_CANDIDATES,
+    pointer: Object.freeze({
+      cellHysteresis: 0.12,
+      exchangeThreshold: 0.8,
+      boundaryHysteresis: 4,
+    }),
+  });
+
+/** Explicit compatibility with the extracted home grid's reversible movements. */
+export const HOME_GRID_MOVEMENT_POLICY: ResolvedGridMovementPolicy =
+  Object.freeze({
+    ...DEFAULT_GRID_MOVEMENT_POLICY,
+    rowRotation: 'full-width',
+    adjacentInsertExchange: 'single-cell',
+  });
+
+/** Copy configuration when starting a session so later caller edits cannot change it. */
+export function resolveGridMovementPolicy(
+  policy?: GridMovementPolicy,
+): ResolvedGridMovementPolicy {
+  'worklet';
+  return {
+    rowRotation:
+      policy?.rowRotation ?? DEFAULT_GRID_MOVEMENT_POLICY.rowRotation,
+    adjacentInsertExchange:
+      policy?.adjacentInsertExchange ??
+      DEFAULT_GRID_MOVEMENT_POLICY.adjacentInsertExchange,
+    candidateOrder: [
+      ...(policy?.candidateOrder ??
+        DEFAULT_GRID_MOVEMENT_POLICY.candidateOrder),
+    ],
+    pointer: {
+      cellHysteresis:
+        policy?.pointer?.cellHysteresis ??
+        DEFAULT_GRID_MOVEMENT_POLICY.pointer.cellHysteresis,
+      exchangeThreshold:
+        policy?.pointer?.exchangeThreshold ??
+        DEFAULT_GRID_MOVEMENT_POLICY.pointer.exchangeThreshold,
+      boundaryHysteresis:
+        policy?.pointer?.boundaryHysteresis ??
+        DEFAULT_GRID_MOVEMENT_POLICY.pointer.boundaryHysteresis,
+    },
+  };
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** Invalid policies reject the complete move before any candidate is computed. */
+export function validateGridMovementPolicy(policy: unknown): ValidationResult {
+  if (policy === undefined) return { valid: true };
+  const invalid = (message: string): ValidationResult => ({
+    valid: false,
+    issues: [{ code: 'invalid-configuration', message }],
+  });
+  if (!record(policy)) return invalid('movementPolicy must be an object.');
+  if (
+    policy.rowRotation !== undefined &&
+    policy.rowRotation !== 'disabled' &&
+    policy.rowRotation !== 'full-width'
+  )
+    return invalid(
+      'movementPolicy.rowRotation must be disabled or full-width.',
+    );
+  if (
+    policy.adjacentInsertExchange !== undefined &&
+    policy.adjacentInsertExchange !== 'disabled' &&
+    policy.adjacentInsertExchange !== 'single-cell'
+  )
+    return invalid(
+      'movementPolicy.adjacentInsertExchange must be disabled or single-cell.',
+    );
+  if (
+    policy.candidateOrder !== undefined &&
+    (!Array.isArray(policy.candidateOrder) ||
+      policy.candidateOrder.length === 0 ||
+      Array.from(policy.candidateOrder).some(
+        candidate => !DEFAULT_CANDIDATES.includes(candidate),
+      ) ||
+      new Set(policy.candidateOrder).size !== policy.candidateOrder.length)
+  )
+    return invalid(
+      'movementPolicy.candidateOrder must contain distinct supported candidates.',
+    );
+  if (policy.pointer !== undefined) {
+    if (!record(policy.pointer))
+      return invalid('movementPolicy.pointer must be an object.');
+    const limits = {
+      cellHysteresis: [0, 0.5],
+      exchangeThreshold: [0.5, 1],
+      boundaryHysteresis: [0, Infinity],
+    };
+    for (const [key, [min, max]] of Object.entries(limits)) {
+      const value = policy.pointer[key];
+      if (
+        value !== undefined &&
+        (typeof value !== 'number' ||
+          !Number.isFinite(value) ||
+          value < min ||
+          value > max)
+      )
+        return invalid(
+          `movementPolicy.pointer.${key} must be finite and between ${min} and ${max}.`,
+        );
+    }
+  }
+  return { valid: true };
+}

package/src/engine/orderedTarget.ts

@@ -0,0 +1,131 @@
+import type { CellSpan, ValidationIssue } from '../types';
+
+import { isCellSpan, isPositiveInteger, isRecord } from './validation';
+
+export type OrderedIndexInput = {
+  rows: number;
+  columns: number;
+  itemSpan: CellSpan;
+  /** Target item count after removing the active item for a same-zone move. */
+  itemCount: number;
+  /** Moving item's center, relative to the target content origin (without padding). */
+  center: { x: number; y: number };
+  cellWidth: number;
+  cellHeight: number;
+  rowGap: number;
+  columnGap: number;
+};
+export type OrderedIndexResult =
+  | { status: 'ok'; index: number }
+  | { status: 'impossible' }
+  | { status: 'invalid'; issues: ValidationIssue[] };
+
+/**
+ * Raw ordered boundary. The caller first hit-tests the pointer against actual zones,
+ * removes the active item, and then applies the same hysteresis for preview and drop.
+ */
+export function computeOrderedIndex(
+  input: OrderedIndexInput,
+): OrderedIndexResult {
+  const fail = (
+    code: ValidationIssue['code'],
+    message: string,
+  ): OrderedIndexResult => ({
+    status: 'invalid',
+    issues: [{ code, message }],
+  });
+  if (!isRecord(input))
+    return fail('invalid-structure', 'Expected ordered target geometry.');
+  if (!isPositiveInteger(input.rows) || !isPositiveInteger(input.columns))
+    return fail(
+      'invalid-dimension',
+      'Grid dimensions must be positive safe integers.',
+    );
+  if (input.itemSpan === undefined)
+    return fail('missing-item-span', 'Ordered targeting requires itemSpan.');
+  if (!isCellSpan(input.itemSpan))
+    return fail(
+      'invalid-span',
+      'itemSpan must contain positive safe integers.',
+    );
+  if (!Number.isSafeInteger(input.itemCount) || input.itemCount < 0)
+    return fail(
+      'invalid-structure',
+      'itemCount must be a non-negative safe integer.',
+    );
+  if (
+    !isRecord(input.center) ||
+    !Number.isFinite(input.center.x) ||
+    !Number.isFinite(input.center.y) ||
+    !Number.isFinite(input.cellWidth) ||
+    input.cellWidth <= 0 ||
+    !Number.isFinite(input.cellHeight) ||
+    input.cellHeight <= 0 ||
+    !Number.isFinite(input.rowGap) ||
+    input.rowGap < 0 ||
+    !Number.isFinite(input.columnGap) ||
+    input.columnGap < 0
+  )
+    return fail(
+      'invalid-geometry',
+      'Center, cell sizes and gaps must be finite valid geometry.',
+    );
+
+  const {
+    rows,
+    columns,
+    itemSpan,
+    itemCount,
+    cellWidth,
+    cellHeight,
+    rowGap,
+    columnGap,
+  } = input;
+  const slotsPerRow = Math.floor(columns / itemSpan.cols);
+  const slotRows = Math.floor(rows / itemSpan.rows);
+  const width = columns * cellWidth + (columns - 1) * columnGap;
+  const height = rows * cellHeight + (rows - 1) * rowGap;
+  const slotWidth = itemSpan.cols * cellWidth + (itemSpan.cols - 1) * columnGap;
+  const slotHeight = itemSpan.rows * cellHeight + (itemSpan.rows - 1) * rowGap;
+  const strideX = slotWidth + columnGap;
+  const strideY = slotHeight + rowGap;
+  if (
+    ![width, height, slotWidth, slotHeight, strideX, strideY].every(
+      n => Number.isFinite(n) && n > 0,
+    )
+  )
+    return fail(
+      'invalid-geometry',
+      'Computed content and slot dimensions must be finite and positive.',
+    );
+  if (!slotsPerRow || !slotRows) return { status: 'impossible' };
+  if (Math.ceil(itemCount / slotsPerRow) > slotRows)
+    return fail('capacity-exceeded', 'itemCount exceeds the ordered capacity.');
+  const x = Math.max(0, Math.min(width, input.center.x));
+  const y = Math.max(0, Math.min(height, input.center.y));
+
+  // Unfillable bottom rows are after the whole array, including a partly filled last row.
+  if (rows % itemSpan.rows !== 0 && y >= slotRows * strideY - rowGap)
+    return { status: 'ok', index: itemCount };
+  const row = Math.max(
+    0,
+    Math.min(slotRows - 1, Math.floor((y - slotHeight / 2) / strideY + 0.5)),
+  );
+  // Right-hand remainder belongs to this row's end, not the whole array's end.
+  if (columns % itemSpan.cols !== 0 && x >= slotsPerRow * strideX - columnGap)
+    return {
+      status: 'ok',
+      index: Math.min(itemCount, (row + 1) * slotsPerRow),
+    };
+  const col = Math.max(
+    0,
+    Math.min(slotsPerRow - 1, Math.floor((x - slotWidth / 2) / strideX + 0.5)),
+  );
+  const slot = row * slotsPerRow + col;
+  if (slot >= itemCount) return { status: 'ok', index: itemCount };
+  const after =
+    slotsPerRow === 1
+      ? y >= row * strideY + slotHeight / 2
+      : x >= col * strideX + slotWidth / 2;
+  return { status: 'ok', index: Math.min(itemCount, slot + Number(after)) };
+}

package/src/engine/pack.ts

@@ -0,0 +1,24 @@
+import type { PackInput, PackResult } from '../types';
+
+import { createPlacementSearch } from './search';
+import { validatePackInput } from './validation';
+
+export function packItems<T>(input: PackInput<T>): PackResult<T> {
+  const validation = validatePackInput(input);
+  if (!validation.valid) {
+    return { status: 'invalid', issues: validation.issues };
+  }
+  const result = createPlacementSearch({
+    items: input.items,
+    rows: input.rows,
+    columns: input.columns,
+    searchBudget: input.searchBudget,
+  }).advance(input.searchBudget);
+  if (result.status === 'ok') {
+    return { status: 'ok', placements: result.placements };
+  }
+  // A chunk containing the entire global budget always resolves its status.
+  return {
+    status: result.status === 'impossible' ? 'impossible' : 'unresolved',
+  };
+}

package/src/engine/rectangles.ts

@@ -0,0 +1,18 @@
+import type { CellPosition, CellSpan } from '../types';
+
+type CellRectangle = { position: CellPosition; span: CellSpan };
+
+/** Internal: rectangles have validated nonnegative anchors and positive spans. */
+export function rectanglesOverlap(a: CellRectangle, b: CellRectangle): boolean {
+  'worklet';
+  // Anchor differences stay exact without adding a span to a large coordinate.
+  const rowsOverlap =
+    a.position.row <= b.position.row
+      ? b.position.row - a.position.row < a.span.rows
+      : a.position.row - b.position.row < b.span.rows;
+  const colsOverlap =
+    a.position.col <= b.position.col
+      ? b.position.col - a.position.col < a.span.cols
+      : a.position.col - b.position.col < b.span.cols;
+  return rowsOverlap && colsOverlap;
+}

package/src/engine/sameLayout.ts

@@ -0,0 +1,50 @@
+import type { GridValue, GridZone } from '../types';
+
+function sameZone<T>(a: GridZone<T>, b: GridZone<T>): boolean {
+  if (
+    a.strategy !== b.strategy ||
+    a.rows !== b.rows ||
+    a.columns !== b.columns ||
+    a.items.length !== b.items.length
+  )
+    return false;
+  if (a.strategy === 'ordered' && b.strategy === 'ordered') {
+    return (
+      a.itemSpan.rows === b.itemSpan.rows &&
+      a.itemSpan.cols === b.itemSpan.cols &&
+      a.items.every((item, index) => {
+        const other = b.items[index];
+        return (
+          item.id === other.id &&
+          (item.placement ?? 'exchange') === (other.placement ?? 'exchange') &&
+          item.span.rows === other.span.rows &&
+          item.span.cols === other.span.cols
+        );
+      })
+    );
+  }
+  if (a.strategy !== 'spatial' || b.strategy !== 'spatial') return false;
+  const byId = new Map(b.items.map(item => [item.id, item]));
+  return a.items.every(item => {
+    const other = byId.get(item.id);
+    return (
+      other !== undefined &&
+      (item.placement ?? 'exchange') === (other.placement ?? 'exchange') &&
+      item.span.rows === other.span.rows &&
+      item.span.cols === other.span.cols &&
+      item.position.row === other.position.row &&
+      item.position.col === other.position.col
+    );
+  });
+}
+
+/** Compare validated layouts. Data, responses and spatial array order are not layout. */
+export function hasSameLayout<T>(a: GridValue<T>, b: GridValue<T>): boolean {
+  if (a === b) return true;
+  if (a.zones.length !== b.zones.length) return false;
+  const byId = new Map(b.zones.map(zone => [zone.id, zone]));
+  return a.zones.every(zone => {
+    const other = byId.get(zone.id);
+    return other !== undefined && sameZone(zone, other);
+  });
+}