domma-cms 1.6.57 → 1.6.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "1.6.57",
+  "version": "1.6.58",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",

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

@@ -362,3 +362,92 @@ export function holdEscapeOn(so) {
         if (hold.count === 0) so.options.closeOnEscape = hold.original;
     };
 }
+
+// ---------------------------------------------------------------------------
+// Edition extensions
+// ---------------------------------------------------------------------------
+
+/**
+ * Menu items an edition contributed (`extensions.folderItems` /
+ * `mailboxItems`), made safe to merge into a core menu.
+ *
+ * Whatever came back is checked rather than trusted: anything that is not a
+ * divider or a labelled item with a function action is dropped, leading,
+ * trailing and doubled dividers go, and every action is wrapped by `wrap` -
+ * which the view uses to run it on the next task (an item picked with Enter
+ * that opens a dialog must not hand that dialog the same Enter) and to turn
+ * a throw into a toast. `disabled` may be a boolean or a function.
+ *
+ * @param   {*} list - what the extension returned
+ * @param   {(action: Function) => Function} [wrap]
+ * @returns {object[]} Domma context-menu items
+ */
+export function extensionMenuItems(list, wrap = (fn) => fn) {
+    const out = [];
+    for (const entry of Array.isArray(list) ? list : []) {
+        if (!entry || typeof entry !== 'object') continue;
+        if (entry.type === 'divider') {
+            if (out.length && out.at(-1).type !== 'divider') out.push({type: 'divider'});
+            continue;
+        }
+        if (typeof entry.label !== 'string' || !entry.label.trim() || typeof entry.action !== 'function') continue;
+        const item = {label: entry.label, action: wrap(entry.action)};
+        if (typeof entry.icon === 'string' && entry.icon) item.icon = entry.icon;
+        if (entry.danger === true) item.danger = true;
+        if (typeof entry.disabled === 'function') item.disabled = entry.disabled;
+        else if (entry.disabled === true) item.disabled = () => true;
+        out.push(item);
+    }
+    while (out.length && out[0].type === 'divider') out.shift();
+    while (out.length && out.at(-1).type === 'divider') out.pop();
+    return out;
+}
+
+/**
+ * Pane-head buttons an edition contributed (`extensions.paneActions`), checked
+ * the same way: each needs an id (a button id and a de-duplication key), a
+ * label (its tooltip and accessible name) and an onClick. An id seen twice
+ * keeps the first.
+ *
+ * @param   {*} list
+ * @returns {{id: string, label: string, icon: string, onClick: Function, haspopup?: string}[]}
+ */
+export function extensionPaneActions(list) {
+    const out = [];
+    const seen = new Set();
+    for (const entry of Array.isArray(list) ? list : []) {
+        if (!entry || typeof entry !== 'object') continue;
+        const id = typeof entry.id === 'string' ? entry.id.replace(/[^a-z0-9_-]/gi, '') : '';
+        if (!id || seen.has(id)) continue;
+        if (typeof entry.label !== 'string' || !entry.label.trim() || typeof entry.onClick !== 'function') continue;
+        seen.add(id);
+        const action = {id, label: entry.label, icon: typeof entry.icon === 'string' && entry.icon ? entry.icon : 'plus', onClick: entry.onClick};
+        if (['dialog', 'menu'].includes(entry.haspopup)) action.haspopup = entry.haspopup;
+        out.push(action);
+    }
+    return out;
+}
+
+/**
+ * Put an edition's items into a core menu: above the menu's last group when
+ * that group holds a destructive item (Remove, Delete) - so the edition's
+ * entries never sit under the dangerous one - and at the end otherwise.
+ * Separated by a divider either way. Unchanged when there is nothing to add.
+ *
+ * @param   {object[]} items - the core menu
+ * @param   {object[]} extra - from extensionMenuItems()
+ * @returns {object[]}
+ */
+export function mergeExtensionItems(items, extra) {
+    if (!extra?.length) return items;
+    const out = [...items];
+    let last = -1;
+    for (let i = out.length - 1; i >= 0; i -= 1) {
+        if (out[i]?.type === 'divider') { last = i; break; }
+    }
+    if (last > 0 && out.slice(last + 1).some(item => item?.danger === true)) {
+        out.splice(last, 0, {type: 'divider'}, ...extra);
+        return out;
+    }
+    return out.length ? [...out, {type: 'divider'}, ...extra] : [...extra];
+}

package/plugins/_lib/admin/mail/reader-view.js

