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

package/src/gesture/gestureGrouping.ts

@@ -0,0 +1,210 @@
+import type { PanGesture } from 'react-native-gesture-handler';
+
+import { sameGestureRelations } from './gestureConfig';
+
+import type { GestureRelations } from '../components/gridTypes';
+
+/** One registered handle as the gesture host sees it. */
+export type GestureOwner<Registration> = {
+  id: number;
+  registration: Registration;
+};
+
+export type GestureRegistry<Registration> = {
+  getSnapshot(): readonly GestureOwner<Registration>[];
+  subscribe(listener: () => void): () => void;
+  setOwners(next: readonly GestureOwner<Registration>[]): void;
+};
+
+/** Handle mounts update their native owners without rendering the controller. */
+export function createGestureRegistry<
+  Registration,
+>(): GestureRegistry<Registration> {
+  let owners: readonly GestureOwner<Registration>[] = [];
+  const listeners = new Set<() => void>();
+  return {
+    getSnapshot: () => owners,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    setOwners(next) {
+      if (
+        next.length === owners.length &&
+        next.every(
+          (owner, index) =>
+            owner.id === owners[index]!.id &&
+            owner.registration === owners[index]!.registration,
+        )
+      )
+        return;
+      owners = next.map(({ id, registration }) => ({ id, registration }));
+      for (const listener of Array.from(listeners)) listener();
+    },
+  };
+}
+
+/**
+ * Delivers a group's hit targets without re-rendering the group. A re-render
+ * would make Reanimated and Gesture Handler rebuild and re-register the native
+ * event handler, which costs a serialization of every callback closure.
+ */
+export type TargetChannel<Target> = {
+  readonly targets: readonly Target[];
+  subscribe(listener: (targets: readonly Target[]) => void): () => void;
+};
+
+export type PublishedTargetChannel<Target> = TargetChannel<Target> & {
+  set(targets: readonly Target[]): void;
+};
+
+export function createTargetChannel<Target>(
+  initial: readonly Target[],
+): PublishedTargetChannel<Target> {
+  let targets = initial;
+  const listeners = new Set<(targets: readonly Target[]) => void>();
+  return {
+    get targets() {
+      return targets;
+    },
+    set(next) {
+      if (next === targets) return;
+      targets = next;
+      for (const listener of Array.from(listeners)) listener(next);
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}
+
+/** Props of one shared-recognizer component rendered by a gesture host. */
+export type GestureGroupProps<Runtime, Target> = {
+  groupId: number;
+  relations: GestureRelations | undefined;
+  channel: TargetChannel<Target>;
+  runtime: Runtime;
+  publish(groupId: number, gesture: PanGesture | null): void;
+};
+
+/** Handles sharing one relation signature share one native recognizer. */
+export type GestureGroupSnapshot<Target> = {
+  groupId: number;
+  relations: GestureRelations | undefined;
+  targets: readonly Target[];
+  /** Stable per group; the group element never re-renders for target changes. */
+  channel: PublishedTargetChannel<Target>;
+};
+
+export type GroupingState<Registration, Target> = {
+  targets: Map<number, { registration: Registration; target: Target }>;
+  signatures: Array<{
+    relations: GestureRelations | undefined;
+    groupId: number;
+  }>;
+  nextGroupId: number;
+  groups: readonly GestureGroupSnapshot<Target>[];
+};
+
+export function createGroupingState<Registration, Target>(): GroupingState<
+  Registration,
+  Target
+> {
+  return { targets: new Map(), signatures: [], nextGroupId: 0, groups: [] };
+}
+
+function sameTargets<Target>(
+  previous: readonly Target[],
+  next: readonly Target[],
+): boolean {
+  return (
+    previous.length === next.length &&
+    previous.every((target, index) => target === next[index])
+  );
+}
+
+/**
+ * Groups the published owners by gesture relation signature. Target objects
+ * stay identical while their registration is unchanged and a group's target
+ * array stays identical while its content is unchanged, so an unchanged group
+ * publishes nothing to the UI runtime.
+ */
+export function groupGestureOwners<
+  Registration extends { gestureRelations?: GestureRelations },
+  Target,
+>(
+  owners: readonly GestureOwner<Registration>[],
+  state: GroupingState<Registration, Target>,
+  toTarget: (owner: GestureOwner<Registration>) => Target,
+): readonly GestureGroupSnapshot<Target>[] {
+  const targets = new Map<
+    number,
+    { registration: Registration; target: Target }
+  >();
+  const collected = new Map<
+    number,
+    { relations: GestureRelations | undefined; targets: Target[] }
+  >();
+  for (const owner of owners) {
+    const cached = state.targets.get(owner.id);
+    const target =
+      cached?.registration === owner.registration
+        ? cached.target
+        : toTarget(owner);
+    targets.set(owner.id, { registration: owner.registration, target });
+    let signature = state.signatures.find(entry =>
+      sameGestureRelations(
+        entry.relations,
+        owner.registration.gestureRelations,
+      ),
+    );
+    if (!signature) {
+      signature = {
+        relations: owner.registration.gestureRelations,
+        groupId: ++state.nextGroupId,
+      };
+      state.signatures.push(signature);
+    }
+    const group = collected.get(signature.groupId);
+    if (group) group.targets.push(target);
+    else
+      collected.set(signature.groupId, {
+        relations: signature.relations,
+        targets: [target],
+      });
+  }
+  state.targets = targets;
+  // A signature without handles releases its native recognizer.
+  state.signatures = state.signatures.filter(entry =>
+    collected.has(entry.groupId),
+  );
+  const groups = Array.from(collected, ([groupId, group]) => {
+    const previous = state.groups.find(entry => entry.groupId === groupId);
+    const hitTargets =
+      previous && sameTargets(previous.targets, group.targets)
+        ? previous.targets
+        : group.targets;
+    return {
+      groupId,
+      relations: previous?.relations ?? group.relations,
+      targets: hitTargets,
+      channel: previous?.channel ?? createTargetChannel(hitTargets),
+    };
+  });
+  state.groups =
+    groups.length === state.groups.length &&
+    groups.every(
+      (group, index) =>
+        group.groupId === state.groups[index]!.groupId &&
+        group.targets === state.groups[index]!.targets &&
+        group.relations === state.groups[index]!.relations,
+    )
+      ? state.groups
+      : groups;
+  return state.groups;
+}

package/src/gesture/gestureHost.tsx

@@ -0,0 +1,163 @@
+import {
+  createContext,
+  memo,
+  useCallback,
+  useContext,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ComponentType,
+  type ReactElement,
+} from 'react';
+import {
+  GestureDetector,
+  useCompetingGestures,
+  useManualGesture,
+  type ManualGestureConfig,
+  type PanGesture,
+} from 'react-native-gesture-handler';
+
+import {
+  createGroupingState,
+  groupGestureOwners,
+  type GestureGroupProps,
+  type GestureOwner,
+  type GestureRegistry,
+} from './gestureGrouping';
+import type { GestureRelations } from '../components/gridTypes';
+
+export type GestureHostProps<Registration, Runtime> = {
+  registry: GestureRegistry<Registration>;
+  runtime: Runtime;
+};
+
+const SENTINEL_CONFIG: ManualGestureConfig = {
+  enabled: false,
+  onTouchesDown: () => {
+    'worklet';
+  },
+};
+
+/**
+ * Builds a host that owns one native recognizer per gesture relation
+ * signature. Handle mounts publish through the registry; the host groups them,
+ * renders one `Group` per signature and composes their recognizers on a single
+ * detector around the root content. Root content updates never render the
+ * detector or the groups.
+ */
+export function createGestureHost<
+  Registration extends { gestureRelations?: GestureRelations },
+  Target,
+  Runtime,
+>({
+  Group,
+  toTarget,
+}: {
+  Group: ComponentType<GestureGroupProps<Runtime, Target>>;
+  toTarget(owner: GestureOwner<Registration>): Target;
+}) {
+  const RootContentContext = createContext<ReactElement | null>(null);
+
+  // Only this descendant consumes changing root content. Its context update does
+  // not render the detector or re-run the gesture composition hooks above it.
+  function NativeRoot() {
+    return useContext(RootContentContext);
+  }
+
+  const GestureGroup = memo(Group);
+
+  const NativeGestureDetector = memo(function NativeGestureDetectorImpl({
+    nativeGestures,
+  }: {
+    nativeGestures: ReadonlyMap<number, PanGesture>;
+  }) {
+    // Keep the native component type stable while no handle is registered.
+    const sentinel = useManualGesture(SENTINEL_CONFIG);
+    const gesture = useCompetingGestures(sentinel, ...nativeGestures.values());
+    return (
+      <GestureDetector gesture={gesture}>
+        <NativeRoot />
+      </GestureDetector>
+    );
+  });
+
+  const GestureHost = memo(function GestureHostImpl({
+    registry,
+    runtime,
+  }: GestureHostProps<Registration, Runtime>) {
+    const owners = useSyncExternalStore(
+      registry.subscribe,
+      registry.getSnapshot,
+      registry.getSnapshot,
+    );
+    const mounted = useRef(true);
+    const gestureValues = useRef(new Map<number, PanGesture>());
+    const [gestureVersion, setGestureVersion] = useState(0);
+    // Group layout effects can publish several changes in one commit. Update
+    // their private map in O(1), then copy once when React renders the combined
+    // update. Never mutate the snapshot passed to the memoized detector.
+    const nativeGestures = useMemo(
+      () => new Map(gestureValues.current),
+      // The version explicitly invalidates this snapshot of the mutable registry.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [gestureVersion],
+    );
+    useLayoutEffect(() => {
+      mounted.current = true;
+      return () => {
+        mounted.current = false;
+      };
+    }, []);
+    const publish = useCallback((id: number, gesture: PanGesture | null) => {
+      if (!mounted.current) return;
+      const current = gestureValues.current;
+      if (gesture ? current.get(id) === gesture : !current.has(id)) return;
+      if (gesture) current.set(id, gesture);
+      else current.delete(id);
+      setGestureVersion(version => version + 1);
+    }, []);
+    const grouping = useRef(
+      createGroupingState<Registration, Target>(),
+    ).current;
+    // Re-running this for the same owners is idempotent, which keeps StrictMode
+    // and discarded renders from producing different group identities.
+    const groups = useMemo(
+      () => groupGestureOwners(owners, grouping, toTarget),
+      [owners, grouping],
+    );
+    // Publish after commit: the group's subscription effect is registered first.
+    useLayoutEffect(() => {
+      for (const group of groups) group.channel.set(group.targets);
+    }, [groups]);
+
+    return (
+      <>
+        <NativeGestureDetector nativeGestures={nativeGestures} />
+        {groups.map(group => (
+          <GestureGroup
+            key={group.groupId}
+            groupId={group.groupId}
+            relations={group.relations}
+            channel={group.channel}
+            runtime={runtime}
+            publish={publish}
+          />
+        ))}
+      </>
+    );
+  });
+
+  return function Host({
+    children,
+    registry,
+    runtime,
+  }: GestureHostProps<Registration, Runtime> & { children: ReactElement }) {
+    return (
+      <RootContentContext value={children}>
+        <GestureHost registry={registry} runtime={runtime} />
+      </RootContentContext>
+    );
+  };
+}

package/src/index.ts

@@ -0,0 +1,162 @@
+export { GridController } from './components/GridController';
+export { DndProvider } from './components/DndProvider';
+export { SortableList } from './components/SortableList';
+export { SortableGrid } from './components/SortableGrid';
+export { resolveListVirtualization } from './adapters/virtualizedList';
+export type {
+  ListVirtualizationOptions,
+  ListVirtualizationResult,
+} from './adapters/virtualizedList';
+export { DragHandle } from './components/DragHandle';
+export type {
+  DndProviderHandle,
+  DndProviderProps,
+  SortableListProps,
+  SortableGridProps,
+  GridItemRenderArgs,
+  DragHandleProps,
+  DragHandleViewProps,
+  ListItemRenderArgs,
+  DndPreviewArgs,
+  DndMotionConfig,
+} from './components/dndTypes';
+export { useDndState } from './controller/useDndState';
+export type { DndState } from './controller/useDndState';
+export {
+  createDndStateStore,
+  respondToDndProposal,
+} from './controller/dndState';
+export type {
+  DndValue,
+  DndProposal,
+  DndProposalResult,
+  DndStateStore,
+  DndStateUpdate,
+} from './controller/dndState';
+export type {
+  DndCancelReason,
+  DndDragEndEvent,
+  DndDropFailureReason,
+  GridItemLayoutResolverArgs,
+} from './controller/dndSession';
+export {
+  computeListLayout,
+  computeListIndex,
+  ListSizeCache,
+} from './engine/list';
+export type {
+  ListLayout,
+  ListLayoutEntry,
+  ListLayoutInput,
+  ListLayoutResult,
+  ListMeasurementContext,
+} from './engine/list';
+export { computeLayoutMove } from './engine/layoutMove';
+export type {
+  GridItemLayout,
+  LayoutMoveInput,
+  LayoutMoveResult,
+} from './engine/layoutMove';
+export {
+  computeAutoScroll,
+  constrainDragPoint,
+  validateAutoScrollOptions,
+} from './adapters/scroll';
+export type {
+  AutoScrollInput,
+  AutoScrollOptions,
+  AutoScrollOptionsValidationResult,
+  AutoScrollResult,
+  DragAxis,
+} from './adapters/scroll';
+export { GridDragHandle } from './components/GridDragHandle';
+export { GridZoneView } from './components/GridZoneView';
+export { useGridState } from './controller/useGridState';
+export type { GridState } from './controller/useGridState';
+export {
+  createGridStateStore,
+  respondToGridProposal,
+} from './controller/gridState';
+export type {
+  GridStateStore,
+  GridStateUpdate,
+  GridProposalResult,
+} from './controller/gridState';
+export type { GridMotionConfig } from './pointer/motion';
+export type { HandleViewProps } from './components/handleViewProps';
+export { DEFAULT_ACTIVATION_DELAY_MS, DEFAULT_SEARCH_BUDGET } from './defaults';
+export {
+  DEFAULT_GRID_MOVEMENT_POLICY,
+  HOME_GRID_MOVEMENT_POLICY,
+  resolveGridMovementPolicy,
+  validateGridMovementPolicy,
+} from './engine/movementPolicy';
+export type {
+  GridMoveCandidate,
+  GridMovementPolicy,
+  ResolvedGridMovementPolicy,
+} from './engine/movementPolicy';
+export type * from './contracts';
+export {
+  validateLayoutState,
+  fromGridValue,
+  toGridValue,
+} from './engine/layoutState';
+export {
+  screenToContent,
+  contentToScreen,
+  screenRectToContent,
+  contentRectToScreen,
+  validateRectMeasurement,
+} from './adapters/coordinates';
+export type {
+  DragPreviewArgs,
+  GestureRelations,
+  GridControllerHandle,
+  GridControllerProps,
+  GridDragHandleProps,
+  GridInsets,
+  GridZoneViewProps,
+  ItemRenderArgs,
+  ZoneGeometry,
+} from './components/gridTypes';
+export type { OrderedIndexInput, OrderedIndexResult } from './engine';
+export {
+  computeMove,
+  computeOrderedIndex,
+  computeZoneLayout,
+  hasSameLayout,
+  packItems,
+  validateValue,
+} from './engine';
+export type {
+  CancelReason,
+  CanDropArgs,
+  CellPosition,
+  CellSpan,
+  CleanupReason,
+  DragEndEvent,
+  DragStartEvent,
+  DropDecision,
+  GridChange,
+  GridDiagnosticEvent,
+  GridItem,
+  GridProposal,
+  GridValue,
+  GridZone,
+  ItemLocation,
+  ItemPlacement,
+  MoveInput,
+  MoveResult,
+  OrderedZone,
+  PackInput,
+  PackResult,
+  PositionedItem,
+  RevisionedGridValue,
+  ProposalInterruptReason,
+  SpatialZone,
+  ValidationCode,
+  ValidationIssue,
+  ValidationResult,
+  ZoneLayoutResult,
+} from './types';