kempo-media 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,10 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+
+### Added
+
+- **Dashboard widget.** A **Media** widget on the kempo admin dashboard showing the asset count and the latest uploads, with a **Upload media** button, declared in `widgets` in `kempo-config.json`. Needs a kempo with the dashboard; ignored on older versions.
 ### Changed
  - **Media now sits on kempo-files, with thumbnails from kempo-thumbs.** Before, this extension kept its own copy of everything: uploads in the site's `public/media/uploads/` (static serving, no permissions), and `sharp` thumbnails in `public/media/thumbnails/`, parallel to kempo-files' permission-checked library and kempo-thumbs' ffmpeg thumbnails. Anything consuming images had to handle both stacks. Now an asset is a kempo-files file plus a `kempoMediaAsset` row (kind, dimensions, alt text, display name), the **asset id is the file id** (no mapping table), the bytes live in kempo-files' `files/media/` folder, and a thumbnail is whatever kempo-thumbs made. One storage layer, one set of file permissions, one thumbnail path.
  - `kempo-config.json` declares `"dependencies": ["kempo-files", "kempo-thumbs"]`; kempo will not install this extension until both are enabled. kempo-thumbs is required rather than optional so every consumer can rely on `thumbnail` meaning the same thing. Requires `kempo-files` >= 0.1.5, which adds `uploadFile`, caller-chosen ids and download caching.

package/README.md

@@ -158,3 +158,7 @@ npm test
 - **Only assets uploaded through this library are in it.** Other files in kempo-files do not appear in the media grid unless registered with `createMediaAsset`.
 - **A replaced public file can be cached for up to an hour** by browsers (kempo-files' cache lifetime).
 - **No usage tracking.** Deleting an asset does not check whether a page links to it.
+
+## Dashboard widget
+
+Adds a **Media** widget to the kempo admin dashboard showing the asset count and the latest uploads, with a **Upload media** button. It is declared in `widgets` in `kempo-config.json` and registered when the extension is installed or updated; people only see it if they hold its permission, and can hide, reorder or resize it from the dashboard's Customize dialog. Needs a kempo with the dashboard (see kempo's `docs/dashboard.md`); on an older kempo the entry is ignored.

package/admin/nav.global.html

@@ -1,3 +1,3 @@
-<content id="kempo-media-nav" name="Media" owner="kempo-media" enabled="true" locked="true" location="admin-nav-extensions" priority="0">
-<k-aside-item icon="image" group="Media" group-icon="image" href="/admin/extension/kempo-media/" no-expand>Media</k-aside-item>
+<content id="kempo-media-nav" name="Media" owner="kempo-media" enabled="true" locked="true" location="admin-nav-extensions" priority="45">
+<k-aside-item icon="image" group="Files" href="/admin/extension/kempo-media/" no-expand>Media</k-aside-item>
 </content>

package/kempo-config.json

@@ -3,6 +3,22 @@
   "public-scope": "kempo-media",
   "schema": "./server/db/schema.js",
   "dependencies": ["kempo-files", "kempo-thumbs"],
