@octane-xplat/lexical 0.10.0 → 0.11.1

package/src/LexicalEditor.web.test.tsrx

@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+import { afterEach, expect, it, vi } from 'vitest'
+import { act, createRoot } from 'octane'
+import { useLexicalComposerContext } from '@octanejs/lexical/LexicalComposerContext'
+import { LexicalEditor } from './LexicalEditor.web.tsrx'
+import type { LexicalEditorHandle } from './types'
+import { BadgeNode } from '../tests/browser/BadgeNode'
+
+const roots: any[] = []
+function UpdatePlugin() {
+	useLexicalComposerContext()
+	return <span data-plugin-mounted="true" />
+}
+
+function mount(props: any = {}) {
+	const el = document.createElement('div')
+	document.body.append(el)
+	const root = createRoot(el)
+	roots.push(root)
+	let handle: LexicalEditorHandle | null = null
+	const render = (next: any) =>
+		act(() =>
+			root.render(
+				<LexicalEditor
+					{...next}
+					ref={(value: LexicalEditorHandle | null) => {
+						handle = value
+					}}
+				/>,
+			),
+		)
+	render(props)
+	return { el, root, render, get handle() { return handle } }
+}
+
+afterEach(() => {
+	for (const root of roots.splice(0)) act(() => root.unmount())
+	document.body.innerHTML = ''
+	vi.restoreAllMocks()
+})
+
+it('reports the live JSON and editor handles once when ready', () => {
+	const onJSONReady = vi.fn()
+	const onReady = vi.fn()
+	const { handle } = mount({ value: '<p>Travel notes</p>', onJSONReady, onReady })
+
+	expect(handle).not.toBeNull()
+	expect(handle!.getJSON()).not.toBeNull()
+	expect(onJSONReady).toHaveBeenCalledExactlyOnceWith(true)
+	expect(onReady).toHaveBeenCalledTimes(1)
+})
+
+it('wires focus and blur callbacks from the real editable element', () => {
+	const onFocus = vi.fn()
+	const onBlur = vi.fn()
+	const { el } = mount({ onFocus, onBlur })
+	const editable = el.querySelector('[contenteditable]') as HTMLElement
+
+	editable.focus()
+	expect(onFocus).toHaveBeenCalledTimes(1)
+	editable.blur()
+	expect(onBlur).toHaveBeenCalledTimes(1)
+})
+
+it('accepts controlled HTML updates and read-only changes', () => {
+	const mounted = mount({ value: '<p>First</p>', editable: false })
+	const editable = mounted.el.querySelector('[contenteditable]') as HTMLElement
+	expect(editable.getAttribute('contenteditable')).toBe('false')
+
+	mounted.render({ value: '<p>Second</p>', editable: true })
+	expect(mounted.handle!.getHTML()).toContain('Second')
+	expect(
+		(mounted.el.querySelector('[contenteditable]') as HTMLElement).getAttribute('contenteditable'),
+	).toBe('true')
+})
+
+it('adds custom nodes to defaults and round-trips their JSON and HTML', () => {
+	const { handle } = mount({
+		value: '<p><span data-badge>Voyager</span></p><h1>Default heading</h1>',
+		web: { nodes: [BadgeNode] },
+	})
+
+	const json = handle!.getJSON()!
+	expect(JSON.stringify(json)).toContain('"type":"badge"')
+	expect(handle!.getHTML()).toContain('data-badge')
+	expect(handle!.getHTML()).toContain('<h1><span')
+
+	handle!.setJSON(json)
+	expect(handle!.getHTML()).toContain('Voyager')
+	expect(handle!.getHTML()).toContain('data-badge')
+})
+
+it('renders custom plugins inside the composer context', () => {
+	const { el } = mount({ web: { plugins: <UpdatePlugin /> } })
+	expect(el.querySelector('[data-plugin-mounted]')).not.toBeNull()
+})
+
+it('can replace the default custom-node registry', () => {
+	const { handle } = mount({
+		value: '<p><span data-badge>Caller schema</span></p>',
+		web: {
+			replaceNodes: true,
+			nodes: [BadgeNode],
+			replacePlugins: true,
+			plugins: <UpdatePlugin />,
+		},
+	})
+	expect(handle).not.toBeNull()
+	expect((handle!.native as any).getRegisteredNode(BadgeNode)).toBeTruthy()
+	expect(handle!.getJSON()!.root).toBeTruthy()
+})

