@openeditor/react 0.0.22 → 0.0.24

package/README.md

@@ -9,6 +9,7 @@ Pass `attachmentRuntime` to `useOpenEditorController` for editable attachments a
 - `useOpenEditorController` for editor state, commands, document exports, and selection state
 - `OpenEditorContent` for the editable Tiptap-backed content surface
 - `OpenEditorViewer` for read-only React rendering
+- `getDefaultBlockPickerItems` for host-owned block rails, pickers, and command palettes
 - `getDefaultSlashMenuItems` for UI packages that want the built-in insert actions
 - position-based block targeting and transaction-backed copy, duplicate, move, and delete commands
 - `defineOpenEditorReactNode` for consumer-owned React blocks
@@ -34,6 +35,49 @@ Pass `blockActions` to contribute product-specific actions. The optional
 Copy, Duplicate, and Delete. Clipboard copies use a versioned OpenEditor block
 envelope so blocks can move between independent editor instances and documents.
 
+## Host-owned block pickers
+
+Use `getDefaultBlockPickerItems` when blocks need to be discoverable outside the
+slash menu. The catalog contains built-in insert presets and registered custom
+blocks, but deliberately excludes slash-only actions such as moving a block or
+converting a whole document. Use `sortBlockPickerItems` when merging additional
+host-owned entries into the catalog.
+
+```tsx
+import {
+  getDefaultBlockPickerItems,
+  OpenEditorContent,
+  useOpenEditorController,
+} from "@openeditor/react";
+
+export function EditorWithBlockRail() {
+  const controller = useOpenEditorController({ extensions });
+  const items = getDefaultBlockPickerItems(controller);
+
+  return (
+    <>
+      <aside aria-label="Blocks">
+        {items.map((item) => (
+          <button
+            key={item.key}
+            onMouseDown={(event) => event.preventDefault()}
+            onClick={item.insert}
+            type="button"
+          >
+            {item.label}
+          </button>
+        ))}
+      </aside>
+      <OpenEditorContent controller={controller} />
+    </>
+  );
+}
+```
+
+`item.insert()` restores focus and inserts at the controller's current editor
+selection. Preventing the button's mouse-down default keeps the caret visibly
+anchored while the user moves from the editor to a host-owned picker.
+
 The built-in web catalog includes editable Toggle Lists, rich-content Callouts,
 and Mermaid-powered Diagrams. Diagrams use `beautiful-mermaid` for synchronous,
 themeable SVG rendering and retain their canonical Mermaid source in the document.
@@ -114,7 +158,7 @@ const productCard = defineOpenEditorReactNode({
     ],
   },
   component: ProductCardNode,
-  slashMenu: {
+  insertMenu: {
     icon: PackageOpen,
     keywords: ["product", "commerce", "card"],
     order: 250,
@@ -143,13 +187,15 @@ Pass the same extension array to `OpenEditorViewer`. The controller automaticall
 uses registered exporters for `controller.exports` and registered blocks appear
 in `getDefaultSlashMenuItems`, which powers `@openeditor/ui`.
 
-Slash-menu entries accept an optional React `icon` component and numeric `order`.
+Insert-menu entries accept an optional React `icon` component and numeric `order`.
 OpenEditor assigns built-in entries orders in increments of 100, so consumer
 blocks can be placed between them (for example, `order: 250` appears between
 Heading 1 and Heading 2). Entries with the same order retain their declaration
-order, and entries without an order appear after ordered entries. The same fields
-are available on direct `slashMenuItems`; a menu's explicit `items` prop is also
-sorted by this rule.
+order, and entries without an order appear after ordered entries. This metadata
+is shared by slash menus and `getDefaultBlockPickerItems`; use `insertMenu: false`
+to keep a block out of both discovery surfaces. The legacy `slashMenu` extension
+field remains supported. The same fields are available on direct
+`slashMenuItems`; a slash menu's explicit `items` prop is also sorted by this rule.
 
 Block `name` is the stable public identifier. Namespace consumer blocks to avoid
 collisions. `nodeType` is the serialized ProseMirror node type and defaults to

package/dist/index.d.ts

@@ -161,6 +161,22 @@ type OpenEditorSlashMenuItem = {
         range: InsertRange;
     }) => boolean;
 };
