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

package/src/components/DragHandle.tsx

@@ -0,0 +1,89 @@
+import { useContext, useLayoutEffect, useRef } from 'react';
+import { type HostInstance, View } from 'react-native';
+import { useAnimatedRef } from 'react-native-reanimated';
+
+import { validateGestureRelations } from '../gesture/gestureConfig';
+import {
+  DndItemContext,
+  useDndHandleActive,
+  useDndRuntime,
+} from '../runtime/dndRuntime';
+import type { DragHandleProps } from './dndTypes';
+import { pickHandleViewProps as viewProps } from './handleViewProps';
+
+/** Registers a hit area. Native gesture ownership stays with the Provider. */
+export function DragHandle(props: DragHandleProps) {
+  const runtime = useDndRuntime();
+  const scope = useContext(DndItemContext);
+  const ref = useAnimatedRef<HostInstance>();
+  const identity = useRef({}).current;
+  const relations = validateGestureRelations(props.gestureRelations);
+  const valid =
+    !!scope &&
+    (props.itemId === undefined || props.itemId === scope.itemId) &&
+    relations.valid;
+  const { cancel, reportIssues, registerHandle, unregisterHandle } = runtime;
+  const itemId = scope?.itemId;
+  const disabledWhileActive = useDndHandleActive(
+    runtime,
+    itemId,
+    props.disabled === true,
+  );
+  useLayoutEffect(() => {
+    if (scope?.preview) return;
+    const owner = `handle:${scope?.zoneId}:${itemId}`;
+    reportIssues(
+      owner,
+      valid
+        ? []
+        : [
+            {
+              code: 'invalid-configuration',
+              itemId,
+              message:
+                'DragHandle must be inside its matching list item with valid gesture relations.',
+            },
+          ],
+    );
+    if (disabledWhileActive) cancel('disabled');
+    return () => reportIssues(owner, []);
+  }, [
+    cancel,
+    itemId,
+    props.disabled,
+    reportIssues,
+    disabledWhileActive,
+    scope?.preview,
+    scope?.zoneId,
+    valid,
+  ]);
+  useLayoutEffect(() => {
+    if (!valid || !scope || scope.preview || !relations.valid) {
+      unregisterHandle(identity);
+      return;
+    }
+    registerHandle(
+      {
+        itemId: scope.itemId,
+        zoneId: scope.zoneId,
+        ref,
+        sourceRef: scope.ref,
+        disabled: props.disabled === true,
+        gestureRelations: relations.relations,
+      },
+      identity,
+    );
+  });
+  useLayoutEffect(
+    () => () => unregisterHandle(identity),
+    [identity, unregisterHandle],
+  );
+  // The preview copy keeps the same labels but never attaches a gesture.
+  if (!valid || !scope || scope.preview)
+    return <View {...viewProps(props)}>{props.children}</View>;
+  return (
+    <View {...viewProps(props)} ref={ref} collapsable={false}>
+      {props.children}
+    </View>
+  );
+}

package/src/components/GridController.tsx

