Headless Editor API

Guides explain these APIs with examples: start with Getting Started. All APIs on this page are exported from @ngstarter-ui/components/headless-editor. The editor service must be scoped with provideNgsHeadlessEditor(); it is intentionally not a root singleton.

Setup and plugin registration

Public functions used to create a scoped editor and compose its feature set.

Name	Type	Default	Description
`provideNgsHeadlessEditor(...features)`	Provider[]	required	Provides one scoped NgsHeadlessEditor, its snapshot history, plugin providers, and the initial plugin set.
`withHeadlessEditorPlugin(plugin)`	NgsHeadlessEditorFeature	—	Wraps a plugin for provideNgsHeadlessEditor(). Use this path when the plugin declares Angular providers.
`defineNgsHeadlessEditorPlugin(plugin)`	NgsHeadlessEditorPlugin	—	Typed identity helper for declaring blocks, marks, commands, keymaps, providers, paste handling, and setup.
`basicTextEditorPlugin()`	NgsHeadlessEditorPlugin	not installed automatically	Creates the paragraph/text preset with bold, italic, strike, and inline-code marks and shortcuts.
`colorEditorPlugin()`	NgsHeadlessEditorPlugin	not installed automatically	Adds independent textColor and backgroundColor marks plus typed commands to set or remove either color.

NgsHeadlessEditor signals

Readonly signal state exposed by the editor service.

Name	Type	Default	Description
`document`	Signal<NgsHeadlessEditorDocument>	empty paragraph	Current normalized JSON document.
`selection`	Signal<NgsHeadlessEditorSelection \| null>	null	Anchor and focus positions expressed as block IDs and text offsets.
`storedMarks`	Signal<readonly NgsHeadlessEditorMark[]>	[]	Marks that will be applied to text inserted at a collapsed selection.
`NgsHeadlessEditorChangeOrigin`	'external' \| 'api' \| 'keyboard' \| 'paste' \| 'composition' \| 'history' \| 'command'	—	Values of the origin signal. external marks documents loaded with setDocument().
`focused`	Signal<boolean>	false	Whether an attached editor surface currently has focus.
`composing`	Signal<boolean>	false	Whether an IME composition session is active.
`readOnly`	Signal<boolean>	false	Prevents commands and editing operations from mutating the document.
`revision`	Signal<number>	0	Monotonic document revision used by surfaces to schedule rendering.
`origin`	Signal<NgsHeadlessEditorChangeOrigin>	external	Origin of the last document change: external, api, keyboard, paste, composition, history, or command.
`plugins`	Signal<readonly NgsHeadlessEditorPlugin[]>	provided plugins	Currently installed plugin instances in execution order.
`empty`	Signal<boolean>	true	True when normalized document text contains no non-whitespace characters.
`canUndo`	Signal<boolean>	false	Whether a previous snapshot is available.
`canRedo`	Signal<boolean>	false	Whether a forward snapshot is available.
`inlineTarget`	Signal<NgsHeadlessEditor \| null>	null	Nested editor (for example the focused table cell) that currently receives formatting.

NgsHeadlessEditor methods

State transitions and extension lookup methods available to custom shells and plugins.

