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

package/lib/rich-content.d.ts

@@ -0,0 +1,138 @@
+import { Mark, Node, type Extensions } from '@tiptap/core';
+import type { Action } from '@navette-js/actions';
+type MaybePromise<T> = T | Promise<T>;
+/** CSS color written by a user: hexadecimal, rgb()/hsl()/oklch() with plain numbers, or a CSS color name. `null` otherwise. */
+export declare function sanitizeCssColor(value: unknown): string | null;
+/** A text color of the editor: its label, its color in light mode, and in dark mode. */
+export declare class TextColor {
+    readonly label: string | null;
+    readonly color: string | null;
+    readonly darkColor: string | null;
+    constructor(label?: string | null, color?: string | null, darkColor?: string | null);
+    static make(label?: string | null, color?: string | null, darkColor?: string | null): TextColor;
+    getLabel(): string | null;
+    getColor(): string | null;
+    getDarkColor(): string | null;
+    /** The Tailwind palette: shade 600, and 400 in dark mode. */
+    static getDefaults(): Record<string, TextColor>;
+}
+/** Colors for the editor's JavaScript: `{ name: { color, darkColor } }`. */
+export declare const textColorsForJs: (colors: Record<string, TextColor>) => {
+    [k: string]: {
+        color: string;
+        darkColor: string;
+    };
+};
+/** Text colors known when content is saved and rendered (an editor's `textColors()` registers its own). */
+export declare function registerTextColors(colors: Record<string, TextColor>): void;
+/** Who or what can be mentioned after a trigger character (`@` for users, `#` for tags…). */
+export declare class MentionProvider {
+    protected _char: string;
+    protected _items: Record<string, string> | (() => MaybePromise<Record<string, string>>);
+    protected _search: ((search: string) => MaybePromise<Record<string, string>>) | null;
+    protected _labels: ((ids: string[]) => MaybePromise<Record<string, string>>) | null;
+    protected _url: ((id: string, label: string) => string | null) | null;
+    protected _extraAttributes: Record<string, string>;
+    protected _messages: {
+        noItems?: string | null;
+        noSearchResults?: string | null;
+        searching?: string | null;
+        searchPrompt?: string | null;
+    };
+    constructor(char: string);
+    static make(char: string): MentionProvider;
+    getTriggerCharacter(): string;
+    /** Mentionable items, `{ id: label }`, offered and filtered in the browser. */
+    items(items: Record<string, string> | (() => MaybePromise<Record<string, string>>)): this;
+    /** Searches on the server as the user types (large lists). */
+    getSearchResultsUsing(callback: ((search: string) => MaybePromise<Record<string, string>>) | null): this;
+    /** Labels of mentioned ids, to show current names in stored content. */
+    getLabelsUsing(callback: ((ids: string[]) => MaybePromise<Record<string, string>>) | null): this;
+    /** Link of a mention in rendered content. */
+    url(callback: ((id: string, label: string) => string | null) | null): this;
+    extraAttributes(attributes: Record<string, string>): this;
+    noItemsMessage(message: string | null): this;
+    noSearchResultsMessage(message: string | null): this;
+    searchingMessage(message: string | null): this;
+    searchPrompt(message: string | null): this;
+    isSearchable(): boolean;
+    getItems(): Promise<Record<string, string>>;
+    getSearchResults(search: string): Promise<Record<string, string>>;
+    getLabels(ids: string[]): Promise<Record<string, string>>;
+    getUrl(id: string, label: string): string | null;
+    toJs(): Promise<Record<string, unknown>>;
+}
+/**
+ * A block users insert in the content (a call to action, a video, a product…), configured in a modal. Extend this class:
+ * `id` and `label`, the modal's fields in `configureEditorAction()`, the preview in the editor, and the final HTML.
+ */
+export declare abstract class RichContentCustomBlock {
+    /** Unique id, stored in the content. */
+    static getId(): string;
+    static getLabel(): string;
+    /** Icon in the blocks panel. */
+    static getIcon(): string | null;
+    /** Group of the block in the panel (none by default). */
+    static getGroup(): string | null;
+    /** Modal of the block: add fields with `action.schema([...])`. Without fields, the block is inserted directly. */
+    static configureEditorAction(action: Action): Action;
+    /** Label of an inserted block in the editor. */
+    static getPreviewLabel(_config: Record<string, unknown>): string;
+    /** HTML of the block in the editor (build it from escaped values). */
+    static toPreviewHtml(_config: Record<string, unknown>): string | null;
+    static shouldApplyProseStylingToPreview(_config: Record<string, unknown>): boolean;
+    /** HTML of the block in rendered content; `data` comes from `RichContentRenderer.customBlocks()`. Build it from escaped values. */
+    static toHtml(_config: Record<string, unknown>, _data: Record<string, unknown>): string | null;
+}
+export type CustomBlockClass = typeof RichContentCustomBlock;
+/** `<span class="color" data-color="red">`: the color must be a known palette name or a safe CSS color. */
+export declare const TextColorMark: Mark<any, any>;
+/** `<span data-type="mergeTag" data-id="name">`: replaced by its value when the content is rendered. */
+export declare const MergeTagNode: Node<any, any>;
+/** `<span data-type="mention" data-id="7" data-label="Ada" data-char="@">@Ada</span>`. */
+export declare const MentionNode: Node<any, any>;
+/** `<div data-type="customBlock" data-id="hero" data-config="{…}">`: rendered by its block class. */
+export declare const CustomBlockNode: Node<any, any>;
+/** Images with an optional id (attachments) and size (resizable images). */
+export declare const SizedImage: Node<import("@tiptap/extension-image").ImageOptions, any>;
+/** Extensions added to the editor's schema by your application (`registerRichContentExtensions()`). */
+export declare const customRichContentExtensions: Extensions;
+/**
+ * Adds TipTap extensions to the server schema of every rich editor and renderer: content using their nodes and marks is then
+ * kept when saved. Load the matching browser extensions with `RichEditor.extensions()`.
+ */
+export declare function registerRichContentExtensions(...extensions: Extensions): void;
+/**
+ * Renders stored rich content (HTML or JSON) for display: merge tags replaced by their values, mentions with their current
+ * labels and links, custom blocks rendered by their classes. The output is sanitized by the editor's schema.
+ */
+export declare class RichContentRenderer {
+    protected content: unknown;
+    protected _mergeTags: Record<string, unknown | (() => unknown)>;
+    protected _blocks: Record<string, {
+        block: CustomBlockClass;
+        data: Record<string, unknown>;
+    }>;
+    protected _mentions: MentionProvider[];
+    constructor(content: unknown);
+    static make(content: unknown): RichContentRenderer;
+    /** Values of the merge tags: text (escaped), an `HtmlString` (inserted as is), or a function returning one. */
+    mergeTags(values: Record<string, unknown | (() => unknown)>): this;
+    /** Block classes, optionally with data passed to their `toHtml()`: `[HeroBlock]` or `{ hero: { block: HeroBlock, data } }`. */
+    customBlocks(blocks: CustomBlockClass[] | Record<string, {
+        block: CustomBlockClass;
+        data?: Record<string, unknown>;
+    }>): this;
+    mentions(providers: MentionProvider[]): this;
+    toHtml(): Promise<string>;
+}
+/** "Lead" paragraph group: `<div class="lead">`. */
+export declare const LeadNode: Node<any, any>;
+/** Small text: `<small>`. */
+export declare const SmallMark: Mark<any, any>;
+/** Columns: `<div class="grid-layout" data-cols="2">` with `<div class="grid-layout-col">` children. */
+export declare const GridNode: Node<any, any>;
+export declare const GridColumnNode: Node<any, any>;
+/** Server schema additions of the rich editor, besides the starter kit. */
+export declare const RICH_CONTENT_EXTENSIONS: Extensions;
+export {};

