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

package/src/components/dndTypes.ts

@@ -0,0 +1,102 @@
+import type { ReactNode, Ref } from 'react';
+import type { StyleProp, ViewProps, ViewStyle } from 'react-native';
+
+import type { AutoScrollOptions, DragAxis } from '../adapters/scroll';
+import type { ListVirtualizationOptions } from '../adapters/virtualizedList';
+import type { DndItem, GridPlacement } from '../contracts';
+import type {
+  DndDragEndEvent,
+  DndSessionOptions,
+} from '../controller/dndSession';
+import type { HandleViewProps } from './handleViewProps';
+import type { GridMotionConfig } from '../pointer/motion';
+import type { GestureRelations, ZoneGeometry } from './gridTypes';
+
+export type DndMotionConfig = GridMotionConfig;
+
+export type ListItemRenderArgs<T> = {
+  item: DndItem<T>;
+  index: number;
+  zoneId: string;
+  isDragging: boolean;
+};
+export type GridItemRenderArgs<T> = ListItemRenderArgs<T> & {
+  position: GridPlacement['position'];
+  span: GridPlacement['span'];
+  placement?: GridPlacement['placement'];
+  width: number;
+  height: number;
+};
+
+/** Spatial grid under the shared provider; cells use the existing geometry contract. */
+export type SortableGridProps<T> = Omit<ViewProps, 'children'> & {
+  zoneId: string;
+  geometry: ZoneGeometry;
+  renderItem(args: GridItemRenderArgs<T>): ReactNode;
+  dropIndicatorStyle?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+};
+
+export type DndPreviewArgs<T> = ListItemRenderArgs<T> & {
+  sessionId: string;
+  targetZoneId: string | null;
+  width: number;
+  height: number;
+  validity: 'pending' | 'valid' | 'invalid';
+  /** Call after the custom preview's drawable content has committed. Late sessions are ignored. */
+  onReady(): void;
+};
+
+export type DndProviderHandle = {
+  /** Cancel the current drag because zone geometry moved under it. */
+  invalidateGeometry(): void;
+};
+
+export type DndProviderProps<T> = Omit<ViewProps, 'children'> &
+  DndSessionOptions<T> & {
+    children: ReactNode;
+    activation?: { delayMs: number };
+    /** Independent of list orientation. Defaults to both screen axes. */
+    dragAxis?: DragAxis;
+    motion?: DndMotionConfig;
+    renderDragPreview?(args: DndPreviewArgs<T>): ReactNode;
+    /** Keep the original visible until the custom preview calls onReady. Defaults to false. */
+    waitForDragPreviewReady?: boolean;
+    dragPreviewStyle?: StyleProp<ViewStyle>;
+    /**
+     * The `onDragEnd` event again once the drag preview has finished settling
+     * into its cell, or right after `onDragEnd` when nothing animates.
+     * `GridController.onDragEnd` uses this timing.
+     */
+    onDragSettled?(event: DndDragEndEvent<T>): void;
+    ref?: Ref<DndProviderHandle>;
+  };
+
+/** ScrollView by default; enable virtualization for FlatList. Sizes are logical pixels. */
+export type SortableListProps<T> = Omit<ViewProps, 'children'> & {
+  zoneId: string;
+  renderItem(args: ListItemRenderArgs<T>): ReactNode;
+  /** Main-axis estimate before a cell has been measured. Defaults to 48. */
+  estimatedItemSize?: number;
+  /** Optional authoritative main-axis size, constant or per item. */
+  itemSize?: number | ((itemId: string, index: number) => number);
+  gap?: number;
+  paddingStart?: number;
+  paddingEnd?: number;
+  autoScroll?: AutoScrollOptions;
+  scrollEnabled?: boolean;
+  showsScrollIndicator?: boolean;
+  onScrollOffsetChange?(offset: { x: number; y: number }): void;
+  /** Use FlatList windowing. True selects defaults; false is the default. */
+  virtualization?: boolean | ListVirtualizationOptions;
+};
+
+/** Accessibility and test attributes forwarded to the handle's native view. */
+export type DragHandleViewProps = HandleViewProps;
+
+export type DragHandleProps = DragHandleViewProps & {
+  children: ReactNode;
+  itemId?: string;
+  disabled?: boolean;
+  gestureRelations?: GestureRelations;
+};

