domma-cms 0.66.0 → 0.69.3

package/plugins/blog/lib/page.js

@@ -0,0 +1,158 @@
+/**
+ * A post page, rendered through its layout block - shared by the public route
+ * (plugin.public.js) and the admin preview (plugin.js), which passes `layout`
+ * to try one on before saving.
+ *
+ * @module blog/lib/page
+ */
+import {listEntries} from '../../../server/services/collections.js';
+import {parseMarkdown} from '../../../server/services/markdown.js';
+import {getUserById} from '../../../server/services/users.js';
+import {getPluginStates} from '../../../server/services/plugins.js';
+import defaultConfig from '../config.js';
+import {buildToc, byNewest, cardVars, DEFAULT_POST_LAYOUT, DISPLAY_DEFAULTS, escapeHtml, interpolate, pickPostLayout, relatedPosts, safeImageUrl} from './layouts.js';
+import {catalogue, loadBlock, renderCards, styleTag} from './render.js';
+
+export function isVisible(post) {
+    return post.status === 'published' ||
+        (post.status === 'scheduled' && post.publishedAt && new Date(post.publishedAt) <= new Date());
+}
+
+/** Settings as they are NOW - display choices apply without a restart. */
+export function liveSettings(registered) {
+    return {...defaultConfig, ...DISPLAY_DEFAULTS, ...registered, ...(getPluginStates()?.blog?.settings ?? {})};
+}
+
+/** Always returns the actual array of entries, regardless of adapter shape. */
+export async function loadEntries(slug) {
+    const result = await listEntries(slug, {limit: 100000, sort: 'createdAt', order: 'desc'});
+    const arr = Array.isArray(result) ? result : (Array.isArray(result?.entries) ? result.entries : []);
+    return arr.map((entry) => ({id: entry.id, ...(entry.data ?? entry)}));
+}
+
+/** Render a post body through the full Markdown + shortcode pipeline. */
+export async function renderPostBody(content) {
+    if (!content) return {html: '', usedComponents: []};
+    try {
+        // Anonymous: the [menu] shortcode treats the visitor as signed out.
+        const {html, usedComponents} = await parseMarkdown('---\n---\n' + content, {});
+        return {html, usedComponents: usedComponents || []};
+    } catch {
+        return {html: escapeHtml(content), usedComponents: []};
+    }
+}
+
+export async function resolveAuthorName(authorId) {
+    if (!authorId) return 'Unknown';
+    try {
+        const user = await getUserById(authorId);
+        return user?.name || user?.email || 'Unknown';
+    } catch {
+        return 'Unknown';
+    }
+}
+
+/** One lookup per author, however many posts they wrote. */
+export async function authorNamesFor(posts) {
+    const ids = [...new Set(posts.map(p => p.authorId).filter(Boolean))];
+    const names = await Promise.all(ids.map(resolveAuthorName));
+    return new Map(ids.map((id, i) => [id, names[i]]));
+}
+
+/**
+ * A post, rendered through its layout block.
+ *
+ * @param {object}   post
+ * @param {object[]} allPosts - every post, for older/newer and related
+ * @param {object}   s        - liveSettings()
+ * @param {object}   opts     - {base, siteUrl, layout (preview only), preview}
+ * @returns {Promise<{html: string, usedComponents: string[], layout: string}>}
+ */
+export async function renderPostPage(post, allPosts, s, {base, siteUrl = '', layout = null, preview = false}) {
+    const {postLayouts, listDisplays} = await catalogue();
+    const chosen = layout && postLayouts.some(l => l.id === layout) ? layout : pickPostLayout(post, s, postLayouts);
+    const block = await loadBlock(chosen) ?? await loadBlock(DEFAULT_POST_LAYOUT);
+
+    const categories = await loadEntries('blog-categories');
+    const catMap = Object.fromEntries(categories.map(c => [c.id, {name: c.name, slug: c.slug}]));
+    const authorName = await resolveAuthorName(post.authorId);
+    const vars = cardVars(post, {base, catMap, authorName});
+
+    const {html: bodyHtml, usedComponents} = await renderPostBody(post.content);
+    const {html: content, toc} = buildToc(bodyHtml);
+
+    // Older and newer, among what a reader can actually see.
+    const visible = allPosts.filter(isVisible).sort(byNewest);
+    const at = visible.findIndex(p => p.id === post.id);
+    const newer = at > 0 ? visible[at - 1] : null;
+    const older = at >= 0 && at < visible.length - 1 ? visible[at + 1] : null;
+    const pn = (p, cls, label) => p
+        ? `<a class="${cls}" href="${base}/${encodeURIComponent(p.slug)}"><span>${label}</span><strong>${escapeHtml(p.title)}</strong></a>`
+        : '<span></span>';
+    const prevNext = newer || older
+        ? `<nav class="blog-prevnext" aria-label="More posts">${pn(older, 'is-older', '← Older')}${pn(newer, 'is-newer', 'Newer →')}</nav>`
+        : '';
+
+    let related = '';
+    let relatedStyle = '';
+    const rel = relatedPosts(post, visible, Number(s.relatedCount ?? 3));
+    if (rel.length) {
+        const cards = listDisplays.find(d => d.id === 'cards');
+        const {items, style} = await renderCards(rel, cards, {base, catMap, authorNames: await authorNamesFor(rel)});
+        relatedStyle = style;
+        related = `<section class="blog-related"><h2 class="blog-section-title">Keep reading</h2><div class="blog-items blog-items--grid">${items}</div></section>`;
+    }
+
+    const url = `${siteUrl}${base}/${encodeURIComponent(post.slug ?? '')}`;
+    const share = `<div class="blog-share" data-blog-share>
+  <a class="blog-share-btn" href="mailto:?subject=${encodeURIComponent(post.title ?? '')}&amp;body=${encodeURIComponent(url)}">Email</a>
+  <button type="button" class="blog-share-btn" data-blog-copy hidden>Copy link</button>
+  <button type="button" class="blog-share-btn" data-blog-native hidden>Share…</button>
+</div>`;
+
+    const comments = s.commentsEnabled ? await commentsHtml(post) : '';
+
+    const imageUrl = safeImageUrl(post.featuredImage);
+    const html = `${styleTag(chosen, block?.css)}${relatedStyle}
+<div class="blog-post-page" data-block="${escapeHtml(chosen)}" data-blog-post${preview ? ' data-preview' : ''}>
+${interpolate(block?.content ?? '', {
+...vars,
+image: imageUrl ? `<img src="${escapeHtml(imageUrl)}" alt="">` : '',
+content, toc, share, prevNext, related, comments
+})}
+</div>`;
+    return {html, usedComponents, layout: chosen};
+}
+
+async function commentsHtml(post) {
+    let approved = [];
+    try {
+        approved = (await loadEntries('blog-comments'))
+            .filter((c) => c.postId === post.id && c.status === 'approved')
+            .sort((a, b) => new Date(a.createdAt || 0) - new Date(b.createdAt || 0));
+    } catch { /* non-fatal */ }
+
+    const list = approved.map((c) => `<li class="blog-comment">
+  <p class="blog-comment-head"><strong>${escapeHtml(c.authorName)}</strong> <time datetime="${escapeHtml(c.createdAt)}">${escapeHtml(new Date(c.createdAt).toLocaleDateString('en-GB', {day: 'numeric', month: 'long', year: 'numeric'}))}</time></p>
+  <p class="blog-comment-body">${escapeHtml(c.body)}</p>
+</li>`).join('\n');
+
+    return `<section class="blog-comments" id="comments">
+  <h2 class="blog-section-title">Comments <span class="blog-count" data-blog-comment-count>${approved.length}</span></h2>
+  <ol class="blog-comment-list" data-blog-comment-list>${list}</ol>
+  <form class="blog-comment-form" method="POST" action="/api/plugins/blog/comments" data-blog-comment-form>
+<h3>Leave a comment</h3>
+<input type="hidden" name="postId" value="${escapeHtml(post.id)}">
+<div class="blog-comment-row">
+  <label>Name<input type="text" name="authorName" required maxlength="80" class="form-input" autocomplete="name"></label>
+  <label>Email <small>(never shown)</small><input type="email" name="authorEmail" required maxlength="160" class="form-input" autocomplete="email"></label>
+</div>
+<label class="blog-hp" aria-hidden="true">Website<input type="text" name="website" tabindex="-1" autocomplete="off"></label>
+<label>Comment<textarea name="body" required rows="4" maxlength="5000" class="form-input"></textarea></label>
+<div class="blog-comment-actions">
+  <button type="submit" class="btn btn-primary">Post comment</button>
+  <span class="blog-comment-status" role="status" data-blog-comment-status></span>
+</div>
+  </form>
+</section>`;
+}

