@openeditor/react 0.0.26 → 0.0.28

package/README.md

@@ -9,9 +9,11 @@ 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
+- `OpenEditorPageHeader` for host-backed page title and icon editing
 - `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
+- stable-identity block targeting and transaction-backed copy, duplicate, move, and delete commands
+- `OpenEditorBlockDragHandle` and `useOpenEditorBlockInteraction` for headless block-handle UIs
 - `defineOpenEditorReactNode` for consumer-owned React blocks
 - `defineOpenEditorReactExtension` for advanced integrations that contribute multiple Tiptap extensions
 
@@ -19,21 +21,52 @@ This package intentionally does not import CSS and does not render styled menus.
 
 ## Block actions
 
-`controller.blockTarget` identifies the top-level block under the pointer or the
-active node selection. Mutating commands operate directly on ProseMirror
-transactions, preserving history and avoiding whole-document replacement:
+Every addressable node has a persistent `openeditor-id`. The block interaction
+snapshot publishes the stable block reference under the handle without
+putting pointer-frequency state into the editor controller. Mutating commands
+resolve that identity against the current ProseMirror document immediately
+before dispatch, preserving history and avoiding stale positions:
 
 ```tsx
-controller.selectBlock(target);
-await controller.copyBlock(target);
-controller.duplicateBlock(target);
-controller.deleteBlock(target);
+const { activeBlock } = useOpenEditorBlockInteraction(controller);
+if (activeBlock) {
+  controller.selectBlock(activeBlock);
+  await controller.copyBlock(activeBlock);
+  controller.duplicateBlock(activeBlock);
+  controller.moveBlock(1, activeBlock);
+  controller.deleteBlock(activeBlock);
+}
 ```
 
 Pass `blockActions` to contribute product-specific actions. The optional
 `OpenEditorBlockMenu` from `@openeditor/ui` combines those contributions with
-Copy, Duplicate, and Delete. Clipboard copies use a versioned OpenEditor block
-envelope so blocks can move between independent editor instances and documents.
+Move Up, Move Down, Copy, Duplicate, and Delete. Action contexts receive
+`context.block`, never a ProseMirror position or DOM rectangle. Clipboard copies
+use a versioned OpenEditor block envelope so blocks can move between independent
+editor instances and documents while receiving fresh identities.
+
+Handle ownership is structural, not inferred from pointer proximity. Callouts,
+quotes, tables, and consumer blocks own a single handle for their content by
+default. Lists, toggles, and columns expose their independent nested blocks.
+Set `blockHandle: "nested"` on a consumer extension whose child blocks should
+receive their own handles. Placement always follows the live DOM element for the
+resolved ProseMirror node, including through scrolling, resizing, and reflow.
+
+Hover targeting is owned by OpenEditor rather than the Tiptap drag-handle
+extension. The editor's interaction surface is one continuous hover region:
+content, the reserved left gutter, and the handle itself. Pointer coordinates
+resolve to the deepest structurally addressable block, with collapsed outer
+margins included so gaps between blocks do not become dead zones. A short hide
+delay lets the pointer cross from content to the handle, while pressing,
+dragging, or opening the block menu freezes the active target. Pointer movement
+is coalesced to one resolution per animation frame and identity changes are the
+only changes published to React.
+
+The gutter is part of layout, not a collision workaround. Its reservation is
+continuous rather than breakpoint-based: the editor borrows only the portion
+of the 42px gutter that physically fits to its left and reserves the remainder
+inside its width. Floating placement may correct vertical overflow but must
+never shift horizontally into block content.
 
 ## Host-owned block pickers
 
@@ -88,12 +121,24 @@ themeable SVG rendering and retain their canonical Mermaid source in the documen
 import { OpenEditorContent, useOpenEditorController } from "@openeditor/react";
 
 export function Example() {
-  const controller = useOpenEditorController();
+  const controller = useOpenEditorController({ initialDocument });
 
   return <OpenEditorContent controller={controller} />;
 }
 ```
 
