Merge branch 'main' into patch-1

.eslintrc.cjs

@@ -1,7 +1,7 @@
+const { filePatterns } = require('./config/eslint/constants/file-patterns.cjs');
 const {
   getDefaultIgnorePatterns,
 } = require('./config/eslint/helpers/getDefaultIgnorePatterns.cjs');
-const { filePatterns } = require('./config/eslint/constants/file-patterns.cjs');
 
 /** @type {import('eslint').Linter.Config} */
 module.exports = {
@@ -34,6 +34,7 @@ module.exports = {
     '.out',
     '**/*.mdx',
     '**/__registry__',
+    '**/scripts/build-registry.mts',
   ],
   overrides: [
     {

BREAKING_CHANGES.md

@@ -1,5 +1,28 @@
 For older changelogs, see https://github.com/udecode/plate/blob/main/docs
 
+# 39.0.0
+
+## @udecode/plate-dnd@39.0.0
+
+### Major Changes
+
+- [#3597](https://github.com/udecode/plate/pull/3597) by [@zbeyens](https://github.com/zbeyens) – The following changes were made to improve performance:
+
+  - Refactored `useDraggable` hook to focus on core dragging functionality:
+    - Removed `dropLine`. Use `useDropLine().dropLine` instead.
+    - Removed `groupProps` from the returned object – `isHovered`, and `setIsHovered` from the returned state. Use CSS instead.
+    - Removed `droplineProps`, and `gutterLeftProps` from the returned object. Use `useDropLine().props`, `useDraggableGutter().props` instead.
+
+## @udecode/plate-selection@39.0.0
+
+### Major Changes
+
+- [#3597](https://github.com/udecode/plate/pull/3597) by [@zbeyens](https://github.com/zbeyens) – The following changes were made to improve performance:
+
+  - Removed `useHooksBlockSelection` in favor of `BlockSelectionAfterEditable`
+  - Removed `slate-selected` class from `BlockSelectable`. You can do it on your components using `useBlockSelected()` instead, or by using our new `block-selection.tsx` component.
+  - Introduced `useBlockSelectableStore` for managing selectable state.
+
 # 38.0.1
 
 ## @udecode/plate-core@38.0.1

apps/www/content/docs/block-selection.mdx

@@ -7,17 +7,19 @@ description: Select and manipulate entire text blocks.
 
 <PackageInfo>
 
+The Block Selection feature allows users to select and manipulate entire text blocks, as opposed to individual words or characters. This powerful functionality enhances the editing experience by providing efficient ways to manage large sections of content.
+
 ## Features
 
-- Select entire blocks, as opposed to individual words or characters.
-- To select an entire block, mouse down outside the text area and then move the cursor into the block. Once it is selected, you'll see a background color.
-- Keep moving down or up to select multiple blocks.
-- Once selected, the available actions are: copy, cut, and delete.
-- Keyboard shortcuts:
-  - `Cmd+A` (Mac) / `Ctrl+A` (Windows/Linux): 
-    - First press: Selects the current block
-    - Double press: Selects the whole document using block selection
-  - Note: This behavior can be disabled by setting `handlers.onKeyDown = null` when creating the plugin
+- Select entire blocks with a single action
+- Multi-block selection
+- Copy, cut, and delete operations on selected blocks
+- Keyboard shortcuts for quick selection:
+  - `Cmd+A`:
+    - First press: select the current block
+    - Double press: select all blocks
+  - Arrow keys: select the block above or below
+- Customizable styling for selected blocks
 
 </PackageInfo>
 
@@ -40,7 +42,9 @@ const plugins = [
 ];
 ```
 
-## Set scrollable container
+## Configuration
+
+### Set scrollable container
 
 To control the scrollable container, configure the `boundaries` and `container` options within `areaOptions`. These options accept CSS selectors, such as `#selection-demo #scroll_container`, which are used with `document.querySelector()`.
 
@@ -64,7 +68,7 @@ Example configuration:
 
 This setup ensures that the block selection functionality is properly constrained within your designated scrollable area.
 
-## Set selectable element
+### Set selectable element
 
 Add data-plate-selectable to the container or the element you want to start block selection.
 
@@ -89,36 +93,48 @@ Example:
     />
 ```
 
-### Styling
+## Styling
 
+### Selection area
 
-#### Selection area
-You can style the selection area by adding this class to the container(.slate-selection-area can be changed in the plugin options):
+Style the selection area using `.slate-selection-area` class. For example:
 
 ```js
 '[&_.slate-selection-area]:border [&_.slate-selection-area]:border-primary [&_.slate-selection-area]:bg-primary/10'
 ```
 
-#### Selected element
+### Selected element
 
-You can style the selected element by adding this class to the container
+To determine if an element is selected, use the new `useBlockSelected` hook. You can render a visual indicator around selected blocks using our `BlockSelection` component or create your own:
 
-```js
-'[&_.slate-selected]:!bg-primary/20 '
-```
+```tsx
+import React from 'react';
+import { useBlockSelected } from '@udecode/plate-selection/react';
 
-### Disable browser default scroll behavior
-If we select some text and then move(keep pressed) the cursor to the very bottom of the page, the page will start scrolling to the bottom.
+export function BlockSelection() {
+  const isBlockSelected = useBlockSelected();
 
-Sometimes this scroll is so fast and confilicts with `BlockSelectionPlugin` scroll behavior(After the selection area appears, move the mouse to the bottom of the scroll container).
+  return (
+    <div
+      className={`pointer-events-none absolute inset-0 z-10 bg-primary/15 ${
+        isBlockSelected ? 'opacity-100' : 'opacity-0'
+      }`}
+    />
+  );
+}
+```
 
-I don't find any way to disable this scroll behavior of browser.(if you find the way to disable it, please tell me that will so appreciate it)
+This component should be rendered inside each block element for consistent selection feedback. Plate UI is doing it in `plate-element.tsx`.
 
-So the solution is add an empty `div` above the editer's right side(The right side is the easiest place to trigger this behavior.) and set `user-select: none` to it .
+### Disable browser default scroll behavior
 
-This will make configuration and maintenance cumbersome so we remove this div from plate.
+When selecting text and moving the cursor to the bottom of the page, the browser's default scroll behavior can conflict with the `BlockSelectionPlugin`. To mitigate this, you can add a non-selectable area to the right side of the editor:
 
-If you encounter this issue, you might consider disabling it in this way.
+```tsx
+<div className="absolute right-0 top-0 h-full w-4 select-none" />
+```
+
+This helps prevent unexpected scrolling during selection operations.
 
 ## Plugins
 
@@ -266,6 +282,10 @@ A wrapper component that adds block selection functionality to its children.
 
 ## Hooks
 
+### useBlockSelected
+
+Returns true if context block is selected.
+
 ### useBlockSelectableState
 
 <APIReturns>

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

@@ -8,8 +8,40 @@ 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.
 
+
+## October 2024 #15
+
+### October 1 #15.1
+
+- New `block-selection.tsx` component for visual selection feedback
+- New `plate-element.tsx` component for rendering the plate element with `BlockSelection`
+- Updated `paragraph-element.tsx` and all block elements to use `plate-element.tsx`
+- `draggable.tsx`:
+  - Refactored to use new hooks: `useDraggableGutter` and `useDropLine`
+  - Removed `classNames` prop in favor of a single `className`
+  - Added `DraggableProvider` wrapper
+  - Introduced `Gutter` and `DropLine` as separate components
+- `with-draggables.tsx`:
+  - Updated to use new className format for draggable props
+- fix `mention-element`: prevent IME input interruption on MacOS
+
+Use `--highlight` color for the following components:
+
+- `comment-leaf.tsx`
+- `highlight-leaf.tsx`
+
+Use `--brand` color for the following components:
+
+- `block-selection.tsx`
+- `draggable.tsx`
+
+
 ## September 2024 #14
 
+### September 29 #14.3
+
+- fix `heading-element`: if the heading is the first block, it should not have a top margin
+
 ### September 13 #14.2
 
 - fix `code-block-combobox`: filter based on label or value

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

@@ -3,6 +3,16 @@ title: CLI
 description: Use the CLI to add components to your project.
 ---
 
+<Callout className="mt-6">
+WIP – We're migrating to <Link href="https://ui.shadcn.com/docs/cli">npx shadcn</Link>.
+</Callout>
+
+{/* <Callout>
+
+**Note:** We are now using the `shadcn` CLI.
+
+</Callout>
+
 ## init
 
 Use the `init` command to initialize configuration and dependencies for a new project.
@@ -13,41 +23,65 @@ The `init` command installs dependencies, adds the `cn` util, configures `tailwi
 npx @udecode/plate-ui@latest init
 ```
 
-You will be asked a few questions to configure `plate-components.json`:
+You will be asked a few questions to configure `components.json`:
 
 ```txt showLineNumbers
 Which style would you like to use? › Default
 Which color would you like to use as base color? › Slate
-Where is your global CSS file? › src/style/globals.css
-Do you want to use CSS variables for colors? › no / yes
-Are you using a custom tailwind prefix eg. tw-? (Leave blank if not) ...
-Where is your tailwind.config.js located? › tailwind.config.js
-Configure the import alias for components: › @/components
-Configure the import alias for ui: › @/components/plate-ui
-Are you using React Server Components? › no / yes
+Do you want to use CSS variables for colors? › yes
+```
+
+To have the same look than Plate UI, you should:
+
+- Pick "Default" for the style. Plate does not have the "New York" style.
+- Pick "Slate" for the base color.
+- Pick "Yes" for using CSS variables.
+
+You should get something like this:
+
+```txt
+npx shadcn@latest init
+Need to install the following packages:
+[email protected]
+Ok to proceed? (y) y
+
+✔ Preflight checks.
+✔ Verifying framework. Found Next.js.
+✔ Validating Tailwind CSS.
+✔ Validating import alias.
+✔ Which style would you like to use? › Default
+✔ Which color would you like to use as the base color? › Slate
+✔ Would you like to use CSS variables for theming? … no / yes
+✔ Writing components.json.
+✔ Checking registry.
+✔ Updating tailwind.config.js
+✔ Updating src/styles/globals.css
+✔ Installing dependencies.
+✔ Created 1 file:
+  - src/lib/utils.ts
+
+Success! Project initialization completed.
+You may now add components.
 ```
 
 ### Options
 
 ```txt
-Usage: @udecode/plate-ui init [options]
+Usage: shadcn init [options] [components...]
 
 initialize your project and install dependencies
 
+Arguments:
+  components         the components to add or a url to the component.
+
 Options:
-  -y, --yes        skip confirmation prompt. (default: false)
-  -c, --cwd <cwd>  the working directory. defaults to the current directory.
+  -d, --defaults    use default values i.e new-york, zinc and css variables. (default: false)
+  -f, --force       force overwrite of existing components.json. (default: false)
+  -y, --yes         skip confirmation prompt. (default: false)
+  -c, --cwd <cwd>   the working directory. defaults to the current directory.
   -h, --help       display help for command
 ```
 
-### Add icons
-
-Add the icons you'll use in `components/icons.tsx`:
-
-<ComponentSource src="../../templates/plate-playground-template/src/components/icons.tsx" />
-
-We use icons from <Link href="https://lucide.dev">Lucide</Link>. You can use any icon library you want.
-
 ## add
 
 Use the `add` command to add components and dependencies to your project.
@@ -142,4 +176,4 @@ Options:
   -y, --yes        skip confirmation prompt. (default: false)
   -c, --cwd <cwd>  the working directory. defaults to the current directory.
   -h, --help       display help for command
-```
+``` */}

apps/www/content/docs/components/components-json.mdx

@@ -1,9 +1,13 @@
 ---
-title: plate-components.json
+title: components.json
 description: Configuration for your project.
 ---
 
-The `plate-components.json` file holds configuration for your project.
+<Callout className="mt-6">
+WIP – We're migrating to <Link href="https://ui.shadcn.com/docs/components-json">shadcn's components.json</Link>.
+</Callout>
+
+{/* The `plate-components.json` file holds configuration for your project.
 
 We use it to understand how your project is set up and how to generate components customized for your project.
 
@@ -163,4 +167,4 @@ The CLI will use this value to determine where to place your UI components. Use
     "plate-ui": "@/components/plate-ui"
   }
 }
-```
+``` */}