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

package/src/runtime/dndRuntime.ts

@@ -0,0 +1,311 @@
+import {
+  createContext,
+  type ReactNode,
+  useContext,
+  useMemo,
+  useSyncExternalStore,
+} from 'react';
+import type { HostInstance } from 'react-native';
+import {
+  measure,
+  type AnimatedRef,
+  type SharedValue,
+} from 'react-native-reanimated';
+
+import type { AutoScrollOptions, DragAxis } from '../adapters/scroll';
+import type {
+  GridLayoutZone,
+  DndItem,
+  LayoutPoint,
+  LayoutRect,
+  ListLayoutZone,
+  MeasuredRect,
+} from '../contracts';
+import type { DndSessionSnapshot } from '../controller/dndSession';
+import type { ListLayout } from '../engine/list';
+import type { ListTargetIndex } from '../engine/listIndex';
+import type { PreparedGridTarget } from '../pointer/layoutTarget';
+import type { DndPresentation, DndZonePresentation } from './dndPresentation';
+import type { LayoutValidationIssue } from '../contracts';
+import type { CancelReason } from '../types';
+import type { GridMotionConfig } from '../pointer/motion';
+import type { ListItemRenderArgs } from '../components/dndTypes';
+import type { GestureRelations, ZoneGeometry } from '../components/gridTypes';
+import type { CellGeometry } from './gridRuntime';
+import {
+  DndRenderStore,
+  type DndZoneSnapshot,
+  type RetainSlotsRule,
+} from './dndRenderStore';
+
+type UiListRegistration = {
+  kind: 'list';
+  zoneId: string;
+  orientation: 'vertical' | 'horizontal';
+  revision: number;
+  layoutVersion: number;
+  ref: AnimatedRef<HostInstance>;
+  offset: SharedValue<number>;
+  contentSize: number;
+  autoScroll?: AutoScrollOptions;
+  targetIndex?: ListTargetIndex;
+};
+type UiGridRegistration = {
+  kind: 'grid';
+  zoneId: string;
+  revision: number;
+  layoutVersion: number;
+  ref: AnimatedRef<HostInstance>;
+  targetGrid?: PreparedGridTarget;
+};
+export type UiZoneRegistration = UiListRegistration | UiGridRegistration;
+export type ListRegistration = Omit<UiListRegistration, 'layoutVersion'> & {
+  layout: ListLayout;
+  dataIdentity?: readonly DndItem<unknown>[];
+  prepareDisplay?(
+    zone: ListLayoutZone,
+    revision: number,
+  ): DndZonePresentation | null;
+  renderItem(args: ListItemRenderArgs<unknown>): ReactNode;
+};
+export type GridRegistration = Omit<UiGridRegistration, 'layoutVersion'> & {
+  layout: GridLayoutZone;
+  geometry: ZoneGeometry;
+  cells: CellGeometry;
+  pixelRatio: number;
+  renderItem(args: ListItemRenderArgs<unknown>): ReactNode;
+};
+export type ZoneRegistration = ListRegistration | GridRegistration;
+export type ListViewport = {
+  zoneId: string;
+  viewport: MeasuredRect<'screen'>;
+  offset: number;
+  layoutVersion: number;
+};
+export type DndMotion = {
+  token: number;
+  /** Provider-owned native recognizer; independent of virtual cell lifetime. */
+  handleId: number | null;
+  seq: number;
+  phase: 'idle' | 'dragging' | 'released';
+  itemId: string | null;
+  sourceZoneId: string | null;
+  revision: number;
+  pointer: LayoutPoint;
+  origin: LayoutPoint;
+  axis: DragAxis;
+  activationDelayMs: number;
+  configRevision: number;
+  grip: LayoutPoint;
+  width: number;
+  height: number;
+  root: LayoutRect;
+  zones: ListViewport[];
+  visible: boolean;
+};
+export const EMPTY_DND_MOTION: DndMotion = {
+  token: 0,
+  handleId: null,
+  seq: 0,
+  phase: 'idle',
+  itemId: null,
+  sourceZoneId: null,
+  revision: 0,
+  pointer: { x: 0, y: 0 },
+  origin: { x: 0, y: 0 },
+  axis: 'both',
+  activationDelayMs: 250,
+  configRevision: 0,
+  grip: { x: 0, y: 0 },
+  width: 0,
+  height: 0,
+  root: { x: 0, y: 0, width: 0, height: 0 },
+  zones: [],
+  visible: false,
+};
+export type DndRuntime = {
+  snapshot: DndSessionSnapshot<unknown>;
+  renderStore?: DndRenderStore;
+  motion: SharedValue<DndMotion>;
+  presentation?: SharedValue<DndPresentation>;
+  /** JS view of the presentation most recently scheduled for the UI runtime. */
+  presentationSnapshot?(): DndPresentation;
+  /** Shared committed revision keeps unchanged cell worklets stable on approval. */
+  committedRevision?: SharedValue<number>;
+  /** Provider frame owns measurements and semantic dispatch when enabled. */
+  frameDriven?: boolean;
+  zones: SharedValue<UiZoneRegistration[]>;
+  disabled: SharedValue<boolean>;
+  token: SharedValue<number>;
+  rootRef: AnimatedRef<HostInstance>;
+  dragAxis: DragAxis;
+  activationDelayMs: number;
+  gestureConfigRevision: number;
+  animation: Required<GridMotionConfig>;
+  begin(state: DndMotion): void;
+  move(state: DndMotion): void;
+  release(state: DndMotion, cancelled: boolean | CancelReason): void;
+  cancel(reason: CancelReason): void;
+  registerZone(registration: ZoneRegistration, identity: object): void;
+  unregisterZone(zoneId: string, identity: object): void;
+  registerHandle(registration: DndHandleRegistration, identity: object): void;
+  unregisterHandle(identity: object): void;
+  reportIssues(owner: string, issues: LayoutValidationIssue[]): void;
+};
+export type DndHandleRegistration = {
+  itemId: string;
+  zoneId: string;
+  ref: AnimatedRef<HostInstance>;
+  sourceRef: AnimatedRef<HostInstance>;
+  disabled: boolean;
+  gestureRelations?: GestureRelations;
+};
+export const DndRuntimeContext = createContext<DndRuntime | null>(null);
+export const DndItemContext = createContext<{
+  itemId: string;
+  zoneId: string;
+  ref: AnimatedRef<HostInstance>;
+  preview?: boolean;
+} | null>(null);
+export function useDndRuntime(): DndRuntime {
+  const runtime = useContext(DndRuntimeContext);
+  if (!runtime)
+    throw new Error(
+      'SortableList, SortableGrid and DragHandle must be inside DndProvider.',
+    );
+  return runtime;
+}
+
+function renderStoreFor(runtime: DndRuntime): DndRenderStore {
+  return (
+    runtime.renderStore ??
+    new DndRenderStore({
+      getSnapshot: () => runtime.snapshot,
+      subscribe: () => () => {},
+    })
+  );
+}
+
+const inactiveHandleSelection = {
+  get: () => false,
+  subscribe: (_listener: () => void) => () => {},
+};
+
+export function useDndZoneSnapshot(
+  runtime: DndRuntime,
+  zoneId: string,
+  preserveSlots: boolean | RetainSlotsRule = true,
+): DndZoneSnapshot {
+  const selection = useMemo(() => {
+    const store = renderStoreFor(runtime);
+    // Without shared presentation nothing moves retained slots on the UI
+    // runtime, so React must follow the candidate order itself.
+    const get = () =>
+      store.getZoneSnapshot(
+        zoneId,
+        runtime.presentation ? preserveSlots : false,
+      );
+    return {
+      get,
+      subscribe: (listener: () => void) =>
+        store.subscribeSelection(get, listener),
+    };
+  }, [runtime, zoneId, preserveSlots]);
+  return useSyncExternalStore(selection.subscribe, selection.get);
+}
+
+export function useDndHandleActive(
+  runtime: DndRuntime,
+  itemId: string | undefined,
+  disabled: boolean,
+): boolean {
+  const selection = useMemo(() => {
+    if (!disabled) return inactiveHandleSelection;
+    const store = renderStoreFor(runtime);
+    const get = () => store.getSnapshot().itemId === itemId;
+    return {
+      get,
+      subscribe: (listener: () => void) =>
+        store.subscribeSelection(get, listener),
+    };
+  }, [runtime, itemId, disabled]);
+  return useSyncExternalStore(selection.subscribe, selection.get);
+}
+
+/** Public render arguments follow approved previews independently of native slots. */
+export function useDndItemSnapshot(
+  runtime: DndRuntime,
+  zoneId: string,
+  itemId: string,
+) {
+  const selection = useMemo(() => {
+    const store = renderStoreFor(runtime);
+    const get = () => store.getItemSnapshot(zoneId, itemId);
+    return {
+      get,
+      subscribe: (listener: () => void) =>
+        store.subscribeSelection(get, listener),
+    };
+  }, [runtime, zoneId, itemId]);
+  return useSyncExternalStore(selection.subscribe, selection.get);
+}
+
+export function measureDndRect(
+  ref: AnimatedRef<HostInstance>,
+): LayoutRect | null {
+  'worklet';
+  const result = measure(ref);
+  if (
+    !result ||
+    ![result.pageX, result.pageY, result.width, result.height].every(
+      Number.isFinite,
+    ) ||
+    result.width <= 0 ||
+    result.height <= 0
+  )
+    return null;
+  return {
+    x: result.pageX,
+    y: result.pageY,
+    width: result.width,
+    height: result.height,
+  };
+}
+
+export function readListViewports(
+  zones: readonly UiZoneRegistration[],
+): ListViewport[] {
+  'worklet';
+  const timestampMs = (
+    globalThis as typeof globalThis & { performance: { now(): number } }
+  ).performance.now();
+  const measured: ListViewport[] = [];
+  for (const zone of zones) {
+    const rect = measureDndRect(zone.ref);
+    const offset = zone.kind === 'grid' ? 0 : zone.offset.get();
+    if (rect && Number.isFinite(offset))
+      measured.push({
+        zoneId: zone.zoneId,
+        offset,
+        layoutVersion: zone.layoutVersion,
+        viewport: {
+          source: 'measured',
+          space: 'screen',
+          rect,
+          revision: zone.revision,
+          timestampMs,
+        },
+      });
+  }
+  return measured;
+}
+
+export function pointInRect(point: LayoutPoint, rect: LayoutRect): boolean {
+  'worklet';
+  return (
+    point.x >= rect.x &&
+    point.x <= rect.x + rect.width &&
+    point.y >= rect.y &&
+    point.y <= rect.y + rect.height
+  );
+}