package/src/components/gridTypes.ts

@@ -0,0 +1,90 @@
+import type { ReactNode, Ref } from 'react';
+import type { StyleProp, ViewProps, ViewStyle } from 'react-native';
+import type { PanGestureConfig } from 'react-native-gesture-handler';
+import type { GridMovementPolicy } from '../engine/movementPolicy';
+import type { HandleViewProps } from './handleViewProps';
+import type { GridMotionConfig } from '../pointer/motion';
+
+import type {
+  CanDropArgs,
+  DragEndEvent,
+  DragStartEvent,
+  DropDecision,
+  GridChange,
+  GridDiagnosticEvent,
+  GridItem,
+  GridValue,
+  ValidationIssue,
+} from '../types';
+
+export type GestureRelations = Pick<
+  PanGestureConfig,
+  'block' | 'requireToFail' | 'simultaneousWith'
+>;
+export type GridInsets = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+export type ZoneGeometry = {
+  rowGap: number;
+  columnGap: number;
+  padding: GridInsets;
+} & (
+  { mode: 'fixed'; cellWidth: number; cellHeight: number } | { mode: 'fit' }
+);
+export type ItemRenderArgs<T> = {
+  item: GridItem<T>;
+  zoneId: string;
+  width: number;
+  height: number;
+  isDragging: boolean;
+};
+export type DragPreviewArgs<T> = Omit<ItemRenderArgs<T>, 'zoneId'> & {
+  sessionId: string;
+  /** Call after the custom preview's drawable content has committed. Late sessions are ignored. */
+  onReady(): void;
+  sourceZoneId: string;
+  targetZoneId: string | null;
+  validity: 'pending' | 'valid' | 'invalid';
+};
+export type GridControllerHandle = { invalidateGeometry(): void };
+export type GridControllerProps<T> = Omit<ViewProps, 'children'> & {
+  value: GridValue<T>;
+  onChange(nextValue: GridValue<T>, change: GridChange): void;
+  renderItem(args: ItemRenderArgs<T>): ReactNode;
+  renderDragPreview?(args: DragPreviewArgs<T>): ReactNode;
+  /** Keep the original visible until the custom preview calls onReady. Defaults to false. */
+  waitForDragPreviewReady?: boolean;
+  /** Optional preview surface styling (background, border, clipping, shadow). */
+  dragPreviewStyle?: StyleProp<ViewStyle>;
+  canDrop?(args: CanDropArgs<T>): DropDecision;
+  onDragStart?(event: DragStartEvent): void;
+  /** Fires once the drag preview has settled into its cell, or at once when nothing animates. */
+  onDragEnd?(event: DragEndEvent): void;
+  onValidationError?(issues: ValidationIssue[]): void;
+  /** Optional JS-only observation. Exceptions are ignored; omit to disable timing. */
+  onDiagnostic?(event: GridDiagnosticEvent): void;
+  /** Defaults to 10,000 bounded search steps. */
+  searchBudget?: number;
+  /** Defaults to a 250ms long press. */
+  activation?: { delayMs: number };
+  /** Generic rules by default; opt into HOME_GRID_MOVEMENT_POLICY for home compatibility. */
+  movementPolicy?: GridMovementPolicy;
+  motion?: GridMotionConfig;
+  responseTimeoutMs?: number;
+  disabled?: boolean;
+  ref?: Ref<GridControllerHandle>;
+  children: ReactNode;
+};
+export type GridZoneViewProps = ViewProps & {
+  zoneId: string;
+  geometry: ZoneGeometry;
+};
+export type GridDragHandleProps = HandleViewProps & {
+  itemId: string;
+  gestureRelations?: GestureRelations;
+  disabled?: boolean;
+  children: ReactNode;
+};

package/src/components/handleViewProps.ts

