@octane-xplat/richtext 0.9.0 → 0.11.0

package/src/RichTextEditor.ios.tsrx

@@ -1,15 +1,230 @@
 /** @jsxImportSource @nativescript-community/octane */
-import type { RichTextEditorProps } from './types'
+import { useImperativeHandle, useCallback, useEffect, useRef } from 'octane'
+import { View } from '@nativescript/core'
+import { registerElement } from '@nativescript-community/octane'
+import type { Attributes } from '@nativescript-community/octane/intrinsics'
+import type {
+	RichTextEditorHandle,
+	RichTextEditorProps,
+	RichTextFormat,
+} from './types'
 
-export const supported = false
+/** `XplatAztecEditorView` arrives through the leaf's
+ *  `platforms/ios/src` Swift facade over `Aztec.TextView` — there are no
+ *  generated typings for it, so every touch goes through `as any` at one
+ *  boundary instead of `declare const` per call site. */
+declare const XplatAztecEditorView: any
 
-/** iOS bring-up is deferred — the Swift facade over Aztec-iOS lands in a
- *  follow-up. Renders the placeholder so a shared screen still mounts. */
+/** AztecEditor-iOS has no task-list or text-alignment API — the facade
+ *  reports these as unsupported rather than faking a result. `link` is
+ *  valid but goes through `linkTo`, matching the Android leaf. */
+const UNSUPPORTED: ReadonlySet<RichTextFormat> = new Set([
+	'taskList',
+	'alignLeft',
+	'alignCenter',
+	'alignRight',
+])
+
+class AztecEditor extends View {
+	createNativeView() {
+		return new XplatAztecEditorView()
+	}
+}
+
+declare module '@nativescript-community/octane/intrinsics' {
+	interface NativeScriptElements {
+		xplatrichtext: Attributes<typeof AztecEditor>
+	}
+}
+
+registerElement('xplatrichtext', AztecEditor)
+
+export const supported = true
+
+/** WordPress AztecEditor-iOS surface — a UITextView-backed native editor,
+ *  not a WebView. Content in/out is HTML (`setHTML`/`getHTML`); JSON
+ *  interchange lives one layer up in @octane-xplat/tiptap. */
 export function RichTextEditor(props: RichTextEditorProps) @{
-	<label
+	const host = useRef<any>(null)
+	const lastEmitted = useRef<string | undefined>(undefined)
+	const applyingValue = useRef(false)
+	const emitTimer = useRef<any>(null)
+	const warned = useRef<Set<string>>(new Set())
+
+	// Stable identity — an inline closure re-fires ref(null)/ref(v) per
+	// render, which would bounce host.current around the effects below.
+	useImperativeHandle(props.ref, () => handle(editor()), []);
+
+	const bindHost = useCallback((v: any) => {
+		host.current = v
+	}, [])
+
+	const editor = () => host.current?.ios
+
+	const emitChange = () => {
+		const e = editor()
+		if (!e || applyingValue.current) return
+		clearTimeout(emitTimer.current)
+		emitTimer.current = setTimeout(() => {
+			const current = editor()
+			if (!current || applyingValue.current) return
+			const html = current.getHTML()
+			lastEmitted.current = html
+			props.onChange?.(html)
+		}, 150)
+	}
+
+	const reportUnsupported = (format: RichTextFormat) => {
+		if (warned.current.has(format)) return
+		warned.current.add(format)
+		console.warn(
+			`[richtext] apply('${format}') is not supported by the iOS Aztec surface`,
+		)
+	}
+
+	const handle = (e: any): RichTextEditorHandle => ({
+		getHTML: () => e.getHTML(),
+		setHTML: (html: string) => {
+			applyingValue.current = true
+			try {
+				e.setHTML(html)
+				lastEmitted.current = html
+			} finally {
+				applyingValue.current = false
+			}
+		},
+		apply: (format: RichTextFormat) => {
+			if (format === 'link') return
+			if (UNSUPPORTED.has(format) || !e.applyFormat(format)) {
+				reportUnsupported(format)
+				return
+			}
+
+			emitChange()
+		},
+		linkTo: (url: string, anchor?: string) => {
+			e.linkTo(url, anchor ?? null)
+			emitChange()
+		},
+		removeLink: () => {
+			e.removeLink()
+			emitChange()
+		},
+		isActive: (format: RichTextFormat) =>
+			!UNSUPPORTED.has(format) && Boolean(e.isFormatActive(format)),
+		undo: () => e.undo(),
+		redo: () => e.redo(),
+		split: () => {
+			const ok = Boolean(e.split())
+			if (ok) emitChange()
+			return ok
+		},
+		join: () => {
+			const ok = Boolean(e.join())
+			if (ok) emitChange()
+			return ok
+		},
+		indent: () => {
+			const ok = Boolean(e.indent())
+			if (ok) emitChange()
+			return ok
+		},
+		outdent: () => {
+			const ok = Boolean(e.outdent())
+			if (ok) emitChange()
+			return ok
+		},
+		canIndent: () => Boolean(e.canIndent()),
+		canOutdent: () => Boolean(e.canOutdent()),
+		focus: () => e.focus(),
+		blur: () => e.blur(),
+		isFocused: () => e.focused(),
+		native: e,
+	})
+
+	useEffect(() => {
+		const e = editor()
+		if (!e) return
+
+		e.onTextChange = () => emitChange()
+		e.onSelectionChange = (start: number, end: number, active: any) => {
+			const formats: RichTextFormat[] = []
+			const count = active?.count ?? 0
+			for (let i = 0; i < count; i++) {
+				formats.push(active.objectAtIndex(i))
+			}
+
+			props.onSelectionChange?.({ start, end, active: formats })
+		}
+
+		e.onFocus = () => props.onFocus?.()
+		e.onBlur = () => props.onBlur?.()
+
+		if (props.placeholder !== undefined) e.placeholder = props.placeholder
+		e.editable = props.editable !== false
+
+		if (props.value !== undefined) {
+			applyingValue.current = true
+			try {
+				e.setHTML(props.value)
+			} finally {
+				applyingValue.current = false
+			}
+		}
+
+		if (props.autofocus) e.focus()
+
+		if (props.ios) Object.assign(e, props.ios)
+		props.onReady?.()
+
+		return () => {
+			e.onTextChange = null
+			e.onSelectionChange = null
+			e.onFocus = null
+			e.onBlur = null
+		}
+	}, [])
+
+	// `value` lands like a controlled prop, minus the loop: text the editor
+	// emitted through onChange is never pushed back; any other change is an
+	// external reset (Aztec-iOS setHTML is non-undoable, matching Android).
+	useEffect(() => {
+		const e = editor()
+		if (!e || props.value === undefined) return
+		if (props.value === lastEmitted.current) return
+		applyingValue.current = true
+		try {
+			e.setHTML(props.value)
+		} finally {
+			applyingValue.current = false
+		}
+	}, [props.value])
+
+	useEffect(() => {
+		const e = editor()
+		if (e) e.editable = props.editable !== false
+	}, [props.editable])
+
+	useEffect(() => {
+		const e = editor()
+		if (e && props.placeholder !== undefined) e.placeholder = props.placeholder
+	}, [props.placeholder])
+
+	<xplatrichtext
+		ref={bindHost}
 		id={props.id}
 		className={props.className}
 		style={props.style}
-		text="Rich text editing is not supported on iOS yet."
+		row={props.row}
+		col={props.col}
+		rowSpan={props.rowSpan}
+		colSpan={props.colSpan}
+		dock={props.dock}
+		left={props.left}
+		top={props.top}
+		flexGrow={props.flexGrow}
+		flexShrink={props.flexShrink}
+		alignSelf={props.alignSelf}
+		order={props.order}
 	/>;
 }

