Merge pull request #3861 from udecode/feat/dnd-column

Column dnd

.changeset/dnd-major.md

@@ -0,0 +1,12 @@
+---
+'@udecode/plate-dnd': major
+---
+
+- Removed `useDndBlock`, `useDragBlock`, and `useDropBlock` hooks in favor of `useDndNode`, `useDragNode`, and `useDropNode`.
+- Removed `DndProvider` and `useDraggableStore`. Drop line state is now managed by `DndPlugin` as a single state object `dropTarget` containing both `id` and `line`.
+- `useDropNode`: removed `onChangeDropLine` and `dropLine` options
+
+Migration steps:
+
+- Remove `DndProvider` from your draggable component (e.g. `draggable.tsx`)
+- Replace `useDraggableStore` with `useEditorPlugin(DndPlugin).useOption`

.changeset/dnd-minor.md

@@ -0,0 +1,11 @@
+---
+'@udecode/plate-dnd': minor
+---
+
+- `useDndNode` now supports horizontal orientation. New option is `orientation?: 'horizontal' | 'vertical'`. Default is `vertical`.
+- `useDraggableState`, `useDndNode`: add `canDropNode` callback option to query if a dragged node can be dropped onto a hovered node.
+- `useDropLine`:
+  - Added `id` option to show dropline only for hovered element. Default is `useElement().id`.
+  - Added `orientation` option to filter droplines by orientation (`'horizontal' | 'vertical'`). Default is `vertical`.
+  - Returns empty dropline if orientation doesn't match (e.g., horizontal dropline in vertical orientation)
+  - Returns empty dropline if elementId doesn't match current hovered element

apps/www/content/docs/components/changelog.mdx

