domma-cms 0.55.1 → 0.69.3

package/plugins/_lib/admin/mail/section-kit.js

@@ -0,0 +1,277 @@
+/**
+ * Building a settings section out of Domma rather than out of `createElement`.
+ *
+ * The mail settings sections were originally hand-built DOM with inline
+ * `style.cssText` on every node - which works, and is exactly what the house
+ * rules say not to do. Domma already owns forms (`F`), reactivity (`M`),
+ * cards, badges and list groups (`E`), and a full set of layout classes; a
+ * plugin that re-implements them has five copies of the same bugs and no
+ * theme support, because inline styles cannot read `--dm-*` tokens that a
+ * theme override redefines.
+ *
+ * So a section here declares a SCHEMA and this renders it. The things a
+ * section still builds by hand are the things Domma has no component for: the
+ * rich editor host, and the rule builder's dynamic clause rows.
+ *
+ * ## The one real constraint
+ *
+ * `F.create(...).renderTo(el)` assigns `innerHTML`. Anything live inside that
+ * element - a rich editor, an autocomplete - is destroyed on every render. So
+ * a form and an editor are always SIBLINGS here, never nested, and `formIn`
+ * returns the host it rendered into so a caller can tell them apart.
+ *
+ * @module _lib/admin/mail/section-kit
+ */
+
+/**
+ * A `<div>` with Domma classes on it, appended to a parent.
+ *
+ * The workhorse. Every layout decision in a section goes through this, so
+ * there is one place that knows the class vocabulary and no section reaches
+ * for `style.cssText`.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} [className]
+ * @param   {string} [tag]
+ * @returns {HTMLElement}
+ */
+export function box(parent, className = '', tag = 'div') {
+    const el = document.createElement(tag);
+    if (className) el.className = className;
+    parent.appendChild(el);
+    return el;
+}
+
+/**
+ * A small heading between groups of fields.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} text
+ * @returns {HTMLElement}
+ */
+export function heading(parent, text) {
+    const el = box(parent, 'mail-section-heading', 'h4');
+    el.textContent = text;
+    return el;
+}
+
+/**
+ * A line of explanation under a heading or a control.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} text
+ * @returns {HTMLElement}
+ */
+export function note(parent, text) {
+    const el = box(parent, 'text-sm text-muted mb-2', 'p');
+    el.textContent = text;
+    return el;
+}
+
+/**
+ * Render a Domma form from a schema, and hand back its reactive state.
+ *
+ * `state` is the model's tracked proxy: reading a field inside `M.effect`
+ * subscribes to it, and the form's own change handling writes through the
+ * same model - so a summary line that reads `state.subject` re-renders itself
+ * when somebody types, with nothing to wire up and nothing to remember to
+ * call.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {object} schema - Forma schema, keyed BY FIELD NAME (not an array)
+ * @param   {object} data
+ * @param   {object} [options] - passed to F.create
+ * @returns {{form: object, state: object, host: HTMLElement}}
+ */
+export function formIn(parent, schema, data = {}, options = {}) {
+    const host = box(parent, 'mail-section-form');
+    const form = F.create(schema, data, {
+        // Labels above, one column: a settings slideover is narrow, and a two
+        // column grid puts a hint under a field it does not belong to.
+        layout: 'stacked',
+        labelPosition: 'top',
+        validationMode: 'change',
+        // Forma adds its own "Submit" unless told not to. Every section here
+        // has a Save in its action bar - and several have more than one form
+        // on screen at once, so the default would put a Submit button after
+        // each group of fields.
+        showSubmitButton: false,
+        ...options
+    });
+    form.renderTo(host);
+    return {form, state: form.model.tracked(), host};
+}
+
+/**
+ * One item in a list of them, as a Domma card.
+ *
+ * Returns the body to fill and the header actions area, so a caller never
+ * touches the card's own structure.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {{title: string, badge?: string, badgeVariant?: string}} options
+ * @returns {{card: HTMLElement, head: HTMLElement, title: HTMLElement, body: HTMLElement}}
+ */
+export function itemCard(parent, {title, badge = '', badgeVariant = 'primary'}) {
+    const card = box(parent, 'card mail-item-card');
+
+    const head = box(card, 'card-header flex items-center gap-2');
+    const titleEl = box(head, 'flex-1 font-semibold text-sm mail-ellipsis', 'span');
+    titleEl.textContent = title;
+
+    if (badge) {
+        const badgeEl = box(head, `badge badge-${badgeVariant}`, 'span');
+        badgeEl.textContent = badge;
+    }
+
+    const body = box(card, 'card-body flex flex-col gap-2');
+    return {card, head, title: titleEl, body};
+}
+
+/**
+ * A button, with Domma's classes and nothing inline.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} label
+ * @param   {Function} onClick
+ * @param   {{variant?: string, title?: string, icon?: string}} [options]
+ * @returns {HTMLButtonElement}
+ */
+export function button(parent, label, onClick, {variant = 'ghost', title = '', icon = ''} = {}) {
+    const el = box(parent, `btn btn-sm btn-${variant}`, 'button');
+    el.type = 'button';
+    if (title) el.title = title;
+
+    if (icon) {
+        // Glyph in a CHILD, then scan the parent. `Domma.icons.scan` REPLACES
+        // the element carrying `data-icon`, so putting it on the button itself
+        // swaps the button out from under this listener.
+        const glyph = box(el, '', 'span');
+        glyph.setAttribute('data-icon', icon);
+        glyph.setAttribute('data-icon-size', '13');
+    }
+    if (label) el.appendChild(document.createTextNode(icon ? ` ${label}` : label));
+
+    el.addEventListener('click', onClick);
+    if (icon) Domma.icons.scan(el);
+    return el;
+}
+
+/**
+ * The row of buttons at the foot of a section, with a status line.
+ *
+ * The status line is the only feedback most of these screens give, so it is
+ * part of the furniture rather than something each section invents.
+ *
+ * @param   {HTMLElement} parent
+ * @returns {{row: HTMLElement, say: Function, busy: Function}}
+ */
+export function actionBar(parent) {
+    const row = box(parent, 'flex items-center gap-2 mt-4');
+    const status = box(row, 'flex-1 text-sm mail-status');
+
+    return {
+        row,
+
+        /**
+         * @param   {string} text
+         * @param   {'ok'|'bad'|'quiet'} [tone]
+         * @returns {void}
+         */
+        say(text, tone = 'quiet') {
+            status.textContent = text ?? '';
+            status.className = 'flex-1 text-sm mail-status '
+                + ({ok: 'text-success', bad: 'text-danger'}[tone] ?? 'text-muted');
+        },
+
+        /**
+         * Disable every button in the bar while something is in flight.
+         *
+         * @param   {boolean} on
+         * @returns {void}
+         */
+        busy(on) {
+            for (const el of row.querySelectorAll('button')) el.disabled = on;
+        }
+    };
+}
+
+/**
+ * A rich editor, with a plain textarea where the component is absent.
+ *
+ * Kept out of `formIn` deliberately: `renderTo` assigns `innerHTML`, so an
+ * editor rendered inside a Forma-owned element is destroyed the next time
+ * that form renders.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} html
+ * @param   {{height?: string, text?: string}} [options]
+ * @returns {{get: Function, getText: Function, set: Function, destroy: Function, rich: boolean}}
+ */
+export function richEditor(parent, html, {height = '10rem', text = ''} = {}) {
+    const host = box(parent, 'mail-editor-host');
+
+    if (typeof E?.editor === 'function') {
+        try {
+            const editor = E.editor(host, {mode: 'rich', height});
+            editor.setValue(html ?? '');
+            return {
+                rich: true,
+                get: () => editor.getValue(),
+                getText: () => editor.getText(),
+                set: value => editor.setValue(value ?? ''),
+                destroy: () => editor.destroy?.()
+            };
+        } catch {
+            host.textContent = '';
+        }
+    }
+
+    // The fallback shows the TEXT it came from rather than markup to
+    // hand-edit: without the editor, raw HTML in a textarea is not something
+    // anybody can reasonably maintain.
+    const area = box(host, 'form-textarea mail-editor-fallback', 'textarea');
+    area.value = text ?? '';
+    return {
+        rich: false,
+        get: () => area.value,
+        getText: () => area.value,
+        set: value => { area.value = value ?? ''; },
+        destroy: () => {}
+    };
+}
+
+/**
+ * A `<select>` with Domma's class and a list of options.
+ *
+ * Used where a select is a CONTROL rather than a form field - a picker that
+ * acts immediately, which is not something a schema describes.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {Array<{value: string, label: string}>} options
+ * @param   {string} [value]
+ * @returns {HTMLSelectElement}
+ */
+export function select(parent, options, value) {
+    const el = box(parent, 'form-select form-select-sm', 'select');
+    for (const option of options) {
+        const node = box(el, '', 'option');
+        node.value = option.value;
+        node.textContent = option.label;
+    }
+    if (value !== undefined) el.value = value;
+    return el;
+}
+
+/**
+ * An empty-state line, in the same voice everywhere.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} text
+ * @returns {HTMLElement}
+ */
+export function empty(parent, text) {
+    const el = box(parent, 'text-sm text-muted mail-empty-line', 'p');
+    el.textContent = text;
+    return el;
+}