+/**
+ * An insertable block exposed to host-owned pickers and command palettes.
+ *
+ * Unlike `OpenEditorSlashMenuItem`, this contract contains only block insertion
+ * and is not coupled to a slash query range. Calling `insert` restores editor
+ * focus and inserts at the controller's current selection.
+ */
+type OpenEditorBlockPickerItem = {
+    key: string;
+    label: string;
+    group: string;
+    icon?: OpenEditorSlashMenuIcon;
+    keywords?: readonly string[];
+    order?: number;
+    insert: () => boolean;
+};
 type OpenEditorViewerRenderer = (context: {
     node: ProseMirrorNode;
     children: ReactNode;
@@ -180,6 +196,9 @@ type OpenEditorExtensionMenu = {
 type OpenEditorReactExtension = {
     block: BlockSpec;
     tiptapExtensions: readonly AnyExtension[];
+    /** Discovery metadata shared by slash menus and host-owned block pickers. */
+    insertMenu?: false | OpenEditorExtensionMenu;
+    /** @deprecated Use `insertMenu`. */
     slashMenu?: false | OpenEditorExtensionMenu;
     viewer: OpenEditorViewerRenderer;
     exporters?: OpenEditorExporters;
@@ -209,9 +228,11 @@ declare module "@tiptap/core" {
 declare const formatAttachmentSize: (size: number | null) => string;
 declare const useOpenEditorController: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
 declare const sortSlashMenuItems: (items: readonly OpenEditorSlashMenuItem[]) => OpenEditorSlashMenuItem[];
+declare const sortBlockPickerItems: (items: readonly OpenEditorBlockPickerItem[]) => OpenEditorBlockPickerItem[];
+declare const getDefaultBlockPickerItems: (controller: OpenEditorController) => OpenEditorBlockPickerItem[];
 declare const getDefaultSlashMenuItems: (controller: OpenEditorController) => OpenEditorSlashMenuItem[];
 declare const OpenEditorContent: ({ controller, className, }: OpenEditorContentProps) => react.JSX.Element;
 declare const OpenEditorViewer: ({ document, className, renderers, extensions, pageRuntime, attachmentRuntime, }: OpenEditorViewerProps) => react.JSX.Element;
 declare const useOpenEditor: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
 
-export { type InsertRange, type OpenEditorBlockAction, type OpenEditorBlockActionContext, type OpenEditorBlockTarget, OpenEditorContent, type OpenEditorContentProps, type OpenEditorController, type OpenEditorExtensionMenu, type OpenEditorOverlayRect, type OpenEditorPageRuntime, type OpenEditorPageSnapshot, type OpenEditorReactConfig, type OpenEditorReactExtension, type OpenEditorReactNodeExtension, type OpenEditorReactProps, type OpenEditorSlashMenuIcon, type OpenEditorSlashMenuIconProps, type OpenEditorSlashMenuItem, type OpenEditorTheme, OpenEditorThemeProvider, type OpenEditorThemeStyle, type OpenEditorThemeToken, OpenEditorViewer, type OpenEditorViewerProps, type OpenEditorViewerRenderer, type SelectionBubbleState, type SlashState, createOpenEditorThemeStyle, defineOpenEditorReactExtension, defineOpenEditorReactNode, formatAttachmentSize, getDefaultSlashMenuItems, openEditorThemeTokenNames, sortSlashMenuItems, useOpenEditor, useOpenEditorController, useOpenEditorThemeStyle };
+export { type InsertRange, type OpenEditorBlockAction, type OpenEditorBlockActionContext, type OpenEditorBlockPickerItem, type OpenEditorBlockTarget, OpenEditorContent, type OpenEditorContentProps, type OpenEditorController, type OpenEditorExtensionMenu, type OpenEditorOverlayRect, type OpenEditorPageRuntime, type OpenEditorPageSnapshot, type OpenEditorReactConfig, type OpenEditorReactExtension, type OpenEditorReactNodeExtension, type OpenEditorReactProps, type OpenEditorSlashMenuIcon, type OpenEditorSlashMenuIconProps, type OpenEditorSlashMenuItem, type OpenEditorTheme, OpenEditorThemeProvider, type OpenEditorThemeStyle, type OpenEditorThemeToken, OpenEditorViewer, type OpenEditorViewerProps, type OpenEditorViewerRenderer, type SelectionBubbleState, type SlashState, createOpenEditorThemeStyle, defineOpenEditorReactExtension, defineOpenEditorReactNode, formatAttachmentSize, getDefaultBlockPickerItems, getDefaultSlashMenuItems, openEditorThemeTokenNames, sortBlockPickerItems, sortSlashMenuItems, useOpenEditor, useOpenEditorController, useOpenEditorThemeStyle };

package/dist/index.js

@@ -32904,15 +32904,34 @@ var pageSnapshotFromNode = (node) => {
     href: typeof node.attrs?.href === "string" ? node.attrs.href : null
   };
 };
+var useResolvedPageSnapshot = (cached, runtime) => {
+  const [resolved, setResolved] = useState(null);
+  useEffect(() => {
+    let active = true;
+    setResolved(null);
+    if (cached?.pageId && runtime?.resolvePage) {
+      void runtime.resolvePage(cached.pageId).then((page) => {
+        if (active && page) setResolved(page);
+      }).catch(() => {
+        if (active) setResolved(null);
+      });
+    }
+    return () => {
+      active = false;
+    };
+  }, [cached?.pageId, runtime]);
+  return [resolved ?? cached, setResolved];
+};
 var OpenEditorPageNodeView = ({ editor, node, updateAttributes: updateAttributes2 }) => {
   const runtime = use(OpenEditorPageRuntimeContext);
   const themeStyle = useOpenEditorThemeStyle();
   const [creating, setCreating] = useState(false);
   const [error, setError] = useState(null);
-  const snapshot = pageSnapshotFromNode(node);
-  const icon = normalizeEmoji(node.attrs.icon, DEFAULT_PAGE_EMOJI);
+  const cached = pageSnapshotFromNode(node);
+  const [page, setResolvedPage] = useResolvedPageSnapshot(cached, runtime);
+  const icon = normalizeEmoji(page?.icon, DEFAULT_PAGE_EMOJI);
   const openPage = () => {
-    if (snapshot) void runtime?.openPage?.(snapshot);
+    if (page) void runtime?.openPage?.(page);
   };
   const createPage = async () => {
     if (!runtime?.createPage || creating) return;
@@ -32929,10 +32948,11 @@ var OpenEditorPageNodeView = ({ editor, node, updateAttributes: updateAttributes
   };
   const updateIcon = async (nextIcon) => {
     updateAttributes2({ icon: nextIcon });
-    if (!snapshot?.pageId || !runtime?.updatePageIcon) return;
+    if (!page?.pageId || !runtime?.updatePageIcon) return;
+    setResolvedPage({ ...page, icon: nextIcon });
     setError(null);
     try {
-      await runtime.updatePageIcon(snapshot.pageId, nextIcon);
+      await runtime.updatePageIcon(page.pageId, nextIcon);
     } catch (cause) {
       setError(cause instanceof Error ? cause.message : "Could not update the page icon.");
     }
@@ -32940,22 +32960,22 @@ var OpenEditorPageNodeView = ({ editor, node, updateAttributes: updateAttributes
   return /* @__PURE__ */ jsxs(
     NodeViewWrapper,
     {
-      "aria-label": snapshot ? `Open ${snapshot.title}` : void 0,
+      "aria-label": page ? `Open ${page.title}` : void 0,
       className: "oe-page",
-      "data-page-id": snapshot?.pageId ?? "",
+      "data-page-id": page?.pageId ?? "",
       onClick: (event) => {
         if (event.target.closest(".oe-emoji-trigger, .oe-emoji-popover")) return;
         openPage();
       },
       onKeyDown: (event) => {
         if (event.target.closest(".oe-emoji-trigger, .oe-emoji-popover")) return;
-        if (snapshot && (event.key === "Enter" || event.key === " ")) {
+        if (page && (event.key === "Enter" || event.key === " ")) {
           event.preventDefault();
           openPage();
         }
       },
-      role: snapshot ? "button" : void 0,
-      tabIndex: snapshot ? 0 : void 0,
+      role: page ? "button" : void 0,
+      tabIndex: page ? 0 : void 0,
       children: [
         /* @__PURE__ */ jsx("span", { contentEditable: false, children: /* @__PURE__ */ jsx(
           OpenEditorEmojiPicker,
@@ -32968,7 +32988,7 @@ var OpenEditorPageNodeView = ({ editor, node, updateAttributes: updateAttributes
             onEmojiSelect: (nextIcon) => void updateIcon(nextIcon)
           }
         ) }),
-        /* @__PURE__ */ jsx(
+        page && page !== cached ? /* @__PURE__ */ jsx("div", { className: "oe-page-title", contentEditable: false, children: page.title }) : /* @__PURE__ */ jsx(
           NodeViewContent,
           {
             as: "div",
@@ -32976,7 +32996,7 @@ var OpenEditorPageNodeView = ({ editor, node, updateAttributes: updateAttributes
             contentEditable: false
           }
         ),
-        !snapshot && runtime?.createPage && editor.isEditable ? /* @__PURE__ */ jsx(
+        !page && runtime?.createPage && editor.isEditable ? /* @__PURE__ */ jsx(
           "button",
           {
             className: "oe-page-action",
@@ -33015,20 +33035,7 @@ var Page = Node3.create({
 var OpenEditorPageViewer = ({ node }) => {
   const runtime = use(OpenEditorPageRuntimeContext);
   const cached = pageSnapshotFromNode(node);
-  const [resolved, setResolved] = useState(null);
-  useEffect(() => {
-    let active = true;
-    setResolved(null);
-    if (cached?.pageId && runtime?.resolvePage) {
-      void runtime.resolvePage(cached.pageId).then((page2) => {
-        if (active && page2) setResolved(page2);
-      });
-    }
-    return () => {
-      active = false;
-    };
-  }, [cached?.pageId, runtime]);
-  const page = resolved ?? cached;
+  const [page] = useResolvedPageSnapshot(cached, runtime);
   const title = page?.title ?? (getNodeText(node) || "Untitled");
   const content = /* @__PURE__ */ jsxs(Fragment$1, { children: [
     /* @__PURE__ */ jsx("span", { className: "oe-page-icon", "aria-hidden": "true", children: normalizeEmoji(page?.icon, DEFAULT_PAGE_EMOJI) }),
@@ -33651,12 +33658,37 @@ var useOpenEditorController = ({
   };
   return controller;
 };
-var sortSlashMenuItems = (items) => [...items].sort((left, right) => {
+var sortMenuItems = (items) => [...items].sort((left, right) => {
   const leftOrder = typeof left.order === "number" && Number.isFinite(left.order) ? left.order : Number.POSITIVE_INFINITY;
   const rightOrder = typeof right.order === "number" && Number.isFinite(right.order) ? right.order : Number.POSITIVE_INFINITY;
   if (leftOrder === rightOrder) return 0;
   return leftOrder - rightOrder;
 });
+var sortSlashMenuItems = (items) => sortMenuItems(items);
+var sortBlockPickerItems = (items) => sortMenuItems(items);
+var getExtensionInsertMenu = (extension) => extension.insertMenu ?? extension.slashMenu;
+var getDefaultBlockPickerItems = (controller) => sortBlockPickerItems([
+  ...openEditorInsertPresets.map((preset, index) => ({
+    key: preset.key,
+    label: preset.label,
+    group: preset.group,
+    keywords: [preset.key],
+    order: (index + 1) * 100,
+    insert: () => controller.insertBlock(preset.key)
+  })),
+  ...controller.extensions.filter((extension) => getExtensionInsertMenu(extension) !== false).map((extension) => {
+    const menu = getExtensionInsertMenu(extension) || void 0;
+    return {
+      key: extension.block.name,
+      label: menu?.label ?? extension.block.label,
+      group: menu?.group ?? extension.block.group,
+      icon: menu?.icon,
+      keywords: menu?.keywords ?? [extension.block.name],
+      order: menu?.order,
+      insert: () => controller.insertBlock(extension.block.name)
+    };
+  })
+]);
 var getDefaultSlashMenuItems = (controller) => {
   const internalController = controller;
   return sortSlashMenuItems([
@@ -33692,8 +33724,8 @@ var getDefaultSlashMenuItems = (controller) => {
         return true;
       }
     },
-    ...controller.extensions.filter((extension) => extension.slashMenu !== false).map((extension) => {
-      const menu = extension.slashMenu || void 0;
+    ...controller.extensions.filter((extension) => getExtensionInsertMenu(extension) !== false).map((extension) => {
+      const menu = getExtensionInsertMenu(extension) || void 0;
       return {
         key: extension.block.name,
         label: menu?.label ?? extension.block.label,
@@ -33847,6 +33879,6 @@ var OpenEditorViewer = ({
 };
 var useOpenEditor = useOpenEditorController;
 
-export { NodeViewContent, NodeViewWrapper, OpenEditorContent, DragHandle2 as OpenEditorDragHandle, OpenEditorThemeProvider, OpenEditorViewer, createOpenEditorThemeStyle, defineOpenEditorReactExtension, defineOpenEditorReactNode, formatAttachmentSize, getDefaultSlashMenuItems, openEditorThemeTokenNames, sortSlashMenuItems, useOpenEditor, useOpenEditorController, useOpenEditorThemeStyle };
+export { NodeViewContent, NodeViewWrapper, OpenEditorContent, DragHandle2 as OpenEditorDragHandle, OpenEditorThemeProvider, OpenEditorViewer, createOpenEditorThemeStyle, defineOpenEditorReactExtension, defineOpenEditorReactNode, formatAttachmentSize, getDefaultBlockPickerItems, getDefaultSlashMenuItems, openEditorThemeTokenNames, sortBlockPickerItems, sortSlashMenuItems, useOpenEditor, useOpenEditorController, useOpenEditorThemeStyle };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map