feat(core): built-in table drag visualization

docs/content/docs/react/styling-theming/overriding-css.mdx

@@ -38,6 +38,15 @@ BlockNote uses classes with the `bn-` prefix to style editor elements. Here are
 
 Menus and popovers may be portalled outside the toolbar or button that opened them. Target their own classes under `.bn-root` rather than relying on a toolbar or `.bn-container` ancestor. See [Configuring Portal Targets](/docs/react/components#configuring-portal-targets).
 
+#### Table Row & Column Dragging
+
+- `.bn-table-handle`: Row & column drag handles.
+- `.bn-table-drag-source-row` / `.bn-table-drag-source-col`: Every cell of the row/column being dragged.
+- `.bn-table-drop-cursor`: Bar marking the edge the row/column would be dropped at.
+- `.bn-table-drag-preview`: Snapshot of the row/column shown next to the cursor. It copies the editor's styling context, so normal table styles apply to it too.
+
+Set `--bn-table-drag-source-color` on the editor to customize the translucent source tint without replacing cell background colors.
+
 ### BlockNote CSS Attributes
 
 BlockNote uses data attributes to target specific block types and properties:

examples/03-ui-components/21-table-reordering-visualization/.bnexample.json

@@ -0,0 +1,12 @@
+{
+  "playground": true,
+  "docs": false,
+  "author": "must",
+  "tags": [
+    "Intermediate",
+    "UI Components",
+    "Tables",
+    "Drag & Drop",
+    "Appearance & Styling"
+  ]
+}

examples/03-ui-components/21-table-reordering-visualization/README.md

@@ -0,0 +1,53 @@
+# Table Reordering Visualization
+
+BlockNote gives table row/column dragging visual feedback out of the box: a
+snapshot of the row/column follows the cursor, the row/column being dragged is
+tinted and outlined, and a drop indicator marks where it would land.
+
+This example shows how to restyle a table - and those built-in drag
+affordances - to match your own product, using a Microsoft Loop-inspired look:
+
+- **Restyled tables**: rounded card look, muted header row, hairline
+  borders, and a row-hover highlight instead of a harsh black grid.
+- **Retuned drag affordances**: the built-in drag source highlight, drop
+  indicator and drag snapshot recolored to the same palette.
+
+## How It Works
+
+Everything here is CSS - no additional extensions or event handling.
+BlockNote's `TableHandlesExtension` owns the whole drag lifecycle and
+exposes it through classes you can target:
+
+| Class                      | What it's on                                   |
+| -------------------------- | ---------------------------------------------- |
+| `bn-table-drag-source-row` | every cell of the row being dragged            |
+| `bn-table-drag-source-col` | every cell of the column being dragged         |
+| `bn-table-drop-cursor`     | a bar on the edge the row/column would drop at |
+| `bn-table-drag-preview`    | the snapshot shown next to the cursor          |
+
+The first three are ProseMirror decorations inside the editor, so they're
+scoped under `.bn-editor [data-content-type="table"]` like any other table
+style. The snapshot lives outside the live editor, but copies its DOM styling
+context, so those same table styles apply to it. Its outer wrapper also carries
+`bn-table-drag-preview` for preview-specific overrides. The source tint uses
+`--bn-table-drag-source-color` so it layers over existing cell backgrounds.
+
+`tableStyles.css` does the restyling; `App.tsx` provides an initial table with
+`headerRows: 1` so the header styling is visible right away.
+
+## Known Limitations
+
+- **Keyboard and touch**: BlockNote's table drag handles are `draggable` +
+  `onDragStart` only today (see `TableHandle.tsx`) - there's no
+  keyboard-operable reorder path, and native HTML5 drag-and-drop isn't
+  supported on touch browsers at all. Both are gaps in BlockNote's table-drag
+  feature as a whole, not something this example introduces or fixes.
+- **Accessibility**: for the same reason, there's no keyboard focus
+  restoration to verify after a reorder - the interaction can't be reached by
+  keyboard in the first place yet.
+
+**Relevant Docs:**
+
+- [Tables](/docs/features/blocks/tables)
+- [Overriding CSS](/docs/react/styling-theming/overriding-css)
+- [Editor Setup](/docs/getting-started/editor-setup)

examples/03-ui-components/21-table-reordering-visualization/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Table Reordering Visualization</title>
+    <script>
+      <!-- AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY -->
+    </script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="./main.tsx"></script>
+  </body>
+</html>

examples/03-ui-components/21-table-reordering-visualization/main.tsx

@@ -0,0 +1,11 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import React from "react";
+import { createRoot } from "react-dom/client";
+import App from "./src/App.jsx";
+
+const root = createRoot(document.getElementById("root")!);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

examples/03-ui-components/21-table-reordering-visualization/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@blocknote/example-ui-components-table-reordering-visualization",
+  "description": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "type": "module",
+  "private": true,
+  "version": "0.12.4",
+  "scripts": {
+    "start": "vp dev",
+    "dev": "vp dev",
+    "lint": "vp lint --type-aware src main.tsx vite.config.ts",
+    "build:prod": "vp run lint && vp build",
+    "preview": "vp preview"
+  },
+  "dependencies": {
+    "@blocknote/ariakit": "latest",
+    "@blocknote/core": "latest",
+    "@blocknote/mantine": "latest",
+    "@blocknote/react": "latest",
+    "@blocknote/shadcn": "latest",
+    "@mantine/core": "^9.0.2",
+    "@mantine/hooks": "^9.0.2",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.3",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^6.0.1",
+    "vite-plus": "catalog:"
+  }
+}