@@ -9,6 +9,23 @@ Since Plate UI is not a component library, a changelog is maintained here.
 Use the [CLI](https://platejs.org/docs/components/cli) to install the latest version of the components.
 
 
+## December 2024 #17
+
+### December 16 #17.1
+
+- `column-element`:
+  - Add drag and drop support for columns
+  - Add drag handle with tooltip
+  - Fix column spacing and padding
+
+- `column-group-element`:
+  - Remove gap between columns
+  - Remove margin top
+
+- `draggable`:
+  - Remove `DraggableProvider` HOC
+  - Remove `DropLine` children prop
+
 ## November 2024 #16
 
 ### November 26 #16.9

apps/www/content/docs/dnd.mdx

@@ -50,6 +50,11 @@ Enables the scroller feature.
 <APIItem name="scrollerProps" type="Partial<ScrollerProps>" optional>
 Props for the `Scroller` component.
 
+</APIItem>
+
+<APIItem name="dropTarget" type="{ id: string | null; line: DropLineDirection }" optional>
+The current drop target state containing both the target element id and drop line direction.
+Internal state.
 </APIItem>
 </APIOptions>
 
@@ -150,16 +155,6 @@ Enhances a component with draggable behavior.
 
 ## API Components
 
-### DraggableProvider
-
-A new component that provides context for managing draggable state.
-
-<APIProps>
-  <APIItem name="children" type="React.ReactNode">
-    The child components to be wrapped with the draggable context.
-  </APIItem>
-</APIProps>
-
 ### DndScroller
 
 A wrapper component for the `Scroller` component that is conditionally rendered based on the dragging state.
@@ -192,17 +187,6 @@ A wrapper component for the `Scroller` component that is conditionally rendered
   </APIItem>
 </APIState>
 
-### useDndBlock
-
-A custom hook that wraps the `useDndNode` hook and configures it for dragging block items.
-
-<APIParameters>
-  <APIItem name="options" type="WithPartial<UseDndNodeOptions, 'type'>">
-    Options for the `useDndNode` hook, with the `type` property set to
-    `DRAG_ITEM_BLOCK`.
-  </APIItem>
-</APIParameters>
-
 ### useDndNode
 
 A custom hook that combines the `useDragNode` and `useDropNode` hooks to enable dragging and dropping of a node from the editor. It provides a default preview for the dragged node, which can be customized or disabled.
@@ -214,11 +198,17 @@ A custom hook that combines the `useDragNode` and `useDropNode` hooks to enable
         The ID of the node to be dragged.
       </APISubListItem>
       <APISubListItem parent="options" name="type" type="string">
-        The type of the node to be dragged.
+        The type of drag item. Defaults to `'block'`.
       </APISubListItem>
       <APISubListItem parent="options" name="nodeRef" type="any">
         The ref of the node to be dragged.
       </APISubListItem>
+      <APISubListItem parent="options" name="orientation" type="'horizontal' | 'vertical'" optional>
+        The orientation of drag and drop. Defaults to `'vertical'`.
+      </APISubListItem>
+      <APISubListItem parent="options" name="canDropNode" type="(args: { dragEntry: TNodeEntry; dragItem: DragItemNode; dropEntry: TNodeEntry; editor: PlateEditor }) => boolean" optional>
+        Callback to determine if a node can be dropped at the current location.
+      </APISubListItem>
       <APISubListItem parent="options" name="preview" type="previewOptions">
         The preview options for the dragged node.
 
@@ -246,29 +236,12 @@ A custom hook that combines the `useDragNode` and `useDropNode` hooks to enable
 <APIItem name="isOver" type="boolean">
   Indicates whether the dragged node is currently over a drop target.
 </APIItem>
-<APIItem name="dropLine" type="'' | 'top' | 'bottom'">
-  The direction of the drop line, indicating the position where the node can be
-  dropped.
-</APIItem>
 <APIItem name="dragRef" type="ConnectDragSource">
   The drag reference that should be assigned to the draggable element.
 </APIItem>
 
 </APIReturns>
 
-### useDragBlock
-
-A custom hook that enables dragging of a block node from the editor. It internally uses the `useDragNode` hook.
-
-<APIParameters>
-  <APIItem name="editor" type="PlateEditor">
-    The editor instance.
-  </APIItem>
-  <APIItem name="id" type="string">
-    The unique ID of the block node to be dragged.
-  </APIItem>
-</APIParameters>
-
 ### useDragNode
 
 A custom hook that enables dragging of a node from the editor using the `useDrag` hook from `react-dnd`.
@@ -296,21 +269,50 @@ A custom hook that enables dragging of a node from the editor using the `useDrag
   </APIItem>
 </APIParameters>
 
-### useDraggable
+### useDraggableState
 
-A custom hook that provides the necessary properties and event handlers for making an element draggable.
+A custom hook that manages the draggable state for a node.
 
-<APIState>
+<APIParameters>
+  <APIItem name="props" type="UseDndNodeOptions & { element: TElement }">
+    <APISubList>
+      <APISubListItem parent="props" name="element" type="TElement">
+        The element to make draggable.
+      </APISubListItem>
+      <APISubListItem parent="props" name="orientation" type="'horizontal' | 'vertical'" optional>
+        The orientation of drag and drop. Defaults to `'vertical'`.
+      </APISubListItem>
+      <APISubListItem parent="props" name="type" type="string" optional>
+        The type of drag item. Defaults to `'block'`.
+      </APISubListItem>
+      <APISubListItem parent="props" name="onDropHandler" type="function" optional>
+        Handler called when the element is dropped.
+      </APISubListItem>
+    </APISubList>
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  <APIItem name="dragRef" type="(element: Element | React.ReactElement | React.RefObject<any> | null) => void">
+    The drag source connector function.
+  </APIItem>
   <APIItem name="isDragging" type="boolean">
-    Indicates whether the node is currently being dragged.
+    Whether the element is currently being dragged.
   </APIItem>
-  <APIItem name="nodeRef" type="React.RefObject">
-    The ref of the node to be dragged.
+  <APIItem name="nodeRef" type="React.RefObject<HTMLDivElement>">
+    Reference to the draggable element.
   </APIItem>
-  <APIItem name="dragRef" type="ConnectDragSource">
-    The drag reference that should be assigned to the draggable element.
+</APIReturns>
+
+### useDraggable
+
+A custom hook that provides the necessary properties and event handlers for making an element draggable.
+
+<APIParameters>
+  <APIItem name="state" type="DraggableState">
+    The state returned from `useDraggableState`.
   </APIItem>
-</APIState>
+</APIParameters>
 
 <APIReturns>
   <APIItem name="previewRef" type="React.RefObject">
@@ -321,19 +323,6 @@ A custom hook that provides the necessary properties and event handlers for maki
   </APIItem>
 </APIReturns>
 
-### useDropBlock
-
-A custom hook that enables dropping a block into the editor. It internally uses the `useDropNode` hook to handle the drop behavior.
-
-<APIParameters>
-  <APIItem name="editor" type="PlateEditor">
-    The editor instance.
-  </APIItem>
-  <APIItem name="options" type="Omit<UseDropNodeOptions, 'accept'>">
-    Options for the drop behavior.
-  </APIItem>
-</APIParameters>
-
 ### useDropNode
 
 A custom hook that enables dropping a node on the editor. It uses the `useDrop` hook from `react-dnd` to handle the drop behavior.
@@ -382,23 +371,23 @@ Returns props for the draggable gutter.
 
 ### useDropLine
 
-Returns the current drop line state and props.
+Returns the current drop line state for an element.
+
+<APIParameters>
+<APIItem name="options" type="object" optional>
+  <APISubList>
+    <APISubListItem parent="options" name="id" type="string" optional>
+      The element ID to show drop line for. Defaults to current element ID.
+    </APISubListItem>
+    <APISubListItem parent="options" name="orientation" type="'horizontal' | 'vertical'" optional>
+      Filter drop lines by orientation. Defaults to 'vertical'.
+    </APISubListItem>
+  </APISubList>
+</APIItem>
+</APIParameters>
 
 <APIReturns>
-  <APIItem name="dropLine" type="'top' | 'bottom' | null">
-    The current direction of the drop line.
-  </APIItem>
-  <APIItem name="props" type="object">
-    Props to be spread on the drop line element.
-  </APIItem>
+<APIItem name="dropLine" type="'top' | 'bottom' | 'left' | 'right' | ''">
+  The current drop line direction.
+</APIItem>
 </APIReturns>
-
-### useDraggableStore
-
-Draggable store.
-
-<APIState>
-  <APIItem name="dropLine" type="'top' | 'bottom' | null">
-    The current direction of the drop line.
-  </APIItem>
-</APIState>

apps/www/src/components/plugins-tab-content.tsx

@@ -10,6 +10,7 @@ import { useDebounce } from '@/registry/default/hooks/use-debounce';
 import { Button } from '@/registry/default/plate-ui/button';
 import { Checkbox } from '@/registry/default/plate-ui/checkbox';
 
+import { Label } from '../registry/default/plate-ui/label';
 import { categoryIds, settingsStore } from './context/settings-store';
 import { Icons } from './icons';
 import { SettingCheckbox } from './setting-checkbox';
@@ -20,7 +21,6 @@ import {
   AccordionItem,
   AccordionTrigger,
 } from './ui/accordion';
-import { Label } from '../registry/default/plate-ui/label';
 
 export function SettingsEffect() {
   const checkedPluginsNext = settingsStore.use.checkedPluginsNext();

apps/www/src/components/setting-checkbox.tsx

@@ -12,12 +12,12 @@ import {
   PopoverTrigger,
 } from '@/registry/default/plate-ui/popover';
 
+import { Label } from '../registry/default/plate-ui/label';
 import { Code } from './code';
 import { settingsStore } from './context/settings-store';
 import { Icons } from './icons';
 import { TreeIcon } from './tree-icon';
 import { Badge } from './ui/badge';
-import { Label } from '../registry/default/plate-ui/label';
 
 export function SettingCheckbox({
   id,

apps/www/src/components/theme-customizer.tsx

@@ -14,9 +14,9 @@ import { useMounted } from '@/registry/default/hooks/use-mounted';
 import { Button } from '@/registry/default/plate-ui/button';
 import { Separator } from '@/registry/default/plate-ui/separator';
 
+import { Label } from '../registry/default/plate-ui/label';
 import { CopyCodeButton, getThemeCode } from './copy-code-button';
 import { ThemesSwitcher } from './themes-selector-mini';
-import { Label } from '../registry/default/plate-ui/label';
 import { Skeleton } from './ui/skeleton';
 
 export function ThemeCustomizer() {

apps/www/src/registry/default/example/editable-voids-demo.tsx

@@ -6,13 +6,13 @@ import type { PlateRenderElementProps } from '@udecode/plate-common/react';
 
 import { Plate, createPlatePlugin } from '@udecode/plate-common/react';
 
-import { Label } from '@/registry/default/plate-ui/label';
 import { RadioGroup, RadioGroupItem } from '@/components/ui/radio-group';
 import { editorPlugins } from '@/registry/default/components/editor/plugins/editor-plugins';
 import { useCreateEditor } from '@/registry/default/components/editor/use-create-editor';
 import { editableVoidsValue } from '@/registry/default/example/values/editable-voids-value';
 import { Editor, EditorContainer } from '@/registry/default/plate-ui/editor';
 import { Input } from '@/registry/default/plate-ui/input';
+import { Label } from '@/registry/default/plate-ui/label';
 
 export const EditableVoidPlugin = createPlatePlugin({
   key: 'editable-void',