feat: Fixed items support for Sortable.Grid (#310)

## Description

This PR adds support for fixed items for the `Sortable.Grid` component.

Thanks @tpaksu for a proposed solution in #305

## Example recordings

- Example 1 - without data change
- Example 2 - with data change (added/removed/inserted items)

| Example 1 | Example 2 |
|-|-|
| <video
src="https://github.com/user-attachments/assets/8b0999d1-5a2d-4684-96cc-8162b4e233c3"
/> | <video
src="https://github.com/user-attachments/assets/5ac8f434-3766-4962-8279-a4e69e066f10"
/> |

<details>
 <summary>Example 1 code snippet</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: 12 }, (_, index) => `Item ${index + 1}`);

export default function PlaygroundExample() {
  const renderItem = useCallback<SortableGridRenderItem<string>>(
    ({ item, index }) => {
      const fixed =
        index === 0 || index === 4 || index === 9 || index === DATA.length - 1;
      return (
        <Sortable.Handle mode={fixed ? 'fixed' : 'draggable'}>
          <View
            style={[
              styles.card,
              {
                backgroundColor: fixed ? colors.secondary : colors.primary
              }
            ]}>
            <Text style={styles.text}>{item}</Text>
          </View>
        </Sortable.Handle>
      );
    },
    []
  );

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

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

<details>
 <summary>Example 2 code snippet</summary>

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

import {
  Button,
  GridCard,
  Group,
  Screen,
  Section,
  Stagger
} from '@/components';
import { IS_WEB } from '@/constants';
import { colors, flex, spacing, text } from '@/theme';
import { getItems } from '@/utils';

const AVAILABLE_DATA = getItems(18);
const COLUMNS = 4;

const FIXED_KEYS = new Set(['Item 1', 'Item 2', 'Item 3', 'Item 4']);

export default function DataChangeExample() {
  const scrollableRef = useAnimatedRef<Animated.ScrollView>();
  const [data, setData] = useState(AVAILABLE_DATA.slice(0, 12));

  const getNewItemName = useCallback((currentData: Array<string>) => {
    if (currentData.length >= AVAILABLE_DATA.length) {
      return null;
    }
    for (const item of AVAILABLE_DATA) {
      if (!currentData.includes(item)) {
        return item;
      }
    }
    return null;
  }, []);

  const prependItem = useCallback(() => {
    setData(prevData => {
      const newItem = getNewItemName(prevData);
      if (newItem) {
        return [newItem, ...prevData];
      }
      return prevData;
    });
  }, [getNewItemName]);

  const insertItem = useCallback(() => {
    setData(prevData => {
      const newItem = getNewItemName(prevData);
      if (newItem) {
        const index = Math.floor(Math.random() * (prevData.length - 1));
        return [...prevData.slice(0, index), newItem, ...prevData.slice(index)];
      }
      return prevData;
    });
  }, [getNewItemName]);

  const appendItem = useCallback(() => {
    setData(prevData => {
      const newItem = getNewItemName(prevData);
      if (newItem) {
        return [...prevData, newItem];
      }
      return prevData;
    });
  }, [getNewItemName]);

  const shuffleItems = useCallback(() => {
    setData(prevData => {
      const shuffledData = [...prevData];
      for (let i = shuffledData.length - 1; i > 0; i--) {
        const j = Math.floor(Math.random() * (i + 1));
        [shuffledData[i], shuffledData[j]] = [
          shuffledData[j]!,
          shuffledData[i]!
        ];
      }
      return shuffledData;
    });
  }, []);

  const sortItems = useCallback(() => {
    setData(prevData =>
      [...prevData].sort((a, b) => +a.split(' ')[1]! - +b.split(' ')[1]!)
    );
  }, []);

  const onRemoveItem = useCallback((item: string) => {
    setData(prevData => prevData.filter(i => i !== item));
  }, []);

  const renderItem = useCallback<SortableGridRenderItem<string>>(
    ({ item }) => (
      <Sortable.Handle mode={FIXED_KEYS.has(item) ? 'fixed' : 'draggable'}>
        <GridItem
          item={item}
          onRemoveItem={onRemoveItem}
          fixed={FIXED_KEYS.has(item)}
        />
      </Sortable.Handle>
    ),
    [onRemoveItem]
  );

  const additionDisabled = data.length >= AVAILABLE_DATA.length;
  const reorderDisabled = data.length < 2;

  const menuSections = [
    {
      buttons: [
        { disabled: additionDisabled, onPress: prependItem, title: 'Prepend' },
        { disabled: additionDisabled, onPress: insertItem, title: 'Insert' },
        { disabled: additionDisabled, onPress: appendItem, title: 'Append' }
      ],
      description: 'Prepend/Insert/Append items to the list',
      title: 'Modify number of items'
    },
    {
      buttons: [
        { disabled: reorderDisabled, onPress: shuffleItems, title: 'Shuffle' },
        { disabled: reorderDisabled, onPress: sortItems, title: 'Sort' }
      ],
      description: 'Reorder items in the list',
      title: 'Change order of items'
    }
  ];

  return (
    <Screen includeNavBarHeight>
      {/* Need to set flex: 1 for the ScrollView parent component in order
      // to ensure that it occupies the entire available space */}
      <Stagger
        wrapperStye={index =>
          index === 2 ? (IS_WEB ? flex.shrink : flex.fill) : {}
        }>
        {menuSections.map(({ buttons, description, title }) => (
          <Section description={description} key={title} title={title}>
            <View style={styles.row}>
              {buttons.map(btnProps => (
                <Button {...btnProps} key={btnProps.title} />
              ))}
            </View>
          </Section>
        ))}

        <Group padding='none' style={[flex.fill, styles.scrollViewGroup]}>
          <Animated.ScrollView
            contentContainerStyle={styles.scrollViewContent}
            ref={scrollableRef}
            // @ts-expect-error - overflowY is needed for proper behavior on web
            style={[flex.fill, IS_WEB && { overflowY: 'scroll' }]}>
            <Group withMargin={false} bordered center>
              <Text style={styles.title}>Above SortableGrid</Text>
            </Group>

            <Sortable.Grid
              columnGap={spacing.sm}
              columns={COLUMNS}
              data={data}
              renderItem={renderItem}
              rowGap={spacing.xs}
              scrollableRef={scrollableRef}
              animateHeight
              customHandle
              hapticsEnabled
              onDragEnd={({ data: newData }) => setData(newData)}
            />

            <Group withMargin={false} bordered center>
              <Text style={styles.title}>Below SortableGrid</Text>
            </Group>
          </Animated.ScrollView>
        </Group>
      </Stagger>
    </Screen>
  );
}

type GridItemProps = {
  item: string;
  fixed: boolean;
  onRemoveItem: (item: string) => void;
};

// It is recommended to use memo for items to prevent re-renders of the entire grid
// on item order changes (renderItem takes and index argument, thus it must be called
// after every order change)
const GridItem = memo(function GridItem({
  item,
  onRemoveItem,
  fixed
}: GridItemProps) {
  return (
    <Sortable.Pressable onPress={onRemoveItem.bind(null, item)}>
      <GridCard style={fixed && { backgroundColor: '#999' }}>{item}</GridCard>
    </Sortable.Pressable>
  );
});

const styles = StyleSheet.create({
  row: {
    columnGap: spacing.sm,
    flexDirection: 'row',
    flexWrap: 'wrap',
    rowGap: spacing.xs
  },
  scrollViewContent: {
    gap: spacing.sm,
    padding: spacing.sm
  },
  scrollViewGroup: {
    overflow: 'hidden',
    paddingHorizontal: spacing.none,
    paddingVertical: spacing.none
  },
  title: {
    ...text.subHeading2,
    color: colors.foreground3
  }
});
```
</details>

Author: MatiPl01

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

@@ -45,7 +45,8 @@ function DraggableView({
 }: DraggableViewProps) {
   const hasPortal = !!usePortalContext();
   const commonValuesContext = useCommonValuesContext();
-  const { handleItemMeasurement, handleItemRemoval } = useMeasurementsContext();
+  const { handleItemMeasurement, removeItemMeasurements } =
+    useMeasurementsContext();
   const { activeItemKey, customHandle, itemsOverridesStyle } =
     commonValuesContext;
 
@@ -59,8 +60,8 @@ function DraggableView({
   );
 
   useEffect(() => {
-    return () => handleItemRemoval(key);
-  }, [key, handleItemRemoval]);
+    return () => removeItemMeasurements(key);
+  }, [key, removeItemMeasurements]);
 
   const sharedCellProps = {
     decorationStyle,

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

@@ -1,4 +1,4 @@
-import { type PropsWithChildren, useCallback, useMemo } from 'react';
+import { type PropsWithChildren, useCallback, useEffect, useMemo } from 'react';
 import { View } from 'react-native';
 import { GestureDetector } from 'react-native-gesture-handler';
 import {
@@ -18,10 +18,13 @@ import { error } from '../../utils';
 
 /** Props for the Sortable Handle component */
 export type SortableHandleProps = PropsWithChildren<{
-  /** When true, the handle will not activate drag gesture
-   * @default false
+  /** Controls how the item behaves in the sortable component
+   * - 'draggable': Item can be dragged and moves with reordering (default)
+   * - 'non-draggable': Item cannot be dragged but moves with reordering
+   * - 'fixed': Item stays in place and cannot be dragged
+   * @default 'draggable'
    */
-  disabled?: boolean;
+  mode?: 'draggable' | 'fixed' | 'non-draggable';
 }>;
 
 export function SortableHandle(props: SortableHandleProps) {
@@ -41,7 +44,7 @@ export function SortableHandle(props: SortableHandleProps) {
 
 function SortableHandleComponent({
   children,
-  disabled = false
+  mode = 'draggable'
 }: SortableHandleProps) {
   const { activeItemKey, activeItemPosition, containerRef } =
     useCommonValuesContext();
@@ -54,7 +57,13 @@ function SortableHandleComponent({
     );
   }
 
-  const { handleDimensions, handleOffset } = customHandleContext;
+  const {
+    activeHandleDimensions,
+    activeHandleOffset,
+    makeItemFixed,
+    removeFixedItem
+  } = customHandleContext;
+  const dragEnabled = mode === 'draggable';
 
   const viewRef = useAnimatedRef<View>();
   const gesture = useItemPanGesture(
@@ -63,6 +72,14 @@ function SortableHandleComponent({
     viewRef
   );
 
+  useEffect(() => {
+    if (mode === 'fixed') {
+      makeItemFixed(itemKey);
+    }
+
+    return () => removeFixedItem(itemKey);
+  }, [mode, itemKey, makeItemFixed, removeFixedItem]);
+
   const measureHandle = useCallback(() => {
     'worklet';
     if (activeItemKey.value !== itemKey) {
@@ -85,8 +102,8 @@ function SortableHandleComponent({
       containerMeasurements;
     const { x: activeX, y: activeY } = activeItemPosition.value;
 
-    handleDimensions.value = { height, width };
-    handleOffset.value = {
+    activeHandleDimensions.value = { height, width };
+    activeHandleOffset.value = {
       x: pageX - containerPageX - activeX,
       y: pageY - containerPageY - activeY
     };
@@ -95,22 +112,22 @@ function SortableHandleComponent({
     activeItemPosition,
     containerRef,
     itemKey,
-    handleDimensions,
-    handleOffset,
+    activeHandleDimensions,
+    activeHandleOffset,
     viewRef
   ]);
 
   // Measure the handle when the active item key changes
   useAnimatedReaction(() => activeItemKey.value, measureHandle);
 
   const adjustedGesture = useMemo(
-    () => gesture.enabled(!disabled),
-    [disabled, gesture]
+    () => gesture.enabled(dragEnabled),
+    [dragEnabled, gesture]
   );
 
   return (
     <GestureDetector gesture={adjustedGesture} userSelect='none'>
-      <View ref={viewRef} onLayout={disabled ? undefined : measureHandle}>
+      <View ref={viewRef} onLayout={dragEnabled ? measureHandle : undefined}>
         {children}
       </View>
     </GestureDetector>

packages/react-native-sortables/src/providers/layout/flex/updates/insert/index.ts

@@ -11,7 +11,7 @@ import type {
   FlexLayout,
   SortableFlexStrategyFactory
 } from '../../../../../types';
-import { reorderInsert } from '../../../../../utils';
+import { gt as gt_, lt as lt_, reorderInsert } from '../../../../../utils';
 import {
   getAdditionalSwapOffset,
   useDebugBoundingBox
@@ -39,14 +39,8 @@ const useInsertStrategy: SortableFlexStrategyFactory = ({
   const isColumn = flexDirection.startsWith('column');
   const isReverse = flexDirection.endsWith('reverse');
 
-  const gt = (a: number, b: number) => {
-    'worklet';
-    return isReverse ? a < b : a > b;
-  };
-  const lt = (a: number, b: number) => {
-    'worklet';
-    return isReverse ? a > b : a < b;
-  };
+  const gt = isReverse ? lt_ : gt_;
+  const lt = isReverse ? gt_ : lt_;
 
   let mainCoordinate: Coordinate;
   let crossCoordinate: Coordinate;
@@ -273,7 +267,8 @@ const useInsertStrategy: SortableFlexStrategyFactory = ({
       if (activeIndex === lastItemIndex) {
         return null;
       }
-      return reorderInsert(indexToKey.value, activeIndex, lastItemIndex);
+      // TODO - add fixed items support in flex
+      return reorderInsert(indexToKey.value, activeIndex, lastItemIndex, {});
     }
     const mainAxisPosition = position[mainCoordinate];
 
@@ -463,7 +458,13 @@ const useInsertStrategy: SortableFlexStrategyFactory = ({
 
     if (newActiveIndex === activeIndex) return;
 
-    return reorderInsert(indexToKey.value, activeIndex, newActiveIndex);
+    return reorderInsert(
+      indexToKey.value,
+      activeIndex,
+      newActiveIndex,
+      {}
+      // TODO - add fixed items support in flex
+    );
   };
 };
 

packages/react-native-sortables/src/providers/layout/flex/updates/insert/utils.ts

@@ -232,7 +232,8 @@ export const getSwappedToGroupBeforeIndices = (
     indexToKey: reorderInsert(
       props.indexToKey,
       props.activeItemIndex,
-      indexes.itemIndex
+      indexes.itemIndex,
+      {} // TODO - add fixed items support in flex
     )
   };
 };
@@ -249,7 +250,8 @@ export const getSwappedToGroupAfterIndices = (
     indexToKey: reorderInsert(
       props.indexToKey,
       props.activeItemIndex,
-      indexes.itemIndex
+      indexes.itemIndex,
+      {} // TODO - add fixed items support in flex
     )
   };
 };

packages/react-native-sortables/src/providers/layout/grid/updates/common.ts

@@ -3,6 +3,7 @@ import type { SharedValue } from 'react-native-reanimated';
 import type {
   Coordinate,
   Dimension,
+  ReorderFunction,
   SortableGridStrategyFactory
 } from '../../../../types';
 import { getAdditionalSwapOffset, useDebugBoundingBox } from '../../../shared';
@@ -11,16 +12,13 @@ import { getCrossIndex, getMainIndex } from '../utils';
 export const createGridStrategy =
   (
     useInactiveIndexToKey: () => SharedValue<Array<string>>,
-    reorder: (
-      indexToKey: Array<string>,
-      activeIndex: number,
-      newIndex: number
-    ) => Array<string>
+    reorder: ReorderFunction
   ): SortableGridStrategyFactory =>
   ({
     containerHeight,
     containerWidth,
     crossGap,
+    fixedItemKeys,
     indexToKey,
     isVertical,
     mainGap,
@@ -236,7 +234,8 @@ export const createGridStrategy =
       }
 
       // Swap the active item with the item at the new index
-      const itemsCount = indexToKey.value.length;
+      const idxToKey = indexToKey.value;
+      const itemsCount = idxToKey.length;
       const limitedCrossIndex = Math.max(
         0,
         Math.min(crossIndex, Math.floor((itemsCount - 1) / numGroups))
@@ -245,11 +244,14 @@ export const createGridStrategy =
         0,
         Math.min(limitedCrossIndex * numGroups + mainIndex, itemsCount - 1)
       );
-      if (newIndex === activeIndex) {
+      if (
+        newIndex === activeIndex ||
+        fixedItemKeys?.value[idxToKey[newIndex]!]
+      ) {
         return;
       }
 
       // return the new order of items
-      return reorder(indexToKey.value, activeIndex, newIndex);
+      return reorder(idxToKey, activeIndex, newIndex, fixedItemKeys?.value);
     };
   };

packages/react-native-sortables/src/providers/layout/grid/updates/insert.ts

@@ -2,7 +2,10 @@ import { useAnimatedReaction, useSharedValue } from 'react-native-reanimated';
 
 import { EMPTY_ARRAY } from '../../../../constants';
 import { areArraysDifferent, reorderInsert } from '../../../../utils';
-import { useCommonValuesContext } from '../../../shared';
+import {
+  useCommonValuesContext,
+  useCustomHandleContext
+} from '../../../shared';
 import { createGridStrategy } from './common';
 
 /**
@@ -20,21 +23,43 @@ import { createGridStrategy } from './common';
  */
 function useInactiveIndexToKey() {
   const { activeItemKey, indexToKey } = useCommonValuesContext();
+  const { fixedItemKeys } = useCustomHandleContext() ?? {};
   const result = useSharedValue<Array<string>>(EMPTY_ARRAY);
 
   useAnimatedReaction(
     () => ({
-      excluded: activeItemKey.value,
+      excludedKey: activeItemKey.value,
+      fixedKeys: fixedItemKeys?.value,
       idxToKey: indexToKey.value
     }),
-    ({ excluded, idxToKey }) => {
-      if (excluded === null) {
+    ({ excludedKey, fixedKeys, idxToKey }) => {
+      if (excludedKey === null) {
         result.value = EMPTY_ARRAY;
-      } else {
-        const othersArray = idxToKey.filter(key => key !== excluded);
-        if (areArraysDifferent(othersArray, result.value)) {
-          result.value = othersArray;
+        return;
+      }
+
+      let othersArray: Array<string>;
+
+      if (fixedKeys) {
+        othersArray = [...idxToKey];
+        let emptyIndex = idxToKey.indexOf(excludedKey);
+
+        for (let i = emptyIndex + 1; i < idxToKey.length; i++) {
+          const itemKey = idxToKey[i]!;
+          if (!fixedKeys[itemKey]) {
+            othersArray[emptyIndex] = itemKey;
+            emptyIndex = i;
+          }
         }
+
+        // Remove the last empty slot and move all remaining items to the left
+        othersArray.splice(emptyIndex, 1);
+      } else {
+        othersArray = idxToKey.filter(key => key !== excludedKey);
+      }
+
+      if (areArraysDifferent(result.value, othersArray)) {
+        result.value = othersArray;
       }
     }
   );

packages/react-native-sortables/src/providers/layout/grid/updates/swap.ts

@@ -30,41 +30,40 @@ function useInactiveIndexToKey() {
 
   useAnimatedReaction(
     () => ({
-      activeKey: activeItemKey.value,
+      excludedKey: activeItemKey.value,
       idxToKey: indexToKey.value,
       keyToIdx: keyToIndex.value
     }),
-    ({ activeKey, idxToKey, keyToIdx }) => {
-      const activeIndex = activeKey && keyToIdx[activeKey];
-
-      if (activeKey === null || activeIndex === undefined) {
+    ({ excludedKey, idxToKey, keyToIdx }) => {
+      const excludedIndex = excludedKey ? keyToIdx[excludedKey] : undefined;
+      if (excludedIndex === undefined) {
         result.value = EMPTY_ARRAY;
-      } else {
-        const othersArray = [...idxToKey];
-        const activeIdx = activeIndex as number;
+        return;
+      }
 
-        for (
-          let i = activeIdx;
-          i + numGroups < othersArray.length;
-          i += numGroups
-        ) {
-          othersArray[i] = othersArray[i + numGroups]!;
-        }
+      const othersArray = [...idxToKey];
 
-        const activeColumnIndex = getMainIndex(activeIdx, numGroups);
-        const lastRowIndex = Math.floor((othersArray.length - 1) / numGroups);
-        for (
-          let i = lastRowIndex * numGroups + activeColumnIndex;
-          i < othersArray.length;
-          i++
-        ) {
-          othersArray[i] = othersArray[i + 1]!;
-        }
-        othersArray.pop();
+      for (
+        let i = excludedIndex;
+        i + numGroups < othersArray.length;
+        i += numGroups
+      ) {
+        othersArray[i] = othersArray[i + numGroups]!;
+      }
+
+      const activeColumnIndex = getMainIndex(excludedIndex, numGroups);
+      const lastRowIndex = Math.floor((othersArray.length - 1) / numGroups);
+      for (
+        let i = lastRowIndex * numGroups + activeColumnIndex;
+        i < othersArray.length;
+        i++
+      ) {
+        othersArray[i] = othersArray[i + 1]!;
+      }
+      othersArray.pop();
 
-        if (areArraysDifferent(othersArray, result.value)) {
-          result.value = othersArray;
-        }
+      if (areArraysDifferent(othersArray, result.value)) {
+        result.value = othersArray;
       }
     }
   );