domma-cms 0.66.0 → 0.69.3

package/plugins/blog/CLAUDE.md

@@ -0,0 +1,237 @@
+# blog - AI Assistant Guide
+
+## Purpose
+
+Public-facing blog for the CMS. Supports posts with categories, tags, and optional moderated comments. Authors can draft posts; only blog-editors (and admins) can publish or schedule them. Public SSR routes serve an archive index, category/tag/author archives, individual post pages, and an RSS feed. All collection I/O goes through `server/services/collections.js` (FileAdapter by default).
+
+## Files
+
+- `plugin.json`, `plugin.js`, `config.js`, `plugin.public.js`
+- `collections/posts/schema.json` - post entries
+- `collections/categories/schema.json` - category entries
+- `collections/comments/schema.json` - comment entries
+- `templates/index.html` - every listing (index, page n, category, tag, author)
+- `templates/post.html` - a post page (also the admin preview)
+- `lib/layouts.js` - PURE: layouts on offer, interpolation, contents list, card values, settings whitelist
+- `lib/render.js` - blocks I/O: seed, load (site copy, else shipped), render cards
+- `lib/page.js` - a post page through its layout; shared by the public route and `POST /preview`
+- `lib/samples.js` - the sample posts and categories
+- `blocks/*.html|css` - the shipped layouts, copied into content/blocks/ once
+- `public/blog.js`, `public/blog.css` - the browser half (listing, right-click menu, post extras)
+- `public/samples/*.svg` - sample covers
+- `tests/layouts.test.js`, `tests/public.test.js`
+- `admin/views/blog.js` - post list (KPIs + status/category/search filters)
+- `admin/views/post-editor.js` - create / edit a post
+- `admin/views/categories.js`, `admin/views/comments.js`, `admin/views/settings.js`
+- `admin/templates/*.html`
+- `admin/css/index.css` - admin styles (declared in `plugin.json` `admin.css`)
+
+## API Routes
+
+All routes are under `/api/plugins/blog`. All require authentication unless noted.
+
+| Method | Path | Purpose | Auth |
+|---|---|---|---|
+| GET | `/posts` | List posts; blog-authors see only their own | authenticate |
+| POST | `/posts` | Create a new post (draft by default) | authenticate |
+| GET | `/posts/:id` | Get a single post by ID | authenticate |
+| PUT | `/posts/:id` | Update post; blog-authors may only edit their own | authenticate |
+| DELETE | `/posts/:id` | Delete post; blog-editor / admin only | authenticate |
+| POST | `/posts/:id/publish` | Set status to `published`; blog-editor / admin only | authenticate |
+| POST | `/posts/:id/schedule` | Set status to `scheduled` + `publishedAt`; blog-editor / admin only | authenticate |
+| GET | `/categories` | List all categories | authenticate |
+| POST | `/categories` | Create category; blog-editor / admin only | authenticate |
+| PUT | `/categories/:id` | Update category; blog-editor / admin only | authenticate |
+| DELETE | `/categories/:id` | Delete category; blog-editor / admin only | authenticate |
+| GET | `/comments` | List comments; supports `?status=` and `?postId=` filters | authenticate |
+| POST | `/comments` | Submit a comment; **no authentication required** (public route) | - |
+| PUT | `/comments/:id` | Moderate comment (update status field) | authenticate |
+| DELETE | `/comments/:id` | Delete comment | authenticate |
+| GET | `/layouts` | Post layouts and listing displays on offer, plus the defaults | authenticate |
+| POST | `/preview` | A post page from UNSAVED fields, in any layout (`{html, layout}`) | authenticate |
+| POST | `/samples` | Add the sample posts (idempotent by slug) | authenticate + requireAdmin |
+| DELETE | `/samples` | Remove `sample: true` posts, and sample categories nothing uses | authenticate + requireAdmin |
+| GET | `/settings` | Read blog plugin settings | authenticate |
+| PUT | `/settings` | Save blog plugin settings | authenticate + requireAdmin |
+
+## Public Routes
+
+Registered at the Fastify root (no `/api/plugins/blog` prefix). Base path defaults to `/blog` (overridable via `basePath` config key).
+
+| Method | Path | Purpose |
+|---|---|---|
+| GET | `{base}/feed.xml` | RSS 2.0 feed (published + scheduled-due posts) |
+| GET | `{base}/page/:n` | Paginated post archive |
+| GET | `{base}/category/:slug` | Posts filtered by category slug |
+| GET | `{base}/tag/:tag` | Posts filtered by tag |
+| GET | `{base}/author/:id` | Posts filtered by author user ID |
+| GET | `{base}` | Blog index (page 1) |
+| GET | `{base}/:slug` | Single post page - registered LAST |
+
+## Data Model
+
+### posts
+| Field | Type | Notes |
+|---|---|---|
+| `title` | string | Required |
+| `slug` | string | URL slug; auto-derived from title if omitted |
+| `content` | string | Raw Markdown or HTML body |
+| `excerpt` | string | Short summary |
+| `featuredImage` | string\|null | Media path or URL |
+| `categories` | string[] | Array of category entry IDs |
+| `tags` | string[] | Array of tag strings |
+| `status` | string | `draft` \| `published` \| `scheduled` |
+| `authorId` | string | User UUID of the author |
+| `publishedAt` | ISO string | Set on publish or schedule |
+| `seo.title` | string | SEO title override |
+| `seo.description` | string | SEO description override |
+| `template` | string | Post layout block (`blog-post-*`); `''` = the site default |
+| `sample` | boolean | Added by "Add sample posts"; removed by "Remove" |
+
+### categories
+| Field | Type | Notes |
+|---|---|---|
+| `name` | string | Display name |
+| `slug` | string | URL slug |
+| `description` | string | Optional |
+
+### comments
+| Field | Type | Notes |
+|---|---|---|
+| `postId` | string | ID of the parent post entry |
+| `authorName` | string | Commenter display name |
+| `authorEmail` | string | Commenter email (not publicly displayed) |
+| `authorUrl` | string | Optional website URL |
+| `body` | string | Comment text |
+| `status` | string | `pending` \| `approved` \| `rejected` \| `spam` |
+| `createdAt` | ISO string | Set at submission time |
+
+## Config Keys (`config.js`)
+
+| Key | Default | Purpose |
+|---|---|---|
+| `basePath` | `'/blog'` | URL prefix for all public blog routes |
+| `postsPerPage` | `10` | Archive pagination page size |
+| `commentsEnabled` | `false` | Show comment list and form on post pages |
+| `commentModeration` | `true` | New comments start as `pending`; `false` = auto-approve |
+| `feedLength` | `20` | Maximum items in RSS feed |
+| `postLayout` | `'blog-post-classic'` | Default post layout (read live) |
+| `listDisplay` | `'cards'` | `cards` \| `list` \| `magazine` \| `compact` \| a `blog-card-*` block (read live) |
+| `displaySwitcher` | `true` | Readers can switch display above listings |
+| `interactive` | `true` | Listings search/filter/sort/right-click in the browser (≤300 posts) |
+| `relatedCount` | `3` | Related posts under a post; 0 = none |
+| `storage.adapter` | `'file'` | Storage adapter; `'file'` works on free installs |
+
+## Roles
+
+Two custom roles are seeded for this plugin:
+
+- **`blog-author`** - can create posts and edit their own; cannot publish, schedule, or delete
+- **`blog-editor`** - can do everything including publish, schedule, delete, and manage categories/comments
+
+Both roles are at **level 2** in the role hierarchy (same as `editor`). The publish gate is therefore a **named-role check**, not a level comparison.
+
+## Embed Shortcodes
+
+Registered via `options.hooks.registerShortcode` so users can drop blog content into any page:
+
+| Shortcode | Attributes | Purpose |
+|---|---|---|
+| `[blog-list count="5" category="news" /]` | `count`, `limit`, `category` (slug) | Vertical list of recent posts (title + date) |
+| `[blog-grid count="6" cols="3" category="..." /]` | `count`, `limit`, `cols` (1-4), `category` | Card grid with featured images |
+| `[blog-featured slug="..." /]` | `slug` (omit for newest) | Single hero card for one post |
+| `[blog-categories show-counts="true" /]` | `show-counts` | Linked category list with optional post counts |
+
+Shortcode handlers are async (markdown.js was upgraded to await them). They reuse `loadPosts()` / `loadCategories()` helpers that always return arrays regardless of adapter shape.
+
+## Layouts are blocks
+
+A post page and a listing card are BLOCKS. `blog-post-<name>` is a post layout, `blog-card-<name>` a
+card; any block with those prefixes is offered automatically (`lib/layouts.js`). The shipped ones are
+copied into content/blocks/ on start, once each (remembered as `seededBlocks` in config/plugins.json),
+so a site edits them in the Blocks tool; a deleted one falls back to `blocks/` here. Placeholders are
+documented in each block's header comment: `{{x}}` escaped, `{{x:D MMM YYYY}}` a date, `{{{x}}}` raw
+for fragments this plugin builds and escapes (content, image, categories, tags, toc, share, prevNext,
+related, comments). Block CSS is scoped under `[data-block="name"]` like every other block.
+
+The listing works without JS; `public/blog.js` then reads each card's `data-post` (base64 JSON of
+plain values - never markup) into domma-reactive observables. Display switching fetches the same URL
+with `?display=` and swaps the cards, since each display is different block markup.
+
+## Gotchas
+
+- **Public handlers must RETURN the reply.** `reply.type(...).send(html)` without `return` in an
+  async handler loses the body under @fastify/compress - every browser got a 200 with nothing in it,
+  while curl (no Accept-Encoding) saw the page. `tests/public.test.js` drives gzip and brotli.
+
+- **The theme styles every `.page-body a` with `!important`** (public/css/site.css, specificity
+  ~(0,8,4)). The blog's interface links opt out by id (`#dm-blog` on the templates' `<main>`); links
+  inside `.blog-content` keep the theme's look. Theme inputs style `input:not([class])`, so the
+  listing's search box carries a class.
+
+- **The theme wrapper has `overflow: hidden`**, which disables `position: sticky` below it. The
+  Sidebar layout's contents list is kept in view by `keepInView()` in public/blog.js instead.
+
+- **Status is not a field a PUT can set.** `postFields()` whitelists what a body may change; only
+  `draft` is accepted from anyone. Publishing goes through `/publish` and `/schedule`, which check the
+  role. It used to merge the body wholesale, so a blog-author could publish with `{"status": "published"}`.
+
+- **Admin styling is Domma's, not Bootstrap's**: `form-input` / `form-textarea`
+  (not `form-control`), `flex` / `items-center` / `justify-between` (not
+  `d-flex` / `align-items-center` / `justify-content-between`), `text-sm`,
+  `font-mono`, `font-bold`, `form-input-lg`, `btn-outline`. The Bootstrap
+  spellings resolve to nothing in this admin, which left every input in the
+  plugin unstyled. KPI tiles use the admin's own `.stat-card` / `.stat-icon` /
+  `.stat-value` / `.stat-label`, and everything else lives in
+  `admin/css/index.css` - the templates carry no inline styles.
+
+- **`GET /posts` sends a BARE ARRAY**, so `postsRes.data` is undefined. The list
+  view read exactly that and showed an empty table with four zero KPIs while the
+  API was returning posts perfectly well. Read it as
+  `res.data ?? (Array.isArray(res) ? res : [])`, the way `categories.js` and
+  `comments.js` already do.
+
+- **Collection schemas follow the CMS contract**: a collection is named by
+  `title` (not `label`) and a field by `name` (not `key`). They were `label` and
+  `key`, so `createCollection` threw on all three, `setupPlugin`'s bare
+  `catch {}` swallowed it, and a fresh install got three empty directories and
+  `Collection "blog-posts" not found` from every route. Existing sites were
+  unaffected only because the collections were already on disk.
+
+- **The post editor reads its id off the HASH**: Domma's router hands `onMount`
+  one argument and never the params, and `R.current` is a method, so
+  `R.current?.params?.id` was always undefined - the editor opened blank on
+  every edit and Save created a duplicate.
+
+- **`/plugins/blog` is a real route**, mapped to the post list. The sidebar's
+  parent item points at it and `post-editor.js` navigates to it on a failed
+  load; without the route both went nowhere.
+
+- **Settings**: `getConfig`/`saveConfig` in `server/config.js` take a FILE NAME.
+  These routes called `getConfig()` with no argument (reading
+  `config/undefined.json`, so GET answered 500 every time) and
+  `saveConfig(cfg)`. Plugin settings belong in `config/plugins.json` via
+  `getPluginStates()` / `savePluginState('blog', {settings})`. The PUT also
+  guarded with `requireAdmin` alone, which reads `request.user` and therefore
+  401s everyone - it needs `[authenticate, requireAdmin]`.
+
+- **`POST /posts` answers 400 on an empty title.** The schema marks title, slug,
+  authorId and status required, so without the guard an empty title reached
+  `createEntry` and came back 500 where the categories and comments routes both
+  answer 400.
+
+- **Named-role publish gate**: `canPublish()` uses `['blog-editor', 'admin', 'super-admin'].includes(user.role)` - NOT a level comparison. Do not refactor this to `getRoleLevel() <= N`; `blog-author` and `blog-editor` are both level 2, so a level check would give blog-authors publish access.
+
+- **Route registration order in plugin.public.js**: Static path segments (`/feed.xml`, `/page/:n`, `/category/:slug`, `/tag/:tag`, `/author/:id`, base index) are all registered **before** `/:slug`. Fastify matches routes in registration order for same-prefix paths, so `/:slug` must be last to avoid swallowing archive routes.
+
+- **Lazy scheduled post check**: `plugin.public.js` calls `isVisible(post)` on every `GET /:slug` request. A post transitions from `scheduled` to visible the moment `new Date(post.publishedAt) <= new Date()` - no background job needed, no cron required.
+
+- **POST /comments has no authenticate preHandler**: It is intentionally a public route so anonymous visitors can submit comments. The honeypot field (`website`) silently discards bot submissions. Do not add `authenticate` to this route.
+
+- **Comments disabled by default**: `commentsEnabled: false` in `config.js`. The comment list and form are only rendered in `plugin.public.js` when `settings.commentsEnabled` is truthy. Enable in plugin settings via the admin panel.
+
+- **plugin.public.js registered at Fastify root**: This file is registered without the `/api/plugins/blog` prefix. Routes use the full absolute path starting from `base` (default `/blog`). The server registers it separately from `plugin.js`.
+
+- **`storage.adapter: 'file'` default**: Unlike the messages plugin (which defaults to `mongodb`), blog defaults to `file` so it works on free installs without MongoDB. Do not change this default.
+
+- **`listEntries` called with bare slug strings**: In `plugin.public.js`, `listEntries('posts')`, `listEntries('categories')`, and `listEntries('comments')` are called with plain string slugs (not constants). This is consistent with the rest of the public file but differs from `plugin.js`, which uses `POSTS_SLUG` / `CATEGORIES_SLUG` / `COMMENTS_SLUG` constants.

