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

package/README.md

@@ -1,5 +1,8 @@
 # React Native Layout DnD
 
+[![npm](https://img.shields.io/npm/v/react-native-layout-dnd)](https://www.npmjs.com/package/react-native-layout-dnd)
+[![CI](https://github.com/baesumin/react-native-layout-dnd/actions/workflows/ci.yml/badge.svg)](https://github.com/baesumin/react-native-layout-dnd/actions/workflows/ci.yml)
+
 Drag and drop for React Native grids and lists, built on Reanimated worklets and
 Gesture Handler.
 
@@ -8,8 +11,8 @@ list, placed by coordinates in a grid, or moved between the two, and every move
 arrives at your state layer as one complete candidate that you can accept or
 reject.
 
-> **Pre-release.** This package is not on npm yet, and its peer versions are
-> pinned to the exact combination it has been verified against. Read
+> **Alpha.** Only one combination of peer versions has been built and run, and
+> device verification is incomplete. Read
 > [Status and limitations](#status-and-limitations) before adopting it.
 
 ## Why this library
@@ -48,13 +51,8 @@ React is a peer too, at 19 or newer, but your React Native version already
 decides it. The New Architecture is required, because Reanimated 4 supports
 nothing else.
 
-Each lower bound is the release that introduced an API this package calls: the
-v3 gesture hooks in Gesture Handler 3.0.0, the worklets package split in
-Reanimated 4.0.0, and `scheduleOnUI`, `scheduleOnRN` and `runOnUISync` in
-Worklets 0.5.0. Only the **Verified** column has actually been built and run
-end to end, so treat the rest of the range as accepted rather than tested, and
-pin what works for you. Reanimated and Worklets constrain your React Native
-version further through their own peer ranges.
+Only the **Verified** column has been built and run end to end. The rest of
+each range is accepted but untested, so pin what works for you.
 
 Your app must also render the provider under `GestureHandlerRootView` and enable
 the Worklets Babel plugin. This package ships worklet directives uncompiled so
@@ -70,23 +68,18 @@ module.exports = {
 
 ## Installation
 
-Not published yet. Build a tarball from a clone and install it by path:
-
 ```sh
-git clone https://github.com/baesumin/react-native-layout-dnd.git
-cd react-native-layout-dnd
-yarn install
-npm pack
+yarn add react-native-layout-dnd
+# or: npm install react-native-layout-dnd
 ```
 
+Install the peers too if your app does not have them yet, then rebuild the
+native app:
+
 ```sh
-# in your app
-yarn add /absolute/path/to/react-native-layout-dnd-0.1.0-alpha.0.tgz
+yarn add react-native-gesture-handler react-native-reanimated react-native-worklets
 ```
 
-Installing straight from the Git URL does not work, because the entry points
-come from a build that only runs while packing.
-
 ## Quick start
 
 A sortable vertical list. `useDndState` holds the layout and acknowledges each
@@ -147,34 +140,80 @@ footprint, so `getGridItemLayout` decides the span an incoming item takes. Keep
 that function stable, because it is captured once per drag.
 
 ```tsx
-<DndProvider
-  value={value}
-  onChange={onChange}
-  getGridItemLayout={({ item }) => ({
-    span: item.data.span,
-    placement: 'insert',
-  })}
-  style={{ flex: 1 }}
->
-  <SortableList<Card> zoneId="library" virtualization ... />
-  <SortableGrid<Card>
-    zoneId="board"
-    style={{ height: 240 }}
-    geometry={{
-      mode: 'fit',
-      rowGap: 8,
-      columnGap: 8,
-      padding: { top: 8, right: 8, bottom: 8, left: 8 },
-    }}
-    renderItem={({ item, width, height }) => (
-      <View style={{ width, height }}>
-        <DragHandle>
-          <Text>{item.data.title}</Text>
-        </DragHandle>
-      </View>
-    )}
-  />
-</DndProvider>
+import { Text, View } from 'react-native';
+import {
+  DndProvider,
+  DragHandle,
+  SortableGrid,
+  SortableList,
+  useDndState,
+  type CellSpan,
+  type GridItemLayoutResolverArgs,
+  type LayoutState,
+} from 'react-native-layout-dnd';
+
+type Card = { title: string; span: CellSpan };
+
+const initial: LayoutState<Card> = {
+  revision: 0,
+  items: [
+    { id: 'notes', data: { title: 'Notes', span: { rows: 1, cols: 2 } } },
+  ],
+  zones: [
+    {
+      id: 'library',
+      kind: 'list',
+      orientation: 'vertical',
+      itemIds: ['notes'],
+    },
+    { id: 'board', kind: 'grid', rows: 3, columns: 4, placements: [] },
+  ],
+};
+
+function getGridItemLayout({ item }: GridItemLayoutResolverArgs<Card>) {
+  return { span: item.data.span, placement: 'insert' as const };
+}
+
+export function Board() {
+  const { value, onChange } = useDndState(initial);
+  return (
+    <DndProvider
+      value={value}
+      onChange={onChange}
+      getGridItemLayout={getGridItemLayout}
+      style={{ flex: 1 }}
+    >
+      <SortableList<Card>
+        zoneId="library"
+        virtualization
+        style={{ flex: 1 }}
+        estimatedItemSize={48}
+        renderItem={({ item }) => (
+          <DragHandle>
+            <Text>{item.data.title}</Text>
+          </DragHandle>
+        )}
+      />
+      <SortableGrid<Card>
+        zoneId="board"
+        style={{ height: 240 }}
+        geometry={{
+          mode: 'fit',
+          rowGap: 8,
+          columnGap: 8,
+          padding: { top: 8, right: 8, bottom: 8, left: 8 },
+        }}
+        renderItem={({ item, width, height }) => (
+          <View style={{ width, height }}>
+            <DragHandle>
+              <Text>{item.data.title}</Text>
+            </DragHandle>
+          </View>
+        )}
+      />
+    </DndProvider>
+  );
+}
 ```
 
 A grid zone with `rows`, `columns` and `placements` is spatial. Add `itemSpan`
@@ -212,6 +251,43 @@ const result = computeLayoutMove({
 if (result.status === 'ok' && result.changed) setValue(result.value);
 ```
 
+## Validation issues
+
+`DndProvider` and `GridController` report issues through two callbacks. In
+`DndProvider`, any issue also disables dragging until it is resolved.
+
+- `onValidationError(issues)` is called when new issues appear. It is never
+  called when they are resolved.
+- `onValidationChange(issues)` is called with the complete current list
+  whenever it changes, and with `[]` once everything is resolved. It runs after
+  the commit that changed the list has settled, so it does not see the
+  in-between states of one update.
+
+Use `onValidationChange` to show an error state that also clears itself:
+
+```tsx
+import { useState } from 'react';
+import type { LayoutValidationIssue } from 'react-native-layout-dnd';
+
+function useValidationState() {
+  const [issues, setIssues] = useState<LayoutValidationIssue[]>([]);
+  return { issues, onValidationChange: setIssues };
+}
+```
+
+What an issue means depends on where it comes from. Some codes come from more
+than one source, so read `zoneId`, `itemId` and `message` together with the code.
+
+| Source                   | Codes                                                                                                                                                                                                                                                                                                                                             | Resolved when                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| The value (data)         | `invalid-structure`, `duplicate-id` (item IDs), `invalid-dimension`, `invalid-span`, `invalid-placement`, `missing-item-span`, `span-mismatch`, `invalid-position`, `out-of-bounds`, `overlap`, `capacity-exceeded`, and for `LayoutState` also `invalid-revision`, `unknown-item`, `unplaced-item`, `duplicate-reference`, `invalid-orientation` | The app passes a corrected value                   |
+| Props and component tree | `invalid-budget`, `invalid-configuration` (provider, list or handle options, a handle outside its item, a zone component whose zone is not in the value), `invalid-geometry` for a malformed geometry object, `duplicate-id` for two components mounted for one zone                                                                              | The props or the mounted components change         |
+| Layout                   | `invalid-geometry` when a fixed geometry does not fit the laid-out zone                                                                                                                                                                                                                                                                           | The zone or the geometry changes so that cells fit |
+
+A layout issue follows the measured size of the zone. The grid checks a fixed
+geometry against the size of the same commit, so a geometry and a zone size that
+change together, as on rotation, are not reported.
+
 ## Documentation
 
 - [Lists and scrolling](docs/list-scroll-api.md) covers `DndProvider`,
@@ -220,30 +296,21 @@ if (result.status === 'ok' && result.changed) setValue(result.value);
 - [Grids and mixed layouts](docs/mixed-layout-api.md) covers `SortableGrid`,
   spans, transfers between zones, approval and failure reasons.
 - [Grid contracts and the `GridController` API](docs/api.md) covers the shared
-  layout contract, movement policies and preview rules, plus the grid-only API
-  kept for existing consumers, which is now an adapter over the same provider.
+  layout contract, movement policies and preview rules, plus `GridController`,
+  a grid-only interface over the same provider.
 - [Contributing](CONTRIBUTING.md) lists the checks and the native test
   checklist.
 
 Runnable examples live in [`example/`](example/), including a 580-item
-`FlatList` tab and a mixed grid and list screen:
-
-```sh
-yarn install
-yarn example start
-yarn example ios     # or: yarn example android
-```
+`FlatList` tab and a mixed grid and list screen. To run them, clone the
+repository and follow
+[Run the native example](CONTRIBUTING.md#run-the-native-example).
 
 ## Status and limitations
 
-Automated verification passes 51 suites and 1,215 tests, seven
-performance-tooling tests, TypeScript, ESLint, the build, and an isolated check
-of the packed API and its types.
-
 Known gaps, stated so you can judge the risk:
 
-- **Not published.** The package stays `private` until the release criteria are
-  met, and the public API may still change.
+- **Alpha.** The public API may still change before `0.1.0`.
 - **One verified combination.** The peer ranges above come from the APIs this
   package calls, not from a test matrix. Only the versions in the Verified
   column have been built and run, and Expo has not been tried.

package/lib/module/components/DndProvider.js

@@ -66,6 +66,7 @@ export function DndProvider({
   onDragEnd,
   onDragSettled,
   onValidationError,
+  onValidationChange,
   onDiagnostic,
   responseTimeoutMs,
   getGridItemLayout,
@@ -137,6 +138,39 @@ export function DndProvider({
       if (!deferred) reportSettled(event);
     }
   }, [reportSettled]);
+  // Issues of the value and options (from the coordinator) and of mounted
+  // adapters and handles (by owner), published together as one list. A new
+  // value reaches the adapters over several synchronous commits, so the list
+  // is read once they are done; intermediate lists are never published.
+  const issues = useRef(new Map());
+  const sessionIssues = useRef([]);
+  const validation = useRef({
+    published: '[]',
+    queued: false,
+    onChange: onValidationChange
+  }).current;
+  const mounted = useRef(true);
+  const publishValidation = useCallback(() => {
+    if (!mounted.current || validation.queued) return;
+    validation.queued = true;
+    globalThis.queueMicrotask(() => {
+      validation.queued = false;
+      if (!mounted.current) return;
+      const current = [...sessionIssues.current, ...Array.from(issues.current.keys()).sort().flatMap(owner => issues.current.get(owner).issues)];
+      const key = JSON.stringify(current);
+      if (key === validation.published) return;
+      validation.published = key;
+      try {
+        validation.onChange?.(current);
+      } catch (error) {
+        console.error('[LayoutDnD] Validation callback failed', error);
+      }
+    });
+  }, [validation]);
+  const reportSessionIssues = useCallback(next => {
+    sessionIssues.current = next;
+    publishValidation();
+  }, [publishValidation]);
   const [coordinator] = useState(() => new DndSessionCoordinator({
     value,
     onChange,
@@ -144,6 +178,7 @@ export function DndProvider({
     onDragStart,
     onDragEnd: endSession,
     onValidationError,
+    onValidationChange: reportSessionIssues,
     onDiagnostic,
     responseTimeoutMs,
     getGridItemLayout,
@@ -195,9 +230,7 @@ export function DndProvider({
   const nextHandleId = useRef(0);
   const [gestureRegistry] = useState(createDndGestureRegistry);
   const registry = useRef(new Map());
-  const issues = useRef(new Map());
   const observer = useRef(onValidationError);
-  const mounted = useRef(true);
   const handlePublication = useRef({
     queued: false,
     generation: 0,
@@ -354,10 +387,14 @@ export function DndProvider({
   }, [handlePublication, publishHandles]);
   const reportIssues = useCallback((owner, next) => {
     const key = JSON.stringify(next);
-    const old = issues.current.get(owner);
-    if (next.length) issues.current.set(owner, key);else issues.current.delete(owner);
+    const old = issues.current.get(owner)?.key;
+    if (next.length) issues.current.set(owner, {
+      key,
+      issues: next
+    });else issues.current.delete(owner);
     if (!mounted.current) return;
     setRegistryInvalid(issues.current.size > 0);
+    publishValidation();
     if (next.length && old !== key) {
       coordinator.cancel('disabled');
       try {
@@ -366,7 +403,7 @@ export function DndProvider({
         console.error('[LayoutDnD] Validation callback failed', error);
       }
     }
-  }, [coordinator]);
+  }, [coordinator, publishValidation]);
   useLayoutEffect(() => {
     mounted.current = true;
     if (currentCanDrop.current !== canDrop || committedValue.current !== value) policyRevision.current++;
@@ -381,6 +418,7 @@ export function DndProvider({
       });
     });
     observer.current = onValidationError;
+    validation.onChange = onValidationChange;
     if (currentConfig.current.dragAxis !== dragAxis || currentConfig.current.delayMs !== activation?.delayMs) coordinator.cancel('input-changed');
     currentConfig.current = {
       dragAxis,
@@ -398,6 +436,7 @@ export function DndProvider({
       onDragStart,
       onDragEnd: endSession,
       onValidationError,
+      onValidationChange: reportSessionIssues,
       onDiagnostic,
       responseTimeoutMs,
       getGridItemLayout,