@openeditor/react 0.0.28 → 0.0.30

package/README.md

@@ -8,17 +8,53 @@ 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
+- `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
 
 This package intentionally does not import CSS and does not render styled menus. Use `@openeditor/ui` for the optional styled components.
 
+## Read-only rendering and URL policy
+
+`OpenEditorViewer` renders the portable document through an explicit registry of
+built-in and structural renderers. Unknown nodes are preserved for forward
+readability but carry `data-openeditor-unknown-node` so unsupported content never
+silently appears to be a fully supported block. Built-in viewer output and safe
+HTML export share stable `oe-*` classes and `data-openeditor-*` hooks for document
+semantics such as columns, tasks, toggles, callouts, tables, pages, and files.
+
+Viewer URLs use `openEditorPublicUrlPolicy` by default. The policy covers links,
+images, pages, and attachments, including snapshots returned by page and
+attachment runtimes. It accepts HTTP(S) and ordinary relative references, plus
+`mailto:` and `tel:` for text links, while rejecting executable and local-preview
+schemes. Owner previews can opt into a narrowly scoped policy:
+
+```tsx
+import {
+  OpenEditorViewer,
+  openEditorPublicUrlPolicy,
+  type OpenEditorUrlPolicy,
+} from "@openeditor/react";
+
+const previewUrlPolicy: OpenEditorUrlPolicy = (value, context) => {
+  if (context === "attachment" && value.startsWith("blob:")) return value;
+  return openEditorPublicUrlPolicy(value, context);
+};
+
+<OpenEditorViewer document={document} urlPolicy={previewUrlPolicy} />;
+```
+
+Custom viewer renderers receive both `urlPolicy` and a typed `resolveUrl` helper.
+The host remains responsible for arbitrary custom renderer output and for actions
+performed inside `openPage` or `openAttachment` callbacks.
+
 ## Block actions
 
 Every addressable node has a persistent `openeditor-id`. The block interaction
@@ -208,7 +244,11 @@ const productCard = defineOpenEditorReactNode({
     keywords: ["product", "commerce", "card"],
     order: 250,
   },
-  viewer: ({ node }) => <article>{String(node.attrs?.title ?? "")}</article>,
+  viewer: ({ node, resolveUrl }) => (
+    <article>
+      <a href={resolveUrl(node.attrs?.href, "link")}>{String(node.attrs?.title ?? "")}</a>
+    </article>
+  ),
   exporters: {
     html: {
       acmeProductCard: ({ node, escapeHtml }) =>

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, OpenEditorPageRuntime, OpenEditorAttachmentRuntime, OpenEditorPageSnapshot, OpenEditorAuthoringCapabilities } from '@openeditor/core';
-export { OpenEditorBlockRef, OpenEditorPageRuntime, OpenEditorPageSnapshot } from '@openeditor/core';
+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 { 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';
 
@@ -17,7 +17,7 @@ type OpenEditorBlockInteractionStore = {
     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"];
+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", "bodyFontSize", "bodyLineHeight", "headingFont", "headingLineHeight", "headingWeight", "heading1Size", "heading2Size", "heading3Size", "heading4Size", "heading5Size", "heading6Size"];
 type OpenEditorThemeToken = (typeof openEditorThemeTokenNames)[number];
 type OpenEditorTheme = Partial<Record<OpenEditorThemeToken, string>>;
 type OpenEditorThemeStyle = CSSProperties & Record<`--oe-${string}`, string | undefined>;
@@ -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;
@@ -65,6 +86,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 +100,7 @@ type OpenEditorController = {
     toggleTaskList: () => void;
     toggleBlockquote: () => void;
     toggleCodeBlock: () => void;
+    table: OpenEditorTableController;
     undo: () => void;
     redo: () => void;
     insertBlock: (blockName?: string, range?: InsertRange) => boolean;
@@ -100,7 +124,8 @@ type OpenEditorController = {
     attachmentRuntime?: OpenEditorAttachmentRuntime<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 +151,6 @@ type SlashState = {
     top: number;
     anchorRect?: OpenEditorOverlayRect;
 };
-type SelectionBubbleState = {
-    left: number;
-    top: number;
-    anchorRect?: OpenEditorOverlayRect;
-};
 type OpenEditorSlashMenuIconProps = {
     "aria-hidden"?: boolean;
     className?: string;
@@ -169,6 +189,8 @@ type OpenEditorBlockPickerItem = {
 type OpenEditorViewerRenderer = (context: {
     node: ProseMirrorNode;
     children: ReactNode;
+    urlPolicy: OpenEditorUrlPolicy;
+    resolveUrl: (value: unknown, context: OpenEditorUrlContext) => string | undefined;
 }) => ReactNode;
 type OpenEditorExtensionMenu = {
     label?: string;
@@ -210,6 +232,8 @@ type OpenEditorViewerProps = {
     extensions?: readonly OpenEditorReactExtension[];
     pageRuntime?: OpenEditorPageRuntime;
     attachmentRuntime?: OpenEditorAttachmentRuntime<any>;
+    /** Safe by default. Supply an explicit host policy for trusted preview URLs such as `blob:`. */
+    urlPolicy?: OpenEditorUrlPolicy;
 };
 declare module "@tiptap/core" {
     interface Commands<ReturnType> {
@@ -228,6 +252,25 @@ 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;
+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;
@@ -250,7 +293,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, }: OpenEditorViewerProps) => 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;
 
-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 };