domma-cms 0.55.1 → 0.66.0

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

@@ -0,0 +1,200 @@
+/**
+ * Grouping messages into conversations.
+ *
+ * A thread is reconstructed from `Message-ID`, `In-Reply-To` and
+ * `References` - never from the subject. Subject grouping is what puts every
+ * "Re: hello" anyone ever sent into one conversation, and what splits a
+ * thread in half the moment somebody edits the subject line.
+ *
+ * ## Two halves, on purpose
+ *
+ * `threadRoot()` is what the mirror stores on each row at write time, so a
+ * folder can be listed and sorted by conversation in the database rather
+ * than in memory. `groupThreads()` is the repair pass over the page actually
+ * being shown: it unions rows whose chains only connect through each other,
+ * which catches the clients that put only the immediate parent in
+ * `References` and so hand every reply a different root.
+ *
+ * The consequence worth knowing is that the repair only sees the page in
+ * hand. A conversation split across a page boundary shows as two groups, and
+ * that is the honest trade against holding every message in memory to list
+ * fifty.
+ *
+ * @module _lib/admin/mail/threads
+ */
+
+/**
+ * Message ids as a clean list.
+ *
+ * Servers disagree about whether `References` is a string or an array, and
+ * whether the angle brackets are part of it. Normalised here so nothing
+ * downstream has to care.
+ *
+ * @param   {string|string[]|null|undefined} value
+ * @returns {string[]}
+ */
+export function messageIds(value) {
+    const raw = Array.isArray(value)
+        ? value
+        : String(value ?? '').split(/\s+/);
+
+    return raw
+        .map(id => String(id ?? '').trim())
+        .filter(Boolean)
+        // Kept WITH their brackets, consistently. Stripping them would be
+        // just as good a rule, but only if everything agreed - and
+        // `messageId` comes off the envelope bracketed while a hand-built
+        // reference may not.
+        .map(id => (id.startsWith('<') ? id : `<${id}>`));
+}
+
+/**
+ * The id that identifies the conversation a message belongs to.
+ *
+ * The root of the chain: the first thing it references, failing that whatever
+ * it is a reply to, failing that itself - a message that starts a thread is
+ * its own root.
+ *
+ * @param   {object} message
+ * @returns {string|null}
+ */
+export function threadRoot(message) {
+    const references = messageIds(message?.references);
+    if (references.length) return references[0];
+
+    const parent = messageIds(message?.inReplyTo);
+    if (parent.length) return parent[0];
+
+    const own = messageIds(message?.messageId);
+    return own[0] ?? null;
+}
+
+/**
+ * Every id a message claims to be connected to, including its own.
+ *
+ * @param   {object} message
+ * @returns {string[]}
+ */
+function chainOf(message) {
+    return [
+        ...messageIds(message?.messageId),
+        ...messageIds(message?.inReplyTo),
+        ...messageIds(message?.references)
+    ];
+}
+
+/**
+ * Group a page of messages into conversations.
+ *
+ * Union-find over the ids each message claims, so two rows land in the same
+ * conversation if anything connects them - directly or through a third row.
+ * Rows with no usable ids at all are their own conversation rather than being
+ * swept together, because "has no Message-ID" is not a thing two messages
+ * have in common.
+ *
+ * Order is preserved: the conversations come back in the order their newest
+ * member appeared in the input, so a list sorted newest-first stays
+ * newest-first once it is grouped.
+ *
+ * @param   {object[]} messages
+ * @returns {{root: string, messages: object[], latest: object, count: number,
+ *            unseen: number, flagged: boolean, hasAttachment: boolean}[]}
+ */
+export function groupThreads(messages) {
+    const parent = new Map();
+
+    /**
+     * @param   {string} id
+     * @returns {string}
+     */
+    const find = (id) => {
+        let root = id;
+        while (parent.get(root) !== root) root = parent.get(root);
+        // Path compression, so a long thread does not walk its whole chain
+        // on every lookup.
+        let walk = id;
+        while (parent.get(walk) !== root) {
+            const next = parent.get(walk);
+            parent.set(walk, root);
+            walk = next;
+        }
+        return root;
+    };
+
+    /**
+     * @param   {string} a
+     * @param   {string} b
+     * @returns {void}
+     */
+    const union = (a, b) => {
+        if (!parent.has(a)) parent.set(a, a);
+        if (!parent.has(b)) parent.set(b, b);
+        const rootA = find(a);
+        const rootB = find(b);
+        if (rootA !== rootB) parent.set(rootB, rootA);
+    };
+
+    const keyed = (messages ?? []).map((message, index) => {
+        const chain = chainOf(message);
+        // A row with nothing to thread by gets a key nothing else can share.
+        const key = chain.length ? chain[0] : `\u0000row-${index}`;
+        if (!parent.has(key)) parent.set(key, key);
+        for (const id of chain) union(key, id);
+        return {message, key};
+    });
+
+    /** @type {Map<string, object[]>} */
+    const groups = new Map();
+    for (const {message, key} of keyed) {
+        const root = find(key);
+        if (!groups.has(root)) groups.set(root, []);
+        groups.get(root).push(message);
+    }
+
+    return [...groups.entries()].map(([root, list]) => {
+        // Newest first within the conversation, so `latest` is the one the
+        // collapsed row represents.
+        const ordered = [...list].sort((a, b) => dateOf(b) - dateOf(a));
+        return {
+            root,
+            messages: ordered,
+            latest: ordered[0],
+            count: ordered.length,
+            // A conversation is unread if anything in it is. Counting them
+            // rather than flagging it, because "3 unread of 11" is the useful
+            // thing to show on a collapsed row.
+            unseen: ordered.filter(m => m.seen === false).length,
+            flagged: ordered.some(m => m.flagged === true),
+            hasAttachment: ordered.some(m => m.hasAttachment === true)
+        };
+    });
+}
+
+/**
+ * A message's date as a number, for sorting.
+ *
+ * @param   {object} message
+ * @returns {number}
+ */
+function dateOf(message) {
+    const value = new Date(String(message?.date ?? '')).getTime();
+    // Undated messages sort to the bottom rather than to 1970, which would
+    // put them above everything on a descending sort.
+    return Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * The subject a conversation is filed under.
+ *
+ * The oldest member's, with the reply and forward prefixes taken off - the
+ * first message is the one that named the thread, and the newest is quite
+ * often "Re: Re: Fwd: Re:" of it.
+ *
+ * @param   {{messages: object[]}} thread
+ * @returns {string}
+ */
+export function threadSubject(thread) {
+    const oldest = (thread?.messages ?? []).at(-1);
+    const subject = String(oldest?.subject ?? '').trim();
+    return subject.replace(/^((re|fwd|fw|aw|sv|vs)\s*(\[\d+\])?\s*:\s*)+/i, '').trim() || subject;
+}

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

@@ -0,0 +1,269 @@
+/**
+ * The automatic reply, and everything that must stop it.
+ *
+ * ## This feature is its own refusals
+ *
+ * Writing "I am away until Monday" into a box is ten minutes' work. The rest
+ * of this module is the reason an auto-responder is not a ten minute feature:
+ * every one of the checks below exists because without it the thing does real
+ * damage to somebody else's mailbox, and almost none of that damage is
+ * visible from this end.
+ *
+ * The failure everybody knows is the mail loop - two responders answering
+ * each other until an administrator notices. The ones people forget are worse
+ * behaved: replying to a mailing list posts your holiday plans to five
+ * hundred subscribers, replying to a bounce writes to a null sender, and
+ * replying to a newsletter tells a list broker the address is live and read
+ * by a person.
+ *
+ * So the rules, each with the case it prevents:
+ *
+ *   1. **Never to an automated message.** `Auto-Submitted` other than `no`
+ *      (RFC 3834), `Precedence: bulk|list|junk`, or any `List-*` header.
+ *      This alone stops the classic loop, because our own replies carry
+ *      `Auto-Submitted: auto-replied` - see `autoReplyHeaders`.
+ *   2. **Never to a bounce.** An empty `Return-Path`, or a sender that is
+ *      MAILER-DAEMON, postmaster, or an obvious no-reply.
+ *   3. **Never to ourselves.** A mailbox that answers its own mail loops
+ *      without needing a second party at all.
+ *   4. **Only when actually addressed.** If our address is in neither To nor
+ *      Cc we were Bcc'd on a blast, and a blast is exactly what must not be
+ *      answered five hundred times.
+ *   5. **Once per sender per interval.** Somebody who writes four times in an
+ *      afternoon gets told once.
+ *
+ * Pure, and browser-side too, so the settings screen can say precisely why a
+ * message would not have been answered.
+ *
+ * @module _lib/admin/mail/vacation
+ */
+
+/** How often one sender may be told, by default. */
+export const DEFAULT_INTERVAL_DAYS = 4;
+
+/** The longest an away message may be. Longer is a document, not a notice. */
+const MAX_BODY = 5000;
+
+/**
+ * Strip anything that would end a header line.
+ *
+ * @param   {*} value
+ * @returns {string}
+ */
+function headerSafe(value) {
+    return String(value ?? '').replace(/[\r\n]+/g, ' ').trim();
+}
+
+/**
+ * An ISO timestamp, or null when it is not one.
+ *
+ * @param   {*} value
+ * @returns {string|null}
+ */
+function isoOrNull(value) {
+    if (!value) return null;
+    const when = new Date(String(value));
+    return Number.isNaN(when.getTime()) ? null : when.toISOString();
+}
+
+/**
+ * Put a stored away message into shape.
+ *
+ * @param   {object|null|undefined} account
+ * @returns {object}
+ */
+export function normaliseVacation(account) {
+    const source = account?.vacation && typeof account.vacation === 'object' ? account.vacation : {};
+    const days = Number(source.intervalDays);
+
+    return {
+        enabled: source.enabled === true,
+        subject: headerSafe(source.subject) || 'Out of office',
+        bodyHtml: String(source.bodyHtml ?? '').trim().slice(0, MAX_BODY),
+        bodyText: String(source.bodyText ?? '').trim().slice(0, MAX_BODY),
+        // Both optional. No start means "from now"; no end means "until I
+        // turn it off", which is the honest reading of leaving it blank.
+        from: isoOrNull(source.from),
+        to: isoOrNull(source.to),
+        intervalDays: Number.isFinite(days) && days >= 1 && days <= 30
+            ? Math.round(days)
+            : DEFAULT_INTERVAL_DAYS,
+        // Off by default. A responder that only answers people already in
+        // your address book is much safer, and much less useful - so it is a
+        // choice rather than a default either way.
+        knownSendersOnly: source.knownSendersOnly === true
+    };
+}
+
+/**
+ * Is the away message switched on and inside its window?
+ *
+ * @param   {object} vacation
+ * @param   {Date} [now]
+ * @returns {boolean}
+ */
+export function isActive(vacation, now = new Date()) {
+    const settings = normaliseVacation({vacation});
+    if (!settings.enabled) return false;
+    if (!settings.bodyHtml && !settings.bodyText) return false;
+
+    const at = now.getTime();
+    if (settings.from && at < new Date(settings.from).getTime()) return false;
+    if (settings.to && at > new Date(settings.to).getTime()) return false;
+    return true;
+}
+
+/** Local parts that are never a person waiting for a reply. */
+const NEVER_REPLY_TO = [
+    'mailer-daemon', 'postmaster', 'no-reply', 'noreply', 'donotreply',
+    'do-not-reply', 'bounce', 'bounces', 'notifications', 'notification'
+];
+
+/**
+ * Was this message sent by a machine rather than a person?
+ *
+ * Computed from the headers at fetch time and stored on the mirror row, so
+ * the responder does not need a second round trip to find out. Exported and
+ * tested on its own because it is the single check that stops a mail loop.
+ *
+ * @param   {Map|object} headers - parsed or raw-parsed header map
+ * @returns {boolean}
+ */
+export function looksAutomated(headers) {
+    const read = (name) => {
+        const value = typeof headers?.get === 'function' ? headers.get(name) : headers?.[name];
+        if (value && typeof value === 'object' && !Array.isArray(value)) return String(value.value ?? '');
+        return String(Array.isArray(value) ? value[0] ?? '' : value ?? '');
+    };
+
+    // RFC 3834. Anything other than an explicit "no" means a machine sent it,
+    // INCLUDING our own replies - which is what closes the loop.
+    const submitted = read('auto-submitted').trim().toLowerCase();
+    if (submitted && submitted !== 'no') return true;
+
+    if (/^(bulk|list|junk|auto_reply)$/i.test(read('precedence').trim())) return true;
+
+    // Any List-* header at all. A mailing list is never expecting a personal
+    // reply, and answering one posts to every subscriber.
+    for (const name of ['list-id', 'list-unsubscribe', 'list-post', 'list-help']) {
+        if (read(name).trim()) return true;
+    }
+
+    // An empty Return-Path is the null sender, which is how a bounce is
+    // addressed. There is nothing there to reply to.
+    const returnPath = read('return-path').trim();
+    if (returnPath === '<>' || returnPath === '') {
+        // Absent is not the same as empty - plenty of fetches simply do not
+        // include it - so only the explicit null sender counts.
+        if (returnPath === '<>') return true;
+    }
+
+    return false;
+}
+
+/**
+ * Is this address one that never wants an automatic reply?
+ *
+ * @param   {string} address
+ * @returns {boolean}
+ */
+export function isNoReplyAddress(address) {
+    const local = String(address ?? '').split('@')[0].toLowerCase().replace(/[._-]/g, '-');
+    return NEVER_REPLY_TO.some(name => local === name || local.startsWith(`${name}-`));
+}
+
+/**
+ * Should this message be answered automatically?
+ *
+ * Returns the reason either way. The settings screen shows it, which is the
+ * only way anybody ever finds out why their responder stayed quiet.
+ *
+ * @param   {{message: object, vacation: object, addresses: string[],
+ *            lastRepliedAt?: string|null, knownSender?: boolean, now?: Date}} options
+ * @returns {{reply: boolean, reason: string}}
+ */
+export function shouldAutoReply({
+    message, vacation, addresses = [], lastRepliedAt = null, knownSender = false, now = new Date()
+}) {
+    const settings = normaliseVacation({vacation});
+
+    if (!isActive(vacation, now)) return {reply: false, reason: 'The away message is not active.'};
+
+    const sender = (message?.from ?? [])[0]?.address ?? '';
+    if (!sender) return {reply: false, reason: 'The message has no sender address.'};
+
+    // 1. Machines, lists and anything that announced itself as automatic.
+    if (message?.automated === true) {
+        return {reply: false, reason: 'It was sent automatically, or to a mailing list.'};
+    }
+
+    // 2. Bounces and addresses that exist to send rather than receive.
+    if (isNoReplyAddress(sender)) {
+        return {reply: false, reason: `${sender} is not an address that accepts replies.`};
+    }
+
+    // 3. Ourselves. A mailbox answering its own mail loops with no second party.
+    const mine = new Set(addresses.map(a => String(a).trim().toLowerCase()).filter(Boolean));
+    if (mine.has(sender.toLowerCase())) {
+        return {reply: false, reason: 'It came from this mailbox.'};
+    }
+
+    // 4. Addressed to us, not merely delivered to us. Anything else is a blast
+    //    we were Bcc'd on, and a blast must not be answered.
+    const recipients = [...(message?.to ?? []), ...(message?.cc ?? [])]
+        .map(entry => String(entry?.address ?? '').toLowerCase());
+    if (mine.size && !recipients.some(address => mine.has(address))) {
+        return {reply: false, reason: 'This mailbox was not in the To or Cc - it looks like a bulk send.'};
+    }
+
+    // 5. Once per sender per interval.
+    if (lastRepliedAt) {
+        const since = now.getTime() - new Date(lastRepliedAt).getTime();
+        if (since < settings.intervalDays * 86_400_000) {
+            return {reply: false, reason: `${sender} has already been told in the last ${settings.intervalDays} days.`};
+        }
+    }
+
+    if (settings.knownSendersOnly && !knownSender) {
+        return {reply: false, reason: `${sender} is not in your contacts.`};
+    }
+
+    return {reply: true, reason: `Replying to ${sender}.`};
+}
+
+/**
+ * The headers an automatic reply must carry.
+ *
+ * This is the other half of the loop prevention, and the half that protects
+ * everybody else: our reply announces itself as automatic so the responder at
+ * the far end refuses to answer it. Leaving these off is what turns two
+ * polite away messages into a mail loop.
+ *
+ * @returns {Object.<string, string>}
+ */
+export function autoReplyHeaders() {
+    return {
+        'Auto-Submitted': 'auto-replied',
+        // Understood by older software that predates RFC 3834.
+        'Precedence': 'bulk',
+        'X-Auto-Response-Suppress': 'All'
+    };
+}
+
+/**
+ * The subject an automatic reply carries.
+ *
+ * @param   {object} vacation
+ * @param   {string} originalSubject
+ * @returns {string}
+ */
+export function replySubject(vacation, originalSubject) {
+    const settings = normaliseVacation({vacation});
+    const original = headerSafe(originalSubject);
+    if (!original) return settings.subject;
+    // The original subject, so it threads with what they sent, prefixed with
+    // the notice rather than replaced by it.
+    return /^re:\s*/i.test(original)
+        ? `${settings.subject}: ${original}`
+        : `${settings.subject}: Re: ${original}`;
+}

package/plugins/_lib/admin/ui/help.css

@@ -0,0 +1 @@
+.dm-help-marker{display:inline-flex;align-items:center;justify-content:center;width:15px;height:15px;margin-left:.35rem;padding:0;flex:0 0 auto;vertical-align:middle;font-size:10px;font-weight:700;line-height:1;font-family:inherit;color:var(--dm-text-muted);background:transparent;border:1px solid var(--dm-border);border-radius:50%;cursor:help}.dm-help-marker:hover,.dm-help-marker:focus-visible{color:var(--dm-primary);border-color:var(--dm-primary)}label.form-label:has(>.dm-help-marker),legend:has(>.dm-help-marker){display:inline-flex;align-items:center}.dm-help-panel{padding:.25rem .25rem 1rem;display:flex;flex-direction:column;gap:.5rem}.dm-help-heading{margin:.75rem 0 0;font-size:.8rem;font-weight:700;text-transform:uppercase;letter-spacing:.06em;color:var(--dm-text-muted)}.dm-help-panel p{margin:0}

package/plugins/_lib/admin/ui/help.js

@@ -0,0 +1,174 @@
+/**
+ * Inline help, as a thing every admin screen gets for free.
+ *
+ * A screen is not finished when it works; it is finished when somebody who has
+ * never seen it can work out what each control does without asking. So help is
+ * declarative and lives in the markup next to the thing it explains:
+ *
+ *     <label class="form-label" data-help="Fills the due date on a new
+ *            invoice. 0 leaves it blank.">Payment terms</label>
+ *
+ * and one `scanHelp(container)` after render wires every one of them. A hint
+ * written three lines from the field it describes is a hint that goes stale;
+ * written on the field, it cannot.
+ *
+ * ## Why tooltips
+ *
+ * Domma has no popover component - the E facade is card/modal/tabs/accordion/
+ * tooltip/badge/dropdown/carousel/slideover/contextMenu and friends - so a
+ * short hint is `E.tooltip` and anything longer is a slideover. `E.tooltip`
+ * physically WRAPS its element in `<domma-tooltip>`, so wiring one twice used
+ * to nest the wrappers and lose the tooltip entirely; it is idempotent from
+ * 0.29.2, and `scanHelp` marks what it has done anyway, because a view that is
+ * re-rendered calls it again.
+ *
+ * There is also no content fallback from `data-tooltip`, so the text is always
+ * passed explicitly.
+ *
+ * @module _lib/admin/ui/help
+ */
+
+/** Marks an element whose help has already been wired. */
+const DONE = 'dmHelpWired';
+
+/**
+ * Attach a hint to one element.
+ *
+ * @param   {HTMLElement} el
+ * @param   {string} text
+ * @param   {{position?: string}} [options]
+ * @returns {void}
+ */
+export function helpTip(el, text, {position = 'top'} = {}) {
+    if (!el || !text || el.dataset[DONE]) return;
+    el.dataset[DONE] = '1';
+
+    if (typeof E?.tooltip === 'function') {
+        try {
+            E.tooltip(el, {content: text, position, delay: {show: 250, hide: 0}});
+        } catch {
+            // A tooltip that cannot be built is not worth losing the screen for.
+        }
+    }
+    // `title` as well, always: it is what a screen reader and a keyboard user
+    // get, and it is the whole hint on any host where the component is absent.
+    if (!el.title) el.title = text;
+}
+
+/**
+ * Append a small `?` marker carrying a hint.
+ *
+ * Its own element rather than a hint on the label, because a whole label that
+ * shows a tooltip on hover is a surprise - a marker is a thing you aim at.
+ *
+ * @param   {HTMLElement} parent
+ * @param   {string} text
+ * @param   {{position?: string, label?: string}} [options]
+ * @returns {HTMLElement}
+ */
+export function helpIcon(parent, text, {position = 'top', label = 'Help'} = {}) {
+    const marker = document.createElement('button');
+    marker.type = 'button';
+    marker.className = 'dm-help-marker';
+    marker.setAttribute('aria-label', label);
+    marker.textContent = '?';
+    // A help marker is not a form control and must never submit or steal a
+    // click from the field it sits beside.
+    marker.addEventListener('click', (e) => e.preventDefault());
+    parent.appendChild(marker);
+    helpTip(marker, text, {position});
+    return marker;
+}
+
+/**
+ * Wire every `data-help` under a root.
+ *
+ * On a `<label>`, a `<legend>` or anything carrying `data-help-marker`, the
+ * hint is hung off an appended `?`. On anything else - a button, an input, a
+ * whole card - it is hung off the element itself, because those are already
+ * things you point at.
+ *
+ * @param   {HTMLElement|object} root - element or Domma collection
+ * @returns {number} how many were wired
+ */
+export function scanHelp(root) {
+    const host = root && typeof root.get === 'function' ? root.get(0) : root;
+    if (!host || host.nodeType !== 1) return 0;
+
+    let wired = 0;
+    const targets = [...host.querySelectorAll('[data-help]')];
+    if (host.matches?.('[data-help]')) targets.unshift(host);
+
+    for (const el of targets) {
+        if (el.dataset[DONE]) continue;
+        const text = el.getAttribute('data-help');
+        if (!text) continue;
+        const position = el.getAttribute('data-help-position') || 'top';
+
+        const wantsMarker = el.hasAttribute('data-help-marker')
+            || el.tagName === 'LABEL' || el.tagName === 'LEGEND'
+            || /^H[1-6]$/.test(el.tagName);
+
+        if (wantsMarker) {
+            el.dataset[DONE] = '1';
+            helpIcon(el, text, {position, label: `Help: ${el.textContent.trim() || 'this field'}`});
+        } else {
+            helpTip(el, text, {position});
+        }
+        wired++;
+    }
+    return wired;
+}
+
+/**
+ * A longer explanation, in a slideover.
+ *
+ * For the things a one-line hint cannot carry - how numbering works, what a
+ * template does. `sections` is `[{title, body}]`, body being plain text or a
+ * list of lines.
+ *
+ * @param   {{title: string, intro?: string, sections?: Array}} options
+ * @returns {object} the slideover, already open
+ */
+export function openHelpPanel({title, intro = '', sections = []}) {
+    const slideover = E.slideover({
+        title,
+        size: 'md',
+        position: 'right',
+        // close() only hides and destroy() does not detach, so both, once the
+        // slide-out has run - otherwise every open leaves a panel behind.
+        onClose: () => setTimeout(() => {
+            slideover.destroy();
+            slideover.element?.remove();
+        }, 350)
+    });
+
+    const wrap = document.createElement('div');
+    wrap.className = 'dm-help-panel';
+
+    if (intro) {
+        const p = document.createElement('p');
+        p.className = 'text-sm text-muted';
+        p.textContent = intro;
+        wrap.appendChild(p);
+    }
+
+    for (const section of sections) {
+        if (section.title) {
+            const h = document.createElement('h4');
+            h.className = 'dm-help-heading';
+            h.textContent = section.title;
+            wrap.appendChild(h);
+        }
+        for (const line of [].concat(section.body ?? [])) {
+            const p = document.createElement('p');
+            p.className = 'text-sm';
+            p.textContent = line;
+            wrap.appendChild(p);
+        }
+    }
+
+    slideover.element.appendChild(wrap);
+    slideover.open();
+    return slideover;
+}