package/src/runtime/dndSettlement.ts

@@ -0,0 +1,117 @@
+import type { LayoutPoint, LayoutRect } from '../contracts';
+
+import { isUsableRect } from '../pointer/geometry';
+
+type SettlementGeometry = {
+  /** Root and viewport use screen coordinates; contentRect excludes scrolling. */
+  root: LayoutRect;
+  viewport: LayoutRect;
+  contentRect: LayoutRect;
+  nativeRect: LayoutRect | null;
+  scrollOffset: LayoutPoint;
+  pixelRatio?: number;
+};
+
+function containsPixels(
+  outer: LayoutRect,
+  inner: LayoutRect,
+  pixelRatio: number,
+): boolean {
+  'worklet';
+  return (
+    Math.round(inner.x * pixelRatio) >= Math.round(outer.x * pixelRatio) &&
+    Math.round(inner.y * pixelRatio) >= Math.round(outer.y * pixelRatio) &&
+    Math.round((inner.x + inner.width) * pixelRatio) <=
+      Math.round((outer.x + outer.width) * pixelRatio) &&
+    Math.round((inner.y + inner.height) * pixelRatio) <=
+      Math.round((outer.y + outer.height) * pixelRatio)
+  );
+}
+
+/** Resolve the committed logical slot without waiting for a native cell. */
+export function settlementTarget({
+  root,
+  viewport,
+  contentRect,
+  scrollOffset,
+  pixelRatio = 1,
+}: Omit<SettlementGeometry, 'nativeRect'>): LayoutRect | null {
+  'worklet';
+  if (
+    !isUsableRect(root) ||
+    !isUsableRect(viewport) ||
+    !isUsableRect(contentRect) ||
+    !Number.isFinite(scrollOffset.x) ||
+    !Number.isFinite(scrollOffset.y) ||
+    !Number.isFinite(pixelRatio) ||
+    pixelRatio <= 0
+  )
+    return null;
+  const expected = {
+    x: viewport.x + contentRect.x - scrollOffset.x,
+    y: viewport.y + contentRect.y - scrollOffset.y,
+    width: contentRect.width,
+    height: contentRect.height,
+  };
+  if (
+    !isUsableRect(expected) ||
+    !containsPixels(viewport, expected, pixelRatio) ||
+    !containsPixels(root, expected, pixelRatio)
+  )
+    return null;
+  return { ...expected, x: expected.x - root.x, y: expected.y - root.y };
+}
+
+/** Native alignment gates only the final handoff, not the overlay animation. */
+export function settlementDestination({
+  root,
+  viewport,
+  contentRect,
+  nativeRect,
+  scrollOffset,
+  pixelRatio = 1,
+}: SettlementGeometry): LayoutRect | null {
+  'worklet';
+  const target = settlementTarget({
+    root,
+    viewport,
+    contentRect,
+    scrollOffset,
+    pixelRatio,
+  });
+  if (!target || !isUsableRect(nativeRect)) return null;
+  const tolerance = 1 / pixelRatio;
+  if (
+    Math.abs(nativeRect.x - root.x - target.x) > tolerance ||
+    Math.abs(nativeRect.y - root.y - target.y) > tolerance ||
+    Math.abs(nativeRect.width - target.width) > tolerance ||
+    Math.abs(nativeRect.height - target.height) > tolerance ||
+    !containsPixels(viewport, nativeRect, pixelRatio) ||
+    !containsPixels(root, nativeRect, pixelRatio)
+  )
+    return null;
+  return {
+    x: nativeRect.x - root.x,
+    y: nativeRect.y - root.y,
+    width: nativeRect.width,
+    height: nativeRect.height,
+  };
+}
+
+/** Both rectangles use root coordinates; progress is the native animation value. */
+export function interpolateSettlementRect(
+  from: LayoutRect,
+  to: LayoutRect,
+  progress: number,
+): LayoutRect | null {
+  'worklet';
+  if (!isUsableRect(from) || !isUsableRect(to) || !Number.isFinite(progress))
+    return null;
+  const amount = Math.max(0, Math.min(1, progress));
+  return {
+    x: from.x + (to.x - from.x) * amount,
+    y: from.y + (to.y - from.y) * amount,
+    width: from.width + (to.width - from.width) * amount,
+    height: from.height + (to.height - from.height) * amount,
+  };
+}