@@ -57,7 +57,7 @@ const {
     esc, mailboxDraftsKey, mailboxDraftId, mailboxDraftData, mailboxFingerprint, normaliseDraftMap,
     pruneDraftMap, mailboxDraftDecision, mailboxRestoreQuestion, RESTORE_BUTTONS, settingsDiscardQuestion,
     onceOnly, accountMenuModel, folderReadMenuModel, mailboxRowMenuModel, menuItems, sidebarUrl, hasNewMail,
-    holdEscapeOn
+    holdEscapeOn, extensionMenuItems, extensionPaneActions, mergeExtensionItems
 } = await import(versioned('reader-kit.js'));
 
 /**
@@ -183,7 +183,18 @@ function formatSize(bytes) {
 /**
  * Build the reader view for one plugin.
  *
- * @param   {{pluginName: string, assetVersion?: string, settingsSections?: object[]}} options
+ * @param   {{pluginName: string, assetVersion?: string, settingsSections?: object[],
+ *            features?: object, extensions?: object}} options
+ *   `extensions` lets an edition add actions to the reader itself, each a
+ *   function given the reader's `view` handle (see `extensionView()`):
+ *     - `paneActions(view)` -> `[{id, label, icon, onClick, haspopup?}]`, buttons
+ *       in the Folders pane head beside New folder;
+ *     - `folderItems(folder, view)` -> Domma menu items, added to a folder's
+ *       menu (right-click, ⋮, Shift+F10);
+ *     - `mailboxItems(account, view)` -> the same, on a mailbox row's menu.
+ *   Optional, checked and feature-detected: an edition that passes it to an
+ *   older reader just does not get the entries. Item actions run on the next
+ *   task, so one picked with Enter cannot hand its own Enter to a dialog.
  *   `settingsSections` lets an edition contribute settings without forking the
  *   view: each is `{id, label, render(container, context)}`, and the shell
  *   handles the tabs, the lazy drawing and a section that throws.
@@ -193,7 +204,8 @@ function formatSize(bytes) {
  *   module is imported by a fixed path and carries no stamp of its own.
  * @returns {object} a Domma view
  */