package/lib/rich-content.js

@@ -0,0 +1,350 @@
+// Rich content beyond the starter kit: text colors, merge tags, mentions, custom blocks and resizable images, on the server
+// (sanitizing what the editor sends, and rendering stored content), with the matching editor configuration objects.
+import { randomBytes } from 'node:crypto';
+import { Mark, Node, mergeAttributes } from '@tiptap/core';
+import Image from '@tiptap/extension-image';
+import { Color, HtmlString } from '@navette-js/support';
+import { t } from '@navette-js/support/i18n';
+// ------------------------------------------------------------------ colors
+/** CSS color written by a user: hexadecimal, rgb()/hsl()/oklch() with plain numbers, or a CSS color name. `null` otherwise. */
+export function sanitizeCssColor(value) {
+    if (typeof value !== 'string')
+        return null;
+    const color = value.trim();
+    if (/^#[0-9a-f]{3,8}$/i.test(color))
+        return color;
+    if (/^(rgb|rgba|hsl|hsla|oklch|oklab|lab|lch)\(\s*[-0-9.%\s,/a-z]{1,80}\)$/i.test(color) && !/(url|expression|var|attr)\s*\(/i.test(color.slice(color.indexOf('(') + 1)))
+        return color;
+    if (/^[a-z]{3,20}$/i.test(color))
+        return color.toLowerCase();
+    return null;
+}
+/** A text color of the editor: its label, its color in light mode, and in dark mode. */
+export class TextColor {
+    label;
+    color;
+    darkColor;
+    constructor(label = null, color = null, darkColor = null) { this.label = label; this.color = color; this.darkColor = darkColor; }
+    static make(label = null, color = null, darkColor = null) { return new this(label, color, darkColor); }
+    getLabel() { return this.label; }
+    getColor() { return this.color; }
+    getDarkColor() { return this.darkColor ?? this.color; }
+    /** The Tailwind palette: shade 600, and 400 in dark mode. */
+    static getDefaults() {
+        return Object.fromEntries(Object.entries(Color).map(([name, palette]) => {
+            const key = name.toLowerCase();
+            const translation = t(`filament-forms::components.rich_editor.actions.text_color.modal.form.color.options.${key}`);
+            return [key, TextColor.make(translation.includes('::') ? name : translation, palette[600], palette[400] ?? null)];
+        }));
+    }
+}
+/** Colors for the editor's JavaScript: `{ name: { color, darkColor } }`. */
+export const textColorsForJs = (colors) => Object.fromEntries(Object.entries(colors).map(([name, color]) => [name, { color: color.getColor(), darkColor: color.getDarkColor() }]));
+let defaultTextColors = null;
+const extraTextColors = {};
+const knownTextColors = () => ({ ...(defaultTextColors ??= TextColor.getDefaults()), ...extraTextColors });
+/** Text colors known when content is saved and rendered (an editor's `textColors()` registers its own). */
+export function registerTextColors(colors) { Object.assign(extraTextColors, colors); }
+// ------------------------------------------------------------------ mentions
+/** Who or what can be mentioned after a trigger character (`@` for users, `#` for tags…). */
+export class MentionProvider {
+    _char;
+    _items = {};
+    _search = null;
+    _labels = null;
+    _url = null;
+    _extraAttributes = {};
+    _messages = {};
+    constructor(char) { this._char = char; }
+    static make(char) { return new this(char); }
+    getTriggerCharacter() { return this._char; }
+    /** Mentionable items, `{ id: label }`, offered and filtered in the browser. */
+    items(items) { this._items = items; return this; }
+    /** Searches on the server as the user types (large lists). */
+    getSearchResultsUsing(callback) { this._search = callback; return this; }
+    /** Labels of mentioned ids, to show current names in stored content. */
+    getLabelsUsing(callback) { this._labels = callback; return this; }
+    /** Link of a mention in rendered content. */
+    url(callback) { this._url = callback; return this; }
+    extraAttributes(attributes) { this._extraAttributes = attributes; return this; }
+    noItemsMessage(message) { this._messages.noItems = message; return this; }
+    noSearchResultsMessage(message) { this._messages.noSearchResults = message; return this; }
+    searchingMessage(message) { this._messages.searching = message; return this; }
+    searchPrompt(message) { this._messages.searchPrompt = message; return this; }
+    isSearchable() { return this._search !== null; }
+    async getItems() {
+        const items = typeof this._items === 'function' ? await this._items() : this._items;
+        return Object.fromEntries(Object.entries(items ?? {}).map(([id, label]) => [String(id), String(label)]));
+    }
+    async getSearchResults(search) {
+        if (this._search)
+            return Object.fromEntries(Object.entries((await this._search(search)) ?? {}).map(([id, label]) => [String(id), String(label)]));
+        const items = await this.getItems();
+        const needle = search.toLowerCase();
+        return needle ? Object.fromEntries(Object.entries(items).filter(([, label]) => label.toLowerCase().includes(needle))) : items;
+    }
+    async getLabels(ids) {
+        const labels = this._labels ? await this._labels(ids) : Object.fromEntries(Object.entries(await this.getItems()).filter(([id]) => ids.includes(id)));
+        return Object.fromEntries(Object.entries(labels ?? {}).map(([id, label]) => [String(id), String(label)]));
+    }
+    getUrl(id, label) { return this._url ? this._url(id, label) : null; }
+    async toJs() {
+        return {
+            triggerCharacter: this._char,
+            extraAttributes: this._extraAttributes,
+            isSearchable: this.isSearchable(),
+            items: this.isSearchable() ? [] : Object.entries(await this.getItems()).map(([id, label]) => ({ id, label })),
+            noOptionsMessage: this._messages.noItems ?? t('filament-forms::components.rich_editor.mentions.no_options_message'),
+            noSearchResultsMessage: this._messages.noSearchResults ?? t('filament-forms::components.rich_editor.mentions.no_search_results_message'),
+            searchPrompt: this._messages.searchPrompt ?? t('filament-forms::components.rich_editor.mentions.search_prompt'),
+            searchingMessage: this._messages.searching ?? t('filament-forms::components.rich_editor.mentions.searching_message'),
+        };
+    }
+}
+// ------------------------------------------------------------------ custom blocks
+/**
+ * A block users insert in the content (a call to action, a video, a product…), configured in a modal. Extend this class:
+ * `id` and `label`, the modal's fields in `configureEditorAction()`, the preview in the editor, and the final HTML.
+ */
+export class RichContentCustomBlock {
+    /** Unique id, stored in the content. */
+    static getId() { throw new Error(`${this.name}.getId() must be defined.`); }
+    static getLabel() { return this.getId().replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[-_]/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()); }
+    /** Icon in the blocks panel. */
+    static getIcon() { return null; }
+    /** Group of the block in the panel (none by default). */
+    static getGroup() { return null; }
+    /** Modal of the block: add fields with `action.schema([...])`. Without fields, the block is inserted directly. */
+    static configureEditorAction(action) { return action.modalHidden(); }
+    /** Label of an inserted block in the editor. */
+    static getPreviewLabel(_config) { return this.getLabel(); }
+    /** HTML of the block in the editor (build it from escaped values). */
+    static toPreviewHtml(_config) { return null; }
+    static shouldApplyProseStylingToPreview(_config) { return false; }
+    /** HTML of the block in rendered content; `data` comes from `RichContentRenderer.customBlocks()`. Build it from escaped values. */
+    static toHtml(_config, _data) { return null; }
+}
+// ------------------------------------------------------------------ server-side extensions
+const json = (value) => { try {
+    return JSON.stringify(value ?? null);
+}
+catch {
+    return 'null';
+} };
+const parseConfig = (value) => { try {
+    const parsed = JSON.parse(value ?? 'null');
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+}
+catch {
+    return null;
+} };
+/** `<span class="color" data-color="red">`: the color must be a known palette name or a safe CSS color. */
+export const TextColorMark = Mark.create({
+    name: 'textColor',
+    parseHTML() { return [{ tag: 'span', getAttrs: (element) => (String(element.getAttribute?.('class') ?? '').split(/\s+/).includes('color') ? null : false) }]; },
+    addAttributes() {
+        return {
+            'data-color': {
+                default: null,
+                parseHTML: (element) => { const value = element.getAttribute('data-color'); return knownTextColors()[value] ? value : sanitizeCssColor(value); },
+                renderHTML: (attributes) => (attributes['data-color'] ? { 'data-color': attributes['data-color'] } : {}),
+            },
+        };
+    },
+    renderHTML({ HTMLAttributes }) {
+        const name = HTMLAttributes['data-color'];
+        const known = typeof name === 'string' ? knownTextColors()[name] : undefined;
+        const color = known ? null : sanitizeCssColor(name);
+        const style = known ? `--color: ${known.getColor()}; --dark-color: ${known.getDarkColor()}` : color ? `--color: ${color}; --dark-color: ${color}` : null;
+        return ['span', mergeAttributes({ class: 'color' }, HTMLAttributes, style ? { style } : {}), 0];
+    },
+});
+/** `<span data-type="mergeTag" data-id="name">`: replaced by its value when the content is rendered. */
+export const MergeTagNode = Node.create({
+    name: 'mergeTag',
+    group: 'inline', inline: true, atom: true, selectable: false,
+    addAttributes() { return { id: { default: null, parseHTML: (element) => element.getAttribute('data-id') || null, renderHTML: (attributes) => ({ 'data-id': attributes.id }) } }; },
+    parseHTML() { return [{ tag: 'span[data-type="mergeTag"]' }]; },
+    renderHTML({ HTMLAttributes }) { return ['span', mergeAttributes({ 'data-type': 'mergeTag' }, HTMLAttributes)]; },
+    renderText({ node }) { return `{{ ${node.attrs.id} }}`; },
+});
+/** `<span data-type="mention" data-id="7" data-label="Ada" data-char="@">@Ada</span>`. */
+export const MentionNode = Node.create({
+    name: 'mention',
+    group: 'inline', inline: true, atom: true, selectable: false,
+    addAttributes() {
+        return {
+            id: { default: null, parseHTML: (element) => element.getAttribute('data-id') || null, renderHTML: (attributes) => ({ 'data-id': attributes.id }) },
+            label: { default: null, parseHTML: (element) => element.getAttribute('data-label') || null, renderHTML: (attributes) => (attributes.label ? { 'data-label': attributes.label } : {}) },
+            char: { default: '@', parseHTML: (element) => String(element.getAttribute('data-char') || '@').slice(0, 3), renderHTML: (attributes) => ({ 'data-char': attributes.char ?? '@' }) },
+            href: { default: null, parseHTML: () => null, renderHTML: (attributes) => (attributes.href ? { href: attributes.href } : {}) },
+        };
+    },
+    parseHTML() { return [{ tag: 'span[data-type="mention"]' }, { tag: 'a[data-type="mention"]' }]; },
+    renderHTML({ node, HTMLAttributes }) { return [node.attrs.href ? 'a' : 'span', mergeAttributes({ 'data-type': 'mention' }, HTMLAttributes), `${node.attrs.char ?? '@'}${node.attrs.label ?? ''}`]; },
+    renderText({ node }) { return `${node.attrs.char ?? '@'}${node.attrs.label ?? ''}`; },
+});
+/** `<div data-type="customBlock" data-id="hero" data-config="{…}">`: rendered by its block class. */
+export const CustomBlockNode = Node.create({
+    name: 'customBlock',
+    group: 'block', atom: true,
+    addAttributes() {
+        return {
+            id: { default: null, parseHTML: (element) => element.getAttribute('data-id') || null, renderHTML: (attributes) => ({ 'data-id': attributes.id }) },
+            config: { default: null, parseHTML: (element) => parseConfig(element.getAttribute('data-config')), renderHTML: (attributes) => ({ 'data-config': json(attributes.config) }) },
+        };
+    },
+    parseHTML() { return [{ tag: 'div[data-type="customBlock"]' }]; },
+    renderHTML({ HTMLAttributes }) { return ['div', mergeAttributes({ 'data-type': 'customBlock' }, HTMLAttributes)]; },
+});
+const lengthOf = (value) => { const text = String(value ?? '').trim(); return /^\d{1,5}(\.\d{1,3})?(px|%|em|rem)?$/.test(text) ? text : null; };
+const styleLength = (value) => (/^\d+(\.\d+)?$/.test(value) ? `${value}px` : value);
+/** Images with an optional id (attachments) and size (resizable images). */
+export const SizedImage = Image.extend({
+    addAttributes() {
+        return {
+            ...this.parent?.(),
+            id: { default: null, parseHTML: (element) => element.getAttribute('data-id'), renderHTML: (attributes) => (attributes.id ? { 'data-id': attributes.id } : {}) },
+            width: {
+                default: null,
+                parseHTML: (element) => lengthOf(element.getAttribute('width') ?? /(?:^|;)\s*width:\s*([^;]+)/.exec(element.getAttribute('style') ?? '')?.[1]),
+                renderHTML: (attributes) => (attributes.width ? { width: attributes.width, style: `width: ${styleLength(attributes.width)}` } : {}),
+            },
+            height: {
+                default: null,
+                parseHTML: (element) => lengthOf(element.getAttribute('height') ?? /(?:^|;)\s*height:\s*([^;]+)/.exec(element.getAttribute('style') ?? '')?.[1]),
+                renderHTML: (attributes) => (attributes.height ? { height: attributes.height, style: `height: ${styleLength(attributes.height)}` } : {}),
+            },
+        };
+    },
+});
+/** Extensions added to the editor's schema by your application (`registerRichContentExtensions()`). */
+export const customRichContentExtensions = [];
+/**
+ * Adds TipTap extensions to the server schema of every rich editor and renderer: content using their nodes and marks is then
+ * kept when saved. Load the matching browser extensions with `RichEditor.extensions()`.
+ */
+export function registerRichContentExtensions(...extensions) { customRichContentExtensions.push(...extensions); }
+/**
+ * Renders stored rich content (HTML or JSON) for display: merge tags replaced by their values, mentions with their current
+ * labels and links, custom blocks rendered by their classes. The output is sanitized by the editor's schema.
+ */
+export class RichContentRenderer {
+    content;
+    _mergeTags = {};
+    _blocks = {};
+    _mentions = [];
+    constructor(content) { this.content = content; }
+    static make(content) { return new this(content); }
+    /** Values of the merge tags: text (escaped), an `HtmlString` (inserted as is), or a function returning one. */
+    mergeTags(values) { this._mergeTags = values; return this; }
+    /** Block classes, optionally with data passed to their `toHtml()`: `[HeroBlock]` or `{ hero: { block: HeroBlock, data } }`. */
+    customBlocks(blocks) {
+        this._blocks = Array.isArray(blocks)
+            ? Object.fromEntries(blocks.map((block) => [block.getId(), { block, data: {} }]))
+            : Object.fromEntries(Object.entries(blocks).map(([id, entry]) => [id, { block: entry.block, data: entry.data ?? {} }]));
+        return this;
+    }
+    mentions(providers) { this._mentions = providers; return this; }
+    async toHtml() {
+        const { richHtmlToDocument, richDocumentToHtml, renderRichDocument } = await import("./index.js");
+        // Sanitized first: only what the schema accepts goes through.
+        const sanitized = richDocumentToHtml(typeof this.content === 'string' ? richHtmlToDocument(this.content) : this.content);
+        if (sanitized === null)
+            return '';
+        const document = richHtmlToDocument(sanitized);
+        const raw = new Map();
+        const placeholder = (html) => { const key = `navette-raw-${randomBytes(8).toString('hex')}`; raw.set(key, html); return { type: 'paragraph', content: [{ type: 'text', text: key }] }; };
+        const inlinePlaceholder = (html) => { const key = `navette-raw-${randomBytes(8).toString('hex')}`; raw.set(key, html); return { type: 'text', text: key }; };
+        // Current labels of the mentions, by trigger character.
+        const mentioned = new Map();
+        const collect = (node) => { if (node.type === 'mention' && node.attrs?.id != null) {
+            const char = node.attrs.char ?? '@';
+            if (!mentioned.has(char))
+                mentioned.set(char, new Set());
+            mentioned.get(char).add(String(node.attrs.id));
+        } node.content?.forEach(collect); };
+        collect(document);
+        const labels = new Map();
+        for (const [char, ids] of mentioned) {
+            const provider = this._mentions.find((candidate) => candidate.getTriggerCharacter() === char);
+            if (provider)
+                labels.set(char, await provider.getLabels([...ids]));
+        }
+        const transform = async (node) => {
+            if (node.type === 'mergeTag') {
+                const id = String(node.attrs?.id ?? '');
+                if (!Object.hasOwn(this._mergeTags, id))
+                    return { type: 'text', text: `{{ ${id} }}` };
+                let value = this._mergeTags[id];
+                if (typeof value === 'function')
+                    value = await value();
+                if (value instanceof HtmlString)
+                    return inlinePlaceholder(value.html);
+                const text = value === null || value === undefined ? '' : String(value);
+                return text === '' ? null : { type: 'text', text, ...(node.marks ? { marks: node.marks } : {}) };
+            }
+            if (node.type === 'mention') {
+                const char = node.attrs?.char ?? '@', id = String(node.attrs?.id ?? '');
+                const label = labels.get(char)?.[id] ?? node.attrs?.label ?? '';
+                const url = this._mentions.find((candidate) => candidate.getTriggerCharacter() === char)?.getUrl(id, label) ?? null;
+                return { ...node, attrs: { ...node.attrs, label, href: url && /^(https?:\/\/|\/(?!\/)|mailto:)/i.test(url) ? url : null } };
+            }
+            if (node.type === 'customBlock') {
+                const entry = this._blocks[String(node.attrs?.id ?? '')];
+                if (!entry)
+                    return null;
+                const config = node.attrs?.config && typeof node.attrs.config === 'object' ? node.attrs.config : {};
+                const html = entry.block.toHtml(config, entry.data);
+                return html ? placeholder(html) : null;
+            }
+            if (!node.content)
+                return node;
+            const children = [];
+            for (const child of node.content) {
+                const result = await transform(child);
+                if (result)
+                    children.push(result);
+            }
+            return { ...node, content: children };
+        };
+        const html = renderRichDocument(await transform(document));
+        let output = html;
+        for (const [key, value] of raw)
+            output = output.replace(`<p>${key}</p>`, () => value).replace(key, () => value);
+        return output;
+    }
+}
+/** "Lead" paragraph group: `<div class="lead">`. */
+export const LeadNode = Node.create({
+    name: 'lead', group: 'block', content: 'block+',
+    parseHTML() { return [{ tag: 'div', getAttrs: (element) => (String(element.getAttribute?.('class') ?? '').split(/\s+/).includes('lead') ? null : false) }]; },
+    renderHTML({ HTMLAttributes }) { return ['div', mergeAttributes({ class: 'lead' }, HTMLAttributes), 0]; },
+});
+/** Small text: `<small>`. */
+export const SmallMark = Mark.create({
+    name: 'small',
+    parseHTML() { return [{ tag: 'small' }]; },
+    renderHTML({ HTMLAttributes }) { return ['small', HTMLAttributes, 0]; },
+});
+const count = (value, max) => Math.min(max, Math.max(1, Math.floor(Number(value)) || 1));
+/** Columns: `<div class="grid-layout" data-cols="2">` with `<div class="grid-layout-col">` children. */
+export const GridNode = Node.create({
+    name: 'grid', group: 'block', content: 'gridColumn+', isolating: true,
+    addAttributes() {
+        return {
+            'data-cols': { default: 2, parseHTML: (element) => count(element.getAttribute('data-cols'), 12) },
+            'data-from-breakpoint': { default: 'md', parseHTML: (element) => (/^(sm|md|lg|xl|2xl)$/.test(element.getAttribute('data-from-breakpoint') ?? '') ? element.getAttribute('data-from-breakpoint') : 'md') },
+        };
+    },
+    parseHTML() { return [{ tag: 'div', getAttrs: (element) => (String(element.getAttribute?.('class') ?? '').split(/\s+/).includes('grid-layout') ? null : false) }]; },
+    renderHTML({ HTMLAttributes }) { return ['div', mergeAttributes({ class: 'grid-layout', style: `--cols: repeat(${count(HTMLAttributes['data-cols'], 12)}, minmax(0, 1fr))` }, HTMLAttributes), 0]; },
+});
+export const GridColumnNode = Node.create({
+    name: 'gridColumn', content: 'block+', isolating: true,
+    addAttributes() { return { 'data-col-span': { default: 1, parseHTML: (element) => count(element.getAttribute('data-col-span'), 12) } }; },
+    parseHTML() { return [{ tag: 'div', getAttrs: (element) => (String(element.getAttribute?.('class') ?? '').split(/\s+/).includes('grid-layout-col') ? null : false) }]; },
+    renderHTML({ HTMLAttributes }) { const span = count(HTMLAttributes['data-col-span'], 12); return ['div', mergeAttributes({ class: 'grid-layout-col', style: `--col-span: span ${span} / span ${span}` }, HTMLAttributes), 0]; },
+});
+/** Server schema additions of the rich editor, besides the starter kit. */
+export const RICH_CONTENT_EXTENSIONS = [TextColorMark, SmallMark, MergeTagNode, MentionNode, CustomBlockNode, LeadNode, GridNode, GridColumnNode];

package/lib/rich-editor-tool.d.ts

@@ -0,0 +1,60 @@
+/** Plain description of a tool (the built-in tools are generated from Filament's definitions). */
+export type RichEditorToolDefinition = {
+    name: string;
+    /** Translation key of the label. */
+    label?: string;
+    jsHandler?: string;
+    /** Arguments of the field action mounted on click, as a JavaScript object expression. */
+    action?: string;
+    toggle?: boolean;
+    icon?: string;
+    activeKey?: string;
+    activeOptions?: Record<string, unknown>;
+    activeJsExpression?: string;
+    activeStyling?: boolean;
+    disabledWhenNotActive?: boolean;
+    extraAttributes?: Record<string, string>;
+};
+/**
+ * A toolbar button. `jsHandler()` runs code in the browser, where `$getEditor()` is the TipTap editor;
+ * `action()` mounts an action of the field (add it with `RichEditor.registerActions()`), with the editor selection.
+ */
+export declare class RichEditorTool {
+    protected _name: string;
+    protected _label: string | null;
+    protected _labelKey: string | null;
+    protected _icon: string | null;
+    protected _jsHandler: string | null;
+    protected _toggle: boolean;
+    protected _activeKey: string | null;
+    protected _activeOptions: Record<string, unknown>;
+    protected _activeJsExpression: string | null;
+    protected _activeStyling: boolean;
+    protected _disabledWhenNotActive: boolean;
+    protected _hiddenLabel: boolean;
+    protected _extraAttributes: Record<string, string>;
+    constructor(name: string);
+    static make(name: string): RichEditorTool;
+    static fromDefinition(definition: RichEditorToolDefinition): RichEditorTool;
+    getName(): string;
+    label(label: string | null): this;
+    getLabel(): string;
+    /** Shows the label next to the icon (by default, it is a tooltip). */
+    hiddenLabel(condition?: boolean): this;
+    icon(name: string | null): this;
+    /** JavaScript run on click: `$getEditor()?.chain().focus().toggleBold().run()`. */
+    jsHandler(handler: string | null): this;
+    /** Mounts the field action `name` (the tool's name by default) with the editor selection and these arguments (a JavaScript object expression). */
+    action(name?: string | null, argumentsJs?: string | null): this;
+    /** The button is a toggle (`aria-pressed`). */
+    toggle(condition?: boolean): this;
+    /** Node or mark whose presence marks the button as active (its name by default), with its attributes. */
+    activeKey(key: string | null): this;
+    activeOptions(options: Record<string, unknown>): this;
+    /** JavaScript expression telling whether the button is active. */
+    activeJsExpression(expression: string | null): this;
+    activeStyling(condition?: boolean): this;
+    disabledWhenNotActive(condition?: boolean): this;
+    extraAttributes(attributes: Record<string, string>): this;
+    toHtml(): string;
+}

package/lib/rich-editor-tool.js

@@ -0,0 +1,89 @@
+// Rich editor toolbar tools: a button running JavaScript in the editor, or mounting an action of the field.
+import { Attributes, e, icon, js } from '@navette-js/support';
+import { t } from '@navette-js/support/i18n';
+/**
+ * A toolbar button. `jsHandler()` runs code in the browser, where `$getEditor()` is the TipTap editor;
+ * `action()` mounts an action of the field (add it with `RichEditor.registerActions()`), with the editor selection.
+ */
+export class RichEditorTool {
+    _name;
+    _label = null;
+    _labelKey = null;
+    _icon = null;
+    _jsHandler = null;
+    _toggle = false;
+    _activeKey = null;
+    _activeOptions = {};
+    _activeJsExpression = null;
+    _activeStyling = true;
+    _disabledWhenNotActive = false;
+    _hiddenLabel = true;
+    _extraAttributes = {};
+    constructor(name) { this._name = name; }
+    static make(name) { return new this(name); }
+    static fromDefinition(definition) {
+        const tool = new this(definition.name);
+        tool._labelKey = definition.label ?? null;
+        tool._icon = definition.icon ?? null;
+        if (definition.jsHandler)
+            tool.jsHandler(definition.jsHandler);
+        if (definition.action !== undefined)
+            tool.action(null, definition.action);
+        tool._toggle = definition.toggle === true;
+        tool._activeKey = definition.activeKey ?? null;
+        tool._activeOptions = definition.activeOptions ?? {};
+        tool._activeJsExpression = definition.activeJsExpression ?? null;
+        tool._activeStyling = definition.activeStyling !== false;
+        tool._disabledWhenNotActive = definition.disabledWhenNotActive === true;
+        tool._extraAttributes = { ...(definition.extraAttributes ?? {}) };
+        return tool;
+    }
+    getName() { return this._name; }
+    label(label) { this._label = label; this._labelKey = null; return this; }
+    getLabel() {
+        if (this._label !== null)
+            return this._label;
+        if (this._labelKey)
+            return t(`filament-forms::${this._labelKey.replace(/^filament-forms::/, '')}`);
+        return this._name.replace(/([a-z])([A-Z])/g, '$1 $2').replace(/[-_]/g, ' ').replace(/^./, (c) => c.toUpperCase());
+    }
+    /** Shows the label next to the icon (by default, it is a tooltip). */
+    hiddenLabel(condition = true) { this._hiddenLabel = condition; return this; }
+    icon(name) { this._icon = name; return this; }
+    /** JavaScript run on click: `$getEditor()?.chain().focus().toggleBold().run()`. */
+    jsHandler(handler) { this._jsHandler = handler; return this; }
+    /** Mounts the field action `name` (the tool's name by default) with the editor selection and these arguments (a JavaScript object expression). */
+    action(name = null, argumentsJs = null) {
+        this._jsHandler = `mountToolAction(${js(name ?? this._name)}, { editorSelection, ...${argumentsJs ?? '{}'} }, $el)`;
+        return this;
+    }
+    /** The button is a toggle (`aria-pressed`). */
+    toggle(condition = true) { this._toggle = condition; return this; }
+    /** Node or mark whose presence marks the button as active (its name by default), with its attributes. */
+    activeKey(key) { this._activeKey = key; return this; }
+    activeOptions(options) { this._activeOptions = options; return this; }
+    /** JavaScript expression telling whether the button is active. */
+    activeJsExpression(expression) { this._activeJsExpression = expression; return this; }
+    activeStyling(condition = true) { this._activeStyling = condition; return this; }
+    disabledWhenNotActive(condition = true) { this._disabledWhenNotActive = condition; return this; }
+    extraAttributes(attributes) { Object.assign(this._extraAttributes, attributes); return this; }
+    toHtml() {
+        const active = this._activeJsExpression
+            ? `editorUpdatedAt && (${this._activeJsExpression})`
+            : `editorUpdatedAt && $getEditor()?.isActive(${js(this._activeKey ?? this._name)}, ${Object.keys(this._activeOptions).length ? js(this._activeOptions) : '[]'})`;
+        const label = this.getLabel();
+        const attributes = new Attributes(this._extraAttributes).merge({
+            'data-rich-editor-tool': this._name,
+            tabindex: '-1',
+            type: 'button',
+            'aria-label': label,
+            'aria-pressed': this._toggle ? 'false' : null,
+            'x-bind:class': `{ 'fi-active': ${this._activeStyling ? active : 'false'} }`,
+            'x-bind:aria-pressed': this._toggle ? `(${active}) ? 'true' : 'false'` : null,
+            'x-bind:disabled': this._disabledWhenNotActive ? `!(${active})` : null,
+            'x-on:click': this._jsHandler,
+            'x-tooltip': label && this._hiddenLabel ? `{ content: ${js(label)}, theme: $store.theme }` : null,
+        }).class(['fi-fo-rich-editor-tool', { 'fi-fo-rich-editor-tool-with-label': !this._hiddenLabel }]);
+        return `<button ${attributes.toHtml()}>${this._icon ? icon(this._icon) : ''}${this._hiddenLabel ? '' : `<span class="fi-fo-rich-editor-tool-label">${e(label)}</span>`}</button>`;
+    }
+}

package/lib/rich-editor-tools.d.ts

@@ -0,0 +1,2 @@
+import type { RichEditorToolDefinition } from './rich-editor-tool.ts';
+export declare const RICH_EDITOR_TOOL_DEFINITIONS: RichEditorToolDefinition[];