Name	Type	Default	Description
`setPlugins(plugins)`	void	—	Atomically validates and replaces the plugin set. Duplicate plugin, command, mark, or block IDs throw without corrupting the current registry.
`getMarkDefinition(type)`	NgsHeadlessEditorMarkDefinition \| undefined	—	Looks up one registered mark definition.
`getMarkDefinitions()`	readonly NgsHeadlessEditorMarkDefinition[]	—	Returns every registered mark definition.
`getBlockDefinition(type)`	NgsHeadlessEditorBlockDefinition \| undefined	—	Looks up one registered block definition.
`getBlockDefinitions()`	readonly NgsHeadlessEditorBlockDefinition[]	—	Returns every registered block definition.
`setDocument(document, resetHistory?)`	void	resetHistory: true	Normalizes and installs an external JSON document, resets selection and stored marks, and optionally clears history.
`setReadOnly(readOnly)`	void	—	Updates the read-only signal.
`setFocused(focused)`	void	—	Updates focus state. NgsHeadlessEditorSurface calls this automatically.
`setComposing(composing)`	void	—	Updates IME composition state. NgsHeadlessEditorSurface calls this automatically.
`setSelection(selection)`	void	—	Clamps and stores a JSON selection, or clears it with null.
`setInlineTarget(editor \| null)`	void	—	Routes marks, stored marks, selection and insertText() to a nested editor. Block operations are disabled while a target is active. Used by NgsHeadlessEditorInlineRegion.
`canApplyMark(type)`	boolean	—	Whether a mark can be applied at the current selection, in this editor or in the inline target. Use it in enabled predicates of formatting commands.
`canEditBlocks()`	boolean	—	False while read-only or while an inline target is active. Use it in enabled predicates of block commands.
`execute(command, payload?)`	boolean	—	Executes a typed command object or registered command ID when enabled and writable.
`isCommandEnabled(command, payload?)`	boolean	—	Evaluates command availability against current editor state.
`isCommandActive(command, payload?)`	boolean	—	Evaluates command active state for toolbar controls.
`handleKeydown(event)`	boolean	—	Resolves normalized Mod, Alt, and Shift key bindings in plugin order, falling back to the physical key (event.code) for layout-dependent keys. Handles Mod-z, Mod-Shift-z and Mod-y as undo/redo.
`handlePaste(event)`	boolean	—	Runs plugin paste handlers in order and stops at the first handler that returns true.
`insertText(text, origin?)`	boolean	origin: keyboard	Replaces the current selection, preserves applicable marks, and converts newlines into paragraph blocks.
`deleteBackward()`	boolean	—	Deletes the selection or previous Unicode character and merges paragraphs at a block boundary.
`deleteForward()`	boolean	—	Deletes the selection or next Unicode character and merges paragraphs at a block boundary.
`deleteRange(selection, origin, historyGroup?)`	boolean	—	Deletes a JSON selection, including ranges spanning multiple text blocks and atomic blocks. Changes with the same historyGroup made in quick succession share one undo step.
`splitBlock()`	boolean	—	Splits the current text block at the selection and places the caret in a new paragraph.
`toggleMark(type, attrs?)`	boolean	—	Toggles a registered mark over a range or in stored marks at a collapsed selection.
`getActiveMark(type)`	NgsHeadlessEditorMark \| undefined	—	Returns the active mark and its attributes at the caret or across the current selection.
`setMark(type, attrs?)`	boolean	—	Applies or replaces a registered mark over a selection or in collapsed-selection stored marks.
`unsetMark(type)`	boolean	—	Removes a mark over a selection or from collapsed-selection stored marks.
`isMarkActive(type)`	boolean	—	Reports whether a mark is active at the caret or across the complete selection.
`toggleBlock(type)`	boolean	—	Toggles the selected text block between a registered block type and paragraph.
`isBlockActive(type)`	boolean	—	Reports whether the selected block has the requested registered type.
`insertBlock(block \| blocks, select?)`	boolean	select: false	Inserts one or more blocks after the block that holds the caret as one undo step.
`replaceBlock(id, blocks, selection?)`	boolean	—	Replaces a block with zero or more blocks as one undo step, for example an empty line with a table.
`updateBlock(id, patch, origin?, historyGroup?)`	boolean	origin: 'command'	Updates type, content or attrs of a block by id. Updates sharing a historyGroup in quick succession form one undo step.
`removeBlock(id)`	boolean	—	Removes a block by stable ID and restores an empty paragraph if it was the final block.
`commitDomDocument(document, selection)`	boolean	—	Commits browser-controlled DOM changes such as completed IME composition into JSON state.
`undo()`	boolean	—	Restores the previous document and selection snapshot.
`redo()`	boolean	—	Restores the next document and selection snapshot.
`clear()`	void	—	Replaces content with an empty paragraph and clears history.

NgsHeadlessEditorSurface

Standalone directive that connects contenteditable DOM, browser selection, and NgsHeadlessEditor state.

