@octane-xplat/lexical 0.0.1 → 0.11.0

package/src/json-bridge.ts

@@ -0,0 +1,335 @@
+/** Lazy lexical document-model bridge for native runtimes. The DOM-free
+ *  slices (lexical core + the Aztec-shaped node packages, @lexical/html,
+ *  zeed-dom as the parser host) load on demand — on a runtime that can't
+ *  host them the bridge settles to unavailable and callers get null/no-op.
+ *
+ *  Conversions run on a single headless `createEditor` (no `setRootElement`,
+ *  no @lexical/headless — that package pulls happy-dom). Each call swaps the
+ *  editor state wholesale, so the shared instance is a pure converter.
+ *
+ *  Import behavior was proven by the demos probe (see packages/demos
+ *  LexicalProbe): all slices load on both NS engines and the round-trip
+ *  preserves links/alignment on 14/14 steps; the failure mode left is a
+ *  future version or bundler regression, which the catch below degrades
+ *  instead of crashing. */
+
+import type { LexicalJSON } from './types'
+
+interface Bridge {
+	editor: any
+	lexical: any
+	html: any
+	zeed: any
+}
+
+let bridge: Bridge | null | undefined
+
+const kebab = (k: string) => k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())
+
+function chainDesc(proto: object, key: string): PropertyDescriptor | undefined {
+	let o: object | null = proto
+	while (o && o !== Object.prototype) {
+		const d = Object.getOwnPropertyDescriptor(o, key)
+		if (d) {
+			return d
+		}
+
+		o = Object.getPrototypeOf(o)
+	}
+
+	return undefined
+}
+
+function cssText(el: any): string {
+	return el.getAttribute('style') ?? ''
+}
+
+function writeStyleProp(el: any, key: string, value: string): void {
+	const rules = cssText(el)
+		.split(';')
+		.map((s: string) => s.trim())
+		.filter(Boolean)
+		.filter((r: string) => !r.startsWith(kebab(key) + ':'))
+
+	if (value !== '' && value != null) {
+		rules.push(`${kebab(key)}: ${value}`)
+	}
+
+	el.setAttribute('style', rules.join('; '))
+}
+
+/** zeed-dom is a vdom, not a DOM — lexical's walkers and exportDOM need four
+ *  categories of patches beyond the classList/DOMParser install the tiptap
+ *  bridge carries:
+ *
+ *  1. `parentElement` (absent pre-0.18 zeed-dom; guarded either way).
+ *  2. `firstChild`/`lastChild`/sibling accessors return `undefined` where the
+ *     DOM spec says `null`, and the getters live on an ancestor proto —
+ *     chainDesc finds them so the coercion wraps the real getter.
+ *  3. `style`: DOM reads of unset props return `''`, and lexical's exportDOM
+ *     writes via property assignment and `setProperty` — neither serializes
+ *     in zeed. The proxy defaults missing props to `''` and writes through
+ *     to the element's `style` attribute.
+ *  4. Attribute-valued property assignments (`element.href = …`) must land
+ *     as attributes — LinkNode.exportDOM sets `anchor.href`, dropping the
+ *     link target entirely without this.
+ *
+ *  Plus the `Node` constants global (lexical's helpers read
+ *  `Node.TEXT_NODE`). */
+function installLexicalDomShim(zeed: any): void {
+	const bootDoc = zeed.createHTMLDocument()
+	bootDoc.body.innerHTML = '<p>x</p>'
+	const elProto = Object.getPrototypeOf(bootDoc.body.childNodes[0])
+	const textProto = Object.getPrototypeOf(bootDoc.body.childNodes[0].childNodes[0])
+
+	for (const p of [elProto, textProto]) {
+		if (!chainDesc(p, 'parentElement')) {
+			Object.defineProperty(p, 'parentElement', {
+				configurable: true,
+				get(this: any) {
+					const par = this.parentNode
+					return par && par.nodeType === 1 ? par : null
+				},
+			})
+		}
+
+		for (const k of ['firstChild', 'lastChild', 'nextSibling', 'previousSibling']) {
+			const d = chainDesc(p, k)
+			Object.defineProperty(p, k, {
+				configurable: true,
+				get(this: any) {
+					const v = d?.get ? d.get.call(this) : undefined
+					return v ?? null
+				},
+				set: d?.set,
+			})
+		}
+	}
+
+	const styleCache = new WeakMap()
+	Object.defineProperty(elProto, 'style', {
+		configurable: true,
+		get(this: any) {
+			let proxy = styleCache.get(this)
+			if (!proxy) {
+				const el = this
+				proxy = new Proxy(
+					{},
+					{
+						get: (_t, k) => {
+							if (k === 'setProperty') {
+								return (prop: string, value: string) => writeStyleProp(el, prop, value)
+							}
+
+							if (k === 'removeProperty') {
+								return (prop: string) => {
+									writeStyleProp(el, prop, '')
+									return ''
+								}
+							}
+
+							if (k === 'cssText') {
+								return cssText(el)
+							}
+
+							if (k === 'getPropertyValue') {
+								return (prop: string) => {
+									const raw = cssText(el)
+										.split(';')
+										.map((s: string) => s.trim())
+										.find((r: string) => r.startsWith(prop + ':'))
+
+									return raw ? raw.slice(raw.indexOf(':') + 1).trim() : ''
+								}
+							}
+
+							if (typeof k === 'string') {
+								const raw = cssText(el)
+									.split(';')
+									.map((s: string) => s.trim())
+									.find((r: string) => r.startsWith(kebab(k) + ':'))
+
+								return raw ? raw.slice(raw.indexOf(':') + 1).trim() : ''
+							}
+
+							return undefined
+						},
+						set: (_t, k, v) => {
+							if (typeof k === 'string') {
+								writeStyleProp(el, k, v)
+							}
+
+							return true
+						},
+					},
+				)
+
+				styleCache.set(this, proxy)
+			}
+
+			return proxy
+		},
+	})
+
+	for (const attr of ['href', 'target', 'rel', 'title']) {
+		const d = chainDesc(elProto, attr)
+		if (!d?.get && !d?.set) {
+			Object.defineProperty(elProto, attr, {
+				configurable: true,
+				get(this: any) {
+					return this.getAttribute(attr) ?? ''
+				},
+				set(this: any, v: string) {
+					this.setAttribute(attr, v)
+				},
+			})
+		}
+	}
+
+	const clDesc = chainDesc(elProto, 'classList')
+	if (clDesc?.get) {
+		Object.defineProperty(elProto, 'classList', {
+			configurable: true,
+			get(this: any) {
+				const cl = clDesc.get!.call(this)
+				if (cl && typeof cl[Symbol.iterator] !== 'function') {
+					const tokens = String(this.getAttribute('class') ?? '')
+						.split(/\s+/)
+						.filter(Boolean)
+
+					return Object.assign(tokens, cl)
+				}
+
+				return cl
+			},
+			set: clDesc.set,
+		})
+	}
+
+	const g = globalThis as any
+	if (!g.window?.DOMParser) {
+		class ZeedDOMParser {
+			parseFromString(html: string) {
+				const doc = zeed.createHTMLDocument()
+				doc.body.innerHTML = html
+				return doc
+			}
+		}
+
+		g.window = { DOMParser: ZeedDOMParser }
+		g.document = zeed.createHTMLDocument()
+	}
+
+	g.Node = g.Node ?? {
+		ELEMENT_NODE: 1,
+		ATTRIBUTE_NODE: 2,
+		TEXT_NODE: 3,
+		CDATA_SECTION_NODE: 4,
+		PROCESSING_INSTRUCTION_NODE: 7,
+		COMMENT_NODE: 8,
+		DOCUMENT_NODE: 9,
+		DOCUMENT_TYPE_NODE: 10,
+		DOCUMENT_FRAGMENT_NODE: 11,
+	}
+}
+
+export async function ensureJSONBridge(): Promise<boolean> {
+	if (bridge !== undefined) {
+		return bridge !== null
+	}
+
+	try {
+		const [lexical, html, rt, list, link, code, ext, zeed] = await Promise.all([
+			import('lexical'),
+			import('@lexical/html'),
+			import('@lexical/rich-text'),
+			import('@lexical/list'),
+			import('@lexical/link'),
+			import('@lexical/code'),
+			import('@lexical/extension'),
+			import('zeed-dom'),
+		])
+
+		installLexicalDomShim(zeed)
+
+		// The leaf's native node set — Aztec's capability surface in lexical
+		// form. taskList/highlight/sub/sup formats have no lexical node here
+		// and stay no-ops on the facade.
+		const editor = lexical.createEditor({
+			namespace: 'octane-xplat/lexical',
+			nodes: [
+				rt.HeadingNode,
+				rt.QuoteNode,
+				list.ListNode,
+				list.ListItemNode,
+				link.LinkNode,
+				code.CodeNode,
+				ext.HorizontalRuleNode,
+			],
+			onError: () => undefined,
+		})
+
+		bridge = { editor, lexical, html, zeed }
+
+		return true
+	} catch {
+		bridge = null
+		return false
+	}
+}
+
+export function jsonBridgeReady(): boolean {
+	return bridge != null
+}
+
+function parseHTML(htmlText: string): any {
+	const doc = bridge!.zeed.createHTMLDocument()
+	doc.body.innerHTML = htmlText
+	return doc
+}
+
+/** HTML → serialized editor state through lexical's own DOM import rules.
+ *  Null when the bridge hasn't loaded (call ensureJSONBridge first / check
+ *  `jsonBridgeReady`). */
+export function htmlToJSON(htmlText: string): LexicalJSON | null {
+	if (!bridge) {
+		return null
+	}
+
+	try {
+		bridge.editor.update(
+			() => {
+				const nodes = bridge!.html.$generateNodesFromDOM(bridge!.editor, parseHTML(htmlText))
+				bridge!.lexical
+					.$getRoot()
+					.clear()
+					.append(...nodes)
+			},
+			{ discrete: true },
+		)
+
+		return bridge.editor.getEditorState().toJSON() as LexicalJSON
+	} catch {
+		return null
+	}
+}
+
+/** Serialized editor state → HTML via lexical's own exportDOM rules (no
+ *  browser DOM — the zeed-dom shim stands in). */
+export function jsonToHTML(doc: LexicalJSON): string | null {
+	if (!bridge) {
+		return null
+	}
+
+	try {
+		bridge.editor.setEditorState(bridge.editor.parseEditorState(JSON.stringify(doc)))
+		let out = ''
+		bridge.editor.read(() => {
+			out = bridge!.html.$generateHtmlFromNodes(bridge!.editor)
+		})
+
+		return out
+	} catch {
+		return null
+	}
+}

