docs: Add Sortable Flex examples (#559)

## Summary

Adds a **Flex examples** section to the docs, mirroring the existing
Grid examples. Previously `flex/examples.mdx` just pointed users to the
Grid examples; it is now a `flex/examples/` folder (analogous to
`grid/examples/`) with interactive examples:

- Auto Scroll
- Drop Indicator (default, custom style, custom component)
- Item snap
- Different Item Sizes
- Touchable
- Custom Handle
- Fixed Items
- Active Item Portal
- Custom Shadow

Each example is implemented with `Sortable.Flex` (the children-based
API) using wrapping pill items. The drop-indicator examples use
theme-aware colours (visible in light and dark mode) and the
custom-handle example disables pointer events on the handle icon —
consistent with the equivalent Grid examples.

There are no result videos yet (the Grid examples have them); the
interactive demos serve as the result.

## Testing

- `yarn build` (Docusaurus production build) passes.
- `prettier --check`, `eslint`, and `tsc` pass on all new files.
- Verified every example renders in the local docs in light and dark
mode: pills wrap correctly; handles, delete buttons, fixed (grayed)
items, the snap switch and the scroll container all render; and the
custom-shadow items receive the animated box-shadow.

Author: MatiPl01

packages/docs/docs/flex/examples.mdx

@@ -0,0 +1,9 @@
+{
+  "label": "Examples",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "title": "Flex Examples",
+    "slug": "/flex/examples"
+  }
+}

packages/docs/docs/flex/examples/_category_.json

@@ -0,0 +1,24 @@
+---
+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 flex container within the `ScrollView` content bounds.
+
+## Example
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexActiveItemPortalExample from '@site/src/examples/FlexActiveItemPortal';
+import FlexActiveItemPortalCode from '!!raw-loader!@site/src/examples/FlexActiveItemPortal';
+
+<InteractiveExample
+  component={FlexActiveItemPortalExample}
+  code={FlexActiveItemPortalCode}
+  metastring='{33,53}'
+/>

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

@@ -0,0 +1,21 @@
+---
+sidebar_position: 1
+description: ''
+---
+
+# Auto Scroll
+
+## Description
+
+This example demonstrates how to use the **auto scroll** feature of the **Sortable Flex** component. Pass a `scrollableRef` pointing to the scrollable container and it will scroll automatically while you drag an item near its edges.
+
+## Example
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexAutoScrollExample from '@site/src/examples/FlexAutoScroll';
+import FlexAutoScrollCode from '!!raw-loader!@site/src/examples/FlexAutoScroll';
+
+<InteractiveExample
+  component={FlexAutoScrollExample}
+  code={FlexAutoScrollCode}
+/>

packages/docs/docs/flex/examples/auto-scroll.mdx

@@ -0,0 +1,21 @@
+---
+sidebar_position: 6
+description: ''
+---
+
+# Custom Handle
+
+## Description
+
+The **Custom Handle** example demonstrates how to use a custom item drag handle in the **Sortable Flex** component.
+
+## Example
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexCustomHandleExample from '@site/src/examples/FlexCustomHandle';
+import FlexCustomHandleCode from '!!raw-loader!@site/src/examples/FlexCustomHandle';
+
+<InteractiveExample
+  component={FlexCustomHandleExample}
+  code={FlexCustomHandleCode}
+/>

packages/docs/docs/flex/examples/custom-handle.mdx

@@ -0,0 +1,23 @@
+---
+sidebar_position: 9
+description: ''
+---
+
+# Custom Shadow
+
+## Description
+
+This example demonstrates how to create a **custom shadow** for the active item during drag. By disabling the default shadow with `activeItemShadowOpacity={0}` and using the [useItemContext](/hooks/useItemContext) hook, you can animate the `box-shadow` property of the item based on the activation animation progress.
+
+This is particularly useful when you want to add shadows on **Android**, where shadows are not supported by default and must be implemented by the user.
+
+## Example
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexCustomShadowExample from '@site/src/examples/FlexCustomShadow';
+import FlexCustomShadowCode from '!!raw-loader!@site/src/examples/FlexCustomShadow';
+
+<InteractiveExample
+  component={FlexCustomShadowExample}
+  code={FlexCustomShadowCode}
+/>

