@octanejs/tiptap 0.0.1 → 0.0.3

package/README.md

@@ -28,7 +28,7 @@ export function RichTextEditor() @{
 
 ## Current scope
 
-The initial binding includes:
+The binding includes:
 
 - `useEditor`, including create/update/recreate and deferred-destroy lifecycle
   behavior;
@@ -36,21 +36,33 @@ The initial binding includes:
   bailout behavior;
 - `EditorContext`, `EditorProvider`, `EditorConsumer`, and `useCurrentEditor`;
 - `EditorContent` / `PureEditorContent` for adopting, switching, resetting, and
-  exposing the DOM of a normal `@tiptap/core` editor; and
-- `Tiptap`, `Tiptap.Content`, `useTiptap`, and `useTiptapState`.
-
-The portal bridge required by custom Octane NodeViews and MarkViews is the next
-stage. `ReactRenderer`, `ReactNodeViewRenderer`, `ReactMarkViewRenderer`,
-`useReactNodeView`, the NodeView wrapper/content components, and the `./menus`
-entry are therefore not part of this release yet. In particular, importing
-`@octanejs/tiptap/menus` is intentionally unsupported until `BubbleMenu` and
-`FloatingMenu` have working Octane implementations.
-
-On the server, editor construction is suppressed and hook snapshots use a `null`
-editor. Set `immediatelyRender: false` when the editor should remain nullable
-through the initial client render as well. The binding's SSR and hydration suite
-verifies deferred server output, adoption of the existing host DOM, and creation
-of the live editor after hydration.
+  exposing an editor DOM while owning its portal registry;
+- `Tiptap`, `Tiptap.Content`, `useTiptap`, and `useTiptapState`;
+- `ReactRenderer`, `ReactNodeViewRenderer`, `ReactMarkViewRenderer`,
+  `useReactNodeView`, and the NodeView/MarkView wrapper and content components
+  for custom Octane editor views; and
+- `BubbleMenu` and `FloatingMenu` from the `@octanejs/tiptap/menus` subpath.
+
+The public names follow `@tiptap/react` so existing TipTap extensions can keep
+their renderer declarations while their components move to Octane. Despite the
+compatibility names, the implementation does not install or render through
+React.
+
+For the pinned 3.28.0 release, the root and `./menus` runtime export surfaces
+match `@tiptap/react`. Package-boundary tests lock those exports and the client
+module directives, while shared-fixture differential tests exercise the same
+editor and custom-view components through both bindings.
+
+On the server, editor construction is suppressed, hook snapshots use a `null`
+editor, and menu portals emit no detached target. Set `immediatelyRender: false`
+when the editor should remain nullable through the initial client render as
+well. The binding's SSR and hydration suite verifies deferred server output,
+adoption of the existing host DOM, and creation of the live editor after
+hydration.
+
+Real-browser coverage complements the jsdom suite for contracts that require a
+layout engine: caret-preserving input, text selection, NodeView dragging, and
+BubbleMenu/FloatingMenu visibility and positioning.
 
 ## Status
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/tiptap",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -21,7 +21,7 @@
       }
     }
   },
-  "description": "TipTap bindings for the Octane renderer — reuses @tiptap/core and @tiptap/pm and ports the React editor lifecycle, state subscriptions, contexts, content surface, and compound TipTap API onto Octane.",
+  "description": "TipTap bindings for Octane, including editor hooks and contexts, EditorContent, custom node and mark views, and floating menus without a React runtime dependency.",
   "author": {
     "name": "Dominic Gannaway",
     "email": "dg@domgan.com"
@@ -42,15 +42,20 @@
     "README.md"
   ],
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./menus": "./src/menus/index.ts"
   },
   "dependencies": {
     "@tiptap/core": "3.28.0",
     "@tiptap/pm": "3.28.0",
     "fast-equals": "^5.3.3"
   },