-export function createReaderView({pluginName, assetVersion = ASSET_VERSION, settingsSections = [], features = {}}) {
+export function createReaderView({pluginName, assetVersion = ASSET_VERSION, settingsSections = [], features = {},
+    extensions = {}}) {
 const BASE = `/api/plugins/${pluginName}`;
 
 // Deliberately NOT keyed by plugin. The two editions never run together - the
@@ -3418,6 +3430,8 @@ return {
                     searchInputEl?.focus();
                     break;
                 case 'escape':
+                    // A panel on top owns Escape: it closes that, and only that.
+                    if (openPanels.size) break;
                     if (selected.size) clearSelection();
                     else if (searchQuery) clearSearch();
                     break;
@@ -4795,6 +4809,184 @@ return {
             }
         }
 
+        // ---------------------------------------------------------------
+        // Edition extensions (createReaderView's `extensions` option)
+        // ---------------------------------------------------------------
+
+        /**
+         * What an extension is handed: enough to open a panel of its own
+         * against this mailbox and to tell the reader something changed.
+         * Read through getters, so a handle kept by an open panel still sees
+         * the current mailbox and folders.
+         *
+         * @type {object}
+         */
+        const extensionView = Object.freeze({
+            pluginName,
+            base: BASE,
+            api,
+            assetVersion,
+            /** The mailbox on screen (a mailbox row's menu passes its own). */
+            get account() { return mailboxes.find(b => b.id === currentAccountId) ?? null; },
+            get mailboxes() { return [...mailboxes]; },
+            get folders() { return [...folders]; },
+            get currentFolder() { return currentFolder; },
+            /** False once the screen has gone - check it after every await. */
+            here,
+            /**
+             * Run `fn` once when the screen goes (or is mounted again).
+             *
+             * @param   {Function} fn
+             * @returns {Function} cancel it
+             */
+            onLeave(fn) {
+                if (typeof fn !== 'function') return () => {};
+                let live = true;
+                lifetime.add(() => { if (live) { live = false; fn(); } });
+                return () => { live = false; };
+            },
+            /**
+             * Have the reader look after a slideover the extension opened:
+             * Escape belongs to it while it is on top (the reader's own
+             * Escape - clear the selection, the search - does not also
+             * answer), it is closed when the screen goes, and it is taken
+             * out of the page once closed. Call before `open()`.
+             *
+             * @param   {object} slideover - from E.slideover
+             * @param   {{onClosed?: Function}} [options]
+             * @returns {object} the slideover
+             */
+            panel(slideover, {onClosed} = {}) {
+                return guardPanel(slideover, () => false, '', typeof onClosed === 'function' ? onClosed : () => {});
+            },
+            /** Read the folder list again, staying in the folder that is open. */
+            refreshFolders: () => refreshFolders(),
+            /**
+             * The same as a settings section's `changed`, so a panel written
+             * for one works from the other: reload means the folders (and the
+             * open list) of the mailbox on screen.
+             *
+             * @param   {{reload?: boolean}} [options]
+             * @returns {Promise<void>}
+             */
+            async changed({reload = false} = {}) {
+                profileFor = null;
+                refreshOutbox();
+                if (reload) await refreshFolders();
+            }
+        });
+
+        /**
+         * The folder list again, keeping the open folder when it still
+         * exists (a full loadFolders goes back to the inbox), and the open
+         * list with it - an import into the folder on screen shows at once.
+         *
+         * @returns {Promise<void>}
+         */
+        async function refreshFolders() {
+            if (!here() || !currentAccountId) return;
+            const account = currentAccountId;
+            const seq = ++foldersSeq;
+            try {
+                const params = new URLSearchParams({account, counts: '1'});
+                const result = await api(`${BASE}/folders?${params}`);
+                if (!here() || seq !== foldersSeq || currentAccountId !== account) return;
+                if (!result.folders?.some(f => f.path === currentFolder)) {
+                    await loadFolders({quiet: true});
+                    return;
+                }
+                folders = result.folders;
+                renderFolders();
+                if (!searchQuery) await loadMessages({fresh: true, quiet: true});
+                if (here()) refreshBadge();
+            } catch (err) {
+                if (here()) handleError(err);
+            }
+        }
+
+        /**
+         * Call one of the edition's extension functions, surviving one that
+         * is missing, throws or returns rubbish.
+         *
+         * @param   {string} name
+         * @param   {...*} args
+         * @returns {*}
+         */
+        function callExtension(name, ...args) {
+            const fn = extensions?.[name];
+            if (typeof fn !== 'function') return [];
+            try {
+                return fn(...args, extensionView) ?? [];
+            } catch (err) {
+                console.warn(`[mail] extensions.${name} failed:`, err);
+                return [];
+            }
+        }
+
+        /**
+         * An extension's action, run on the next task - a menu item picked
+         * with Enter that opens a dialog must not hand it that same Enter -
+         * and only while the screen is still here, with a throw shown.
+         *
+         * @param   {Function} fn
+         * @returns {Function}
+         */
+        function deferExtension(fn) {
+            return (...args) => {
+                setTimeout(() => {
+                    if (!here()) return;
+                    Promise.resolve()
+                        .then(() => fn(...args))
+                        .catch(err => E.toast(err?.message || 'That could not be done.', {type: 'error'}));
+                }, 0);
+            };
+        }
+
+        /**
+         * The menu items an extension adds for one row.
+         *
+         * @param   {'folderItems'|'mailboxItems'} name
+         * @param   {object} subject - the folder or mailbox
+         * @returns {object[]}
+         */
+        function extensionItems(name, subject) {
+            return extensionMenuItems(callExtension(name, subject), deferExtension);
+        }
+
+        /**
+         * The extension's buttons in the Folders pane head, beside New folder.
+         *
+         * @returns {void}
+         */
+        function addPaneActions() {
+            const actions = extensionPaneActions(callExtension('paneActions'));
+            if (!actions.length) return;
+            const head = foldersEl?.closest('.mail-folders-pane')?.querySelector('.mail-pane-head');
+            if (!head) return;
+            const before = head.querySelector('#mail-settings-btn');
+            for (const action of actions) {
+                const id = `mail-ext-${action.id}`;
+                if (head.querySelector(`#${id}`)) continue;
+                const button = document.createElement('button');
+                button.type = 'button';
+                button.className = 'btn btn-sm btn-ghost';
+                button.id = id;
+                button.title = action.label;
+                button.setAttribute('aria-label', action.label);
+                if (action.haspopup) button.setAttribute('aria-haspopup', action.haspopup);
+                const icon = document.createElement('span');
+                icon.setAttribute('data-icon', action.icon);
+                icon.setAttribute('data-icon-size', '14');
+                button.appendChild(icon);
+                // A click needs no deferring, but it costs nothing and keeps
+                // every entry point the same.
+                button.addEventListener('click', deferExtension(() => action.onClick(extensionView)));
+                if (before?.parentNode === head) head.insertBefore(button, before);
+                else head.appendChild(button);
+            }
+            try { Domma.icons?.scan?.(head); } catch { /* the title still names it */ }
+        }
+
         /**
          * Right-click a folder to manage it.
          *
@@ -4844,7 +5036,7 @@ return {
          * @returns {object[]}
          */
         function accountMenuItemsFor(box) {
-            return menuItems(accountMenuModel({
+            return mergeExtensionItems(menuItems(accountMenuModel({
                 isCurrent: box.id === currentAccountId,
                 isDefault: box.isDefault === true,
                 count: mailboxes.length
@@ -4854,7 +5046,7 @@ return {
                 edit: () => openMailboxForm(box),
                 default: () => toggleDefaultMailbox(box),
                 remove: () => removeMailbox(box)
-            });
+            }), extensionItems('mailboxItems', box));
         }
 
         /**
@@ -4895,8 +5087,9 @@ return {
             const locked = protectedUse || isInbox;
 
             const read = folderReadItems(folder);
-            if (!features.folders) return read;
-            return [
+            const extra = extensionItems('folderItems', folder);
+            if (!features.folders) return mergeExtensionItems(read, extra);
+            return mergeExtensionItems([
                 ...read,
                 {type: 'divider'},
                 {
@@ -4934,7 +5127,7 @@ return {
                     disabled: () => locked,
                     action: () => deleteFolder(folder)
                 }
-            ];
+            ], extra);
         }
 
         /**
@@ -5872,6 +6065,7 @@ return {
                 newFolder.addEventListener('click', () => createFolder(null, {pickParent: true}));
             }
         }
+        addPaneActions();
 
         // A real <input> here, unlike the row ticks: this one is not inside a
         // button, so it can be what it is.