packages/docs/docs/flex/examples/custom-shadow.mdx

@@ -0,0 +1,21 @@
+---
+sidebar_position: 4
+description: ''
+---
+
+# Different Item Sizes
+
+## Description
+
+This example shows that the **Sortable Flex** component can handle **items of different sizes** without any issues. Items flow and wrap naturally based on their content.
+
+## Example
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexDifferentSizesExample from '@site/src/examples/FlexDifferentSizes';
+import FlexDifferentSizesCode from '!!raw-loader!@site/src/examples/FlexDifferentSizes';
+
+<InteractiveExample
+  component={FlexDifferentSizesExample}
+  code={FlexDifferentSizesCode}
+/>

packages/docs/docs/flex/examples/different-item-sizes.mdx

@@ -0,0 +1,41 @@
+---
+sidebar_position: 2
+description: ''
+---
+
+# Drop Indicator
+
+## Description
+
+The drop indicator is a **visual indicator** that shows the **position where the item will be dropped** when the user releases the item.
+
+## Default
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexDropIndicatorDefaultExample from '@site/src/examples/FlexDropIndicatorDefault';
+import FlexDropIndicatorDefaultCode from '!!raw-loader!@site/src/examples/FlexDropIndicatorDefault';
+
+<InteractiveExample
+  component={FlexDropIndicatorDefaultExample}
+  code={FlexDropIndicatorDefaultCode}
+/>
+
+## Custom Style
+
+import FlexDropIndicatorCustomStyleExample from '@site/src/examples/FlexDropIndicatorCustomStyle';
+import FlexDropIndicatorCustomStyleCode from '!!raw-loader!@site/src/examples/FlexDropIndicatorCustomStyle';
+
+<InteractiveExample
+  component={FlexDropIndicatorCustomStyleExample}
+  code={FlexDropIndicatorCustomStyleCode}
+/>
+
+## Custom Component
+
+import FlexDropIndicatorCustomComponentExample from '@site/src/examples/FlexDropIndicatorCustomComponent';
+import FlexDropIndicatorCustomComponentCode from '!!raw-loader!@site/src/examples/FlexDropIndicatorCustomComponent';
+
+<InteractiveExample
+  component={FlexDropIndicatorCustomComponentExample}
+  code={FlexDropIndicatorCustomComponentCode}
+/>

packages/docs/docs/flex/examples/drop-indicator.mdx

@@ -0,0 +1,23 @@
+---
+sidebar_position: 7
+description: ''
+---
+
+# Fixed Items
+
+## Description
+
+The fixed items example demonstrates how to create a **Sortable Flex** with items which have a **fixed position**.
+
+In the example below, the **first**, the **last** and an **item in the middle** are fixed (grayed out) and stay in the same ordinal position.
+
+## Example
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexFixedItemsExample from '@site/src/examples/FlexFixedItems';
+import FlexFixedItemsCode from '!!raw-loader!@site/src/examples/FlexFixedItems';
+
+<InteractiveExample
+  component={FlexFixedItemsExample}
+  code={FlexFixedItemsCode}
+/>

packages/docs/docs/flex/examples/fixed-items.mdx

@@ -0,0 +1,18 @@
+---
+sidebar_position: 3
+description: ''
+---
+
+# Item snap
+
+## Description
+
+The item snap is a **transformation of the item** that happens when the user **presses the item** (before the drag starts). It **transforms** the item **in relation to the touch position**.
+
+## Example
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+import FlexItemSnapExample from '@site/src/examples/FlexItemSnap';
+import FlexItemSnapCode from '!!raw-loader!@site/src/examples/FlexItemSnap';
+
+<InteractiveExample component={FlexItemSnapExample} code={FlexItemSnapCode} />