Name	Type	Default	Description
`ngsHeadlessEditorSurface`	directive	required	Attach to a host element inside the same injector scope as NgsHeadlessEditor.
`editor`	NgsHeadlessEditor	injected	The scoped editor instance used by the surface.
`placeholder`	InputSignal<string>	Write something…	Exposed as data-placeholder so the host application can choose how to style empty state.
`ariaLabel`	InputSignal<string>	Rich text editor	Accessible label applied to the textbox host.
`disabled`	InputSignal<boolean>	false	Disables contenteditable and input handling for this surface.
`spellcheck`	InputSignal<boolean>	true	Controls the native spellcheck attribute.
`focus()`	void	—	Focuses the surface and restores the current JSON selection into the DOM.
`getBlockElement(blockId)`	HTMLElement \| null	—	Returns the element currently rendering a block, for positioning overlays or toolbars. Unchanged blocks keep the same element between renders.
`ngsHeadlessEditorRuns`	directive	—	Renders text runs with the mark definitions of the nearest editor, for static previews of rich text.

NgsHeadlessEditorCommandDirective

Typed bridge between toolbar controls and editor commands.

Name	Type	Default	Description
`[ngsHeadlessEditorCommand]`	InputSignal<NgsHeadlessEditorCommand<TPayload>>	required	Command executed on click. Mousedown is prevented so the current editor selection is preserved.
`commandData`	InputSignal<TPayload>	undefined	Optional typed command payload.
`active`	Signal<boolean>	computed	Reflects command.active() and adds the active class plus aria-pressed.
`disabled`	Signal<boolean>	computed	Reflects read-only state and command.enabled(), and sets the disabled attribute.

Plugin contract

One plugin can contribute model definitions, behavior, Angular providers, and lifecycle work.

Name	Type	Default	Description
`id`	string	required	Unique stable plugin ID.
`blocks`	readonly NgsHeadlessEditorBlockDefinition[]	[]	Block definitions with a unique type, DOM rendering/parsing contract, and factory for an empty block.
`marks`	readonly NgsHeadlessEditorMarkDefinition[]	[]	Inline mark definitions with render tag, optional parse tags, and attribute read/write hooks.
`commands`	readonly NgsHeadlessEditorCommand[]	[]	Typed operations with execute and optional enabled and active predicates.
`keymap`	readonly NgsHeadlessEditorKeyBinding[]	[]	Keyboard mappings such as Mod-b or Mod-Shift-x targeting a command object or registered command ID.
`providers`	readonly Provider[]	[]	Angular providers installed when the plugin is supplied through provideNgsHeadlessEditor(withHeadlessEditorPlugin(...)).
`handlePaste(event, editor)`	boolean	undefined	Optional paste interception. Return true only when the plugin handled the clipboard event.
`setup(editor)`	void \| (() => void)	undefined	Optional lifecycle hook. A returned cleanup function runs before plugin replacement or editor destruction.

Extension definitions

Typed building blocks used inside NgsHeadlessEditorPlugin.

