Merge pull request #3616 from udecode/refactor/selection

BlockMenuPlugin

.changeset/afraid-coins-share.md

@@ -0,0 +1,5 @@
+---
+'@udecode/plate-ai': patch
+---
+
+WIP

.changeset/great-bottles-exist.md

@@ -0,0 +1,7 @@
+---
+'@udecode/plate-floating': patch
+---
+
+- `getSelectionBoundingClientRect` is now returning the bounding client rect of the editor selection instead of the dom selection. This is more robust for cases like floating toolbar.
+- Update floating toolbar position on value change, in addition to selection change.
+- Return `clickOutsideRef` from `useFloatingToolbar` so it can be used to close the toolbar when clicking outside of it. Use `ignore-click-outside/toolbar` class to ignore clicks outside of the toolbar.

.changeset/honest-lamps-work.md

@@ -0,0 +1,5 @@
+---
+'@udecode/slate-react': patch
+---
+
+- Add `setNode`

.changeset/lovely-ads-push.md

@@ -0,0 +1,17 @@
+---
+'@udecode/plate-selection': minor
+---
+
+- Add `useBlockSelectionNodes`, `useBlockSelectionFragment`, `useBlockSelectionFragmentProp`
+- `BlockSelectionPlugin`:
+  - Make `setSelectedIds` options optional
+  - Rename option `getSelectedBlocks` -> `getNodes`
+  - Extend api: `duplicate`, `removeNodes`, `select`, `setNodes`, `setTexts`
+- Rename `BlockContextMenuPlugin` to `BlockMenuPlugin`
+- `BlockMenuPlugin` options:
+  - `position`
+  - `openId`
+- `BlockMenuPlugin` api:
+  - `hide`
+  - `show`
+  - `showContextMenu`

.changeset/quick-swans-repeat.md

@@ -0,0 +1,9 @@
+---
+'@udecode/plate-core': patch
+---
+
+`PlateContent`:
+
+- When `disabled=true`, `readOnly` should be `true`
+- Add prop `aria-disabled=true` and `data-readonly=true` when `readOnly=true`
+- Add class `slate-editor`, `ignore-click-outside/toolbar` (used by floating toolbar)

.changeset/rotten-hornets-fly.md

@@ -0,0 +1,7 @@
+---
+'@udecode/plate-utils': patch
+---
+
+- Update `useMarkToolbarButton().props.onClick`: focus editor after toggle mark
+- Add `useSelectionCollapsed`, `useSelectionExpanded`, `useSelectionWithinBlock`, `useSelectionAcrossBlocks`
+- Add `useSelectionFragment`, `useSelectionFragmentProp`

.changeset/serious-baboons-study.md

@@ -0,0 +1,7 @@
+---
+'@udecode/slate-utils': patch
+---
+
+- Add queries `getBlocks`, `getFragmentProp`, `getSelectionFragment`
+- Add transforms `duplicateBlocks`, `removeEmptyPreviousBlock`, `selectNodes`, `setBlockAboveNode`, `setBlockNodes`
+- Add utils `unwrapStructuralNodes`

.changeset/sixty-wombats-roll.md

@@ -0,0 +1,5 @@
+---
+'@udecode/plate-link': patch
+---
+
+Floating patch

apps/www/content/docs/api/core.mdx

@@ -308,6 +308,91 @@ Get the version of the editor selection. That version is incremented on each sel
 </APIParameters>
 <APIReturns>The current version of the editor selection.</APIReturns>
 
