Merge pull request #62 from MohamedRejeb/0.5.x

Docs improvements

Author: MohamedRejeb

compose-dnd/src/commonMain/kotlin/com/mohamedrejeb/compose/dnd/drag/DraggableItemModifier.kt

@@ -92,8 +92,7 @@ fun <T> Modifier.draggableItem(
                 sizeDropAnimationSpec = sizeDropAnimationSpec,
                 draggableContent = draggableContent,
             )
-        )
-        .pointerInput(
+        ).pointerInput(
             key,
             enabled,
             state,

compose-dnd/src/commonMain/kotlin/com/mohamedrejeb/compose/dnd/drag/DropStrategy.kt

@@ -20,14 +20,35 @@ import androidx.compose.ui.geometry.Size
 import com.mohamedrejeb.compose.dnd.drop.DropTargetState
 import com.mohamedrejeb.compose.dnd.utils.MathUtils
 
+/**
+ * Strategy for determining which drop target receives the dragged item when
+ * multiple targets overlap.
+ *
+ * Built-in strategies:
+ * - [Surface] — Largest absolute overlap area wins.
+ * - [SurfacePercentage] — Largest overlap as a percentage of the dragged item wins. (Default)
+ * - [CenterDistance] — Closest center-to-center distance wins.
+ */
 interface DropStrategy {
 
+    /**
+     * Determine which drop target the dragged item is currently hovering over.
+     *
+     * @param draggedItemTopLeft Top-left position of the dragged item in root coordinates.
+     * @param draggedItemSize Size of the dragged item.
+     * @param dropTargets List of candidate drop targets that intersect with the dragged item.
+     * @return The drop target that should receive the drop, or null if none qualifies.
+     */
     fun <T> getHoveredDropTarget(
         draggedItemTopLeft: Offset,
         draggedItemSize: Size,
         dropTargets: List<DropTargetState<T>>,
     ): DropTargetState<T>?
 
+    /**
+     * Selects the target with the largest absolute overlap area.
+     * Z-index is factored in by adding `zIndex * maxArea` to the score.
+     */
     object Surface : DropStrategy {
         override fun <T> getHoveredDropTarget(
             draggedItemTopLeft: Offset,
@@ -47,6 +68,10 @@ interface DropStrategy {
                 }
     }
 
+    /**
+     * Selects the target with the largest overlap as a percentage of the dragged item area.
+     * This is the default strategy. Z-index is added to the percentage score.
+     */
     object SurfacePercentage : DropStrategy {
         override fun <T> getHoveredDropTarget(
             draggedItemTopLeft: Offset,
@@ -66,6 +91,9 @@ interface DropStrategy {
                 }
     }
 
+    /**
+     * Selects the target whose center is closest to the dragged item's center.
+     */
     object CenterDistance : DropStrategy {
         override fun <T> getHoveredDropTarget(
             draggedItemTopLeft: Offset,

compose-dnd/src/commonMain/kotlin/com/mohamedrejeb/compose/dnd/drop/DropTarget.kt

@@ -36,10 +36,18 @@ import com.mohamedrejeb.compose.dnd.drag.DraggedItemState
  * Mark this composable as a drop target.
  *
  * @param key The key used to identify the drop target.
- * @param zIndex The z-index of the drop target.
  * @param state The drag and drop state.
- * @param dropAlignment The alignment of the dropped item.
- * @param dropOffset The offset of the dropped item.
+ * @param zIndex The z-index of the drop target. When multiple targets overlap,
+ * the one with the highest z-index takes priority.
+ * @param dropAlignment The alignment of the dropped item within this target
+ * for the drop animation.
+ * @param dropOffset An additional offset applied to the drop animation position.
+ * @param dropAnimationEnabled Whether the drop animation is enabled. When false,
+ * the dragged item disappears immediately on drop without animating to the target.
+ * @param canDrop Whether this target currently accepts drops. When false, the target
+ * is excluded from hover detection — dragged items cannot hover over it or be dropped on it.
+ * This is a Compose-evaluated boolean, so it can read state (e.g., `state.draggedItem?.data`)
+ * to dynamically accept or reject specific items.
  * @param onDrop The action to perform when an item is dropped onto the target.
  * Accepts the dragged item state as a parameter.
  * @param onDragEnter The action to perform when an item is dragged over the target.

compose-dnd/src/commonMain/kotlin/com/mohamedrejeb/compose/dnd/reorder/ReorderState.kt

@@ -23,8 +23,9 @@ import com.mohamedrejeb.compose.dnd.annotation.ExperimentalDndApi
 
 /**
  * Remember [ReorderState]
- * @param dragAfterLongPress if true, drag will start after long press, otherwise drag will start after simple press
+ * @param dragAfterLongPress if true, drag will start after long press, otherwise drag will start after simple press.
  * This parameter is applied to all [ReorderableItem]s. If you want to change it for a specific item, use [ReorderableItem] parameter.
+ * @param requireFirstDownUnconsumed if true, the first down event must be unconsumed to start the drag.
  * @return [ReorderState]
  */
 @Composable

compose-dnd/src/commonMain/kotlin/com/mohamedrejeb/compose/dnd/reorder/ReorderableItemModifier.kt

@@ -98,8 +98,7 @@ fun <T> Modifier.reorderableItem(
             dropAnimationSpec = dropAnimationSpec,
             sizeDropAnimationSpec = sizeDropAnimationSpec,
             draggableContent = draggableContent,
-        )
-        .dropTarget(
+        ).dropTarget(
             key = key,
             state = state,
             zIndex = zIndex,

compose-dnd/src/commonMain/kotlin/com/mohamedrejeb/compose/dnd/reorder/ReorderableItemScope.kt

@@ -24,6 +24,10 @@ import com.mohamedrejeb.compose.dnd.drag.DragHandleModifier
 import com.mohamedrejeb.compose.dnd.drag.DraggableItemScope
 import com.mohamedrejeb.compose.dnd.drag.DraggableItemState
 
+/**
+ * Scope for [ReorderableItem] content. Extends [DraggableItemScope] with
+ * access to [isDragging] state and [dragHandle] modifier.
+ */
 interface ReorderableItemScope : DraggableItemScope
 
 internal class ReorderableItemScopeImpl<T>(

docs/drag-and-drop/overview.md

@@ -4,7 +4,8 @@ Compose DND provides a declarative API for adding drag and drop functionality to
 
 - `DragAndDropState` -- Holds the state for all drag and drop operations.
 - `DragAndDropContainer` -- A container that wraps all draggable items and drop targets.
-- `DraggableItem` -- Makes a composable draggable.
+- `DraggableItem` composable -- Makes a composable draggable (wrapper approach).
+- `draggableItem` modifier -- Makes a composable draggable (modifier approach, less boilerplate).
 - `dropTarget` modifier -- Marks a composable as a drop target.
 
 ## Creating DragAndDropState
@@ -91,6 +92,32 @@ Inside `DraggableItem`'s content lambda, you have access to `DraggableItemScope`
 - `key: Any` -- The key of this item.
 - `isDragging: Boolean` -- Whether this item is currently being dragged.
 
+## draggableItem Modifier
+
+As an alternative to the `DraggableItem` composable wrapper, you can use the `Modifier.draggableItem` modifier directly. This reduces boilerplate by eliminating the wrapper composable.
+
+```kotlin
+val isDragging = dragAndDropState.isDragging("item-1")
+
+Text(
+    text = "Drag me",
+    modifier = Modifier
+        .graphicsLayer { alpha = if (isDragging) 0f else 1f }
+        .draggableItem(
+            state = dragAndDropState,
+            key = "item-1",
+            data = "Hello World",
+            draggableContent = {
+                Text("Drag me") // Content shown as drag shadow
+            },
+        )
+)
+```
+
+The `draggableItem` modifier accepts the same parameters as `DraggableItem` (except `content`, which is the composable it's applied to). The `draggableContent` parameter is required — it defines what the drag shadow looks like.
+
+Use `DragAndDropState.isDragging(key)` to check if a specific item is being dragged.
+
 ## Drop Target
 
 Use the `Modifier.dropTarget` extension to mark any composable as a drop target.
@@ -127,6 +154,7 @@ Box(
 | `dropAlignment`       | `Alignment`                            | `Alignment.Center` | Alignment of the dropped item within the target for the drop animation. |
 | `dropOffset`          | `Offset`                               | `Offset.Zero`      | Additional offset for the drop animation position. |
 | `dropAnimationEnabled`| `Boolean`                              | `true`             | Whether to animate the drop. If `false`, the drop callback fires immediately. |
+| `canDrop`             | `Boolean`                              | `true`             | Whether this target accepts drops. When `false`, dragged items cannot hover over or be dropped on this target. Can read `state.draggedItem?.data` to validate dynamically. |
 | `onDrop`              | `(DraggedItemState<T>) -> Unit`        | `{}`               | Called when an item is dropped on this target. |
 | `onDragEnter`         | `(DraggedItemState<T>) -> Unit`        | `{}`               | Called when a dragged item enters this target. |
 | `onDragExit`          | `(DraggedItemState<T>) -> Unit`        | `{}`               | Called when a dragged item exits this target. |

docs/drag-and-drop/reorder.md

@@ -204,3 +204,48 @@ private fun ItemCard(
 
 !!! tip
     Use `graphicsLayer { alpha = if (isDragging) 0f else 1f }` to hide the original item while it is being dragged, so only the drag shadow is visible.
+
+## reorderableItem Modifier
+
+As an alternative to the `ReorderableItem` composable wrapper, you can use the `Modifier.reorderableItem` modifier. This combines `draggableItem` and `dropTarget` into a single modifier and reduces boilerplate.
+
+```kotlin
+val dndState = rememberDragAndDropState<String>()
+
+DragAndDropContainer(state = dndState) {
+    LazyColumn(
+        verticalArrangement = Arrangement.spacedBy(12.dp),
+    ) {
+        items(items, key = { it }) { item ->
+            val isDragging = dndState.isDragging(item)
+
+            ItemCard(
+                text = item,
+                modifier = Modifier
+                    .graphicsLayer { alpha = if (isDragging) 0f else 1f }
+                    .reorderableItem(
+                        key = item,
+                        data = item,
+                        state = dndState,
+                        onDragEnter = { state ->
+                            items = items.toMutableList().apply {
+                                val index = indexOf(item)
+                                if (index != -1) {
+                                    remove(state.data)
+                                    add(index, state.data)
+                                }
+                            }
+                        },
+                        draggableContent = {
+                            ItemCard(text = item, isDragShadow = true)
+                        },
+                    )
+                    .fillMaxWidth(),
+            )
+        }
+    }
+}
+```
+
+!!! note
+    When using the modifier API, use `rememberDragAndDropState` and `DragAndDropContainer` directly instead of `rememberReorderState` and `ReorderContainer`. Use `DragAndDropState.isDragging(key)` to check drag state.

sample/common/src/commonMain/kotlin/ui/ConditionalDropScreen.kt

@@ -73,6 +73,9 @@ private fun ConditionalDropContent(
     val evenFull = evenTargetCount >= 2
     val oddFull = oddTargetCount >= 2
 
+    // Read the dragged item's data to validate parity in canDrop
+    val draggedNumber = state.draggedItem?.data?.toIntOrNull()
+
     DragAndDropContainer(
         state = state,
         modifier = modifier,
@@ -130,7 +133,8 @@ private fun ConditionalDropContent(
                         .dropTarget(
                             key = "even",
                             state = state,
-                            canDrop = !evenFull,
+                            canDrop = !evenFull && (draggedNumber == null || draggedNumber % 2 == 0),
+                            dropAnimationEnabled = false,
                             onDrop = { droppedItem ->
                                 val num = droppedItem.data.toIntOrNull() ?: return@dropTarget
                                 if (num % 2 == 0) {
@@ -152,7 +156,8 @@ private fun ConditionalDropContent(
                         .dropTarget(
                             key = "odd",
                             state = state,
-                            canDrop = !oddFull,
+                            canDrop = !oddFull && (draggedNumber == null || draggedNumber % 2 != 0),
+                            dropAnimationEnabled = false,
                             onDrop = { droppedItem ->
                                 val num = droppedItem.data.toIntOrNull() ?: return@dropTarget
                                 if (num % 2 != 0) {

sample/common/src/commonMain/kotlin/ui/ItemToItemOneDirectionScreen.kt

@@ -126,8 +126,7 @@ private fun ItemToItemOneDirectionScreenContent(
                                 draggableContent = {
                                     RedBox(modifier = Modifier.size(200.dp))
                                 },
-                            )
-                            .size(200.dp),
+                            ).size(200.dp),
                     )
                 }
             }