@octane-xplat/tiptap 0.10.0 → 0.11.0

package/src/TiptapEditor.web.tsrx

@@ -1,7 +1,8 @@
-import { useImperativeHandle, useEffect, useRef } from 'octane'
+import { useImperativeHandle, useEffect, useMemo, useRef } from 'octane'
 import { EditorContent, useEditor } from '@octanejs/tiptap'
 import StarterKit from '@tiptap/starter-kit'
-import type { TiptapEditorHandle, TiptapEditorProps, TiptapFormat } from './types'
+import type { Extensions } from '@tiptap/core'
+import type { TiptapEditorHandle, TiptapEditorProps, TiptapFormat, TiptapWebOptions } from './types'
 
 export const supported = true
 
@@ -56,6 +57,20 @@ function activeFormats(editor: any): TiptapFormat[] {
 	return out
 }
 
+/** Extension list for the web engine: the built-in StarterKit (optionally
+ *  configured) followed by caller extras. `starterKit: false` or a
+ *  starterKit-named caller entry hands the schema over to the caller —
+ *  registering two StarterKits trips tiptap's duplicate-name warning. */
+function resolveExtensions(web: TiptapWebOptions | undefined): Extensions {
+	const extras = web?.extensions ?? []
+	if (web?.starterKit === false || extras.some((ext) => ext?.name === 'starterKit')) {
+		return extras
+	}
+
+	const kit = web?.starterKit ? StarterKit.configure(web.starterKit) : StarterKit
+	return [kit, ...extras]
+}
+
 /** Unified editor facade, web half — a thin adapter over the published
  *  `@octanejs/tiptap` binding (useEditor + EditorContent + StarterKit). */
 export function TiptapEditor(props: TiptapEditorProps) @{
@@ -65,8 +80,15 @@ export function TiptapEditor(props: TiptapEditorProps) @{
 	const lastJSONInput = useRef(JSON.stringify(props.json))
 	const bound = useRef<TiptapEditorHandle | undefined>(undefined)
 
+	// tiptap fixes the schema at construction; memoized on the option values
+	// so a stable caller config never re-triggers setOptions.
+	const extensions = useMemo(
+		() => resolveExtensions(props.web),
+		[props.web?.extensions, props.web?.starterKit],
+	)
+
 	const editor = useEditor({
-		extensions: [StarterKit],
+		extensions,
 		content: (props.json ?? props.value ?? '') as any,
 		editable: props.editable !== false,
 		autofocus: props.autofocus ?? false,

package/src/types.ts

@@ -1,4 +1,6 @@
 import type { Octane } from 'octane/jsx-runtime'
+import type { Extensions } from '@tiptap/core'
+import type { StarterKitOptions } from '@tiptap/starter-kit'
 
 /** Format vocabulary shared by the web (tiptap StarterKit) and native
  *  (Aztec) backends. On web, starter-kit covers everything except
@@ -35,6 +37,25 @@ export type TiptapFormat =
  *  callers round-trip through tiptap's own schema on both platforms. */
 export type TiptapJSON = { type: string; content?: unknown[] } & Record<string, unknown>
 
+/** Engine options for the web target only. The `.web` entry mounts a real
+ *  tiptap `Editor`, so callers can extend its schema here. The Android
+ *  facade (Aztec leaf) and the bundled AppKit engine cannot host DOM-bound
+ *  ProseMirror/tiptap extension objects and ignore these options. Caller
+ *  plugins, node views, and browser menus are web behavior, not shared
+ *  contract. */
+export interface TiptapWebOptions {
+	/** Extra tiptap extensions appended after the built-in StarterKit — any
+	 *  `Extension`/`Node`/`Mark` from `@tiptap/*` or app code. An entry named
+	 *  `starterKit` replaces the built-in instead of registering it twice.
+	 *  The editor fixes its schema at construction; keep the list
+	 *  referentially stable across renders. */
+	extensions?: Extensions
+	/** `StarterKit.configure()` options for the built-in StarterKit, or
+	 *  `false` to omit it — `extensions` must then supply a complete schema
+	 *  (document, paragraph, and text nodes at minimum). */
+	starterKit?: StarterKitOptions | false
+}
+
 export interface TiptapEditorHandle {
 	/** AppKit: returns the latest WebKit snapshot; commands are asynchronous. */
 	getHTML(): string
@@ -69,7 +90,9 @@ export interface TiptapEditorProps {
 	 *  setContent, preserving the diff loop the editor emitted is skipped). */
 	value?: string
 	/** Document JSON. Takes precedence over `value` when both arrive. On
-	 *  native it waits for the schema modules (see `onJSONReady`). */
+	 *  native it waits for the schema modules and host readiness (see
+	 *  `onJSONReady`); a doc that arrives early is applied once both are up
+	 *  rather than dropped. */
 	json?: TiptapJSON
 	placeholder?: string
 	editable?: boolean
@@ -88,6 +111,9 @@ export interface TiptapEditorProps {
 	ref?: Octane.Ref<TiptapEditorHandle>
 	android?: Record<string, any>
 	ios?: Record<string, any>
+	/** Web-target engine configuration — tiptap extensions and StarterKit
+	 *  options. See `TiptapWebOptions`; ignored on native and AppKit. */
+	web?: TiptapWebOptions
 	row?: number | string
 	col?: number | string
 	rowSpan?: number

package/types/types.d.ts

@@ -1,4 +1,6 @@
 import type { Octane } from 'octane/jsx-runtime';
+import type { Extensions } from '@tiptap/core';
+import type { StarterKitOptions } from '@tiptap/starter-kit';
 /** Format vocabulary shared by the web (tiptap StarterKit) and native
  *  (Aztec) backends. On web, starter-kit covers everything except
  *  taskList/highlight/subscript/superscript/align* — those no-op there and
@@ -10,6 +12,24 @@ export type TiptapJSON = {
     type: string;
     content?: unknown[];
 } & Record<string, unknown>;
+/** Engine options for the web target only. The `.web` entry mounts a real
+ *  tiptap `Editor`, so callers can extend its schema here. The Android
+ *  facade (Aztec leaf) and the bundled AppKit engine cannot host DOM-bound
+ *  ProseMirror/tiptap extension objects and ignore these options. Caller
+ *  plugins, node views, and browser menus are web behavior, not shared
+ *  contract. */
+export interface TiptapWebOptions {
+    /** Extra tiptap extensions appended after the built-in StarterKit — any
+     *  `Extension`/`Node`/`Mark` from `@tiptap/*` or app code. An entry named
+     *  `starterKit` replaces the built-in instead of registering it twice.
+     *  The editor fixes its schema at construction; keep the list
+     *  referentially stable across renders. */
+    extensions?: Extensions;
+    /** `StarterKit.configure()` options for the built-in StarterKit, or
+     *  `false` to omit it — `extensions` must then supply a complete schema
+     *  (document, paragraph, and text nodes at minimum). */
+    starterKit?: StarterKitOptions | false;
+}
 export interface TiptapEditorHandle {
     /** AppKit: returns the latest WebKit snapshot; commands are asynchronous. */
     getHTML(): string;
@@ -43,7 +63,9 @@ export interface TiptapEditorProps {
      *  setContent, preserving the diff loop the editor emitted is skipped). */
     value?: string;
     /** Document JSON. Takes precedence over `value` when both arrive. On
-     *  native it waits for the schema modules (see `onJSONReady`). */
+     *  native it waits for the schema modules and host readiness (see
+     *  `onJSONReady`); a doc that arrives early is applied once both are up
+     *  rather than dropped. */
     json?: TiptapJSON;
     placeholder?: string;
     editable?: boolean;
@@ -66,6 +88,9 @@ export interface TiptapEditorProps {
     ref?: Octane.Ref<TiptapEditorHandle>;
     android?: Record<string, any>;
     ios?: Record<string, any>;
+    /** Web-target engine configuration — tiptap extensions and StarterKit
+     *  options. See `TiptapWebOptions`; ignored on native and AppKit. */
+    web?: TiptapWebOptions;
     row?: number | string;
     col?: number | string;
     rowSpan?: number;