@@ -0,0 +1,35 @@
+import type { ViewProps } from 'react-native';
+
+/** Accessibility and test attributes forwarded to a handle's native view. */
+export type HandleViewProps = Pick<
+  ViewProps,
+  | 'accessible'
+  | 'accessibilityLabel'
+  | 'accessibilityHint'
+  | 'accessibilityRole'
+  | 'accessibilityState'
+  | 'accessibilityActions'
+  | 'onAccessibilityAction'
+  | 'importantForAccessibility'
+  | 'testID'
+>;
+
+const HANDLE_VIEW_PROP_KEYS = [
+  'accessible',
+  'accessibilityLabel',
+  'accessibilityHint',
+  'accessibilityRole',
+  'accessibilityState',
+  'accessibilityActions',
+  'onAccessibilityAction',
+  'importantForAccessibility',
+  'testID',
+] as const satisfies ReadonlyArray<keyof HandleViewProps>;
+
+/** Copies only the defined view attributes so handle-specific props never reach the native view. */
+export function pickHandleViewProps(props: HandleViewProps): HandleViewProps {
+  const forwarded: Record<string, unknown> = {};
+  for (const key of HANDLE_VIEW_PROP_KEYS)
+    if (props[key] !== undefined) forwarded[key] = props[key];
+  return forwarded as HandleViewProps;
+}

package/src/contracts.ts

@@ -0,0 +1,149 @@
+import type {
+  CellPosition,
+  CellSpan,
+  ItemPlacement,
+  ValidationCode,
+} from './types';
+
+export type ItemId = string;
+export type ZoneId = string;
+
+/** Application data has no layout meaning and remains owned by the caller. */
+export type DndItem<T> = { id: ItemId; data: T };
+
+export type GridPlacement = {
+  itemId: ItemId;
+  position: CellPosition;
+  span: CellSpan;
+  placement?: ItemPlacement;
+};
+
+export type GridLayoutZone = {
+  id: ZoneId;
+  kind: 'grid';
+  rows: number;
+  columns: number;
+  placements: GridPlacement[];
+  /**
+   * Ordered packing (a dock, for example): every placement has this span,
+   * the array order is the item order and positions are the reading-order
+   * slots of that order. A move inserts at the slot the target addresses and
+   * re-packs; removing an item closes the gap; capacity is rows × columns
+   * in slots. Omitted for spatial grids.
+   */
+  itemSpan?: CellSpan;
+};
+
+/** A one-dimensional order, independent of item sizes and the drag axis. */
+export type ListLayoutZone = {
+  id: ZoneId;
+  kind: 'list';
+  orientation: 'vertical' | 'horizontal';
+  itemIds: ItemId[];
+};
+
+export type LayoutZone = GridLayoutZone | ListLayoutZone;
+
+/**
+ * Every item is referenced by exactly one zone. Revisions are nonnegative safe
+ * integers; the owner increments the revision for each accepted/external change.
+ * Shared by the list adapter and the grid conversion helpers.
+ */
+export type LayoutState<T> = {
+  revision: number;
+  items: DndItem<T>[];
+  zones: LayoutZone[];
+};
+
+export type GridLocation = {
+  kind: 'grid';
+  zoneId: ZoneId;
+  position: CellPosition;
+};
+export type ListLocation = { kind: 'list'; zoneId: ZoneId; index: number };
+export type LayoutLocation = GridLocation | ListLocation;
+
+/** The completed candidate is approved atomically against baseRevision. */
+export type MoveProposal<State, Location = LayoutLocation> = {
+  sessionId: string;
+  itemId: ItemId;
+  baseRevision: number;
+  from: Location;
+  to: Location;
+  value: State;
+};
+
+/** A response applies only to the matching session AND base revision. */
+export type ProposalResponse = {
+  sessionId: string;
+  baseRevision: number;
+  accepted: boolean;
+};
+
+export type LayoutValidationCode =
+  | ValidationCode
+  | 'invalid-revision'
+  | 'unknown-item'
+  | 'unplaced-item'
+  | 'duplicate-reference'
+  | 'invalid-orientation';
+export type LayoutValidationIssue = {
+  code: LayoutValidationCode;
+  zoneId?: ZoneId;
+  itemId?: ItemId;
+  message: string;
+};
+export type LayoutValidationResult =
+  { valid: true } | { valid: false; issues: LayoutValidationIssue[] };
+
+export type LayoutConversionIssue = Omit<LayoutValidationIssue, 'code'> & {
+  code: LayoutValidationCode | 'unsupported-zone';
+};
+export type LayoutConversionResult<Value> =
+  | { valid: true; value: Value }
+  | { valid: false; issues: LayoutConversionIssue[] };
+
+/** Logical pixels in the coordinate space named by the containing contract. */
+export type LayoutPoint = { x: number; y: number };
+export type LayoutRect = LayoutPoint & { width: number; height: number };
+export type CoordinateSpace = 'screen' | 'content';
+
+type MeasurementBase<Space extends CoordinateSpace> = {
+  space: Space;
+  rect: LayoutRect;
+  revision: number;
+  /** Monotonic milliseconds in the same clock domain as MeasurementFreshness.nowMs. */
+  timestampMs: number;
+};
+export type MeasuredRect<Space extends CoordinateSpace = CoordinateSpace> =
+  MeasurementBase<Space> & { source: 'measured' };
+export type EstimatedRect<Space extends CoordinateSpace = CoordinateSpace> =
+  MeasurementBase<Space> & { source: 'estimated' };
+export type RectMeasurement<Space extends CoordinateSpace = CoordinateSpace> =
+  MeasuredRect<Space> | EstimatedRect<Space>;
+
+export type MeasurementFreshness = {
+  revision: number;
+  /** Supply both nowMs and maxAgeMs to impose an age limit. */
+  nowMs?: number;
+  maxAgeMs?: number;
+};
+
+/**
+ * Viewport is the measured screen origin of content at scroll offset zero.
+ * Offset changes do not change layout revision. Negative offsets support bounce
+ * and insets. Padding is part of content coordinates, not another offset here.
+ */
+export type ZoneCoordinateContext = {
+  viewport: MeasuredRect<'screen'>;
+  scrollOffset: LayoutPoint;
+};
+export type CoordinateFailureReason =
+  | 'invalid-coordinate'
+  | 'invalid-context'
+  | 'invalid-measurement'
+  | 'invalid-freshness'
+  | 'stale-measurement';
+export type CoordinateResult<Value> =
+  | { valid: true; value: Value }
+  | { valid: false; reason: CoordinateFailureReason };

