@octanejs/lexical 0.1.2

package/src/shared/LexicalContentEditableElement.tsrx

@@ -0,0 +1,101 @@
+// Ported from @lexical/react/src/shared/LexicalContentEditableElement.tsx.
+// React's `forwardRef` + `mergeRefs` becomes octane's ref-as-prop + a multi-ref
+// array (`ref={[userRef, handleRef]}`). `handleRef` binds the editor to the DOM
+// node via setRootElement — octane fires callback refs at commit with a connected
+// node, the same timing React's ref gets, and calls them with null on unmount.
+//
+// The full ARIA set + `{...rest}` passthrough mirror @lexical/react exactly:
+// boolean ARIA values are stringified (octane drops `false` as an attribute), and
+// unknown props flow through via `rest` (everything not consumed by name).
+import { useCallback, useLayoutEffect, useState } from 'octane';
+
+// Props consumed by name — everything else flows through to the <div> via `rest`.
+const NAMED_PROPS = new Set([
+	'editor',
+	'ariaActiveDescendant',
+	'ariaAutoComplete',
+	'ariaControls',
+	'ariaDescribedBy',
+	'ariaErrorMessage',
+	'ariaExpanded',
+	'ariaInvalid',
+	'ariaLabel',
+	'ariaLabelledBy',
+	'ariaMultiline',
+	'ariaOwns',
+	'ariaRequired',
+	'autoCapitalize',
+	'className',
+	'contentEditable',
+	'id',
+	'role',
+	'spellCheck',
+	'style',
+	'tabIndex',
+	'ref',
+	'placeholder',
+	'data-testid',
+]);
+
+export function ContentEditableElement(props) @{
+	const editor = props.editor;
+	const [isEditable, setEditable] = useState(editor.isEditable());
+
+	const handleRef = useCallback((rootElement) => {
+		// defaultView is required for a root element. In multi-window setups it may
+		// not exist at certain points.
+		if (rootElement && rootElement.ownerDocument && rootElement.ownerDocument.defaultView) {
+			editor.setRootElement(rootElement);
+		} else {
+			editor.setRootElement(null);
+		}
+	}, [editor]);
+
+	useLayoutEffect(() => {
+		setEditable(editor.isEditable());
+		return editor.registerEditableListener((currentIsEditable) => {
+			setEditable(currentIsEditable);
+		});
+	}, [editor]);
+
+	const role =
+		props.role != null ? props.role : 'textbox';
+	const rest: Record<string, any> = {};
+	for (const k in props) {
+		if (!NAMED_PROPS.has(k)) {
+			rest[k] = props[k];
+		}
+	}
+	// Route `class` through the spread (setSpread omits an absent/undefined key) so
+	// an unset className produces NO attribute — matching React. An explicit
+	// `class={undefined}` binding would emit `class=""` on the spread/de-opt path.
+	if (props.className != null) {
+		rest['class'] = props.className;
+	}
+
+	<div
+		ref={props.ref != null ? [props.ref, handleRef] : handleRef}
+		aria-activedescendant={isEditable ? props.ariaActiveDescendant : undefined}
+		aria-autocomplete={isEditable ? props.ariaAutoComplete : 'none'}
+		aria-controls={isEditable ? props.ariaControls : undefined}
+		aria-describedby={props.ariaDescribedBy}
+		aria-errormessage={props.ariaErrorMessage != null ? props.ariaErrorMessage : undefined}
+		aria-expanded={isEditable && role === 'combobox' ? String(!!props.ariaExpanded) : undefined}
+		aria-invalid={props.ariaInvalid != null ? props.ariaInvalid : undefined}
+		aria-label={props.ariaLabel}
+		aria-labelledby={props.ariaLabelledBy}
+		aria-multiline={props.ariaMultiline}
+		aria-owns={isEditable ? props.ariaOwns : undefined}
+		aria-readonly={isEditable ? undefined : 'true'}
+		aria-required={props.ariaRequired != null ? String(props.ariaRequired) : undefined}
+		autocapitalize={props.autoCapitalize}
+		contenteditable={isEditable ? 'true' : 'false'}
+		data-testid={props['data-testid']}
+		id={props.id}
+		role={role}
+		spellcheck={props.spellCheck === false ? 'false' : 'true'}
+		style={props.style}
+		tabindex={props.tabIndex}
+		{...rest}
+	/>
+}

