From c2d0afe06909aaba871c55c89abcea7c25ae749a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20=C5=81opaci=C5=84ski?= Date: Fri, 18 Apr 2025 00:31:40 +0200 Subject: [PATCH 1/3] Add handle component docs --- packages/docs/docs/grid/examples/handle.mdx | 1 + .../docs/docs/helper-components/handle.mdx | 54 +++++++++++++++++++ .../docs/docs/helper-components/layer.mdx | 26 ++++----- .../docs/helper-components/touchables.mdx | 48 +++++------------ 4 files changed, 80 insertions(+), 49 deletions(-) create mode 100644 packages/docs/docs/grid/examples/handle.mdx create mode 100644 packages/docs/docs/helper-components/handle.mdx diff --git a/packages/docs/docs/grid/examples/handle.mdx b/packages/docs/docs/grid/examples/handle.mdx new file mode 100644 index 00000000..46409041 --- /dev/null +++ b/packages/docs/docs/grid/examples/handle.mdx @@ -0,0 +1 @@ +# TODO diff --git a/packages/docs/docs/helper-components/handle.mdx b/packages/docs/docs/helper-components/handle.mdx new file mode 100644 index 00000000..efcd8c18 --- /dev/null +++ b/packages/docs/docs/helper-components/handle.mdx @@ -0,0 +1,54 @@ +--- +sidebar_position: 1 +description: 'Component that allows to drag an item by a specific area' +--- + +# Handle + +## Overview + +The **Handle** component allows you to drag an item by a specific area (part of the item) instead of the whole item. + +## Usage + +:::info + +For the complete usage example, refer to the [Handle](/grid/examples/handle) example. + +::: + +Use this component within a sortable component's child (item) component. + +```tsx +import Sortable from 'react-native-sortables'; + +// ... other components + + {/* ... other components */} + + {/* ... other components */} +; +// ... other components +``` + +## Props + +### mode + +Determines the reordering behavior of the item. + +| type | default | required | +| ------------------------------------------- | ------------- | -------- | +| `'draggable' \| 'fixed' \| 'non-draggable'` | `'draggable'` | NO | + +- `'draggable'` - the item **can be dragged** and **moves** when other items are reordered. +- `'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. + +### children + +The handle component (can be anything, e.g. an icon, image, etc.). + +| type | default | required | +| ----------- | ------- | -------- | +| `ReactNode` | NO | NO | diff --git a/packages/docs/docs/helper-components/layer.mdx b/packages/docs/docs/helper-components/layer.mdx index 5fc31750..53dd286c 100644 --- a/packages/docs/docs/helper-components/layer.mdx +++ b/packages/docs/docs/helper-components/layer.mdx @@ -1,6 +1,6 @@ --- -sidebar_position: 1 -description: '' +sidebar_position: 3 +description: 'Component managing zIndex when an item is being dragged' --- # Layer @@ -31,19 +31,15 @@ The **Sortable Layer** component should be used only when necessary, i.e. if you ```tsx import Sortable from 'react-native-sortables'; -function MyComponent() { - return ( - // ... other components - - {/* ... other components */} - - {/* ... other components */} - - // ... other components - ); -} +// ... other components + + {/* ... other components */} + + {/* ... other components */} +; +// ... other components ``` ## Props diff --git a/packages/docs/docs/helper-components/touchables.mdx b/packages/docs/docs/helper-components/touchables.mdx index 5ffdb99b..0d3a93a4 100644 --- a/packages/docs/docs/helper-components/touchables.mdx +++ b/packages/docs/docs/helper-components/touchables.mdx @@ -1,6 +1,6 @@ --- sidebar_position: 2 -description: '' +description: 'Components that work well with sortable component gesture detectors' --- # Touchables @@ -24,45 +24,25 @@ Use these components when you need to add **interactive elements** (buttons, lin ## Usage -Use these components withing a sortable component's child (item) component. +:::info -```tsx -import Sortable from 'react-native-sortables'; +For the complete usage example, refer to the [Touchables](/grid/examples/touchables) example. -function Item({ item }: { item: string }) { - return ( - // ... other components - { - console.log('pressed'); - }}> - {/* ... other components */} - - // ... other components - ); -} -``` +::: -And, for example, if you use the **Sortable Grid** component: +Use these components withing a sortable component's child (item) component. ```tsx -import { useCallback } from 'react'; import Sortable from 'react-native-sortables'; -import type { SortableGridRenderItem } from 'react-native-sortables'; - -export default function Grid() { - const renderItem = useCallback>( - ({ item }) => , - [] - ); - - return ( - - ); -} + +// ... other components + { + console.log('pressed'); + }}> + {/* ... other components */} +; +// ... other components ``` ## Props From f13358aa358dd58edf5a101cd8a3ccffdbf19a83 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20=C5=81opaci=C5=84ski?= Date: Fri, 18 Apr 2025 00:56:20 +0200 Subject: [PATCH 2/3] Finish handle example --- packages/docs/docs/grid/examples/handle.mdx | 82 +++++++++++++++++- .../docs/docs/helper-components/handle.mdx | 6 ++ .../docs/static/video/grid-custom-handle.mp4 | Bin 0 -> 852972 bytes 3 files changed, 87 insertions(+), 1 deletion(-) create mode 100644 packages/docs/static/video/grid-custom-handle.mp4 diff --git a/packages/docs/docs/grid/examples/handle.mdx b/packages/docs/docs/grid/examples/handle.mdx index 46409041..f04d492a 100644 --- a/packages/docs/docs/grid/examples/handle.mdx +++ b/packages/docs/docs/grid/examples/handle.mdx @@ -1 +1,81 @@ -# TODO +--- +sidebar_position: 6 +description: '' +--- + +# Custom Handle + +## Description + +The **Custom Handle** example demonstrates how to use a custom item drag handle. + +## Usage + +### Source Code + +```tsx +import { faGripVertical } from '@fortawesome/free-solid-svg-icons'; +import { FontAwesomeIcon } from '@fortawesome/react-native-fontawesome'; +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'; + +const DATA = Array.from({ length: 8 }, (_, index) => `Item ${index + 1}`); + +export default function PlaygroundExample() { + const renderItem = useCallback>( + ({ item }) => ( + + {item} + {/* Wraps the handle component (an icon in this case) */} + + + + + ), + [] + ); + + return ( + + + + ); +} + +const styles = StyleSheet.create({ + card: { + alignItems: 'center', + backgroundColor: '#36877F', + borderRadius: 12, + flexDirection: 'row', + justifyContent: 'center', + padding: 24 + }, + container: { + padding: 16 + }, + text: { + color: 'white', + flex: 1, + fontWeight: 'bold' + } +}); +``` + +## Result + +import handleVideo from '@site/static/video/grid-custom-handle.mp4'; + +