package/src/RichTextEditor.windows.tsrx

@@ -0,0 +1,15 @@
+/** @jsxImportSource @nativescript-community/octane */
+import type { RichTextEditorProps } from './types'
+
+export const supported = false
+
+/** Windows bring-up is deferred — renders the placeholder so a shared
+ *  screen still mounts. */
+export function RichTextEditor(props: RichTextEditorProps) @{
+	<label
+		id={props.id}
+		className={props.className}
+		style={props.style}
+		text="Rich text editing is not supported on Windows yet."
+	/>;
+}

package/src/browser-transport.web.ts

@@ -0,0 +1,119 @@
+const formats = [
+	'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',
+]
+
+/** Internal document transport. Engine handles never cross the WebKit boundary. */
+export function installEditorDocument(render: (props: any) => void) {
+	let handle: any = null
+	const pending: { method: string; args: any[] }[] = []
+	let selection = { start: 0, end: 0, active: [] as string[] }
+	const post = (event: string, extra: object = {}) => {
+		const packet = {
+			event,
+			html: handle?.getHTML() ?? '',
+			json: handle?.getJSON?.() ?? null,
+			focused: handle?.isFocused() ?? false,
+			selection,
+			...extra,
+		}
+
+		;(window as any).webkit.messageHandlers.editor.postMessage(JSON.stringify(packet))
+	}
+
+	const snapshot = (event: string) => {
+		setTimeout(() => {
+			if (!handle) {
+				return
+			}
+
+			selection = { ...selection, active: formats.filter((f) => handle.isActive(f)) }
+			post(event)
+		}, 0)
+	}
+
+	const command = (packet: { method: string; args: any[] }) => {
+		if (packet.method === 'props') {
+			render({ ...packet.args[0], ...callbacks })
+			if (handle) {
+				snapshot('snapshot')
+			}
+		} else if (!handle) {
+			pending.push(packet)
+		} else if (
+			[
+				'setHTML',
+				'setJSON',
+				'apply',
+				'linkTo',
+				'removeLink',
+				'undo',
+				'redo',
+				'focus',
+				'blur',
+			].includes(packet.method)
+		) {
+			handle[packet.method]?.(...packet.args)
+			snapshot('snapshot')
+		}
+	}
+
+	const callbacks = {
+		ref(next: any) {
+			if (!next || next === handle) {
+				return
+			}
+
+			handle = next
+			snapshot('ready')
+			for (const packet of pending.splice(0)) {
+				command(packet)
+			}
+		},
+		onChange: () => snapshot('change'),
+		onSelectionChange(next: typeof selection) {
+			selection = next
+			snapshot('selection')
+		},
+		onFocus: () => snapshot('focus'),
+		onBlur: () => snapshot('blur'),
+	}
+
+	;(window as any).__xplatEditorReceive = (serialized: string) => {
+		try {
+			command(JSON.parse(serialized))
+		} catch (error) {
+			post('error', { message: String(error) })
+		}
+	}
+
+	window.addEventListener('error', (event) => post('error', { message: event.message }))
+	window.addEventListener('unhandledrejection', (event) =>
+		post('error', { message: String(event.reason) }),
+	)
+
+	post('boot')
+}

