@openeditor/react 0.0.29 → 0.0.31

package/README.md

@@ -2,17 +2,48 @@
 
 Headless React bindings for OpenEditor's web editor runtime.
 
-Pass `attachmentRuntime` to `useOpenEditorController` for editable attachments and to `OpenEditorViewer` for identity-based resolution/opening. Progress, cancellation, retry input, and errors remain transient node-view state and are never emitted through document JSON.
+Pass `imageRuntime` and `attachmentRuntime` to `useOpenEditorController` for
+host-backed media and to `OpenEditorViewer` for identity-based URL resolution.
+Progress, cancellation, retry input, and errors remain transient node-view state
+and are never emitted through document JSON.
+
+An inserted image starts as an empty image node—never a fake placeholder URL.
+The built-in node view offers upload, drag/drop, URL embedding, replacement,
+alternative-text editing, progress, retry, and removal. The upload button is
+shown only when the host supplies `selectImage` and `uploadImage`:
+
+```tsx
+const imageRuntime = {
+  selectImage: () => chooseImageFromYourPicker(),
+  validateImage: (input) => input.size && input.size > 15_000_000
+    ? { accepted: false, message: "Image is too large." }
+    : { accepted: true },
+  uploadImage: (input, { signal, onProgress } = {}) =>
+    uploadToYourStorage(input.source, { signal, onProgress }),
+  resolveImage: (imageId, { signal } = {}) =>
+    resolveImageFromYourStorage(imageId, { signal }),
+  replaceImage: (imageId, input, options) =>
+    replaceImageInYourStorage(imageId, input.source, options),
+};
+
+const controller = useOpenEditorController({ imageRuntime });
+```
+
+`uploadImage` and `replaceImage` return an `OpenEditorImageSnapshot`. Store a
+durable `imageId`, public `src`, or both; `resolveImage` may return a temporary
+owner-preview URL such as a `blob:` URL without serializing it.
 
 ## Public surface
 
 - `useOpenEditorController` for editor state, commands, document exports, and selection state
 - `OpenEditorContent` for the editable Tiptap-backed content surface