package/src/types.ts

@@ -0,0 +1,131 @@
+import type { Octane } from 'octane/jsx-runtime'
+import type { OctaneNode } from 'octane'
+import type { Klass, LexicalNode, LexicalNodeReplacement } from 'lexical'
+
+/** Format vocabulary shared by the web (lexical core + registered nodes)
+ *  and native (Aztec) backends. On web, `taskList`/`highlight`/`subscript`/
+ *  `superscript` are only active when their nodes are registered — the
+ *  default node set doesn't include them, so they no-op there and map to
+ *  Aztec formats on Android. */
+export type LexicalFormat =
+	| 'bold'
+	| 'italic'
+	| 'underline'
+	| 'strikethrough'
+	| 'code'
+	| 'blockquote'
+	| 'bulletList'
+	| 'orderedList'
+	| 'taskList'
+	| 'codeBlock'
+	| 'horizontalRule'
+	| 'highlight'
+	| 'subscript'
+	| 'superscript'
+	| 'paragraph'
+	| 'heading1'
+	| 'heading2'
+	| 'heading3'
+	| 'heading4'
+	| 'heading5'
+	| 'heading6'
+	| 'alignLeft'
+	| 'alignCenter'
+	| 'alignRight'
+	| 'link'
+
+/** Lexical serialized editor state (`{ root: { children: [...] } }` — the
+ *  `EditorState.toJSON()` shape). Opaque here — callers round-trip through
+ *  lexical's own schema on both platforms. */
+export type LexicalJSON = { root: Record<string, unknown> } & Record<string, unknown>
+
+/** Web-only extensions for the live Lexical composer. These options are ignored
+ *  by native backends; caller plugins, custom nodes, transforms, and browser
+ *  views require a separate native implementation. */
+export interface LexicalWebOptions {
+	/** Additional Lexical node classes or replacements. By default these are
+	 *  added to the facade's built-in node set. Set `replaceNodes` to use this
+	 *  list as the complete custom node registry instead. */
+	nodes?: readonly (Klass<LexicalNode> | LexicalNodeReplacement)[]
+	/** Replace the facade's built-in custom node registry with `nodes`. Core
+	 *  Lexical nodes remain managed by Lexical. Defaults to `false`. */
+	replaceNodes?: boolean
+	/** Replace the default history, list, link, and autofocus plugins with the
+	 *  plugin components supplied in `plugins`. Defaults to `false`. The rich
+	 *  text surface and facade change/ref bindings remain installed. */
+	replacePlugins?: boolean
+	/** Additional Octane plugin components rendered inside the Lexical composer,
+	 *  or the replacement plugin composition when `replacePlugins` is `true`.
+	 *  Use a fragment when composing more than one plugin. */
+	plugins?: OctaneNode
+}
+
+export interface LexicalEditorHandle {
+	/** AppKit: returns the latest WebKit snapshot; commands are asynchronous. */
+	getHTML(): string
+	/** Web: `setEditorState` inside an update (undo-aware). Native: Aztec
+	 *  `fromHtml` — resets undo history. */
+	setHTML(html: string): void
+	/** Serialized editor state, or null while the native doc-model modules
+	 *  are still loading / on a runtime that can't host them (`onJSONReady`
+	 *  reports the outcome). Web is always ready. */
+	/** AppKit: latest live engine JSON snapshot; null before onReady. */
+	getJSON(): LexicalJSON | null
+	setJSON(doc: LexicalJSON): void
+	apply(format: LexicalFormat): void
+	linkTo(url: string, anchor?: string): void
+	removeLink(): void
+	isActive(format: LexicalFormat): boolean
+	undo(): void
+	redo(): void
+	focus(): void
+	blur(): void
+	isFocused(): boolean
+	/** The platform surface — the lexical `LexicalEditor` on web,
+	 *  `AztecText` on Android. */
+	/** AppKit: the XplatEditorHost transport, not the browser engine instance. */
+	native: any
+}
+
+export interface LexicalEditorProps {
+	id?: string
+	className?: string
+	style?: any
+	/** Document HTML. Seed at mount; external changes re-push. */
+	value?: string
+	/** Serialized editor state. Takes precedence over `value` when both
+	 *  arrive. On native it waits for the doc-model modules and host
+	 *  readiness (see `onJSONReady`); a doc that arrives early is applied
+	 *  once both are up rather than dropped. */
+	json?: LexicalJSON
+	placeholder?: string
+	editable?: boolean
+	autofocus?: boolean
+	onReady?: () => void
+	/** Reports when serialized JSON access is available. Web and AppKit report
+	 *  `true` when their live editor handle exists. Native reports whether its
+	 *  lazy DOM-free conversion bridge loaded; unsupported runtimes report
+	 *  `false` and JSON getters return `null`. */
+	onJSONReady?: (ready: boolean) => void
+	onChange?: (html: string) => void
+	onJSONChange?: (doc: LexicalJSON) => void
+	onSelectionChange?: (event: { start: number; end: number; active: LexicalFormat[] }) => void
+	onFocus?: () => void
+	onBlur?: () => void
+	/** Web-only Lexical node and plugin composition. Ignored by native backends. */
+	web?: LexicalWebOptions
+	ref?: Octane.Ref<LexicalEditorHandle>
+	android?: Record<string, any>
+	ios?: Record<string, any>
+	row?: number | string
+	col?: number | string
+	rowSpan?: number
+	colSpan?: number
+	dock?: 'left' | 'top' | 'right' | 'bottom'
+	left?: number
+	top?: number
+	flexGrow?: number
+	flexShrink?: number
+	alignSelf?: 'auto' | 'flex-start' | 'flex-end' | 'center' | 'stretch' | 'baseline'
+	order?: number
+}

package/types/index.d.ts

@@ -0,0 +1,8 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { LexicalEditorProps, LexicalJSON } from '../src/types'
+
+export declare const LexicalEditor: UniversalComponent<LexicalEditorProps>
+export declare const supported: boolean
+export declare function ensureJSONBridge(): Promise<boolean>
+export declare function jsonBridgeReady(): boolean
+export type * from '../src/types'

package/types/index.macos.d.ts

@@ -0,0 +1,7 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { LexicalEditorProps } from '../src/types'
+export declare const LexicalEditor: UniversalComponent<LexicalEditorProps>
+export declare const supported: boolean
+export type * from '../src/types'
+export declare function ensureJSONBridge(): Promise<boolean>
+export declare function jsonBridgeReady(): boolean