package/plugins/_lib/admin/mail/templates.js

@@ -0,0 +1,238 @@
+/**
+ * Canned responses.
+ *
+ * A template is a signature with a subject on it, and it is kept deliberately
+ * close to one: the same editor writes it, the same sanitiser cleans it, and
+ * the same derived-text rule applies, so a mailbox has one idea of "stored
+ * markup I wrote and will send" rather than two that drift.
+ *
+ * ## Why this sits under `admin/`
+ *
+ * The same reason `identity.js` does - the static mount serves
+ * `{plugin}/{admin|public}/**` and nothing else, and both the compose window
+ * and the store need this. See the note at the top of `identity.js`.
+ *
+ * ## Placeholders
+ *
+ * A template that cannot say the recipient's name is a template people stop
+ * using after the second time they retype it. The token set is small and
+ * fixed: anything bigger becomes a language, and a language in a text box is
+ * a support burden.
+ *
+ * An UNRECOGNISED token is left exactly as it was written. Silently emptying
+ * it would send `Dear ,` to a customer; leaving `{{to.frist}}` visible means
+ * the mistake is found while the message is still in the window.
+ *
+ * @module _lib/admin/mail/templates
+ */
+import {signatureToText, textToHtml} from './identity.js';
+
+/** How many templates one mailbox may hold. */
+export const MAX_TEMPLATES = 50;
+
+/**
+ * The tokens a template may use, and what each one means.
+ *
+ * Exported because the settings screen lists them: a placeholder feature
+ * whose placeholders are only documented in a comment is a placeholder
+ * feature nobody discovers.
+ */
+export const TEMPLATE_TOKENS = [
+    {token: '{{to.name}}', describes: "The first recipient's name, or their address if it has none"},
+    {token: '{{to.first}}', describes: "The first recipient's first name"},
+    {token: '{{to.email}}', describes: "The first recipient's address"},
+    {token: '{{my.name}}', describes: 'Your display name on this identity'},
+    {token: '{{my.email}}', describes: 'The address this message sends from'},
+    {token: '{{subject}}', describes: "The message's subject, as it currently stands"},
+    {token: '{{date}}', describes: "Today's date"},
+    {token: '{{time}}', describes: 'The time now'}
+];
+
+/**
+ * Strip anything that would end a header line.
+ *
+ * A template's subject is interpolated into the Subject header, so it is held
+ * to the same rule the display name is - a newline there is a second header.
+ *
+ * @param   {*} value
+ * @returns {string}
+ */
+function headerSafe(value) {
+    return String(value ?? '').replace(/[\r\n]+/g, ' ').trim();
+}
+
+/**
+ * A stable id for a template. See the note on `newId` in `identity.js`.
+ *
+ * @returns {string}
+ */
+function newId() {
+    return `tpl-${Math.random().toString(36).slice(2, 10)}${Date.now().toString(36).slice(-4)}`;
+}
+
+/**
+ * Put one stored template into shape.
+ *
+ * Whitelisted rather than merged, for the same reason identities are: this
+ * markup is embedded in outgoing mail and handed back to an editor that sets
+ * it as innerHTML, so an unexpected key must not survive the round trip.
+ *
+ * @param   {object} input
+ * @param   {number} index
+ * @returns {object}
+ */
+export function normaliseTemplate(input, index = 0) {
+    const source = input && typeof input === 'object' ? input : {};
+
+    const bodyHtml = String(source.bodyHtml ?? '').trim();
+    // Derived, never accepted from the caller - the same rule the signature
+    // text follows, and for the same reason: two copies of one piece of
+    // writing is two copies to keep in step, and nobody does.
+    const bodyText = bodyHtml
+        ? signatureToText(bodyHtml)
+        : String(source.bodyText ?? '').trim();
+
+    return {
+        id: typeof source.id === 'string' && source.id.trim() ? source.id.trim() : newId(),
+        name: headerSafe(source.name) || `Template ${index + 1}`,
+        // Optional. A template that only supplies a body is the common case -
+        // it is being dropped into a reply that already has its subject.
+        subject: headerSafe(source.subject),
+        bodyHtml,
+        bodyText
+    };
+}
+
+/**
+ * Every template a mailbox holds, in the order they were arranged.
+ *
+ * @param   {object|null|undefined} account
+ * @returns {object[]}
+ */
+export function normaliseTemplates(account) {
+    const source = account && typeof account === 'object' ? account : {};
+    const raw = Array.isArray(source.templates) ? source.templates : [];
+    const list = raw.slice(0, MAX_TEMPLATES).map(normaliseTemplate);
+
+    const seen = new Set();
+    for (const entry of list) {
+        while (seen.has(entry.id)) entry.id = newId();
+        seen.add(entry.id);
+    }
+    return list;
+}
+
+/**
+ * The values a template's tokens are filled from.
+ *
+ * @param   {{to?: object[], subject?: string, identity?: object|null,
+ *            fromAddress?: string, now?: Date}} context
+ * @returns {Object.<string, string>}
+ */
+export function templateValues({to = [], subject = '', identity = null, fromAddress = '', now = new Date()} = {}) {
+    const first = (to ?? [])[0] ?? {};
+    const name = String(first.name ?? '').trim();
+    const email = String(first.address ?? '').trim();
+
+    return {
+        'to.name': name || email,
+        // The part before the first space, which is what a greeting wants.
+        // Falls back to the whole name rather than to nothing, because a
+        // one-word name is a name.
+        'to.first': (name.split(/\s+/)[0] || '').trim() || name || email,
+        'to.email': email,
+        'my.name': String(identity?.displayName ?? '').trim(),
+        'my.email': String(identity?.address || fromAddress || '').trim(),
+        subject: String(subject ?? '').trim(),
+        // The reader's own locale, not the server's - a template written in
+        // London and read in London should not say 9/20/2026.
+        date: now.toLocaleDateString(),
+        time: now.toLocaleTimeString([], {hour: '2-digit', minute: '2-digit'})
+    };
+}
+
+/**
+ * Escape text for interpolation into HTML.
+ *
+ * Every value substituted into the HTML body goes through this. A recipient
+ * whose display name is `<script>` is not a likely attack, but it is a
+ * likely way to break the markup of every message sent to them.
+ *
+ * @param   {*} value
+ * @returns {string}
+ */
+function escapeHtml(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}
+
+/**
+ * Substitute the tokens in one string.
+ *
+ * @param   {string} text
+ * @param   {Object.<string, string>} values
+ * @param   {(value: string) => string} escape
+ * @returns {string}
+ */
+function fill(text, values, escape) {
+    return String(text ?? '').replace(/\{\{\s*([a-z][a-z.]*)\s*\}\}/gi, (whole, token) => {
+        const key = token.toLowerCase();
+        // Left alone when it is not one of ours. See the module note: a typo
+        // that shows is a typo that gets fixed before it is sent.
+        return Object.prototype.hasOwnProperty.call(values, key) ? escape(values[key]) : whole;
+    });
+}
+
+/**
+ * A template, with its placeholders filled in.
+ *
+ * @param   {object} template
+ * @param   {object} [context] - passed to `templateValues`
+ * @returns {{subject: string, html: string, text: string}}
+ */
+export function expandTemplate(template, context = {}) {
+    const entry = normaliseTemplate(template);
+    const values = templateValues(context);
+
+    return {
+        subject: fill(entry.subject, values, v => v),
+        html: fill(entry.bodyHtml, values, escapeHtml),
+        text: fill(entry.bodyText, values, v => v)
+    };
+}
+
+/**
+ * Put an expanded template into a draft.
+ *
+ * Inserted ABOVE whatever is already there rather than replacing it. A
+ * template is nearly always dropped into a reply, and a reply already holds
+ * the quoted message and - depending on the identity - a signature. Replacing
+ * would throw both away; appending would put the greeting under the quote.
+ *
+ * An empty body is the one case where it simply becomes the body, because
+ * there is nothing to preserve and the leading blank line would be the only
+ * thing the insertion achieved.
+ *
+ * The subject is only taken when the draft has none. A template that
+ * overwrote a reply's `Re:` line would be renaming someone else's thread.
+ *
+ * @param   {{subject?: string, html?: string, body?: string}} draft
+ * @param   {{subject: string, html: string, text: string}} expanded
+ * @returns {object}
+ */
+export function applyTemplate(draft, expanded) {
+    const existingHtml = String(draft?.html ?? '');
+    const existingText = String(draft?.body ?? '');
+    const html = expanded.html || textToHtml(expanded.text);
+    const empty = !existingHtml.trim() && !existingText.trim();
+
+    return {
+        ...draft,
+        subject: String(draft?.subject ?? '').trim() || expanded.subject,
+        html: empty ? html : `${html}${existingHtml}`,
+        body: empty ? expanded.text : `${expanded.text}\n\n${existingText}`
+    };
+}