feat: Base zone with event callbacks (#413)

## Description

This PR adds base zone implementation that detects whether the item
entered/left or was dropped over the zone.

This implementation will help build other zones, like delete zone or
drop zone and dragging between different sections.

Author: MatiPl01

example/app/src/examples/SortableGrid/features/MultiZoneExample.tsx

@@ -1,15 +1,19 @@
-import { useCallback } from 'react';
+import { useCallback, useRef, useState } from 'react';
+import { StyleSheet } from 'react-native';
 import type { SortableGridRenderItem } from 'react-native-sortables';
 import Sortable from 'react-native-sortables';
 
 import { GridCard, ScrollScreen, Section } from '@/components';
 import { spacing } from '@/theme';
 import { getItems } from '@/utils';
 
-const DATA = getItems(8);
+const DATA = getItems(12);
 const COLUMNS = 4;
 
 export default function MultiZoneExample() {
+  const [data, setData] = useState(DATA);
+  const activeItemKeyRef = useRef<null | string>(null);
+
   const renderItem = useCallback<SortableGridRenderItem<string>>(
     ({ item }) => <GridCard>{item}</GridCard>,
     []
@@ -22,24 +26,43 @@ export default function MultiZoneExample() {
           <Sortable.Grid
             columnGap={spacing.xs}
             columns={COLUMNS}
-            data={DATA}
+            data={data}
+            dimensionsAnimationType='worklet'
             renderItem={renderItem}
-            rowGap={spacing.xs}
+            rowGap={50}
             debug
+            onDragEnd={({ data: newData }) => setData(newData)}
+            onActiveItemDropped={() => {
+              activeItemKeyRef.current = null;
+            }}
+            onDragStart={({ key }) => {
+              activeItemKeyRef.current = key;
+            }}
           />
         </Section>
 
         <Section title='Section 2'>
-          <Sortable.Grid
-            columnGap={spacing.xs}
-            columns={COLUMNS}
-            data={DATA}
-            renderItem={renderItem}
-            rowGap={spacing.xs}
-            debug
+          <Sortable.BaseZone
+            style={styles.zone}
+            onItemDrop={() => {
+              console.log('Item dropped');
+              setData(data.filter(item => item !== activeItemKeyRef.current));
+            }}
+            onItemEnter={() => {
+              console.log('Item entered');
+            }}
+            onItemLeave={() => {
+              console.log('Item left');
+            }}
           />
         </Section>
       </Sortable.MultiZoneProvider>
     </ScrollScreen>
   );
 }
+
+const styles = StyleSheet.create({
+  zone: {
+    height: 100
+  }
+});

packages/react-native-sortables/src/components/index.ts

@@ -1,3 +1,4 @@
 export * from './shared';
 export { default as SortableFlex } from './SortableFlex';
 export { default as SortableGrid } from './SortableGrid';
+export * from './zones';

packages/react-native-sortables/src/components/shared/CustomHandle.tsx

@@ -5,8 +5,8 @@ import { runOnUI, useAnimatedRef } from 'react-native-reanimated';
 
 import {
   useCustomHandleContext,
-  useItemContext,
-  usePortalOutletContext
+  useIsInPortalOutlet,
+  useItemContext
 } from '../../providers';
 import { error } from '../../utils';
 
@@ -23,9 +23,8 @@ export type CustomHandleProps = PropsWithChildren<{
 
 export default function CustomHandle(props: CustomHandleProps) {
   // The item is teleported when it is rendered within the PortalOutlet
-  // component. Because PortalOutlet creates a context, we can use it to
-  // check if the item is teleported
-  const isTeleported = !!usePortalOutletContext();
+  // component
+  const isTeleported = useIsInPortalOutlet();
 
   // In case of teleported handle items, we want to render just the
   // handle component without any functionality

packages/react-native-sortables/src/components/shared/DraggableView/ActiveItemPortal.tsx

@@ -7,43 +7,56 @@ import {
 
 import { useMutableValue } from '../../../integrations/reanimated';
 import { usePortalContext } from '../../../providers';
+import type { CommonValuesContextType } from '../../../types';
 
 type ActiveItemPortalProps = PropsWithChildren<{
-  teleportedItemId: string;
+  itemKey: string;
   activationAnimationProgress: SharedValue<number>;
+  commonValuesContext: CommonValuesContextType;
   renderTeleportedItemCell: () => ReactNode;
 }>;
 
 export default function ActiveItemPortal({
   activationAnimationProgress,
   children,
-  renderTeleportedItemCell,
-  teleportedItemId
+  commonValuesContext,
+  itemKey,
+  renderTeleportedItemCell
 }: ActiveItemPortalProps) {
-  const { teleport } = usePortalContext()!;
+  const { containerId } = commonValuesContext;
+  const { measurePortalOutlet, teleport } = usePortalContext() ?? {};
+
   const teleportEnabled = useMutableValue(false);
 
+  const teleportedItemId = `${containerId}-${itemKey}`;
+
   useEffect(() => {
     if (teleportEnabled.value) {
-      teleport(teleportedItemId, renderTeleportedItemCell());
+      teleport?.(teleportedItemId, renderTeleportedItemCell());
     }
     // This is fine, we want to update the teleported item cell only when
     // the children change
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [children]);
 
   const enableTeleport = () => {
-    teleport(teleportedItemId, renderTeleportedItemCell());
+    teleport?.(teleportedItemId, renderTeleportedItemCell());
   };
 
   const disableTeleport = () => {
-    runOnJS(teleport)(teleportedItemId, null);
+    if (teleport) {
+      runOnJS(teleport)(teleportedItemId, null);
+    }
   };
 
   useAnimatedReaction(
     () => activationAnimationProgress.value,
     (progress, prevProgress) => {
       if (prevProgress && progress > prevProgress && !teleportEnabled.value) {
+        // We have to ensure that the portal outlet ref is measured before the
+        // teleported item is rendered within it because portal outlet position
+        // must be known to calculate the teleported item position
+        measurePortalOutlet?.();
         teleportEnabled.value = true;
         runOnJS(enableTeleport)();
       } else if (progress === 0 && teleportEnabled.value) {

packages/react-native-sortables/src/components/shared/DraggableView/DraggableView.tsx

@@ -16,6 +16,7 @@ import {
   CommonValuesContext,
   ItemContextProvider,
   useCommonValuesContext,
+  useDragContext,
   useItemPanGesture,
   useItemStyles,
   useMeasurementsContext,
@@ -45,26 +46,31 @@ function DraggableView({
   const commonValuesContext = useCommonValuesContext();
   const { handleItemMeasurement, removeItemMeasurements } =
     useMeasurementsContext();
+  const { handleDragEnd } = useDragContext();
   const { activeItemKey, containerId, customHandle } = commonValuesContext;
 
-  const teleportedItemId = `${containerId}-${key}`;
-
   const [isTeleported, setIsTeleported] = useState(false);
   const activationAnimationProgress = useMutableValue(0);
   const isActive = useDerivedValue(() => activeItemKey.value === key);
   const itemStyles = useItemStyles(key, isActive, activationAnimationProgress);
   const gesture = useItemPanGesture(key, activationAnimationProgress);
 
   useEffect(
-    () => runOnUI(removeItemMeasurements)(key),
-    [key, removeItemMeasurements]
+    () =>
+      runOnUI(() => {
+        handleDragEnd(key, activationAnimationProgress);
+        removeItemMeasurements(key);
+      }),
+    [activationAnimationProgress, handleDragEnd, key, removeItemMeasurements]
   );
 
   useEffect(() => {
     if (!portalContext) {
       setIsTeleported(false);
+      return;
     }
 
+    const teleportedItemId = `${containerId}-${key}`;
     const unsubscribe = portalContext?.subscribe?.(
       teleportedItemId,
       setIsTeleported
@@ -74,7 +80,7 @@ function DraggableView({
       portalContext?.teleport?.(teleportedItemId, null);
       unsubscribe?.();
     };
-  }, [portalContext, teleportedItemId]);
+  }, [portalContext, containerId, key]);
 
   const onMeasure = (width: number, height: number) =>
     handleItemMeasurement(key, { height, width });
@@ -145,8 +151,9 @@ function DraggableView({
       {renderItemCell(isTeleported)}
       <ActiveItemPortal
         activationAnimationProgress={activationAnimationProgress}
-        renderTeleportedItemCell={renderTeleportedItemCell}
-        teleportedItemId={teleportedItemId}>
+        commonValuesContext={commonValuesContext}
+        itemKey={key}
+        renderTeleportedItemCell={renderTeleportedItemCell}>
         {children}
       </ActiveItemPortal>
     </Fragment>

packages/react-native-sortables/src/components/shared/SortableContainer.tsx

@@ -14,10 +14,8 @@ import Animated, {
 import { EMPTY_OBJECT, IS_WEB } from '../../constants';
 import { DebugOutlet } from '../../debug';
 import {
-  MultiZoneOutlet,
   useCommonValuesContext,
-  useMeasurementsContext,
-  useMultiZoneContext
+  useMeasurementsContext
 } from '../../providers';
 import type {
   DimensionsAnimation,
@@ -60,7 +58,6 @@ export default function SortableContainer({
     usesAbsoluteLayout
   } = useCommonValuesContext();
   const { handleHelperContainerMeasurement } = useMeasurementsContext();
-  const multiZoneContext = useMultiZoneContext();
 
   const animateWorklet = dimensionsAnimationType === 'worklet';
   const animateLayout = dimensionsAnimationType === 'layout';
@@ -143,7 +140,6 @@ export default function SortableContainer({
         ref={innerContainerRef}
         style={[style, innerContainerStyle]}>
         {children}
-        {multiZoneContext && <MultiZoneOutlet />}
       </Animated.View>
       {debug && <DebugOutlet />}
       {/* Renders an overlay view helpful for debugging */}

packages/react-native-sortables/src/components/zones/BaseZone.tsx

@@ -0,0 +1,33 @@
+import { View, type ViewProps } from 'react-native';
+import { useAnimatedRef } from 'react-native-reanimated';
+
+import { useStableCallbackValue } from '../../integrations/reanimated';
+import type { ZoneHandlers } from '../../providers';
+import { useZoneHandlers } from '../../providers';
+
+export type BaseZoneProps = ViewProps &
+  ZoneHandlers & {
+    minActivationDistance?: number;
+  };
+
+export default function BaseZone({
+  minActivationDistance = 0,
+  onItemDrop,
+  onItemEnter,
+  onItemLeave,
+  ...rest
+}: BaseZoneProps) {
+  const containerRef = useAnimatedRef<View>();
+
+  const stableOnItemEnter = useStableCallbackValue(onItemEnter);
+  const stableOnItemLeave = useStableCallbackValue(onItemLeave);
+  const stableOnItemDrop = useStableCallbackValue(onItemDrop);
+
+  useZoneHandlers(containerRef, minActivationDistance, {
+    onItemDrop: stableOnItemDrop,
+    onItemEnter: stableOnItemEnter,
+    onItemLeave: stableOnItemLeave
+  });
+
+  return <View ref={containerRef} {...rest} />;
+}

packages/react-native-sortables/src/components/zones/index.ts

@@ -0,0 +1 @@
+export { default as BaseZone } from './BaseZone';

packages/react-native-sortables/src/index.ts

@@ -1,4 +1,5 @@
 import {
+  BaseZone,
   CustomHandle,
   SortableFlex,
   SortableGrid,
@@ -7,7 +8,7 @@ import {
 } from './components';
 export { useItemContext } from './providers';
 
-import { MultiZoneProvider, PortalProvider } from './providers';
+import { MultiZoneProvider, PortalProvider, useZoneContext } from './providers';
 export type { CustomHandleProps, SortableLayerProps } from './components';
 export * from './constants/layoutAnimations';
 export type {
@@ -39,8 +40,13 @@ export type {
 } from './types';
 export { DragActivationState } from './types';
 
+const zones = {
+  BaseZone
+};
+
 /** Collection of sortable components and utilities for React Native */
 const Sortable = {
+  ...zones,
   /** Flexible container component that allows reordering of child elements through drag and drop.
    * Uses flexbox layout for arranging items, making it ideal for dynamic layouts
    * where items need to flow naturally based on available space.
@@ -170,7 +176,6 @@ const Sortable = {
 
   // TODO - add doc string
   MultiZoneProvider,
-
   /** Optional provider that renders dragged items above all other components that are
    * wrapped within the PortalProvider.
    *
@@ -227,4 +232,6 @@ const Sortable = {
   Touchable: SortableTouchable
 };
 
+export { useZoneContext };
+
 export default Sortable;

packages/react-native-sortables/src/providers/SharedProvider.tsx

@@ -19,13 +19,13 @@ import type {
   SortableCallbacks
 } from '../types';
 import {
-  ActiveItemValuesProvider,
   AutoScrollProvider,
   CommonValuesProvider,
   CustomHandleProvider,
   DragProvider,
   LayerProvider,
-  MeasurementsProvider
+  MeasurementsProvider,
+  useMultiZoneContext
 } from './shared';
 import { ContextProviderComposer } from './utils';
 
@@ -67,6 +67,8 @@ export default function SharedProvider({
   scrollableRef,
   ...rest
 }: SharedProviderProps) {
+  const inMultiZone = !!useMultiZoneContext();
+
   if (__DEV__) {
     useWarnOnPropChange('debug', debug);
     useWarnOnPropChange('customHandle', customHandle);
@@ -75,11 +77,9 @@ export default function SharedProvider({
 
   const providers = [
     // Provider used for proper zIndex management
-    <LayerProvider />,
+    !inMultiZone && <LayerProvider />,
     // Provider used for layout debugging (can be used only in dev mode)
     __DEV__ && debug && <DebugProvider />,
-    // Provider used for active item values
-    <ActiveItemValuesProvider />,
     // Provider used for shared values between all providers below
     <CommonValuesProvider
       customHandle={customHandle}