Name	Type	Default	Description
`NgsHeadlessEditorCommand.id`	string	required	Unique command ID used by registry lookup and string-based key bindings.
`NgsHeadlessEditorCommand.execute(editor, payload)`	boolean	required	Runs the command and returns whether it performed an operation.
`NgsHeadlessEditorCommand.enabled(editor, payload)`	boolean	true	Optional availability predicate.
`NgsHeadlessEditorCommand.active(editor, payload)`	boolean	false	Optional active-state predicate for toolbar controls.
`NgsHeadlessEditorKeyBinding.key`	string	required	Normalized shortcut such as Mod-b, Mod-Shift-x, Alt-ArrowDown, or Escape.
`NgsHeadlessEditorKeyBinding.command`	NgsHeadlessEditorCommand \| string	required	Command object or registered command ID.
`NgsHeadlessEditorKeyBinding.payload`	unknown	undefined	Optional payload passed to the command.
`NgsHeadlessEditorMarkDefinition.type`	string	required	Unique serialized mark type.
`NgsHeadlessEditorMarkDefinition.tagName`	string	required	DOM element created when the mark is rendered.
`NgsHeadlessEditorMarkDefinition.parseTags`	readonly string[]	[]	Additional DOM tag names accepted when browser-controlled DOM is parsed.
`NgsHeadlessEditorMarkDefinition.applyAttributes(element, mark)`	void	undefined	Writes serialized mark attributes to the rendered element.
`NgsHeadlessEditorMarkDefinition.readAttributes(element)`	NgsHeadlessEditorMarkAttributes \| undefined	undefined	Reads mark attributes when DOM changes are committed back to JSON.
`NgsHeadlessEditorMarkDefinition.nested`	boolean	true	Whether the mark is available in nested editors such as table cells.
`NgsHeadlessEditorMarkDefinition.atomic`	boolean	false	Renders an indivisible, non-editable inline token. Selection and deletion expand to its boundaries; ordinary typing never inherits this mark.
`NgsHeadlessEditorBlockDefinition.type`	string	required	Unique serialized block type.
`NgsHeadlessEditorBlockDefinition.tagName`	string	required	DOM element used by the default surface renderer.
`NgsHeadlessEditorBlockDefinition.contentTagName`	string	undefined	Optional nested editable element, for example li inside ul or code inside pre.
`NgsHeadlessEditorBlockDefinition.editable`	boolean	true	Set false for atomic media or application blocks that the browser must not edit directly.
`NgsHeadlessEditorBlockDefinition.exitOnEmptyEnter`	boolean	true	Enter in an empty block of this type replaces the empty line with an exitType block, so Enter twice leaves quotes, lists and code.
`NgsHeadlessEditorBlockDefinition.exitType`	string	paragraph	Block type used when leaving the block.
`NgsHeadlessEditorBlockDefinition.create()`	NgsHeadlessEditorBlock	required	Creates an empty block of this type; Enter in a non-empty block uses it for the block that follows.
`NgsHeadlessEditorBlockDefinition.render(element, block)`	void	undefined	Optional block renderer for atomic or non-text DOM such as image and embed blocks.
`NgsHeadlessEditorBlockDefinition.read(element, previous)`	NgsHeadlessEditorBlock	undefined	Optional DOM-to-JSON parser used when a custom editable block commits browser changes.
`NgsHeadlessEditorBlockDefinition.isEmpty(block)`	boolean	text check	Optional empty-state override, commonly returning false for meaningful media blocks.
`NgsHeadlessEditorBlockDefinition.editorComponent`	Type<unknown>	undefined	Angular component rendered as the block while the surface is editable. The tagName element becomes its non-editable host, the block is passed to a `block` input when declared, and the instance survives block updates while the id and type stay the same. The component can inject NgsHeadlessEditor and call updateBlock().
`NgsHeadlessEditorBlockDefinition.rendererComponent`	Type<unknown>	undefined	Component used instead of editorComponent while the surface is read-only or disabled. Each falls back to the other when only one is defined.
`NgsHeadlessEditorBlockComponent<TContent>`	interface	—	Recommended shape of block components: a block input (for example input.required<NgsHeadlessEditorBlock>()).
`NgsHeadlessEditorFeature.plugin`	NgsHeadlessEditorPlugin	required	Feature wrapper consumed by provideNgsHeadlessEditor().
`NGS_HEADLESS_EDITOR_PLUGINS`	InjectionToken<readonly NgsHeadlessEditorPlugin[]>	provided by provideNgsHeadlessEditor()	Low-level token containing the initial plugin set.

Surface host contract

DOM attributes and hooks intentionally left available for host-owned styling and accessibility.

Name	Type	Default	Description
`exportAs`	ngsHeadlessEditorSurface	—	Template reference name for calling focus() or reading the injected editor.
`class`	ngs-headless-editor-surface	always	Stable class hook. The editor package does not attach opinionated visual styles.
`role`	textbox	always	Accessible role applied to the host element.
`contenteditable`	true \| false	true	Derived from surface disabled and editor readOnly state.
`aria-multiline`	true	true	Identifies the surface as a multiline textbox.
`aria-disabled`	true \| false	false	Mirrors effective disabled state.
`data-placeholder`	string	Write something…	Contains placeholder text for a host CSS pseudo-element or other custom presentation.
`data-empty`	empty attribute \| null	empty attribute	Present while editor.empty() is true.
`data-ngs-headless-editor-block-id`	string	generated	Connects each rendered block element to a stable JSON block ID.
`data-ngs-headless-editor-block-type`	string	paragraph	Preserves the serialized block type in the DOM.
`data-ngs-headless-editor-placeholder`	string	first empty text block	Placed on the empty block that owns the caret so host placeholder styling shares its line box.
`data-ngs-headless-editor-mark`	string	registered mark type	Identifies rendered mark wrappers when DOM content is parsed.