package/src/LexicalEditor.web.tsrx

@@ -46,9 +46,8 @@ import type { LexicalEditorHandle, LexicalEditorProps, LexicalFormat } from './t
 
 export const supported = true
 
-/** The facade's fixed node set — Aztec's capability surface plus
- *  AutoLinkNode (parsing safety for docs produced by fuller editors). Apps
- *  needing custom nodes or plugins import @octanejs/lexical directly. */
+/** The facade's default node set — Aztec's capability surface plus
+ *  AutoLinkNode (parsing safety for docs produced by fuller editors). */
 const NODES = [
 	HeadingNode,
 	QuoteNode,
@@ -241,10 +240,8 @@ function activeFormats(editor: any): LexicalFormat[] {
 	return out
 }
 
-/** Unified editor facade, web half — a fixed-plugin LexicalComposer over
- *  the published `@octanejs/lexical` binding. The composition is sealed on
- *  purpose: the facade's contract is the native-compatible vocabulary, and
- *  apps that need arbitrary plugins use the upstream package directly. */
+/** Unified editor facade, web half — a LexicalComposer over the published
+ *  `@octanejs/lexical` binding, with optional web-only node and plugin composition. */
 export function LexicalEditor(props: LexicalEditorProps) @{
 	const editorRef = useRef<any>(null)
 	const lastEmitted = useRef<string | undefined>(undefined)
@@ -257,7 +254,9 @@ export function LexicalEditor(props: LexicalEditorProps) @{
 
 	const initialConfig = {
 		namespace: 'octane-xplat/lexical',
-		nodes: NODES,
+		nodes: props.web?.replaceNodes
+			? props.web.nodes ?? []
+			: [...new Set([...NODES, ...(props.web?.nodes ?? [])])],
 		editable: props.editable !== false,
 		editorState: props.json != null
 			? JSON.stringify(props.json)
@@ -317,6 +316,7 @@ export function LexicalEditor(props: LexicalEditorProps) @{
 		}
 
 		setHandle(bound.current!)
+		props.onJSONReady?.(true)
 		props.onReady?.()
 	}
 
@@ -376,6 +376,8 @@ export function LexicalEditor(props: LexicalEditorProps) @{
 						placeholder={null}
 						className="vx-lexical-input"
 						style={{ outline: 'none' }}
+						onFocus={props.onFocus}
+						onBlur={props.onBlur}
 					/>
 				}
 				placeholder={
@@ -395,12 +397,17 @@ export function LexicalEditor(props: LexicalEditorProps) @{
 				}
 				ErrorBoundary={LexicalErrorBoundary}
 			/>
-			<HistoryPlugin />
-			<ListPlugin />
-			<LinkPlugin />
-			{props.autofocus ? <AutoFocusPlugin /> : null}
+			{!props.web?.replacePlugins ? (
+				<>
+					<HistoryPlugin />
+					<ListPlugin />
+					<LinkPlugin />
+					{props.autofocus ? <AutoFocusPlugin /> : null}
+				</>
+			) : null}
 			<OnChangePlugin onChange={emitChange} />
 			<EditorRefPlugin editorRef={attach} />
+			{props.web?.plugins}
 		</LexicalComposer>
 	</div>
 }

package/src/types.ts

@@ -1,4 +1,6 @@
 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`/
@@ -37,6 +39,27 @@ export type LexicalFormat =
  *  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
@@ -71,23 +94,26 @@ export interface LexicalEditorProps {
 	/** 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 (see
-	 *  `onJSONReady`). */
+	 *  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
-	/** Fires once when the native lexical bridge settles — `true` if the
-	 *  DOM-free lexical modules loaded, `false` on runtimes that can't host
-	 *  them (JSON calls then no-op / return null). Never fires on web. */
-	/** AppKit: fires true with mounted engine readiness; no headless conversion bridge. */
+	/** 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>