package/src/controller/approval.ts

@@ -0,0 +1,179 @@
+import type { MoveProposal, ProposalResponse } from '../contracts';
+import { isRecord } from '../engine/validation';
+
+/**
+ * Shared revisioned approval for both value shapes (`GridValue` and
+ * `LayoutState`). The adapter supplies the shape-specific checks; the order of
+ * checks, the stale rules and the response protocol are the same for both.
+ */
+export type ApprovalResult<Value, Issue> =
+  | { status: 'accepted' | 'rejected' | 'stale'; value: Value }
+  | { status: 'invalid'; value: Value; issues: Issue[] };
+
+/** Legacy grid values may carry a response without a base revision. */
+type Revisioned = {
+  revision: number;
+  proposalResponse?: {
+    sessionId: string;
+    baseRevision?: number;
+    accepted: boolean;
+  };
+};
+
+export type ApprovalAdapter<Value extends Revisioned, Location, Issue> = {
+  /** Issues of the current value, or null when it is usable as a baseline. */
+  validateCurrent(current: Value): Issue[] | null;
+  /** Issues of the complete candidate, or null when it is valid. */
+  validateCandidate(candidate: Value): Issue[] | null;
+  issue(message: string): Issue;
+  isLocation(value: unknown): value is Location;
+  location(value: Value, itemId: string): Location | null;
+  sameLocation(first: Location, second: Location | null): boolean;
+  hasDestinationZone(value: Value, to: Location): boolean;
+  zonesPreserved(current: Value, candidate: Value): boolean;
+  itemsPreserved(current: Value, candidate: Value): boolean;
+  messages: { zones: string; items: string; destination: string };
+  /** Attach the response (and any retained caller objects) to the candidate. */
+  accept(current: Value, candidate: Value, response: ProposalResponse): Value;
+};
+
+/** A response only changes the exact revision on which the complete proposal was based. */
+export function respondToProposal<Value extends Revisioned, Location, Issue>(
+  adapter: ApprovalAdapter<Value, Location, Issue>,
+  current: Value,
+  proposal: MoveProposal<Value, Location>,
+  accepted: boolean,
+  checkCurrent: boolean,
+): ApprovalResult<Value, Issue> {
+  const invalid = (message: string): ApprovalResult<Value, Issue> => ({
+    status: 'invalid',
+    value: current,
+    issues: [adapter.issue(message)],
+  });
+  if (checkCurrent) {
+    const issues = adapter.validateCurrent(current);
+    if (issues) return { status: 'invalid', value: current, issues };
+  }
+  if (
+    !isRecord(proposal) ||
+    typeof proposal.sessionId !== 'string' ||
+    typeof proposal.itemId !== 'string' ||
+    !Number.isSafeInteger(proposal.baseRevision) ||
+    proposal.baseRevision < 0 ||
+    typeof accepted !== 'boolean'
+  )
+    return invalid(
+      'A proposal requires a session ID, item ID, base revision and boolean response.',
+    );
+  if (
+    proposal.baseRevision !== current.revision ||
+    (current.proposalResponse?.sessionId === proposal.sessionId &&
+      current.proposalResponse.baseRevision === proposal.baseRevision)
+  )
+    return { status: 'stale', value: current };
+  if (
+    !adapter.isLocation(proposal.from) ||
+    !adapter.isLocation(proposal.to) ||
+    !adapter.sameLocation(
+      proposal.from,
+      adapter.location(current, proposal.itemId),
+    ) ||
+    !adapter.hasDestinationZone(current, proposal.to)
+  )
+    return invalid(
+      'Proposal locations must identify the current item and an existing destination zone.',
+    );
+  const response: ProposalResponse = {
+    sessionId: proposal.sessionId,
+    baseRevision: proposal.baseRevision,
+    accepted,
+  };
+  if (!accepted)
+    return {
+      status: 'rejected',
+      value: { ...current, proposalResponse: response },
+    };
+  const issues = adapter.validateCandidate(proposal.value);
+  if (issues) return { status: 'invalid', value: current, issues };
+  if (
+    !Number.isSafeInteger(proposal.value.revision) ||
+    proposal.value.revision !== current.revision + 1
+  )
+    return invalid(
+      'An accepted proposal must advance its base revision by one.',
+    );
+  if (!adapter.zonesPreserved(current, proposal.value))
+    return invalid(adapter.messages.zones);
+  if (!adapter.itemsPreserved(current, proposal.value))
+    return invalid(adapter.messages.items);
+  if (
+    !adapter.sameLocation(
+      proposal.to,
+      adapter.location(proposal.value, proposal.itemId),
+    )
+  )
+    return invalid(adapter.messages.destination);
+  return {
+    status: 'accepted',
+    value: adapter.accept(current, proposal.value, response),
+  };
+}
+
+export type ApprovalStore<Value, Proposal, Issue> = {
+  getSnapshot(): Value;
+  subscribe(listener: () => void): () => void;
+  respond(proposal: Proposal, accepted: boolean): ApprovalResult<Value, Issue>;
+  /** Publish a value produced outside the reducer, such as an external edit. */
+  publish(next: Value): void;
+};
+
+/**
+ * Listeners, closed-session memory and publication shared by the grid and
+ * layout stores. Rejections leave the revision unchanged; every closed session
+ * is remembered until the next revision so a delayed response cannot reopen an
+ * earlier rejection.
+ */
+export function createApprovalStore<
+  Value extends { revision: number },
+  Proposal extends { sessionId: string; baseRevision: number },
+  Issue,
+>(
+  initial: Value,
+  respond: (
+    current: Value,
+    proposal: Proposal,
+    accepted: boolean,
+  ) => ApprovalResult<Value, Issue>,
+): ApprovalStore<Value, Proposal, Issue> {
+  let value = initial;
+  const listeners = new Set<() => void>();
+  const closedSessions = new Set<string>();
+  const publish = (next: Value) => {
+    if (next === value) return;
+    if (next.revision !== value.revision) closedSessions.clear();
+    value = next;
+    for (const listener of listeners) listener();
+  };
+  return {
+    getSnapshot: () => value,
+    subscribe: listener => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    respond: (proposal, accepted) => {
+      if (
+        isRecord(proposal) &&
+        proposal.baseRevision === value.revision &&
+        closedSessions.has(proposal.sessionId)
+      )
+        return { status: 'stale', value };
+      const result = respond(value, proposal, accepted);
+      if (result.status === 'rejected') closedSessions.add(proposal.sessionId);
+      publish(result.value);
+      return result;
+    },
+    publish,
+  };
+}