examples/03-ui-components/21-table-reordering-visualization/src/App.tsx

@@ -0,0 +1,40 @@
+import "@blocknote/core/fonts/inter.css";
+import { BlockNoteView } from "@blocknote/mantine";
+import "@blocknote/mantine/style.css";
+import { useCreateBlockNote } from "@blocknote/react";
+
+import "./tableStyles.css";
+
+export default function App() {
+  const editor = useCreateBlockNote({
+    tables: {
+      splitCells: true,
+      cellBackgroundColor: true,
+      cellTextColor: true,
+      headers: true,
+    },
+    initialContent: [
+      {
+        type: "heading",
+        props: { level: 2 },
+        content: "Restyling BlockNote.js Table Reordering",
+      },
+      {
+        type: "table",
+        content: {
+          type: "tableContent",
+          columnWidths: [180, 140, 140, 220],
+          headerRows: 1,
+          rows: [
+            { cells: ["Column A", "Column B", "Column C", "Column D"] },
+            { cells: ["1a", "1b", "1c", "1d"] },
+            { cells: ["2a", "2b", "2c", "2d"] },
+            { cells: ["3a", "3b", "3c", "3d"] },
+          ],
+        },
+      },
+    ],
+  });
+
+  return <BlockNoteView editor={editor} />;
+}

examples/03-ui-components/21-table-reordering-visualization/src/tableStyles.css

@@ -0,0 +1,116 @@
+/**
+ * Palette
+ *
+ * Declared on `.bn-root` rather than on the table, for two reasons: the drag
+ * handles render in a portal outside the editor, and so does the drag
+ * snapshot - BlockNote puts `bn-root` and the active color scheme on both, so
+ * anything defined here reaches them.
+ */
+.bn-root {
+  --table-border: #e2e2ea;
+  --table-shadow: rgb(0 0 0 / 6%);
+  --table-header-bg: #f0f0f3;
+  --table-header-text: #5d5d70;
+  --table-row-hover: #d3d4e0;
+  --table-accent: #4a48b8;
+  --table-handle-hover-bg: #eef1fa;
+  --table-handle-hover-text: #5e5cd0;
+  /* Kept translucent so they read as a wash over the cell's own background
+   rather than replacing it - a flat fill light enough for this palette would
+   blot out the text in dark mode. */
+  --table-drag-tint: rgb(94 92 208 / 14%);
+  --table-drag-outline: rgb(94 92 208 / 45%);
+  --table-selected: rgb(94 92 208 / 18%);
+}
+
+.bn-root[data-color-scheme="dark"] {
+  --table-border: #3b3b46;
+  --table-shadow: rgb(0 0 0 / 40%);
+  --table-header-bg: #2c2c35;
+  --table-header-text: #a6a6bd;
+  --table-row-hover: #35353f;
+  /* The light-mode accent is a dark purple, which all but disappears against
+   the dark editor background. */
+  --table-accent: #9391ff;
+  --table-handle-hover-bg: #35354a;
+  --table-handle-hover-text: #b3b1ff;
+  --table-drag-tint: rgb(147 145 255 / 22%);
+  --table-drag-outline: rgb(147 145 255 / 55%);
+  --table-selected: rgb(147 145 255 / 25%);
+}
+
+/**
+ * Tables
+ * Loop/Notion-style card look: rounded outer border, muted header row,
+ * hairline internal grid and a hover highlight instead of the default
+ * harsh black grid lines.
+ */
+.bn-editor [data-content-type="table"] table {
+  border-collapse: separate;
+  border-spacing: 0;
+  border: 1px solid var(--table-border);
+  border-radius: 8px;
+  box-shadow: 0 1px 3px var(--table-shadow);
+  overflow: hidden;
+}
+.bn-editor [data-content-type="table"] th,
+.bn-editor [data-content-type="table"] td {
+  border: none;
+  border-right: 1px solid var(--table-border);
+  border-bottom: 1px solid var(--table-border);
+  padding: 10px 16px;
+  transition: background-color 0.15s ease;
+}
+.bn-editor [data-content-type="table"] th:last-child,
+.bn-editor [data-content-type="table"] td:last-child {
+  border-right: none;
+}
+.bn-editor [data-content-type="table"] tr:last-child th,
+.bn-editor [data-content-type="table"] tr:last-child td {
+  border-bottom: none;
+}
+.bn-editor [data-content-type="table"] th {
+  background-color: var(--table-header-bg);
+  color: var(--table-header-text);
+  font-weight: 600;
+  font-size: 0.8125em;
+  letter-spacing: 0.01em;
+}
+.bn-editor [data-content-type="table"] tr:hover > td {
+  background-color: var(--table-row-hover);
+}
+.bn-editor [data-content-type="table"] .selectedCell:after {
+  background: var(--table-selected);
+  opacity: 1;
+}
+
+/**
+ * Row/column reordering: BlockNote already highlights the row/column being
+ * dragged and marks the drop position; these just retune the built-in
+ * affordances to the palette above, so the drag state stays distinguishable
+ * from this table's own hover and selection colors.
+ */
+.bn-editor [data-content-type="table"] td.bn-table-drag-source-row,
+.bn-editor [data-content-type="table"] th.bn-table-drag-source-row,
+.bn-editor [data-content-type="table"] td.bn-table-drag-source-col,
+.bn-editor [data-content-type="table"] th.bn-table-drag-source-col {
+  --bn-table-drag-source-color: var(--table-drag-tint);
+  outline-color: var(--table-drag-outline);
+}
+.bn-editor [data-content-type="table"] .bn-table-drop-cursor {
+  background-color: var(--table-accent);
+}
+
+/* Row/column drag handles and add-row/add-column buttons. */
+.bn-mantine .bn-table-handle,
+.bn-mantine .bn-table-cell-handle {
+  border-radius: 2px;
+}
+.bn-mantine .bn-table-handle:hover,
+.bn-mantine .bn-table-handle-dragging,
+.bn-mantine .bn-table-cell-handle:hover,
+.bn-mantine .bn-extend-button:hover,
+.bn-mantine .bn-extend-button-editing {
+  background-color: var(--table-handle-hover-bg);
+  color: var(--table-handle-hover-text);
+}

