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

package/src/controller/dndState.ts

@@ -0,0 +1,198 @@
+import type {
+  LayoutLocation,
+  LayoutState,
+  LayoutValidationIssue,
+  MoveProposal,
+  ProposalResponse,
+} from '../contracts';
+import { validateLayoutState } from '../engine/layoutState';
+import { isCellPosition, isRecord } from '../engine/validation';
+
+import {
+  createApprovalStore,
+  respondToProposal,
+  type ApprovalAdapter,
+  type ApprovalResult,
+} from './approval';
+import { layoutLocation, sameLayoutLocation } from './locations';
+
+export type DndValue<T> = LayoutState<T> & {
+  proposalResponse?: ProposalResponse;
+};
+export type DndProposal<T> = MoveProposal<LayoutState<T>, LayoutLocation>;
+export type DndProposalResult<T> = ApprovalResult<
+  DndValue<T>,
+  LayoutValidationIssue
+>;
+
+function isLocation(value: unknown): value is LayoutLocation {
+  if (!isRecord(value) || typeof value.zoneId !== 'string') return false;
+  return value.kind === 'list'
+    ? typeof value.index === 'number' &&
+        Number.isSafeInteger(value.index) &&
+        value.index >= 0
+    : value.kind === 'grid' &&
+        isCellPosition(value.position) &&
+        value.position.row >= 0 &&
+        value.position.col >= 0;
+}
+
+function issues<T>(value: LayoutState<T>): LayoutValidationIssue[] | null {
+  const checked = validateLayoutState(value);
+  return checked.valid ? null : checked.issues;
+}
+
+function layoutAdapter<T>(): ApprovalAdapter<
+  DndValue<T>,
+  LayoutLocation,
+  LayoutValidationIssue
+> {
+  return {
+    validateCurrent: issues,
+    validateCandidate: issues,
+    issue: message => ({ code: 'invalid-structure', message }),
+    isLocation,
+    location: layoutLocation,
+    sameLocation: sameLayoutLocation,
+    hasDestinationZone: (value, to) =>
+      value.zones.some(zone => zone.id === to.zoneId && zone.kind === to.kind),
+    zonesPreserved: (current, candidate) => {
+      const zones = new Map(current.zones.map(zone => [zone.id, zone]));
+      return (
+        candidate.zones.length === zones.size &&
+        candidate.zones.every(zone => {
+          const original = zones.get(zone.id);
+          return (
+            original !== undefined &&
+            original.kind === zone.kind &&
+            (zone.kind !== 'list' ||
+              original.kind !== 'list' ||
+              zone.orientation === original.orientation) &&
+            (zone.kind !== 'grid' ||
+              original.kind !== 'grid' ||
+              (zone.rows === original.rows &&
+                zone.columns === original.columns &&
+                zone.itemSpan?.rows === original.itemSpan?.rows &&
+                zone.itemSpan?.cols === original.itemSpan?.cols))
+          );
+        })
+      );
+    },
+    // computeLayoutMove reuses the baseline items array; only a replaced array
+    // needs the per-item identity check.
+    itemsPreserved: (current, candidate) => {
+      if (candidate.items === current.items) return true;
+      const items = new Map(current.items.map(item => [item.id, item]));
+      return (
+        candidate.items.length === items.size &&
+        candidate.items.every(item => items.get(item.id) === item)
+      );
+    },
+    messages: {
+      zones:
+        'A movement must preserve zone IDs, kinds, orientations and grid dimensions.',
+      items:
+        'A movement must preserve every caller-owned item object and its data.',
+      destination:
+        'The destination must match the item location in the complete candidate.',
+    },
+    accept: (current, candidate, response) => ({
+      ...candidate,
+      items: current.items,
+      proposalResponse: response,
+    }),
+  };
+}
+
+/** Validate the complete atomic proposal before applying a matching revision response. */
+export function respondToDndProposal<T>(
+  current: DndValue<T>,
+  proposal: DndProposal<T>,
+  accepted: boolean,
+): DndProposalResult<T> {
+  return respondToProposal(
+    layoutAdapter<T>(),
+    current,
+    proposal,
+    accepted,
+    true,
+  );
+}
+
+/**
+ * Internal entry for a caller that has already validated `current` and holds
+ * it immutably since (the session keeps its committed value). The proposal and
+ * its complete candidate are still checked in full.
+ */
+export function respondToValidatedDndProposal<T>(
+  current: DndValue<T>,
+  proposal: DndProposal<T>,
+  accepted: boolean,
+): DndProposalResult<T> {
+  return respondToProposal(
+    layoutAdapter<T>(),
+    current,
+    proposal,
+    accepted,
+    false,
+  );
+}
+
+export type DndStateUpdate<T> =
+  LayoutState<T> | ((current: DndValue<T>) => LayoutState<T>);
+export type DndStateStore<T> = {
+  getSnapshot(): DndValue<T>;
+  subscribe(listener: () => void): () => void;
+  onChange(next: DndValue<T>, proposal: DndProposal<T>): void;
+  /** External edits advance the revision and clear the previous proposal response. */
+  setValue(next: DndStateUpdate<T>): void;
+  respond(proposal: DndProposal<T>, accepted: boolean): DndProposalResult<T>;
+};
+
+function assertValid<T>(value: LayoutState<T>): void {
+  const checked = validateLayoutState(value);
+  if (!checked.valid)
+    throw new TypeError(checked.issues.map(issue => issue.message).join(' '));
+}
+
+/** The same synchronous approval path for React state and external stores. */
+export function createDndStateStore<T>(
+  initialValue: LayoutState<T>,
+): DndStateStore<T> {
+  assertValid(initialValue);
+  const store = createApprovalStore<
+    DndValue<T>,
+    DndProposal<T>,
+    LayoutValidationIssue
+  >(
+    {
+      revision: initialValue.revision,
+      items: initialValue.items,
+      zones: initialValue.zones,
+    },
+    respondToDndProposal,
+  );
+  return {
+    getSnapshot: store.getSnapshot,
+    subscribe: store.subscribe,
+    onChange: (next, proposal) => {
+      // The callback carries one complete proposal; two different candidates are ambiguous.
+      if (next !== proposal.value) return;
+      store.respond(proposal, true);
+    },
+    setValue: update => {
+      const value = store.getSnapshot();
+      const next = typeof update === 'function' ? update(value) : update;
+      if (next === value) return;
+      assertValid(next);
+      if (value.revision === Number.MAX_SAFE_INTEGER)
+        throw new RangeError('Layout revision is exhausted.');
+      store.publish({
+        revision: value.revision + 1,
+        items: next.items,
+        zones: next.zones,
+      });
+    },
+    respond: store.respond,
+  };
+}