package/src/runtime/gridRuntime.ts

@@ -0,0 +1,73 @@
+import type { HostInstance } from 'react-native';
+import type { AnimatedRef } from 'react-native-reanimated';
+
+import type { GridMovementPolicy } from '../engine/movementPolicy';
+import type { CellSpan, GridZone, ItemLocation } from '../types';
+
+import type { ZoneGeometry } from '../components/gridTypes';
+
+/**
+ * Geometry vocabulary of the grid pointer policy (`pointer/geometry.ts`),
+ * shared by the provider's layout targeting. The React runtime of the former
+ * grid controller no longer lives here.
+ */
+
+export type WindowRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+};
+export type CellGeometry = { cellWidth: number; cellHeight: number };
+export type ZoneRegistration = {
+  zone: GridZone<undefined>;
+  geometry: ZoneGeometry;
+  pixelRatio: number;
+  ref: AnimatedRef<HostInstance>;
+};
+export type MeasuredZone = Omit<ZoneRegistration, 'ref'> & {
+  rect: WindowRect;
+  cells: CellGeometry;
+};
+export type UiMotion = {
+  movementPolicy?: GridMovementPolicy;
+  baseRevision?: number;
+  token: number;
+  phase: 'idle' | 'dragging' | 'finalizing' | 'settling' | 'handoff';
+  itemId: string | null;
+  sourceZoneId: string | null;
+  seq: number;
+  target: ItemLocation | null;
+  span: CellSpan;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  gripX: number;
+  gripY: number;
+  zones: MeasuredZone[];
+  outlet: WindowRect;
+  validity: 'pending' | 'valid' | 'invalid';
+  visible: boolean;
+  destination: WindowRect | null;
+};
+export const EMPTY_MOTION: UiMotion = {
+  token: 0,
+  phase: 'idle',
+  itemId: null,
+  sourceZoneId: null,
+  seq: 0,
+  target: null,
+  span: { rows: 1, cols: 1 },
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+  gripX: 0,
+  gripY: 0,
+  zones: [],
+  outlet: { x: 0, y: 0, width: 0, height: 0 },
+  validity: 'pending',
+  visible: false,
+  destination: null,
+};

