domma-cms 0.66.0 → 0.69.3

package/plugins/blog/blocks/blog-card.html

@@ -0,0 +1,16 @@
+<!--
+  blog-card - one post in a Blog listing (the Cards and Magazine displays).
+  Edit it here to restyle every card; copy it as blog-card-<name> to add a display.
+
+  {{title}} {{url}} {{excerpt}} {{authorName}} {{authorUrl}} {{readingTime}} {{date}}
+  {{publishedAt:D MMM YYYY}}  any date format
+  {{imageUrl}} {{imageClass}} (has-image | no-image) {{category}} (the first one)
+  {{{image}}} {{{categories}}} {{{tags}}}  ready-made markup
+-->
+<a class="bc-media {{imageClass}}" href="{{url}}" tabindex="-1" aria-hidden="true">{{{image}}}</a>
+<div class="bc-body">
+  <div class="bc-kicker">{{{categories}}}</div>
+  <h2 class="bc-title"><a href="{{url}}">{{title}}</a></h2>
+  <p class="bc-excerpt">{{excerpt}}</p>
+  <p class="bc-meta"><a href="{{authorUrl}}">{{authorName}}</a> · <time datetime="{{publishedAt}}">{{publishedAt:D MMM YYYY}}</time> · {{readingTime}}</p>
+</div>

package/plugins/blog/blocks/blog-post-classic.css

@@ -0,0 +1,15 @@
+.pc { max-width: 46rem; margin: 0 auto; }
+.pc-head { text-align: center; margin: 1rem 0 1.75rem; }
+.pc-kicker { display: flex; justify-content: center; gap: .4rem; flex-wrap: wrap; margin-bottom: .75rem; }
+.pc-title { font-size: clamp(2rem, 4.5vw, 2.9rem); line-height: 1.12; margin: 0 0 .75rem; letter-spacing: -.015em; }
+.pc-standfirst { font-size: 1.2rem; color: var(--dm-text-muted); margin: 0 auto .9rem; max-width: 38rem; line-height: 1.5; }
+.pc-standfirst:empty { display: none; }
+.pc-meta { color: var(--dm-text-muted); font-size: .9rem; margin: 0; }
+.pc-meta a { color: inherit; font-weight: 600; }
+.pc-figure { margin: 0 -2rem 2rem; border-radius: var(--dm-radius-lg, 12px); overflow: hidden; }
+.pc-figure img { width: 100%; display: block; }
+.pc-figure.no-image { display: none; }
+.pc-foot { display: flex; justify-content: space-between; align-items: center; gap: 1rem; flex-wrap: wrap;
+  margin: 2.5rem 0 0; padding-top: 1.25rem; border-top: 1px solid var(--dm-border, rgba(127,127,127,.25)); }
+.pc-tags { display: flex; gap: .4rem; flex-wrap: wrap; }
+@media (max-width: 900px) { .pc-figure { margin-left: 0; margin-right: 0; } }

package/plugins/blog/blocks/blog-post-classic.html

@@ -0,0 +1,28 @@
+<!--
+  blog-post-classic - title, image, then the story in one centred column.
+  Edit it to restyle every post that uses Classic; copy it as blog-post-<name>
+  to add a layout authors can choose.
+
+  {{title}} {{excerpt}} {{url}} {{authorName}} {{authorUrl}} {{readingTime}} {{date}}
+  {{publishedAt:D MMMM YYYY}}  any date format
+  {{imageUrl}} {{imageClass}} (has-image | no-image)
+  Ready-made markup: {{{content}}} {{{image}}} {{{categories}}} {{{tags}}} {{{toc}}}
+  {{{share}}} {{{prevNext}}} {{{related}}} {{{comments}}}
+-->
+<article class="pc">
+  <header class="pc-head">
+    <div class="pc-kicker">{{{categories}}}</div>
+    <h1 class="pc-title">{{title}}</h1>
+    <p class="pc-standfirst">{{excerpt}}</p>
+    <p class="pc-meta">By <a href="{{authorUrl}}">{{authorName}}</a> · <time datetime="{{publishedAt}}">{{publishedAt:D MMMM YYYY}}</time> · {{readingTime}}</p>
+  </header>
+  <figure class="pc-figure {{imageClass}}">{{{image}}}</figure>
+  <div class="pc-body blog-content">{{{content}}}</div>
+  <footer class="pc-foot">
+    <div class="pc-tags">{{{tags}}}</div>
+    {{{share}}}
+  </footer>
+  {{{prevNext}}}
+  {{{related}}}
+  {{{comments}}}
+</article>