package/src/controller/gridAdapter.ts

@@ -0,0 +1,268 @@
+import type {
+  DndItem,
+  LayoutLocation,
+  LayoutState,
+  LayoutValidationIssue,
+} from '../contracts';
+import {
+  orderedSlots,
+  slotIndex,
+  slotPosition,
+} from '../engine/gridPlacements';
+import { fromGridValue } from '../engine/layoutState';
+import { hasSameLayout } from '../engine/sameLayout';
+import { validateValue } from '../engine/validation';
+import type {
+  DragEndEvent,
+  GridChange,
+  GridItem,
+  GridValue,
+  ItemLocation,
+  ValidationCode,
+  ValidationIssue,
+} from '../types';
+
+import type { DndDragEndEvent } from './dndSession';
+import type { DndProposal, DndValue } from './dndState';
+
+/**
+ * Maps the `GridValue` API of `GridController` onto the layout-state API of
+ * the shared provider: values, locations, changes, end events and validation
+ * issues. Every function is pure; the component keeps only React state.
+ */
+
+/** The grid API's location for a layout location; ordered grids use slot indices. */
+export function toItemLocation<T>(
+  state: LayoutState<T>,
+  location: LayoutLocation,
+): ItemLocation {
+  if (location.kind === 'list')
+    return {
+      zoneId: location.zoneId,
+      strategy: 'ordered',
+      index: location.index,
+    };
+  const zone = state.zones.find(entry => entry.id === location.zoneId);
+  if (zone?.kind === 'grid' && zone.itemSpan) {
+    const slots = orderedSlots(zone, zone.itemSpan);
+    const index = slotIndex(location.position, zone.itemSpan, slots.perRow);
+    if (index !== null)
+      return { zoneId: location.zoneId, strategy: 'ordered', index };
+  }
+  return {
+    zoneId: location.zoneId,
+    strategy: 'spatial',
+    position: { row: location.position.row, col: location.position.col },
+  };
+}
+
+/** The layout location for a grid API location, or null when it names no slot. */
+export function toLayoutLocation<T>(
+  state: LayoutState<T>,
+  location: ItemLocation,
+): LayoutLocation | null {
+  const zone = state.zones.find(entry => entry.id === location.zoneId);
+  if (!zone) return null;
+  if (zone.kind === 'list')
+    return location.strategy === 'ordered'
+      ? { kind: 'list', zoneId: zone.id, index: location.index }
+      : null;
+  if (location.strategy === 'spatial')
+    return zone.itemSpan
+      ? null
+      : {
+          kind: 'grid',
+          zoneId: zone.id,
+          position: { row: location.position.row, col: location.position.col },
+        };
+  if (
+    !zone.itemSpan ||
+    !Number.isSafeInteger(location.index) ||
+    location.index < 0
+  )
+    return null;
+  const slots = orderedSlots(zone, zone.itemSpan);
+  if (slots.perRow === 0 || location.index >= slots.perRow * slots.rows)
+    return null;
+  return {
+    kind: 'grid',
+    zoneId: zone.id,
+    position: slotPosition(location.index, zone.itemSpan, slots.perRow),
+  };
+}
+
+/** The legacy change record of a proposal; the base revision is optional API. */
+export function gridChangeOf<T>(
+  proposal: DndProposal<T>,
+  includeBaseRevision: boolean,
+): GridChange {
+  return {
+    sessionId: proposal.sessionId,
+    ...(includeBaseRevision ? { baseRevision: proposal.baseRevision } : {}),
+    itemId: proposal.itemId,
+    from: toItemLocation(proposal.value, proposal.from),
+    to: toItemLocation(proposal.value, proposal.to),
+  };
+}
+
+export function gridEndEvent<T>(
+  event: DndDragEndEvent<T>,
+  includeBaseRevision: boolean,
+): DragEndEvent {
+  const base = {
+    sessionId: event.sessionId,
+    itemId: event.itemId,
+    sourceZoneId: event.sourceZoneId,
+    ...(event.error === undefined ? {} : { error: event.error }),
+  };
+  if (event.outcome === 'unchanged') return { ...base, outcome: 'unchanged' };
+  if (event.outcome === 'cancelled')
+    return {
+      ...base,
+      outcome: 'cancelled',
+      reason: event.reason,
+      ...(event.targetZoneId === undefined
+        ? {}
+        : { targetZoneId: event.targetZoneId }),
+      ...(event.policyReason === undefined
+        ? {}
+        : { policyReason: event.policyReason }),
+    };
+  const change = gridChangeOf(event.proposal, includeBaseRevision);
+  return event.response === 'interrupted'
+    ? {
+        ...base,
+        outcome: 'proposed',
+        change,
+        targetZoneId: event.targetZoneId,
+        response: 'interrupted',
+        reason: event.reason,
+      }
+    : {
+        ...base,
+        outcome: 'proposed',
+        change,
+        targetZoneId: event.targetZoneId,
+        response: event.response,
+      };
+}
+
+const GRID_CODES = new Set<string>([
+  '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',
+]);
+
+/** Layout-state issues in the grid API's vocabulary. */
+export function gridIssues(
+  issues: ReadonlyArray<
+    Pick<LayoutValidationIssue, 'message' | 'zoneId' | 'itemId'> & {
+      code: string;
+    }
+  >,
+): ValidationIssue[] {
+  return issues.map(issue => ({
+    code: (GRID_CODES.has(issue.code)
+      ? issue.code
+      : 'invalid-structure') as ValidationCode,
+    message: issue.message,
+    ...(issue.zoneId === undefined ? {} : { zoneId: issue.zoneId }),
+    ...(issue.itemId === undefined ? {} : { itemId: issue.itemId }),
+  }));
+}
+
+export type ConvertedGridValue<T> = {
+  /** Null when the grid value is invalid; `issues` then explains why. */
+  state: DndValue<T> | null;
+  issues: ValidationIssue[];
+  revision: number;
+};
+
+export type PreviousConversion<T> = {
+  value: GridValue<T>;
+  revision: number;
+  state: DndValue<T> | null;
+};
+
+/**
+ * Convert a committed grid value for the provider. Values without a revision
+ * receive a synthetic one that advances whenever the layout changes, so the
+ * provider's revision protocol still detects edits; a response that omits its
+ * base revision is attributed to the proposal it answers. Item objects whose
+ * data is unchanged keep their identity, so cells and the approval reducer see
+ * stable objects; acceptance itself compares layout and revision only, so an
+ * owner may rebuild an item's data for its new zone.
+ */
+export function convertGridValue<T>(
+  value: GridValue<T>,
+  previous: PreviousConversion<T> | null,
+  pendingBaseRevision: number | undefined,
+): ConvertedGridValue<T> {
+  const checked = validateValue(value);
+  const revision =
+    value.revision ??
+    (previous === null
+      ? 0
+      : hasSameLayout(previous.value, value)
+        ? previous.revision
+        : previous.revision + 1);
+  if (!checked.valid) return { state: null, issues: checked.issues, revision };
+  const converted = fromGridValue(value, revision);
+  if (!converted.valid)
+    return { state: null, issues: gridIssues(converted.issues), revision };
+  const state = converted.value;
+  if (previous?.state)
+    state.items = reuseItems(state.items, previous.state.items);
+  const response = value.proposalResponse;
+  return {
+    revision,
+    issues: [],
+    state: response
+      ? {
+          ...state,
+          proposalResponse: {
+            sessionId: response.sessionId,
+            accepted: response.accepted,
+            baseRevision:
+              response.baseRevision ?? pendingBaseRevision ?? revision,
+          },
+        }
+      : state,
+  };
+}
+
+function reuseItems<T>(
+  items: DndItem<T>[],
+  previous: DndItem<T>[],
+): DndItem<T>[] {
+  const known = new Map(previous.map(item => [item.id, item]));
+  let same = items.length === previous.length;
+  const reused = items.map((item, index) => {
+    const before = known.get(item.id);
+    const kept = before && Object.is(before.data, item.data) ? before : item;
+    if (kept !== previous[index]) same = false;
+    return kept;
+  });
+  return same ? previous : reused;
+}
+
+/** The caller's own item objects by ID, so render callbacks see stable identities. */
+export function gridItemIndex<T>(
+  value: GridValue<T>,
+): Map<string, GridItem<T>> {
+  const items = new Map<string, GridItem<T>>();
+  for (const zone of value.zones)
+    for (const item of zone.items) items.set(item.id, item);
+  return items;
+}