+  "widgets": [
+    {
+      "key": "library",
+      "title": "Media",
+      "description": "How many media assets there are and the latest uploads.",
+      "icon": "image",
+      "element": "k-media-widget",
+      "module": "/kempo-media/components/MediaWidget.js",
+      "defaultWidth": 2,
+      "defaultHeight": 2,
+      "minWidth": 1,
+      "minHeight": 2,
+      "permission": "media:browse",
+      "priority": 73
+    }
+  ],
   "permissions": [
     { "name": "media:browse", "description": "List and view media library assets" },
     { "name": "media:upload", "description": "Upload new media assets" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-media",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Media library extension for kempo — upload and manage images, video, audio, 3D models, and archives, stored in kempo-files with thumbnails from kempo-thumbs",
   "license": "MIT",
   "author": "Dustin Poissant",

package/public/components/MediaWidget.js

@@ -0,0 +1,50 @@
+import DashboardWidget from '/kempo/components/DashboardWidget.js';
+import { html, nothing } from '/kempo-ui/lit-all.min.js';
+import { getMediaAssets } from '/kempo-media/sdk.js';
+
+/*
+  The size of the media library and the most recent uploads.
+*/
+export default class MediaWidget extends DashboardWidget {
+  static properties = {
+    ...DashboardWidget.properties,
+    total: { state: true },
+    recent: { state: true }
+  };
+
+  constructor(){
+    super();
+    this.total = 0;
+    this.recent = [];
+    this.cta = { label: 'Upload media', icon: 'upload', href: '/admin/extension/kempo-media/', permission: 'media:upload' };
+  }
+
+  /*
+    Public Methods
+  */
+
+  load = async () => {
+    const { assets, total } = await this.unwrap(getMediaAssets({ limit: 9 }));
+    this.total = total;
+    this.recent = assets;
+  };
+
+  /*
+    Rendering
+  */
+
+  renderContent(){
+    if(!this.total) return html`<p class="tc-muted">No media yet.</p>`;
+    const rows = this.recent.slice(0, this.height * 3);
+    return html`
+      <div class="h2 m0">${this.total}</div>
+      <div class="small tc-muted mb">${this.total === 1 ? 'Asset' : 'Assets'}</div>
+      ${rows.length ? html`<div class="small tc-muted mbq">Latest</div>` : nothing}
+      ${rows.map(asset => html`
+        <div class="d-f pyq bb"><span class="flex">${asset.originalName || asset.name || asset.id}</span><span class="small tc-muted">${asset.kind}</span></div>
+      `)}
+    `;
+  }
+}
+
+customElements.define('k-media-widget', MediaWidget);

package/tests/dashboard-widget.node-test.js

@@ -0,0 +1,85 @@
+import path from 'path';
+import { existsSync } from 'fs';
+import { readFile } from 'fs/promises';
+import { fileURLToPath, pathToFileURL } from 'url';
+
+/*
+  This extension adds widgets to the kempo admin dashboard through `widgets` in kempo-config.json. Core
+  refuses a definition it could not render (and the extension would fail to install), and a module path
+  that points at nothing only shows up as a broken tile, so both are checked here.
+
+  The rules are checked inline so this works against any installed kempo, including one released before
+  the dashboard existed. When the installed kempo does have the dashboard, its own validation also runs.
+*/
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const config = JSON.parse(await readFile(path.join(root, 'kempo-config.json'), 'utf8'));
+const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+const core = await import(pathToFileURL(path.join(root, 'node_modules', 'kempo', 'server', 'utils', 'dashboard', 'helpers.js')).href).catch(() => null);
+
+const scope = `/${pkg.kempo?.['public-scope'] || config['public-scope']}/`;
+const permissions = new Set((config.permissions || []).map(p => p.name));
+
+const ELEMENT = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
+const KEY = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
+const LOCAL_PATH = /^\/(?![/\\])[^\\\s\u0000-\u001f\u007f]*$/;
+const blocks = (value, max) => Number.isInteger(value) && value >= 1 && value <= max;
+
+const problems = widget => {
+  const { key, title, element, module, defaultWidth = 2, defaultHeight = 1, minWidth = 1, maxWidth = 4, minHeight = 1, maxHeight = 3, actions = [] } = widget;
+  const found = [];
+  if(typeof key !== 'string' || !KEY.test(key)) found.push('key must be letters, numbers, ".", "_" or "-"');
+  if(typeof title !== 'string' || !title.trim() || title.length > 100) found.push('title is required, at most 100 characters');
+  if(typeof element !== 'string' || !ELEMENT.test(element)) found.push('element must be a custom element name such as "my-ext-widget"');
+  if(typeof module !== 'string' || !LOCAL_PATH.test(module)) found.push('module must be a path on this site beginning with a single "/"');
+  if(!blocks(minWidth, 4) || !blocks(maxWidth, 4) || minWidth > maxWidth) found.push('minWidth and maxWidth must be 1 to 4, min no greater than max');
+  if(!blocks(minHeight, 3) || !blocks(maxHeight, 3) || minHeight > maxHeight) found.push('minHeight and maxHeight must be 1 to 3, min no greater than max');
+  if(!Number.isInteger(defaultWidth) || defaultWidth < minWidth || defaultWidth > maxWidth) found.push('defaultWidth must be within the width bounds');
+  if(!Number.isInteger(defaultHeight) || defaultHeight < minHeight || defaultHeight > maxHeight) found.push('defaultHeight must be within the height bounds');
+  if(!Array.isArray(actions) || actions.length > 3 || actions.some(action => !action?.label || !LOCAL_PATH.test(action?.href))) found.push('actions must be at most 3 { label, href } with a site path');
+  return found;
+};
+
+export default {
+  'kempo-config.json declares at least one widget': async ({ pass, fail }) => {
+    if(!Array.isArray(config.widgets) || !config.widgets.length) return fail('no widgets declared');
+    pass(`${config.widgets.length} widget(s)`);
+  },
+
+  'every declared widget is a definition the dashboard can render': async ({ pass, fail }) => {
+    for(const widget of config.widgets){
+      const found = problems(widget);
+      if(found.length) return fail(`${widget.key}: ${found.join('; ')}`);
+      if(core){
+        const [error] = core.normalizeWidget({ ...widget, owner: pkg.name });
+        if(error) return fail(`${widget.key}: kempo core refuses it: ${error.msg}`);
+      }
+    }
+    pass(core ? 'checked inline and by kempo core' : 'checked inline');
+  },
+
+  'every widget module is served from the public scope and exists': async ({ pass, fail }) => {
+    for(const { key, module } of config.widgets){
+      if(!module.startsWith(scope)) return fail(`${key}: ${module} is outside ${scope}`);
+      if(!existsSync(path.join(root, 'public', module.slice(scope.length)))) return fail(`${key}: ${module} does not exist under public/`);
+    }
+    pass();
+  },
+
+  'a widget permission is one the extension declares, or from core or a dependency when it declares none': async ({ pass, fail }) => {
+    for(const { key, permission } of config.widgets){
+      if(permission && permissions.size && !permissions.has(permission) && !permission.startsWith('system:')){
+        return fail(`${key}: permission "${permission}" is not declared by this extension`);
+      }
+    }
+    pass();
+  },
+
+  'every widget module defines the element it is registered with': async ({ pass, fail }) => {
+    for(const { key, module, element } of config.widgets){
+      const source = await readFile(path.join(root, 'public', module.slice(scope.length)), 'utf8');
+      if(!source.includes(`customElements.define('${element}'`)) return fail(`${key}: ${module} never defines <${element}>`);
+    }
+    pass();
+  },
+};