examples/03-ui-components/21-table-reordering-visualization/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "__comment": "AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY",
+  "compilerOptions": {
+    "target": "ESNext",
+    "useDefineForClassFields": true,
+    "lib": ["DOM", "DOM.Iterable", "ESNext"],
+    "allowJs": false,
+    "skipLibCheck": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "composite": true
+  },
+  "include": ["."],
+  "__ADD_FOR_LOCAL_DEV_references": [
+    {
+      "path": "../../../packages/core/"
+    },
+    {
+      "path": "../../../packages/react/"
+    }
+  ]
+}

examples/03-ui-components/21-table-reordering-visualization/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite-plus/client" />

examples/03-ui-components/21-table-reordering-visualization/vite.config.ts

@@ -0,0 +1,34 @@
+// AUTO-GENERATED FILE, DO NOT EDIT DIRECTLY
+import react from "@vitejs/plugin-react";
+import * as fs from "fs";
+import * as path from "path";
+import { defineConfig } from "vite-plus";
+// https://vitejs.dev/config/
+export default defineConfig(((conf: { command: string }) => ({
+  // This example's standalone build lints its sources, unlike the workspace
+  // lint command which excludes examples.
+  lint: { ignorePatterns: [] },
+  plugins: [react()],
+  optimizeDeps: {},
+  build: {
+    sourcemap: true,
+  },
+  resolve: {
+    alias:
+      conf.command === "build" ||
+      !fs.existsSync(path.resolve(__dirname, "../../../packages/core/src"))
+        ? {}
+        : ({
+            // Comment out the lines below to load a built version of blocknote
+            // or, keep as is to load live from sources with live reload working
+            "@blocknote/core": path.resolve(
+              __dirname,
+              "../../../packages/core/src/",
+            ),
+            "@blocknote/react": path.resolve(
+              __dirname,
+              "../../../packages/react/src/",
+            ),
+          } as any),
+  },
+})) as Parameters<typeof defineConfig>[0]);

packages/core/src/editor/editor.css

@@ -59,13 +59,29 @@
   -moz-osx-font-smoothing: grayscale;
 }
 
+/* Marks the edge a dragged table row/column would be dropped at. */
 .bn-table-drop-cursor {
   position: absolute;
   z-index: 20;
   background-color: #adf;
   pointer-events: none;
 }
 
+/* Highlights the source row/column, separately from the destination cursor. */
+.bn-editor [data-content-type="table"] .bn-table-drag-source-row,
+.bn-editor [data-content-type="table"] .bn-table-drag-source-col {
+  /* A separate layer preserves the cell's own background color beneath the
+   translucent tint, in both light and dark themes. */
+  background-image: linear-gradient(
+    var(--bn-table-drag-source-color, rgb(170 221 255 / 22%)),
+    var(--bn-table-drag-source-color, rgb(170 221 255 / 22%))
+  );
+  /* An outline rather than a border, so it doesn't shift the cell's contents,
+   and inset so adjacent cells in the dragged row/column don't double it up. */
+  outline: 1.5px dashed #adf;
+  outline-offset: -1.5px;
+}
+
 .bn-editor .bn-collaboration-cursor__base {
   position: relative;
 }