feat: Reverse items stacking order (#535)

## Description

This PR adds a possibility to reverse items stacking order (render items
with lower index below items with higher index).

## Changes showcase


https://github.com/user-attachments/assets/0be26017-7188-4c06-a36b-f2cc15b932a7


<details>
<summary>Example source code</summary>

```tsx
import { useCallback } from 'react';
import { StyleSheet, Text, View } from 'react-native';
import type { SortableGridRenderItem } from 'react-native-sortables';
import Sortable from 'react-native-sortables';

import { ScrollScreen } from '@/components';
import { colors, radius, sizes, spacing, text } from '@/theme';

const DATA = Array.from({ length: 5 }, (_, index) => `Item ${index + 1}`);

export default function PlaygroundExample() {
  const renderItem = useCallback<SortableGridRenderItem<string>>(
    ({ item }) => (
      <View style={styles.card}>
        <Text style={styles.text}>{item}</Text>
        <View
          style={{
            backgroundColor: 'red',
            height: 40,
            position: 'absolute',
            right: -20,
            top: -20,
            width: 40
          }}
        />
      </View>
    ),
    []
  );

  return (
    <ScrollScreen contentContainerStyle={styles.container} includeNavBarHeight>
      <Sortable.Grid
        columnGap={10}
        columns={3}
        data={DATA}
        renderItem={renderItem}
        rowGap={10}
        stackingOrder='desc'
      />
    </ScrollScreen>
  );
}

const styles = StyleSheet.create({
  card: {
    alignItems: 'center',
    backgroundColor: '#36877F',
    borderRadius: radius.md,
    height: sizes.xl,
    justifyContent: 'center'
  },
  container: {
    padding: spacing.md
  },
  text: {
    ...text.label2,
    color: colors.white
  }
});
```

</details>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: MatiPl01

packages/react-native-sortables/src/constants/props.ts

@@ -62,7 +62,8 @@ export const DEFAULT_SHARED_PROPS = {
   showDropIndicator: false,
   snapOffsetX: '50%',
   snapOffsetY: '50%',
-  sortEnabled: true
+  sortEnabled: true,
+  stackingOrder: 'asc'
 } satisfies DefaultSharedProps;
 
 export const DEFAULT_SORTABLE_GRID_PROPS = {

packages/react-native-sortables/src/providers/shared/CommonValuesProvider.ts

@@ -17,6 +17,7 @@ import type {
   ItemDragSettings,
   ItemSizes,
   ItemsLayoutTransitionMode,
+  ItemsStackingOrder,
   Vector
 } from '../../types';
 import { DragActivationState } from '../../types';
@@ -35,6 +36,7 @@ type CommonValuesProviderProps = PropsWithChildren<
       controlledContainerDimensions: ControlledDimensions;
       controlledItemDimensions: ControlledDimensions;
       itemsLayoutTransitionMode: ItemsLayoutTransitionMode;
+      stackingOrder: ItemsStackingOrder;
     }
 >;
 
@@ -59,7 +61,8 @@ const { CommonValuesContext, CommonValuesProvider, useCommonValuesContext } =
     itemsLayoutTransitionMode,
     snapOffsetX: _snapOffsetX,
     snapOffsetY: _snapOffsetY,
-    sortEnabled: _sortEnabled
+    sortEnabled: _sortEnabled,
+    stackingOrder
   }) => {
     const { getKeys, subscribeKeys } = useItemsContext();
 
@@ -165,6 +168,7 @@ const { CommonValuesContext, CommonValuesProvider, useCommonValuesContext } =
         inactiveItemOpacity,
         inactiveItemScale,
         indexToKey,
+        isStackingOrderDesc: stackingOrder === 'desc',
         itemHeights,
         itemPositions,
         itemsLayoutTransitionMode,

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

@@ -40,6 +40,7 @@ export type SharedProviderProps = PropsWithChildren<
         | 'itemsLayoutTransitionMode'
         | 'measureDebounceDelay'
         | 'sortEnabled'
+        | 'stackingOrder'
       >
     > &
     Required<SortableCallbacks> & {

packages/react-native-sortables/src/providers/shared/hooks/useItemZIndex.ts

@@ -7,8 +7,13 @@ export default function useItemZIndex(
   key: string,
   activationAnimationProgress: SharedValue<number>
 ): SharedValue<number> {
-  const { activeItemKey, indexToKey, keyToIndex, prevActiveItemKey } =
-    useCommonValuesContext();
+  const {
+    activeItemKey,
+    indexToKey,
+    isStackingOrderDesc,
+    keyToIndex,
+    prevActiveItemKey
+  } = useCommonValuesContext();
 
   return useDerivedValue<number>(() => {
     const itemCount = indexToKey.value.length;
@@ -17,7 +22,10 @@ export default function useItemZIndex(
       return 2 * itemCount + 1;
     }
 
-    const orderZIndex = keyToIndex.value[key] ?? 0;
+    const realIndex = keyToIndex.value[key] ?? 0;
+    const orderZIndex = isStackingOrderDesc
+      ? itemCount - realIndex - 1
+      : realIndex;
 
     if (activationAnimationProgress.value > 0) {
       if (prevActiveItemKey.value === key) {

packages/react-native-sortables/src/types/props/shared.ts

@@ -59,6 +59,8 @@ export type Offset = `${number}%` | number;
 export type OverDrag = 'both' | 'horizontal' | 'none' | 'vertical';
 /** Position of the reordering trigger point */
 export type ReorderTriggerOrigin = 'center' | 'touch';
+/** Strategy for setting zIndex of items */
+export type ItemsStackingOrder = 'asc' | 'desc';
 
 export type ItemDragSettings = AnimatableProps<{
   /** Delay in ms before drag gesture is activated */
@@ -337,6 +339,13 @@ export type SharedProps = Simplify<
            * @default true
            */
           bringToFrontWhenActive: boolean;
+          /**
+           * Strategy for setting zIndex of items
+           * - 'asc' - items with higher index have higher zIndex (default)
+           * - 'desc' - items with higher index have lower zIndex
+           * @default 'asc'
+           */
+          stackingOrder: ItemsStackingOrder;
         }
     >
 >;

packages/react-native-sortables/src/types/providers/shared.ts

@@ -96,6 +96,7 @@ export type CommonValuesContextType =
       shouldAnimateLayout: SharedValue<boolean>; // is set to false on web when the browser window is resized
       animateLayoutOnReorderOnly: SharedValue<boolean>;
       customHandle: boolean;
+      isStackingOrderDesc: boolean;
     };
 
 // MEASUREMENTS