package/plugins/blog/blocks/blog-post-feature.css

@@ -0,0 +1,20 @@
+.pf-hero { position: relative; min-height: min(72vh, 40rem); display: flex; align-items: flex-end;
+  margin: 0 calc(50% - 50vw) 2.5rem; padding: 0 calc(50vw - 50%);
+  background: var(--pf-image) center / cover no-repeat, var(--dm-primary, #334155); color: #fff; }
+.pf-hero.no-image { min-height: 22rem;
+  background: linear-gradient(135deg, var(--dm-primary, #334155), color-mix(in srgb, var(--dm-primary, #334155) 55%, #000)); }
+.pf-hero::before { content: ""; position: absolute; inset: 0; background: linear-gradient(180deg, rgba(0,0,0,0) 25%, rgba(0,0,0,.72) 100%); }
+.pf-hero-inner { position: relative; width: 100%; max-width: 52rem; margin: 0 auto; padding: 3rem 1.25rem 2.5rem; }
+.pf-kicker { display: flex; gap: .4rem; flex-wrap: wrap; margin-bottom: .9rem; }
+.pf-kicker .blog-chip { background: rgba(255,255,255,.18); color: #fff; border-color: rgba(255,255,255,.35); }
+.pf-title { font-size: clamp(2.2rem, 5.5vw, 3.8rem); line-height: 1.05; margin: 0 0 .9rem; color: #fff; letter-spacing: -.02em;
+  text-shadow: 0 2px 18px rgba(0,0,0,.35); }
+.pf-standfirst { font-size: 1.25rem; line-height: 1.5; margin: 0 0 1rem; max-width: 40rem; opacity: .92; }
+.pf-standfirst:empty { display: none; }
+.pf-meta { margin: 0; font-size: .92rem; opacity: .85; }
+.pf-meta a { color: inherit; font-weight: 600; }
+.pf-wrap { max-width: 44rem; margin: 0 auto; }
+.pf-body > p:first-of-type::first-letter { float: left; font-size: 3.6em; line-height: .85; padding: .08em .12em 0 0; font-weight: 700; color: var(--dm-primary); }
+.pf-foot { display: flex; justify-content: space-between; align-items: center; gap: 1rem; flex-wrap: wrap;
+  margin-top: 2.5rem; padding-top: 1.25rem; border-top: 1px solid var(--dm-border, rgba(127,127,127,.25)); }
+.pf-tags { display: flex; gap: .4rem; flex-wrap: wrap; }

package/plugins/blog/blocks/blog-post-feature.html

@@ -0,0 +1,30 @@
+<!--
+  blog-post-feature - a full-width hero image with the title over it.
+  Without a featured image the hero falls back to the theme's primary colour.
+
+  {{title}} {{excerpt}} {{url}} {{authorName}} {{authorUrl}} {{readingTime}} {{date}}
+  {{publishedAt:D MMMM YYYY}}  any date format
+  {{imageUrl}} {{imageClass}} (has-image | no-image)
+  Ready-made markup: {{{content}}} {{{image}}} {{{categories}}} {{{tags}}} {{{toc}}}
+  {{{share}}} {{{prevNext}}} {{{related}}} {{{comments}}}
+-->
+<article class="pf">
+  <header class="pf-hero {{imageClass}}" style="--pf-image: url('{{imageUrl}}')">
+    <div class="pf-hero-inner">
+      <div class="pf-kicker">{{{categories}}}</div>
+      <h1 class="pf-title">{{title}}</h1>
+      <p class="pf-standfirst">{{excerpt}}</p>
+      <p class="pf-meta"><a href="{{authorUrl}}">{{authorName}}</a> · <time datetime="{{publishedAt}}">{{publishedAt:D MMMM YYYY}}</time> · {{readingTime}}</p>
+    </div>
+  </header>
+  <div class="pf-wrap">
+    <div class="pf-body blog-content">{{{content}}}</div>
+    <footer class="pf-foot">
+      <div class="pf-tags">{{{tags}}}</div>
+      {{{share}}}
+    </footer>
+    {{{prevNext}}}
+    {{{related}}}
+    {{{comments}}}
+  </div>
+</article>

package/plugins/blog/blocks/blog-post-minimal.css

@@ -0,0 +1,10 @@
+.pm { max-width: 38rem; margin: 0 auto; }
+.pm-head { margin: 2.5rem 0 2.25rem; }
+.pm-meta { margin: 0 0 .6rem; font-size: .8rem; letter-spacing: .08em; text-transform: uppercase; color: var(--dm-text-muted); }
+.pm-title { font-size: clamp(1.9rem, 4vw, 2.5rem); line-height: 1.15; margin: 0 0 .6rem; font-weight: 700; }
+.pm-by { margin: 0; font-style: italic; color: var(--dm-text-muted); }
+.pm-by a { color: inherit; }
+.pm-body { font-size: 1.13rem; line-height: 1.85; }
+.pm-foot { margin-top: 3rem; padding-top: 1.25rem; border-top: 1px solid var(--dm-border, rgba(127,127,127,.25));
+  display: flex; justify-content: space-between; align-items: center; gap: 1rem; flex-wrap: wrap; }
+.pm-tags { display: flex; gap: .4rem; flex-wrap: wrap; }

package/plugins/blog/blocks/blog-post-minimal.html

@@ -0,0 +1,23 @@
+<!--
+  blog-post-minimal - just the words: a narrow reading column, no image.
+
+  {{title}} {{excerpt}} {{url}} {{authorName}} {{authorUrl}} {{readingTime}} {{date}}
+  {{publishedAt:D MMMM YYYY}}  any date format
+  {{imageUrl}} {{imageClass}} (has-image | no-image)
+  Ready-made markup: {{{content}}} {{{image}}} {{{categories}}} {{{tags}}} {{{toc}}}
+  {{{share}}} {{{prevNext}}} {{{related}}} {{{comments}}}
+-->
+<article class="pm">
+  <header class="pm-head">
+    <p class="pm-meta"><time datetime="{{publishedAt}}">{{publishedAt:D MMMM YYYY}}</time> · {{readingTime}}</p>
+    <h1 class="pm-title">{{title}}</h1>
+    <p class="pm-by">by <a href="{{authorUrl}}">{{authorName}}</a></p>
+  </header>
+  <div class="pm-body blog-content">{{{content}}}</div>
+  <footer class="pm-foot">
+    <div class="pm-tags">{{{categories}}}{{{tags}}}</div>
+    {{{share}}}
+  </footer>
+  {{{prevNext}}}
+  {{{comments}}}
+</article>

package/plugins/blog/blocks/blog-post-sidebar.css

@@ -0,0 +1,22 @@
+.ps-head { max-width: 50rem; margin: 1rem 0 2rem; }
+.ps-kicker { display: flex; gap: .4rem; flex-wrap: wrap; margin-bottom: .75rem; }
+.ps-title { font-size: clamp(2rem, 4.2vw, 2.8rem); line-height: 1.12; margin: 0 0 .7rem; letter-spacing: -.015em; }
+.ps-standfirst { font-size: 1.15rem; color: var(--dm-text-muted); margin: 0; line-height: 1.55; }
+.ps-standfirst:empty { display: none; }
+.ps-grid { display: grid; grid-template-columns: minmax(0, 1fr) 17rem; gap: 3rem; align-items: start; }
+.ps-figure { margin: 0 0 2rem; border-radius: var(--dm-radius-lg, 12px); overflow: hidden; }
+.ps-figure img { width: 100%; display: block; }
+.ps-figure.no-image { display: none; }
+.ps-aside { align-self: stretch; display: flex; flex-direction: column; gap: 1.25rem; }
+.ps-aside .blog-toc { position: sticky; top: calc(var(--dm-navbar-height, 64px) + 1.25rem); max-height: calc(100vh - var(--dm-navbar-height, 64px) - 2.5rem); overflow-y: auto; }
+.ps-card { padding: 1.1rem 1.2rem; border: 1px solid var(--dm-border, rgba(127,127,127,.25)); border-radius: var(--dm-radius-lg, 12px); font-size: .9rem; }
+.ps-card p { margin: 0 0 .7rem; }
+.ps-label { font-size: .72rem !important; letter-spacing: .06em; text-transform: uppercase; color: var(--dm-text-muted); margin-bottom: .15rem !important; }
+.ps-author a { font-weight: 600; color: inherit; }
+.ps-tags { display: flex; gap: .35rem; flex-wrap: wrap; margin: .25rem 0 .9rem; }
+.ps-tags:empty { display: none; }
+@media (max-width: 960px) {
+  .ps-grid { grid-template-columns: 1fr; gap: 2rem; }
+  .ps-aside { order: -1; }
+  .ps-aside .blog-toc { display: none; }
+}

package/plugins/blog/blocks/blog-post-sidebar.html

@@ -0,0 +1,36 @@
+<!--
+  blog-post-sidebar - the story beside a sticky contents list, details and share links.
+
+  {{title}} {{excerpt}} {{url}} {{authorName}} {{authorUrl}} {{readingTime}} {{date}}
+  {{publishedAt:D MMMM YYYY}}  any date format
+  {{imageUrl}} {{imageClass}} (has-image | no-image)
+  Ready-made markup: {{{content}}} {{{image}}} {{{categories}}} {{{tags}}} {{{toc}}}
+  {{{share}}} {{{prevNext}}} {{{related}}} {{{comments}}}
+-->
+<article class="ps">
+  <header class="ps-head">
+    <div class="ps-kicker">{{{categories}}}</div>
+    <h1 class="ps-title">{{title}}</h1>
+    <p class="ps-standfirst">{{excerpt}}</p>
+  </header>
+  <div class="ps-grid">
+    <div class="ps-main">
+      <figure class="ps-figure {{imageClass}}">{{{image}}}</figure>
+      <div class="ps-body blog-content">{{{content}}}</div>
+      {{{prevNext}}}
+      {{{comments}}}
+    </div>
+    <aside class="ps-aside">
+      <div class="ps-card">
+        <p class="ps-label">Written by</p>
+        <p class="ps-author"><a href="{{authorUrl}}">{{authorName}}</a></p>
+        <p class="ps-label">Published</p>
+        <p><time datetime="{{publishedAt}}">{{publishedAt:D MMMM YYYY}}</time> · {{readingTime}}</p>
+        <div class="ps-tags">{{{tags}}}</div>
+        {{{share}}}
+      </div>
+      {{{toc}}}
+    </aside>
+  </div>
+  {{{related}}}
+</article>

package/plugins/blog/collections/posts/schema.json

@@ -15,6 +15,8 @@
     { "name": "authorId",      "label": "Author",         "type": "text",     "required": true },
     { "name": "status",        "label": "Status",         "type": "select",   "required": true, "options": ["draft", "scheduled", "published"] },
     { "name": "publishedAt",   "label": "Published At",   "type": "datetime", "required": false },
-    { "name": "seo",           "label": "SEO",            "type": "object",   "required": false }
+    { "name": "template",      "label": "Layout",         "type": "text",     "required": false },
+    { "name": "seo",           "label": "SEO",            "type": "object",   "required": false },
+    { "name": "sample",        "label": "Sample post",    "type": "boolean",  "required": false }
   ]
 }

package/plugins/blog/config.js

@@ -4,5 +4,11 @@ export default {
     commentsEnabled:   false,
     commentModeration: true,
     feedLength:        20,
+    // Display - see lib/layouts.js. Read live, so no restart is needed.
+    postLayout:        'blog-post-classic',
+    listDisplay:       'cards',
+    displaySwitcher:   true,
+    interactive:       true,
+    relatedCount:      3,
     storage: { adapter: 'file' }
 };

package/plugins/blog/lib/layouts.js

@@ -0,0 +1,304 @@
+/**
+ * Blog layouts - the pure half of rendering posts through blocks.
+ *
+ * A post page and every listing card are BLOCKS (content/blocks/*.html), so a
+ * site restyles its blog in the Blocks tool rather than in this plugin:
+ *
+ *   blog-post-<name>  a whole post page       (Classic, Feature, Minimal, Sidebar…)
+ *   blog-card-<name>  one post in a listing   (Cards, List, Compact…)
+ *
+ * Any block a site adds with one of those prefixes becomes a further choice -
+ * nothing here needs to know about it. Nothing in this file touches the disk,
+ * so all of it is testable on its own; lib/render.js does the I/O.
+ *
+ * @module blog/lib/layouts
+ */
+
+/** The post layouts the plugin ships. Each is a block of the same name. */
+export const POST_LAYOUTS = [
+    {id: 'blog-post-classic', label: 'Classic', description: 'Title, image, then the story in one centred column.'},
+    {id: 'blog-post-feature', label: 'Feature', description: 'A full-width hero image with the title over it - for the big pieces.'},
+    {id: 'blog-post-minimal', label: 'Minimal', description: 'Just the words: a narrow reading column, no image.'},
+    {id: 'blog-post-sidebar', label: 'Sidebar', description: 'The story beside a sticky contents list, details and share links.'}
+];
+
+/**
+ * The listing displays the plugin ships. A display is a card block plus how the
+ * cards are arranged; Magazine reuses the Cards block and makes the first post
+ * the lead.
+ */
+export const LIST_DISPLAYS = [
+    {id: 'cards',    block: 'blog-card',         arrange: 'grid',  label: 'Cards',    description: 'A grid of picture cards.'},
+    {id: 'list',     block: 'blog-card-row',     arrange: 'stack', label: 'List',     description: 'One post per row, picture beside the text.'},
+    {id: 'magazine', block: 'blog-card',         arrange: 'grid',  label: 'Magazine', description: 'The newest post large across the top, the rest as cards.', lead: true},
+    {id: 'compact',  block: 'blog-card-compact', arrange: 'stack', label: 'Compact',  description: 'Titles and dates only - an archive at a glance.'}
+];
+
+export const DEFAULT_POST_LAYOUT = 'blog-post-classic';
+export const DEFAULT_DISPLAY = 'cards';
+
+const BUILTIN_CARD_BLOCKS = new Set(LIST_DISPLAYS.map(d => d.block));
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** 'blog-post-long-read' -> 'Long read' */
+function labelFrom(suffix) {
+    const s = suffix.replace(/-/g, ' ');
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * Every post layout on offer: the shipped ones, then any other `blog-post-*`
+ * block the site has. A shipped layout whose block was deleted still counts -
+ * the plugin carries its own copy.
+ *
+ * @param   {string[]} blockNames - names of the blocks on this site
+ * @returns {{id: string, label: string, description: string, custom: boolean}[]}
+ */
+export function postLayouts(blockNames = []) {
+    const shipped = new Set(POST_LAYOUTS.map(l => l.id));
+    const extra = blockNames
+        .filter(n => NAME_RE.test(n) && n.startsWith('blog-post-') && !shipped.has(n))
+        .sort()
+        .map(n => ({id: n, label: labelFrom(n.slice('blog-post-'.length)), description: 'Your own layout, from the Blocks tool.', custom: true}));
+    return [...POST_LAYOUTS.map(l => ({...l, custom: false})), ...extra];
+}
+
+/**
+ * Every listing display on offer: the shipped four, then one per extra
+ * `blog-card-*` block, arranged as a grid.
+ *
+ * @param   {string[]} blockNames
+ * @returns {{id: string, block: string, arrange: string, label: string, description: string, lead?: boolean, custom: boolean}[]}
+ */
+export function listDisplays(blockNames = []) {
+    const extra = blockNames
+        .filter(n => NAME_RE.test(n) && n.startsWith('blog-card-') && !BUILTIN_CARD_BLOCKS.has(n))
+        .sort()
+        .map(n => ({id: n, block: n, arrange: 'grid', label: labelFrom(n.slice('blog-card-'.length)), description: 'Your own card, from the Blocks tool.', custom: true}));
+    return [...LIST_DISPLAYS.map(d => ({...d, custom: false})), ...extra];
+}
+
+/** The layout a post renders with: its own choice if still on offer, else the site default. */
+export function pickPostLayout(post, settings, layouts) {
+    const ids = new Set(layouts.map(l => l.id));
+    if (post?.template && ids.has(post.template)) return post.template;
+    if (settings?.postLayout && ids.has(settings.postLayout)) return settings.postLayout;
+    return DEFAULT_POST_LAYOUT;
+}
+
+/** The display a listing renders with: a valid request wins, then the setting, then Cards. */
+export function pickDisplay(requested, settings, displays) {
+    const byId = new Map(displays.map(d => [d.id, d]));
+    return byId.get(requested) ?? byId.get(settings?.listDisplay) ?? byId.get(DEFAULT_DISPLAY);
+}
+
+// ---------------------------------------------------------------------------
+// Settings
+// ---------------------------------------------------------------------------
+
+/** The display settings and their defaults (the rest live in config.js). */
+export const DISPLAY_DEFAULTS = {
+    postLayout: DEFAULT_POST_LAYOUT,
+    listDisplay: DEFAULT_DISPLAY,
+    displaySwitcher: true,
+    interactive: true,
+    relatedCount: 3
+};
+
+/**
+ * Whitelist the display settings from a request body. Only keys present are
+ * returned, so a PUT carrying one of them leaves the others as stored.
+ *
+ * @param   {object} body
+ * @returns {object}
+ */
+export function pickDisplaySettings(body = {}) {
+    const out = {};
+    if (typeof body.postLayout === 'string' && /^blog-post-[a-z0-9-]+$/.test(body.postLayout)) out.postLayout = body.postLayout;
+    if (typeof body.listDisplay === 'string' && /^[a-z0-9][a-z0-9-]*$/.test(body.listDisplay)) out.listDisplay = body.listDisplay;
+    if (body.displaySwitcher !== undefined) out.displaySwitcher = Boolean(body.displaySwitcher);
+    if (body.interactive !== undefined) out.interactive = Boolean(body.interactive);
+    if (body.relatedCount !== undefined) {
+        const n = Number(body.relatedCount);
+        out.relatedCount = Number.isFinite(n) ? Math.max(0, Math.min(6, Math.round(n))) : DISPLAY_DEFAULTS.relatedCount;
+    }
+    return out;
+}
+
+// ---------------------------------------------------------------------------
+// Interpolation
+// ---------------------------------------------------------------------------
+
+export function escapeHtml(str) {
+    return String(str ?? '')
+        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+/**
+ * Moment-style date formatting, the same tokens block templates use elsewhere
+ * (`{{publishedAt:D MMM YYYY}}`). UTC, so a page renders the same wherever the
+ * server is.
+ *
+ * @returns {string|null} null when the value is not a date
+ */
+export function formatDate(value, fmt) {
+    if (!value) return null;
+    const d = new Date(value);
+    if (Number.isNaN(d.getTime())) return null;
+    const pad = (n) => String(n).padStart(2, '0');
+    const t = {
+        YYYY: () => d.getUTCFullYear(), YY: () => pad(d.getUTCFullYear() % 100),
+        MMMM: () => MONTHS[d.getUTCMonth()], MMM: () => MONTHS[d.getUTCMonth()].slice(0, 3),
+        MM: () => pad(d.getUTCMonth() + 1), M: () => d.getUTCMonth() + 1,
+        DD: () => pad(d.getUTCDate()), D: () => d.getUTCDate(),
+        dddd: () => DAYS[d.getUTCDay()], ddd: () => DAYS[d.getUTCDay()].slice(0, 3),
+        HH: () => pad(d.getUTCHours()), mm: () => pad(d.getUTCMinutes())
+    };
+    return fmt.replace(/YYYY|YY|MMMM|MMM|MM|M|DD|D|dddd|ddd|HH|mm/g, k => String(t[k]()));
+}
+
+/**
+ * Fill a block template. `{{{key}}}` is raw (for the fragments this plugin
+ * builds and escapes itself), `{{key}}` is escaped, `{{key:D MMM YYYY}}`
+ * formats a date. HTML comments go - a block's header documents its
+ * placeholders, and a listing of fifty cards need not repeat that fifty times.
+ *
+ * @param   {string} tpl
+ * @param   {object} vars
+ * @returns {string}
+ */
+export function interpolate(tpl, vars) {
+    return String(tpl ?? '')
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .replace(/\{\{\{(\w+)\}\}\}/g, (_, k) => String(vars[k] ?? ''))
+        .replace(/\{\{(\w+)(?::([^{}]+))?\}\}/g, (_, k, fmt) => {
+            const v = vars[k] ?? '';
+            if (fmt) {
+                const f = formatDate(v, fmt);
+                if (f !== null) return escapeHtml(f);
+            }
+            return escapeHtml(v);
+        })
+        .trim();
+}
+
+// ---------------------------------------------------------------------------
+// What a post page and a card are made of
+// ---------------------------------------------------------------------------
+
+/** An image address safe inside `url('…')` and `src="…"`, or ''. */
+export function safeImageUrl(url) {
+    const s = String(url ?? '').trim();
+    return /^(\/|https?:\/\/)[^\s'"()\\<>]+$/.test(s) ? s : '';
+}
+
+/** "4 min read", from the words in the post (markup stripped). */
+export function readingTime(text) {
+    const words = String(text ?? '').replace(/<[^>]*>/g, ' ').split(/\s+/).filter(Boolean).length;
+    return `${Math.max(1, Math.round(words / 200))} min read`;
+}
+
+function slugify(s) {
+    return String(s).toLowerCase().replace(/<[^>]*>/g, '').replace(/&[a-z#0-9]+;/g, '')
+        .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'section';
+}
+
+/**
+ * Give the body's h2/h3 headings ids and build a contents list from them.
+ * Fewer than two headings is not worth a list, and gets none.
+ *
+ * @param   {string} html - the rendered post body
+ * @returns {{html: string, toc: string, count: number}}
+ */
+export function buildToc(html) {
+    const items = [];
+    const used = new Set();
+    const out = String(html ?? '').replace(/<h([23])([^>]*)>([\s\S]*?)<\/h\1>/g, (m, level, attrs, inner) => {
+        let id = /\sid="([^"]+)"/.exec(attrs)?.[1];
+        if (!id) {
+            const base = slugify(inner);
+            id = base;
+            for (let n = 2; used.has(id); n++) id = `${base}-${n}`;
+            attrs = `${attrs} id="${id}"`;
+        }
+        used.add(id);
+        items.push({level: Number(level), id, text: inner.replace(/<[^>]*>/g, '').trim()});
+        return `<h${level}${attrs}>${inner}</h${level}>`;
+    });
+    if (items.length < 2) return {html: out, toc: '', count: items.length};
+    const lis = items.map(i => `<li class="blog-toc-l${i.level}"><a href="#${escapeHtml(i.id)}">${i.text}</a></li>`).join('');
+    return {html: out, toc: `<nav class="blog-toc" aria-label="On this page" data-blog-toc><p class="blog-toc-title">On this page</p><ol>${lis}</ol></nav>`, count: items.length};
+}
+
+/**
+ * Posts related to this one: shared categories count double, shared tags once;
+ * ties go to the newer post.
+ */
+export function relatedPosts(post, all, count = 3) {
+    if (!count) return [];
+    const cats = new Set(post.categories ?? []);
+    const tags = new Set(post.tags ?? []);
+    return all
+        .filter(p => p.id !== post.id)
+        .map(p => ({p, score: (p.categories ?? []).filter(c => cats.has(c)).length * 2 + (p.tags ?? []).filter(t => tags.has(t)).length}))
+        .filter(x => x.score > 0)
+        .sort((a, b) => b.score - a.score || new Date(b.p.publishedAt || 0) - new Date(a.p.publishedAt || 0))
+        .slice(0, count)
+        .map(x => x.p);
+}
+
+/**
+ * The placeholders a card block can use, for one post. Raw (`{{{…}}}`) ones are
+ * built here from escaped parts; everything else is plain text.
+ *
+ * @param {object} post
+ * @param {object} ctx - {base, catMap: id -> {name, slug}, authorName}
+ */
+export function cardVars(post, {base, catMap = {}, authorName = ''}) {
+    const url = `${base}/${encodeURIComponent(post.slug ?? '')}`;
+    const imageUrl = safeImageUrl(post.featuredImage);
+    const cats = (post.categories ?? []).map(id => catMap[id]).filter(Boolean);
+    return {
+        id: post.id,
+        title: post.title ?? '',
+        url,
+        excerpt: post.excerpt ?? '',
+        publishedAt: post.publishedAt ?? '',
+        date: formatDate(post.publishedAt, 'D MMM YYYY') ?? '',
+        authorName,
+        authorUrl: post.authorId ? `${base}/author/${encodeURIComponent(post.authorId)}` : base,
+        readingTime: readingTime(post.content),
+        imageUrl,
+        imageClass: imageUrl ? 'has-image' : 'no-image',
+        image: imageUrl ? `<img src="${escapeHtml(imageUrl)}" alt="" loading="lazy">` : '',
+        category: cats[0]?.name ?? '',
+        categories: cats.map(c => `<a class="blog-chip" href="${base}/category/${encodeURIComponent(c.slug)}" data-blog-cat="${escapeHtml(c.slug)}">${escapeHtml(c.name)}</a>`).join(''),
+        tags: (post.tags ?? []).map(t => `<a class="blog-tag" href="${base}/tag/${encodeURIComponent(t)}" data-blog-tag="${escapeHtml(t)}">#${escapeHtml(t)}</a>`).join('')
+    };
+}
+
+/**
+ * What the browser needs to filter, sort and right-click a card: plain values,
+ * carried in a data attribute - never markup.
+ */
+export function cardMeta(post, {catMap = {}, authorName = ''}) {
+    return {
+        id: post.id,
+        title: post.title ?? '',
+        excerpt: post.excerpt ?? '',
+        date: post.publishedAt ?? '',
+        cats: (post.categories ?? []).map(id => catMap[id]).filter(Boolean).map(c => ({slug: c.slug, name: c.name})),
+        tags: post.tags ?? [],
+        author: {id: post.authorId ?? '', name: authorName},
+        minutes: Number.parseInt(readingTime(post.content), 10)
+    };
+}
+
+/** Newest first, by publishedAt; undated posts last. */
+export function byNewest(a, b) {
+    return new Date(b.publishedAt || 0) - new Date(a.publishedAt || 0);
+}