@domternal/react 0.15.0 → 1.0.1

package/README.md

@@ -16,10 +16,10 @@ and React 19.
 ## Install
 
 ```bash
-pnpm add @domternal/react @domternal/core react react-dom
+pnpm add @domternal/react @domternal/core @domternal/theme react react-dom
 ```
 
-`react` (>=18), `react-dom` (>=18), and `@domternal/core` (>=0.15.0) are peer dependencies. Import the theme
+`react` (>=18), `react-dom` (>=18), and `@domternal/core` (>=1.0.0) are peer dependencies. Import the theme
 ([`@domternal/theme`](https://www.npmjs.com/package/@domternal/theme)) in your entry CSS for default styling:
 
 ```css
@@ -73,13 +73,35 @@ export default function Editor() {
 }
 ```
 
+## Options
+
+`useEditor(options, deps?)` and `<Domternal>` take the same options:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `extensions` | `AnyExtension[]` | `[]` | Extensions to load on top of `DEFAULT_EXTENSIONS`. |
+| `history` | `boolean` | `true` | Whether the built-in History extension is loaded. Turn it off when an extension brings its own undo. |
+| `content` | `Content` | `''` | Initial content, HTML string or JSON. Changing it syncs the editor. |
+| `editable` | `boolean` | `true` | Whether the editor is editable. |
+| `preset` | `'classic' \| 'notion'` | `'classic'` | `'notion'` paints `dm-notion-mode` on the `.dm-editor` host and switches preset-aware extensions to their Notion behavior. Create-time only. |
+| `autofocus` | `FocusPosition` | `false` | Where to place the caret on mount. |
+| `outputFormat` | `'html' \| 'json'` | `'html'` | Format used when comparing the `content` prop against the document. |
+| `immediatelyRender` | `boolean` | `false` | Create the editor during the first render, so `editor` is never null. Throws in SSR. |
+
+`onCreate`, `onUpdate`, `onSelectionChange`, `onFocus`, `onBlur`, and `onDestroy` callbacks are
+accepted alongside them. `<Domternal>` additionally takes `deps`, the dependency array
+`useEditor` reads as its second argument: change a value in it and the editor is rebuilt.
+
 ## Exports
 
-- **Hooks**: `useEditor`, `useEditorState` (full state or a granular selector), `useCurrentEditor`
+- **Hooks**: `useEditor`, `useEditorState` (full state or a granular selector), `useCurrentEditor`,
+  `useNotionColorPicker`
 - **Constants**: `DEFAULT_EXTENSIONS`
 - **Composable component**: `Domternal` with `Domternal.Toolbar`, `Domternal.Content`, `Domternal.BubbleMenu`,
   `Domternal.FloatingMenu`, `Domternal.EmojiPicker`, `Domternal.Loading`
 - **Components**: `DomternalEditor`, `EditorContent`, `DomternalToolbar`, `DomternalBubbleMenu`,
   `DomternalFloatingMenu`, `DomternalEmojiPicker`, `DomternalNotionColorPicker`, `EditorProvider`
 - **Node views**: `ReactNodeViewRenderer`, `NodeViewWrapper`, `NodeViewContent`, `useReactNodeView`
+- **Core re-exports**: the `Editor` class plus the `Content`, `AnyExtension`, `FocusPosition`,
+  and `JSONContent` types
 - **SSR helpers** (re-exported from core, work without an editor instance): `generateHTML`, `generateJSON`, `generateText`

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { DependencyList, ReactNode, HTMLAttributes, Ref, RefObject, KeyboardEvent, ElementType, RefCallback } from 'react';
-import { AnyExtension, Content, EditorPreset, FocusPosition, Editor, JSONContent, IconSet, ToolbarLayoutEntry, BubbleMenuOptions, FloatingMenuOptions, FloatingMenuItemsOverride, FloatingMenuKeymap } from '@domternal/core';
+import { AnyExtension, Content, EditorPreset, FocusPosition, Editor, JSONContent, IconSet, ToolbarLayoutEntry, BubbleMenuOptions, BubbleContexts, FloatingMenuOptions, FloatingMenuItemsOverride, FloatingMenuKeymap } from '@domternal/core';
 export { AnyExtension, Content, Editor, FocusPosition, GenerateHTMLOptions, GenerateJSONOptions, GenerateTextOptions, JSONContent, generateHTML, generateJSON, generateText } from '@domternal/core';
 
 declare const DEFAULT_EXTENSIONS: AnyExtension[];
@@ -177,7 +177,7 @@ interface DomternalBubbleMenuProps {
     /** Fixed item names, e.g. ['bold', 'italic', 'code']. */
     items?: string[];
     /** Context-aware: map context names to item arrays, true for all, or null to disable. */
-    contexts?: Record<string, string[] | true | null>;
+    contexts?: BubbleContexts;
     /** Custom icon overrides. Falls back to default Phosphor icons for unmapped keys. */
     icons?: IconSet;
     /** Additional content rendered after buttons. */
@@ -230,7 +230,7 @@ interface DomternalEmojiPickerProps {
     /** Array of emoji items with emoji, name, and group. */
     emojis: EmojiPickerItem[];
 }
-declare function DomternalEmojiPicker({ editor: editorProp, emojis }: DomternalEmojiPickerProps): ReactNode;
+declare function DomternalEmojiPicker({ editor: editorProp, emojis, }: DomternalEmojiPickerProps): ReactNode;
 
 interface DomternalProps extends UseEditorOptions {
     /** Optional dependency array for forced editor recreation. */

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createContext, forwardRef, useImperativeHandle, useRef, useEffect, useState, useMemo, useCallback, useSyncExternalStore, useContext, Fragment, useLayoutEffect, createElement } from 'react';
-import { Document, Paragraph, Text, BaseKeymap, History, Editor, refocusEditorAfterCommand, positionFloatingOnce, PluginKey, createFloatingMenuPlugin, FloatingMenuController, defaultIcons, positionFloating, ToolbarController, defaultBubbleContexts, createBubbleMenuPlugin } from '@domternal/core';
+import { Document, Paragraph, Text, BaseKeymap, History, Editor, refocusEditorAfterCommand, positionFloatingOnce, PluginKey, createFloatingMenuPlugin, FloatingMenuController, defaultIcons, positionFloating, ToolbarController, defaultBubbleContexts, buildBubbleItemMaps, createBubbleShouldShow, createBubbleMenuPlugin, resolveBubbleNames, resolveBubbleMenuItems } from '@domternal/core';
 export { Editor, generateHTML, generateJSON, generateText } from '@domternal/core';
 import { jsxs, jsx, Fragment as Fragment$1 } from 'react/jsx-runtime';
 import { createPortal } from 'react-dom';
@@ -947,20 +947,6 @@ var INITIAL_TRAILING_STATE = {
   currentBgColorVar: null,
   hasAnyColor: false
 };
-function isInsideTableCell($pos) {
-  for (let d = $pos.depth; d > 0; d--) {
-    const name = $pos.node(d).type.name;
-    if (name === "tableCell" || name === "tableHeader") return true;
-  }
-  return false;
-}
-function findCellNode(pos) {
-  for (let d = pos.depth; d > 0; d--) {
-    const node = pos.node(d);
-    if (node.type.name === "tableCell" || node.type.name === "tableHeader") return node;
-  }
-  return null;
-}
 function useBubbleMenu(options) {
   const { editor, shouldShow, placement = "top", offset = 8, updateDelay = 0, items, contexts: explicitContexts, icons } = options;
   const contexts = explicitContexts ?? (items ? void 0 : editor ? defaultBubbleContexts(editor) : void 0);
@@ -971,8 +957,6 @@ function useBubbleMenu(options) {
   const [trailing, setTrailing] = useState(INITIAL_TRAILING_STATE);
   const activeMapRef = useRef(/* @__PURE__ */ new Map());
   const disabledMapRef = useRef(/* @__PURE__ */ new Map());
-  const itemMapRef = useRef(/* @__PURE__ */ new Map());
-  const bubbleDefaultsRef = useRef(/* @__PURE__ */ new Map());
   const resolvedItemsRef = useRef([]);
   const editorRef = useRef(editor);
   editorRef.current = editor;
@@ -981,127 +965,8 @@ function useBubbleMenu(options) {
     const exts = editor.extensionManager.extensions;
     const hasNotionColorPicker = exts.some((e) => e.name === "notionColorPicker");
     const hasBlockContextMenu = exts.some((e) => e.name === "blockContextMenu");
-    const itemMap = /* @__PURE__ */ new Map();
-    const dropdownMap = /* @__PURE__ */ new Map();
-    for (const item of editor.toolbarItems) {
-      if (item.type === "button") {
-        itemMap.set(item.name, item);
-      } else if (item.type === "dropdown") {
-        dropdownMap.set(item.name, item);
-        for (const sub of item.items) {
-          itemMap.set(sub.name, sub);
-        }
-      }
-    }
-    itemMapRef.current = itemMap;
-    const bubbleDefaults = /* @__PURE__ */ new Map();
-    const byCtx = /* @__PURE__ */ new Map();
-    const addItem = (btn) => {
-      const ctx = btn["bubbleMenu"];
-      if (!ctx) return;
-      let arr = byCtx.get(ctx);
-      if (!arr) {
-        arr = [];
-        byCtx.set(ctx, arr);
-      }
-      arr.push(btn);
-    };
-    for (const item of editor.toolbarItems) {
-      if (item.type === "button") addItem(item);
-      else if (item.type === "dropdown") {
-        for (const sub of item.items) addItem(sub);
-      }
-    }
-    for (const [ctx, ctxItems] of byCtx) {
-      ctxItems.sort((a, b) => (b.priority ?? 100) - (a.priority ?? 100));
-      const result = [];
-      let lastGroup;
-      let sepIdx = 0;
-      for (const item of ctxItems) {
-        if (lastGroup !== void 0 && item.group !== lastGroup) {
-          result.push({ type: "separator", name: `bsep-${String(sepIdx++)}` });
-        }
-        result.push(item);
-        lastGroup = item.group;
-      }
-      bubbleDefaults.set(ctx, result);
-    }
-    bubbleDefaultsRef.current = bubbleDefaults;
-    const resolveNames = (names) => {
-      const result = [];
-      let sepIdx = 0;
-      for (const name of names) {
-        if (name === "|") {
-          result.push({ type: "separator", name: `sep-${String(sepIdx++)}` });
-        } else {
-          const dropdown = dropdownMap.get(name);
-          if (dropdown) {
-            result.push(dropdown);
-            continue;
-          }
-          const item = itemMap.get(name);
-          if (item) result.push(item);
-        }
-      }
-      return result;
-    };
-    const getFormatItems = () => {
-      return Array.from(itemMap.values()).filter((item) => item.group === "format").sort((a, b) => (b.priority ?? 100) - (a.priority ?? 100));
-    };
-    const detectContext = (selection, ctxs) => {
-      if ("$anchorCell" in selection) return null;
-      if (selection.node) return selection.node.type.name;
-      if (selection.empty) return null;
-      const fromCell = findCellNode(selection.$from);
-      if (fromCell) {
-        const toCell = findCellNode(selection.$to);
-        if (toCell && fromCell !== toCell) return null;
-        return "table";
-      }
-      const fromName = selection.$from.parent.type.name;
-      if (fromName in ctxs) return fromName;
-      if ("text" in ctxs && selection.$from.parent.type.spec.marks !== "") return "text";
-      const toName = selection.$to.parent.type.name;
-      if (toName in ctxs) return toName;
-      if ("text" in ctxs && selection.$to.parent.type.spec.marks !== "") return "text";
-      return null;
-    };
-    const filterBySchema = (contextName, schemaItems) => {
-      if (contextName === "text" || contextName === "table") return schemaItems;
-      const schema = editor.state.schema;
-      if (!schema) return schemaItems;
-      const nodeType = schema.nodes[contextName];
-      if (!nodeType) return schemaItems;
-      return schemaItems.filter((item) => {
-        const markName = typeof item.isActive === "string" ? item.isActive : null;
-        if (!markName) return true;
-        const markType = schema.marks[markName];
-        if (!markType) return true;
-        return nodeType.allowsMarkType(markType);
-      });
-    };
-    let shouldShowFn = shouldShow;
-    if (!shouldShowFn) {
-      if (contexts) {
-        shouldShowFn = ({ state }) => {
-          const context = detectContext(state.selection, contexts);
-          if (!context) return false;
-          if (context in contexts) {
-            const val = contexts[context];
-            if (val === null) return false;
-            return val === true || Array.isArray(val) && val.length > 0;
-          }
-          return bubbleDefaults.has(context);
-        };
-      } else {
-        shouldShowFn = ({ state }) => {
-          if (state.selection.empty) return false;
-          if (state.selection.node) return bubbleDefaults.has(state.selection.node.type.name);
-          if (isInsideTableCell(state.selection.$from)) return false;
-          return state.selection.$from.parent.type.spec.marks !== "" || state.selection.$to.parent.type.spec.marks !== "";
-        };
-      }
-    }
+    const maps = buildBubbleItemMaps(editor);
+    const shouldShowFn = shouldShow ?? createBubbleShouldShow(maps, contexts);
     const pluginKey = pluginKeyRef.current;
     const plugin = createBubbleMenuPlugin({
       pluginKey,
@@ -1117,13 +982,15 @@ function useBubbleMenu(options) {
       resolvedItemsRef.current = newItems;
       setResolvedItems(newItems);
     };
-    if (contexts) {
-      updateContextItems(editor, contexts, detectContext, resolveNames, getFormatItems, filterBySchema, bubbleDefaults, setItems);
-    } else if (items) {
-      setItems(resolveNames(items));
-    } else {
-      setItems(resolveNames(["bold", "italic", "underline"]));
-    }
+    const fallbackItems = resolveBubbleNames(
+      items ?? ["bold", "italic", "underline"],
+      maps.itemMap,
+      maps.dropdownMap
+    );
+    const refreshItems = (ed) => {
+      setItems(resolveBubbleMenuItems({ editor: ed, maps, contexts, fallbackItems }));
+    };
+    refreshItems(editor);
     const updateStates = (ed) => {
       let canProxy = null;
       try {
@@ -1148,7 +1015,6 @@ function useBubbleMenu(options) {
         trackButton(item);
       }
     };
-    const defaultItems = items ? resolveNames(items) : resolveNames(["bold", "italic", "underline"]);
     const syncTrailingState = (ed) => {
       const sel = ed.state.selection;
       const isNode = !!sel.node;
@@ -1185,16 +1051,7 @@ function useBubbleMenu(options) {
       });
     };
     const transactionHandler = () => {
-      if (contexts) {
-        updateContextItems(editor, contexts, detectContext, resolveNames, getFormatItems, filterBySchema, bubbleDefaults, setItems);
-      } else {
-        const sel = editor.state.selection;
-        if (sel.node && bubbleDefaults.has(sel.node.type.name)) {
-          setItems(bubbleDefaults.get(sel.node.type.name) ?? []);
-        } else {
-          setItems(defaultItems);
-        }
-      }
+      refreshItems(editor);
       updateStates(editor);
       syncTrailingState(editor);
       setActiveVersion((v) => v + 1);
@@ -1209,30 +1066,6 @@ function useBubbleMenu(options) {
       }
     };
   }, [editor]);
-  function updateContextItems(ed, ctxs, detectContext, resolveNames, getFormatItems, filterBySchema, defaults, setItems) {
-    const ctx = detectContext(ed.state.selection, ctxs);
-    if (!ctx) {
-      setItems([]);
-      return;
-    }
-    if (ctx in ctxs) {
-      const val = ctxs[ctx];
-      if (val === null || Array.isArray(val) && val.length === 0) {
-        setItems([]);
-        return;
-      }
-      if (val === true) {
-        setItems(filterBySchema(ctx, getFormatItems()));
-      } else if (Array.isArray(val)) {
-        const resolved = resolveNames(val);
-        const buttons = resolved.filter((i) => i.type !== "separator");
-        const filtered = new Set(filterBySchema(ctx, buttons).map((b) => b.name));
-        setItems(resolved.filter((i) => i.type === "separator" || filtered.has(i.name)));
-      }
-    } else {
-      setItems(defaults.get(ctx) ?? []);
-    }
-  }
   const isItemActive = (item) => {
     return activeMapRef.current.get(item.name) ?? false;
   };
@@ -1334,6 +1167,8 @@ function DomternalBubbleMenu({
   const colorBtnRef = useRef(null);
   const blockMenuBtnRef = useRef(null);
   const innerHtml = useInnerHtml();
+  const showColor = trailing.showColorPickerButton && !trailing.isNodeSelection;
+  const showBlock = trailing.showBlockMenuButton && !trailing.isNodeSelection;
   return /* @__PURE__ */ jsxs("div", { ref: menuRef, className: "dm-bubble-menu", role: "toolbar", "aria-label": "Text formatting", children: [
     resolvedItems.map((item) => {
       if (item.type === "separator") {
@@ -1383,8 +1218,8 @@ function DomternalBubbleMenu({
         btn.name
       );
     }),
-    trailing.showColorPickerButton && !trailing.isNodeSelection && /* @__PURE__ */ jsxs(Fragment$1, { children: [
-      /* @__PURE__ */ jsx("span", { className: "dm-toolbar-separator", role: "separator" }),
+    showColor && /* @__PURE__ */ jsxs(Fragment$1, { children: [
+      resolvedItems.length > 0 && /* @__PURE__ */ jsx("span", { className: "dm-toolbar-separator", role: "separator" }),
       /* @__PURE__ */ jsxs(
         "button",
         {
@@ -1420,8 +1255,8 @@ function DomternalBubbleMenu({
         }
       )
     ] }),
-    trailing.showBlockMenuButton && !trailing.isNodeSelection && /* @__PURE__ */ jsxs(Fragment$1, { children: [
-      /* @__PURE__ */ jsx("span", { className: "dm-toolbar-separator", role: "separator" }),
+    showBlock && /* @__PURE__ */ jsxs(Fragment$1, { children: [
+      (resolvedItems.length > 0 || showColor) && /* @__PURE__ */ jsx("span", { className: "dm-toolbar-separator", role: "separator" }),
       /* @__PURE__ */ jsx(
         "button",
         {
@@ -1957,10 +1792,10 @@ var CATEGORY_ICONS = {
   "Animals & Nature": "\u{1F431}",
   "Food & Drink": "\u{1F355}",
   "Travel & Places": "\u{1F697}",
-  "Activities": "\u26BD",
-  "Objects": "\u{1F4A1}",
-  "Symbols": "\u{1F523}",
-  "Flags": "\u{1F3C1}"
+  Activities: "\u26BD",
+  Objects: "\u{1F4A1}",
+  Symbols: "\u{1F523}",
+  Flags: "\u{1F3C1}"
 };
 function categoryIcon(cat) {
   return CATEGORY_ICONS[cat] ?? cat.charAt(0);
@@ -1968,7 +1803,10 @@ function categoryIcon(cat) {
 function formatName(name) {
   return name.replace(/_/g, " ");
 }
-function DomternalEmojiPicker({ editor: editorProp, emojis }) {
+function DomternalEmojiPicker({
+  editor: editorProp,
+  emojis
+}) {
   const { editor: contextEditor } = useCurrentEditor();
   const editor = editorProp ?? contextEditor;
   const {
@@ -2000,7 +1838,7 @@ function DomternalEmojiPicker({ editor: editorProp, emojis }) {
       return;
     }
     const cols = 8;
-    let next = idx;
+    let next;
     switch (event.key) {
       case "ArrowRight":
         event.preventDefault();
@@ -2261,6 +2099,14 @@ function EditorContent({ editor, innerRef, ...htmlProps }) {
     }
   );
 }
+function paletteFromExtensionOptions(options) {
+  if (typeof options !== "object" || options === null || !("palette" in options)) return [];
+  const palette = options.palette;
+  if (!Array.isArray(palette) || !palette.every((token) => typeof token === "string")) {
+    return [];
+  }
+  return [...palette];
+}
 var TOKEN_LABELS = {
   gray: "Gray",
   brown: "Brown",
@@ -2318,22 +2164,24 @@ function useNotionColorPicker(options) {
     setCurrentTextToken(attrs.colorToken ?? null);
     setCurrentBgToken(attrs.backgroundColorToken ?? null);
   }, []);
-  const close = useCallback((opts = {}) => {
-    if (!isOpenRef.current) return;
-    setIsOpen(false);
-    setStorageOpen2(false);
-    if (opts.refocus) {
-      editorRef.current?.view.focus();
-    }
-    setAnchorEl(null);
-  }, [setStorageOpen2]);
+  const close = useCallback(
+    (opts = {}) => {
+      if (!isOpenRef.current) return;
+      setIsOpen(false);
+      setStorageOpen2(false);
+      if (opts.refocus) {
+        editorRef.current?.view.focus();
+      }
+      setAnchorEl(null);
+    },
+    [setStorageOpen2]
+  );
   useEffect(() => {
     if (!editor || editor.isDestroyed) return;
     const host = editor.view.dom.closest(".dm-editor") ?? null;
     setHostEl(host);
     const ext = editor.extensionManager.extensions.find((e) => e.name === "notionColorPicker");
-    const extOptions = ext?.options ?? null;
-    setPalette(extOptions?.palette ? [...extOptions.palette] : []);
+    setPalette(paletteFromExtensionOptions(ext?.options));
     const onOpen = (...args) => {
       const detail = args[0];
       const incomingAnchor = detail?.anchorElement;
@@ -2371,35 +2219,49 @@ function useNotionColorPicker(options) {
     if (!isOpen) return;
     const controller = new AbortController();
     const { signal } = controller;
-    document.addEventListener("mousedown", (e) => {
-      const target = e.target;
-      if (!target) return;
-      if (panelRef.current?.contains(target)) return;
-      if (anchorRef.current?.contains(target)) return;
-      close({ refocus: false });
-    }, { signal });
-    document.addEventListener("keydown", (e) => {
-      if (e.key === "Escape" && isOpenRef.current) {
-        e.preventDefault();
-        close({ refocus: true });
-      }
-    }, { signal });
+    document.addEventListener(
+      "mousedown",
+      (e) => {
+        const target = e.target;
+        if (!target) return;
+        if (panelRef.current?.contains(target)) return;
+        if (anchorRef.current?.contains(target)) return;
+        close({ refocus: false });
+      },
+      { signal }
+    );
+    document.addEventListener(
+      "keydown",
+      (e) => {
+        if (e.key === "Escape" && isOpenRef.current) {
+          e.preventDefault();
+          close({ refocus: true });
+        }
+      },
+      { signal }
+    );
     return () => {
       controller.abort();
     };
   }, [isOpen, close]);
-  const applyText = useCallback((token) => {
-    const ed = editorRef.current;
-    if (!ed) return;
-    ed.commands.setTextColorToken(token);
-    syncFromSelection();
-  }, [syncFromSelection]);
-  const applyBg = useCallback((token) => {
-    const ed = editorRef.current;
-    if (!ed) return;
-    ed.commands.setBackgroundColorToken(token);
-    syncFromSelection();
-  }, [syncFromSelection]);
+  const applyText = useCallback(
+    (token) => {
+      const ed = editorRef.current;
+      if (!ed) return;
+      ed.commands.setTextColorToken(token);
+      syncFromSelection();
+    },
+    [syncFromSelection]
+  );
+  const applyBg = useCallback(
+    (token) => {
+      const ed = editorRef.current;
+      if (!ed) return;
+      ed.commands.setBackgroundColorToken(token);
+      syncFromSelection();
+    },
+    [syncFromSelection]
+  );
   const tokenLabel = useCallback((token) => {
     return TOKEN_LABELS[token] ?? token.charAt(0).toUpperCase() + token.slice(1);
   }, []);
@@ -2407,14 +2269,12 @@ function useNotionColorPicker(options) {
     const cols = 5;
     const root = panelRef.current;
     if (!root) return;
-    const swatches = Array.from(
-      root.querySelectorAll(".dm-ncp-swatch")
-    );
+    const swatches = Array.from(root.querySelectorAll(".dm-ncp-swatch"));
     if (!swatches.length) return;
     const active = document.activeElement;
     const idx = active ? swatches.indexOf(active) : -1;
     if (idx === -1) return;
-    let next = idx;
+    let next;
     switch (event.key) {
       case "ArrowRight":
         event.preventDefault();