+### useSelectionCollapsed
+
+Returns whether the current selection is collapsed (i.e., the selection is a single point).
+
+<APIReturns>
+  A boolean value indicating if the selection is collapsed.
+</APIReturns>
+
+### useSelectionExpanded
+
+Returns whether the current selection is expanded (i.e., the selection has a non-zero range).
+
+<APIReturns>
+  A boolean value indicating if the selection is expanded.
+</APIReturns>
+
+### useSelectionWithinBlock
+
+Returns whether the current selection is within a single block.
+
+<APIReturns>
+  A boolean value indicating if the selection is within a single block.
+</APIReturns>
+
+### useSelectionAcrossBlocks
+
+Returns whether the current selection spans across multiple blocks.
+
+<APIReturns>
+  A boolean value indicating if the selection spans across multiple blocks.
+</APIReturns>
+
+### useSelectionFragment
+
+Returns the fragment of the current selection, optionally unwrapping structural nodes.
+
+<APIParameters>
+  <APIItem name="options" type="GetSelectionFragmentOptions" optional>
+    Options for getting the selection fragment.
+    <APISubList>
+      <APISubListItem parent="options" name="structuralTypes" type="string[]" optional>
+        Array of structural types to unwrap from the fragment.
+      </APISubListItem>
+    </APISubList>
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  An array of `TElement` representing the fragment of the current selection. Returns an empty array if the selection is not expanded or if no fragment is found.
+</APIReturns>
+
+### useSelectionFragmentProp
+
+Returns a prop value derived from the current selection fragment.
+
+<APIParameters>
+  <APIItem name="options" type="GetSelectionFragmentOptions & GetFragmentPropOptions" optional>
+    <APISubList>
+      <APISubListItem parent="options" name="structuralTypes" type="string[]" optional>
+        Array of structural types to unwrap from the fragment.
+      </APISubListItem>
+      <APISubListItem parent="options" name="key" type="string" optional>
+        The key of the property to extract from each node.
+      </APISubListItem>
+      <APISubListItem parent="options" name="defaultValue" type="string" optional>
+        The default value to return if no valid prop is found.
+      </APISubListItem>
+      <APISubListItem parent="options" name="getProp" type="(node: TElement | TText) => any" optional>
+        Custom function to extract the prop value from a node.
+      </APISubListItem>
+      <APISubListItem parent="options" name="mode" type="'all' | 'block' | 'text'" optional>
+        Determines how to traverse the fragment:
+        - 'all': Check both block and text nodes
+        - 'block': Only check block nodes
+        - 'text': Only check text nodes
+        Default is 'block'.
+      </APISubListItem>
+    </APISubList>
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  A value derived from the fragment nodes, or undefined if no consistent value is found across the specified nodes.
+</APIReturns>
+
 ## Core plugins
 
 ### DebugPlugin

apps/www/content/docs/api/slate-react.mdx

@@ -58,3 +58,44 @@ Find the corresponding documentation in the <Link href="https://docs.slatejs.org
 ### `toSlatePoint`
 
 ### `toSlateRange`
+
+## Transforms
+
+### focusEditorEdge
+
+Focuses the editor at a specified edge (start or end).
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor instance.
+  </APIItem>
+  <APIItem name="options" type="object" optional>
+    <APISubList>
+      <APISubListItem parent="options" name="edge" type="'start' | 'end'" optional>
+        The edge to focus on. 
+        - 'start': Focus at the beginning of the editor.
+        - 'end': Focus at the end of the editor.
+        Default is 'start'.
+      </APISubListItem>
+    </APISubList>
+  </APIItem>
+</APIParameters>
+
+### setNode
+
+Sets properties on a specific node in the editor.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor instance.
+  </APIItem>
+  <APIItem name="node" type="NodeOf<E>">
+    The node to update.
+  </APIItem>
+  <APIItem name="props" type="Partial<TNodeProps<N>>">
+    The properties to set on the node.
+  </APIItem>
+  <APIItem name="options" type="Omit<SetNodesOptions<E>, 'at'>" optional>
+    Options for setting nodes, excluding the 'at' property.
+  </APIItem>
+</APIParameters>

apps/www/content/docs/api/slate-utils.mdx

@@ -45,6 +45,23 @@ Returns the block above the specified location.
 
 </APIReturns>
 
+### getBlocks
+
+Retrieves block-level node entries from the editor.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor to search for block-level nodes.
+  </APIItem>
+  <APIItem name="options" type="GetNodeEntriesOptions<E>" optional>
+    Options for getting node entries.
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  An array of block-level node entries.
+</APIReturns>
+
 ### getChildren
 
 Returns the children node entries of a node entry.
@@ -79,6 +96,40 @@ Returns the edge blocks above a specified location.
   location, or `null` if not found.
 </APIReturns>
 