package/src/controller/coordinatorBase.ts

@@ -0,0 +1,118 @@
+/**
+ * Snapshot ownership shared by both session coordinators: subscribers,
+ * batched notification, shallow patching with `Object.is` change detection
+ * and the response deadline timer. The subclasses own their snapshot shapes,
+ * candidate calculation and lifecycle events.
+ */
+export abstract class CoordinatorBase<Snapshot extends object> {
+  protected snapshot: Snapshot;
+  protected changed = false;
+  private listeners = new Set<() => void>();
+  private depth = 0;
+  private responseTimer: ReturnType<typeof setTimeout> | undefined;
+
+  protected constructor(initial: Snapshot) {
+    this.snapshot = initial;
+  }
+
+  getSnapshot = (): Snapshot => this.snapshot;
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  /** Nested batches notify subscribers once, after the outermost one ends. */
+  protected batch<R>(work: () => R): R {
+    this.batchStarted();
+    this.depth++;
+    try {
+      return work();
+    } finally {
+      this.depth--;
+      if (this.depth === 0) {
+        try {
+          if (this.changed) {
+            this.changed = false;
+            for (const listener of this.listeners) listener();
+          }
+        } finally {
+          this.batchFinished();
+        }
+      }
+    }
+  }
+
+  protected batchStarted(): void {}
+
+  /** Runs after subscribers were notified, even when one of them threw. */
+  protected batchFinished(): void {}
+
+  protected get batchDepth(): number {
+    return this.depth;
+  }
+
+  protected update(patch: Partial<Snapshot>): void {
+    if (
+      !Object.keys(patch).some(
+        key =>
+          !Object.is(
+            this.snapshot[key as keyof Snapshot],
+            patch[key as keyof Snapshot],
+          ),
+      )
+    )
+      return;
+    this.snapshot = { ...this.snapshot, ...patch };
+    this.changed = true;
+  }
+
+  /** Put back an earlier snapshot and its pending-notification flag. */
+  protected restore(snapshot: Snapshot, changed: boolean): void {
+    this.snapshot = snapshot;
+    this.changed = changed;
+  }
+
+  /**
+   * Wait for a proposal response until `deadline`. The timer re-arms while the
+   * clock has not reached the deadline (fake timers, long sleeps) and calls
+   * `onExpire` inside a batch once it has, unless `isPending` says the
+   * proposal was already settled.
+   */
+  protected armDeadline(
+    deadline: number | undefined,
+    isPending: () => boolean,
+    onExpire: () => void,
+  ): void {
+    const remaining = Math.max(0, (deadline ?? now()) - now());
+    this.responseTimer = setTimeout(
+      () =>
+        this.batch(() => {
+          this.responseTimer = undefined;
+          if (!isPending()) return;
+          if (deadline !== undefined && now() < deadline)
+            this.armDeadline(deadline, isPending, onExpire);
+          else onExpire();
+        }),
+      Math.min(remaining, 2147483647),
+    );
+  }
+
+  protected clearDeadline(): void {
+    clearTimeout(this.responseTimer);
+    this.responseTimer = undefined;
+  }
+}
+
+/** RN provides this monotonic clock; its generated ambient declarations omit it. */
+export function now(): number {
+  return (
+    globalThis as typeof globalThis & { performance: { now(): number } }
+  ).performance.now();
+}
+
+export function reportCallbackError(scope: string, error: unknown): void {
+  console.error(`[${scope}] Callback failed`, error);
+}