@@ -0,0 +1,213 @@
+import {
+  createContext,
+  type ReactNode,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+
+import type { DndDragEndEvent } from '../controller/dndSession';
+import type { DndProposal, DndValue } from '../controller/dndState';
+import {
+  convertGridValue,
+  gridChangeOf,
+  gridEndEvent,
+  gridIssues,
+  gridItemIndex,
+  type PreviousConversion,
+} from '../controller/gridAdapter';
+import type { LayoutValidationIssue } from '../contracts';
+import { layoutToGridValue } from '../engine/layoutState';
+import type { GridItem } from '../types';
+
+import { DndProvider } from './DndProvider';
+import type { DndPreviewArgs } from './dndTypes';
+import type { GridControllerProps, ItemRenderArgs } from './gridTypes';
+
+/** What `GridZoneView` needs from its controller to render the grid API's items. */
+export type GridAdapterScope<T> = {
+  renderItem(args: ItemRenderArgs<T>): ReactNode;
+  /** The caller's own item object, so render callbacks see stable identities. */
+  itemOf(itemId: string): GridItem<T> | undefined;
+};
+
+export const GridAdapterContext =
+  createContext<GridAdapterScope<unknown> | null>(null);
+
+const EMPTY_STATE: DndValue<never> = { revision: 0, items: [], zones: [] };
+
+/**
+ * The grid API on the shared provider. `GridValue` is converted to the
+ * provider's layout state once per committed value; candidates, changes and
+ * end events are converted back with their ordered zones, item data and
+ * revision intact. Zones render through `GridZoneView`, handles through
+ * `GridDragHandle`; both are thin wrappers over the provider's components.
+ * `onDragEnd` is delivered once the preview has settled, as the grid API
+ * always did (the provider's `onDragSettled` timing).
+ */
+export function GridController<T>({
+  value,
+  onChange,
+  renderItem,
+  renderDragPreview,
+  waitForDragPreviewReady = false,
+  dragPreviewStyle,
+  canDrop,
+  onDragStart,
+  onDragEnd,
+  onValidationError,
+  onDiagnostic,
+  searchBudget,
+  activation,
+  movementPolicy,
+  motion,
+  responseTimeoutMs,
+  disabled = false,
+  ref,
+  children,
+  ...viewProps
+}: GridControllerProps<T>) {
+  // Values without a revision get a synthetic one that advances with each
+  // layout change; a response without a base revision answers the pending
+  // proposal.
+  const previous = useRef<PreviousConversion<T> | null>(null);
+  const pendingProposal = useRef<DndProposal<T> | null>(null);
+  const [lastValidState, setLastValidState] = useState<DndValue<T> | null>(
+    null,
+  );
+  const converted = useMemo(
+    () =>
+      convertGridValue(
+        value,
+        previous.current,
+        pendingProposal.current?.baseRevision,
+      ),
+    [value],
+  );
+  previous.current = {
+    value,
+    revision: converted.revision,
+    state: converted.state ?? previous.current?.state ?? null,
+  };
+  const state =
+    converted.state ?? lastValidState ?? (EMPTY_STATE as DndValue<T>);
+  useEffect(() => {
+    if (converted.state) setLastValidState(converted.state);
+  }, [converted.state]);
+  const includeBaseRevision = value.revision !== undefined;
+
+  const items = useMemo(() => gridItemIndex(value), [value]);
+  const itemOf = useCallback((itemId: string) => items.get(itemId), [items]);
+  const scope = useMemo<GridAdapterScope<T>>(
+    () => ({ renderItem, itemOf }),
+    [renderItem, itemOf],
+  );
+
+  // Input validation keeps the grid API's issue codes; provider issues (zone
+  // geometry, handles) are translated. Repeating the same issues does not
+  // notify again, and an invalid value silences the zone issues it causes.
+  const valueValid = converted.state !== null;
+  const lastValueIssues = useRef<string | null>(null);
+  const lastProviderIssues = useRef<string | null>(null);
+  useEffect(() => {
+    const key = converted.issues.length
+      ? JSON.stringify(converted.issues)
+      : null;
+    if (key === lastValueIssues.current) return;
+    lastValueIssues.current = key;
+    if (key) onValidationError?.(converted.issues);
+  }, [converted.issues, onValidationError]);
+  const handleProviderIssues = useCallback(
+    (issues: LayoutValidationIssue[]) => {
+      if (!valueValid) return;
+      const key = issues.length ? JSON.stringify(issues) : null;
+      if (key === lastProviderIssues.current) return;
+      lastProviderIssues.current = key;
+      if (key) onValidationError?.(gridIssues(issues));
+    },
+    [onValidationError, valueValid],
+  );
+
+  const handleChange = useCallback(
+    (next: DndValue<T>, proposal: DndProposal<T>) => {
+      pendingProposal.current = proposal;
+      onChange(
+        layoutToGridValue(next),
+        gridChangeOf(proposal, includeBaseRevision),
+      );
+    },
+    [onChange, includeBaseRevision],
+  );
+  const handleDrop = useMemo(
+    () =>
+      canDrop
+        ? (proposal: DndProposal<T>) => {
+            const item = itemOf(proposal.itemId);
+            if (!item) return { allowed: false, reason: 'unknown-item' };
+            return canDrop({
+              item,
+              change: gridChangeOf(proposal, includeBaseRevision),
+              proposedValue: layoutToGridValue(proposal.value),
+            });
+          }
+        : undefined,
+    [canDrop, itemOf, includeBaseRevision],
+  );
+  const handleEnd = useCallback(
+    (event: DndDragEndEvent<T>) => {
+      pendingProposal.current = null;
+      onDragEnd?.(gridEndEvent(event, includeBaseRevision));
+    },
+    [onDragEnd, includeBaseRevision],
+  );
+  const handlePreview = useMemo(
+    () =>
+      renderDragPreview
+        ? (args: DndPreviewArgs<T>) => {
+            const item = itemOf(args.item.id);
+            if (!item) return null;
+            return renderDragPreview({
+              item,
+              width: args.width,
+              height: args.height,
+              isDragging: true,
+              sessionId: args.sessionId,
+              onReady: args.onReady,
+              sourceZoneId: args.zoneId,
+              targetZoneId: args.targetZoneId,
+              validity: args.validity,
+            });
+          }
+        : undefined,
+    [renderDragPreview, itemOf],
+  );
+
+  return (
+    <DndProvider<T>
+      {...viewProps}
+      ref={ref}
+      value={state}
+      onChange={handleChange}
+      canDrop={handleDrop}
+      onDragStart={onDragStart}
+      onDragSettled={handleEnd}
+      onValidationError={handleProviderIssues}
+      onDiagnostic={onDiagnostic}
+      searchBudget={searchBudget}
+      activation={activation}
+      movementPolicy={movementPolicy}
+      motion={motion}
+      responseTimeoutMs={responseTimeoutMs}
+      disabled={disabled || converted.state === null}
+      renderDragPreview={handlePreview}
+      waitForDragPreviewReady={waitForDragPreviewReady}
+      dragPreviewStyle={dragPreviewStyle}
+    >
+      <GridAdapterContext value={scope as GridAdapterScope<unknown>}>
+        {children}
+      </GridAdapterContext>
+    </DndProvider>
+  );
+}

package/src/components/GridDragHandle.tsx

@@ -0,0 +1,11 @@
+import { DragHandle } from './DragHandle';
+import type { GridDragHandleProps } from './gridTypes';
+
+/**
+ * A grid item's hit area. The provider owns one native recognizer per gesture
+ * relation signature, so mounting, re-rendering or unmounting a handle never
+ * creates, re-serializes or drops a native handler.
+ */
+export function GridDragHandle(props: GridDragHandleProps) {
+  return <DragHandle {...props} />;
+}

package/src/components/GridZoneView.tsx

@@ -0,0 +1,57 @@
+import { useCallback, useContext } from 'react';
+import { StyleSheet } from 'react-native';
+
+import type { GridItem } from '../types';
+
+import type { GridItemRenderArgs } from './dndTypes';
+import { GridAdapterContext } from './GridController';
+import type { GridZoneViewProps } from './gridTypes';
+import { SortableGrid } from './SortableGrid';
+
+/**
+ * One zone of a `GridController`: the provider's grid adapter rendering the
+ * controller's `renderItem` with the grid API's arguments. Ordered zones
+ * (`strategy: 'ordered'`) keep their slot layout and capacity.
+ */
+export function GridZoneView({
+  zoneId,
+  geometry,
+  children,
+  ...props
+}: GridZoneViewProps) {
+  const scope = useContext(GridAdapterContext);
+  if (!scope) throw new Error('GridZoneView must be inside GridController.');
+  const { renderItem, itemOf } = scope;
+  const renderCell = useCallback(
+    (args: GridItemRenderArgs<unknown>) => {
+      const item: GridItem<unknown> = itemOf(args.item.id) ?? {
+        id: args.item.id,
+        data: args.item.data,
+        span: args.span,
+        ...(args.placement === undefined ? {} : { placement: args.placement }),
+      };
+      return renderItem({
+        item,
+        zoneId: args.zoneId,
+        width: args.width,
+        height: args.height,
+        isDragging: args.isDragging,
+      });
+    },
+    [renderItem, itemOf],
+  );
+  return (
+    <SortableGrid
+      {...props}
+      zoneId={zoneId}
+      geometry={geometry}
+      renderItem={renderCell}
+      // The grid API moves neighbors instead of drawing a destination marker.
+      dropIndicatorStyle={styles.noIndicator}
+    >
+      {children}
+    </SortableGrid>
+  );
+}
+
+const styles = StyleSheet.create({ noIndicator: { display: 'none' } });