@contember/react-repeater-dnd-kit 2.0.0-alpha.9 → 2.0.0-beta.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@contember/react-repeater-dnd-kit",
   "license": "Apache-2.0",
-  "version": "2.0.0-alpha.9",
+  "version": "2.0.0-beta.2",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/production/index.js",
@@ -11,6 +11,7 @@
         "types": "./dist/types/index.d.ts",
         "development": "./dist/development/index.js",
         "production": "./dist/production/index.js",
+        "typescript": "./src/index.ts",
         "default": "./dist/production/index.js"
       },
       "require": {
@@ -28,13 +29,13 @@
     "ae:test": "api-extractor run"
   },
   "dependencies": {
-    "@contember/react-binding": "2.0.0-alpha.9",
-    "@contember/react-repeater": "2.0.0-alpha.9",
-    "@contember/react-utils": "2.0.0-alpha.9",
+    "@contember/react-binding": "2.0.0-beta.2",
+    "@contember/react-repeater": "2.0.0-beta.2",
+    "@contember/react-utils": "2.0.0-beta.2",
     "@dnd-kit/core": "^6.1.0",
     "@dnd-kit/sortable": "^8.0.0",
-    "@radix-ui/react-portal": "^1.0.4",
-    "@radix-ui/react-slot": "^1.0.2"
+    "@radix-ui/react-portal": "^1.1.2",
+    "@radix-ui/react-slot": "^1.1.0"
   },
   "peerDependencies": {
     "react": "^18 || ^19",
@@ -49,4 +50,4 @@
     "url": "https://github.com/contember/interface.git",
     "directory": "packages/react-repeater-dnd-kit"
   }
-}
+}

package/src/components/RepeaterSortable.tsx

@@ -5,6 +5,37 @@ import { RepeaterActiveEntityContext } from '../contexts'
 import { SortableContext, verticalListSortingStrategy } from '@dnd-kit/sortable'
 import { useRepeaterMethods, useRepeaterSortedEntities } from '@contember/react-repeater'
 
+/**
+ * Initializes dnd-kit based sorting for the repeater.
+ * Using the props, you can customize the behavior of the sorting and hook into the drag events.
+ *
+ * ## Example
+ * ```tsx
+ * <Repeater {...}>
+ *   <RepeaterSortable>
+ *     <RepeaterSortableEachItem>
+ *       <div>
+ *         <RepeaterSortableDropIndicator position={'before'}><div>Drop here</div></RepeaterSortableDropIndicator>
+ *         <RepeaterSortableItemNode>
+ *           <div>
+ *             <RepeaterSortableItemActivator>
+ *               <span/>
+ *             </RepeaterSortableItemActivator>
+ *             {children}
+ *           </div>
+ *         </RepeaterSortableItemNode>
+ *         <RepeaterSortableDropIndicator position={'afer'}><div>Drop here</div></RepeaterSortableDropIndicator>
+ *       </div>
+ *     </RepeaterSortableEachItem>
+ *     <RepeaterSortableDragOverlay>
+ *       <div>
+ *         {children}
+ *       </div>
+ *     </RepeaterSortableDragOverlay>
+ *   </RepeaterSortable>
+ * </Repeater>
+ * ```
+ */
 export const RepeaterSortable = ({ children, onDragStart, onDragEnd: onDragEndIn, onDragCancel: onDragCancelIn, ...props }: {
 	children: ReactNode
 } & DndContextProps) => {

package/src/components/RepeaterSortableDragOverlay.tsx

@@ -5,6 +5,9 @@ import { DragOverlay } from '@dnd-kit/core'
 import { AccessorTree, Entity, useAccessorTreeState } from '@contember/react-binding'
 import { RepeaterCurrentEntityContext } from '@contember/react-repeater'
 
+/**
+ * Component for rendering the repeater item being dragged.
+ */
 export const RepeaterSortableDragOverlay = ({ children }: {
 	children: ReactNode
 }) => {

package/src/components/RepeaterSortableDropIndicator.tsx

@@ -1,6 +1,9 @@
 import React, { ReactNode } from 'react'
 import { useRepeaterSortableItem } from '../contexts'
 
+/**
+ * Renders a child element when the repeater item is being dragged over the drop indicator.
+ */
 export const RepeaterSortableDropIndicator = ({ children, position }: {
 	children: ReactNode
 	position: 'before' | 'after'

package/src/components/RepeaterSortableEachItem.tsx

@@ -4,6 +4,10 @@ import { RepeaterEachItem, useRepeaterSortedEntities } from '@contember/react-re
 import { RepeaterSortableItemContext } from '../contexts'
 import { useEntity } from '@contember/react-binding'
 
+/**
+ * Iterates over all entities in the repeater and renders the children for each entity.
+ * Also sets up the dnd-kit sortable context for the repeater items.
+ */
 export const RepeaterSortableEachItem = ({ children }: {
 	children: ReactNode
 }) => {

package/src/components/RepeaterSortableItemActivator.tsx

@@ -1,10 +1,13 @@
-import React, { forwardRef, ReactNode } from 'react'
+import React, { forwardRef, ReactElement, ReactNode } from 'react'
 import { useRepeaterSortableItem } from '../contexts'
 import { Slot } from '@radix-ui/react-slot'
 import { useComposeRef } from '@contember/react-utils'
 
+/**
+ * Slot for the repeater item activator, which is the element that triggers the drag and drop interaction (e.g. a handle).
+ */
 export const RepeaterSortableItemActivator = forwardRef<HTMLElement, {
-	children: ReactNode
+	children: ReactElement
 }>((props, ref) => {
 	const { setActivatorNodeRef, listeners } = useRepeaterSortableItem()
 	return <Slot ref={useComposeRef(ref, setActivatorNodeRef)} {...listeners} {...props} />

package/src/components/RepeaterSortableItemNode.tsx

@@ -1,9 +1,12 @@
-import React, { ReactNode } from 'react'
+import React, { ReactElement } from 'react'
 import { useRepeaterSortableItem } from '../contexts'
 import { Slot } from '@radix-ui/react-slot'
 
+/**
+ * Slot for the repeater item node, which is the element that is being dragged.
+ */
 export const RepeaterSortableItemNode = ({ children }: {
-	children: ReactNode
+	children: ReactElement
 }) => {
 	const { setNodeRef } = useRepeaterSortableItem()
 	return <Slot ref={setNodeRef}>{children}</Slot>

package/src/contexts.ts

@@ -5,9 +5,15 @@ import { useSortable } from '@dnd-kit/sortable'
 const RepeaterSortableItemContext_ = createRequiredContext<ReturnType<typeof useSortable>>('RepeaterSortableItemContext')
 /** @internal */
 export const RepeaterSortableItemContext = RepeaterSortableItemContext_[0]
+/**
+ * Returns the sortable context from dnd-kit (e.g. isDragging, isOver, setNodeRef) for the repeater item.
+ */
 export const useRepeaterSortableItem = RepeaterSortableItemContext_[1]
 
 const RepeaterActiveEntityContext_ = createContext<EntityAccessor | undefined>('RepeaterActiveEntityContext', undefined)
 /** @internal */
 export const RepeaterActiveEntityContext = RepeaterActiveEntityContext_[0]
+/**
+ * Returns the entity that is currently being dragged in the repeater.
+ */
 export const useRepeaterActiveEntity = RepeaterActiveEntityContext_[1]