Merge pull request #3878 from udecode/feat/dnd-above-nodes

Dnd above nodes
udecode · Dec 20, 2024 · d703840 · d703840
2 parents 2e25ff7 + 4fa87c4
commit d703840
Show file tree

Hide file tree

Showing 97 changed files with 1,416 additions and 2,269 deletions.
diff --git a/.changeset/dnd-major copy 2.md b/.changeset/dnd-major copy 2.md
@@ -0,0 +1,8 @@
+---
+'@udecode/plate-layout': patch
+---
+
+- Add `setColumns`: set any number of columns of any size to a column group. Decreasing the number of columns will move the removed columns' content to the last remaining column.
+- `toggleColumnGroup`: now uses `setColumns` if we're already in a column group.
+- Remove `layout` prop from `column_group` nodes. We're now only relying on `column` `width` prop. You can unset `layout` prop or just leave it as it is since it's not read anymore.
+- `ColumnPlugin`: Added width normalization ensuring column widths always sum to 100% by automatically adjusting widths when columns are added or removed. If the sum of widths is not 100%, the difference is distributed evenly across all columns.
diff --git a/.changeset/dnd-major copy 3.md b/.changeset/dnd-major copy 3.md
@@ -0,0 +1,8 @@
+---
+'@udecode/plate-layout': patch
+---
+
+Additional breaking changes to v41:
+
+- `insertColumnGroup`: rename `layout` to `columns`
+- Remove `setColumnWidth`, `useColumnState`. Use `setColumns` instead
diff --git a/.changeset/dnd-major copy.md b/.changeset/dnd-major copy.md
@@ -0,0 +1,7 @@
+---
+'@udecode/plate-core': patch
+---
+
+- Add `useNodePath(node: TNode)`: memoized `findPath` (`useMemo`)
+- Add `usePath(pluginKey?: string)`: memoized `findPath` (context)
+- `PlateElementProps` now includes `path` prop, also accessible using `usePath`
diff --git a/.changeset/dnd-major.md b/.changeset/dnd-major.md
@@ -0,0 +1,10 @@
+---
+'@udecode/plate-dnd': patch
+---
+
+Additional breaking changes to v41:
+
+- Remove `useDraggableState`. Use `const { isDragging, previewRef, handleRef } = useDraggable`
+- Remove `useDraggableGutter`. Set `contentEditable={false}` to your gutter element
+- Remove `props` from `useDropLine`. Set `contentEditable={false}` to your drop line element
+- Remove `withDraggable`, `useWithDraggable`. Use [`DraggableAboveNodes`](https://github.com/udecode/plate/pull/3878/files#diff-493c12ebed9c3ef9fd8c3a723909b18ad439a448c0132d2d93e5341ee0888ad2) instead
diff --git a/apps/www/content/docs/api/core.mdx b/apps/www/content/docs/api/core.mdx
@@ -405,6 +405,49 @@ Returns a prop value derived from the current selection fragment.
   A value derived from the fragment nodes, or undefined if no consistent value is found across the specified nodes.
 </APIReturns>
 
+### useNodePath
+
+Returns the path of a node in the editor.
+
+<APIParameters>
+  <APIItem name="node" type="TNode">
+    The node to find the path for.
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  A memoized Path array representing the location of the node in the editor's tree structure.
+</APIReturns>
+
+### usePath
+
+Get the memoized path of the closest element.
+
+<APIParameters>
+  <APIItem name="pluginKey" type="string" optional>
+    The key of the plugin to get the path for.
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  The path of the element, or `undefined` if used outside of a node component's context.
+</APIReturns>
+
+### useElement
+
+Get the element by plugin key.
+
+<APIParameters>
+  <APIItem name="pluginKey" type="string" optional>
+    The key of the plugin to get the element for.
+    - **Default:** `'element'`
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  The element of type `T extends TElement`, or an empty object if used outside of a node component's context.
+</APIReturns>
+
 ## Core plugins
 
 ### DebugPlugin

diff --git a/apps/www/content/docs/api/utils.mdx b/apps/www/content/docs/api/utils.mdx
@@ -18,14 +18,17 @@ PlateElementProps.
 <APIItem name="className" type="string" optional>
 The CSS class to apply to the component.
 </APIItem>
-<APIItem name="editor" type="E">
-The editor instance.
-</APIItem>
 <APIItem name="nodeProps" type="AnyObject" optional>
 Additional props to pass to the component.
 </APIItem>
+<APIItem name="editor" type="E">
+The editor instance. Also available using `useEditorRef` hook.
+</APIItem>
 <APIItem name="element" type="TElement">
-The element node.
+The element node. Also available using `useElement` hook.
+</APIItem>
+<APIItem name="path" type="Path">
+The path of the element in the editor tree. Also available using `usePath` hook.
 </APIItem>
 <APIItem name="attributes" type="object">
 Attributes of the element to be spread on the top-level element.

diff --git a/apps/www/content/docs/column.mdx b/apps/www/content/docs/column.mdx
@@ -53,9 +53,6 @@ Add Column Item Plugin to your document.
 <APIAttributes>
 Extends `TElement`.
 
-<APIItem name="layout" type="number[]" optional>
-  Set the width of its children `Column`
-</APIItem>
 </APIAttributes>
 
 ### TColumnElement
@@ -76,9 +73,9 @@ Insert a columnGroup with two empty columns.
   <APIItem name="editor" type="PlateEditor">
     The editor instance.
   </APIItem>
-  <APIItem name="options" type="InsertNodesOptions & { layout?: number[] | number }">
-    - `layout`: Array of column widths or number of equal-width columns (default: 2)
-    - Other InsertNodesOptions to control insert behavior
+  <APIItem name="options" type="InsertNodesOptions & { columns?: number[] | number }">
+    - `columns`: Array of column widths or number of equal-width columns (default: 2)
+    - Other `InsertNodesOptions` to control insert behavior
   </APIItem>
 </APIParameters>
 
@@ -111,59 +108,69 @@ Move the middle column to the left or right by options.direction. If the middle
   </APIItem>
 </APIParameters>
 
-### setColumnWidth
+### toggleColumnGroup
 
-Set the width of `ColumnGroup`'s children. In general, you don't need to use this function, since we will call this function automatically when the property of `layout` changes.
-If you want to set the `layout` use setNodes.
+Converts a block into a column group layout or updates an existing column group's layout.
 
 <APIParameters>
   <APIItem name="editor" type="PlateEditor">
     The editor instance.
   </APIItem>
-  <APIItem name="groupPathRef" type="PathRef">
-    The path ref of `ColumnGroup`
-  </APIItem>
-  <APIItem name="layout" type="number[]">
-    The element property of `layout`
+  <APIItem name="options" type="object">
+    <APISubList>
+      <APISubListItem parent="options" name="at" type="Location" optional>
+        The location to toggle the column group at.
+      </APISubListItem>
+      <APISubListItem parent="options" name="columns" type="number" optional>
+        Number of equal-width columns to create (default: 2)
+      </APISubListItem>
+      <APISubListItem parent="options" name="widths" type="string[]" optional>
+        Array of column widths (e.g., ['50%', '50%']). Takes precedence over `columns`.
+      </APISubListItem>
+    </APISubList>
   </APIItem>
 </APIParameters>
 
-### toggleColumnGroup
+Behavior:
+- If the target block is not a column group, wraps it in a new column group with the specified number of columns
+- If the target block is already a column group, updates its column layout using `setColumns`
+- The original content becomes the content of the first column
+- Additional columns are created with empty paragraphs
 
-Convert a block into a column group layout. The selected block becomes the content of the first column.
+### setColumns
+
+Updates the column layout of an existing column group by modifying the number and widths of columns.
 
 <APIParameters>
   <APIItem name="editor" type="PlateEditor">
     The editor instance.
   </APIItem>
-  <APIItem name="options" type="ReplaceNodeChildrenOptions & { layout?: number[] | number }">
-    - `layout`: Array of column widths or number of equal-width columns (default: 2)
+  <APIItem name="options" type="object">
+    <APISubList>
+      <APISubListItem parent="options" name="at" type="Path">
+        The path to the column group element.
+      </APISubListItem>
+      <APISubListItem parent="options" name="columns" type="number" optional>
+        Number of equal-width columns to create.
+      </APISubListItem>
+      <APISubListItem parent="options" name="widths" type="string[]" optional>
+        Array of column widths (e.g., ['33%', '67%']). Takes precedence over `columns`.
+      </APISubListItem>
+    </APISubList>
   </APIItem>
 </APIParameters>
 
-## API Components
-
-### useColumnState
+Behavior:
+- When increasing columns:
+  - Keeps existing column content
+  - Adds new empty columns with specified widths
+- When decreasing columns:
+  - Merges content from removed columns into the last remaining column
+  - Updates widths of remaining columns
+- When keeping same number of columns:
+  - Only updates column widths
 
-<APIReturns>
-  <APIItem name="setDoubleColumn" type="function">
-    Call this function to make the `ColumnGroup`'s children, column bisects the
-    parent element space. This sets the `layout` property of
-    `ColumnGroup` to `[50,50]`
-  </APIItem>
-  <APIItem name="setThreeColumn" type="function">
-    Set the `layout` property of `ColumnGroup` to `[33, 33, 33]`
-  </APIItem>
-  <APIItem name="setRightSideDoubleColumn" type="function">
-    Set the `layout` property of `ColumnGroup` to `[70,30]`
-  </APIItem>
-  <APIItem name="setLeftSideDoubleColumn" type="function">
-    Set the `layout` property of `ColumnGroup` to `[30,70]`
-  </APIItem>
-  <APIItem name="setDoubleSideDoubleColumn" type="function">
-    Set the `layout` property of `ColumnGroup` to `[25, 50, 25]`
-  </APIItem>
-</APIReturns>
+## API Components
 
 ### useDebouncePopoverOpen
 

diff --git a/apps/www/content/docs/components/changelog.mdx b/apps/www/content/docs/components/changelog.mdx
@@ -12,6 +12,23 @@ Use the [CLI](https://platejs.org/docs/components/cli) to install the latest ver
 
 ### December 20 #17.3
 
+- `insertColumnGroup`, `toggleColumnGroup`: use `columns` option instead of `layout` 
+- Remove `with-draggables`. Add [`DraggableAboveNodes`](https://github.com/udecode/plate/pull/3878/files#diff-493c12ebed9c3ef9fd8c3a723909b18ad439a448c0132d2d93e5341ee0888ad2) to `draggable`. Add to `DndPlugin` config:
+```tsx
+DndPlugin.configure({ render: { aboveNodes: DraggableAboveNodes } }),
+```
+- `column-element`, `image-element`, `media-video-element`: Remove `useDraggableState`. Use `const { isDragging, previewRef, handleRef } = useDraggable`
+- `column-group-element`: Remove `useColumnState`. Use instead:
+```tsx
+const columnGroupElement = useElement<TColumnGroupElement>(ColumnPlugin.key);
+
+const onColumnChange = (widths: string[]) => {
+  setColumns(editor, {
+    at: findNodePath(editor, columnGroupElement),
+    widths,
+  });
+};
+```
 - `export-toolbar-button`: add `exportToHtml`
 
 ### December 19 #17.2

diff --git a/apps/www/content/docs/dnd.mdx b/apps/www/content/docs/dnd.mdx
@@ -269,60 +269,41 @@ A custom hook that enables dragging of a node from the editor using the `useDrag
   </APIItem>
 </APIParameters>
 
-### useDraggableState
+### useDraggable
 
 A custom hook that manages the draggable state for a node.
 
 <APIParameters>
-  <APIItem name="props" type="UseDndNodeOptions & { element: TElement }">
+  <APIItem name="options" type="UseDndNodeOptions & { element: TElement }">
     <APISubList>
-      <APISubListItem parent="props" name="element" type="TElement">
+      <APISubListItem parent="options" name="element" type="TElement">
         The element to make draggable.
       </APISubListItem>
-      <APISubListItem parent="props" name="orientation" type="'horizontal' | 'vertical'" optional>
+      <APISubListItem parent="options" name="orientation" type="'horizontal' | 'vertical'" optional>
         The orientation of drag and drop. Defaults to `'vertical'`.
       </APISubListItem>
-      <APISubListItem parent="props" name="type" type="string" optional>
+      <APISubListItem parent="options" name="type" type="string" optional>
         The type of drag item. Defaults to `'block'`.
       </APISubListItem>
-      <APISubListItem parent="props" name="onDropHandler" type="function" optional>
+      <APISubListItem parent="options" 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">
+  <APIItem name="handleRef" type="(element: Element | React.ReactElement | React.RefObject<any> | null) => void">
     The drag source connector function.
   </APIItem>
   <APIItem name="isDragging" type="boolean">
     Whether the element is currently being dragged.
   </APIItem>
-  <APIItem name="nodeRef" type="React.RefObject<HTMLDivElement>">
+  <APIItem name="previewRef" type="React.RefObject<HTMLDivElement>">
     Reference to the draggable element.
   </APIItem>
 </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>
-</APIParameters>
-
-<APIReturns>
-  <APIItem name="previewRef" type="React.RefObject">
-    A reference to the HTML `div` element that serves as the preview during drag.
-  </APIItem>
-  <APIItem name="handleRef" type="ConnectDragSource">
-    A reference to the drag source connector provided by `react-dnd`.
-  </APIItem>
-</APIReturns>
-
 ### 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.
@@ -359,16 +340,6 @@ A custom hook that enables dropping a node on the editor. It uses the `useDrop`
   </APIItem>
 </APIParameters>
 
-### useDraggableGutter
-
-Returns props for the draggable gutter.
-
-<APIReturns>
-  <APIItem name="props" type="object">
-    Props to be spread on the gutter element.
-  </APIItem>
-</APIReturns>
-
 ### useDropLine
 
 Returns the current drop line state for an element.

diff --git a/apps/www/package.json b/apps/www/package.json
@@ -84,7 +84,6 @@
     "@udecode/plate-block-quote": "workspace:^",
     "@udecode/plate-break": "workspace:^",
     "@udecode/plate-caption": "workspace:^",
-    "@udecode/plate-cloud": "workspace:^",
     "@udecode/plate-code-block": "workspace:^",
     "@udecode/plate-combobox": "workspace:^",
     "@udecode/plate-comments": "workspace:^",

diff --git a/apps/www/src/app/(app)/_components/installation-tab.tsx b/apps/www/src/app/(app)/_components/installation-tab.tsx
@@ -309,7 +309,6 @@ export default function InstallationTab() {
     pluginsCode.push(formattedPlugin + ',');
   });
 
-  const hasDraggable = components.some((comp) => comp.id === 'draggable');
   const hasPlaceholder = components.some((comp) => comp.id === 'placeholder');
 
   const usageCode = [
@@ -318,11 +317,11 @@ export default function InstallationTab() {
     pluginsCode.join('\n'),
     '  ],',
     '  override: {',
-    `    components: ${hasDraggable ? 'withDraggables(' : ''}${hasPlaceholder ? 'withPlaceholders(' : ''}({`,
+    `    components: ${hasPlaceholder ? 'withPlaceholders(' : ''}({`,
     ...componentsWithPluginKey.map(
       ({ pluginKey, usage }) => `      [${pluginKey}]: ${usage},`
     ),
-    `    })${hasPlaceholder ? ')' : ''}${hasDraggable ? ')' : ''},`,
+    `    })${hasPlaceholder ? ')' : ''},`,
     '  },',
     '  value: [',
     '    {',