package/src/controller/gridState.ts

@@ -0,0 +1,187 @@
+import { isCellPosition, isRecord, validateValue } from '../engine/validation';
+import type {
+  GridChange,
+  GridProposal,
+  GridValue,
+  ItemLocation,
+  RevisionedGridValue,
+  ValidationIssue,
+} from '../types';
+
+import {
+  createApprovalStore,
+  respondToProposal,
+  type ApprovalAdapter,
+  type ApprovalResult,
+} from './approval';
+import { itemLocation, sameItemLocation } from './locations';
+
+export type GridProposalResult<T> = ApprovalResult<
+  RevisionedGridValue<T>,
+  ValidationIssue
+>;
+
+function isLocation(value: unknown): value is ItemLocation {
+  if (!isRecord(value) || typeof value.zoneId !== 'string') return false;
+  return value.strategy === 'ordered'
+    ? typeof value.index === 'number' &&
+        Number.isSafeInteger(value.index) &&
+        value.index >= 0
+    : value.strategy === 'spatial' &&
+        isCellPosition(value.position) &&
+        value.position.row >= 0 &&
+        value.position.col >= 0;
+}
+
+function issues<T>(value: GridValue<T>): ValidationIssue[] | null {
+  const checked = validateValue(value);
+  return checked.valid ? null : checked.issues;
+}
+
+function gridAdapter<T>(): ApprovalAdapter<
+  RevisionedGridValue<T>,
+  ItemLocation,
+  ValidationIssue
+> {
+  return {
+    validateCurrent: current =>
+      issues(current) ??
+      (!Number.isSafeInteger(current.revision) || current.revision < 0
+        ? [
+            {
+              code: 'invalid-structure',
+              message:
+                'Current grid state must have a non-negative safe integer revision.',
+            },
+          ]
+        : null),
+    validateCandidate: issues,
+    issue: message => ({ code: 'invalid-structure', message }),
+    isLocation,
+    location: itemLocation,
+    sameLocation: sameItemLocation,
+    hasDestinationZone: (value, to) =>
+      value.zones.some(
+        zone => zone.id === to.zoneId && zone.strategy === to.strategy,
+      ),
+    zonesPreserved: (current, candidate) => {
+      const zones = new Map(current.zones.map(zone => [zone.id, zone]));
+      return (
+        candidate.zones.length === zones.size &&
+        candidate.zones.every(zone => {
+          const original = zones.get(zone.id);
+          return (
+            original !== undefined &&
+            original.strategy === zone.strategy &&
+            original.rows === zone.rows &&
+            original.columns === zone.columns &&
+            (original.strategy !== 'ordered' ||
+              zone.strategy !== 'ordered' ||
+              (original.itemSpan.rows === zone.itemSpan.rows &&
+                original.itemSpan.cols === zone.itemSpan.cols))
+          );
+        })
+      );
+    },
+    // A movement may change layout, never the caller's item set or opaque data.
+    itemsPreserved: (current, candidate) => {
+      const items = new Map(
+        current.zones.flatMap(zone => zone.items).map(item => [item.id, item]),
+      );
+      const proposed = candidate.zones.flatMap(zone => zone.items);
+      return (
+        proposed.length === items.size &&
+        proposed.every(item => {
+          const original = items.get(item.id);
+          return (
+            original !== undefined &&
+            Object.is(original.data, item.data) &&
+            original.span.rows === item.span.rows &&
+            original.span.cols === item.span.cols &&
+            original.placement === item.placement
+          );
+        })
+      );
+    },
+    messages: {
+      zones:
+        'A grid proposal must preserve zone IDs, strategies, dimensions and ordered item spans.',
+      items:
+        'A grid proposal must preserve all item IDs, spans, placement policies and caller data.',
+      destination:
+        'The proposed destination must match the item location in the complete candidate.',
+    },
+    accept: (_current, candidate, response) => ({
+      ...candidate,
+      proposalResponse: response,
+    }),
+  };
+}
+
+/** A response only changes the exact revision on which the complete proposal was based. */
+export function respondToGridProposal<T>(
+  current: RevisionedGridValue<T>,
+  proposal: GridProposal<T>,
+  accepted: boolean,
+): GridProposalResult<T> {
+  return respondToProposal(gridAdapter<T>(), current, proposal, accepted, true);
+}
+
+export type GridStateUpdate<T> =
+  GridValue<T> | ((current: RevisionedGridValue<T>) => GridValue<T>);
+export type GridStateStore<T> = {
+  getSnapshot(): RevisionedGridValue<T>;
+  subscribe(listener: () => void): () => void;
+  /** Synchronously accept valid controller proposals. Use canDrop for synchronous rejection. */
+  onChange(next: GridValue<T>, change: GridChange): void;
+  /** External edits advance the revision and clear any previous response. */
+  setValue(next: GridStateUpdate<T>): void;
+  respond(proposal: GridProposal<T>, accepted: boolean): GridProposalResult<T>;
+};
+
+function assertValid<T>(value: GridValue<T>): void {
+  const result = validateValue(value);
+  if (!result.valid)
+    throw new TypeError(result.issues.map(issue => issue.message).join(' '));
+}
+
+/** React-independent store; the state hook and external stores share the response reducer. */
+export function createGridStateStore<T>(
+  initialValue: GridValue<T>,
+): GridStateStore<T> {
+  assertValid(initialValue);
+  const store = createApprovalStore<
+    RevisionedGridValue<T>,
+    GridProposal<T>,
+    ValidationIssue
+  >(
+    { zones: initialValue.zones, revision: initialValue.revision ?? 0 },
+    respondToGridProposal,
+  );
+  return {
+    getSnapshot: store.getSnapshot,
+    subscribe: store.subscribe,
+    onChange: (next, change) => {
+      if (change.baseRevision === undefined || next.revision === undefined)
+        return;
+      store.respond(
+        {
+          ...change,
+          baseRevision: change.baseRevision,
+          value: { ...next, revision: next.revision },
+        },
+        true,
+      );
+    },
+    setValue: update => {
+      const value = store.getSnapshot();
+      const next = typeof update === 'function' ? update(value) : update;
+      if (next === value) return;
+      assertValid(next);
+      if (value.revision === Number.MAX_SAFE_INTEGER)
+        throw new RangeError('Grid revision is exhausted.');
+      store.publish({ zones: next.zones, revision: value.revision + 1 });
+    },
+    respond: store.respond,
+  };
+}