@navette-js/forms 1.0.0-beta.4 → 1.0.0-beta.5

package/lib/index.d.ts

@@ -1,6 +1,11 @@
 import { HtmlString, type ColorManager, type Lazy } from '@navette-js/support';
-import { Component, Schema, type ComponentContext } from '@navette-js/schemas';
+import { Component, Schema, type ComponentContext, type ComponentSlot } from '@navette-js/schemas';
 import { Action } from '@navette-js/actions';
+import { TextColor, MentionProvider, type CustomBlockClass } from './rich-content.ts';
+export { CustomBlockNode, GridColumnNode, GridNode, LeadNode, MentionNode, MentionProvider, MergeTagNode, registerRichContentExtensions, RichContentCustomBlock, RichContentRenderer, sanitizeCssColor, SizedImage, SmallMark, TextColor, TextColorMark, type CustomBlockClass } from './rich-content.ts';
+import { RichEditorTool } from './rich-editor-tool.ts';
+export { RichEditorTool, type RichEditorToolDefinition } from './rich-editor-tool.ts';
+export { RICH_EDITOR_TOOL_DEFINITIONS } from './rich-editor-tools.ts';
 export declare const useColorManager: (manager: ColorManager) => void;
 import { type Rule } from './rules.ts';
 export type { Rule } from './rules.ts';