+- `OpenEditorBubbleMenu` for Tiptap-owned selection visibility and positioning
 - `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
 - stable-identity block targeting and transaction-backed copy, duplicate, move, and delete commands
+- a first-class `controller.table` domain API for selection-aware row, column, header, cell, and table commands
 - `OpenEditorBlockDragHandle` and `useOpenEditorBlockInteraction` for headless block-handle UIs
 - `defineOpenEditorReactNode` for consumer-owned React blocks
 - `defineOpenEditorReactExtension` for advanced integrations that contribute multiple Tiptap extensions

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties, RefObject, ComponentType } from 'react';
-import { OpenEditorBlockRef, OpenEditorDocument, BlockSpec, ProseMirrorNode, OpenEditorUrlPolicy, OpenEditorUrlContext, OpenEditorPageRuntime, OpenEditorAttachmentRuntime, OpenEditorPageSnapshot, OpenEditorAuthoringCapabilities } from '@openeditor/core';
-export { OpenEditorBlockRef, OpenEditorPageRuntime, OpenEditorPageSnapshot, OpenEditorUrlContext, OpenEditorUrlPolicy, openEditorPublicUrlPolicy, openEditorUnsafeUrlPolicy } from '@openeditor/core';
+import { OpenEditorBlockRef, OpenEditorDocument, BlockSpec, ProseMirrorNode, OpenEditorUrlPolicy, OpenEditorUrlContext, OpenEditorPageRuntime, OpenEditorAttachmentRuntime, OpenEditorImageRuntime, OpenEditorPageSnapshot, OpenEditorAuthoringCapabilities } from '@openeditor/core';
+export { OpenEditorBlockRef, OpenEditorImageRuntime, OpenEditorImageSnapshot, OpenEditorImageUploadInput, OpenEditorPageRuntime, OpenEditorPageSnapshot, OpenEditorUrlContext, OpenEditorUrlPolicy, openEditorPublicUrlPolicy, openEditorUnsafeUrlPolicy } from '@openeditor/core';
 import { ExportFormat, OpenEditorExporters } from '@openeditor/exporters';
 export { seedDocument } from '@openeditor/extensions';
-import { AnyExtension, NodeConfig } from '@tiptap/core';
+import { Editor, AnyExtension, NodeConfig } from '@tiptap/core';
 import { ReactNodeViewProps } from '@tiptap/react';
 export { NodeViewContent, NodeViewWrapper, ReactNodeViewProps as OpenEditorNodeViewProps } from '@tiptap/react';
 
@@ -29,6 +29,27 @@ declare function OpenEditorThemeProvider({ children, className, theme }: {
     theme: OpenEditorTheme;
 }): react.JSX.Element;
 
+declare const openEditorTableCommands: readonly ["addRowBefore", "addRowAfter", "deleteRow", "addColumnBefore", "addColumnAfter", "deleteColumn", "toggleHeaderRow", "toggleHeaderColumn", "mergeCells", "splitCell", "deleteTable"];
+type OpenEditorTableCommand = (typeof openEditorTableCommands)[number];
+type OpenEditorTableState = {
+    active: boolean;
+    rows: number;
+    columns: number;
+    headerRow: boolean;
+    headerColumn: boolean;
+    cellSelection: boolean;
+    canMergeCells: boolean;
+    canSplitCell: boolean;
+};
+type OpenEditorTableController = {
+    getState: () => OpenEditorTableState;
+    can: (command: OpenEditorTableCommand) => boolean;
+    run: (command: OpenEditorTableCommand) => boolean;
+};
+declare const getOpenEditorTableState: (editor: Editor | null) => OpenEditorTableState;
+declare const canRunOpenEditorTableCommand: (editor: Editor | null, command: OpenEditorTableCommand) => boolean;
+declare const runOpenEditorTableCommand: (editor: Editor | null, command: OpenEditorTableCommand) => boolean;
+
 type OpenEditorReactProps = OpenEditorAuthoringCapabilities & {
     initialDocument?: OpenEditorDocument;
     editable?: boolean;
@@ -37,6 +58,7 @@ type OpenEditorReactProps = OpenEditorAuthoringCapabilities & {
     onFilePasteDrop?: (file: File) => boolean;
     pageRuntime?: OpenEditorPageRuntime;
     attachmentRuntime?: OpenEditorAttachmentRuntime<any>;
+    imageRuntime?: OpenEditorImageRuntime<any>;
     slashMenuItems?: readonly OpenEditorSlashMenuItem[];
     /** Consumer-owned blocks. Extension names and node types must be unique. */
     extensions?: readonly OpenEditorReactExtension[];
@@ -65,6 +87,8 @@ type OpenEditorController = {
     setSelectedBlock: (blockName: string) => void;
     getContent: () => OpenEditorDocument;
     setContent: (document: OpenEditorDocument) => void;
+    focus: () => void;
+    getPositionRect: (position: number) => OpenEditorOverlayRect | null;
     setParagraph: () => void;
     toggleHeading: (level: 1 | 2 | 3 | 4 | 5 | 6) => void;
     toggleBold: () => void;
@@ -77,6 +101,7 @@ type OpenEditorController = {
     toggleTaskList: () => void;
     toggleBlockquote: () => void;
     toggleCodeBlock: () => void;
+    table: OpenEditorTableController;
     undo: () => void;
     redo: () => void;
     insertBlock: (blockName?: string, range?: InsertRange) => boolean;
@@ -98,9 +123,11 @@ type OpenEditorController = {
     extensions: readonly OpenEditorReactExtension[];
     pageRuntime?: OpenEditorPageRuntime;
     attachmentRuntime?: OpenEditorAttachmentRuntime<any>;
+    imageRuntime?: OpenEditorImageRuntime<any>;
     enabledBlocks?: readonly string[];
     slashState: SlashState | null;
-    selectionBubbleState: SelectionBubbleState | null;
+    dismissSlashMenu: () => void;
+    registerSlashMenuKeyboardHandler: (handler: (event: globalThis.KeyboardEvent) => boolean) => () => void;
 };
 type OpenEditorContentProps = {
     controller: OpenEditorController;
@@ -126,11 +153,6 @@ type SlashState = {
     top: number;
     anchorRect?: OpenEditorOverlayRect;
 };
-type SelectionBubbleState = {
-    left: number;
-    top: number;
-    anchorRect?: OpenEditorOverlayRect;
-};
 type OpenEditorSlashMenuIconProps = {
     "aria-hidden"?: boolean;
     className?: string;
@@ -212,6 +234,7 @@ type OpenEditorViewerProps = {
     extensions?: readonly OpenEditorReactExtension[];
     pageRuntime?: OpenEditorPageRuntime;
     attachmentRuntime?: OpenEditorAttachmentRuntime<any>;
+    imageRuntime?: OpenEditorImageRuntime<any>;
     /** Safe by default. Supply an explicit host policy for trusted preview URLs such as `blob:`. */
     urlPolicy?: OpenEditorUrlPolicy;
 };
@@ -231,7 +254,26 @@ type OpenEditorPageHeaderProps = {
 };
 /** 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 useOpenEditorController: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, imageRuntime, enabledBlocks, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
+type OpenEditorBubbleMenuProps = {
+    controller: OpenEditorController;
+    children: ReactNode;
+    className?: string;
+    container?: HTMLElement | null;
+    scrollTarget?: HTMLElement | Window | null;
+    style?: CSSProperties;
+};
+type OpenEditorTableBubbleMenuProps = {
+    controller: OpenEditorController;
+    children: (state: OpenEditorTableState) => ReactNode;
+    className?: string;
+    container?: HTMLElement | null;
+    style?: CSSProperties;
+};
+/** Selection-aware positioning and lifecycle owned by Tiptap's BubbleMenu plugin. */
+declare const OpenEditorBubbleMenu: ({ controller, children, className, container, scrollTarget, style, }: OpenEditorBubbleMenuProps) => react.JSX.Element | null;
+/** A table-owned contextual surface, anchored to the complete selected table. */
+declare const OpenEditorTableBubbleMenu: ({ controller, children, className, container, style, }: OpenEditorTableBubbleMenuProps) => react.JSX.Element | null;
 declare const useOpenEditorBlockInteraction: (controller: OpenEditorController) => OpenEditorBlockInteractionSnapshot;
 type OpenEditorBlockDragHandleProps = {
     controller: OpenEditorController;
@@ -254,7 +296,7 @@ declare const sortBlockPickerItems: (items: readonly 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, urlPolicy, }: OpenEditorViewerProps) => react.JSX.Element;
-declare const useOpenEditor: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, enabledBlocks, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
+declare const OpenEditorViewer: ({ document, className, renderers, extensions, pageRuntime, attachmentRuntime, imageRuntime, urlPolicy, }: OpenEditorViewerProps) => react.JSX.Element;
+declare const useOpenEditor: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, imageRuntime, enabledBlocks, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
 
-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 };
+export { type InsertRange, type OpenEditorBlockAction, type OpenEditorBlockActionContext, OpenEditorBlockDragHandle, type OpenEditorBlockDragHandleProps, type OpenEditorBlockPickerItem, OpenEditorBubbleMenu, type OpenEditorBubbleMenuProps, 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, OpenEditorTableBubbleMenu, type OpenEditorTableBubbleMenuProps, type OpenEditorTableCommand, type OpenEditorTableController, type OpenEditorTableState, type OpenEditorTheme, OpenEditorThemeProvider, type OpenEditorThemeStyle, type OpenEditorThemeToken, OpenEditorViewer, type OpenEditorViewerProps, type OpenEditorViewerRenderer, type SlashState, canRunOpenEditorTableCommand, createOpenEditorThemeStyle, defineOpenEditorReactExtension, defineOpenEditorReactNode, formatAttachmentSize, getDefaultBlockPickerItems, getDefaultSlashMenuItems, getOpenEditorTableState, openEditorTableCommands, openEditorThemeTokenNames, runOpenEditorTableCommand, sortBlockPickerItems, sortSlashMenuItems, useOpenEditor, useOpenEditorBlockInteraction, useOpenEditorController, useOpenEditorThemeStyle };