package/plugins/blog/lib/render.js

@@ -0,0 +1,119 @@
+/**
+ * Blog rendering through blocks - the half of layouts.js that touches the disk.
+ *
+ * A layout's block is read from the site's Blocks (content/blocks/), where it
+ * can be edited, and from this plugin's own blocks/ folder when the site has
+ * no block of that name - so deleting a shipped block in the Blocks tool puts
+ * the original back rather than breaking the blog.
+ *
+ * @module blog/lib/render
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import {getBlock, listBlocks, saveBlock} from '../../../server/services/blocks.js';
+import {getPluginStates, savePluginState} from '../../../server/services/plugins.js';
+import {cardMeta, cardVars, escapeHtml, interpolate, LIST_DISPLAYS, listDisplays, POST_LAYOUTS, postLayouts} from './layouts.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const SHIPPED_DIR = path.join(__dirname, '..', 'blocks');
+const SHIPPED = [...new Set([...POST_LAYOUTS.map(l => l.id), ...LIST_DISPLAYS.map(d => d.block)])];
+
+async function readShipped(name) {
+    if (!SHIPPED.includes(name)) return null;
+    try {
+        const content = await fs.readFile(path.join(SHIPPED_DIR, `${name}.html`), 'utf8');
+        const css = await fs.readFile(path.join(SHIPPED_DIR, `${name}.css`), 'utf8').catch(() => '');
+        return {content, css};
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Copy the shipped blocks into the site's Blocks, once each. Remembered in
+ * config/plugins.json, so a block the site deletes on purpose stays deleted
+ * (and the blog quietly falls back to the plugin's copy); one that is already
+ * there is never overwritten.
+ *
+ * @returns {Promise<string[]>} the names copied this time
+ */
+export async function seedBlocks() {
+    const done = new Set(getPluginStates()?.blog?.seededBlocks ?? []);
+    const copied = [];
+    for (const name of SHIPPED.filter(n => !done.has(n))) {
+        const shipped = await readShipped(name);
+        if (!shipped) continue;
+        let exists = true;
+        try { await getBlock(name); } catch { exists = false; }
+        if (!exists) {
+            await saveBlock(name, shipped.content, {css: shipped.css, meta: {plugin: 'blog'}});
+            copied.push(name);
+        }
+        done.add(name);
+    }
+    if (copied.length || done.size !== (getPluginStates()?.blog?.seededBlocks ?? []).length) {
+        savePluginState('blog', {seededBlocks: [...done]});
+    }
+    return copied;
+}
+
+/**
+ * A block's template and CSS - the site's copy, else the shipped one.
+ *
+ * @returns {Promise<{content: string, css: string}|null>}
+ */
+export async function loadBlock(name) {
+    try {
+        const b = await getBlock(name);
+        return {content: b.content, css: b.css ?? ''};
+    } catch {
+        return readShipped(name);
+    }
+}
+
+/** The names of every block on the site, plus the shipped ones. */
+async function allBlockNames() {
+    const names = new Set(SHIPPED);
+    try { for (const b of await listBlocks()) names.add(b.name); } catch { /* no blocks dir yet */ }
+    return [...names];
+}
+
+/** Every post layout and listing display on offer on this site. */
+export async function catalogue() {
+    const names = await allBlockNames();
+    return {postLayouts: postLayouts(names), listDisplays: listDisplays(names)};
+}
+
+/**
+ * A block's CSS, scoped to elements carrying its `data-block` - the same
+ * convention every other block on the site uses, so CSS written in the Blocks
+ * tool behaves identically here.
+ */
+export function styleTag(name, css) {
+    if (!css || !css.trim()) return '';
+    const body = String(css).replace(/<\/style/gi, '<\\/style').replace(/\n\s*\n+/g, '\n').trim();
+    return `<style>[data-block="${escapeHtml(name)}"] {\n${body}\n}</style>`;
+}
+
+/**
+ * Render posts as a listing in one display. Each card is wrapped in the
+ * element the browser script filters and right-clicks - `data-entry-id` and a
+ * `data-post` of plain values, never markup.
+ *
+ * @param {object[]} posts
+ * @param {object}   display - one of catalogue().listDisplays
+ * @param {object}   ctx     - {base, catMap, authorNames: Map}
+ * @returns {Promise<{items: string, style: string}>}
+ */
+export async function renderCards(posts, display, ctx) {
+    const block = await loadBlock(display.block) ?? await loadBlock('blog-card');
+    const items = posts.map((post, i) => {
+        const authorName = ctx.authorNames.get(post.authorId) ?? '';
+        const vars = cardVars(post, {base: ctx.base, catMap: ctx.catMap, authorName});
+        const meta = Buffer.from(JSON.stringify(cardMeta(post, {catMap: ctx.catMap, authorName})), 'utf8').toString('base64');
+        const lead = display.lead && i === 0 ? ' is-lead' : '';
+        return `<article class="blog-item${lead}" data-block="${escapeHtml(display.block)}" data-entry-id="${escapeHtml(post.id)}" data-post="${meta}">${interpolate(block?.content ?? '', vars)}</article>`;
+    }).join('\n');
+    return {items, style: styleTag(display.block, block?.css)};
+}

