domma-cms 1.0.0 → 1.2.0

package/server/services/plugins.js

@@ -38,6 +38,7 @@ import {registerThemeProvider} from './themeSettings.js';
 import {classifyEntitlement, mayLoad} from './pluginEntitlement.js';
 import {notifierFor} from './notify.js';
 import {disableInstantCalls, enableInstantCalls, grantInstantCallsOnce} from './instantCalls.js';
+import {disableDashboardPro, enableDashboardPro, registerWidget, unregisterWidgetsFrom} from './widgets.js';
 import {createCollection, getCollection} from './collections.js';
 import * as defaultRolesService from './roles.js';
 import {getAdminScope, normaliseAdminScope} from './roles.js';
@@ -560,6 +561,10 @@ export async function registerPlugins(fastify) {
                   // them on at boot. Bound to the plugin's name, tier and closedSource: only a paid plugin that
                   // loads under a licence may.
                   enableInstantCalls: () => enableInstantCalls({owner: manifest.name, tier: manifest.tier || 'free', closedSource: manifest.closedSource === true}),
+                  // Dashboard Pro (services/widgets.js) - the widget board; the same contract as instant calls.
+                  enableDashboardPro: () => enableDashboardPro({owner: manifest.name, tier: manifest.tier || 'free', closedSource: manifest.closedSource === true}),
+                  // A widget from code (anything richer than a manifest's admin.widgets entry), owned by this plugin.
+                  registerWidget: (def) => registerWidget({...def, owner: manifest.name, source: manifest.displayName || manifest.name}),
                   // Who may read a contact that is not their own (Contacts Pro's sharing) - hooks.js 7b.
                   registerContactAccess: (fn) => registerContactAccess(manifest.name, fn),
                   // Direct messages between team members (Messages) - hooks.js 7c; a call's "Add people" uses it.
@@ -594,6 +599,14 @@ export async function registerPlugins(fastify) {
                 }
             }
 
+            // Dashboard widgets the manifest offers (services/widgets.js) - drawn by the admin
+            // from their `kind` and `dataUrl`, so a Tool needs no code to have one.
+            for (const def of manifest.admin?.widgets || []) {
+                if (!registerWidget({...def, owner: manifest.name, source: manifest.displayName || manifest.name})) {
+                    fastify.log.warn(`[plugins] widget "${def?.id}" for "${manifest.name}" skipped: not a valid widget`);
+                }
+            }
+
             // Ensure plugin collections exist (idempotent - skips if already present)
             await setupPlugin(manifest.name, {collections: {getCollection, createCollection}})
                 .catch(err => fastify.log.warn(`[plugins] Collection setup for "${manifest.name}" failed: ${err.message}`));