JSON document model

Serializable model types and normalization helpers. The core does not store HTML.

Name	Type	Default	Description
`NgsHeadlessEditorDocument`	{ version: 1; blocks: readonly NgsHeadlessEditorBlock[] }	—	Versioned root document.
`NgsHeadlessEditorBlock<TContent>`	{ id; type; content; attrs? }	—	Addressable block with plugin-defined type and content.
`NgsHeadlessEditorText`	{ type: text; text; marks }	—	Text run with a normalized list of inline marks.
`NgsHeadlessEditorMark`	{ type; attrs? }	—	Serializable inline annotation.
`NgsHeadlessEditorMarkAttributes`	Readonly<Record<string, string \| number \| boolean \| null>>	—	Serializable attribute value map used by inline marks.
`NgsHeadlessEditorSelection`	{ anchor; focus }	—	Forward or backward selection in model coordinates.
`NgsHeadlessEditorPoint`	{ blockId; offset }	—	Position inside a block text stream.
`createNgsHeadlessEditorId(prefix?)`	string	prefix: block	Creates a unique browser-safe model ID.
`createNgsHeadlessEditorText(text?, marks?)`	NgsHeadlessEditorText	empty text	Creates and normalizes one text run.
`createNgsHeadlessEditorParagraph(text?, marks?)`	NgsHeadlessEditorBlock	empty paragraph	Creates a paragraph block with a fresh ID.
`createNgsHeadlessEditorDocument(text?)`	NgsHeadlessEditorDocument	empty document	Creates a version 1 document containing one paragraph.
`cloneNgsHeadlessEditorDocument(document)`	NgsHeadlessEditorDocument	—	Clones blocks, text runs, marks, and serializable attributes.
`normalizeNgsHeadlessEditorDocument(document)`	NgsHeadlessEditorDocument	—	Ensures at least one block, unique block IDs and normalized text runs. Unchanged blocks keep their object identity and an already normalized document is returned as-is.
`normalizeNgsHeadlessEditorTextContent(content)`	readonly NgsHeadlessEditorText[]	—	Removes empty runs, merges adjacent equal marks, and preserves an empty text run when needed.
`normalizeNgsHeadlessEditorMarks(marks)`	readonly NgsHeadlessEditorMark[]	—	Deduplicates marks by type and returns deterministic order.
`ngsHeadlessEditorMarksEqual(left, right)`	boolean	—	Compares normalized mark collections.
`ngsHeadlessEditorDocumentsEqual(left, right)`	boolean	—	Structural document comparison that short-circuits on shared, unchanged blocks and ignores object key order.
`ngsHeadlessEditorBlocksEqual(left, right)`	boolean	—	Structural comparison of one block: id, type, attrs and content.
`ngsHeadlessEditorValuesEqual(left, right)`	boolean	—	Deep equality for JSON-like values; key order is ignored and undefined keys count as absent.
`isNgsHeadlessEditorTextContent(content)`	type predicate	—	Checks whether block content is composed of text runs.
`getNgsHeadlessEditorBlockText(block)`	string	—	Flattens text runs in one block.
`getNgsHeadlessEditorDocumentText(document)`	string	—	Flattens document blocks separated by newlines.
`isNgsHeadlessEditorDocumentEmpty(document)`	boolean	—	Checks whether flattened document text is empty after trimming.

Basic text preset

Exports supplied by basicTextEditorPlugin().