package/src/host-session.macos.ts

@@ -0,0 +1,142 @@
+import type { RichTextEditorHandle, RichTextEditorProps, RichTextFormat } from './types'
+
+export interface EditorPacket {
+	event: string
+	html?: string
+	json?: any
+	selection?: { start: number; end: number; active: RichTextFormat[] }
+	focused?: boolean
+	message?: string
+}
+
+/** Internal transport adapter: synchronous getters read the last WebKit snapshot. */
+export function createEditorSession(
+	send: (packet: string) => void,
+	native: any,
+	readProps: () => RichTextEditorProps & {
+		onJSONChange?: (doc: any) => void
+		onJSONReady?: (ok: boolean) => void
+	},
+) {
+	let disposed = false
+	let ready = false
+	let html = ''
+	let json: any = null
+	let active: RichTextFormat[] = []
+	let focused = false
+	let pending: string[] = []
+	const command = (method: string, ...args: any[]) => {
+		if (disposed) {
+			return
+		}
+
+		const packet = JSON.stringify({ method, args })
+		if (ready) {
+			send(packet)
+		} else {
+			pending.push(packet)
+		}
+	}
+
+	const handle: RichTextEditorHandle & { getJSON(): any; setJSON(doc: any): void } = {
+		getHTML: () => html,
+		setHTML: (value) => command('setHTML', value),
+		getJSON: () => json,
+		setJSON: (doc) => command('setJSON', doc),
+		apply: (format) => command('apply', format),
+		linkTo: (url, anchor) => command('linkTo', url, anchor),
+		removeLink: () => command('removeLink'),
+		isActive: (format) => active.includes(format),
+		undo: () => command('undo'),
+		redo: () => command('redo'),
+		// Structural commands are Aztec-only for now: the AppKit transport
+		// is one-way async dispatch, so a synchronous "applied" result cannot
+		// be reported and a fire-and-forget forward would lie to the caller.
+		split: () => false,
+		join: () => false,
+		indent: () => false,
+		outdent: () => false,
+		canIndent: () => false,
+		canOutdent: () => false,
+		focus: () => command('focus'),
+		blur: () => command('blur'),
+		isFocused: () => focused,
+		native,
+	}
+
+	return {
+		handle,
+		update(props: object) {
+			command('props', props)
+		},
+		receive(serialized: string) {
+			if (disposed) {
+				return
+			}
+
+			const packet: EditorPacket = JSON.parse(serialized)
+			const props = readProps()
+			if (packet.html !== undefined) {
+				html = packet.html
+			}
+
+			if ('json' in packet) {
+				json = packet.json
+			}
+
+			if (packet.selection) {
+				active = packet.selection.active
+			}
+
+			if (packet.focused !== undefined) {
+				focused = packet.focused
+			}
+
+			switch (packet.event) {
+				case 'boot':
+					ready = true
+					for (const packet of pending) {
+						send(packet)
+					}
+
+					pending = []
+					break
+				case 'ready':
+					props.onJSONReady?.(true)
+					props.onReady?.()
+					break
+				case 'change':
+					props.onChange?.(html)
+					if (json) {
+						props.onJSONChange?.(json)
+					}
+
+					break
+				case 'selection':
+					if (packet.selection) {
+						props.onSelectionChange?.(packet.selection)
+					}
+
+					break
+				case 'focus':
+					props.onFocus?.()
+					break
+				case 'blur':
+					props.onBlur?.()
+					break
+				case 'error':
+					console.error('[macos-editor] ' + packet.message)
+					break
+			}
+		},
+		dispose() {
+			if (disposed) {
+				return
+			}
+
+			disposed = true
+			pending = []
+			native.dispose()
+		},
+	}
+}

