@openeditor/react 0.0.25 → 0.0.27

package/README.md

@@ -11,7 +11,8 @@ Pass `attachmentRuntime` to `useOpenEditorController` for editable attachments a
 - `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
+- 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 +20,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
 

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 { ReactNode, CSSProperties, RefObject, ComponentType } from 'react';
+import { OpenEditorBlockRef, OpenEditorDocument, BlockSpec, ProseMirrorNode, OpenEditorAttachmentRuntime } from '@openeditor/core';
+export { OpenEditorBlockRef } from '@openeditor/core';
 import { toExportBundle, 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>>;
@@ -49,16 +58,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 +71,9 @@ type OpenEditorBlockAction = {
 };
 type OpenEditorReactConfig = OpenEditorReactProps;
 type OpenEditorController = {
-    editor: Editor | null;
     document: OpenEditorDocument;
     exports: ReturnType<typeof toExportBundle>;
+    ready: boolean;
     editable: boolean;
     placeholder: string;
     selectedBlock: string;
@@ -95,17 +97,17 @@ type OpenEditorController = {
     insertBlock: (blockName?: string, range?: InsertRange) => 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;
@@ -196,6 +198,12 @@ 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`. */
@@ -227,6 +235,23 @@ 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 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[];
@@ -235,4 +260,4 @@ declare const OpenEditorContent: ({ controller, className, }: OpenEditorContentP
 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 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, 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, useOpenEditorBlockInteraction, useOpenEditorController, useOpenEditorThemeStyle };