Name	Type	Default	Description
`paragraph`	block	<p>	Default text block.
`bold`	mark	<strong>	Parses strong and b elements. Shortcut: Mod-b.
`italic`	mark	<em>	Parses em and i elements. Shortcut: Mod-i.
`strike`	mark	<s>	Parses s and strike elements. Shortcut: Mod-Shift-x.
`code`	mark	<code>	Inline code mark. Shortcut: Mod-e.
`NGS_HEADLESS_EDITOR_TOGGLE_BOLD`	NgsHeadlessEditorCommand<void>	—	Built-in bold command.
`NGS_HEADLESS_EDITOR_TOGGLE_ITALIC`	NgsHeadlessEditorCommand<void>	—	Built-in italic command.
`NGS_HEADLESS_EDITOR_TOGGLE_STRIKE`	NgsHeadlessEditorCommand<void>	—	Built-in strike command.
`NGS_HEADLESS_EDITOR_TOGGLE_CODE`	NgsHeadlessEditorCommand<void>	—	Built-in inline-code command.

Color plugin

Opt-in text and highlight colors supplied by colorEditorPlugin(). Colors are stored as mark attributes in the JSON document.

Name	Type	Default	Description
`textColor`	mark	<span style="color: …">	Applies a foreground color without affecting the background color mark.
`backgroundColor`	mark	<span style="background-color: …">	Applies a highlight/background color without affecting the text color mark.
`NGS_HEADLESS_EDITOR_SET_TEXT_COLOR`	NgsHeadlessEditorCommand<string>	—	Sets or replaces the textColor mark using a color command payload.
`NGS_HEADLESS_EDITOR_UNSET_TEXT_COLOR`	NgsHeadlessEditorCommand<void>	—	Removes the textColor mark while preserving other marks.
`NGS_HEADLESS_EDITOR_SET_BACKGROUND_COLOR`	NgsHeadlessEditorCommand<string>	—	Sets or replaces the backgroundColor mark using a color command payload.
`NGS_HEADLESS_EDITOR_UNSET_BACKGROUND_COLOR`	NgsHeadlessEditorCommand<void>	—	Removes the backgroundColor mark while preserving other marks.
`normalizeNgsHeadlessEditorColor(value)`	string \| null	—	Normalizes supported CSS colors and design-token variables and rejects values that can escape the color declaration.
`NGS_HEADLESS_EDITOR_TEXT_COLOR_MARK`	'textColor'	—	Mark type of the text color mark.
`NGS_HEADLESS_EDITOR_BACKGROUND_COLOR_MARK`	'backgroundColor'	—	Mark type of the background color mark.

Nested editors

Rich text inside component blocks, as used by table cells.

Name	Type	Default	Description
`provideNgsHeadlessEditorInlineRegion()`	Provider[]	—	Provides a nested editor and NgsHeadlessEditorInlineRegion for a component.
`NgsHeadlessEditorInlineRegion.parent / editor`	NgsHeadlessEditor	—	The document editor and the nested editor.
`NgsHeadlessEditorInlineRegion.configure(options)`	void	marks: true	marks: true (all marks without nested: false), false (plain text) or a list of mark types.
`NgsHeadlessEditorInlineRegion.load(runs)`	void	—	Shows content in the nested editor unless it already does; keeps the caret when possible.
`NgsHeadlessEditorInlineRegion.content`	Signal<readonly NgsHeadlessEditorText[]>	—	Current content as text runs; lines are joined with newline characters.
`NgsHeadlessEditorInlineRegion.activate() / deactivate() / active`	void / Signal<boolean>	—	Makes the region the inline target of the document editor.
`renderNgsHeadlessEditorRuns / renderNgsHeadlessEditorTextRun`	function	—	Render text runs into DOM with mark definitions.
`readNgsHeadlessEditorInlineContent(element, marks, options?)`	NgsHeadlessEditorText[]	—	Reads text runs from DOM; lineBreaks turns br and block boundaries into newlines.

Mention plugin and menu

Indivisible inline mentions with a caret menu and custom Angular option components. See the Mentions guide.