@@ -1123,6 +1136,8 @@ export async function runLifecycleHook(name, hook, fastify) {
     // A Tool with calls switched off stops keeping instant calls on - at once, not at the next restart.
     if (hook === 'onDisable') {
         disableInstantCalls(name);
+        disableDashboardPro(name);
+        unregisterWidgetsFrom(name);
         unregisterContactAccess(name);
         unregisterDirectMessenger(name);
     }

package/server/services/renderer.js

@@ -16,6 +16,7 @@ import {buildCustomThemeStyleTag, buildOverrideStyleTag, getThemeTokenMap, listT
 import {getSearchSettings} from './search.js';
 import {isToolEnabled} from './tools.js';
 import {fmtDateTime} from './dates.js';
+import {cssClasses} from '../../public/js/css-classes.mjs';
 
 const VALID_LAYOUT_WIDTHS = new Set(['narrow', 'normal', 'wide', 'full']);
 const CUSTOM_CSS_PATH = new URL('../../content/custom.css', import.meta.url).pathname;
@@ -285,7 +286,8 @@ export async function renderPage(page, opts = {}) {
     const navbarClass = (navigation.orientation === 'vertical' && navigation.position !== 'floating')
         ? `dm-nav-vertical dm-nav-vertical-${navigation.side === 'right' ? 'right' : 'left'}`
         : '';
-    const layoutBodyClass = ['dm-layout-' + layoutWidth, preset.class || '', verticalNavClass].filter(Boolean).join(' ');
+    // Site Settings > Appearance > Body CSS classes - the designer's own, on every page.
+    const layoutBodyClass = ['dm-layout-' + layoutWidth, preset.class || '', verticalNavClass, ...cssClasses(site.bodyClass)].filter(Boolean).join(' ');
     const pageBodyStyleParts = [];
     const BG_COLOR_SAFE = /^[a-zA-Z0-9#(),.\s%/-]+$/;
     if (preset.bgColor && BG_COLOR_SAFE.test(preset.bgColor)) pageBodyStyleParts.push(`background-color:${preset.bgColor}`);
@@ -365,7 +367,7 @@ export async function renderPage(page, opts = {}) {
         ? `window.__CMS_CTXMENUS__ = ${JSON.stringify(ctxMenus).replace(/<\/script>/gi, '<\\/script>')};`
         : '';
     const ctxMenusModule = ctxMenus.length
-        ? '<script src="/public/js/context-menus.js?v=20260918-ctx" type="module"></script>'
+        ? '<script src="/public/js/context-menus.js?v=20261009-classes" type="module"></script>'
         : '';
 
     const vars = {
@@ -1079,7 +1081,7 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
         ? `window.__CMS_CTXMENUS__ = ${JSON.stringify(ctxMenus).replace(/<\/script>/gi, '<\\/script>')};`
         : '';
     const ctxMenusModule = ctxMenus.length
-        ? '<script src="/public/js/context-menus.js?v=20260918-ctx" type="module"></script>'
+        ? '<script src="/public/js/context-menus.js?v=20261009-classes" type="module"></script>'
         : '';
 
     const vars = {
@@ -1098,7 +1100,7 @@ export async function renderBlogPage(templatePath, data = {}, seoMeta = {}) {
         layout: 'default',
         layoutBodyClass: ['dm-layout-normal', navigation.orientation === 'vertical'
             ? `dm-vnav dm-vnav-${navigation.side === 'right' ? 'right' : 'left'}`
-            : ''].filter(Boolean).join(' '),
+            : '', ...cssClasses(site.bodyClass)].filter(Boolean).join(' '),
         pageBodyStyle: '',
         showNavbar: true,
         showFooter: true,

package/server/services/siteGitignore.js

@@ -317,6 +317,8 @@ export function buildGitignore({sitePlugins = [], pluginContent = {}, sitePublic
         '/content/.migrations.json',
         '/content/instances_log.json',
         '/content/preview-links.json',
+        // Each admin's own Dashboard Pro layout (keyed by user id); the site default beside it is tracked.
+        '/content/dashboard/layouts/',
         '/config/connections.json*',
         '/config/keys/',
         '/plugins/*/data/*.jsonl',

package/server/services/widgets.js

@@ -0,0 +1,269 @@
+/**
+ * Dashboard widgets - the parts a Tool offers for the Dashboard, and the Pro
+ * switch for the board that arranges them.
+ *
+ * A widget is a small, self-describing card. It never ships code: it names a
+ * `kind` the admin knows how to draw and a `dataUrl` that answers in that
+ * kind's shape, so a Tool adds a widget with a few lines of manifest and
+ * every widget looks like part of the same admin.
+ *
+ *   kind      dataUrl answers                                   drawn as
+ *   ------    -----------------------------------------------   -------------------------
+ *   count     {count, label, tone, details}  (a sidebar badge)   big number + its details list
+ *   stat      {value, label, sub, tone}                          big value + a line under it
+ *   list      {items: [{text, meta, href, value, tone}], empty}   rows that open on click
+ *   chart     {labels: [], values: [], label}                    a line chart
+ *
+ * Three sources, merged by getWidgets():
+ *
+ *   1. Core's own (CORE_WIDGETS) - traffic, needs attention, recent activity,
+ *      health, visitors now - read from /api/dashboard/widget/<name>.
+ *   2. Every sidebar entry with a `countUrl` - a Tool that has a badge has a
+ *      widget, for free, in the badge's own shape (`count`). This is how
+ *      Email, Booking, Support and the rest arrive on day one.
+ *   3. A plugin's `admin.widgets[]` in plugin.json (bridged in plugins.js),
+ *      or registerWidget() from code - for anything richer than a badge.
+ *
+ * PRO ONLY: the board (add, arrange, resize, a layout per user) exists only
+ * while a paid, closed-source Tool has called `hooks.enableDashboardPro()` -
+ * the same contract as instant calls (services/instantCalls.js). Without it
+ * the widget and layout routes answer 404 and `#/` is the fixed Dashboard.
+ *
+ * @module services/widgets
+ */
+
+import {getRegisteredSidebarItems, registerSidebarItem} from './hooks.js';
+
+/** Widths on the board's four-column grid. */
+export const WIDGET_SIZES = ['s', 'm', 'l', 'xl'];
+export const WIDGET_KINDS = ['count', 'stat', 'list', 'chart'];
+
+const ID_RE = /^[a-z0-9][a-z0-9:._/-]{0,119}$/;
+const DATA_URL_RE = /^\/api\/[A-Za-z0-9/_.:?=&%-]+$/;
+
+/** Core's own widgets - the fixed Dashboard's parts, one card each. */
+export const CORE_WIDGETS = [
+    {id: 'core:traffic', title: 'Traffic', description: 'Page views over the last 30 days.', icon: 'activity',
+        kind: 'chart', size: 'xl', dataUrl: '/api/dashboard/widget/traffic', href: '#/analytics', admin: true, refresh: 300},
+    {id: 'core:visitors', title: 'Visitors now', description: 'People on the site in the last five minutes, and page views today.',
+        icon: 'users', kind: 'stat', size: 's', dataUrl: '/api/dashboard/widget/visitors', href: '#/analytics', admin: true, refresh: 30},
+    {id: 'core:attention', title: 'Needs attention', description: 'Anything late, failing or waiting on you, across every Tool you can open.',
+        icon: 'alert-circle', kind: 'list', size: 'm', dataUrl: '/api/dashboard/widget/attention', refresh: 60},
+    {id: 'core:activity', title: 'Recent activity', description: 'What changed on the site lately, and who changed it.',
+        icon: 'clock', kind: 'list', size: 'm', dataUrl: '/api/dashboard/widget/activity', admin: true, refresh: 120},
+    {id: 'core:health', title: 'Site health', description: 'The health checks - storage, email, backups and the rest.',
+        icon: 'heart', kind: 'list', size: 'm', dataUrl: '/api/dashboard/widget/health', admin: true, refresh: 300},
+    {id: 'core:top-pages', title: 'Top pages', description: 'The most visited pages today.',
+        icon: 'trending-up', kind: 'list', size: 'm', dataUrl: '/api/dashboard/widget/top-pages', href: '#/analytics', admin: true, refresh: 300}
+];
+
+/** What a new board starts with when the site has set no default. */
+export const DEFAULT_LAYOUT = [
+    {id: 'core:attention', size: 'm'},
+    {id: 'core:visitors', size: 's'},
+    {id: 'core:traffic', size: 'xl'},
+    {id: 'core:activity', size: 'm'},
+    {id: 'core:top-pages', size: 'm'}
+];
+
+const _registered = [];
+
+/**
+ * Normalise a widget definition; null when it cannot be drawn.
+ *
+ * @param {object} def
+ * @param {string} [source] - who offers it ('Built in', a plugin's name)
+ * @returns {object|null}
+ */
+export function normaliseWidget(def, source = '') {
+    if (!def || typeof def !== 'object') return null;
+    const id = String(def.id || '').trim();
+    if (!ID_RE.test(id)) return null;
+    if (!WIDGET_KINDS.includes(def.kind)) return null;
+    if (typeof def.dataUrl !== 'string' || !DATA_URL_RE.test(def.dataUrl)) return null;
+    const href = typeof def.href === 'string' && /^#\//.test(def.href) ? def.href : '';
+    const refresh = Number.isFinite(Number(def.refresh)) ? Math.min(3600, Math.max(15, Number(def.refresh))) : 60;
+    return {
+        id,
+        title: String(def.title || id).slice(0, 60),
+        description: String(def.description || '').slice(0, 200),
+        icon: typeof def.icon === 'string' && /^[a-z0-9-]{1,40}$/.test(def.icon) ? def.icon : 'grid',
+        kind: def.kind,
+        size: WIDGET_SIZES.includes(def.size) ? def.size : 'm',
+        dataUrl: def.dataUrl,
+        refresh,
+        ...(href && {href}),
+        ...(typeof def.permission === 'string' && def.permission && {permission: def.permission}),
+        ...(def.admin === true && {admin: true}),
+        // Which plugin offers it, so disabling that plugin takes it away (unregisterWidgetsFrom).
+        ...(typeof def.owner === 'string' && def.owner && {owner: def.owner}),
+        source: String(def.source || source || '').slice(0, 60)
+    };
+}
+
+/**
+ * Offer a widget (core, or a plugin from code - a manifest's `admin.widgets`
+ * goes through here too). A second widget with the same id replaces the first.
+ *
+ * @param {object} def
+ * @param {string} [source]
+ * @returns {boolean} whether it was accepted
+ */
+export function registerWidget(def, source = '') {
+    const w = normaliseWidget(def, source);
+    if (!w) return false;
+    const at = _registered.findIndex(x => x.id === w.id);
+    if (at >= 0) _registered[at] = w; else _registered.push(w);
+    return true;
+}
+
+/** Take a plugin's widgets away (it was disabled). */
+export function unregisterWidgetsFrom(owner) {
+    for (let i = _registered.length - 1; i >= 0; i--) {
+        if (_registered[i].owner === owner) _registered.splice(i, 1);
+    }
+}
+
+/** A sidebar entry with a badge, as a widget in the badge's own shape. */
+export function widgetFromSidebarItem(entry) {
+    const item = entry?.item || entry;
+    if (!item || typeof item.countUrl !== 'string' || !item.url) return null;
+    return normaliseWidget({
+        id: `count:${item.url.replace(/^#\//, '') || 'home'}`,
+        title: item.text,
+        description: item.inventory ? `How many there are in ${item.text}.` : `What ${item.text} is waiting on, as its sidebar badge says.`,
+        icon: item.icon,
+        kind: 'count',
+        size: 's',
+        dataUrl: item.countUrl,
+        href: item.url,
+        permission: item.permission,
+        refresh: 60
+    }, item.source || '');
+}
+
+/**
+ * Every widget there is: core's, one per sidebar badge, then the registered
+ * ones (which win on a clash of id).
+ *
+ * @param {{sidebarItems?: object[]}} [opts] - injectable for tests
+ * @returns {object[]}
+ */
+export function getWidgets({sidebarItems = getRegisteredSidebarItems()} = {}) {
+    const byId = new Map();
+    for (const w of CORE_WIDGETS) byId.set(w.id, normaliseWidget(w, 'Built in'));
+    for (const entry of sidebarItems) {
+        const w = widgetFromSidebarItem(entry);
+        if (w) byId.set(w.id, w);
+    }
+    for (const w of _registered) byId.set(w.id, w);
+    return [...byId.values()].filter(Boolean);
+}
+
+/** canAny() from the admin, server side: the resource or any of its actions. */
+export function canAny(permissions, resource) {
+    if (!resource) return true;
+    if (!Array.isArray(permissions) || !permissions.length) return false;
+    if (permissions.includes(resource)) return true;
+    return ['read', 'create', 'update', 'delete'].some(a => permissions.includes(`${resource}.${a}`));
+}
+
+/**
+ * The widgets this user may put on their board: each one's permission, and
+ * `admin` widgets for admins only (they read the admin-only summary).
+ *
+ * @param {object[]} widgets
+ * @param {{permissions: string[], isAdmin: boolean}} who
+ */
+export function widgetsFor(widgets, {permissions = [], isAdmin = false} = {}) {
+    return widgets.filter(w => (!w.admin || isAdmin) && canAny(permissions, w.permission));
+}
+
+// ---------------------------------------------------------------------------
+// Layouts
+// ---------------------------------------------------------------------------
+
+export const MAX_WIDGETS = 40;
+
+/**
+ * A stored or submitted layout, cleaned: known sizes, no duplicates, capped.
+ * Ids are kept even when no such widget exists right now - a Tool switched off
+ * for a moment should not cost someone their arrangement - and dropped at draw.
+ *
+ * @param {*} input - {widgets: [{id, size}]} or the array itself
+ * @returns {{version: number, widgets: Array<{id: string, size: string}>}}
+ */
+export function normaliseLayout(input) {
+    const list = Array.isArray(input) ? input : (Array.isArray(input?.widgets) ? input.widgets : []);
+    const seen = new Set();
+    const widgets = [];
+    for (const w of list) {
+        const id = String(w?.id || '').trim();
+        if (!ID_RE.test(id) || seen.has(id)) continue;
+        seen.add(id);
+        // `collapsed`: folded down to its title bar on this person's board.
+        widgets.push({id, size: WIDGET_SIZES.includes(w.size) ? w.size : 'm', ...(w.collapsed === true && {collapsed: true})});
+        if (widgets.length >= MAX_WIDGETS) break;
+    }
+    return {version: 1, widgets};
+}
+
+/** What is wrong with a submitted layout, as messages ([] when it is fine). */
+export function layoutProblems(input) {
+    const list = Array.isArray(input) ? input : input?.widgets;
+    if (!Array.isArray(list)) return ['widgets must be an array'];
+    if (list.length > MAX_WIDGETS) return [`at most ${MAX_WIDGETS} widgets`];
+    const out = [];
+    list.forEach((w, i) => {
+        if (!ID_RE.test(String(w?.id || ''))) out.push(`widgets[${i}].id is not a widget id`);
+        if (w?.size != null && !WIDGET_SIZES.includes(w.size)) out.push(`widgets[${i}].size must be one of ${WIDGET_SIZES.join(', ')}`);
+    });
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Switched on by a Pro Tool
+// ---------------------------------------------------------------------------
+
+const owners = new Set();
+let sidebarRegistered = false;
+
+/**
+ * A Pro Tool switches the board on (plugins.js hands it to each plugin as
+ * `hooks.enableDashboardPro`, bound to the plugin's name, tier and closedSource).
+ * Only a paid, closed-source plugin - one that loads only under a licence - may.
+ *
+ * @param {{owner: string, tier: string, closedSource: boolean}} who
+ * @returns {boolean}
+ */
+export function enableDashboardPro({owner, tier, closedSource} = {}) {
+    if (typeof owner !== 'string' || !owner.trim()) return false;
+    if (tier !== 'paid' || closedSource !== true) return false;
+    // The board's own address in the sidebar (Overview), once: `#/` can belong to
+    // another Tool (the fleet manager's Dashboard), and My Dashboard still reaches it.
+    if (!sidebarRegistered) {
+        sidebarRegistered = true;
+        try {
+            registerSidebarItem({folder: 'overview', item: {source: 'Dashboard Pro', text: 'My Dashboard', url: '#/my-dashboard', icon: 'layout'}});
+        } catch { /* a sidebar without folders still has the route */ }
+    }
+    owners.add(owner.trim());
+    return true;
+}
+
+/** The Tool that kept it on was disabled; the last one gone switches the board off. */
+export function disableDashboardPro(owner) {
+    owners.delete(String(owner || '').trim());
+    return owners.size > 0;
+}
+
+/** Whether this site has Dashboard Pro right now. */
+export function isDashboardPro() {
+    return owners.size > 0;
+}
+
+/** Tests only: forget every owner and registration. */
+export function _resetWidgetsForTests() {
+    owners.clear();
+    _registered.length = 0;
+}

package/server/templates/page.html

@@ -137,7 +137,7 @@
     </script>
 
     <!-- Site initialisation -->
-    <script src="/public/js/site.js?v=20261009-hover-darken" type="module"></script>
+    <script src="/public/js/site.js?v=20261009-more-classes" type="module"></script>
     <script src="/public/js/collection-context.js?v=20260927-ctx" type="module"></script>
     {{ctxMenusModule}}