package/src/index.macos.ts

@@ -1,10 +1,4 @@
-import type { RichTextEditorProps } from './types'
-
-export const supported = false
-
-/** The macOS editor is deferred; the tiptap facade covers desktop needs. */
-export function RichTextEditor(_props: RichTextEditorProps): null {
-	return null
-}
-
+export { RichTextEditor } from './Editor.macos'
+/** The AppKit/WKWebView backend is implemented. */
+export const supported = true
 export type * from './types'

package/src/index.ts

@@ -1,5 +1,5 @@
 // Keep this relative import extensionless so the NativeScript resolver picks
-// the Android (Aztec) or iOS (stub until the Swift facade lands) component
-// for the current build target.
+// the Android (Aztec) or iOS (AztecEditor-iOS facade) component for the
+// current build target.
 export { RichTextEditor, supported } from './RichTextEditor'
 export type * from './types'

package/src/types.ts

@@ -1,6 +1,8 @@
-/** Supported on Android today (WordPress Aztec); iOS is stubbed until the
- *  Swift-facade bring-up. Web/macOS/Windows route through the tiptap facade
- *  instead of this leaf. */
+import type { Octane } from 'octane/jsx-runtime'
+
+/** Android uses WordPress Aztec; iOS uses AztecEditor-iOS; AppKit uses
+ * StarterKit in WKWebView. Web/Windows use the tiptap facade instead of
+ * this leaf. */
 export type RichTextFormat =
 	| 'bold'
 	| 'italic'
