docs: Active item portal provider (#366)

## Description

Add active item portal provider example and `PortalProvider`
documentation pages.

Author: MatiPl01

packages/docs/docs/customization/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Customization",
-  "position": 6,
+  "position": 8,
   "link": {
     "type": "generated-index"
   }

packages/docs/docs/grid/examples/active-item-portal.mdx

@@ -0,0 +1,109 @@
+---
+sidebar_position: 8
+description: ''
+---
+
+# Active Item Portal
+
+## Description
+
+This example demonstrates how to use the active item portal to render the active item on top of other components.
+
+In this case, the `PortalProvider` is used to render the active item outside of the `ScrollView` content bounds. This is the only way to render only the active item without cropping it whilst keeping the rest of the grid within the `ScrollView` content bounds.
+
+## Source Code
+
+```tsx
+import { useCallback, useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import Animated, { useAnimatedRef } from 'react-native-reanimated';
+import type { SortableGridRenderItem } from 'react-native-sortables';
+import Sortable from 'react-native-sortables';
+
+const DATA = Array.from({ length: 18 }, (_, index) => `Item ${index + 1}`);
+
+export default function Example() {
+  const [portalEnabled, setPortalEnabled] = useState(false);
+  const scrollableRef = useAnimatedRef<Animated.ScrollView>();
+
+  const renderItem = useCallback<SortableGridRenderItem<string>>(
+    ({ item }) => (
+      <View style={styles.card}>
+        <Text style={styles.text}>{item}</Text>
+      </View>
+    ),
+    []
+  );
+
+  return (
+    <View style={styles.container}>
+      {/* highlight-start */}
+      <Sortable.PortalProvider enabled={portalEnabled}>
+        {/* highlight-end */}
+        <View style={styles.gridContainer}>
+          <Animated.ScrollView
+            contentContainerStyle={styles.contentContainer}
+            ref={scrollableRef}>
+            <Sortable.Grid
+              columnGap={10}
+              columns={3}
+              data={DATA}
+              renderItem={renderItem}
+              rowGap={10}
+              scrollableRef={scrollableRef}
+            />
+          </Animated.ScrollView>
+        </View>
+        <Pressable onPress={() => setPortalEnabled(prev => !prev)}>
+          <Text
+            style={
+              styles.buttonText
+            }>{`${portalEnabled ? 'Disable' : 'Enable'} Portal`}</Text>
+        </Pressable>
+        {/* highlight-start */}
+      </Sortable.PortalProvider>
+      {/* highlight-end */}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    backgroundColor: '#DDE2E3'
+  },
+  gridContainer: {
+    margin: 15,
+    borderRadius: 10,
+    height: 400,
+    backgroundColor: '#FFFFFF'
+  },
+  card: {
+    alignItems: 'center',
+    backgroundColor: '#36877F',
+    borderRadius: 10,
+    height: 100,
+    justifyContent: 'center'
+  },
+  contentContainer: {
+    padding: 10
+  },
+  text: {
+    color: 'white',
+    fontWeight: 'bold'
+  },
+  buttonText: {
+    color: '#36877F',
+    fontSize: 18,
+    fontWeight: 'bold'
+  }
+});
+```
+
+## Result
+
+import video from '@site/static/video/grid-active-item-portal.mp4';
+
+<video autoPlay loop muted width='300px' src={video} />

packages/docs/docs/helper-components/handle.mdx

@@ -45,17 +45,17 @@ Determines the reordering behavior of the item.
 - `'non-draggable'` - the item **cannot be dragged** but **moves** when other items are reordered.
 - `'fixed'` - the item **cannot be dragged** and **does not move** when other items are reordered.
 
-:::info Complete Usage Examples
-
-- Complete usage example: [Custom Handle](/grid/examples/custom-handle)
-- Grid with fixed items: [Fixed Items](/grid/examples/fixed-items)
-
-:::
-
 ### children
 
 The handle component (can be anything, e.g. an icon, image, etc.).
 
 | type        | default | required |
 | ----------- | ------- | -------- |
 | `ReactNode` | NO      | NO       |
+
+:::info
+
+- Complete usage example: [Custom Handle](/grid/examples/custom-handle)
+- Grid with fixed items: [Fixed Items](/grid/examples/fixed-items)
+
+:::

packages/docs/docs/providers/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Feature Providers",
+  "position": 7,
+  "link": {
+    "type": "generated-index"
+  }
+}

packages/docs/docs/providers/portal-provider.mdx

