domma-cms 1.8.32 → 1.8.34

package/plugins/docs/admin/views/docs.js

@@ -0,0 +1,777 @@
+/**
+ * Docs - Home.
+ *
+ * A rail of places (Recent, Starred, Shared with me, My documents and its
+ * folders, Templates, Trash, and any an add-on adds) and the documents in the
+ * one chosen, as cards or a list. Opening a document goes to its own screen
+ * (admin/views/editor.js, #/plugins/docs/d/<id>).
+ *
+ * On the Tool upgrade path: state is domma-reactive observables bound with
+ * M.applyBindings; every per-document and per-folder action is on a context
+ * menu (right-click, Shift+F10 or the ⋮); settings are behind the banner cog;
+ * help popovers explain the parts that need it.
+ *
+ * @module docs/admin/views/docs
+ */
+
+import {docsApi, api, HOME, docHref, esc, icon, loadKit, loadExtensions, allowDocAttrs, setContentFilter, promptWith, readBase64, isPdfFile} from '/plugins/docs/admin/lib/api.js';
+import {pdfFacts, pdfExportItems} from '/plugins/docs/admin/lib/pdf-view.js';
+import {FolderManager} from '/plugins/docs/admin/lib/folders.js';
+import {exportItems, openSendEmail} from '/plugins/docs/admin/lib/send.js';
+import {openShare} from '/plugins/docs/admin/lib/share.js';
+import {openSettings} from '/plugins/docs/admin/lib/settings.js';
+import {fmtDateTime} from '/plugins/_lib/admin/ui/dates.js';
+
+const STAR = () => icon('star', 16);
+const KEBAB = () => icon('more-vertical', 16);
+
+/**
+ * Item templates for the lists - the bodies of their `data-each`. Here, not
+ * in docs.html, because the router renders a templateUrl through `_.render`
+ * first, which replaces every `{{…}}` with nothing. Mustache escapes values.
+ * Whole class lists are values: the compiler drops whitespace beside `{{…}}`.
+ */
+const cardTemplate = () => `
+<div class="{{cls}}" data-doc="{{id}}" tabindex="0" role="button" aria-label="{{label}}">
+    <div class="docs-card__sheet" aria-hidden="true"><div class="docs-card__excerpt">{{excerpt}}</div></div>
+    <div class="docs-card__info">
+        <div class="docs-card__title">{{title}}</div>
+        <div class="docs-card__meta" title="{{when}}">{{meta}}</div>
+        <div class="docs-card__chips">
+            <span class="docs-chip docs-chip--pdf">PDF</span>
+            <span class="docs-chip docs-chip--shared">Shared</span>
+            <span class="docs-chip docs-chip--public">Public link</span>
+            <span class="docs-chip docs-chip--locked">{{lockText}}</span>
+        </div>
+    </div>
+    <button type="button" class="docs-card__star" data-star="{{id}}" aria-label="{{starLabel}}" title="{{starLabel}}">${STAR()}</button>
+    <button type="button" class="docs-kebab" aria-label="Actions for {{title}}" title="Actions">${KEBAB()}</button>
+</div>`;
+
+const templateTemplate = () => `
+<div class="docs-card docs-card--template" data-template="{{id}}" tabindex="0" role="button" aria-label="New document from {{title}}">
+    <div class="docs-card__sheet" aria-hidden="true"><div class="docs-card__excerpt">{{excerpt}}</div></div>
+    <div class="docs-card__info">
+        <div class="docs-card__title">{{title}}</div>
+        <div class="docs-card__meta">{{meta}}</div>
+    </div>
+    <button type="button" class="docs-kebab" aria-label="Actions for {{title}}" title="Actions">${KEBAB()}</button>
+</div>`;
+
+const folderTemplate = () => `
+<div class="{{cls}}" data-folder="{{id}}" tabindex="0" role="button" style="padding-left: {{indent}}rem">
+    <span class="docs-folder__name">{{name}}</span>
+    <button type="button" class="docs-kebab" aria-label="Actions for folder {{name}}" title="Actions">${KEBAB()}</button>
+</div>`;
+
+const VIEWS = {
+    recent: {title: 'Recent', empty: 'Documents you open or edit show up here.'},
+    starred: {title: 'Starred', empty: 'Star a document to keep it here - the star on its card, or its menu.'},
+    shared: {title: 'Shared with me', empty: 'Nobody has shared a document with you yet.'},
+    mine: {title: 'My documents', empty: 'No documents here yet.'},
+    templates: {title: 'Templates', empty: 'No templates yet. Open a document and choose Save as template from its menu.'},
+    trash: {title: 'Trash', empty: 'Trash is empty.'}
+};
+
+const PREFS_KEY = 'docs.home';
+const DEFAULT_PREFS = Object.freeze({view: 'recent', folderId: null, layout: 'grid', sort: 'updated', railCollapsed: false, showWordCount: true});
+
+/** Whitelist stored preferences - never merged blind. */
+export function normalisePrefs(raw) {
+    const r = raw && typeof raw === 'object' ? raw : {};
+    const d = DEFAULT_PREFS;
+    return {
+        view: typeof r.view === 'string' && (VIEWS[r.view] || /^ext:[a-z0-9-]+$/.test(r.view)) ? r.view : d.view,
+        folderId: typeof r.folderId === 'string' ? r.folderId : null,
+        layout: r.layout === 'list' ? 'list' : 'grid',
+        sort: ['updated', 'opened', 'title', 'created'].includes(r.sort) ? r.sort : d.sort,
+        railCollapsed: r.railCollapsed === true,
+        showWordCount: typeof r.showWordCount === 'boolean' ? r.showWordCount : d.showWordCount
+    };
+}
+
+/** Read a picked or dropped file as text, with a size limit. */
+function readFile(file) {
+    return new Promise((resolve, reject) => {
+        if (file.size > 4 * 1024 * 1024) { reject(new Error(`${file.name} is over 4 MB`)); return; }
+        const r = new FileReader();
+        r.onload = () => resolve(String(r.result || ''));
+        r.onerror = () => reject(new Error(`Could not read ${file.name}`));
+        r.readAsText(file);
+    });
+}
+
+let lifetime = null;
+
+export const docsView = {
+    templateUrl: '/plugins/docs/admin/templates/docs.html',
+
+    async onMount($container) {
+        const kit = await loadKit();
+        lifetime ??= kit.viewLifetime(/^#\/plugins\/docs\/?(\?.*)?$/);
+        lifetime.reset();
+        const root = $container.get(0);
+        const prefsStore = kit.settingsStore(PREFS_KEY, normalisePrefs);
+        let alive = true;
+        lifetime.add(() => { alive = false; });
+
+        let site = {};
+        try { site = await docsApi.settings.get(); } catch { /* an older server: defaults */ }
+        if (!alive) return;
+        const extensions = await loadExtensions(site.extensions);
+        if (!alive) return;
+        // Skeletons for a place's first load (an older core without the helper shows the slot's text).
+        const loader = await import('/admin/js/lib/loading.js').catch(() => null);
+        if (!alive) return;
+
+        // ---- State ----
+        const start = prefsStore.read();
+        const view = M.observable(start.view);
+        const folderId = M.observable(start.view === 'mine' ? start.folderId : null);
+        const layout = M.observable(start.layout);
+        const sort = M.observable(start.sort);
+        const railCollapsed = M.observable(start.railCollapsed || window.innerWidth < 720);
+        const showWordCount = M.observable(start.showWordCount);
+        const query = M.observable('');
+        const raw = M.observable([]);           // rows as the server sent them
+        const templates = M.observable([]);
+        const loading = M.observable(true);
+        // The skeleton slot: a place's first load, never a reload (search, after a change) - those keep the list on screen.
+        const skeleton = M.observable(true);
+        // The rail's numbers - what each place shows when opened (GET /count `places`).
+        const placeCounts = M.observable({starred: '', shared: '', mine: '', trash: ''});
+        const dragging = M.observable(false);
+        const folders = M.observable([]);
+
+        lifetime.add(M.effect(() => prefsStore.write({
+            view: view.value, folderId: folderId.value, layout: layout.value, sort: sort.value,
+            railCollapsed: railCollapsed.value, showWordCount: showWordCount.value
+        })));
+
+        // Plain observables fed by effects: a data-each over a computed never re-renders.
+        const rows = M.observable([]);
+        lifetime.add(M.effect(() => {
+            const s = sort.value;
+            const words = showWordCount.value;
+            const v = view.value;
+            const time = (iso) => Date.parse(iso || '') || 0;
+            const list = [...raw.value];
+            if (v !== 'recent') {
+                list.sort(s === 'title' ? (a, b) => a.title.localeCompare(b.title, undefined, {sensitivity: 'base'})
+                    : s === 'created' ? (a, b) => time(b.createdAt) - time(a.createdAt)
+                        : s === 'opened' ? (a, b) => time(b.openedAt) - time(a.openedAt)
+                            : (a, b) => time(b.updatedAt) - time(a.updatedAt));
+            }
+            rows.value = list.map((d) => {
+                const flags = ['docs-card'];
+                if (d.starred) flags.push('is-starred');
+                if (d.shared) flags.push('has-shared');
+                if (d.public) flags.push('has-public');
+                if (d.locked) flags.push('has-locked');
+                if (d.trashedAt) flags.push('is-trashed');
+                if (d.format === 'pdf') flags.push('is-pdf');
+                const when = v === 'trash' ? d.trashedAt : (s === 'opened' && d.openedAt ? d.openedAt : d.updatedAt);
+                const whenWord = v === 'trash' ? 'Trashed' : (s === 'opened' && d.openedAt ? 'Opened' : 'Edited');
+                const parts = [when ? `${whenWord} ${D(when).fromNow()}` : ''];
+                if (d.access !== 'owner' || v === 'shared') parts.push(d.ownerName);
+                // A PDF (2.13) says its pages and size where a written document says its words.
+                if (d.format === 'pdf') parts.push(pdfFacts(d.file) || 'PDF');
+                else if (words) parts.push(`${d.wordCount} word${d.wordCount === 1 ? '' : 's'}`);
+                return {
+                    id: d.id,
+                    cls: flags.join(' '),
+                    title: d.title || 'Untitled',
+                    label: `Open ${d.title || 'Untitled'}`,
+                    excerpt: d.excerpt || '',
+                    meta: parts.filter(Boolean).join(' · '),
+                    when: when ? fmtDateTime(when) : '',
+                    lockText: d.locked ? `${d.locked.name} is editing` : '',
+                    starLabel: d.starred ? 'Remove star' : 'Star'
+                };
+            });
+        }));
+
+        const templateRows = M.observable([]);
+        lifetime.add(M.effect(() => {
+            const q = query.value.trim().toLowerCase();
+            templateRows.value = templates.value
+                .filter(t => !q || (t.name || '').toLowerCase().includes(q) || (t.category || '').toLowerCase().includes(q))
+                .map(t => ({id: t.id, title: t.name || 'Untitled template',
+                    meta: t.builtIn ? [t.category, t.source].filter(Boolean).join(' · ') || 'Ready-made' : 'Your template',
+                    excerpt: String(t.content || '').replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 220)}));
+        }));
+
+        const folderRows = M.observable([]);
+        lifetime.add(M.effect(() => {
+            const current = view.value === 'mine' ? folderId.value : '__none';
+            folderRows.value = folders.value.filter(f => f.id !== null).map(f => ({
+                key: f.key, id: f.id, name: f.name,
+                indent: (0.75 + f.depth * 0.85).toFixed(2),
+                cls: `docs-folder${f.id === current ? ' is-active' : ''}`
+            }));
+        }));
+
+        let countsReady = false;
+        const folderManager = new FolderManager({
+            onFolderSelect: (id) => { go('mine', id); },
+            // A folder deleted moves its documents up: My documents' number changes (after the first load).
+            onChange: () => { folders.value = folderManager.rows(); if (countsReady) loadCounts(); }
+        });
+        const folderName = (id) => (id ? (folderManager.byId(id)?.name || 'Folder') : null);
+
+        const extPlaces = [];
+        const isExt = M.computed(() => view.value.startsWith('ext:'));
+        const data = {
+            view, folderId, layout, sort, query, rows, templateRows, folderRows, railCollapsed, dragging, skeleton, placeCounts,
+            isTemplates: M.computed(() => view.value === 'templates'),
+            isTrash: M.computed(() => view.value === 'trash'),
+            isExt,
+            bodyClass: M.computed(() => `docs-main__body ${layout.value === 'list' ? 'is-list' : 'is-grid'}${dragging.value ? ' is-dragging' : ''}`),
+            viewTitle: M.computed(() => {
+                folders.value;
+                const v = view.value;
+                if (v.startsWith('ext:')) return extPlaces.find(p => `ext:${p.key}` === v)?.label || 'Docs';
+                if (v === 'mine' && folderId.value) return folderName(folderId.value);
+                return VIEWS[v]?.title || 'Docs';
+            }),
+            countText: M.computed(() => {
+                if (view.value.startsWith('ext:') || loading.value) return '';
+                const n = view.value === 'templates' ? templateRows.value.length : rows.value.length;
+                return `${n}`;
+            }),
+            showEmpty: M.computed(() => !loading.value && !view.value.startsWith('ext:')
+                && (view.value === 'templates' ? templateRows.value.length === 0 : rows.value.length === 0)),
+            emptyText: M.computed(() => (query.value.trim() ? 'Nothing matches that search.' : (VIEWS[view.value]?.empty || ''))),
+            canCreateHere: M.computed(() => view.value === 'mine' || view.value === 'recent'),
+            trashNote: M.computed(() => `Documents in Trash are deleted for good after ${Number(site.trashDays) || 30} days.`)
+        };
+
+        // -------------------------------------------------------------- data
+
+        let loadSeq = 0;
+        /** The place's list. `fresh` (a place just opened): clear it and show a skeleton while it loads. */
+        async function load({fresh = false} = {}) {
+            const seq = ++loadSeq;
+            const v = view.peek();
+            if (v.startsWith('ext:')) { loading.value = false; skeleton.value = false; return; }
+            loading.value = true;
+            if (fresh) {
+                skeleton.value = true;
+                if (v === 'templates') templates.value = []; else raw.value = [];
+            }
+            const request = v === 'templates' ? api('/templates')
+                : docsApi.list({view: v, folder: v === 'mine' ? (folderId.peek() || '') : undefined, q: query.peek().trim() || undefined});
+            const slot = root.querySelector('.docs-loading');
+            try {
+                const list = skeleton.peek() && loader?.whileLoading && slot
+                    ? await loader.whileLoading(slot, request, layout.peek() === 'list' ? loader.SHAPES.rows : loader.SHAPES.tiles)
+                    : await request;
+                if (seq !== loadSeq || !alive) return;
+                if (v === 'templates') templates.value = Array.isArray(list) ? list : [];
+                else raw.value = Array.isArray(list) ? list : [];
+            } catch (err) {
+                if (alive && seq === loadSeq) E.toast(err.message || 'Could not load documents', {type: 'error'});
+            } finally {
+                if (seq === loadSeq && alive) { loading.value = false; skeleton.value = false; }
+            }
+        }
+
+        /** The rail's numbers. Quietly blank when the count cannot be had. */
+        let countSeq = 0;
+        async function loadCounts() {
+            // Only the newest answer counts: a quick trash then restore must not end on the older one.
+            const seq = ++countSeq;
+            try {
+                const r = await api('/count');
+                if (alive && seq === countSeq && r?.places) placeCounts.value = {...placeCounts.peek(), ...r.places};
+            } catch { /* the numbers are a convenience */ }
+        }
+
+        const extView = root.querySelector('.docs-ext-view');
+        let extDispose = null;
+        function go(v, folder = null) {
+            if (extDispose) { try { extDispose(); } catch { /* gone */ } extDispose = null; }
+            extView.replaceChildren();
+            view.value = v;
+            folderId.value = v === 'mine' ? folder : null;
+            if (v.startsWith('ext:')) {
+                const place = extPlaces.find(p => `ext:${p.key}` === v);
+                if (place) {
+                    Promise.resolve(place.render(extView, host)).then((d) => { extDispose = typeof d === 'function' ? d : null; })
+                        .catch((err) => E.toast(err.message || 'Could not open that view', {type: 'error'}));
+                }
+            }
+            if (window.innerWidth < 720) railCollapsed.value = true;
+            load({fresh: true});
+        }
+        lifetime.add(() => { if (extDispose) try { extDispose(); } catch { /* gone */ } });
+
+        let searchTimer = null;
+        let firstQuery = true;
+        lifetime.add(M.effect(() => {
+            query.value;
+            if (firstQuery) { firstQuery = false; return; }
+            clearTimeout(searchTimer);
+            searchTimer = setTimeout(() => { if (view.peek() !== 'templates') load(); }, 250);
+        }));
+        lifetime.add(() => clearTimeout(searchTimer));
+
+        // ---------------------------------------------------------- actions
+
+        const rowById = (id) => raw.peek().find(r => r.id === id);
+        /** The sidebar badge (GET /count) and the rail's numbers, after anything that changes them. */
+        const recount = () => { kit.sidebarCount('#/plugins/docs'); loadCounts(); };
+        const open = (id) => { location.hash = docHref(id); };
+
+        async function createDoc(content = '', title = 'Untitled') {
+            try {
+                const doc = await docsApi.create({title, content, folderId: view.peek() === 'mine' ? folderId.peek() : null});
+                recount();
+                if (alive) open(doc.id);
+            } catch (err) {
+                E.toast(err.message || 'Could not create the document', {type: 'error'});
+            }
+        }
+
+        /** Importers add-ons contribute (2.4): {ext: ['.docx'], label, accept, import(file, {folderId}) => doc}. */
+        const importers = [];
+        const importerFor = (f) => importers.find(i => i.ext.some(e => f.name.toLowerCase().endsWith(e)));
+
+        async function importFiles(files) {
+            const list = [...files].filter(Boolean);
+            if (!list.length) return;
+            const made = [];
+            const maxPdf = Number(site.pdf?.maxBytes) || 20 * 1024 * 1024;
+            for (const f of list) {
+                try {
+                    const own = importerFor(f);
+                    if (own) { made.push(await own.import(f, {folderId: view.peek() === 'mine' ? folderId.peek() : null})); continue; }
+                    // A PDF (2.13) is kept as a file, not converted.
+                    if (isPdfFile(f)) {
+                        if (f.size > maxPdf) throw new Error(`${f.name} is over ${Math.round(maxPdf / 1024 / 1024)} MB`);
+                        made.push(await docsApi.uploadPdf({name: f.name, data: await readBase64(f), folderId: view.peek() === 'mine' ? folderId.peek() : null}));
+                        continue;
+                    }
+                    const text = await readFile(f);
+                    const doc = await docsApi.importFile({name: f.name, text, folderId: view.peek() === 'mine' ? folderId.peek() : null});
+                    made.push(doc);
+                } catch (err) {
+                    E.toast(err.message || `Could not import ${f.name}`, {type: 'error'});
+                }
+            }
+            if (made.length) recount();
+            if (!alive) return;
+            if (made.length === 1) { open(made[0].id); return; }
+            if (made.length) {
+                E.toast(`Added ${made.length} documents`, {type: 'success'});
+                if (view.peek() !== 'mine') go('mine', view.peek() === 'mine' ? folderId.peek() : null);
+                else load();
+            }
+        }
+
+        async function toggleStar(id) {
+            const r = rowById(id);
+            if (!r) return;
+            try {
+                await docsApi.star(id, !r.starred);
+                if (!alive) return;
+                raw.value = raw.peek().map(x => (x.id === id ? {...x, starred: !r.starred} : x))
+                    .filter(x => view.peek() !== 'starred' || x.starred);
+                recount();   // Starred is in the badge's details and on the rail
+            } catch (err) {
+                E.toast(err.message || 'Could not change the star', {type: 'error'});
+            }
+        }
+
+        async function rename(id) {
+            const r = rowById(id);
+            const name = await promptWith('Document title', {title: 'Rename document'}, r?.title || '');
+            if (!alive || name === null || name === undefined || !String(name).trim()) return;
+            try {
+                await docsApi.update(id, {title: String(name).trim()});
+                if (alive) load();
+            } catch (err) {
+                E.toast(err.message || 'Could not rename', {type: 'error'});
+            }
+        }
+
+        async function copy(id) {
+            try {
+                const c = await docsApi.duplicate(id);
+                E.toast('Copy made in My documents', {type: 'success'});
+                recount();
+                if (alive && (view.peek() === 'mine' || view.peek() === 'recent')) load();
+                return c;
+            } catch (err) {
+                E.toast(err.message || 'Could not copy', {type: 'error'});
+            }
+        }
+
+        async function move(id, folder) {
+            try {
+                await docsApi.update(id, {folderId: folder});
+                E.toast(`Moved to ${folderName(folder) || 'My documents'}`, {type: 'success'});
+                if (!alive) return;
+                load();
+                loadCounts();   // My documents counts its top level
+            } catch (err) {
+                E.toast(err.message || 'Could not move', {type: 'error'});
+            }
+        }
+
+        async function trash(id) {
+            try {
+                await docsApi.trash(id);
+                if (alive) raw.value = raw.peek().filter(r => r.id !== id);
+                E.toast('Moved to Trash', {type: 'success'});
+                recount();
+            } catch (err) {
+                E.toast(err.message || 'Could not move to Trash', {type: 'error'});
+            }
+        }
+
+        async function restore(id) {
+            try {
+                await docsApi.restore(id);
+                if (alive) raw.value = raw.peek().filter(r => r.id !== id);
+                E.toast('Restored', {type: 'success'});
+                recount();
+            } catch (err) {
+                E.toast(err.message || 'Could not restore', {type: 'error'});
+            }
+        }
+
+        async function purge(id) {
+            const r = rowById(id);
+            const ok = await E.confirm(`Delete <strong>${esc(r?.title || 'this document')}</strong> and its version history for good? This cannot be undone.`,
+                {title: 'Delete for good', confirmText: 'Delete'});
+            if (!ok || !alive) return;
+            try {
+                await docsApi.purge(id);
+                if (alive) raw.value = raw.peek().filter(x => x.id !== id);
+                recount();
+            } catch (err) {
+                E.toast(err.message || 'Could not delete', {type: 'error'});
+            }
+        }
+
+        async function emptyTrash() {
+            const ok = await E.confirm('Delete everything in Trash for good? This cannot be undone.', {title: 'Empty Trash', confirmText: 'Empty Trash'});
+            if (!ok || !alive) return;
+            try {
+                const r = await docsApi.emptyTrash();
+                E.toast(`${r.deleted} document${r.deleted === 1 ? '' : 's'} deleted`, {type: 'success'});
+                recount();
+                if (alive) load();
+            } catch (err) {
+                E.toast(err.message || 'Could not empty Trash', {type: 'error'});
+            }
+        }
+
+        // Panels opened from Home close with it; one still opening checks alive().
+        const panelLife = {alive: () => alive, add: (fn) => lifetime.add(fn)};
+
+        async function share(id) {
+            try {
+                const doc = await docsApi.get(id);
+                if (!alive) return;
+                await openShare({doc, kit, life: panelLife, onChange: () => { if (alive) load(); }, sections: forKind(shareSections, doc), suggestions: Boolean(site.suggestions)});
+            } catch (err) {
+                E.toast(err.message || 'Could not open sharing', {type: 'error'});
+            }
+        }
+
+        const fetchDoc = (id) => () => docsApi.get(id);
+
+        function moveItems(id) {
+            const r = rowById(id);
+            const here = r?.folderId || null;
+            return [{id: null, name: 'My documents (no folder)', depth: 0}, ...folderManager.rows().filter(f => f.id !== null)].map(f => ({
+                label: `${'  '.repeat(f.depth)}${f.name}`,
+                icon: f.id === null ? 'folder-open' : 'folder',
+                disabled: f.id === here,
+                action: () => move(id, f.id)
+            }));
+        }
+
+        /** Everything you can do to one document from Home. */
+        function docMenu(id) {
+            const r = rowById(id);
+            if (!r) return [];
+            if (r.trashedAt) {
+                return [
+                    {header: r.title || 'Untitled'},
+                    {label: 'Open (read only)', icon: 'eye', action: () => open(id)},
+                    {label: 'Restore', icon: 'rotate-ccw', action: () => restore(id)},
+                    {type: 'divider'},
+                    {label: 'Delete for good…', icon: 'trash', danger: true, action: () => purge(id)}
+                ];
+            }
+            const owner = r.access === 'owner';
+            const editor = owner || r.access === 'editor';
+            const items = [
+                {header: r.title || 'Untitled'},
+                {label: 'Open', icon: 'edit', action: () => open(id)},
+                {label: 'Open in a new tab', icon: 'external-link', action: () => window.open(`${location.pathname}${docHref(id)}`, '_blank', 'noopener')},
+                {label: r.starred ? 'Remove star' : 'Star', icon: 'star', action: () => toggleStar(id)},
+                {type: 'divider'}
+            ];
+            if (owner) items.push({label: 'Rename…', icon: 'edit-3', action: () => rename(id)});
+            items.push({label: 'Make a copy', icon: 'copy', action: () => copy(id)});
+            if (owner) items.push({label: 'Move to', icon: 'folder', submenu: moveItems(id)});
+            if (editor && (owner || r.outward !== false)) items.push({label: 'Share…', icon: 'user-plus', action: () => share(id)});
+            items.push({label: 'Download', icon: 'download', submenu: r.format === 'pdf' ? pdfExportItems(fetchDoc(id)) : exportItems(fetchDoc(id))});
+            if (editor && site.allowSend !== false && r.outward !== false) {
+                items.push({label: 'Email…', icon: 'mail', action: async () => {
+                    try {
+                        const doc = await docsApi.get(id);
+                        if (alive) openSendEmail({doc, kit, life: panelLife, publicLinksAllowed: site.publicLinks !== false});
+                    } catch (err) { E.toast(err.message || 'Could not open the document', {type: 'error'}); }
+                }});
+            }
+            for (const fn of forKind(extMenus, r)) {
+                try { const extra = fn({row: r, view: 'home'}); if (Array.isArray(extra) && extra.length) items.push({type: 'divider'}, ...extra); } catch { /* an add-on's problem */ }
+            }
+            if (owner) items.push({type: 'divider'}, {label: 'Move to Trash', icon: 'trash', danger: true, action: () => trash(id)});
+            return items;
+        }
+
+        async function useTemplate(id) {
+            const t = templates.peek().find(x => x.id === id);
+            if (!t) return;
+            // A template with {{fields}}: tell the editor (and so Docs Pro) to offer filling them in (2.4).
+            if (/\{\{[^{}]{1,80}\}\}/.test(t.content || '')) { try { sessionStorage.setItem('docs:fill-next', '1'); } catch { /* fine */ } }
+            await createDoc(t.content || '', t.name || 'Untitled');
+        }
+
+        async function deleteTemplate(id) {
+            const t = templates.peek().find(x => x.id === id);
+            const ok = await E.confirm(`Delete the template <strong>${esc(t?.name || '')}</strong>? Documents made from it are not affected.`, {title: 'Delete template', confirmText: 'Delete'});
+            if (!ok || !alive) return;
+            try {
+                await api(`/templates/${encodeURIComponent(id)}`, 'DELETE');
+                if (alive) templates.value = templates.peek().filter(x => x.id !== id);
+            } catch (err) {
+                E.toast(err.message || 'Could not delete the template', {type: 'error'});
+            }
+        }
+
+        async function pickTemplate() {
+            go('templates');
+        }
+
+        // ------------------------------------------------------- extensions
+
+        // Each add-on's menu items and share sections carry the kinds of document it understands (2.13):
+        // an add-on written before PDF documents sees HTML ones only.
+        const extMenus = [];
+        const shareSections = [];
+        let installing = null;
+        const tag = (fn) => { fn.kinds = installing?.kinds?.length ? installing.kinds : ['html']; return fn; };
+        const forKind = (list, doc) => list.filter(fn => (fn.kinds || ['html']).includes(doc?.format === 'pdf' ? 'pdf' : 'html'));
+        const host = {
+            view: 'home', api: docsApi, kit, esc, icon,
+            open, reload: () => load(),
+            addDocMenu(fn) { if (typeof fn === 'function') extMenus.push(tag(fn)); },
+            addShareSection(fn) { if (typeof fn === 'function') shareSections.push(tag(fn)); },
+            /** More file types for New > Import and drag-and-drop (2.4). */
+            addImporter(imp) {
+                if (!imp || !Array.isArray(imp.ext) || typeof imp.import !== 'function') return;
+                importers.push(imp);
+                const input = root.querySelector('.docs-import-input');
+                if (input) input.accept = [input.accept, ...imp.ext, imp.accept].filter(Boolean).join(',');
+            },
+            /** Keep more data-* attributes through the admin's sanitiser (2.4) - e.g. comment anchors. */
+            allowAttrs: (list) => allowDocAttrs(list),
+            /** Filter the body on its way out - downloads, print, Send to (2.5). */
+            setContentFilter: (key, fn) => setContentFilter(key, fn),
+            suggestions: Boolean(site.suggestions),
+            addPlace(place) {
+                if (!place || !/^[a-z0-9-]{1,40}$/.test(place.key) || typeof place.render !== 'function') return;
+                extPlaces.push(place);
+                const btn = document.createElement('button');
+                btn.type = 'button';
+                btn.className = 'docs-place';
+                btn.dataset.place = `ext:${place.key}`;
+                btn.innerHTML = `${icon(place.icon || 'file-text', 16)}<span class="docs-rail__label"></span>`;
+                btn.querySelector('.docs-rail__label').textContent = place.label || place.key;
+                root.querySelector('.docs-rail__ext').appendChild(btn);
+                lifetime.add(M.effect(() => btn.classList.toggle('is-active', view.value === `ext:${place.key}`)));
+            }
+        };
+        for (const ext of extensions) {
+            installing = ext;
+            try { await ext.mod.install?.(host); } catch (err) { console.warn('[docs] add-on install failed', ext.owner, err); }
+            installing = null;
+            if (!alive) return;
+        }
+
+        // ---------------------------------------------------------- bindings
+
+        root.querySelector('.docs-cards:not(.docs-cards--templates)').innerHTML = cardTemplate();
+        root.querySelector('.docs-cards--templates').innerHTML = templateTemplate();
+        root.querySelector('.docs-rail__folders').innerHTML = folderTemplate();
+        // Help first, while every marker is still in the document.
+        lifetime.add(kit.helpPopovers(root, {position: 'bottom'}));
+
+        const newBtn = root.querySelector('.docs-rail__new');
+        const fileInput = root.querySelector('.docs-import-input');
+        const cards = root.querySelector('.docs-cards:not(.docs-cards--templates)');
+        const templateCards = root.querySelector('.docs-cards--templates');
+        const folderPane = root.querySelector('.docs-rail__folders');
+        const body = root.querySelector('.docs-main__body');
+        const search = root.querySelector('.docs-main__search input');
+
+        // New lives in the banner (the screen's actions go there); its menu is bound to that button.
+        // Without the chrome (an old core) the rail keeps its own New button.
+        const bannerNew = kit.addBannerAction($container, {id: 'docs-new', icon: 'plus', title: 'New - a blank document, a template, an import or a folder', onClick: () => kit.openMenuAt(bannerNew)});
+        const bannerImport = kit.addBannerAction($container, {id: 'docs-import', icon: 'upload', title: 'Import or upload files - .md, .html, .txt, .pdf (or drop them on the list)', onClick: () => fileInput.click()});
+        if (bannerNew) newBtn.hidden = true;
+        const newTarget = bannerNew || newBtn;
+
+        const bindings = M.applyBindings(data, root, {
+            methods: {
+                openNewMenu: () => kit.openMenuAt(newTarget),
+                newDoc: () => createDoc(),
+                newFolder: () => folderManager.createFolder(null),
+                toggleRail: () => { railCollapsed.value = !railCollapsed.peek(); },
+                gridLayout: () => { layout.value = 'grid'; },
+                listLayout: () => { layout.value = 'list'; },
+                emptyTrash
+            }
+        });
+        lifetime.add(() => bindings.dispose());
+
+        const menus = [
+            E.contextMenu(newTarget, {
+                cursor: 'glyph', inherit: false, density: 'compact',
+                items: () => [
+                    {header: 'New'},
+                    {label: 'Blank document', icon: 'file-text', action: () => createDoc()},
+                    {label: 'From a template…', icon: 'layout', action: pickTemplate},
+                    {label: 'Import a file…', icon: 'upload', action: () => fileInput.click()},
+                    {label: 'Upload a PDF…', icon: 'file', action: () => fileInput.click()},
+                    {type: 'divider'},
+                    {label: 'New folder…', icon: 'folder-plus', action: () => folderManager.createFolder(view.peek() === 'mine' ? folderId.peek() : null)}
+                ]
+            }),
+            E.contextMenu(cards, {cursor: 'glyph', match: '.docs-card', inherit: false, density: 'compact', items: (el) => docMenu(el.dataset.doc)}),
+            E.contextMenu(templateCards, {
+                cursor: 'glyph', match: '.docs-card', inherit: false, density: 'compact',
+                items: (el) => {
+                    const t = templates.peek().find(x => x.id === el.dataset.template);
+                    const items = [{header: t?.name || 'Template'}, {label: 'New document from this', icon: 'plus', action: () => useTemplate(el.dataset.template)}];
+                    // Ready-made templates (from an add-on) are read only.
+                    if (t && !t.builtIn) items.push({type: 'divider'}, {label: 'Delete template…', icon: 'trash', danger: true, action: () => deleteTemplate(el.dataset.template)});
+                    return items;
+                }
+            }),
+            E.contextMenu(folderPane, {
+                cursor: 'glyph', match: '.docs-folder', inherit: false, density: 'compact',
+                items: (el) => {
+                    const f = folderManager.byId(el.dataset.folder);
+                    if (!f) return [];
+                    return [
+                        {header: f.name},
+                        {label: 'Open', icon: 'folder-open', action: () => go('mine', f.id)},
+                        {label: 'New subfolder…', icon: 'folder-plus', action: () => folderManager.createFolder(f.id)},
+                        {label: 'Rename…', icon: 'edit-3', action: () => folderManager.renameFolder(f)},
+                        {type: 'divider'},
+                        {label: 'Delete folder…', icon: 'trash', danger: true, action: () => folderManager.deleteFolder(f)}
+                    ];
+                }
+            })
+        ];
+        lifetime.add(() => menus.forEach(m => m?.destroy?.()));
+        lifetime.add(() => { bannerNew?.remove(); bannerImport?.remove(); });
+
+        root.querySelector('.docs-rail__places').addEventListener('click', (e) => {
+            const b = e.target.closest('[data-place]');
+            if (b) go(b.dataset.place);
+        });
+        cards.addEventListener('click', (e) => {
+            const card = e.target.closest('.docs-card');
+            if (!card) return;
+            if (e.target.closest('.docs-kebab')) return kit.openMenuAt(e.target.closest('.docs-kebab'));
+            if (e.target.closest('[data-star]')) return toggleStar(card.dataset.doc);
+            open(card.dataset.doc);
+        });
+        templateCards.addEventListener('click', (e) => {
+            const card = e.target.closest('.docs-card');
+            if (!card) return;
+            if (e.target.closest('.docs-kebab')) return kit.openMenuAt(e.target.closest('.docs-kebab'));
+            useTemplate(card.dataset.template);
+        });
+        folderPane.addEventListener('click', (e) => {
+            const row = e.target.closest('.docs-folder');
+            if (!row) return;
+            if (e.target.closest('.docs-kebab')) return kit.openMenuAt(e.target.closest('.docs-kebab'));
+            folderManager.select(row.dataset.folder);
+        });
+        for (const pane of [cards, templateCards, folderPane]) {
+            pane.addEventListener('keydown', (e) => {
+                if (!e.target.matches('.docs-card, .docs-folder')) return;
+                if (e.key === 'Enter' || e.key === ' ') {
+                    e.preventDefault();
+                    e.target.click();
+                } else if (e.key === 'F10' && e.shiftKey) {
+                    // The item's menu, as a right-click or its ⋮ opens it.
+                    e.preventDefault();
+                    kit.openMenuAt(e.target);
+                }
+            });
+        }
+
+        // Import: the file picker, or files dropped anywhere on the list.
+        fileInput.addEventListener('change', () => { importFiles(fileInput.files); fileInput.value = ''; });
+        let dragDepth = 0;
+        const hasFiles = (e) => [...(e.dataTransfer?.types || [])].includes('Files');
+        body.addEventListener('dragenter', (e) => { if (!hasFiles(e)) return; e.preventDefault(); dragDepth++; dragging.value = true; });
+        body.addEventListener('dragover', (e) => { if (hasFiles(e)) e.preventDefault(); });
+        body.addEventListener('dragleave', () => { dragDepth = Math.max(0, dragDepth - 1); if (!dragDepth) dragging.value = false; });
+        body.addEventListener('drop', (e) => {
+            if (!hasFiles(e)) return;
+            e.preventDefault();
+            dragDepth = 0;
+            dragging.value = false;
+            importFiles(e.dataTransfer.files);
+        });
+
+        // "/" jumps to search, as in most document lists.
+        const onKey = (e) => {
+            if (e.key !== '/' || e.ctrlKey || e.metaKey || e.altKey) return;
+            if (e.target.closest?.('input, textarea, select, [contenteditable="true"]')) return;
+            e.preventDefault();
+            search?.focus();
+        };
+        document.addEventListener('keydown', onKey);
+        lifetime.add(() => document.removeEventListener('keydown', onKey));
+
+        // Settings: the banner cog.
+        const cog = kit.addBannerAction($container, {id: 'docs-settings', icon: 'settings', title: 'Docs settings',
+            onClick: () => openSettings({kit, site, life: panelLife, prefs: {showWordCount}, onSaved: (next) => { Object.assign(site, next); }})});
+        if (!cog) {
+            const btn = document.createElement('button');
+            btn.type = 'button';
+            btn.className = 'btn btn-sm btn-ghost';
+            btn.title = 'Docs settings';
+            btn.setAttribute('aria-label', 'Docs settings');
+            btn.innerHTML = icon('settings', 16);
+            btn.addEventListener('click', () => openSettings({kit, site, life: panelLife, prefs: {showWordCount}, onSaved: (next) => Object.assign(site, next)}));
+            root.querySelector('.docs-main__bar')?.appendChild(btn);
+        }
+
+        Domma.icons.scan(root);
+
+        // ---- First load ----
+        await folderManager.load();
+        if (!alive) return;
+        if (folderId.peek() && !folderManager.byId(folderId.peek())) folderId.value = null;
+        if (view.peek().startsWith('ext:') && !extPlaces.some(p => `ext:${p.key}` === view.peek())) view.value = 'recent';
+        go(view.peek(), folderId.peek());
+        countsReady = true;
+        loadCounts();
+    }
+};
+
+export {HOME};