@octanejs/lexical 0.1.9 → 0.1.10

package/src/LexicalTableOfContentsPlugin.tsrx

@@ -3,15 +3,32 @@
 // component: `children(entries, editor)` returns the element to render.
 import { useLexicalComposerContext } from './LexicalComposerContext';
 import { $isHeadingNode, HeadingNode } from '@lexical/rich-text';
+import type { HeadingTagType } from '@lexical/rich-text';
 import { $getNextRightPreorderNode } from '@lexical/utils';
 import { $getNodeByKey, $getRoot, $isElementNode, TextNode } from 'lexical';
+import type { ElementNode, LexicalEditor, LexicalNode, NodeKey } from 'lexical';
 import { useEffect, useState } from 'octane';
+import type { OctaneNode } from 'octane';
 
-function toEntry(heading) {
+/**
+ * A single entry in the table of contents, as a tuple of the heading node's
+ * {@link NodeKey}, its text content, and its heading tag (for example `'h1'`).
+ */
+export type TableOfContentsEntry = [key: NodeKey, text: string, tag: HeadingTagType];
+
+type Props = {
+	children: (values: Array<TableOfContentsEntry>, editor: LexicalEditor) => OctaneNode;
+};
+
+function toEntry(heading: HeadingNode): TableOfContentsEntry {
 	return [heading.getKey(), heading.getTextContent(), heading.getTag()];
 }
 
-function $insertHeadingIntoTableOfContents(prevHeading, newHeading, currentTableOfContents) {
+function $insertHeadingIntoTableOfContents(
+	prevHeading: HeadingNode | null,
+	newHeading: HeadingNode | null,
+	currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
 	if (newHeading === null) {
 		return currentTableOfContents;
 	}
@@ -40,7 +57,10 @@ function $insertHeadingIntoTableOfContents(prevHeading, newHeading, currentTable
 	return newTableOfContents;
 }
 
-function $deleteHeadingFromTableOfContents(key, currentTableOfContents) {
+function $deleteHeadingFromTableOfContents(
+	key: NodeKey,
+	currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
 	const newTableOfContents = [];
 	for (const heading of currentTableOfContents) {
 		if (heading[0] !== key) {
@@ -50,7 +70,10 @@ function $deleteHeadingFromTableOfContents(key, currentTableOfContents) {
 	return newTableOfContents;
 }
 
-function $updateHeadingInTableOfContents(heading, currentTableOfContents) {
+function $updateHeadingInTableOfContents(
+	heading: HeadingNode,
+	currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
 	const newTableOfContents = [];
 	for (const oldHeading of currentTableOfContents) {
 		if (oldHeading[0] === heading.getKey()) {
@@ -62,8 +85,12 @@ function $updateHeadingInTableOfContents(heading, currentTableOfContents) {
 	return newTableOfContents;
 }
 
-function $updateHeadingPosition(prevHeading, heading, currentTableOfContents) {
-	const newTableOfContents = [];
+function $updateHeadingPosition(
+	prevHeading: HeadingNode | null,
+	heading: HeadingNode,
+	currentTableOfContents: Array<TableOfContentsEntry>,
+): Array<TableOfContentsEntry> {
+	const newTableOfContents: Array<TableOfContentsEntry> = [];
 	const newEntry = toEntry(heading);
 
 	if (!prevHeading) {
@@ -82,7 +109,7 @@ function $updateHeadingPosition(prevHeading, heading, currentTableOfContents) {
 	return newTableOfContents;
 }
 
-function $getPreviousHeading(node) {
+function $getPreviousHeading(node: LexicalNode): HeadingNode | null {
 	let prevHeading = $getNextRightPreorderNode(node);
 	while (prevHeading !== null && !$isHeadingNode(prevHeading)) {
 		prevHeading = $getNextRightPreorderNode(prevHeading);
@@ -90,14 +117,14 @@ function $getPreviousHeading(node) {
 	return prevHeading;
 }
 
-export function TableOfContentsPlugin(props) {
-	const [tableOfContents, setTableOfContents] = useState([]);
+export function TableOfContentsPlugin(props: Props) {
+	const [tableOfContents, setTableOfContents] = useState<Array<TableOfContentsEntry>>([]);
 	const [editor] = useLexicalComposerContext();
 
 	useEffect(() => {
-		let currentTableOfContents = [];
+		let currentTableOfContents: Array<TableOfContentsEntry> = [];
 		editor.read('latest', () => {
-			const updateCurrentTableOfContents = (node) => {
+			const updateCurrentTableOfContents = (node: ElementNode) => {
 				for (const child of node.getChildren()) {
 					if ($isHeadingNode(child)) {
 						currentTableOfContents.push([
@@ -120,7 +147,7 @@ export function TableOfContentsPlugin(props) {
 			dirtyElements,
 		}) => {
 			editorState.read(() => {
-				const updateChildHeadings = (node) => {
+				const updateChildHeadings = (node: ElementNode) => {
 					for (const child of node.getChildren()) {
 						if ($isHeadingNode(child)) {
 							const prevHeading = $getPreviousHeading(child);

package/src/LexicalTablePlugin.tsrx

@@ -12,7 +12,40 @@ import { $fullReconcile } from 'lexical';
 import { useLexicalComposerContext } from './LexicalComposerContext';
 import { useEffect, useState } from 'octane';
 
-export function TablePlugin(props) {
+/**
+ * Props for the {@link TablePlugin} component.
+ */
+export interface TablePluginProps {
+	/**
+ * When `false` (default `true`), merged cell support (colspan and rowspan)
+ * will be disabled and all tables will be forced into a regular grid with
+ * 1x1 table cells.
+ */
+	hasCellMerge?: boolean;
+	/**
+ * When `false` (default `true`), the background color of TableCellNode will
+ * always be removed.
+ */
+	hasCellBackgroundColor?: boolean;
+	/**
+ * When `true` (default `true`), the tab key can be used to navigate table
+ * cells.
+ */
+	hasTabHandler?: boolean;
+	/**
+ * When `true` (default `false`), tables will be wrapped in a `<div>` to
+ * enable horizontal scrolling.
+ */
+	hasHorizontalScroll?: boolean;
+	/**
+ * When `true` (default `false`), nested tables will be allowed.
+ *
+ * @experimental Nested tables are not officially supported.
+ */
+	hasNestedTables?: boolean;
+}
+
+export function TablePlugin(props: TablePluginProps) {
 	const [editor] = useLexicalComposerContext();
 	const hasCellMerge =
 		props.hasCellMerge === undefined ? true : props.hasCellMerge;

package/src/LexicalTypeaheadMenuPlugin.tsrx

@@ -11,7 +11,9 @@ import {
 	tryToPositionRange,
 } from './typeaheadShared';
 import { $getSelection, $isRangeSelection, COMMAND_PRIORITY_LOW } from 'lexical';
+import type { CommandListenerPriority, TextNode } from 'lexical';
 import { startTransition, useCallback, useEffect, useState } from 'octane';
+import type { MenuOption, MenuRenderFn, MenuResolution, TriggerFn } from './shared/menuShared';
 
 export { useBasicTypeaheadTriggerMatch, PUNCTUATION } from './typeaheadShared';
 export { MenuOption, SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND } from './shared/menuShared';
@@ -19,7 +21,26 @@ export { useDynamicPositioning } from './shared/useDynamicPositioning';
 // Upstream re-exports @lexical/utils' getScrollParent from this module.
 export { getScrollParent } from '@lexical/utils';
 
-export function LexicalTypeaheadMenuPlugin(props) {
+/**
+ * Props for the {@link LexicalTypeaheadMenuPlugin} component.
+ */
+export type TypeaheadMenuPluginProps<TOption extends MenuOption> = {
+	onQueryChange: (matchingString: string | null) => void;
+	onSelectOption: (option: TOption, textNodeContainingQuery: | TextNode
+	| null, closeMenu: () => void, matchingString: string) => void;
+	options: TOption[];
+	triggerFn: TriggerFn;
+	menuRenderFn?: MenuRenderFn<TOption>;
+	onOpen?: (resolution: MenuResolution) => void;
+	onClose?: () => void | PromiseLike<void>;
+	anchorClassName?: string;
+	commandPriority?: CommandListenerPriority;
+	parent?: HTMLElement;
+	preselectFirstItem?: boolean;
+	ignoreEntityBoundary?: boolean;
+};
+
+export function LexicalTypeaheadMenuPlugin<TOption extends MenuOption>(props: TypeaheadMenuPluginProps<TOption>) {
 	const options = props.options;
 	const onQueryChange = props.onQueryChange;
 	const onSelectOption = props.onSelectOption;
@@ -35,7 +56,7 @@ export function LexicalTypeaheadMenuPlugin(props) {
 	const ignoreEntityBoundary = props.ignoreEntityBoundary === true;
 
 	const [editor] = useLexicalComposerContext();
-	const [resolution, setResolution] = useState(null);
+	const [resolution, setResolution] = useState<MenuResolution | null>(null);
 	const anchorElementRef = useMenuAnchorRef(resolution, setResolution, anchorClassName, parent);
 
 	const closeTypeahead = useCallback(() => {
@@ -55,7 +76,7 @@ export function LexicalTypeaheadMenuPlugin(props) {
 		}
 	}, [onClose, resolution]);
 
-	const openTypeahead = useCallback((res) => {
+	const openTypeahead = useCallback((res: MenuResolution) => {
 		setResolution(res);
 		if (onOpen != null && resolution === null) {
 			onOpen(res);

package/src/shared/LexicalContentEditableElement.tsrx

@@ -7,7 +7,42 @@
 // 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 type { LexicalEditor } from 'lexical';
 import { useCallback, useLayoutEffect, useState } from 'octane';
+import type { Octane } from 'octane/jsx-runtime';
+
+type DivAttributes = Octane.HTMLAttributes<HTMLDivElement>;
+
+/**
+ * Props for the {@link ContentEditableElement} component. In addition to an
+ * `editor`, it accepts the standard `<div>` attributes (except `placeholder`),
+ * including the hyphenated `aria-*` attributes, which are the preferred way to
+ * set ARIA properties. The camelCase `aria*` props (such as `ariaLabel`) are
+ * also accepted but are retained only for backwards compatibility.
+ */
+export type ContentEditableElementProps = {
+		editor: LexicalEditor;
+		ariaActiveDescendant?: DivAttributes['aria-activedescendant'];
+		ariaAutoComplete?: DivAttributes['aria-autocomplete'];
+		ariaControls?: DivAttributes['aria-controls'];
+		ariaDescribedBy?: DivAttributes['aria-describedby'];
+		ariaErrorMessage?: DivAttributes['aria-errormessage'];
+		ariaExpanded?: DivAttributes['aria-expanded'];
+		ariaInvalid?: DivAttributes['aria-invalid'];
+		ariaLabel?: DivAttributes['aria-label'];
+		ariaLabelledBy?: DivAttributes['aria-labelledby'];
+		ariaMultiline?: DivAttributes['aria-multiline'];
+		ariaOwns?: DivAttributes['aria-owns'];
+		ariaRequired?: DivAttributes['aria-required'];
+		autoCapitalize?: HTMLDivElement['autocapitalize'];
+		'data-testid'?: string | null | undefined;
+		// Octane ref shapes (no forwardRef): callback or ref object.
+		ref?: ((el: HTMLDivElement | null) => void) | { current: HTMLDivElement | null };
+		// Consumed (excluded from the `rest` passthrough) but never rendered —
+		// upstream omits `placeholder` from the accepted div attributes; the octane
+		// port receives it via `<ContentEditable {...props}>`'s spread instead.
+		placeholder?: unknown;
+	} & Omit<Octane.JSX.IntrinsicElements['div'], 'ref' | 'placeholder'>;
 
 // Props consumed by name — everything else flows through to the <div> via `rest`.
 const NAMED_PROPS = new Set([
@@ -37,11 +72,11 @@ const NAMED_PROPS = new Set([
 	'data-testid',
 ]);
 
-export function ContentEditableElement(props) @{
+export function ContentEditableElement(props: ContentEditableElementProps) @{
 	const editor = props.editor;
 	const [isEditable, setEditable] = useState(editor.isEditable());
 
-	const handleRef = useCallback((rootElement) => {
+	const handleRef = useCallback((rootElement: HTMLDivElement | null) => {
 		// 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) {
@@ -63,7 +98,7 @@ export function ContentEditableElement(props) @{
 	const rest: Record<string, any> = {};
 	for (const k in props) {
 		if (!NAMED_PROPS.has(k)) {
-			rest[k] = props[k];
+			rest[k] = (props as Record<string, unknown>)[k];
 		}
 	}
 	// Route `class` through the spread (setSpread omits an absent/undefined key) so
@@ -73,29 +108,42 @@ export function ContentEditableElement(props) @{
 		rest['class'] = props.className;
 	}
 
+	// Attribute names are authored camelCase (matching upstream and octane's typed
+	// JSX contract); the runtime writes the equivalent lowercase DOM attributes
+	// (`tabIndex` via ATTRIBUTE_ALIASES, the rest via HTML's case-insensitive
+	// setAttribute).
 	<div
-		ref={props.ref != null ? [props.ref, handleRef] : handleRef}
+		ref={props.ref != null
+			? // Octane's runtime accepts an array of refs natively; the checker's
+				// merged-ref signature only models the single-ref forms, so the
+				// dynamic array branch needs a type-level cast.
+				[props.ref, handleRef] as unknown as typeof 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-expanded={isEditable && role === 'combobox'
+			? String(!!props.ariaExpanded) as 'true' | 'false'
+			: 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'}
+		aria-required={props.ariaRequired != null
+			? String(props.ariaRequired) as 'true' | 'false'
+			: undefined}
+		autoCapitalize={props.autoCapitalize}
+		contentEditable={isEditable ? 'true' : 'false'}
 		data-testid={props['data-testid']}
 		id={props.id}
 		role={role}
-		spellcheck={props.spellCheck === false ? 'false' : 'true'}
+		spellCheck={props.spellCheck === false ? 'false' : 'true'}
 		style={props.style}
-		tabindex={props.tabIndex}
+		tabIndex={props.tabIndex}
 		{...rest}
 	/>
 }

package/src/shared/LexicalDecorators.tsrx

@@ -8,6 +8,8 @@
 // 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 type { LexicalEditor } from 'lexical';
+import type { OctaneNode } from 'octane';
 import {
 	useState,
 	useEffect,
@@ -19,18 +21,39 @@ import {
 	Suspense,
 } from 'octane';
 
-function DecoratorPortalBody(props) {
+type ErrorBoundaryType = (props: {
+		children: OctaneNode;
+		onError: (error: Error) => void;
+	}) => OctaneNode;
+
+type DecoratorPortalBodyProps = {
+	ErrorBoundary: ErrorBoundaryType;
+	onError: (error: Error) => void;
+	decorator: OctaneNode;
+};
+
+function DecoratorPortalBody(props: DecoratorPortalBodyProps) {
 	return createElement(props.ErrorBoundary, {
 		onError: props.onError,
 		children: createElement(Suspense, { fallback: null, children: props.decorator }),
 	});
 }
 
-function DecoratorPortal(props) {
+type DecoratorPortalProps = {
+	element: HTMLElement;
+	bodyProps: DecoratorPortalBodyProps;
+};
+
+function DecoratorPortal(props: DecoratorPortalProps) {
 	return createPortal(DecoratorPortalBody, props.element, props.bodyProps);
 }
 
-export function Decorators(props) {
+type DecoratorsProps = {
+	editor: LexicalEditor;
+	ErrorBoundary: ErrorBoundaryType;
+};
+
+export function Decorators(props: DecoratorsProps) {
 	const editor = props.editor;
 	const ErrorBoundary = props.ErrorBoundary;
 
@@ -38,7 +61,7 @@ export function Decorators(props) {
 
 	// Subscribe to decorator changes.
 	useLayoutEffect(() => {
-		return editor.registerDecoratorListener((nextDecorators) => {
+		return editor.registerDecoratorListener((nextDecorators: Record<string, OctaneNode>) => {
 			flushSync(() => {
 				setDecorators(nextDecorators);
 			});
@@ -79,7 +102,7 @@ export function Decorators(props) {
 				element={entry.element}
 				bodyProps={{
 					ErrorBoundary,
-					onError: (e) => editor._onError(e),
+					onError: (e: Error) => editor._onError(e),
 					decorator: entry.decorator,
 				}}
 			/>,

package/src/shared/LexicalMenu.tsrx

@@ -2,11 +2,13 @@
 // @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 type { MenuOption, MenuRef, MenuRenderFn, MenuResolution } from './menuShared';
 import {
 	$splitNodeContainingQuery,
 	scrollIntoViewIfNeeded,
 	SCROLL_TYPEAHEAD_OPTION_INTO_VIEW_COMMAND,
 } from './menuShared';
+import type { CommandListenerPriority, LexicalEditor, TextNode } from 'lexical';
 import {
 	COMMAND_PRIORITY_LOW,
 	KEY_ARROW_DOWN_COMMAND,
@@ -18,9 +20,17 @@ import {
 } from 'lexical';
 import { createPortal, useCallback, useEffect, useLayoutEffect, useMemo, useState } from 'octane';
 
-function MenuItem(props) @{
+type MenuItemProps<TOption extends MenuOption> = {
+	index: number;
+	isSelected: boolean;
+	onClick: () => void;
+	onMouseEnter: () => void;
+	option: TOption;
+};
+
+function MenuItem<TOption extends MenuOption>(props: MenuItemProps<TOption>) @{
 	<li
-		tabindex={-1}
+		tabIndex={-1}
 		class={props.isSelected ? 'item selected' : 'item'}
 		ref={props.option.setRefElement}
 		role="option"
@@ -34,7 +44,14 @@ function MenuItem(props) @{
 	</li>
 }
 
-function DefaultMenu(props) @{
+type DefaultMenuProps<TOption extends MenuOption> = {
+	options: TOption[];
+	selectedIndex: number | null;
+	selectOptionAndCleanUp: (option: TOption) => void;
+	setHighlightedIndex: (index: number) => void;
+};
+
+function DefaultMenu<TOption extends MenuOption>(props: DefaultMenuProps<TOption>) @{
 	<div class="typeahead-popover mentions-menu">
 		<ul>{props.options.map(
 			(option, i) => <MenuItem
@@ -52,7 +69,21 @@ function DefaultMenu(props) @{
 	</div>
 }
 
-export function LexicalMenu(props) {
+type LexicalMenuProps<TOption extends MenuOption> = {
+	close: () => void;
+	editor: LexicalEditor;
+	anchorElementRef: MenuRef;
+	resolution: MenuResolution;
+	options: TOption[];
+	shouldSplitNodeWithQuery?: boolean;
+	menuRenderFn?: MenuRenderFn<TOption>;
+	onSelectOption: (option: TOption, textNodeContainingQuery: | TextNode
+	| null, closeMenu: () => void, matchingString: string) => void;
+	commandPriority?: CommandListenerPriority;
+	preselectFirstItem?: boolean;
+};
+
+export function LexicalMenu<TOption extends MenuOption>(props: LexicalMenuProps<TOption>) {
 	const close = props.close;
 	const editor = props.editor;
 	const anchorElementRef = props.anchorElementRef;
@@ -65,7 +96,7 @@ export function LexicalMenu(props) {
 		props.commandPriority != null ? props.commandPriority : COMMAND_PRIORITY_LOW;
 	const preselectFirstItem = props.preselectFirstItem !== false;
 
-	const [rawSelectedIndex, setHighlightedIndex] = useState(null);
+	const [rawSelectedIndex, setHighlightedIndex] = useState<number | null>(null);
 	const selectedIndex =
 		rawSelectedIndex !== null ? Math.min(options.length - 1, rawSelectedIndex) : null;
 
@@ -77,7 +108,7 @@ export function LexicalMenu(props) {
 		}
 	}, [matchingString, preselectFirstItem]);
 
-	const selectOptionAndCleanUp = useCallback((selectedEntry) => {
+	const selectOptionAndCleanUp = useCallback((selectedEntry: TOption) => {
 		editor.update(() => {
 			const textNodeContainingQuery =
 				resolution.match != null && shouldSplitNodeWithQuery
@@ -92,7 +123,7 @@ export function LexicalMenu(props) {
 		});
 	}, [editor, shouldSplitNodeWithQuery, resolution.match, onSelectOption, close]);
 
-	const updateSelectedIndex = useCallback((index) => {
+	const updateSelectedIndex = useCallback((index: number) => {
 		const rootElem = editor.getRootElement();
 		if (rootElem !== null) {
 			rootElem.setAttribute('aria-activedescendant', 'typeahead-item-' + index);