+Editors are uncontrolled on both web and native. `initialDocument` is read once;
+use `controller.setContent(document)` for an undoable programmatic replacement.
+It emits `onChange` and preserves the current selection where possible. Runtime
+changes to callbacks, `editable`, and `placeholder` are applied without remounting.
+
+Exports are lazy. `controller.export("html")` returns publishing-safe built-in
+HTML. `controller.exportUnsafe("html")` opts into trusted custom extension HTML.
+
+Pass `enabledBlocks` to restrict authoring without removing nodes from the
+schema. Existing disabled blocks remain readable. Runtime-dependent insertion
+is automatically disabled unless page creation or attachment upload is wired.
+
 ## Custom blocks
 
 Custom blocks belong to the consuming product. OpenEditor hosts them without
@@ -183,8 +228,9 @@ export function ProductEditor() {
 }
 ```
 
-Pass the same extension array to `OpenEditorViewer`. The controller automatically
-uses registered exporters for `controller.exports` and registered blocks appear
+Pass the same extension array to `OpenEditorViewer`. The controller uses
+registered exporters only through the explicit `controller.exportUnsafe(...)`
+path, and registered blocks appear
 in `getDefaultSlashMenuItems`, which powers `@openeditor/ui`.
 
 Insert-menu entries accept an optional React `icon` component and numeric `order`.
@@ -193,8 +239,7 @@ 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. 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
+to keep a block out of both discovery surfaces. 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
@@ -206,19 +251,23 @@ Duplicate names and node types fail immediately during editor construction.
 
 The first-party `page` block models a Notion-style child page as a reference to
 a separately persisted document. Supply `pageRuntime` to connect creation,
-resolution, renaming, and navigation to your application:
+resolution, metadata updates, and navigation to your application:
 
 ```tsx
 const controller = useOpenEditorController({
   pageRuntime: {
     createPage: async ({ title, icon }) => api.pages.create({ title, icon }),
     resolvePage: async (pageId) => api.pages.get(pageId),
-    renamePage: async (pageId, title) => api.pages.rename(pageId, title),
+    updatePage: async (pageId, update) => api.pages.update(pageId, update),
     openPage: (page) => router.push(`/pages/${page.pageId}`),
   },
 });
 ```
 
+Render `OpenEditorPageHeader` on the opened page surface to provide the canonical
+editable title and icon. Both fields call `pageRuntime.updatePage`; page references
+resolve the same page entity instead of owning independent metadata.
+
 The document stores only the stable reference and cached presentation. Page
 contents, hierarchy, permissions, routing, and deletion remain host-owned.
 

package/dist/index.d.ts

@@ -1,13 +1,22 @@
 import * as react from 'react';
-import { ReactNode, CSSProperties, ComponentType } from 'react';
-import { OpenEditorDocument, BlockSpec, ProseMirrorNode, OpenEditorAttachmentRuntime } from '@openeditor/core';
-import { toExportBundle, OpenEditorExporters } from '@openeditor/exporters';
+import { ReactNode, CSSProperties, RefObject, ComponentType } from 'react';
+import { OpenEditorBlockRef, OpenEditorDocument, BlockSpec, ProseMirrorNode, OpenEditorPageRuntime, OpenEditorAttachmentRuntime, OpenEditorPageSnapshot, OpenEditorAuthoringCapabilities } from '@openeditor/core';
+export { OpenEditorBlockRef, OpenEditorPageRuntime, OpenEditorPageSnapshot } from '@openeditor/core';
+import { ExportFormat, OpenEditorExporters } from '@openeditor/exporters';
 export { seedDocument } from '@openeditor/extensions';
-import { Editor, AnyExtension, NodeConfig } from '@tiptap/core';
-export { DragHandle as OpenEditorDragHandle } from '@tiptap/extension-drag-handle-react';
+import { AnyExtension, NodeConfig } from '@tiptap/core';
 import { ReactNodeViewProps } from '@tiptap/react';
 export { NodeViewContent, NodeViewWrapper, ReactNodeViewProps as OpenEditorNodeViewProps } from '@tiptap/react';
 
+type OpenEditorBlockInteractionSnapshot = {
+    activeBlock: OpenEditorBlockRef | null;
+    dragging: boolean;
+};
+type OpenEditorBlockInteractionStore = {
+    getSnapshot: () => OpenEditorBlockInteractionSnapshot;
+    subscribe: (listener: () => void) => () => void;
+};
+
 declare const openEditorThemeTokenNames: readonly ["surface", "surfaceRaised", "surfaceMuted", "blockSurface", "text", "textSoft", "heading", "muted", "placeholder", "border", "borderStrong", "structuralLine", "accent", "accentText", "accentStrong", "buttonBackground", "buttonText", "codeBackground", "codeText", "link", "linkHover", "shadow", "fontSans", "fontMono", "radiusSmall", "radiusMedium", "radiusLarge", "spaceBlock", "spaceInline"];
 type OpenEditorThemeToken = (typeof openEditorThemeTokenNames)[number];
 type OpenEditorTheme = Partial<Record<OpenEditorThemeToken, string>>;
@@ -20,23 +29,7 @@ declare function OpenEditorThemeProvider({ children, className, theme }: {
     theme: OpenEditorTheme;
 }): react.JSX.Element;
 
-type OpenEditorPageSnapshot = {
-    pageId: string;
-    title: string;
-    icon?: string | null;
-    href?: string | null;
-};
-type OpenEditorPageRuntime = {
-    createPage?: (input: {
-        title: string;
-        icon?: string | null;
-    }) => Promise<OpenEditorPageSnapshot>;
-    resolvePage?: (pageId: string) => Promise<OpenEditorPageSnapshot | null>;
-    renamePage?: (pageId: string, title: string) => Promise<void> | void;
-    updatePageIcon?: (pageId: string, icon: string) => Promise<void> | void;
-    openPage?: (page: OpenEditorPageSnapshot) => Promise<void> | void;
-};
-type OpenEditorReactProps = {
+type OpenEditorReactProps = OpenEditorAuthoringCapabilities & {
     initialDocument?: OpenEditorDocument;
     editable?: boolean;
     placeholder?: string;
@@ -49,16 +42,9 @@ type OpenEditorReactProps = {
     extensions?: readonly OpenEditorReactExtension[];
     blockActions?: readonly OpenEditorBlockAction[];
 };
-type OpenEditorBlockTarget = {
-    pos: number;
-    depth: number;
-    nodeType: string;
-    blockName?: string;
-    rect: OpenEditorOverlayRect;
-};
 type OpenEditorBlockActionContext = {
     controller: OpenEditorController;
-    target: OpenEditorBlockTarget;
+    block: OpenEditorBlockRef;
 };
 type OpenEditorBlockAction = {
     id: string;
@@ -69,9 +55,10 @@ type OpenEditorBlockAction = {
 };
 type OpenEditorReactConfig = OpenEditorReactProps;
 type OpenEditorController = {
-    editor: Editor | null;
     document: OpenEditorDocument;
-    exports: ReturnType<typeof toExportBundle>;
+    export: (format: ExportFormat) => string;
+    exportUnsafe: (format: ExportFormat) => string;
+    ready: boolean;
     editable: boolean;
     placeholder: string;
     selectedBlock: string;
@@ -93,23 +80,25 @@ type OpenEditorController = {
     undo: () => void;
     redo: () => void;
     insertBlock: (blockName?: string, range?: InsertRange) => boolean;
+    isBlockEnabled: (blockName: string) => boolean;
     setLink: (url?: string | null) => void;
     getActiveLink: () => string | undefined;
-    moveSelectedBlock: (direction: -1 | 1) => void;
-    duplicateSelectedBlock: () => void;
-    deleteSelectedBlock: () => void;
-    selectBlock: (target: OpenEditorBlockTarget) => void;
-    copyBlock: (target?: OpenEditorBlockTarget) => Promise<boolean>;
-    duplicateBlock: (target?: OpenEditorBlockTarget) => boolean;
-    deleteBlock: (target?: OpenEditorBlockTarget) => boolean;
-    moveBlock: (direction: -1 | 1, target?: OpenEditorBlockTarget) => boolean;
+    selectBlock: (block: OpenEditorBlockRef) => boolean;
+    copyBlock: (block?: OpenEditorBlockRef) => Promise<boolean>;
+    duplicateBlock: (block?: OpenEditorBlockRef) => boolean;
+    deleteBlock: (block?: OpenEditorBlockRef) => boolean;
+    moveBlock: (direction: -1 | 1, block?: OpenEditorBlockRef) => boolean;
+    canMoveBlock: (direction: -1 | 1, block?: OpenEditorBlockRef) => boolean;
     blockActions: readonly OpenEditorBlockAction[];
-    blockTarget: OpenEditorBlockTarget | null;
-    setBlockTargetAt: (pos: number | null) => void;
+    blockInteraction: OpenEditorBlockInteractionStore;
+    getRootElement: () => HTMLElement | null;
+    setBlockHandleLocked: (locked: boolean) => void;
+    isActive: (name: string, attributes?: Record<string, unknown>) => boolean;
     slashMenuItems: readonly OpenEditorSlashMenuItem[];
     extensions: readonly OpenEditorReactExtension[];
     pageRuntime?: OpenEditorPageRuntime;
     attachmentRuntime?: OpenEditorAttachmentRuntime<any>;
+    enabledBlocks?: readonly string[];
     slashState: SlashState | null;
     selectionBubbleState: SelectionBubbleState | null;
 };
@@ -196,10 +185,14 @@ type OpenEditorExtensionMenu = {
 type OpenEditorReactExtension = {
     block: BlockSpec;
     tiptapExtensions: readonly AnyExtension[];
+    /**
+     * Controls ownership when this block contains other block nodes. Containers
+     * own one handle by default; use `nested` when their children are independent
+     * draggable blocks, as in column layouts.
+     */
+    blockHandle?: "self" | "nested";
     /** Discovery metadata shared by slash menus and host-owned block pickers. */
     insertMenu?: false | OpenEditorExtensionMenu;
-    /** @deprecated Use `insertMenu`. */
-    slashMenu?: false | OpenEditorExtensionMenu;
     viewer: OpenEditorViewerRenderer;
     exporters?: OpenEditorExporters;
 };
@@ -226,13 +219,38 @@ 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;
+type OpenEditorPageHeaderProps = {
+    page: OpenEditorPageSnapshot;
+    runtime: OpenEditorPageRuntime;
+    className?: string;
+    onPageChange?: (page: OpenEditorPageSnapshot) => void;
+};
+/** Canonical Notion-style page metadata editor shared by host page surfaces. */
+declare const OpenEditorPageHeader: ({ page, runtime, className, onPageChange, }: OpenEditorPageHeaderProps) => react.JSX.Element;
+declare const useOpenEditorController: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, enabledBlocks, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
+declare const useOpenEditorBlockInteraction: (controller: OpenEditorController) => OpenEditorBlockInteractionSnapshot;
+type OpenEditorBlockDragHandleProps = {
+    controller: OpenEditorController;
+    children: ReactNode;
+    className?: string;
+    ariaLabel?: string;
+    elementRef?: RefObject<HTMLDivElement | null>;
+    expanded?: boolean;
+    onActivate?: () => void;
+    onDraggingChange?: (dragging: boolean) => void;
+};
+/**
+ * Headless block handle whose outer DOM element owns both native dragging and
+ * activation. Keep visual children pointer-transparent so nested controls do
+ * not intercept the dragstart gesture.
+ */
+declare const OpenEditorBlockDragHandle: ({ controller, children, className, ariaLabel, elementRef, expanded, onActivate, onDraggingChange, }: OpenEditorBlockDragHandleProps) => react.ReactPortal | null;
 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;
+declare const useOpenEditor: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, enabledBlocks, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
 
-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 };
+export { type InsertRange, type OpenEditorBlockAction, type OpenEditorBlockActionContext, OpenEditorBlockDragHandle, type OpenEditorBlockDragHandleProps, type OpenEditorBlockPickerItem, OpenEditorContent, type OpenEditorContentProps, type OpenEditorController, type OpenEditorExtensionMenu, type OpenEditorOverlayRect, OpenEditorPageHeader, type OpenEditorPageHeaderProps, 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, useOpenEditorBlockInteraction, useOpenEditorController, useOpenEditorThemeStyle };