+  "optionalDependencies": {
+    "@tiptap/extension-bubble-menu": "3.28.0",
+    "@tiptap/extension-floating-menu": "3.28.0"
+  },
   "peerDependencies": {
-    "octane": "0.1.7"
+    "octane": "0.1.9"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -58,11 +63,13 @@
     "@tiptap/starter-kit": "3.28.0",
     "@tsrx/react": "^0.2.37",
     "esbuild": "^0.28.1",
+    "playwright": "^1.61.0",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "vite": "^8.0.16",
     "vitest": "^4.1.9",
-    "@octanejs/testing-library": "0.1.4",
-    "octane": "0.1.7"
+    "@octanejs/testing-library": "0.1.6",
+    "octane": "0.1.9"
   },
   "scripts": {
     "test": "vitest run"

package/src/Editor.ts

@@ -0,0 +1,27 @@
+import type { Editor } from '@tiptap/core';
+import type { PortalDescriptor } from 'octane';
+
+import type { ReactRenderer } from './ReactRenderer';
+
+/** One immutable renderer entry consumed by EditorContent's keyed portal list. */
+export type RendererPortalEntry = {
+	id: string;
+	portal: PortalDescriptor;
+};
+
+export type RendererPortalSnapshot = Readonly<Record<string, RendererPortalEntry>>;
+
+/** External-store registry shared by EditorContent and custom view renderers. */
+export type ContentComponent = {
+	setRenderer(id: string, renderer: ReactRenderer<any, any>): void;
+	removeRenderer(id: string): void;
+	subscribe(callback: () => void): () => void;
+	getSnapshot(): RendererPortalSnapshot;
+	getServerSnapshot(): RendererPortalSnapshot;
+};
+
+/** TipTap's Editor augmented with the framework binding's mounted content state. */
+export type EditorWithContentComponent = Editor & {
+	contentComponent?: ContentComponent | null;
+	isEditorContentInitialized?: boolean;
+};

package/src/EditorContent.tsrx

@@ -1,11 +1,86 @@
-// DOM lifecycle bridge ported from @tiptap/react 3.28.0 EditorContent.tsx.
-// Portal-backed node and mark views intentionally arrive in the next stage;
-// this component owns only adoption, reset, editor switching, and host refs.
-import { memo, useLayoutEffect, useMemo, useRef } from 'octane';
+// DOM lifecycle and portal-registry bridge ported from @tiptap/react 3.28.0.
+import {
+	createPortal,
+	memo,
+	useLayoutEffect,
+	useMemo,
+	useRef,
+	useState,
+	useSyncExternalStore,
+} from 'octane';
+
+function PortalEntry({ entry }) {
+	return entry.portal;
+}
+
+/** Render every custom view in this EditorContent's logical Octane tree. */
+function Portals({ contentComponent }) @{
+	const renderers = useSyncExternalStore(
+		contentComponent.subscribe,
+		contentComponent.getSnapshot,
+		contentComponent.getServerSnapshot,
+	);
+	const entries = Object.values(renderers);
+
+	<>
+		@for (const entry of entries; key entry.id) {
+			<PortalEntry entry={entry} />
+		}
+	</>
+}
+
+/** Create the immutable external-store registry consumed by Portals. */
+export function createContentComponent() {
+	const subscribers = new Set();
+	let renderers = {};
+	let isNotificationQueued = false;
+
+	const notifySubscribers = () => {
+		if (isNotificationQueued || !subscribers.size) {
+			return;
+		}
+
+		isNotificationQueued = true;
+		queueMicrotask(() => {
+			isNotificationQueued = false;
+			subscribers.forEach((subscriber) => subscriber());
+		});
+	};
+
+	return {
+		subscribe(callback) {
+			subscribers.add(callback);
+			return () => subscribers.delete(callback);
+		},
+		getSnapshot() {
+			return renderers;
+		},
+		getServerSnapshot() {
+			return renderers;
+		},
+		setRenderer(id, renderer) {
+			renderers = {
+				...renderers,
+				[id]: {
+					id,
+					portal: createPortal(renderer.reactElement, renderer.element),
+				},
+			};
+			notifySubscribers();
+		},
+		removeRenderer(id) {
+			const nextRenderers = { ...renderers };
+			delete nextRenderers[id];
+			renderers = nextRenderers;
+			notifySubscribers();
+		},
+	};
+}
 
 export function PureEditorContent(props) @{
 	const { editor, innerRef, ref, ...rest } = props;
 	const editorContentRef = useRef(null);
+	const [contentComponent, setContentComponent] = useState(null);
 
 	useLayoutEffect(() => {
 		if (!editor || editor.isDestroyed || editor.isEditorContentInitialized) {
@@ -24,16 +99,26 @@ export function PureEditorContent(props) @{
 		// moving nodes preserves the existing EditorView and DOM identity.
 		element.append(...editorParent.childNodes);
 		editor.setOptions({ element });
+
+		// The registry must exist before createNodeViews: renderer factories publish
+		// into it while ProseMirror builds the custom view instances.
+		const nextContentComponent = createContentComponent();
+		editor.contentComponent = nextContentComponent;
 		editor.createNodeViews();
 		editor.isEditorContentInitialized = true;
+		setContentComponent(nextContentComponent);
 
 		return () => {
 			editor.isEditorContentInitialized = false;
 
 			if (!editor.isDestroyed) {
-				editor.view.setProps({ nodeViews: {} });
+				// ProseMirror destroys the live view instances here. Keep the registry
+				// installed until their destroy methods have unregistered every portal.
+				editor.view.setProps({ nodeViews: {}, markViews: {} });
 			}
 
+			editor.contentComponent = null;
+
 			// Reset the editor to a detached element so the still-live instance can
 			// safely be mounted by a later EditorContent. A view that has already
 			// been destroyed or never mounted has nothing left to transfer.
@@ -53,7 +138,12 @@ export function PureEditorContent(props) @{
 		};
 	}, [editor]);
 
-	<div {...rest} ref={[ref, innerRef, editorContentRef]} />
+	<>
+		<div {...rest} ref={[ref, innerRef, editorContentRef]} />
+		@if (contentComponent) {
+			<Portals contentComponent={contentComponent} />
+		}
+	</>
 }
 
 function EditorContentWithKey(props) @{

package/src/EditorContent.tsrx.d.ts

@@ -1,5 +1,7 @@
 import type { Editor } from '@tiptap/core';
 
+import type { ContentComponent } from './Editor';
+
 export type EditorContentRef<T> =
 	| { current: T | null }
 	| ((value: T | null) => void | (() => void))
@@ -17,5 +19,6 @@ export interface EditorContentProps {
 	[key: string]: unknown;
 }
 
+export declare function createContentComponent(): ContentComponent;
 export declare function PureEditorContent(props: EditorContentProps): unknown;
 export declare const EditorContent: (props: EditorContentProps) => unknown;

package/src/NodeViewContent.ts

@@ -0,0 +1,30 @@
+import { createElement, type ComponentBody } from 'octane';
+
+import { useReactNodeView } from './useReactNodeView';
+
+type HostComponent = string | ComponentBody<any>;
+
+export interface NodeViewContentProps {
+	as?: HostComponent;
+	style?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+export function NodeViewContent({ as: Tag = 'div', ...props }: NodeViewContentProps): unknown {
+	const { nodeViewContentRef, nodeViewContentChildren } = useReactNodeView();
+	// The editable content node is owned by ProseMirror rather than Octane. Keep a
+	// fresh adapter so a host-prop update re-attaches that node after Octane has
+	// reconciled the wrapper's authored children.
+	const contentRef = (element: HTMLElement | null) => nodeViewContentRef?.(element);
+
+	return createElement(Tag, {
+		...props,
+		ref: contentRef,
+		'data-node-view-content': '',
+		style: {
+			whiteSpace: 'pre-wrap',
+			...props.style,
+		},
+		children: nodeViewContentChildren,
+	});
+}

package/src/NodeViewWrapper.ts

@@ -0,0 +1,27 @@
+import { createElement, type ComponentBody } from 'octane';
+
+import { useReactNodeView } from './useReactNodeView';
+
+type HostComponent = string | ComponentBody<any>;
+
+export interface NodeViewWrapperProps {
+	as?: HostComponent;
+	ref?: unknown;
+	style?: Record<string, unknown>;
+	[key: string]: unknown;
+}
+
+export function NodeViewWrapper({ as: Tag = 'div', ...props }: NodeViewWrapperProps): unknown {
+	const { onDragStart } = useReactNodeView();
+
+	return createElement(Tag, {
+		...props,
+		ref: props.ref,
+		'data-node-view-wrapper': '',
+		onDragStart,
+		style: {
+			whiteSpace: 'normal',
+			...props.style,
+		},
+	});
+}

package/src/ReactMarkViewRenderer.ts

@@ -0,0 +1,113 @@
+import type { MarkViewProps, MarkViewRenderer, MarkViewRendererOptions } from '@tiptap/core';
+import { MarkView } from '@tiptap/core';
+import { createContext, createElement, memo, useContext, type ComponentBody } from 'octane';
+
+import { ReactRenderer } from './ReactRenderer';
+
+export interface MarkViewContextProps {
+	markViewContentRef: (element: HTMLElement | null) => void;
+}
+
+export const ReactMarkViewContext = createContext<MarkViewContextProps>({
+	markViewContentRef: () => {},
+});
+
+type HostComponent = string | ComponentBody<any>;
+
+export interface MarkViewContentProps {
+	as?: HostComponent;
+	[key: string]: unknown;
+}
+
+/** Host the ProseMirror-managed content of a custom mark view. */
+export function MarkViewContent({ as: Tag = 'span', ...props }: MarkViewContentProps): unknown {
+	const { markViewContentRef } = useContext(ReactMarkViewContext);
+	// Mark content is mutated by ProseMirror. Re-attach it after any Octane host
+	// reconciliation instead of treating the unmanaged child as authored output.
+	const contentRef = (element: HTMLElement | null) => markViewContentRef(element);
+
+	return createElement(Tag, {
+		...props,
+		ref: contentRef,
+		'data-mark-view-content': '',
+	});
+}
+
+export interface ReactMarkViewRendererOptions extends MarkViewRendererOptions {
+	/** Wrapper element tag. */
+	as?: string;
+	/** Additional wrapper classes. */
+	className?: string;
+	/** Static wrapper attributes. */
+	attrs?: Record<string, string>;
+}
+
+export class ReactMarkView extends MarkView<
+	ComponentBody<MarkViewProps>,
+	ReactMarkViewRendererOptions
+> {
+	renderer: ReactRenderer<unknown, MarkViewProps>;
+	contentDOMElement: HTMLElement;
+
+	constructor(
+		component: ComponentBody<MarkViewProps>,
+		props: MarkViewProps,
+		options?: Partial<ReactMarkViewRendererOptions>,
+	) {
+		super(component, props, options);
+
+		const { as = 'span', attrs, className = '' } = options || {};
+		const componentProps = {
+			...props,
+			updateAttributes: this.updateAttributes.bind(this),
+		} satisfies MarkViewProps;
+
+		this.contentDOMElement = document.createElement('span');
+		const context: MarkViewContextProps = {
+			markViewContentRef: (element) => {
+				if (element && !element.contains(this.contentDOMElement)) {
+					element.appendChild(this.contentDOMElement);
+				}
+			},
+		};
+		const providerBody: ComponentBody<MarkViewProps> = (providerProps) =>
+			createElement(ReactMarkViewContext.Provider, {
+				value: context,
+				children: createElement(component, providerProps),
+			});
+		const ReactMarkViewProvider = memo(providerBody);
+		(ReactMarkViewProvider as any).displayName = 'ReactMarkView';
+
+		this.renderer = new ReactRenderer(ReactMarkViewProvider, {
+			editor: props.editor,
+			props: componentProps,
+			as,
+			className: `mark-${props.mark.type.name} ${className}`.trim(),
+		});
+
+		if (attrs) {
+			this.renderer.updateAttributes(attrs);
+		}
+	}
+
+	get dom(): HTMLElement {
+		return this.renderer.element;
+	}
+
+	get contentDOM(): HTMLElement {
+		return this.contentDOMElement;
+	}
+
+	/** ProseMirror calls this when the mark view leaves the document. */
+	destroy(): void {
+		this.renderer.destroy();
+	}
+}
+
+/** Create a TipTap mark-view renderer backed by an Octane portal. */
+export function ReactMarkViewRenderer(
+	component: ComponentBody<MarkViewProps>,
+	options: Partial<ReactMarkViewRendererOptions> = {},
+): MarkViewRenderer {
+	return (props) => new ReactMarkView(component, props, options);
+}