From 52228af92e06ff8aec439027f1a4670f305936f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20=C5=81opaci=C5=84ski?= Date: Thu, 17 Apr 2025 22:03:56 +0200 Subject: [PATCH 1/2] Add documentation of some missing props and proper docs for new callbacks support --- packages/docs/docs/flex/props.mdx | 102 +++++++++++++++++++++-------- packages/docs/docs/grid/props.mdx | 105 ++++++++++++++++++++++-------- 2 files changed, 152 insertions(+), 55 deletions(-) diff --git a/packages/docs/docs/flex/props.mdx b/packages/docs/docs/flex/props.mdx index a655bd49..13a66e35 100644 --- a/packages/docs/docs/flex/props.mdx +++ b/packages/docs/docs/flex/props.mdx @@ -11,7 +11,7 @@ Whenever `Animatable` is used, it refers to the following type definition: type Animatable = SharedValue | T; ``` -This means that properties of type `Animatable` can accept either: +This means that properties of type `Animatable` can accept either of the following: - a Reanimated **Shared Value** (`SharedValue`) - a **static value** of type `T` @@ -268,7 +268,7 @@ This may sometimes cause **performance issues** as it requires layout recalculat --- -## Item Drag Settings +## Item Drag ### overDrag @@ -325,6 +325,42 @@ The maximum distance (in pixels) the finger can move from the touch start positi --- +## Reordering + +### strategy + +Controls how items **are reordered** while the **active item** is being **dragged around**. + +| type | default | required | +| ---------------------- | -------- | -------- | +| `SortableFlexStrategy` | 'insert' | NO | + +- `'insert'` - items are reordered by inserting the active item at the target position and moving all items between the active item and the target position + +
+ Type definitions + +```tsx +type SortableFlexStrategy = 'insert' | SortableFlexStrategyFactory; +``` + +{/* TODO: Add link to docs page explaining how to use SortableFlexStrategyFactory */} + +
+ +### reorderTriggerOrigin + +Determines position of the reordering trigger point. If that point enters the area of a different item than the current one, the reordering will be triggered. + +| type | default | required | +| --------------------- | ---------- | -------- | +| `'center' \| 'touch'` | `'center'` | NO | + +- `'center'` - reordering will be triggered when the center of the active item enters the area of a different item +- `'touch'` - reordering will be triggered when the touch point enters the area of a different item + +--- + ## Active Item Decoration All active item decoration settings are applied when the **item becomes active** (when drag gesture starts being handled). @@ -553,13 +589,9 @@ type DropIndicatorComponentProps = { Layout animations control how items animate when their positions change and when they are added or removed from the flex container. -:::note - - Item **entering** animations are **not** triggered during the **initial render** of the flex container - Item **exiting** animations are **not** triggered when the **entire flex container is unmounted** -::: - :::warning Warning (Web) There are some **differences** in the **layout animations** implementation on **Web**: @@ -676,6 +708,41 @@ import reorderVideo from '@site/static/video/flex-layout-transition-mode-reorder ## Callbacks +:::tip Performance Recommendation +Use **worklet functions** for callbacks to run directly on the UI thread and avoid thread jumping overhead. +::: + +All callbacks accept two types of functions: + +1. **Worklet Functions** (Recommended) + + - To mark a function as worklet, you have to add `'worklet'` directive at the start of the function body + - Run directly on the UI thread + - More performant + - Example: + + ```ts + const onDragStart = useCallback((params: DragStartParams) => { + 'worklet'; + // Your code here + }, []); + ``` + +2. **Plain JS Functions** + - No special directive needed + - Runs on the JS thread by using `runOnJS` + - Less performant due to jumping between threads + - Example: + ```ts + const onDragStart = useCallback((params: DragStartParams) => { + // Your code here + }, []); + ``` + +:::info +For more information about worklets refer to the [Reanimated documentation](https://docs.swmansion.com/react-native-reanimated/docs/guides/worklets/). +::: + ### onDragStart Called when the drag gesture starts. @@ -782,27 +849,6 @@ type DragMoveParams = { ## Other Settings -### strategy - -Controls how items **are reordered** while the **active item** is being **dragged around**. - -| type | default | required | -| ---------------------- | -------- | -------- | -| `SortableFlexStrategy` | 'insert' | NO | - -
- Type definitions - -```tsx -type SortableFlexStrategy = 'insert' | SortableFlexStrategyFactory; -``` - -{/* TODO: Add link to docs page explaining how to use SortableFlexStrategyFactory */} - -
- ---- - ### customHandle Controls whether drag gestures should be restricted to a custom handle component. @@ -841,6 +887,8 @@ You can also use any other haptics library but you will have to trigger haptics Enables debug mode, which shows additional views helpful for debugging. This property is intended for the library **developers** and is not recommended for the library **users**. +Debug mode has no effect in production builds and can be used to debug the library only in the development environment. + | type | default | required | | --------- | ------- | -------- | | `boolean` | false | NO | diff --git a/packages/docs/docs/grid/props.mdx b/packages/docs/docs/grid/props.mdx index 47b52da5..d7dc245b 100644 --- a/packages/docs/docs/grid/props.mdx +++ b/packages/docs/docs/grid/props.mdx @@ -11,7 +11,7 @@ Whenever `Animatable` is used, it refers to the following type definition: type Animatable = SharedValue | T; ``` -This means that properties of type `Animatable` can accept either: +This means that properties of type `Animatable` can accept either of the following: - a Reanimated **Shared Value** (`SharedValue`) - a **static value** of type `T` @@ -135,7 +135,7 @@ This may sometimes cause **performance issues** as it requires layout recalculat --- -## Item Drag Settings +## Item Drag ### overDrag @@ -192,6 +192,43 @@ The maximum distance (in pixels) the finger can move from the touch start positi --- +## Reordering + +### strategy + +Controls how items **are reordered** while the **active item** is being **dragged around**. + +| type | default | required | +| ---------------------- | -------- | -------- | +| `SortableGridStrategy` | 'insert' | NO | + +- `'insert'` - items are reordered by inserting the active item at the target position and moving all items between the active item and the target position +- `'swap'` - items are reordered by swapping the active item with the target item without moving other items + +
+ Type definitions + +```tsx +type SortableGridStrategy = 'insert' | 'swap' | SortableGridStrategyFactory; +``` + +{/* TODO: Add link to docs page explaining how to use SortableGridStrategyFactory */} + +
+ +### reorderTriggerOrigin + +Determines position of the reordering trigger point. If that point enters the area of a different item than the current one, the reordering will be triggered. + +| type | default | required | +| --------------------- | ---------- | -------- | +| `'center' \| 'touch'` | `'center'` | NO | + +- `'center'` - reordering will be triggered when the center of the active item enters the area of a different item +- `'touch'` - reordering will be triggered when the touch point enters the area of a different item + +--- + ## Active Item Decoration All active item decoration settings are applied when the **item becomes active** (when drag gesture starts being handled). @@ -436,13 +473,9 @@ type DropIndicatorComponentProps = { Layout animations control how items animate when their positions change and when they are added or removed from the grid. -:::note - - Item **entering** animations are **not** triggered during the **initial render** of the grid - Item **exiting** animations are **not** triggered when the **entire grid is unmounted** -::: - :::warning Warning (Web) There are some **differences** in the **layout animations** implementation on **Web**: @@ -557,6 +590,41 @@ import reorderVideo from '@site/static/video/grid-layout-transition-mode-reorder ## Callbacks +:::tip Performance Recommendation +Use **worklet functions** for callbacks to run directly on the UI thread and avoid thread jumping overhead. +::: + +All callbacks accept two types of functions: + +1. **Worklet Functions** (Recommended) + + - To mark a function as worklet, you have to add `'worklet'` directive at the start of the function body + - Run directly on the UI thread + - More performant + - Example: + + ```ts + const onDragStart = useCallback((params: DragStartParams) => { + 'worklet'; + // Your code here + }, []); + ``` + +2. **Plain JS Functions** + - No special directive needed + - Runs on the JS thread by using `runOnJS` + - Less performant due to jumping between threads + - Example: + ```ts + const onDragStart = useCallback((params: DragStartParams) => { + // Your code here + }, []); + ``` + +:::info +For more information about worklets refer to the [Reanimated documentation](https://docs.swmansion.com/react-native-reanimated/docs/guides/worklets/). +::: + ### onDragStart Called when the drag gesture starts. @@ -583,7 +651,7 @@ type DragStartParams = { ### onDragEnd -Called when the drag gesture ends. Data passed to the callback is the new order of the items. +Called when the drag gesture ends. Data passed to the callback is sorted according to the new order of the items. If the order of items is not changed, the same data array as the one passed to the `data` prop of the grid is passed in the callback params. | type | default | required | | -------------------------------- | ------- | -------- | @@ -665,27 +733,6 @@ type DragMoveParams = { ## Other Settings -### strategy - -Controls how items **are reordered** while the **active item** is being **dragged around**. - -| type | default | required | -| ---------------------- | -------- | -------- | -| `SortableGridStrategy` | 'insert' | NO | - -
- Type definitions - -```tsx -type SortableGridStrategy = 'insert' | 'swap' | SortableGridStrategyFactory; -``` - -{/* TODO: Add link to docs page explaining how to use SortableGridStrategyFactory */} - -
- ---- - ### customHandle Controls whether drag gestures should be restricted to a custom handle component. @@ -726,6 +773,8 @@ You can also use any other haptics library but you will have to trigger haptics Enables debug mode, which shows additional views helpful for debugging. This property is intended for the library **developers** and is not recommended for the library **users**. +Debug mode has no effect in production builds and can be used to debug the library only in the development environment. + | type | default | required | | --------- | ------- | -------- | | `boolean` | false | NO | From a770b29414109c0ec7e979b2935b76e244e0280f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mateusz=20=C5=81opaci=C5=84ski?= Date: Thu, 17 Apr 2025 23:43:36 +0200 Subject: [PATCH 2/2] Some progress --- packages/docs/docs/flex/props.mdx | 26 +++++++++++++++++-- packages/docs/docs/grid/props.mdx | 26 +++++++++++++++++-- .../src/types/props/shared.ts | 4 +-- 3 files changed, 50 insertions(+), 6 deletions(-) diff --git a/packages/docs/docs/flex/props.mdx b/packages/docs/docs/flex/props.mdx index 13a66e35..7fa5bdb3 100644 --- a/packages/docs/docs/flex/props.mdx +++ b/packages/docs/docs/flex/props.mdx @@ -572,11 +572,17 @@ Component to use as the drop indicator. It gives a **full control** over the dro ```tsx type DropIndicatorComponentProps = { - activationProgress: SharedValue; - touchedItemKey: SharedValue; + /** Progress of the active item animation (from 0 to 1) */ + activeAnimationProgress: SharedValue; + /** Key of the currently dragged item, or null if no item is being dragged */ + activeItemKey: SharedValue; + /** Current index where the dragged item would be dropped */ dropIndex: SharedValue; + /** Current position where the item would be dropped */ dropPosition: SharedValue; + /** Array of item keys in their current order */ orderedItemKeys: SharedValue>; + /** Style to be applied to the drop indicator */ style: ViewStyle; }; ``` @@ -820,6 +826,12 @@ type OrderChangeParams = { +:::warning + +**Don't use** this callback to update items order in state because it's called **frequently** during dragging. Use `onDragEnd` for **state updates** instead. + +::: + --- ### onDragMove @@ -883,6 +895,16 @@ You can also use any other haptics library but you will have to trigger haptics --- +### overflow + +Controls if the overflowing content should be clipped or visible. Applies only when no item is active. + +| type | default | required | +| ----------------------- | ---------- | -------- | +| `'hidden' \| 'visible'` | `'hidden'` | NO | + +--- + ### debug Enables debug mode, which shows additional views helpful for debugging. This property is intended for the library **developers** and is not recommended for the library **users**. diff --git a/packages/docs/docs/grid/props.mdx b/packages/docs/docs/grid/props.mdx index d7dc245b..7f1e18a4 100644 --- a/packages/docs/docs/grid/props.mdx +++ b/packages/docs/docs/grid/props.mdx @@ -456,11 +456,17 @@ Component to use as the drop indicator. It gives a **full control** over the dro ```tsx type DropIndicatorComponentProps = { - activationProgress: SharedValue; - touchedItemKey: SharedValue; + /** Progress of the active item animation (from 0 to 1) */ + activeAnimationProgress: SharedValue; + /** Key of the currently dragged item, or null if no item is being dragged */ + activeItemKey: SharedValue; + /** Current index where the dragged item would be dropped */ dropIndex: SharedValue; + /** Current position where the item would be dropped */ dropPosition: SharedValue; + /** Array of item keys in their current order */ orderedItemKeys: SharedValue>; + /** Style to be applied to the drop indicator */ style: ViewStyle; }; ``` @@ -704,6 +710,12 @@ type OrderChangeParams = { +:::warning + +**Don't use** this callback to update items order in state because it's called **frequently** during dragging. Use `onDragEnd` for **state updates** instead. + +::: + --- ### onDragMove @@ -769,6 +781,16 @@ You can also use any other haptics library but you will have to trigger haptics --- +### overflow + +Controls if the overflowing content should be clipped or visible. Applies only when no item is active. + +| type | default | required | +| ----------------------- | ---------- | -------- | +| `'hidden' \| 'visible'` | `'hidden'` | NO | + +--- + ### debug Enables debug mode, which shows additional views helpful for debugging. This property is intended for the library **developers** and is not recommended for the library **users**. diff --git a/packages/react-native-sortables/src/types/props/shared.ts b/packages/react-native-sortables/src/types/props/shared.ts index b95cbdf5..d738c193 100644 --- a/packages/react-native-sortables/src/types/props/shared.ts +++ b/packages/react-native-sortables/src/types/props/shared.ts @@ -12,7 +12,7 @@ import type { Animatable, AnimatableProps, Simplify } from '../utils'; * Almost all values are provided as Reanimated shared values for fast updates. */ export type DropIndicatorComponentProps = { - /** Progress of the active drag animation (0 to 1) */ + /** Progress of the active item animation (from 0 to 1) */ activeAnimationProgress: SharedValue; /** Key of the currently dragged item, or null if no item is being dragged */ activeItemKey: SharedValue; @@ -22,7 +22,7 @@ export type DropIndicatorComponentProps = { dropPosition: SharedValue; /** Array of item keys in their current order */ orderedItemKeys: SharedValue>; - /** Style to be applied to the drop indicator (will be merged with the default style) */ + /** Style to be applied to the drop indicator */ style: ViewStyle; };