Name	Type	Default	Description
`mentionEditorPlugin(config \| configs[])`	NgsHeadlessEditorPlugin	trigger: @	One plugin accepts one configuration or an array of unique triggers, each with its own options callback and optionComponent. All configurations share one mention mark.
`NgsHeadlessEditorMentionSearch<T>`	(query: string) => Promise<readonly T[]>	—	Consumer-defined local or backend search. Receives the query without the trigger. Results retain their order without additional filtering.
`NgsHeadlessEditorMentionOption`	{ id: string; label: string; text?: string }	text: trigger + label	Candidate identity, menu label and optional exact insertion text. Set text to an emoji glyph to insert the emoji. Extend with arbitrary presentation data.
`NgsHeadlessEditorMentionOptionComponent<T>`	{ option: () => T; active: () => boolean }	—	Inputs required by a custom optionComponent. The menu handles selection around the component.
`NGS_HEADLESS_EDITOR_MENTION_OPTIONS`	InjectionToken<readonly NgsHeadlessEditorMentionRegistration[]>	[]	Independent editor-scoped configurations installed together by the mention plugin.
`ngsHeadlessEditorMentions`	Menu \| null	default menu	Directive on a surface. Pass a Menu for custom content, or use the default menu with the plugin optionComponent.
`mentionOptions / mentionTrigger`	NgsHeadlessEditorMentionSearch<T> \| null / string \| null	null (use plugin settings)	Single-configuration compatibility overrides. Configure multiple triggers in the plugin configuration array.
`registration / activeTrigger / optionComponent`	Signal	null / null / undefined	Settings, trigger and option component of the active plugin registration. Longest matching trigger wins.
`query / suggestions / activeIndex / open`	Signal	null / [] / 0 / false	Current query, matching candidates, highlighted index and whether suggestions are open.
`loading / error`	Signal<boolean> / Signal<unknown>	false / null	Pending search and latest search error. Outdated responses are ignored; rejection closes the menu until the next search.
`optionId(index) / select(option) / dismiss()`	methods	—	Option id for aria-activedescendant, candidate insertion in one undo step, and dismissal of the current query.
`mentionSelected / mentionQueryChange`	output	—	Emits the inserted candidate or the query (null when inactive). Search itself runs through the options callback.
`findNgsHeadlessEditorMentionQuery(editor, trigger?)`	NgsHeadlessEditorMentionQuery \| null	trigger: @	Finds a trigger and query at a collapsed caret; ignores existing mentions and e-mail addresses.
`insertNgsHeadlessEditorMention(editor, option, query)`	boolean	—	Replaces a still-current query with a mention and a space; preserves surrounding text and formatting.
`NGS_HEADLESS_EDITOR_MENTION_MARK`	'mention'	—	Shared atomic mention mark. Attributes contain id, label, trigger and a unique tokenId per insertion. Older marks without trigger or tokenId remain valid.
`NgsHeadlessEditorMentionMenu`	component	built in	Default ngs-menu content used by the mentions directive.

Table plugin

Table blocks: plugin, commands, data helpers and components. See the Tables guide.