package/src/types.ts

@@ -0,0 +1,189 @@
+import type { MoveProposal, ProposalResponse } from './contracts';
+
+import type { GridMovementPolicy } from './engine/movementPolicy';
+
+export type CellPosition = { row: number; col: number };
+export type CellSpan = { rows: number; cols: number };
+/** Optional JS diagnostics; durations are not native rendering or GPU timings. */
+export type GridDiagnosticEvent =
+  | {
+      type: 'timing';
+      name:
+        'compute-move' | 'input-validation' | 'candidate-validation' | 'policy';
+      durationMs: number;
+      sessionId?: string;
+      attempts?: number;
+      status?: string;
+    }
+  | {
+      type: 'lifecycle';
+      name:
+        | 'request'
+        | 'request-coalesced'
+        | 'release'
+        | 'proposal'
+        | 'response'
+        | 'settling'
+        | 'end';
+      timestampMs: number;
+      sessionId: string;
+    };
+export type ItemPlacement = 'insert' | 'exchange';
+export type GridItem<T> = {
+  id: string;
+  span: CellSpan;
+  /** Caller-selected spatial behavior. Omitted means exchange, regardless of size. */
+  placement?: ItemPlacement;
+  data: T;
+};
+export type PositionedItem<T> = GridItem<T> & { position: CellPosition };
+
+export type SpatialZone<T> = {
+  id: string;
+  rows: number;
+  columns: number;
+  strategy: 'spatial';
+  items: PositionedItem<T>[];
+};
+export type OrderedZone<T> = {
+  id: string;
+  rows: number;
+  columns: number;
+  strategy: 'ordered';
+  itemSpan: CellSpan;
+  items: GridItem<T>[];
+};
+export type GridZone<T> = SpatialZone<T> | OrderedZone<T>;
+export type GridValue<T> = {
+  zones: GridZone<T>[];
+  /** Increment on every external data/layout edit. Omit only for legacy control. */
+  revision?: number;
+  proposalResponse?: Omit<ProposalResponse, 'baseRevision'> & {
+    baseRevision?: number;
+  };
+};
+
+export type RevisionedGridValue<T> = GridValue<T> & { revision: number };
+export type GridProposal<T> = MoveProposal<
+  RevisionedGridValue<T>,
+  ItemLocation
+>;
+
+export type ValidationCode =
+  | 'invalid-structure'
+  | 'duplicate-id'
+  | 'invalid-dimension'
+  | 'invalid-span'
+  | 'invalid-placement'
+  | 'missing-item-span'
+  | 'span-mismatch'
+  | 'invalid-position'
+  | 'out-of-bounds'
+  | 'overlap'
+  | 'capacity-exceeded'
+  | 'invalid-budget'
+  | 'invalid-geometry'
+  | 'invalid-configuration';
+export type ValidationIssue = {
+  code: ValidationCode;
+  zoneId?: string;
+  itemId?: string;
+  message: string;
+};
+export type ValidationResult =
+  { valid: true } | { valid: false; issues: ValidationIssue[] };
+export type ZoneLayoutResult<T> =
+  | { valid: true; items: PositionedItem<T>[] }
+  | { valid: false; issues: ValidationIssue[] };
+export type PackInput<T> = {
+  items: readonly GridItem<T>[];
+  rows: number;
+  columns: number;
+  searchBudget: number;
+};
+export type PackResult<T> =
+  | { status: 'ok'; placements: PositionedItem<T>[] }
+  | { status: 'impossible' }
+  | { status: 'unresolved' }
+  | { status: 'invalid'; issues: ValidationIssue[] };
+
+export type ItemLocation =
+  | { zoneId: string; strategy: 'spatial'; position: CellPosition }
+  | { zoneId: string; strategy: 'ordered'; index: number };
+
+/** A logical target, after pointer conversion and hysteresis in the controller. */
+export type MoveInput<T> = {
+  movementPolicy?: GridMovementPolicy;
+  value: GridValue<T>;
+  itemId: string;
+  to: ItemLocation;
+  searchBudget?: number;
+};
+export type MoveResult<T> =
+  | {
+      status: 'ok';
+      value: GridValue<T>;
+      from: ItemLocation;
+      to: ItemLocation;
+      changed: boolean;
+      attempts: number;
+    }
+  | { status: 'impossible' | 'unresolved'; attempts: number }
+  | { status: 'invalid'; issues: ValidationIssue[] };
+
+export type GridChange = {
+  sessionId: string;
+  /** Present when the input GridValue supplies a revision (including useGridState). */
+  baseRevision?: number;
+  itemId: string;
+  from: ItemLocation;
+  to: ItemLocation;
+};
+export type DragStartEvent = {
+  sessionId: string;
+  itemId: string;
+  sourceZoneId: string;
+};
+export type CanDropArgs<T> = {
+  item: GridItem<T>;
+  change: GridChange;
+  proposedValue: GridValue<T>;
+};
+export type DropDecision =
+  { allowed: true } | { allowed: false; reason?: string };
+export type CleanupReason =
+  | 'input-changed'
+  | 'geometry-changed'
+  | 'zone-removed'
+  | 'disabled'
+  | 'unmounted';
+/** Interruptions include every cancel reason a proposal can meet while it awaits a response. */
+export type ProposalInterruptReason =
+  CancelReason | 'response-missing' | 'change-handler-error';
+export type CancelReason =
+  | CleanupReason
+  | 'outside-zones'
+  | 'invalid-target'
+  | 'measure-failed'
+  | 'policy-rejected'
+  | 'search-budget'
+  | 'unresolvable'
+  | 'gesture-interrupted'
+  | 'policy-error'
+  | 'start-handler-error';
+export type DragEndEvent = DragStartEvent & {
+  cleanupReason?: CleanupReason;
+  error?: unknown;
+} & (
+    | { outcome: 'unchanged' }
+    | {
+        outcome: 'cancelled';
+        targetZoneId?: string;
+        reason: CancelReason;
+        policyReason?: string;
+      }
+    | ({ outcome: 'proposed'; change: GridChange; targetZoneId: string } & (
+        | { response: 'accepted' | 'rejected' | 'expired' | 'mismatch' }
+        | { response: 'interrupted'; reason: ProposalInterruptReason }
+      ))
+  );