domma-cms 1.1.0 → 1.2.0

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;
+}