@@ -0,0 +1,98 @@
+---
+sidebar_position: 1
+description: 'Allows rendering the active item on top of other components'
+---
+
+# Portal Provider
+
+## Overview
+
+The **Portal Provider** component allows you to render the active item on top of other components.
+
+It is useful if your sortable component is **deeply nested within other components** and you want to render the active item on top of all of them or if you want to render the active item **outside of the `ScrollView` content bounds**.
+
+## Usage
+
+Just wrap your sortable component (and any other components you want the active item to render above) with the `Sortable.PortalProvider` component.
+
+```tsx
+import Sortable from 'react-native-sortables';
+
+// ... other components
+<Sortable.PortalProvider>
+  {/* other components and the nested sortable component */}
+</Sortable.PortalProvider>;
+// ... other components
+```
+
+## Example
+
+import video from '@site/static/video/portal-provider.mp4';
+
+<video autoPlay loop muted width='300px' src={video} />
+
+## Props
+
+### enabled
+
+Determines whether the portal functionality is enabled.
+
+| type      | default | required |
+| --------- | ------- | -------- |
+| `boolean` | `true`  | NO       |
+
+When enabled, the active item will be rendered in a portal outlet, which is rendered on top of other components rendered within the `PortalProvider` component.
+
+### children
+
+The components above which the active item should be rendered.
+
+| type        | default | required |
+| ----------- | ------- | -------- |
+| `ReactNode` | NO      | YES      |
+
+## How It Works?
+
+The Portal Provider creates a separate portal outlet component higher in the view hierarchy. When an item becomes active, it is teleported to this outlet, allowing it to be rendered on top of other components. The provider synchronizes the position of the teleported item with the original item and manages the visibility of the original item while it is being dragged.
+
+This approach ensures a smooth transition between the item rendered within the sortable component and the one rendered in the portal.
+
+## Remarks
+
+### Active Item Copy
+
+The portal renders the active item on a different layer, within a different parent component than the item is normally rendered in. As a result, the copy of the active item is mounted (not re-rendered) while the old component within the sortable container is still rendered but invisible.
+
+This means there are 2 instances of the active item component rendered at the same time until it is dropped.
+
+### Component State
+
+Since the teleported component is a separate instance from the original one, any local state (like `useState` or fetched data) will not be shared between the two instances.
+
+For components that need to maintain state during dragging, consider using:
+
+- Context providers to share state
+- External store or state management library
+- Lifting state up to a parent component (but it may lead to performance issues if not implemented correctly)
+
+### Layout Animations
+
+Since the view is mounted and unmounted within the portal outlet, all entering and exiting animations used in this view triggered on render will be triggered here as well.
+
+### Paper (Old Architecture) Only
+
+When using the Portal Provider with in the React Native Old Architecture, you may encounter a shadow-related warning saying that the shadow calculation is inefficient. To resolve this, either set `activeItemShadowOpacity={0}` to remove the shadow or ignore the warning as the shadow only affects a single (active) view.
+
+:::warning
+
+The Portal Provider uses complex synchronization logic to synchronize Reanimated style updates with React renders. While this approach works well in most cases, it may have some limitations.
+
+If you encounter unexpected behavior or any kind of issues, please report them on [GitHub](https://github.com/matipl01/react-native-sortables/issues) with a detailed description of the problem.
+
+:::
+
+:::info
+
+For the complete usage example of the Portal Provider, check out the [Active Item Portal](/grid/examples/active-item-portal) example.
+
+:::

packages/docs/src/css/custom.css

@@ -36,11 +36,12 @@ button {
   --ifm-color-primary-lighter: #359962;
   --ifm-color-primary-lightest: #3cad6e;
   --ifm-code-font-size: 95%;
-  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
   --ifm-details-color-background: #edf7f3;
   --ifm-details-color-border: #33925d40;
   --ifm-details-color-text: var(--ifm-color-emphasis-900);
   --ifm-details-color-icon: var(--ifm-color-emphasis-900);
+  --ifm-tabs-color-active: var(--ifm-color-emphasis-900);
+  --docusaurus-highlighted-code-line-bg: #c6e1d6;
 }
 
 /* For readability concerns, you should choose a lighter palette in dark mode. */
@@ -57,6 +58,7 @@ button {
   --ifm-details-color-border: #25c2a040;
   --ifm-details-color-text: #ffffff;
   --ifm-details-color-icon: #25c2a0;
+  --docusaurus-highlighted-code-line-bg: #25c2a020;
 }
 
 hr {