@openeditor/react 0.0.27 → 0.0.29

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
+- `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
@@ -18,6 +19,40 @@ Pass `attachmentRuntime` to `useOpenEditorController` for editable attachments a
 
 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
@@ -120,12 +155,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
@@ -195,7 +242,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 }) =>
@@ -215,8 +266,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`.
@@ -225,8 +277,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
@@ -238,19 +289,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,8 +1,8 @@
 import * as react from 'react';
 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';
+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 { ReactNodeViewProps } 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,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;
@@ -72,7 +56,8 @@ type OpenEditorBlockAction = {
 type OpenEditorReactConfig = OpenEditorReactProps;
 type OpenEditorController = {
     document: OpenEditorDocument;
-    exports: ReturnType<typeof toExportBundle>;
+    export: (format: ExportFormat) => string;
+    exportUnsafe: (format: ExportFormat) => string;
     ready: boolean;
     editable: boolean;
     placeholder: string;
@@ -95,6 +80,7 @@ type OpenEditorController = {
     undo: () => void;
     redo: () => void;
     insertBlock: (blockName?: string, range?: InsertRange) => boolean;
+    isBlockEnabled: (blockName: string) => boolean;
     setLink: (url?: string | null) => void;
     getActiveLink: () => string | undefined;
     selectBlock: (block: OpenEditorBlockRef) => boolean;
@@ -112,6 +98,7 @@ type OpenEditorController = {
     extensions: readonly OpenEditorReactExtension[];
     pageRuntime?: OpenEditorPageRuntime;
     attachmentRuntime?: OpenEditorAttachmentRuntime<any>;
+    enabledBlocks?: readonly string[];
     slashState: SlashState | null;
     selectionBubbleState: SelectionBubbleState | null;
 };
@@ -182,6 +169,8 @@ type OpenEditorBlockPickerItem = {
 type OpenEditorViewerRenderer = (context: {
     node: ProseMirrorNode;
     children: ReactNode;
+    urlPolicy: OpenEditorUrlPolicy;
+    resolveUrl: (value: unknown, context: OpenEditorUrlContext) => string | undefined;
 }) => ReactNode;
 type OpenEditorExtensionMenu = {
     label?: string;
@@ -206,8 +195,6 @@ type OpenEditorReactExtension = {
     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;
 };
@@ -225,6 +212,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> {
@@ -234,7 +223,15 @@ 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;
@@ -257,7 +254,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 useOpenEditor: ({ initialDocument, editable, placeholder, onChange, onFilePasteDrop, pageRuntime, attachmentRuntime, slashMenuItems, extensions, blockActions, }?: OpenEditorReactProps) => OpenEditorController;
+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, 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 };
+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 };