package/src/shared/LexicalDecorators.tsrx

@@ -0,0 +1,88 @@
+// Ported from @lexical/react/src/shared/useDecorators.tsx (the LegacyDecorators
+// path used by Rich/PlainTextPlugin). React's `useDecorators` hook is realized as
+// a `Decorators` COMPONENT here: each <Decorators/> usage is its own octane scope,
+// so its useState/useEffect/useMemo get per-instance identity automatically.
+//
+// Each decorator node renders into the DOM element Lexical created for it, via a
+// portal. octane's createPortal lowers to portal() only as a DIRECT child of a host
+// element (a createPortal VALUE is inert), so each portal lives inside its own
+// `DecoratorPortal` (a display:contents wrapper — the content escapes into the
+// node's element).
+import {
+	useState,
+	useEffect,
+	useLayoutEffect,
+	useMemo,
+	flushSync,
+	createElement,
+	createPortal,
+	Suspense,
+} from 'octane';
+
+function DecoratorPortalBody(props) {
+	return createElement(props.ErrorBoundary, {
+		onError: props.onError,
+		children: createElement(Suspense, { fallback: null, children: props.decorator }),
+	});
+}
+
+function DecoratorPortal(props) {
+	return createPortal(DecoratorPortalBody, props.element, props.bodyProps);
+}
+
+export function Decorators(props) {
+	const editor = props.editor;
+	const ErrorBoundary = props.ErrorBoundary;
+
+	const [decorators, setDecorators] = useState(() => editor.getDecorators());
+
+	// Subscribe to decorator changes.
+	useLayoutEffect(() => {
+		return editor.registerDecoratorListener((nextDecorators) => {
+			flushSync(() => {
+				setDecorators(nextDecorators);
+			});
+		});
+	}, [editor]);
+
+	useEffect(() => {
+		// If the content editable mounts before the subscription is added, nothing
+		// renders on the initial pass — re-read on mount to cover that.
+		setDecorators(editor.getDecorators());
+	}, [editor]);
+
+	// Resolve each decorator node's DOM element + its decorator content.
+	const entries = useMemo(() => {
+		const out = [];
+		const decoratorKeys = Object.keys(decorators);
+		for (let i = 0; i < decoratorKeys.length; i++) {
+			const nodeKey = decoratorKeys[i];
+			const element = editor.getElementByKey(nodeKey);
+			if (element !== null) {
+				out.push({ nodeKey, element, decorator: decorators[nodeKey] });
+			}
+		}
+		return out;
+	}, [decorators, editor]);
+
+	// Render nothing when there are no decorators (matches @lexical/react). Each
+	// decorator is a portal into its node's element — a keyed list of DecoratorPortal
+	// components, each returning a createPortal VALUE (octane renders portals at any
+	// position, so no wrapper element is needed).
+	if (entries.length === 0) {
+		return null;
+	}
+	return <>
+		{entries.map(
+			(entry) => <DecoratorPortal
+				key={entry.nodeKey}
+				element={entry.element}
+				bodyProps={{
+					ErrorBoundary,
+					onError: (e) => editor._onError(e),
+					decorator: entry.decorator,
+				}}
+			/>,
+		)}
+	</>;
+}

package/src/shared/LexicalMenu.tsrx

