domma-cms 1.8.33 → 1.8.35

package/plugins/docs/admin/lib/api.js

@@ -0,0 +1,340 @@
+/**
+ * The Docs API, and what the Docs screens share: the admin's helpers (loaded
+ * at run time - a plugin never imports admin/ statically), escaping, small
+ * DOM fragments and the add-on loader.
+ *
+ * Calls go through Domma's `H`, which the admin wraps to attach the access
+ * token and refresh it on a 401. It throws with the server's `error` text.
+ *
+ * @module docs/admin/lib/api
+ */
+
+export const BASE = '/api/plugins/docs';
+export const HOME = '#/plugins/docs';
+export const docHref = (id) => `#/plugins/docs/d/${encodeURIComponent(id)}`;
+
+const seg = (id) => encodeURIComponent(String(id));
+
+/**
+ * Call a Docs endpoint - the old single-function form, kept for the libs
+ * (folders, templates, versions) that use it.
+ *
+ * @param   {string} path
+ * @param   {string} [method='GET']
+ * @param   {*}      [body]
+ * @param   {object} [headers]
+ * @returns {Promise<*>}
+ */
+export function api(path, method = 'GET', body, headers) {
+    return H.request(method, BASE + path, body ?? null, {headers: headers || {}, silent: true});
+}
+
+/** One browser tab's editing session - what the edit lock is held by. */
+export function newSession() {
+    return (crypto.randomUUID?.() || `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}`).replace(/[^A-Za-z0-9-]/g, '');
+}
+
+const sessionHeader = (session) => (session ? {'X-Docs-Session': session} : {});
+
+export const docsApi = {
+    settings: {
+        get: () => api('/settings'),
+        save: (d) => api('/settings', 'PUT', d)
+    },
+    people: () => api('/people'),
+    list: (params = {}) => {
+        const q = new URLSearchParams();
+        for (const [k, v] of Object.entries(params)) if (v !== undefined && v !== null && v !== '') q.set(k, v);
+        return api(`/documents${q.toString() ? `?${q}` : ''}`);
+    },
+    get: (id, session, {poll = false} = {}) => api(`/documents/${seg(id)}${poll ? '?poll=1' : ''}`, 'GET', null, sessionHeader(session)),
+    create: (d) => api('/documents', 'POST', d),
+    update: (id, d, session) => api(`/documents/${seg(id)}`, 'PUT', d, sessionHeader(session)),
+    trash: (id) => api(`/documents/${seg(id)}`, 'DELETE'),
+    purge: (id) => api(`/documents/${seg(id)}?permanent=1`, 'DELETE'),
+    restore: (id) => api(`/documents/${seg(id)}/restore`, 'POST', {}),
+    emptyTrash: () => api('/trash/empty', 'POST', {}),
+    duplicate: (id, d = {}) => api(`/documents/${seg(id)}/duplicate`, 'POST', d),
+    star: (id, on) => api(`/documents/${seg(id)}/star`, 'POST', {on}),
+    importFile: (d) => api('/documents/import', 'POST', d),
+    // 2.13: PDF documents - the file goes up as base64 (the same road Docs Pro's Word import takes).
+    uploadPdf: (d) => api('/documents/upload', 'POST', d),
+    replaceFile: (id, d, session) => api(`/documents/${seg(id)}/file`, 'PUT', d, sessionHeader(session)),
+    fileUrl: (id, {download = false} = {}) => `${BASE}/documents/${seg(id)}/file${download ? '?download=1' : ''}`,
+    // The frame's address: the file by ticket (GET /documents/:id answers `fileTicket`), since a frame carries no bearer header.
+    viewUrl: (id, ticket) => `${BASE}/documents/${seg(id)}/view?t=${encodeURIComponent(ticket)}`,
+    versionFileUrl: (id, n, {download = false} = {}) => `${BASE}/documents/${seg(id)}/versions/${seg(n)}/file${download ? '?download=1' : ''}`,
+    shares: (id, d) => api(`/documents/${seg(id)}/shares`, 'PUT', d),
+    linkOn: (id) => api(`/documents/${seg(id)}/link`, 'POST', {}),
+    linkOff: (id) => api(`/documents/${seg(id)}/link`, 'DELETE'),
+    send: (id, d) => api(`/documents/${seg(id)}/send`, 'POST', d),
+    lock: (id, session, force = false) => api(`/documents/${seg(id)}/lock`, 'POST', {session, force}),
+    unlock: (id, session) => api(`/documents/${seg(id)}/lock?session=${seg(session)}`, 'DELETE'),
+    versions: (id) => api(`/documents/${seg(id)}/versions`),
+    version: (id, n) => api(`/documents/${seg(id)}/versions/${seg(n)}`),
+    restoreVersion: (id, n, session) => api(`/documents/${seg(id)}/versions/${seg(n)}/restore`, 'POST', {}, sessionHeader(session))
+};
+
+/**
+ * Let go of the edit lock while the page itself is going away (a closed
+ * tab). A normal call may be cut off mid-flight; `keepalive` is not.
+ */
+export function unlockOnUnload(id, session) {
+    try {
+        const raw = S.get('auth_token');
+        const token = typeof raw === 'string' ? raw : '';
+        fetch(`${BASE}/documents/${seg(id)}/lock?session=${seg(session)}`, {
+            method: 'DELETE', keepalive: true, headers: token ? {Authorization: `Bearer ${token}`} : {}
+        }).catch(() => {});
+    } catch { /* best effort */ }
+}
+
+/**
+ * Sanitise document HTML for the admin. DOMPurify directly, because the
+ * admin's Domma.sanitize drops data-* attributes - and checklists live in
+ * data-type / data-checked. Without DOMPurify the HTML goes in as the server
+ * stored it (the server sanitised it on the way in).
+ *
+ * @param   {string} html
+ * @returns {string}
+ */
+// Suggestion marks (2.5) are always kept, so they stay suggestions even while Docs Pro is off.
+const DOC_ATTRS = ['target', 'data-type', 'data-checked', 'data-sug', 'data-by', 'data-name', 'data-at'];
+
+/** Let an add-on keep more attributes in documents (Docs Pro comment anchors). */
+export function allowDocAttrs(list) {
+    for (const a of list || []) if (/^[a-z][a-z0-9-]*$/.test(a) && !/^on/.test(a) && !DOC_ATTRS.includes(a)) DOC_ATTRS.push(a);
+}
+
+/**
+ * What a document says to the world (2.5): add-ons' filters over the body
+ * before it leaves Docs - a download, print, a new Page or Blog post. Docs
+ * Pro takes out comment marks and shows pending suggestions as not made.
+ * Keyed, so an add-on installed again replaces its own filter.
+ */
+const contentFilters = new Map();
+
+/** Pending suggestions as not made - Docs' own, whether or not Docs Pro is on (the server's withoutSuggestions). */
+export function withoutSuggestions(html) {
+    if (!html.includes('data-sug')) return html;
+    const t = document.createElement('template');
+    t.innerHTML = html;
+    t.content.querySelectorAll('ins[data-sug]').forEach(el => el.remove());
+    t.content.querySelectorAll('del[data-sug]').forEach(el => el.replaceWith(...el.childNodes));
+    return t.innerHTML;
+}
+export function setContentFilter(key, fn) {
+    if (typeof fn === 'function') contentFilters.set(String(key), fn); else contentFilters.delete(String(key));
+}
+export function outgoing(html) {
+    let out = withoutSuggestions(String(html ?? ''));
+    for (const fn of contentFilters.values()) { try { out = String(fn(out) ?? out); } catch { /* an add-on's problem */ } }
+    return out;
+}
+
+export function sanitizeHtml(html) {
+    const P = window.DOMPurify;
+    if (P?.sanitize) {
+        // Only the data-* attributes documents use: a data-on-click or a help marker
+        // in someone's body must never reach the admin's own bindings.
+        return P.sanitize(String(html ?? ''), {
+            ALLOW_DATA_ATTR: false,
+            ADD_ATTR: DOC_ATTRS,
+            FORBID_TAGS: ['style', 'form', 'input', 'button', 'textarea', 'select', 'iframe', 'object', 'embed'],
+            FORBID_ATTR: ['id', 'name']
+        });
+    }
+    // No sanitiser loaded: show the text, never raw markup.
+    const t = document.createElement('div');
+    t.textContent = String(html ?? '').replace(/<[^>]+>/g, ' ');
+    return t.innerHTML;
+}
+
+/** E.confirm, titles and toasts render HTML: user text goes in escaped. */
+export const esc = (s) => String(s ?? '').replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+
+/** Text as text, whatever it arrived as. */
+export function asText(value) {
+    return value === null || value === undefined ? '' : String(value);
+}
+
+/** A small DOM tree from an HTML string that holds NO unescaped user data. */
+export function fragment(html) {
+    const t = document.createElement('template');
+    t.innerHTML = html.trim();
+    return t.content.firstElementChild;
+}
+
+/** An icon as an SVG string, for templates built in JS (empty when the name is unknown). */
+export function icon(name, size = 16) {
+    try { return window.I?.html?.(name, {size}) || ''; } catch { return ''; }
+}
+
+let kit = null;
+
+/** tool-kit, plugin-chrome and help-popover, once, with stand-ins for an older admin. */
+export function loadKit() {
+    if (!kit) {
+        kit = Promise.all([
+            import('/admin/js/lib/tool-kit.js').catch(() => ({})),
+            import('/admin/js/lib/plugin-chrome.js').catch(() => ({})),
+            import('/admin/js/lib/help-popover.js').catch(() => ({}))
+        ]).then(([tk, chrome, help]) => ({
+            onceClosed: tk.onceClosed || ((so, fn) => {
+                const c = so.close.bind(so);
+                let done = false;
+                so.close = (...a) => {
+                    const r = c(...a);
+                    if (!done) { done = true; fn?.(); setTimeout(() => { try { so.destroy?.(); } catch { /* gone */ } so.element?.remove(); }, 400); }
+                    return r;
+                };
+            }),
+            openMenuAt: tk.openMenuAt || ((el) => {
+                const r = el.getBoundingClientRect();
+                el.dispatchEvent(new MouseEvent('contextmenu', {bubbles: true, cancelable: true, clientX: r.left, clientY: r.bottom, view: window}));
+            }),
+            settingsStore: tk.settingsStore || ((key, normalise) => ({
+                read() { try { return normalise(S.get(key)); } catch { return normalise(null); } },
+                write(v) { try { S.set(key, v); } catch { /* convenience only */ } }
+            })),
+            viewLifetime: tk.viewLifetime || ((pattern) => {
+                let fns = [];
+                const run = () => { const l = fns; fns = []; l.forEach(fn => { try { fn?.(); } catch { /* gone */ } }); };
+                const onHash = () => { if (!pattern.test(location.hash)) run(); };
+                return {
+                    add(fn) { fns.push(fn); return () => { const at = fns.indexOf(fn); if (at !== -1) fns.splice(at, 1); }; },
+                    reset() { run(); window.addEventListener('hashchange', onHash); fns.push(() => window.removeEventListener('hashchange', onHash)); }
+                };
+            }),
+            addBannerAction: chrome.addBannerAction || (() => null),
+            sidebarCount: tk.sidebarCount || (() => {}),
+            helpPopovers: help.helpPopovers || (() => () => {})
+        }));
+    }
+    return kit;
+}
+
+/**
+ * Add-ons (Docs Pro) the server says are registered: their admin modules,
+ * imported once. Each exports `install(host)`; a module that fails to load
+ * is skipped - Docs works without it.
+ *
+ * @param   {Array<{module:string}>} list from GET /settings `extensions`
+ * @returns {Promise<Array<object>>}
+ */
+const loaded = new Map();
+export async function loadExtensions(list) {
+    const out = [];
+    for (const ext of Array.isArray(list) ? list : []) {
+        if (!ext?.module || !String(ext.module).startsWith('/plugins/')) continue;
+        if (!loaded.has(ext.module)) loaded.set(ext.module, import(ext.module).catch((err) => { console.warn('[docs] add-on failed to load', ext.module, err); return null; }));
+        const mod = await loaded.get(ext.module);
+        if (mod) out.push({...ext, mod});
+    }
+    return out;
+}
+
+/** A file (an upload) as base64, for the JSON body of an upload. */
+export function readBase64(file) {
+    return new Promise((resolve, reject) => {
+        const r = new FileReader();
+        r.onload = () => resolve(String(r.result || '').replace(/^data:[^,]*,/, ''));
+        r.onerror = () => reject(new Error(`Could not read ${file.name}`));
+        r.readAsDataURL(file);
+    });
+}
+
+/** Is this a PDF, by name or type? (2.13) */
+export const isPdfFile = (file) => Boolean(file) && (/\.pdf$/i.test(file.name || '') || file.type === 'application/pdf');
+
+/**
+ * A Docs route that answers bytes (a PDF), fetched with the signed-in token
+ * - an <iframe> cannot carry a bearer header, so the file comes here as a
+ * Blob and the frame shows the blob's address (2.13).
+ *
+ * @param   {string} url  from docsApi.fileUrl / versionFileUrl
+ * @returns {Promise<Blob>}
+ */
+export async function fetchBlob(url) {
+    const raw = S.get('auth_token');
+    const token = typeof raw === 'string' ? raw : '';
+    const res = await fetch(url, {headers: token ? {Authorization: `Bearer ${token}`} : {}, cache: 'no-store'});
+    if (!res.ok) {
+        let msg = '';
+        try { msg = (await res.json())?.error || ''; } catch { /* no body */ }
+        throw new Error(msg || (res.status === 404 ? 'The file could not be found.' : `The file could not be loaded (${res.status}).`));
+    }
+    return res.blob();
+}
+
+/** Save a Blob as a file. */
+export function downloadBlob(name, blob) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = name;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/** Download a string as a file. */
+export function download(name, text, type) {
+    const blob = new Blob([text], {type});
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = name;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    setTimeout(() => URL.revokeObjectURL(url), 1000);
+}
+
+/**
+ * Print a document on its own - the browser's dialog, where "Save as PDF"
+ * lives. A hidden frame holding just the document, so the admin around it
+ * never reaches the page.
+ */
+export function printHtml(fullHtml) {
+    const frame = document.createElement('iframe');
+    frame.setAttribute('aria-hidden', 'true');
+    frame.style.cssText = 'position:fixed;right:0;bottom:0;width:0;height:0;border:0;visibility:hidden';
+    document.body.appendChild(frame);
+    const doc = frame.contentDocument;
+    doc.open();
+    doc.write(fullHtml);
+    doc.close();
+    const go = () => {
+        try { frame.contentWindow.focus(); frame.contentWindow.print(); } catch { /* blocked */ }
+        setTimeout(() => frame.remove(), 60000);
+    };
+    // Images must be in before the page is laid out for print.
+    const imgs = [...doc.images].filter(i => !i.complete);
+    if (!imgs.length) setTimeout(go, 50);
+    else Promise.all(imgs.map(i => new Promise(r => { i.onload = i.onerror = r; }))).then(go);
+}
+
+/**
+ * E.prompt with a starting value that survives any characters. E.prompt's own
+ * `inputValue` is sanitised into a value="…" string, which turns &quot; back
+ * into a bare quote - a title like Q3 "draft" opened as `Q3 ` and saved cut
+ * short. The dialog's input exists as soon as E.prompt returns, so the value is
+ * set as a property instead.
+ *
+ * @param {string} message
+ * @param {object} options - E.prompt options, without inputValue
+ * @param {string} value
+ * @returns {Promise<string|null>}
+ */
+export function promptWith(message, options, value) {
+    const answer = E.prompt(message, options);
+    const input = [...document.querySelectorAll('.dm-dialog-input')].at(-1);
+    if (input) {
+        input.value = String(value ?? '');
+        setTimeout(() => { try { input.select(); } catch { /* gone */ } }, 60);
+    }
+    return answer;
+}