@@ -31,25 +33,68 @@ export type RichTextFormat =
 export interface RichTextEditorHandle {
 	/** Serialized document HTML (Aztec's "plain" HTML — no contenteditable
 	 *  markup). */
+	/** AppKit: returns the latest WebKit snapshot; commands are asynchronous. */
 	getHTML(): string
-	/** Replace the document; resets Aztec's undo history. */
+	/** Replace the document. Android resets Aztec history; the iOS
+	 *  `setHTML` variant is likewise non-undoable; AppKit uses engine
+	 *  history. */
 	setHTML(html: string): void
 	/** Toggle a format at the current selection. `link` needs
-	 *  `linkTo(url, anchor)` instead. */
+	 *  `linkTo(url, anchor)` instead. iOS has no taskList or text-alignment
+	 *  engine support — those calls report a console warning and do not
+	 *  change the document. */
 	apply(format: RichTextFormat): void
 	/** Insert or re-target a link over the current selection. */
 	linkTo(url: string, anchor?: string): void
 	removeLink(): void
-	/** Formats active at the selection — powers toolbar highlight state. */
+	/** Formats active at the selection — powers toolbar highlight state.
+	 *  iOS always reports false for taskList and the align* formats (no
+	 *  engine support). */
 	isActive(format: RichTextFormat): boolean
 	/** Android: Aztec's history batches keyboard input only — format
-	 *  toggles and programmatic edits do not register. */
+	 *  toggles and programmatic edits do not register. iOS: the engine
+	 *  undoManager covers format toggles and keyboard input; `setHTML` and
+	 *  split/join edits sit outside it. */
 	undo(): void
 	redo(): void
+	/** Split the block at the caret into two siblings — the Enter-key
+	 *  semantic (a non-collapsed selection is deleted first). Android: a
+	 *  real block break through Aztec's watcher pipeline — a caret inside
+	 *  a list item produces a sibling `<li>`. iOS routes through Aztec's
+	 *  `insertText` newline handling for the same semantics. Inside hidden
+	 *  block markup Aztec does not understand (`<div data-*>` wrappers),
+	 *  this is a line break, not a new node — it serializes as `<br>`.
+	 *  Returns false when
+	 *  there is no valid selection. AppKit: returns false — the engine
+	 *  transport is asynchronous and cannot report application. */
+	split(): boolean
+	/** Merge the block at the caret into the previous block — the
+	 *  Backspace-at-block-start semantic. Returns false unless the
+	 *  selection is a collapsed caret directly after a block boundary. */
+	join(): boolean
+	/** Demote the block(s) in the selection. Aztec semantics: a list item
+	 *  nests under its previous sibling; a plain paragraph, heading,
+	 *  quote, or preformat line gains a literal `\t` indent. Hidden
+	 *  `<div data-*>` nodes are opaque to Aztec and cannot be demoted.
+	 *  iOS: `increaseIndent` acts on list/quote depth and falls back to a
+	 *  `\t` insert on plain blocks. Returns false when Aztec reports no
+	 *  indentable selection (iOS: when the view is not editable). */
+	indent(): boolean
+	/** Promote the block(s) in the selection one level — the inverse of
+	 *  `indent()`. iOS has no plain-block outdent, so this applies only to
+	 *  list items and blockquotes. Returns false when Aztec reports no
+	 *  outdentable selection. */
+	outdent(): boolean
+	/** Whether `indent()` can apply to the current selection. */
+	canIndent(): boolean
+	/** Whether `outdent()` can apply to the current selection. */
+	canOutdent(): boolean
 	focus(): void
 	blur(): void
 	isFocused(): boolean
-	/** The platform surface — `AztecText` on Android. */
+	/** The platform surface — `AztecText` on Android, the
+	 *  `XplatAztecEditorView` facade on iOS. */
+	/** AppKit: the XplatEditorHost transport, not the browser engine instance. */
 	native: any
 }
 
@@ -77,7 +122,7 @@ export interface RichTextEditorProps {
 	onFocus?: () => void
 	onBlur?: () => void
 	/** Imperative handle — fires once when the native editor exists. */
-	bind?: (handle: RichTextEditorHandle) => void
+	ref?: Octane.Ref<RichTextEditorHandle>
 	/** Per-platform escape bag — properties are assigned onto the native
 	 *  `AztecText` after the leaf's own props. */
 	android?: Record<string, any>

package/types/browser-transport.d.ts

@@ -0,0 +1,2 @@
+/** Internal WebKit document transport installer. */
+export declare function installEditorDocument(render: (props: any) => void): void

package/types/index.macos.d.ts

@@ -0,0 +1,5 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { RichTextEditorProps } from '../src/types'
+export declare const RichTextEditor: UniversalComponent<RichTextEditorProps>
+export declare const supported: boolean
+export type * from '../src/types'

package/types/macos-host.d.ts

@@ -0,0 +1,11 @@
+import type { UniversalComponent } from 'octane/universal'
+import type { RichTextEditorProps } from '../src/types'
+/** Internal shared editor host. */
+export declare const NativeEditor: UniversalComponent<
+	RichTextEditorProps & {
+		browser: string
+		json?: any
+		onJSONReady?: (ok: boolean) => void
+		onJSONChange?: (doc: any) => void
+	}
+>