@@ -0,0 +1,275 @@
+// The LexicalMenu component + default renderer, ported from
+// @lexical/react/src/shared/LexicalMenu.tsx. A `.tsrx` component (auto-slotted
+// hooks). The hooks (useMenuAnchorRef / useDynamicPositioning) + non-component
+// pieces live in the sibling `.ts` files.
+import {
+	$splitNodeContainingQuery,
+	scrollIntoViewIfNeeded,
+	SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND,
+} from './menuShared';
+import {
+	COMMAND_PRIORITY_LOW,
+	KEY_ARROW_DOWN_COMMAND,
+	KEY_ARROW_UP_COMMAND,
+	KEY_ENTER_COMMAND,
+	KEY_ESCAPE_COMMAND,
+	KEY_TAB_COMMAND,
+	mergeRegister,
+} from 'lexical';
+import { createPortal, useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'octane';
+
+function MenuItem(props) @{
+	<li
+		tabindex={-1}
+		class={props.isSelected ? 'item selected' : 'item'}
+		ref={props.option.setRefElement}
+		role="option"
+		aria-selected={props.isSelected ? 'true' : 'false'}
+		id={'typeahead-item-' + props.index}
+		onMouseEnter={props.onMouseEnter}
+		onClick={props.onClick}
+	>
+		{props.option.icon}
+		<span class="text">{props.option.title}</span>
+	</li>
+}
+
+function DefaultMenu(props) @{
+	<div class="typeahead-popover mentions-menu">
+		<ul>{props.options.map(
+			(option, i) => <MenuItem
+				key={option.key}
+				index={i}
+				isSelected={props.selectedIndex === i}
+				onClick={() => {
+					props.setHighlightedIndex(i);
+					props.selectOptionAndCleanUp(option);
+				}}
+				onMouseEnter={() => props.setHighlightedIndex(i)}
+				option={option}
+			/>,
+		)}</ul>
+	</div>
+}
+
+export function LexicalMenu(props) {
+	const close = props.close;
+	const editor = props.editor;
+	const anchorElementRef = props.anchorElementRef;
+	const resolution = props.resolution;
+	const options = props.options;
+	const menuRenderFnProp = props.menuRenderFn;
+	const onSelectOption = props.onSelectOption;
+	const shouldSplitNodeWithQuery = props.shouldSplitNodeWithQuery === true;
+	const commandPriority =
+		props.commandPriority != null ? props.commandPriority : COMMAND_PRIORITY_LOW;
+	const preselectFirstItem = props.preselectFirstItem !== false;
+
+	const [rawSelectedIndex, setHighlightedIndex] = useState(null);
+	const selectedIndex =
+		rawSelectedIndex !== null ? Math.min(options.length - 1, rawSelectedIndex) : null;
+
+	const matchingString = resolution.match && resolution.match.matchingString;
+
+	useEffect(() => {
+		if (preselectFirstItem) {
+			setHighlightedIndex(0);
+		}
+	}, [matchingString, preselectFirstItem]);
+
+	const selectOptionAndCleanUp = useCallback((selectedEntry) => {
+		editor.update(() => {
+			const textNodeContainingQuery =
+				resolution.match != null && shouldSplitNodeWithQuery
+					? $splitNodeContainingQuery(resolution.match)
+					: null;
+			onSelectOption(
+				selectedEntry,
+				textNodeContainingQuery,
+				close,
+				resolution.match ? resolution.match.matchingString : '',
+			);
+		});
+	}, [editor, shouldSplitNodeWithQuery, resolution.match, onSelectOption, close]);
+
+	const updateSelectedIndex = useCallback((index) => {
+		const rootElem = editor.getRootElement();
+		if (rootElem !== null) {
+			rootElem.setAttribute('aria-activedescendant', 'typeahead-item-' + index);
+			setHighlightedIndex(index);
+		}
+	}, [editor]);
+
+	useEffect(() => {
+		return () => {
+			const rootElem = editor.getRootElement();
+			if (rootElem !== null) {
+				rootElem.removeAttribute('aria-activedescendant');
+			}
+		};
+	}, [editor]);
+
+	useLayoutEffect(() => {
+		if (options === null) {
+			setHighlightedIndex(null);
+		} else if (selectedIndex === null && preselectFirstItem) {
+			updateSelectedIndex(0);
+		}
+	}, [options, selectedIndex, updateSelectedIndex, preselectFirstItem]);
+
+	useEffect(() => {
+		return mergeRegister(
+			editor.registerCommand(
+				SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND,
+				({ option }) => {
+					if (option.ref && option.ref.current != null) {
+						scrollIntoViewIfNeeded(option.ref.current);
+						return true;
+					}
+					return false;
+				},
+				commandPriority,
+			),
+		);
+	}, [editor, updateSelectedIndex, commandPriority]);
+
+	useEffect(() => {
+		return mergeRegister(
+			editor.registerCommand(
+				KEY_ARROW_DOWN_COMMAND,
+				(event) => {
+					if (options !== null && options.length) {
+						const newSelectedIndex =
+							selectedIndex === null
+								? 0
+								: selectedIndex !== options.length - 1
+									? selectedIndex + 1
+									: 0;
+						updateSelectedIndex(newSelectedIndex);
+						const option = options[newSelectedIndex];
+						if (!option) {
+							updateSelectedIndex(-1);
+							event.preventDefault();
+							event.stopImmediatePropagation();
+							return true;
+						}
+						if (option.ref && option.ref.current) {
+							editor.dispatchCommand(SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND, {
+								index: newSelectedIndex,
+								option,
+							});
+						}
+						event.preventDefault();
+						event.stopImmediatePropagation();
+					}
+					return true;
+				},
+				commandPriority,
+			),
+			editor.registerCommand(
+				KEY_ARROW_UP_COMMAND,
+				(event) => {
+					if (options !== null && options.length) {
+						const newSelectedIndex =
+							selectedIndex === null
+								? options.length - 1
+								: selectedIndex !== 0
+									? selectedIndex - 1
+									: options.length - 1;
+						updateSelectedIndex(newSelectedIndex);
+						const option = options[newSelectedIndex];
+						if (!option) {
+							updateSelectedIndex(-1);
+							event.preventDefault();
+							event.stopImmediatePropagation();
+							return true;
+						}
+						if (option.ref && option.ref.current) {
+							scrollIntoViewIfNeeded(option.ref.current);
+						}
+						event.preventDefault();
+						event.stopImmediatePropagation();
+					}
+					return true;
+				},
+				commandPriority,
+			),
+			editor.registerCommand(
+				KEY_ESCAPE_COMMAND,
+				(event) => {
+					event.preventDefault();
+					event.stopImmediatePropagation();
+					close();
+					return true;
+				},
+				commandPriority,
+			),
+			editor.registerCommand(
+				KEY_TAB_COMMAND,
+				(event) => {
+					if (options === null || selectedIndex === null || options[selectedIndex] == null) {
+						return false;
+					}
+					event.preventDefault();
+					event.stopImmediatePropagation();
+					selectOptionAndCleanUp(options[selectedIndex]);
+					return true;
+				},
+				commandPriority,
+			),
+			editor.registerCommand(
+				KEY_ENTER_COMMAND,
+				(event) => {
+					if (
+						options === null || selectedIndex === null || options[selectedIndex] == null ||
+							event && event.shiftKey
+					) {
+						return false;
+					}
+					if (event !== null) {
+						event.preventDefault();
+						event.stopImmediatePropagation();
+					}
+					selectOptionAndCleanUp(options[selectedIndex]);
+					return true;
+				},
+				commandPriority,
+			),
+		);
+	}, [
+		selectOptionAndCleanUp,
+		close,
+		editor,
+		options,
+		selectedIndex,
+		updateSelectedIndex,
+		commandPriority,
+	]);
+
+	const listItemProps = useMemo(
+		() => ({ options, selectOptionAndCleanUp, selectedIndex, setHighlightedIndex }),
+		[selectOptionAndCleanUp, selectedIndex, options],
+	);
+
+	if (anchorElementRef.current === null) {
+		return null;
+	}
+	// A custom menuRenderFn returns a portal directly (React-compatible); the default
+	// renders DefaultMenu into the anchor. octane renders a createPortal VALUE at any
+	// position, so no host-element wrapper is needed.
+	if (menuRenderFnProp != null) {
+		return menuRenderFnProp(
+			anchorElementRef,
+			listItemProps,
+			resolution.match ? resolution.match.matchingString : '',
+		);
+	}
+	return options.length
+		? createPortal(DefaultMenu, anchorElementRef.current, {
+				options,
+				selectedIndex,
+				selectOptionAndCleanUp,
+				setHighlightedIndex,
+			})
+		: null;
+}

package/src/shared/internal.ts

@@ -0,0 +1,32 @@
+// Slot mechanics shared by the binding's plain-`.ts` hooks (copied from
+// @octanejs/router / @octanejs/query). The octane compiler injects a per-call-site
+// Symbol slot into every hook call in `.tsrx`/`.tsx`, but these binding files are
+// NOT compiled — so a hook here receives the caller's slot as its trailing argument
+// and derives a distinct sub-slot for each base hook it composes.
+
+// Derive a stable, distinct sub-slot from a wrapper's slot, namespaced per hook so
+// composing multiple base hooks gives each its own identity.
+// Memoized: subSlot runs on EVERY hook call every render, and the naive form
+// pays a string concat + global symbol-registry lookup each time. The cache is
+// keyed by the slot symbol itself; the minted value is byte-identical to the
+// uncached Symbol.for result, so identity is preserved across HMR re-evals and
+// the per-package copies of this helper. Key universe is bounded: slots are
+// per-call-site module constants (never minted per render).
+const subSlotCache = new Map<symbol, Map<string, symbol>>();
+export function subSlot(slot: symbol | undefined, tag: string): symbol | undefined {
+	if (slot === undefined) return undefined;
+	let byTag = subSlotCache.get(slot);
+	if (byTag === undefined) subSlotCache.set(slot, (byTag = new Map()));
+	let sym = byTag.get(tag);
+	if (sym === undefined) byTag.set(tag, (sym = Symbol.for((slot.description ?? '') + ':' + tag)));
+	return sym;
+}
+
+// Split the compiler-injected trailing slot off a hook's args. Needed for hooks
+// with OPTIONAL user args, where the slot can't be located positionally (the
+// compiler always appends it last). Returns the user args + the slot.
+export function splitSlot(args: any[]): [any[], symbol | undefined] {
+	const tail = args[args.length - 1];
+	const slot = typeof tail === 'symbol' ? (tail as symbol) : undefined;
+	return [slot !== undefined ? args.slice(0, -1) : args, slot];
+}

package/src/shared/menuShared.ts

@@ -0,0 +1,152 @@
+import type { LexicalCommand, LexicalEditor, TextNode } from 'lexical';
+import {
+	$getSelection,
+	$isRangeSelection,
+	CAN_USE_DOM,
+	createCommand,
+	isDOMShadowRoot,
+} from 'lexical';
+
+// Non-hook, non-JSX shared pieces of @lexical/react/src/shared/LexicalMenu.tsx
+// (the hooks live in useMenuAnchorRef.ts / useDynamicPositioning.ts; the LexicalMenu
+// component in LexicalMenu.tsrx). Plain `.ts` — no compiler involvement.
+
+export type MenuTextMatch = {
+	leadOffset: number;
+	matchingString: string;
+	replaceableString: string;
+};
+
+export type MenuResolution = {
+	match?: MenuTextMatch;
+	getRect: () => DOMRect;
+};
+
+export type MenuRef = { current: HTMLElement | null };
+
+export type MenuRenderFn<TOption extends MenuOption> = (
+	anchorElementRef: MenuRef,
+	itemProps: {
+		selectedIndex: number | null;
+		selectOptionAndCleanUp: (option: TOption) => void;
+		setHighlightedIndex: (index: number) => void;
+		options: TOption[];
+	},
+	matchingString: string,
+) => unknown;
+
+export type TriggerFn = (text: string, editor: LexicalEditor) => MenuTextMatch | null;
+
+export class MenuOption {
+	key: string;
+	ref?: MenuRef;
+	icon?: unknown;
+	title?: unknown;
+
+	constructor(key: string) {
+		this.key = key;
+		this.ref = { current: null };
+		this.setRefElement = this.setRefElement.bind(this);
+	}
+
+	setRefElement(element: HTMLElement | null) {
+		this.ref = { current: element };
+	}
+}
+
+export const SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND: LexicalCommand<{
+	index: number;
+	option: MenuOption;
+}> = createCommand('SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND');
+
+export const scrollIntoViewIfNeeded = (target: HTMLElement) => {
+	const typeaheadContainerNode = target.closest('#typeahead-menu') as HTMLElement | null;
+	if (!typeaheadContainerNode) {
+		return;
+	}
+	const typeaheadRect = typeaheadContainerNode.getBoundingClientRect();
+	if (typeaheadRect.top + typeaheadRect.height > window.innerHeight) {
+		typeaheadContainerNode.scrollIntoView({ block: 'center' });
+	}
+	if (typeaheadRect.top < 0) {
+		typeaheadContainerNode.scrollIntoView({ block: 'center' });
+	}
+	target.scrollIntoView({ block: 'nearest' });
+};
+
+function getFullMatchOffset(documentText: string, entryText: string, offset: number): number {
+	let triggerOffset = offset;
+	for (let i = triggerOffset; i <= entryText.length; i++) {
+		if (documentText.slice(-i) === entryText.substring(0, i)) {
+			triggerOffset = i;
+		}
+	}
+	return triggerOffset;
+}
+
+export function $splitNodeContainingQuery(match: MenuTextMatch): TextNode | null {
+	const selection = $getSelection();
+	if (!$isRangeSelection(selection) || !selection.isCollapsed()) {
+		return null;
+	}
+	const anchor = selection.anchor;
+	if (anchor.type !== 'text') {
+		return null;
+	}
+	const anchorNode = anchor.getNode();
+	if (!anchorNode.isSimpleText()) {
+		return null;
+	}
+	const selectionOffset = anchor.offset;
+	const textContent = anchorNode.getTextContent().slice(0, selectionOffset);
+	const characterOffset = match.replaceableString.length;
+	const queryOffset = getFullMatchOffset(textContent, match.matchingString, characterOffset);
+	const startOffset = selectionOffset - queryOffset;
+	if (startOffset < 0) {
+		return null;
+	}
+	let newNode;
+	if (startOffset === 0) {
+		[newNode] = anchorNode.splitText(selectionOffset);
+	} else {
+		[, newNode] = anchorNode.splitText(startOffset, selectionOffset);
+	}
+	return newNode;
+}
+
+export function isTriggerVisibleInNearestScrollContainer(
+	targetElement: HTMLElement,
+	containerElement: HTMLElement,
+): boolean {
+	const tRect = targetElement.getBoundingClientRect();
+	const cRect = containerElement.getBoundingClientRect();
+	const VISIBILITY_MARGIN_PX = 6;
+	return (
+		tRect.top >= cRect.top - VISIBILITY_MARGIN_PX &&
+		tRect.top <= cRect.bottom + VISIBILITY_MARGIN_PX
+	);
+}
+
+export function setContainerDivAttributes(containerDiv: HTMLElement, className?: string) {
+	if (className != null) {
+		containerDiv.className = className;
+	}
+	containerDiv.setAttribute('aria-label', 'Typeahead menu');
+	containerDiv.setAttribute('role', 'listbox');
+	containerDiv.style.display = 'block';
+	containerDiv.style.position = 'absolute';
+}
+
+export function resolveMenuParent(editor: LexicalEditor): HTMLElement | ShadowRoot | undefined {
+	if (!CAN_USE_DOM) {
+		return undefined;
+	}
+	const rootElement = editor.getRootElement();
+	if (rootElement !== null) {
+		const root = rootElement.getRootNode();
+		if (isDOMShadowRoot(root)) {
+			return root as ShadowRoot;
+		}
+	}
+	return document.body;
+}

package/src/shared/point.ts

@@ -0,0 +1,46 @@
+// Ported verbatim from @lexical/react/src/shared/point.ts (framework-agnostic).
+export class Point {
+	private readonly _x: number;
+	private readonly _y: number;
+
+	constructor(x: number, y: number) {
+		this._x = x;
+		this._y = y;
+	}
+
+	get x(): number {
+		return this._x;
+	}
+
+	get y(): number {
+		return this._y;
+	}
+
+	public equals({ x, y }: Point): boolean {
+		return this.x === x && this.y === y;
+	}
+
+	public calcDeltaXTo({ x }: Point): number {
+		return this.x - x;
+	}
+
+	public calcDeltaYTo({ y }: Point): number {
+		return this.y - y;
+	}
+
+	public calcHorizontalDistanceTo(point: Point): number {
+		return Math.abs(this.calcDeltaXTo(point));
+	}
+
+	public calcVerticalDistance(point: Point): number {
+		return Math.abs(this.calcDeltaYTo(point));
+	}
+
+	public calcDistanceTo(point: Point): number {
+		return Math.sqrt(Math.pow(this.calcDeltaXTo(point), 2) + Math.pow(this.calcDeltaYTo(point), 2));
+	}
+}
+
+export function isPoint(x: unknown): x is Point {
+	return x instanceof Point;
+}