+### getFragmentProp
+
+Retrieves a consistent property value from a fragment of nodes.
+
+<APIParameters>
+  <APIItem name="fragment" type="TElement[]">
+    The fragment of nodes to search for the property.
+  </APIItem>
+  <APIItem name="options" type="GetFragmentPropOptions" optional>
+    <APISubList>
+      <APISubListItem parent="options" name="key" type="string" optional>
+        The key of the property to extract from each node.
+      </APISubListItem>
+      <APISubListItem parent="options" name="defaultValue" type="string" optional>
+        The default value to return if no valid prop is found.
+      </APISubListItem>
+      <APISubListItem parent="options" name="getProp" type="(node: TElement | TText) => any" optional>
+        Custom function to extract the prop value from a node.
+      </APISubListItem>
+      <APISubListItem parent="options" name="mode" type="'all' | 'block' | 'text'" optional>
+        Determines how to traverse the fragment:
+        - 'all': Check both block and text nodes
+        - 'block': Only check block nodes
+        - 'text': Only check text nodes
+        Default is 'block'.
+      </APISubListItem>
+    </APISubList>
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  The consistent property value found in the fragment, or undefined if no consistent value is found.
+</APIReturns>
+
 ### getLastChild
 
 Returns the last child of a node or `null` if no children.
@@ -356,6 +407,27 @@ Gets the range from the start of the block above a location to the location.
   `undefined` if no such block exists.
 </APIReturns>
 
+### getSelectionFragment
+
+Retrieves the fragment of the current selection, optionally unwrapping structural nodes.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor to get the selection fragment from.
+  </APIItem>
+  <APIItem name="options" type="GetSelectionFragmentOptions" optional>
+    <APISubList>
+      <APISubListItem parent="options" name="structuralTypes" type="string[]" optional>
+        Array of structural types to unwrap from the fragment.
+      </APISubListItem>
+    </APISubList>
+  </APIItem>
+</APIParameters>
+
+<APIReturns>
+  An array of `TElement` representing the fragment of the current selection. Returns an empty array if the selection is not expanded or if no fragment is found.
+</APIReturns>
+
 ### getSelectionText
 
 Gets the selected text from the editor.
@@ -635,6 +707,19 @@ Queries the editor state.
 
 ## Transforms
 
+### duplicateBlocks
+
+Duplicates the given blocks and inserts them after the last block in the selection.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor instance.
+  </APIItem>
+  <APIItem name="blocks" type="TNodeEntry[]">
+    An array of node entries representing the blocks to duplicate.
+  </APIItem>
+</APIParameters>
+
 ### insertElements
 
 Inserts nodes at a location in the document.
@@ -750,6 +835,67 @@ Selects the end point of the block above the selection.
   </APIItem>
 </APIParameters>
 
+### selectNodes
+
+Selects the range encompassing the given nodes.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor instance.
+  </APIItem>
+  <APIItem name="nodes" type="TNodeEntry[]">
+    An array of node entries to select.
+  </APIItem>
+</APIParameters>
+
+### setBlockAboveNode
+
+Sets properties on the block above the current selection.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor instance.
+  </APIItem>
+  <APIItem name="props" type="Partial<TNodeProps<N>>">
+    The properties to set on the block.
+  </APIItem>
+  <APIItem name="options" type="Omit<SetNodesOptions<E>, 'at'>" optional>
+    Options for setting nodes, excluding the 'at' property.
+  </APIItem>
+</APIParameters>
+
+### setBlockAboveTexts
+
+Sets properties on the lowest-level nodes within the block above the current selection.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor instance.
+  </APIItem>
+  <APIItem name="props" type="Partial<TNodeProps<N>>">
+    The properties to set on the text nodes.
+  </APIItem>
+  <APIItem name="options" type="Omit<SetNodesOptions<E>, 'at'>" optional>
+    Options for setting nodes, excluding the 'at' property.
+  </APIItem>
+</APIParameters>
+
+### setBlockNodes
+
+Sets properties on all block nodes that match the given options.
+
+<APIParameters>
+  <APIItem name="editor" type="TEditor">
+    The editor instance.
+  </APIItem>
+  <APIItem name="props" type="Partial<TNodeProps<N>>">
+    The properties to set on the matching block nodes.
+  </APIItem>
+  <APIItem name="options" type="GetNodeEntriesOptions<E>" optional>
+    Options for getting node entries to update.
+  </APIItem>
+</APIParameters>
+
 ### setMarks
 
 Sets marks to selected text.