package/plugins/blog/admin/css/index.css

@@ -1 +1,178 @@
-.blog-hidden{display:none!important}.blog-clickable{cursor:pointer}.blog-nowrap{white-space:nowrap}.blog-editor{align-items:flex-start}.blog-editor-main{flex:1;min-width:0}.blog-editor-side{width:280px;flex-shrink:0}@media(max-width:900px){.blog-editor{flex-wrap:wrap}.blog-editor-side{width:100%}}.blog-filter-select{width:auto}.blog-filter-search{width:240px}.blog-settings-card{max-width:600px}.blog-media-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(120px,1fr));gap:.75rem;padding:.5rem}.blog-media-tile{border:1px solid var(--dm-border, #333);background:transparent;border-radius:.25rem;padding:.25rem;cursor:pointer;display:flex;flex-direction:column;align-items:center;gap:.25rem}.blog-media-tile img{width:100%;height:90px;object-fit:cover;border-radius:.15rem}.blog-media-tile span{font-size:.7rem;text-overflow:ellipsis;overflow:hidden;white-space:nowrap;width:100%}.blog-modal-form{display:flex;flex-direction:column;gap:1rem}.blog-modal-actions{display:flex;justify-content:flex-end;gap:.5rem;margin-top:.5rem}.blog-image-preview{max-width:100%;border-radius:.25rem;display:block;margin-bottom:.5rem}.blog-title-link{font-weight:600}.blog-empty-cell{opacity:.4}.blog-row-actions{display:flex;gap:.4rem}.blog-comment-body{font-size:.87rem}.blog-moderation-actions{display:flex;gap:.3rem;flex-wrap:wrap}
+/* Blog plugin - admin styling.
+   The templates carry no inline styles and no Bootstrap class names; Domma's
+   spellings are form-input / form-textarea, flex, items-center, justify-between,
+   text-sm and font-mono. */
+
+.blog-hidden    { display: none !important; }
+.blog-clickable { cursor: pointer; }
+.blog-nowrap    { white-space: nowrap; }
+
+/* Post editor: body on the left, status / categories / tags rail on the right. */
+.blog-editor      { align-items: flex-start; }
+.blog-editor-main { flex: 1; min-width: 0; }
+.blog-editor-side { width: 280px; flex-shrink: 0; }
+
+@media (max-width: 900px) {
+    .blog-editor      { flex-wrap: wrap; }
+    .blog-editor-side { width: 100%; }
+}
+
+/* Media picker (the Featured Image slideover) */
+.blog-media-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
+    gap: 0.75rem;
+    padding: 0.5rem;
+}
+
+.blog-media-tile {
+    border: 1px solid var(--dm-border, #333);
+    background: transparent;
+    border-radius: 0.25rem;
+    padding: 0.25rem;
+    cursor: pointer;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.25rem;
+}
+
+.blog-media-tile img {
+    width: 100%;
+    height: 90px;
+    object-fit: cover;
+    border-radius: 0.15rem;
+}
+
+.blog-media-tile span {
+    font-size: var(--dm-text-xs);
+    text-overflow: ellipsis;
+    overflow: hidden;
+    white-space: nowrap;
+    width: 100%;
+}
+
+.blog-image-preview {
+    max-width: 100%;
+    border-radius: 0.25rem;
+    display: block;
+    margin-bottom: 0.5rem;
+}
+
+/* ---- The list screens (Posts, Categories, Comments) ----
+   One compact bar of filters, then rows. Every row action lives on its
+   context menu, reached by right-click, Shift+F10 or the ⋮. */
+.blog-screen { display: flex; flex-direction: column; gap: .75rem; }
+.blog-bar { display: flex; align-items: center; gap: .5rem; flex-wrap: wrap; }
+.blog-bar-end { display: flex; align-items: center; gap: .5rem; margin-left: auto; }
+.blog-search { width: 240px; max-width: 100%; height: 2rem; }
+.blog-select { width: auto; height: 2rem; padding-top: 0; padding-bottom: 0; }
+.blog-count { font-size: var(--dm-text-sm); color: var(--dm-text-muted); }
+.blog-state { margin: 1rem 0; text-align: center; color: var(--dm-text-muted); }
+.blog-note { margin: 0; display: flex; align-items: center; gap: .5rem; font-size: var(--dm-text-sm);
+    padding: .5rem .75rem; border-radius: var(--dm-radius-md);
+    background: color-mix(in srgb, var(--dm-warning, #d97706) 12%, transparent); }
+.blog-note--quiet { background: none; padding: 0; color: var(--dm-text-muted); }
+
+/* Status chips: a count and a filter in one. */
+.blog-chips { display: inline-flex; flex-wrap: wrap; gap: .25rem; }
+.blog-chip {
+    border: 1px solid var(--dm-border); background: none; color: var(--dm-text); cursor: pointer;
+    font: inherit; font-size: var(--dm-text-xs); padding: .15rem .6rem; border-radius: 999px;
+}
+.blog-chip b { font-weight: 600; margin-left: .15rem; color: var(--dm-text-muted); }
+.blog-chip:hover { border-color: var(--dm-primary); }
+.blog-chip.is-active { background: var(--dm-primary); border-color: var(--dm-primary); color: var(--dm-text-inverse, #fff); }
+.blog-chip.is-active b { color: inherit; }
+
+.blog-rows:not(:empty) { border: 1px solid var(--dm-border); border-radius: var(--dm-radius-md); overflow: hidden; }
+.blog-row {
+    display: flex; align-items: center; gap: .75rem; padding: .5rem .5rem .5rem .75rem; cursor: pointer;
+    border-bottom: 1px solid var(--dm-border); font-size: var(--dm-text-sm);
+}
+.blog-row:last-child { border-bottom: 0; }
+.blog-row:hover, .blog-row:focus-visible { background: var(--dm-surface-hover, rgba(127,127,127,.08)); outline: none; }
+.blog-row-main { flex: 1; min-width: 0; display: flex; flex-direction: column; }
+.blog-row-title { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.blog-row-sub { color: var(--dm-text-muted); font-size: var(--dm-text-xs); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.blog-row-sub:empty { display: none; }
+.blog-row-sub-inline { font-weight: 400; color: var(--dm-text-muted); margin-left: .35rem; }
+.blog-row-cats { flex: 0 1 12rem; min-width: 0; font-size: var(--dm-text-xs); color: var(--dm-text-muted);
+    overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.blog-row-slug { flex: 0 1 12rem; font-size: var(--dm-text-xs); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.blog-row-count { flex: 0 0 5rem; text-align: right; font-size: var(--dm-text-xs); color: var(--dm-text-muted); }
+.blog-row-date { flex: 0 0 6.5rem; text-align: right; font-size: var(--dm-text-xs); color: var(--dm-text-muted); white-space: nowrap; }
+.blog-kebab {
+    flex: 0 0 auto; border: 0; background: none; cursor: pointer; padding: 0 .3rem;
+    font-size: var(--dm-text-lg); line-height: 1.2; color: var(--dm-text-muted); border-radius: var(--dm-radius-sm);
+}
+.blog-kebab:hover { color: var(--dm-primary); background: var(--dm-surface-hover, rgba(127,127,127,.15)); }
+
+/* A comment reads as one line until clicked open. */
+.blog-comment-text { font-size: var(--dm-text-sm); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.blog-comment.is-open .blog-comment-text { white-space: pre-wrap; overflow-wrap: anywhere; padding: .25rem 0; }
+
+@media (max-width: 720px) {
+    .blog-row-cats, .blog-row-slug, .blog-row-count { display: none; }
+    .blog-bar-end { margin-left: 0; }
+}
+
+/* ---- Slideover panels (settings, category editor) ---- */
+.blog-panel { display: flex; flex-direction: column; gap: 1rem; padding: .25rem 0 .5rem; }
+.blog-field { display: flex; flex-direction: column; gap: .3rem; }
+.blog-field .form-label { display: flex; align-items: center; margin: 0; font-weight: 500; }
+.blog-field-row { flex-direction: row; align-items: center; justify-content: space-between; gap: 1rem; }
+.blog-panel-heading { display: flex; align-items: center; margin: .5rem 0 -.25rem; padding-top: .9rem; border-top: 1px solid var(--dm-border);
+    font-size: var(--dm-text-xs); font-weight: 600; letter-spacing: .05em; text-transform: uppercase; color: var(--dm-text-muted); }
+.blog-panel-link { align-self: flex-start; }
+.blog-panel-note { margin: 0; font-size: var(--dm-text-xs); color: var(--dm-warning, #d97706); }
+.blog-panel-actions { display: flex; align-items: center; gap: .5rem; padding-top: .75rem; border-top: 1px solid var(--dm-border); }
+.blog-panel-status { font-size: var(--dm-text-xs); color: var(--dm-text-muted); }
+.blog-spacer { flex: 1; }
+
+/* The old settings page renders the same panel in a card. */
+.blog-settings-card { max-width: 600px; }
+
+/* ── Post editor: layout picker ─────────────────────────────────────── */
+.blog-card-head { display: flex; align-items: center; gap: .25rem; }
+.blog-preview-btn { margin-left: auto; }
+.blog-layouts { display: grid; grid-template-columns: repeat(auto-fill, minmax(5.6rem, 1fr)); gap: .5rem; }
+.blog-layout { display: flex; flex-direction: column; align-items: center; gap: .35rem; padding: .5rem .35rem .45rem; cursor: pointer;
+    border: 1px solid var(--dm-border); border-radius: var(--dm-radius-md); background: none; color: var(--dm-text-muted); font: inherit; font-size: var(--dm-text-xs); }
+.blog-layout:hover { border-color: var(--dm-primary); color: var(--dm-text); }
+.blog-layout.is-on { border-color: var(--dm-primary); color: var(--dm-primary);
+    background: color-mix(in srgb, var(--dm-primary) 10%, transparent); box-shadow: 0 0 0 1px var(--dm-primary) inset; }
+.blog-layout-name { line-height: 1.2; text-align: center; overflow-wrap: anywhere; }
+/* Schematic thumbnails, drawn as masks so they take the theme's colour. */
+.blog-thumb { width: 3.6rem; height: 2.4rem; background: currentColor; -webkit-mask: var(--thumb) center / contain no-repeat; mask: var(--thumb) center / contain no-repeat; }
+.blog-thumb[data-thumb="classic"] { --thumb: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2060%2040'%3E%3Crect%20x='18'%20y='4'%20width='24'%20height='3'%20rx='1'%20opacity='1'/%3E%3Crect%20x='22'%20y='9'%20width='16'%20height='2'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='12'%20y='13'%20width='36'%20height='11'%20rx='1'%20opacity='0.45'/%3E%3Crect%20x='14'%20y='27'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='14'%20y='30'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='14'%20y='33'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='14'%20y='36'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3C/svg%3E"); }
+.blog-thumb[data-thumb="feature"] { --thumb: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2060%2040'%3E%3Crect%20x='0'%20y='0'%20width='60'%20height='20'%20rx='1'%20opacity='0.45'/%3E%3Crect%20x='6'%20y='11'%20width='30'%20height='3.2'%20rx='1'%20opacity='1'/%3E%3Crect%20x='6'%20y='16'%20width='20'%20height='1.8'%20rx='1'%20opacity='0.8'/%3E%3Crect%20x='14'%20y='24.0'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='14'%20y='27.2'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='14'%20y='30.4'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='14'%20y='33.6'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='14'%20y='36.8'%20width='32'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3C/svg%3E"); }
+.blog-thumb[data-thumb="minimal"] { --thumb: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2060%2040'%3E%3Crect%20x='20'%20y='5'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='20'%20y='9'%20width='22'%20height='3'%20rx='1'%20opacity='1'/%3E%3Crect%20x='20'%20y='16.0'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='20'%20y='19.2'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='20'%20y='22.4'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='20'%20y='25.6'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='20'%20y='28.8'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='20'%20y='32.0'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='20'%20y='35.2'%20width='20'%20height='1.5'%20rx='1'%20opacity='0.6'/%3E%3C/svg%3E"); }
+.blog-thumb[data-thumb="sidebar"] { --thumb: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2060%2040'%3E%3Crect%20x='4'%20y='4'%20width='30'%20height='3'%20rx='1'%20opacity='1'/%3E%3Crect%20x='4'%20y='10'%20width='34'%20height='9'%20rx='1'%20opacity='0.45'/%3E%3Crect%20x='4'%20y='22.0'%20width='34'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='4'%20y='25.2'%20width='34'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='4'%20y='28.4'%20width='34'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='4'%20y='31.6'%20width='34'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='4'%20y='34.8'%20width='34'%20height='1.6'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='42'%20y='10'%20width='14'%20height='10'%20rx='1'%20opacity='0.35'/%3E%3Crect%20x='43'%20y='23'%20width='10'%20height='1.4'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='43'%20y='26'%20width='10'%20height='1.4'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='43'%20y='29'%20width='10'%20height='1.4'%20rx='1'%20opacity='0.6'/%3E%3Crect%20x='43'%20y='32'%20width='10'%20height='1.4'%20rx='1'%20opacity='0.6'/%3E%3C/svg%3E"); }
+.blog-thumb[data-thumb="custom"] { --thumb: url("data:image/svg+xml,%3Csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2060%2040'%3E%3Crect%20x='6'%20y='5'%20width='48'%20height='30'%20rx='3'%20fill='none'%20stroke='%23000'%20stroke-width='1.6'%20stroke-dasharray='3%202.4'/%3E%3Crect%20x='28.8'%20y='14'%20width='2.4'%20height='12'%20rx='1'%20opacity='1'/%3E%3Crect%20x='24'%20y='18.8'%20width='12'%20height='2.4'%20rx='1'%20opacity='1'/%3E%3C/svg%3E"); }
+.blog-layout-desc { margin: .6rem 0 0; font-size: var(--dm-text-xs); color: var(--dm-text-muted); min-height: 2.2em; }
+
+/* ── Post editor: preview slideover ──────────────────────────────────── */
+.blog-preview { display: flex; flex-direction: column; gap: .6rem; height: 100%; min-height: 70vh; }
+.blog-preview-bar { display: flex; align-items: center; gap: .5rem; flex-wrap: wrap; }
+.blog-preview-bar .form-select { width: auto; }
+.blog-preview-state { font-size: var(--dm-text-xs); color: var(--dm-text-muted); }
+.blog-seg { display: inline-flex; border: 1px solid var(--dm-border); border-radius: var(--dm-radius-md); overflow: hidden; }
+.blog-seg button { border: 0; background: none; padding: .3rem .55rem; cursor: pointer; color: var(--dm-text-muted); display: inline-flex; }
+.blog-seg button + button { border-left: 1px solid var(--dm-border); }
+.blog-seg button.is-on { background: color-mix(in srgb, var(--dm-primary) 14%, transparent); color: var(--dm-primary); }
+.blog-preview-stage { flex: 1; display: flex; justify-content: center; overflow: auto; padding: .5rem;
+    border: 1px solid var(--dm-border); border-radius: var(--dm-radius-md); background: repeating-linear-gradient(45deg, transparent 0 8px, rgba(127,127,127,.06) 8px 16px); }
+.blog-preview-stage iframe { width: 100%; height: 100%; min-height: 65vh; border: 0; border-radius: var(--dm-radius-sm); background: #fff;
+    box-shadow: 0 4px 18px rgba(0,0,0,.18); transition: width .2s ease; }
+.blog-preview-stage.is-tablet iframe { width: 820px; max-width: 100%; }
+.blog-preview-stage.is-phone iframe { width: 390px; max-width: 100%; }
+
+/* ── Post editor header: Back, title, save state, actions ──────────────── */
+.blog-editor-bar { display: flex; align-items: center; gap: .6rem; flex-wrap: wrap; }
+.blog-editor-bar .view-header-actions { margin-left: auto; display: flex; align-items: center; gap: .4rem; flex-wrap: wrap; }
+.blog-editor-title { font-size: var(--dm-text-sm); font-weight: 600; color: var(--dm-text-muted); }
+.blog-save-state { font-size: var(--dm-text-xs); color: var(--dm-text-muted); }
+.blog-save-state.is-dirty { color: var(--dm-warning, #d97706); }
+.blog-save-state.is-dirty::before { content: '●'; margin-right: .3rem; font-size: .7em; vertical-align: .1em; }
+.blog-editor-bar .btn { display: inline-flex; align-items: center; gap: .35rem; }

package/plugins/blog/admin/templates/blog.html

@@ -1,57 +1,39 @@
-<div class="view-header">
-  <h1><span data-icon="file-text"></span> Blog Posts</h1>
-  <button id="btn-new-post" class="btn btn-primary">
-    <span data-icon="plus"></span> New Post
-  </button>
-</div>
+<!-- No heading: the banner above is the title. Bound with M.applyBindings - see
+     admin/views/blog.js, which also inserts the row and chip templates (the router
+     renders this file through _.render first, which would eat any {{…}}). -->
+<div class="blog-screen">
+  <div class="blog-bar">
+    <div class="blog-chips" data-each="chips.value key=key"></div>
+    <span data-help="Published posts are live. Drafts are only visible here. Scheduled posts go live on their date. Click a count to show only those."></span>
+    <span class="blog-bar-end">
+      <button type="button" class="btn btn-sm btn-primary" data-on-click="create">
+        <span data-icon="plus" data-icon-size="14"></span> New post
+      </button>
+      <button type="button" class="btn btn-sm btn-ghost blog-more" aria-label="More" title="View the blog, sample posts, layouts">⋮</button>
+      <span data-help-title="Sample posts and layouts"
+            data-help="⋮ adds a set of sample posts - spread over every layout, with categories and pictures - so there is something to look at before you have written anything. Remove them from the same menu; only the samples go. Each post's look is a block you can edit under Blocks (blog-post-… and blog-card-…)."></span>
+    </span>
+  </div>
 
-<div class="grid grid-cols-4 gap-3 mb-4">
-  <div class="card stat-card"><div class="card-body">
-    <div class="stat-icon"><span data-icon="file-text"></span></div>
-    <div>
-      <div class="stat-value" id="kpi-total">-</div>
-      <div class="stat-label">Total</div>
-    </div>
-  </div></div>
-  <div class="card stat-card"><div class="card-body">
-    <div class="stat-icon stat-icon--success"><span data-icon="check-circle"></span></div>
-    <div>
-      <div class="stat-value" id="kpi-published">-</div>
-      <div class="stat-label">Published</div>
-    </div>
-  </div></div>
-  <div class="card stat-card"><div class="card-body">
-    <div class="stat-icon"><span data-icon="edit"></span></div>
-    <div>
-      <div class="stat-value" id="kpi-drafts">-</div>
-      <div class="stat-label">Drafts</div>
-    </div>
-  </div></div>
-  <div class="card stat-card"><div class="card-body">
-    <div class="stat-icon stat-icon--warning"><span data-icon="clock"></span></div>
-    <div>
-      <div class="stat-value" id="kpi-scheduled">-</div>
-      <div class="stat-label">Scheduled</div>
-    </div>
-  </div></div>
-</div>
+  <div class="blog-bar">
+    <input type="search" class="form-input blog-search" placeholder="Search posts…" aria-label="Search posts"
+           data-model="query.value">
+    <select class="form-select blog-select" aria-label="Category"
+            data-options="categoryOptions.value" data-options-text="name" data-options-value="id"
+            data-options-caption="'All categories'" data-model="category.value"></select>
+    <select class="form-select blog-select" aria-label="Sort" data-model="sort.value">
+      <option value="newest">Newest first</option>
+      <option value="oldest">Oldest first</option>
+      <option value="title">Title, A to Z</option>
+    </select>
+    <button type="button" class="btn btn-sm btn-ghost" data-on-click="reset" data-if="canReset.value">Clear filters</button>
+    <span data-help="Search matches titles, excerpts and slugs. Right-click a post, or use its ⋮, to publish, unpublish, duplicate or delete it."></span>
+  </div>
+
+  <p class="blog-state" data-if="loading.value">Loading posts…</p>
+  <p class="blog-state" data-if="isEmpty.value" data-bind-text="emptyText.value"></p>
 
-<div class="card mb-3">
-  <div class="card-body">
-    <div class="flex gap-2 flex-wrap items-center">
-      <select id="filter-status" class="form-select blog-filter-select">
-        <option value="">All statuses</option>
-        <option value="draft">Draft</option>
-        <option value="scheduled">Scheduled</option>
-        <option value="published">Published</option>
-      </select>
-      <select id="filter-category" class="form-select blog-filter-select">
-        <option value="">All categories</option>
-      </select>
-      <input id="filter-search" type="search" class="form-input blog-filter-search" placeholder="Search title or excerpt…">
-      <button id="filter-reset" class="btn btn-ghost btn-sm">Reset</button>
-    </div>
+  <div class="blog-list">
+    <div class="blog-rows" data-each="rows.value key=id"></div>
   </div>
 </div>
-
-<div id="posts-table"></div>

package/plugins/blog/admin/templates/categories.html

@@ -1,7 +1,20 @@
-<div class="view-header">
-  <h1><span data-icon="folder"></span> Blog Categories</h1>
-  <button id="btn-new-category" class="btn btn-primary">
-    <span data-icon="plus"></span> New Category
-  </button>
+<!-- No heading: the banner above is the title. Bound with M.applyBindings - see
+     admin/views/categories.js, which also inserts the row template. -->
+<div class="blog-screen">
+  <div class="blog-bar">
+    <span class="blog-count" data-bind-text="countText.value"></span>
+    <span data-help="Categories group posts on the site, each with its own page at /blog/category/<slug>. Right-click a category, or use its ⋮, to edit it, see its posts or delete it."></span>
+    <span class="blog-bar-end">
+      <button type="button" class="btn btn-sm btn-primary" data-on-click="create">
+        <span data-icon="plus" data-icon-size="14"></span> New category
+      </button>
+    </span>
+  </div>
+
+  <p class="blog-state" data-if="loading.value">Loading categories…</p>
+  <p class="blog-state" data-if="isEmpty.value">No categories yet - New category adds one.</p>
+
+  <div class="blog-list">
+    <div class="blog-rows" data-each="rows.value key=id"></div>
+  </div>
 </div>
-<div id="categories-table"></div>

package/plugins/blog/admin/templates/comments.html

@@ -1,11 +1,28 @@
-<div class="view-header">
-  <h1><span data-icon="message-circle"></span> Blog Comments</h1>
-</div>
+<!-- No heading: the banner above is the title. Bound with M.applyBindings - see
+     admin/views/comments.js, which also inserts the row and chip templates. -->
+<div class="blog-screen">
+  <div class="blog-bar">
+    <div class="blog-chips" data-each="chips.value key=key"></div>
+    <span data-help="Pending comments wait for you before they appear on the site; Approved ones are live; Rejected and Spam never show. Right-click a comment, or use its ⋮, to moderate it. Click it to read all of it."></span>
+    <span class="blog-bar-end">
+      <input type="search" class="form-input blog-search" placeholder="Search comments…" aria-label="Search comments"
+             data-model="query.value">
+      <button type="button" class="btn btn-sm btn-ghost" data-on-click="approveAll" data-bind-disabled="!pendingCount.value" title="Approve every pending comment">
+        <span data-icon="check-circle" data-icon-size="14"></span> Approve all pending
+      </button>
+    </span>
+  </div>
 
-<div class="tab-list mb-3">
-  <button class="tab-item active" data-tab="pending">Pending</button>
-  <button class="tab-item" data-tab="approved">Approved</button>
-  <button class="tab-item" data-tab="spam">Spam</button>
-</div>
+  <p class="blog-note" data-if="commentsOff.value">
+    Comments are switched off, so readers cannot leave new ones.
+    <button type="button" class="btn btn-sm btn-ghost" data-on-click="settings">Blog settings</button>
+  </p>
+  <p class="blog-note blog-note--quiet" data-if="!commentsOff.value" data-bind-text="moderationText.value"></p>
 
-<div id="comments-table"></div>
+  <p class="blog-state" data-if="loading.value">Loading comments…</p>
+  <p class="blog-state" data-if="isEmpty.value" data-bind-text="emptyText.value"></p>
+
+  <div class="blog-list">
+    <div class="blog-rows" data-each="rows.value key=id"></div>
+  </div>
+</div>