@@ -39,6 +44,9 @@ export declare abstract class Field extends Component {
     default(value: unknown): this;
     /** Helper text shown under the field. */
     helperText(text: string | null): this;
+    protected _belowContent: ComponentSlot;
+    /** Text, components or actions under the control (after the helper text). Strings are escaped. */
+    belowContent(content: ComponentSlot): this;
     /** Helper text id, linked to the control through `aria-describedby`. */
     protected getHelperTextId(): string | null;
     /** Keeps the label for screen readers only. */
@@ -876,9 +884,18 @@ export declare function richHtmlToDocument(html: string | null | undefined): Ric
  * TipTap document → HTML to save, or null if empty or invalid. The document comes from the browser,
  * so it is rendered then re-parsed to keep only what the schema accepts.
  */
+/** HTML of a document already sanitized (`RichContentRenderer`): no re-parsing. */
+export declare function renderRichDocument(document: unknown): string;
 export declare function richDocumentToHtml(document: unknown): string | null;
 /** Tools of the rich editor's toolbar, in their default groups. */
 export declare const RICH_EDITOR_TOOLS: string[][];
+/** Custom blocks of an editor: a list, or groups of blocks by label. */
+export type CustomBlocks = CustomBlockClass[] | Record<string, CustomBlockClass[]>;
+/**
+ * Rich text editor (TipTap): the browser works on a document, the database receives HTML (or JSON with `json()`).
+ * Besides the starter kit: text colors, merge tags, mentions, custom blocks, columns, resizable images, and your own
+ * tools and TipTap extensions.
+ */
 export declare class RichEditor extends Field {
     private _toolbar;
     private _disabledTools;
@@ -888,12 +905,34 @@ export declare class RichEditor extends Field {
     private _attachmentsDirectory;
     private _attachmentTypes;
     private _attachmentMaxSize;
+    private _customTools;
+    private _textColors;
+    private _customTextColors;
+    private _mergeTags;
+    private _noMergeTagResults;
+    private _mentions;
+    private _customBlocks;
+    private _minimalCustomBlockControls;
+    private _customBlocksGrid;
+    private _searchableCustomBlocks;
+    private _activePanel;
+    private _stickyToolbar;
+    private _resizableImages;
+    private _jsExtensions;
+    private _editorActions;
     static make(name: string): RichEditor;
-    /** Toolbar tools, by group (`[['bold', 'italic', 'link'], ['h2', 'h3'], ['undo', 'redo']]`); see `RICH_EDITOR_TOOLS`. */
+    /** Toolbar tools, by group (`[['bold', 'italic', 'link'], ['h2', 'h3'], ['undo', 'redo']]`); see `RICH_EDITOR_TOOLS` and `RICH_EDITOR_TOOL_DEFINITIONS`. */
     toolbarButtons(groups: string[][] | string[]): this;
+    private assertKnownTools;
     /** Removes buttons; with no argument, removes them all. */
     disableToolbarButtons(tools?: string[]): this;
     disableAllToolbarButtons(condition?: boolean): this;
+    /** Your own toolbar buttons (or replacements of built-in ones, by name); place them with `toolbarButtons()`. */
+    tools(tools: RichEditorTool[]): this;
+    /** Actions mounted by your tools (`RichEditorTool.make('x').action()`), run with the editor selection in `arguments.editorSelection`. */
+    editorActions(actions: Action[]): this;
+    /** Browser TipTap extensions: URLs of ES modules exporting an extension (or an array of them). Register their server side with `registerRichContentExtensions()`. */
+    extensions(urls: string[]): this;
     /** Saves the content as the editor's JSON document instead of HTML. */
     json(condition?: boolean): this;
     placeholder(text: string | null): this;
@@ -904,25 +943,73 @@ export declare class RichEditor extends Field {
     fileAttachmentsAcceptedFileTypes(types: string[]): this;
     /** Maximum size of attached files, in kilobytes. */
     fileAttachmentsMaxSize(kilobytes: number): this;
+    /** Text colors offered by the `textColor` tool (the Tailwind palette by default): `{ brand: TextColor.make('Brand', '#0ea5e9', '#38bdf8') }`. */
+    textColors(colors: Record<string, TextColor> | null): this;
+    getTextColors(): Record<string, TextColor>;
+    /** Lets users pick any color, besides the listed ones. */
+    customTextColors(condition?: boolean): this;
+    /** Merge tags users insert (`mergeTags` tool and `{{` in the text), replaced by values when the content is rendered: `['name', 'today']` or `{ name: 'Name' }`. */
+    mergeTags(tags: string[] | Record<string, string>): this;
+    noMergeTagSearchResultsMessage(message: string | null): this;
+    /** Mentions: `[MentionProvider.make('@').items({ 1: 'Ada' })]`. */
+    mentions(providers: MentionProvider[]): this;
+    /** Custom blocks (`customBlocks` tool), as a list or grouped by label. */
+    customBlocks(blocks: CustomBlocks): this;
+    minimalCustomBlockControls(condition?: boolean): this;
+    /** Shows the blocks of the panel in a grid. */
+    customBlocksGrid(condition?: boolean): this;
+    /** Adds a search field to the blocks panel. */
+    searchableCustomBlocks(condition?: boolean): this;
+    /** Panel open when the editor loads (`customBlocks`, `mergeTags`). */
+    activePanel(panel: string | null): this;
+    /** Keeps the toolbar visible while scrolling the content. */
+    stickyToolbar(condition?: boolean): this;
+    /** Lets users resize images with handles; the size is saved on the image. */
+    resizableImages(condition?: boolean): this;
     private attachmentsStorage;
-    private tools;
+    private findTool;
+    private toolGroups;
+    private blockGroups;
+    getCustomBlock(id: unknown): CustomBlockClass | null;
     hydrateState(value: unknown): unknown;
     getDefaultState(): unknown;
     /** HTML (sanitized by the editor's schema), or the JSON document with `json()` (normalized through the same schema). */
     dehydrateState(state: unknown): unknown;
     getValidationRules(): Promise<Rule[]>;
     getExposedMethods(): string[];
-    getMentionSearchResultsForJs(): unknown[];
-    getMentionLabelsForJs(): unknown[];
-    getCustomBlockPreviewsForJs(): unknown[];
+    private mentionProvider;
+    /** Mention search, for the editor's JavaScript: `[{ id, label }]`. */
+    getMentionSearchResultsForJs(search?: unknown, triggerCharacter?: unknown): Promise<{
+        id: string;
+        label: string;
+    }[]>;
+    /** Current labels of mentioned ids, by trigger character. */
+    getMentionLabelsForJs(mentions?: unknown): Promise<Record<string, Record<string, string>>>;
+    /** Previews of inserted blocks, for the editor's JavaScript. */
+    getCustomBlockPreviewsForJs(customBlocks?: unknown): {
+        key: number;
+        label: string;
+        preview: string;
+        shouldApplyProseStylingToPreview: boolean;
+    }[];
     /**
      * URL of a file the editor just uploaded: the file is checked (type from its content, size), stored, and its public URL returned.
      * It stays stored even if the form is not saved.
      */
     getUploadedFileAttachmentTemporaryUrl(args?: unknown): Promise<string | null>;
     saveUploadedFileAttachmentAndGetUrl(args?: unknown): Promise<string | null>;
-    /** Toolbar "link" action: a modal (URL, new tab), then commands sent back to the browser editor. */
+    /** Sends commands to the editor in the browser (after an action), on the given selection. */
+    runCommands(livewire: any, commands: {
+        name: string;
+        arguments?: unknown[];
+    }[], editorSelection?: unknown): void;
+    /** Toolbar actions: link, text color, custom block, and the ones of `editorActions()`. */
     getActions(): Action[];
+    private textColorAction;
+    /** Modal of a custom block, built from the block class named in the arguments (`id`): insert or edit. */
+    private customBlockAction;
+    private customBlocksPanelHtml;
+    private mergeTagsPanelHtml;
     toHtml(): Promise<string>;
 }
 /** Color picker (hex format). */

package/lib/index.js

@@ -2,7 +2,7 @@
 import { Attributes, HtmlString, cls, e, evaluate, icon, js, sanitizeHtml, views, configured } from '@navette-js/support';
 import { createHash } from 'node:crypto';
 import { t } from '@navette-js/support/i18n';
-import { Component, Icon as SchemaIcon, Schema, Text, childSchema, renderInlineItems, slug } from '@navette-js/schemas';
+import { Component, Icon as SchemaIcon, Schema, Text, childSchema, renderInlineItems, renderSlot, slug } from '@navette-js/schemas';
 import { Action } from '@navette-js/actions';
 import { loadingIndicator } from '@navette-js/support';
 import { randomUUID } from 'node:crypto';
@@ -12,7 +12,12 @@ import TextAlign from '@tiptap/extension-text-align';
 import Subscript from '@tiptap/extension-subscript';
 import Superscript from '@tiptap/extension-superscript';
 import Highlight from '@tiptap/extension-highlight';
-import Image from '@tiptap/extension-image';
+import { RICH_CONTENT_EXTENSIONS, SizedImage, customRichContentExtensions, registerTextColors, sanitizeCssColor, TextColor, textColorsForJs } from "./rich-content.js";
+export { CustomBlockNode, GridColumnNode, GridNode, LeadNode, MentionNode, MentionProvider, MergeTagNode, registerRichContentExtensions, RichContentCustomBlock, RichContentRenderer, sanitizeCssColor, SizedImage, SmallMark, TextColor, TextColorMark } from "./rich-content.js";
+import { RichEditorTool } from "./rich-editor-tool.js";
+export { RichEditorTool } from "./rich-editor-tool.js";
+import { RICH_EDITOR_TOOL_DEFINITIONS } from "./rich-editor-tools.js";
+export { RICH_EDITOR_TOOL_DEFINITIONS } from "./rich-editor-tools.js";
 import { TableKit } from '@tiptap/extension-table';
 import { fileURLToPath } from 'node:url';
 import nodePath from 'node:path';
@@ -61,6 +66,9 @@ export class Field extends Component {
     default(value) { this._default = value; return this; }
     /** Helper text shown under the field. */
     helperText(text) { this._helperText = text; return this; }
+    _belowContent = null;
+    /** Text, components or actions under the control (after the helper text). Strings are escaped. */
+    belowContent(content) { this._belowContent = content; return this; }
     /** Helper text id, linked to the control through `aria-describedby`. */
     getHelperTextId() { return this._helperText !== null ? `${this.getId()}-helper-text` : null; }
     /** Keeps the label for screen readers only. */
@@ -299,6 +307,8 @@ export class Field extends Component {
         // Helper text: a small inline schema under the control.
         if (this._helperText !== null)
             html += `<div id="${e(this.getHelperTextId())}" class="fi-sc fi-inline fi-sc-has-gap fi-sc-dense"><div x-data="filamentSchemaComponent(${e(js({ key: null, exposedMethods: [], path: this.getStatePath(), containerPath: this.container.getStatePath() }))})"><div class="fi-sc-component"><span class="fi-sc-text">${e(this._helperText)}</span></div></div></div>`;
+        if (this._belowContent !== null)
+            html += await renderSlot(this, this._belowContent, this.getKey());
         return views.render('filament-forms::components.field-wrapper', {
             id: this.getId(), label: await this.getLabel(), required: (await this.isMarkedAsRequired()) && !(await this.isDisabled()),
             labelPrefix: options.labelPrefix ?? '', hiddenLabel: this._hiddenLabel, after: options.after ?? '', afterLabel: this._hiddenLabel ? '' : await this.renderAfterLabel(), labelAsDiv: options.labelAsDiv === true, focusable: options.focusable === true, html, errorMessage: errors[0] ?? null, wrapperClass: options.wrapperClass ?? null,
@@ -1884,24 +1894,25 @@ export class ToggleButtons extends Field {
         return this.wrap(`<div ${container.toHtml()}>${grid ? `<div${grid}>${items.join('')}</div>` : items.join('')}</div>`, { wrapperClass: 'fi-fo-toggle-buttons-wrp', labelAsDiv: true, focusable: true, after });
     }
 }
-// Server-side TipTap schema: the nodes and marks the rich editor's default toolbar can produce.
-// Not supported yet: grids, custom blocks, mentions, merge tags, text color, "lead" and "small".
-const RICH_EXTENSIONS = [StarterKit, TextAlign.configure({ types: ['heading', 'paragraph'], defaultAlignment: 'start' }), Subscript, Superscript, Highlight, Image, TableKit];
+// Server-side TipTap schema: the nodes and marks the rich editor can produce, and the extensions your application registers.
+const richExtensions = () => [StarterKit, TextAlign.configure({ types: ['heading', 'paragraph'], defaultAlignment: 'start' }), Subscript, Superscript, Highlight, SizedImage, TableKit, ...RICH_CONTENT_EXTENSIONS, ...customRichContentExtensions];
 const isRichDocument = (value) => !!value && typeof value === 'object' && value.type === 'doc';
 const richText = (node) => (typeof node?.text === 'string' ? node.text : '') + (Array.isArray(node?.content) ? node.content.map(richText).join('') : '');
-const hasRichContent = (node) => node?.type === 'image' || node?.type === 'horizontalRule' || (Array.isArray(node?.content) && node.content.some(hasRichContent));
+const hasRichContent = (node) => ['image', 'horizontalRule', 'mergeTag', 'mention', 'customBlock'].includes(node?.type) || (Array.isArray(node?.content) && node.content.some(hasRichContent));
 /** Stored HTML → TipTap document. Parsing drops anything the schema does not know (scripts, event attributes, `javascript:` links). */
-export function richHtmlToDocument(html) { return generateJSON(html ?? '', RICH_EXTENSIONS); }
+export function richHtmlToDocument(html) { return generateJSON(html ?? '', richExtensions()); }
 /**
  * TipTap document → HTML to save, or null if empty or invalid. The document comes from the browser,
  * so it is rendered then re-parsed to keep only what the schema accepts.
  */
+/** HTML of a document already sanitized (`RichContentRenderer`): no re-parsing. */
+export function renderRichDocument(document) { return generateHTML(document, richExtensions()); }
 export function richDocumentToHtml(document) {
     if (!isRichDocument(document))
         return null;
     try {
-        const clean = generateJSON(generateHTML(document, RICH_EXTENSIONS), RICH_EXTENSIONS);
-        return richText(clean).trim() === '' && !hasRichContent(clean) ? null : generateHTML(clean, RICH_EXTENSIONS);
+        const clean = generateJSON(generateHTML(document, richExtensions()), richExtensions());
+        return richText(clean).trim() === '' && !hasRichContent(clean) ? null : generateHTML(clean, richExtensions());
     }
     catch {
         return null;
@@ -1936,6 +1947,15 @@ async function storeEditorAttachment(field, id, options) {
 }
 /** Tools of the rich editor's toolbar, in their default groups. */
 export const RICH_EDITOR_TOOLS = [['bold', 'italic', 'underline', 'strike', 'subscript', 'superscript', 'link'], ['h2', 'h3'], ['alignStart', 'alignCenter', 'alignEnd'], ['blockquote', 'codeBlock', 'bulletList', 'orderedList'], ['table', 'attachFiles'], ['undo', 'redo']];
+/** The editor selection sent by the browser with a toolbar action. */
+const selectionOf = (args) => (args.editorSelection ?? null);
+// `details` needs a TipTap extension the server schema does not have: its content would be lost on save.
+const BUILT_IN_TOOLS = new Map(RICH_EDITOR_TOOL_DEFINITIONS.filter((definition) => definition.name !== 'details').map((definition) => [definition.name, definition]));
+/**
+ * Rich text editor (TipTap): the browser works on a document, the database receives HTML (or JSON with `json()`).
+ * Besides the starter kit: text colors, merge tags, mentions, custom blocks, columns, resizable images, and your own
+ * tools and TipTap extensions.
+ */
 export class RichEditor extends Field {
     _toolbar = null;
     _disabledTools = [];
@@ -1945,22 +1965,47 @@ export class RichEditor extends Field {
     _attachmentsDirectory = null;
     _attachmentTypes = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
     _attachmentMaxSize = 12288;
+    _customTools = [];
+    _textColors = null;
+    _customTextColors = false;
+    _mergeTags = {};
+    _noMergeTagResults = null;
+    _mentions = [];
+    _customBlocks = [];
+    _minimalCustomBlockControls = false;
+    _customBlocksGrid = false;
+    _searchableCustomBlocks = false;
+    _activePanel = null;
+    _stickyToolbar = false;
+    _resizableImages = false;
+    _jsExtensions = [];
+    _editorActions = [];
     static make(name) { return configured(new RichEditor(name)); }
-    /** Toolbar tools, by group (`[['bold', 'italic', 'link'], ['h2', 'h3'], ['undo', 'redo']]`); see `RICH_EDITOR_TOOLS`. */
+    /** Toolbar tools, by group (`[['bold', 'italic', 'link'], ['h2', 'h3'], ['undo', 'redo']]`); see `RICH_EDITOR_TOOLS` and `RICH_EDITOR_TOOL_DEFINITIONS`. */
     toolbarButtons(groups) {
         const list = (groups.length && typeof groups[0] === 'string' ? [groups] : groups);
-        const known = new Set(RICH_EDITOR_TOOLS.flat());
-        const unknown = list.flat().filter((tool) => !known.has(tool));
-        if (unknown.length)
-            throw new Error(`RichEditor: unknown toolbar buttons ${unknown.join(', ')} (available: ${[...known].join(', ')}).`);
         this._toolbar = list;
+        this.assertKnownTools();
         return this;
     }
+    assertKnownTools() {
+        if (!this._toolbar)
+            return;
+        const unknown = this._toolbar.flat().filter((tool) => !this.findTool(tool));
+        if (unknown.length)
+            throw new Error(`RichEditor: unknown toolbar buttons ${unknown.join(', ')} (available: ${[...BUILT_IN_TOOLS.keys(), ...this._customTools.map((tool) => tool.getName())].join(', ')}).`);
+    }
     /** Removes buttons; with no argument, removes them all. */
     disableToolbarButtons(tools = []) { if (!tools.length)
         this._toolbar = []; this._disabledTools = [...this._disabledTools, ...tools]; return this; }
     disableAllToolbarButtons(condition = true) { if (condition)
         this._toolbar = []; return this; }
+    /** Your own toolbar buttons (or replacements of built-in ones, by name); place them with `toolbarButtons()`. */
+    tools(tools) { this._customTools = [...this._customTools.filter((tool) => !tools.some((other) => other.getName() === tool.getName())), ...tools]; this.assertKnownTools(); return this; }
+    /** Actions mounted by your tools (`RichEditorTool.make('x').action()`), run with the editor selection in `arguments.editorSelection`. */
+    editorActions(actions) { this._editorActions = [...this._editorActions, ...actions]; return this; }
+    /** Browser TipTap extensions: URLs of ES modules exporting an extension (or an array of them). Register their server side with `registerRichContentExtensions()`. */
+    extensions(urls) { this._jsExtensions = [...this._jsExtensions, ...urls]; return this; }
     /** Saves the content as the editor's JSON document instead of HTML. */
     json(condition = true) { this._json = condition; return this; }
     placeholder(text) { this._richPlaceholder = text; return this; }
@@ -1971,8 +2016,41 @@ export class RichEditor extends Field {
     fileAttachmentsAcceptedFileTypes(types) { this._attachmentTypes = types.filter((type) => type.startsWith('image/') && type !== 'image/svg+xml'); return this; }
     /** Maximum size of attached files, in kilobytes. */
     fileAttachmentsMaxSize(kilobytes) { this._attachmentMaxSize = kilobytes; return this; }
+    /** Text colors offered by the `textColor` tool (the Tailwind palette by default): `{ brand: TextColor.make('Brand', '#0ea5e9', '#38bdf8') }`. */
+    textColors(colors) { this._textColors = colors; if (colors)
+        registerTextColors(colors); return this; }
+    getTextColors() { return this._textColors ?? TextColor.getDefaults(); }
+    /** Lets users pick any color, besides the listed ones. */
+    customTextColors(condition = true) { this._customTextColors = condition; return this; }
+    /** Merge tags users insert (`mergeTags` tool and `{{` in the text), replaced by values when the content is rendered: `['name', 'today']` or `{ name: 'Name' }`. */
+    mergeTags(tags) { this._mergeTags = Array.isArray(tags) ? Object.fromEntries(tags.map((tag) => [tag, tag])) : { ...tags }; return this; }
+    noMergeTagSearchResultsMessage(message) { this._noMergeTagResults = message; return this; }
+    /** Mentions: `[MentionProvider.make('@').items({ 1: 'Ada' })]`. */
+    mentions(providers) { this._mentions = providers; return this; }
+    /** Custom blocks (`customBlocks` tool), as a list or grouped by label. */
+    customBlocks(blocks) { this._customBlocks = blocks; return this; }
+    minimalCustomBlockControls(condition = true) { this._minimalCustomBlockControls = condition; return this; }
+    /** Shows the blocks of the panel in a grid. */
+    customBlocksGrid(condition = true) { this._customBlocksGrid = condition; return this; }
+    /** Adds a search field to the blocks panel. */
+    searchableCustomBlocks(condition = true) { this._searchableCustomBlocks = condition; return this; }
+    /** Panel open when the editor loads (`customBlocks`, `mergeTags`). */
+    activePanel(panel) { this._activePanel = panel; return this; }
+    /** Keeps the toolbar visible while scrolling the content. */
+    stickyToolbar(condition = true) { this._stickyToolbar = condition; return this; }
+    /** Lets users resize images with handles; the size is saved on the image. */
+    resizableImages(condition = true) { this._resizableImages = condition; return this; }
     attachmentsStorage() { return this._attachmentsStorage ?? FileUpload.storage; }
-    tools() { return (this._toolbar ?? RICH_EDITOR_TOOLS).map((group) => group.filter((tool) => !this._disabledTools.includes(tool) && (tool !== 'attachFiles' || this.attachmentsStorage() !== null))).filter((group) => group.length); }
+    findTool(name) {
+        const custom = this._customTools.find((tool) => tool.getName() === name);
+        if (custom)
+            return custom;
+        const definition = BUILT_IN_TOOLS.get(name);
+        return definition ? RichEditorTool.fromDefinition(definition) : null;
+    }
+    toolGroups() { return (this._toolbar ?? RICH_EDITOR_TOOLS).map((group) => group.filter((tool) => !this._disabledTools.includes(tool) && (tool !== 'attachFiles' || this.attachmentsStorage() !== null))).filter((group) => group.length); }
+    blockGroups() { return Array.isArray(this._customBlocks) ? [['', this._customBlocks]] : Object.entries(this._customBlocks); }
+    getCustomBlock(id) { return this.blockGroups().flatMap(([, blocks]) => blocks).find((block) => block.getId() === id) ?? null; }
     hydrateState(value) {
         if (typeof value === 'string' && value.trim().startsWith('{')) {
             try {
@@ -1997,9 +2075,43 @@ export class RichEditor extends Field {
         return [...rules, ...this._rules];
     }
     getExposedMethods() { return ['getMentionSearchResultsForJs', 'getMentionLabelsForJs', 'getCustomBlockPreviewsForJs', 'getUploadedFileAttachmentTemporaryUrl', 'saveUploadedFileAttachmentAndGetUrl']; }
-    getMentionSearchResultsForJs() { return []; }
-    getMentionLabelsForJs() { return []; }
-    getCustomBlockPreviewsForJs() { return []; }
+    mentionProvider(char) { return this._mentions.find((provider) => provider.getTriggerCharacter() === char) ?? this._mentions[0] ?? null; }
+    /** Mention search, for the editor's JavaScript: `[{ id, label }]`. */
+    async getMentionSearchResultsForJs(search = '', triggerCharacter = '@') {
+        const provider = this.mentionProvider(triggerCharacter ?? '@');
+        if (!provider || (await this.isDisabled()))
+            return [];
+        return Object.entries(await provider.getSearchResults(typeof search === 'string' ? search.slice(0, 200) : '')).slice(0, 50).map(([id, label]) => ({ id, label }));
+    }
+    /** Current labels of mentioned ids, by trigger character. */
+    async getMentionLabelsForJs(mentions = []) {
+        const byChar = new Map();
+        for (const mention of Array.isArray(mentions) ? mentions.slice(0, 500) : []) {
+            const char = String(mention?.triggerCharacter ?? '@'), id = mention?.id;
+            if (id === null || id === undefined)
+                continue;
+            byChar.set(char, [...(byChar.get(char) ?? []), String(id)]);
+        }
+        const labels = {};
+        for (const [char, ids] of byChar) {
+            const provider = this.mentionProvider(char);
+            if (provider)
+                labels[char] = await provider.getLabels(ids);
+        }
+        return labels;
+    }
+    /** Previews of inserted blocks, for the editor's JavaScript. */
+    getCustomBlockPreviewsForJs(customBlocks = []) {
+        const previews = [];
+        for (const item of Array.isArray(customBlocks) ? customBlocks.slice(0, 200) : []) {
+            const block = this.getCustomBlock(item?.id);
+            const config = item?.config && typeof item.config === 'object' && !Array.isArray(item.config) ? item.config : {};
+            if (!block || !Number.isInteger(item?.key))
+                continue;
+            previews.push({ key: item.key, label: block.getPreviewLabel(config), preview: Buffer.from(block.toPreviewHtml(config) ?? '').toString('base64'), shouldApplyProseStylingToPreview: block.shouldApplyProseStylingToPreview(config) });
+        }
+        return previews;
+    }
     /**
      * URL of a file the editor just uploaded: the file is checked (type from its content, size), stored, and its public URL returned.
      * It stays stored even if the form is not saved.
@@ -2007,15 +2119,19 @@ export class RichEditor extends Field {
     async getUploadedFileAttachmentTemporaryUrl(args = {}) {
         const id = String(args?.attachment ?? '');
         const storage = this.attachmentsStorage();
-        if (!storage || !/^[A-Za-z0-9_-]{1,64}$/.test(id) || !this.tools().flat().includes('attachFiles') || (await this.isDisabled()))
+        if (!storage || !/^[A-Za-z0-9_-]{1,64}$/.test(id) || !this.toolGroups().flat().includes('attachFiles') || (await this.isDisabled()))
             return null;
         return storeEditorAttachment(this, id, { storage, directory: this._attachmentsDirectory, types: this._attachmentTypes, maxSize: this._attachmentMaxSize });
     }
     async saveUploadedFileAttachmentAndGetUrl(args = {}) { return this.getUploadedFileAttachmentTemporaryUrl(args); }
-    /** Toolbar "link" action: a modal (URL, new tab), then commands sent back to the browser editor. */
+    /** Sends commands to the editor in the browser (after an action), on the given selection. */
+    runCommands(livewire, commands, editorSelection = null) {
+        const key = this.getKey();
+        livewire.dispatch('run-rich-editor-commands', { awaitSchemaComponent: key, livewireId: livewire.id, key, editorSelection, commands: commands.map((command) => ({ name: command.name, arguments: command.arguments ?? [] })) });
+    }
+    /** Toolbar actions: link, text color, custom block, and the ones of `editorActions()`. */
     getActions() {
         const tr = (name) => t(`filament-forms::components.rich_editor.actions.link.${name}`);
-        const key = this.getKey();
         return [
             ...this.getHintActions(),
             Action.make('link').label(tr('label')).modalHeading(tr('modal.heading')).modalWidth('lg')
@@ -2027,20 +2143,107 @@ export class RichEditor extends Field {
                 Checkbox.make('shouldOpenInNewTab').label(tr('modal.form.should_open_in_new_tab.label')),
             ])
                 .action(({ livewire, arguments: args, data }) => {
-                const selection = (args.editorSelection ?? null);
+                const selection = selectionOf(args);
                 const single = selection?.head === selection?.anchor;
                 const url = typeof data.url === 'string' && data.url !== '' ? data.url : null;
-                const commands = [
+                this.runCommands(livewire, [
                     ...(single ? [{ name: 'extendMarkRange', arguments: ['link'] }] : []),
-                    url ? { name: 'setLink', arguments: [{ href: url, target: data.shouldOpenInNewTab ? '_blank' : null }] } : { name: 'unsetLink', arguments: [] },
-                ];
-                livewire.dispatch('run-rich-editor-commands', { awaitSchemaComponent: key, livewireId: livewire.id, key, editorSelection: selection, commands });
+                    url ? { name: 'setLink', arguments: [{ href: url, target: data.shouldOpenInNewTab ? '_blank' : null }] } : { name: 'unsetLink' },
+                ], selection);
             }),
+            this.textColorAction(),
+            this.customBlockAction(),
+            ...this._editorActions,
         ];
     }
+    textColorAction() {
+        const tr = (name) => t(`filament-forms::components.rich_editor.actions.text_color.${name}`);
+        return Action.make('textColor').label(tr('label')).modalHeading(tr('modal.heading')).modalWidth('lg')
+            .fillForm(({ arguments: args }) => {
+            const color = typeof args.color === 'string' ? args.color : null;
+            if (!color)
+                return {};
+            const known = Object.hasOwn(this.getTextColors(), color);
+            return { color: known ? color : null, customColor: this._customTextColors && !known ? color : null };
+        })
+            .schema(() => {
+            const options = Object.fromEntries(Object.entries(this.getTextColors()).map(([name, color]) => [name, `<div class="fi-fo-rich-editor-text-color-select-option"><div class="fi-fo-rich-editor-text-color-select-option-preview" style="--color: ${e(sanitizeCssColor(color.getColor()) ?? '')}; --dark-color: ${e(sanitizeCssColor(color.getDarkColor()) ?? '')}"></div><div>${e(color.getLabel() ?? name)}</div></div>`]));
+            return [
+                ...(Object.keys(options).length ? [Select.make('color').label(tr('modal.form.color.label')).options(options).allowHtml().native(false).live()] : []),
+                ...(this._customTextColors ? [ColorPicker.make('customColor').label(tr('modal.form.custom_color.label')).visible(({ get }) => !get('color'))] : []),
+            ];
+        })
+            .action(({ livewire, arguments: args, data }) => {
+            const selection = selectionOf(args);
+            const single = selection?.head === selection?.anchor;
+            const picked = typeof data.color === 'string' && Object.hasOwn(this.getTextColors(), data.color) ? data.color : this._customTextColors ? sanitizeCssColor(data.customColor) : null;
+            this.runCommands(livewire, picked
+                ? [...(single ? [{ name: 'extendMarkRange', arguments: ['textColor'] }] : []), { name: 'setTextColor', arguments: [{ color: picked }] }]
+                : [...(single ? [{ name: 'extendMarkRange', arguments: ['textColor'] }] : []), { name: 'unsetTextColor' }], selection);
+        });
+    }
+    /** Modal of a custom block, built from the block class named in the arguments (`id`): insert or edit. */
+    customBlockAction() {
+        const blockOf = (args) => this.getCustomBlock(args?.id);
+        const configured = (args) => { const block = blockOf(args); return block ? block.configureEditorAction(Action.make('customBlock')) : null; };
+        const argumentsOf = (livewire) => livewire?.mountedActions?.find?.((mounted) => mounted.name === 'customBlock')?.arguments ?? {};
+        return Action.make('customBlock').modalWidth('lg')
+            .modalHeading(({ arguments: args }) => blockOf(args)?.getLabel() ?? null)
+            .modalSubmitActionLabel(({ arguments: args }) => t(`filament-forms::components.rich_editor.actions.custom_block.modal.actions.${args.mode === 'edit' ? 'save' : 'insert'}.label`))
+            .modalHidden(async (ctx) => { const action = configured(ctx.arguments); return !action || (await action.isModalHidden(ctx)); })
+            .fillForm(({ arguments: args }) => (args.config && typeof args.config === 'object' && !Array.isArray(args.config) ? args.config : {}))
+            .schema((schema) => configured(argumentsOf(schema.livewire))?.applySchema(schema) ?? schema.components([]))
+            .action(({ livewire, arguments: args, data }) => {
+            const block = blockOf(args);
+            if (!block)
+                return;
+            const config = data ?? {};
+            const content = { type: 'customBlock', attrs: { config, id: block.getId(), label: block.getPreviewLabel(config), preview: Buffer.from(block.toPreviewHtml(config) ?? '').toString('base64'), shouldApplyProseStylingToPreview: block.shouldApplyProseStylingToPreview(config) } };
+            const selection = { ...(selectionOf(args) ?? {}) };
+            if (args.dragPosition !== undefined && args.dragPosition !== null) {
+                this.runCommands(livewire, [{ name: 'insertContentAt', arguments: [args.dragPosition, content] }]);
+                return;
+            }
+            if (selection.type === 'node' && args.mode === 'insert') {
+                this.runCommands(livewire, [{ name: 'insertContentAt', arguments: [Number(selection.anchor ?? -1) + 1, content] }]);
+                return;
+            }
+            if (args.mode === 'edit' && selection.type !== 'node') {
+                selection.type = 'node';
+                selection.anchor = Number(selection.anchor ?? 1) - 1;
+                delete selection.head;
+            }
+            this.runCommands(livewire, [{ name: 'insertContent', arguments: [content] }], selection);
+        });
+    }
+    customBlocksPanelHtml(key) {
+        const searchable = this._searchableCustomBlocks;
+        const groups = this.blockGroups();
+        const allLabels = groups.flatMap(([label, blocks]) => [label, ...blocks.map((block) => block.getLabel())]).filter(Boolean);
+        const parts = [];
+        if (searchable)
+            parts.push(`<div class="fi-fo-rich-editor-custom-blocks-search">${icon('m-magnifying-glass')}<input type="search" x-model="customBlockSearch" x-on:keydown.enter.prevent aria-label="${e(t('filament-forms::components.rich_editor.custom_blocks.search_label'))}" placeholder="${e(t('filament-forms::components.rich_editor.custom_blocks.search_prompt'))}" class="fi-fo-rich-editor-custom-blocks-search-input" /></div>`);
+        const list = groups.map(([groupLabel, blocks]) => {
+            const groupLabels = [groupLabel, ...blocks.map((block) => block.getLabel())];
+            const show = (labels) => (searchable ? ` x-show="${e(`matchesCustomBlockSearch(${js(labels)})`)}"` : '');
+            const header = groupLabel ? `<h4${show(groupLabels)} class="fi-fo-rich-editor-custom-blocks-group-header">${e(groupLabel)}</h4>` : '';
+            const buttons = blocks.map((block) => {
+                const id = block.getId();
+                const blockIcon = block.getIcon();
+                return `<button draggable="true" type="button" data-block-id="${e(id)}" x-data="{ isLoading: false }"${show([groupLabel, block.getLabel()])} x-on:click="${e(`isLoading = true\n$wire.mountAction('customBlock', { editorSelection, id: ${js(id)}, mode: 'insert' }, { schemaComponent: ${js(key)} })`)}" x-on:dragstart="${e(`$event.dataTransfer.setData('customBlock', ${js(id)})`)}" x-on:open-modal.window="isLoading = false" x-on:run-rich-editor-commands.window="isLoading = false" class="fi-fo-rich-editor-custom-block-btn">${blockIcon ? `<span x-show="! isLoading" class="fi-fo-rich-editor-custom-block-icon">${icon(blockIcon)}</span>` : ''}${loadingIndicator(new Attributes({ 'x-show': 'isLoading', 'x-cloak': '' }))}<span>${e(block.getLabel())}</span></button>`;
+            }).join('');
+            return `${header}<div${show(groupLabels)} class="${cls(['fi-fo-rich-editor-custom-blocks-list', { 'fi-fo-rich-editor-custom-blocks-grid': this._customBlocksGrid }])}">${buttons}</div>`;
+        }).join('');
+        const noResults = searchable ? `<p x-show="${e(`! matchesCustomBlockSearch(${js(allLabels)})`)}" x-cloak role="status" class="fi-fo-rich-editor-custom-blocks-no-results">${e(t('filament-forms::components.rich_editor.custom_blocks.no_search_results_message'))}</p>` : '';
+        return `${parts.join('')}<div class="fi-fo-rich-editor-custom-blocks-ctn">${list}${noResults}</div>`;
+    }
+    mergeTagsPanelHtml() {
+        return Object.entries(this._mergeTags).map(([id, label]) => `<button draggable="true" type="button" x-on:click="${e(`insertMergeTag(${js(id)})`)}" x-on:dragstart="${e(`$event.dataTransfer.setData('mergeTag', ${js(id)})`)}" class="fi-fo-rich-editor-merge-tag-btn"><span data-type="mergeTag" data-id="${e(id)}">${e(label)}</span></button>`).join('');
+    }
     async toHtml() {
-        let html = views.render('filament-forms::components.rich-editor', { livewireId: this.livewire.id, key: this.getKey(), statePath: this.getStatePath(), label: await this.getLabel(), js });
-        // Toolbar: the snapshot's buttons, regrouped as configured.
+        const key = this.getKey();
+        let html = views.render('filament-forms::components.rich-editor', { livewireId: this.livewire.id, key, statePath: this.getStatePath(), label: await this.getLabel(), js });
+        // Toolbar: the configured groups, each tool rendered from its definition.
         const toolbarStart = html.indexOf('data-rich-editor-toolbar="main"');
         if (toolbarStart >= 0) {
             const open = html.indexOf('>', toolbarStart) + 1;
@@ -2050,24 +2253,42 @@ export class RichEditor extends Field {
             if (close < 0)
                 throw new Error('RichEditor: unexpected view markup (toolbar end not found).');
             const body = html.slice(open, close);
-            const buttons = new Map();
-            for (const match of body.matchAll(/<button data-rich-editor-tool="([A-Za-z0-9]+)"[\s\S]*?<\/button>/g))
-                buttons.set(match[1], match[0]);
-            const groups = this.tools().map((group) => `<div class="fi-fo-rich-editor-toolbar-group">${group.map((tool) => buttons.get(tool) ?? '').join('')}</div>`).join('');
+            const groups = this.toolGroups().map((group) => `<div class="fi-fo-rich-editor-toolbar-group">${group.map((tool) => this.findTool(tool)?.toHtml() ?? '').join('')}</div>`).join('');
             const endOfToolbar = body.lastIndexOf('</div>');
             html = html.slice(0, open) + groups + body.slice(endOfToolbar) + html.slice(close);
+            if (this._stickyToolbar)
+                html = html.replace('class="fi-fo-rich-editor-toolbar "', 'class="fi-fo-rich-editor-toolbar fi-fo-rich-editor-sticky-toolbar"');
+        }
+        // Panels: custom blocks and merge tags.
+        const blocksStart = html.indexOf('<div class="fi-fo-rich-editor-custom-blocks-ctn">');
+        if (blocksStart >= 0) {
+            const blocksEnd = html.indexOf('</div>', blocksStart) + '</div>'.length;
+            html = html.slice(0, blocksStart) + this.customBlocksPanelHtml(key) + html.slice(blocksEnd);
+        }
+        const tagsStart = html.indexOf('<div class="fi-fo-rich-editor-merge-tags-list">');
+        if (tagsStart >= 0) {
+            const open = html.indexOf('>', tagsStart) + 1;
+            html = html.slice(0, open) + this.mergeTagsPanelHtml() + html.slice(html.indexOf('</div>', open));
         }
-        const attach = this.tools().flat().includes('attachFiles');
-        const tr = (key, replace = {}) => t(`filament-forms::components.rich_editor.${key}`, replace);
+        const attach = this.toolGroups().flat().includes('attachFiles');
+        const mentions = await Promise.all(this._mentions.map((provider) => provider.toJs()));
         html = html.replace('canAttachFiles: true,', `canAttachFiles: ${attach ? 'true' : 'false'},`)
             .replace('maxFileSize: 12288,', `maxFileSize: ${this._attachmentMaxSize},`)
             .replace(/maxFileSizeValidationMessage: '[^']*',/, () => `maxFileSizeValidationMessage: ${js(`Uploaded files must not be greater than ${this._attachmentMaxSize} kilobytes.`)},`)
             .replace(/acceptedFileTypes: JSON\.parse\('[^']*'\),/, () => `acceptedFileTypes: ${js(this._attachmentTypes)},`)
             .replace(/acceptedFileTypesValidationMessage: '[^']*',/, () => `acceptedFileTypesValidationMessage: ${js(`Uploaded files must be of type: ${this._attachmentTypes.join(', ')}.`)},`)
+            .replace('activePanel: null,', () => `activePanel: ${js(this._activePanel)},`)
+            .replace('extensions: [],', () => `extensions: ${js(this._jsExtensions)},`)
+            .replace('hasResizableImages: false,', `hasResizableImages: ${this._resizableImages ? 'true' : 'false'},`)
+            .replace('hasMinimalCustomBlockControls: false,', `hasMinimalCustomBlockControls: ${this._minimalCustomBlockControls ? 'true' : 'false'},`)
+            .replace('hasStickyToolbar: false,', `hasStickyToolbar: ${this._stickyToolbar ? 'true' : 'false'},`)
+            .replace('mentions: [],', () => `mentions: ${js(mentions)},`)
+            .replace('mergeTags: [],', () => `mergeTags: ${js(Object.keys(this._mergeTags).length ? this._mergeTags : [])},`)
+            .replace(/noMergeTagSearchResultsMessage: '[^']*',/, () => `noMergeTagSearchResultsMessage: ${js(this._noMergeTagResults ?? t('filament-forms::components.rich_editor.no_merge_tag_search_results_message'))},`)
+            .replace(/textColors: JSON\.parse\('[^']*'\),/, () => `textColors: ${js(textColorsForJs(this.getTextColors()))},`)
             .replace('placeholder: null,', `placeholder: ${js(this._richPlaceholder)},`)
             .replace('isLiveOnBlur: false,', `isLiveOnBlur: ${this._liveMode === 'blur' ? 'true' : 'false'},`)
             .replace(/state: \$wire\.\$entangle\(('[^']*'), false\)/, (_m, path) => `state: $wire.$entangle(${path}, ${this._liveMode === 'live' ? 'true' : 'false'})`);
-        void tr;
         return this.wrap(html, { labelAsDiv: true });
     }
 }