package/plugins/blog/lib/samples.js

@@ -0,0 +1,234 @@
+/**
+ * Sample posts - a blog to look at before there is one.
+ *
+ * Every sample post and category carries `sample: true`, so "Remove sample
+ * posts" takes away exactly what "Add sample posts" put there and nothing an
+ * author wrote. A sample category an author has since filed a real post under
+ * is left alone.
+ *
+ * The posts are spread over the four shipped layouts and use the covers in
+ * public/samples/, so nothing is hotlinked from elsewhere.
+ *
+ * @module blog/lib/samples
+ */
+
+const IMG = (name) => `/plugins/blog/public/samples/${name}.svg`;
+
+export const SAMPLE_CATEGORIES = [
+    {name: 'Guides', slug: 'guides', description: 'How to get things done, step by step.'},
+    {name: 'News', slug: 'news', description: 'What is new, and what changed.'},
+    {name: 'Design', slug: 'design', description: 'Notes on layout, type and colour.'},
+    {name: 'Engineering', slug: 'engineering', description: 'How it works under the bonnet.'}
+];
+
+const DAY = 86_400_000;
+
+/**
+ * @param {number} daysAgo
+ * @param {number} [hour]
+ */
+const ago = (daysAgo, hour = 9) => {
+    const d = new Date(Date.now() - daysAgo * DAY);
+    d.setUTCHours(hour, 0, 0, 0);
+    return d.toISOString();
+};
+
+/** Posts reference categories by slug here; the installer maps them to ids. */
+export function samplePosts() {
+    return [
+        {
+            title: 'Welcome to the new blog',
+            slug: 'welcome-to-the-new-blog',
+            excerpt: 'Layouts you can choose per post, listings you can filter with a right-click, and every template editable as a block.',
+            categories: ['news'], tags: ['announcement', 'blog'],
+            featuredImage: IMG('aurora'), template: 'blog-post-feature', publishedAt: ago(1),
+            content: `The blog has had a proper overhaul. Every post can now choose how it looks, every listing can be searched and filtered without leaving the page, and all of it is built from blocks you can edit.
+
+## Layouts, per post
+
+Open any post in the editor and pick a layout from the **Layout** card: *Classic*, *Feature* (this one), *Minimal* or *Sidebar*. The site-wide default lives in the Blog settings, behind the cog.
+
+## Listings that answer back
+
+The blog index is no longer a static list. Search it, narrow it to a category with the pills, or **right-click any post** for "More in this category", "More tagged…" and "More by this author".
+
+## Everything is a block
+
+The layouts are ordinary blocks called \`blog-post-*\` and \`blog-card-*\`. Change one in the Blocks tool and every post using it changes with it. Copy one under a new name and it appears as a new choice.
+
+> Start with the Blocks tool, not the code. That is the point.
+
+Enjoy it - and delete these sample posts from the Posts menu whenever you are ready.`
+        },
+        {
+            title: 'Writing your first post, start to finish',
+            slug: 'writing-your-first-post',
+            excerpt: 'From a blank editor to a published, well-linked post in about ten minutes.',
+            categories: ['guides'], tags: ['writing', 'getting-started'],
+            featuredImage: IMG('meadow'), template: 'blog-post-sidebar', publishedAt: ago(4),
+            content: `This guide walks through a post from the first word to the Publish button. The contents list beside it follows you down the page.
+
+## Start with the title
+
+A good title says what the reader gets. "Ten minutes to your first post" beats "Some thoughts on writing". The slug fills itself in from the title while **Auto** is ticked.
+
+## Write the excerpt
+
+The excerpt is the sentence or two shown on listings and in search results. Write it last if that is easier - it is often clearer once the post exists.
+
+## The body
+
+Posts are Markdown. Headings (\`##\`) become the contents list in the Sidebar layout, so use them for the real sections of your argument.
+
+### Links and images
+
+Link generously to your own older posts. Pick a featured image from the Media library; it appears on listings and at the top of most layouts.
+
+### Shortcodes
+
+Every shortcode the site supports works in a post, including blocks.
+
+## Categories and tags
+
+Categories are the few big shelves your blog has. Tags are the many small labels. A reader can right-click any post on the listing to see more with the same tag.
+
+## Publish, or schedule
+
+**Publish now** puts it live. **Schedule** holds it until the date you choose - no need to be awake at 7am.`
+        },
+        {
+            title: 'Why whitespace is a feature',
+            slug: 'why-whitespace-is-a-feature',
+            excerpt: 'Room to breathe is not wasted space. It is how a reader knows what matters.',
+            categories: ['design'], tags: ['typography', 'layout'],
+            featuredImage: IMG('dusk'), template: 'blog-post-minimal', publishedAt: ago(9),
+            content: `Every page makes an argument about what matters, and whitespace is how it makes it.
+
+Crowd two things together and the reader assumes they belong together. Put room between them and they read as separate thoughts. Layout is grammar.
+
+## Measure
+
+A line of text is most comfortable at somewhere between 55 and 75 characters. Wider, and the eye loses its place on the way back. This layout keeps to a narrow column on purpose.
+
+## Rhythm
+
+Consistent spacing - the same gap after every paragraph, the same before every heading - is what makes a page feel calm. Inconsistent spacing is noise the reader cannot name but can feel.
+
+## Restraint
+
+The hardest part of design is leaving things out. This layout has no featured image and no sidebar. It has the words, and room around them.`
+        },
+        {
+            title: 'How the listing filters work',
+            slug: 'how-the-listing-filters-work',
+            excerpt: 'The blog index filters in the browser with domma-reactive - here is what happens between the click and the cards.',
+            categories: ['engineering'], tags: ['domma-reactive', 'javascript', 'blog'],
+            featuredImage: IMG('harbour'), publishedAt: ago(15),
+            content: `The listing you came from is rendered on the server, so it works without JavaScript and search engines see every post. The script then takes it over.
+
+## One model
+
+Each card carries a small bundle of plain values - title, date, categories, tags, author. The script reads those into a list and keeps the filters in a handful of observables: the search text, the category, the tag, the author and the sort order.
+
+## Derived, not managed
+
+What is shown is a *computed* value: filter the list, sort it, take the first page. Nothing hides or shows a card by hand; an effect applies whatever the computed says. Change any filter and everything downstream follows.
+
+## The right-click menu
+
+Right-clicking a card opens a menu built from that card's own values. "More in Design" simply sets the category observable. The chips above the list are the same observables, drawn the other way round.
+
+## The address bar
+
+Filters are written back into the address, so a filtered view is a link you can share.`
+        },
+        {
+            title: 'Five small things that make a site feel fast',
+            slug: 'five-things-that-make-a-site-feel-fast',
+            excerpt: 'Speed is partly measured and partly perceived. These five help with both.',
+            categories: ['engineering', 'design'], tags: ['performance'],
+            featuredImage: IMG('ember'), publishedAt: ago(23),
+            content: `A site can be quick on paper and still feel slow. These are the small things that close the gap.
+
+## 1. Reserve space for images
+
+Give images their proportions up front so the page does not jump as they arrive. Cards here use a fixed aspect ratio for exactly that reason.
+
+## 2. Lazy-load what is below the fold
+
+The browser does this for you with \`loading="lazy"\`. Cards use it; the image at the top of a post does not, because it is the first thing you see.
+
+## 3. Respond instantly, finish later
+
+Filtering the blog listing happens in the browser, so the cards change the moment you type - there is no round trip to wait for.
+
+## 4. Compress the right things
+
+Text compresses beautifully. Already-compressed files - images, archives - should be sent as they are.
+
+## 5. Do less
+
+The fastest code is the code that never runs. Every feature should earn its bytes.`
+        },
+        {
+            title: 'Choosing categories that last',
+            slug: 'choosing-categories-that-last',
+            excerpt: 'A handful of broad, stable categories and a generous sprinkling of tags will outlive any clever taxonomy.',
+            categories: ['guides'], tags: ['writing', 'organisation'],
+            featuredImage: IMG('rosewood'), publishedAt: ago(31),
+            content: `Categories are the shelves; tags are the labels on the books. Get the shelves right and the rest looks after itself.
+
+## Keep them few
+
+Four to eight categories is plenty for most blogs. More than that and authors start guessing, and readers stop trusting the pills at the top of the listing.
+
+## Make them stable
+
+A category should still make sense in two years. "News" will. "Spring 2026 launch" will not - that is a tag.
+
+## Let tags do the detail
+
+Tags can be as specific as you like. Readers find them by right-clicking a post and choosing "More tagged…", so a precise tag is genuinely useful.`
+        },
+        {
+            title: 'Release notes: comments, moderation and more',
+            slug: 'release-notes-comments-and-moderation',
+            excerpt: 'Comments now respect their settings the moment you change them, and moderation gained a Rejected list.',
+            categories: ['news'], tags: ['release', 'comments'],
+            featuredImage: IMG('harbour'), publishedAt: ago(40),
+            content: `A round-up of the changes to comments.
+
+## Settings take effect immediately
+
+Switching comments off now closes them straight away - no restart. Holding comments for approval works the same way.
+
+## A place for rejected comments
+
+Rejected comments used to vanish from view. They now have their own list, so a mistaken rejection can be undone.
+
+## Posting without leaving the page
+
+The comment form under each post now sends in place and tells you whether your comment is live or waiting for approval.`
+        },
+        {
+            title: 'A colour palette in an afternoon',
+            slug: 'a-colour-palette-in-an-afternoon',
+            excerpt: 'Start from one colour you love, and let contrast rules do the rest.',
+            categories: ['design'], tags: ['colour', 'theming'],
+            featuredImage: IMG('meadow'), publishedAt: ago(52),
+            content: `You do not need a design degree to build a palette that works. You need one colour, and some discipline.
+
+## Start with one
+
+Pick a primary colour you would be happy to see every day. It will be your links, your buttons and the accent on every card.
+
+## Derive the rest
+
+A darker shade for hover, a pale tint for backgrounds, and a neutral grey family for text. The theme settings can generate these from the one colour.
+
+## Check contrast
+
+Body text needs a contrast ratio of at least 4.5:1 against its background. Test it rather than trusting your eyes on a bright screen.`
+        }
+    ];
+}