Name	Type	Default	Description
`tableEditorPlugin(options?)`	NgsHeadlessEditorPlugin	paste: true, formatting: true	Registers the table block, its editor and read-only components, the table commands and spreadsheet/HTML table paste. formatting: true, false or a list of mark types allowed in cells.
`NGS_HEADLESS_EDITOR_TABLE_OPTIONS`	InjectionToken<NgsHeadlessEditorTablePluginOptions>	{}	Plugin options, provided by withHeadlessEditorPlugin(tableEditorPlugin(...)).
`NgsHeadlessEditorTableCellContent`	readonly NgsHeadlessEditorText[]	—	Content of one cell: text runs with marks; newlines are line breaks.
`getNgsHeadlessEditorTableCellText(cell)`	string	—	Plain text of a cell.
`normalizeNgsHeadlessEditorTableCell(value)`	NgsHeadlessEditorTableCellContent	—	Normalizes a cell from a string, text runs or untrusted JSON.
`ngsHeadlessEditorTableCellMarks(registry, formatting?)`	NgsHeadlessEditorMarkRegistry	—	Mark registry filtered to the marks allowed in cells.
`NGS_HEADLESS_EDITOR_INSERT_TABLE`	NgsHeadlessEditorCommand<NgsHeadlessEditorTableSize \| undefined>	3 x 3, header	Replaces an empty line or inserts after the current block, adds a trailing paragraph when needed and focuses the first cell.
`NGS_HEADLESS_EDITOR_TABLE_ADD_ROW_BEFORE / _AFTER`	NgsHeadlessEditorCommand	—	Adds a row above or below the active cell.
`NGS_HEADLESS_EDITOR_TABLE_ADD_COLUMN_BEFORE / _AFTER`	NgsHeadlessEditorCommand	—	Adds a column left or right of the active cell.
`NGS_HEADLESS_EDITOR_TABLE_DELETE_ROW / _COLUMN`	NgsHeadlessEditorCommand	—	Deletes the row or column of the active cell; disabled for the last one.
`NGS_HEADLESS_EDITOR_TABLE_TOGGLE_HEADER`	NgsHeadlessEditorCommand	—	Toggles the header row; active while it is on.
`NGS_HEADLESS_EDITOR_TABLE_DELETE`	NgsHeadlessEditorCommand	—	Removes the table of the active cell.
`insertNgsHeadlessEditorTable(editor, block)`	boolean	—	Inserts a table block with the same placement and focus rules as the insert command.
`ngsHeadlessEditorActiveTableCell(editor)`	Signal<NgsHeadlessEditorTableCell \| null>	null	Focused (or last focused) table cell: block id, row and column.
`focusNgsHeadlessEditorTableCell(editor, cell)`	void	—	Focuses a cell once its table is rendered.
`NgsHeadlessEditorTableData`	{ rows: NgsHeadlessEditorTableCellContent[][]; header: boolean }	—	Table data stored in block.attrs.
`NgsHeadlessEditorTableSize`	{ rows; columns; header? }	—	Payload of the insert command.
`createNgsHeadlessEditorTable(sizeOrRows, header?)`	NgsHeadlessEditorBlock<null>	header: true	Creates a table block from a size or from cells given as strings or text runs.
`getNgsHeadlessEditorTableData(block)`	NgsHeadlessEditorTableData	—	Reads and normalizes table data (rectangular rows, at most 500 x 50).
`setNgsHeadlessEditorTableCell / insert…Row / remove…Row / insert…Column / remove…Column`	NgsHeadlessEditorTableData	—	Pure table operations that return new data.
`parseNgsHeadlessEditorTableText(text)`	NgsHeadlessEditorTableCellContent[][] \| null	—	Parses a tab-separated spreadsheet range into cells; null unless it is a real grid.
`parseNgsHeadlessEditorTableHtml(html, marks?)`	NgsHeadlessEditorTableCellContent[][] \| null	—	Extracts cells from clipboard HTML that contains only a table, keeping formatting for the given marks.
`NgsHeadlessEditorTableBlockEditor / NgsHeadlessEditorTableView`	component	—	Editing and read-only components registered by the plugin. Style them through .ngs-headless-editor-table, .ngs-headless-editor-table-cell, th, .active, .ngs-headless-editor-table-cell-content and .ngs-headless-editor-table-cell-editor.

Snapshot history

NgsHeadlessEditorHistory is scoped with the editor and records document plus selection snapshots.

Name	Type	Default	Description
`NgsHeadlessEditorSnapshot`	{ document; selection }	—	Immutable history value containing JSON document and model selection.
`canUndo`	Signal<boolean>	false	Whether the past stack contains a snapshot.
`canRedo`	Signal<boolean>	false	Whether the future stack contains a snapshot.
`record(snapshot, group?)`	void	—	Adds a snapshot to the past stack (structure is shared, not cloned) and clears redo state. Consecutive records with the same non-null group within one second form a single undo step. At most 200 steps are kept.
`breakGroup()`	void	—	Forces the next record to start a new undo step. Called on caret moves, undo and redo.
`NGS_HEADLESS_EDITOR_HISTORY_LIMIT`	number	200	Maximum number of undo steps kept in memory.
`NGS_HEADLESS_EDITOR_HISTORY_GROUP_DELAY`	number	1000	Milliseconds within which changes of the same group form one undo step.
`undo(current)`	NgsHeadlessEditorSnapshot \| null	—	Moves current state to the future stack and returns the previous snapshot.
`redo(current)`	NgsHeadlessEditorSnapshot \| null	—	Moves current state to the past stack and returns the next snapshot.
`clear()`	void	—	Clears both history stacks.