domma-cms 0.6.4 → 0.6.6

package/CLAUDE.md

@@ -0,0 +1,159 @@
+# Domma CMS — AI Assistant Guide
+
+## Project Overview
+
+This is a **Domma CMS** project. Stack: Fastify 5 (ESM) backend, Domma SPA admin, SSR public site.
+Content is Markdown + YAML frontmatter in `content/pages/`. Config is JSON in `config/`.
+Server runs on port **4096** by default (`config/server.json`).
+
+## Domma Framework — Use These, Not Vanilla JS
+
+Domma provides built-in solutions. Never use vanilla JS equivalents.
+
+| Alias                                            | Purpose                                  | NOT this                           |
+|--------------------------------------------------|------------------------------------------|------------------------------------|
+| `$('#el')`                                       | DOM selection + manipulation             | `document.querySelector()`         |
+| `S.set/get`                                      | Storage                                  | `localStorage.setItem/getItem`     |
+| `H.get/post/put/delete`                          | HTTP                                     | `fetch()`, `XMLHttpRequest`        |
+| `D()`                                            | Date manipulation (Moment-style)         | Manual `Date` arithmetic           |
+| `_`                                              | Array/object utils (`_.map`, `_.filter`) | Always evaluate if native suffices |
+| `M.create(blueprint)`                            | Reactive data models                     | Manual state management            |
+| `F.create(selector, {blueprint})`                | Form generation                          | Manual `<form>` HTML               |
+| `E.toast/confirm/modal/tabs/accordion/slideover` | UI components                            | Manual HTML/CSS/JS components      |
+| `I.scan()` / `<span data-icon="name">`           | Icons                                    | Manual SVG or icon fonts           |
+| `T.create(selector, {data, columns})`            | Tables                                   | Manual `<table>` generation        |
+
+## Architecture
+
+```
+server/          Fastify 5 API + SSR (DO NOT modify — upstream-replaced on update)
+admin/           Domma SPA admin panel (DO NOT modify — upstream-replaced on update)
+public/js/       Public site JS (site.js + component init)
+public/css/      Site stylesheet (site.css is yours to edit)
+content/pages/   Markdown pages (URL → file mapping below)
+content/media/   Uploaded media
+content/users/   User accounts (JSON)
+content/collections/  Collection entries
+config/          All configuration JSON (see Config section)
+plugins/         CMS plugins (yours to create/modify)
+docs/            Reference documentation
+```
+
+**URL → file mapping:**
+
+- `/` → `content/pages/index.md`
+- `/about` → `content/pages/about.md`
+- `/services` → `content/pages/services/index.md`
+
+## Content Pages
+
+Pages are Markdown files with YAML frontmatter:
+
+```markdown
+---
+title: Page Title
+layout: default          # default | landing | blank
+description: SEO desc
+---
+
+Page content here. Shortcodes work anywhere in the body.
+```
+
+### Shortcodes (18 types — full syntax in `docs/markdown-shortcodes.md`)
+
+| Shortcode                               | Purpose                                            |
+|-----------------------------------------|----------------------------------------------------|
+| `[card]`                                | Card container (optional title, collapsible, icon) |
+| `[grid cols="N"]` / `[col]`             | CSS Grid layout (Domma Grid — NOT `.col` class)    |
+| `[row]` / `[col]`                       | Row/column layout                                  |
+| `[slideover trigger="..." title="..."]` | Slide-over panel                                   |
+| `[dconfig]{...}[/dconfig]`              | Declarative page config (JSON)                     |
+| `[tabs]` / `[tab title="..."]`          | Tab panels                                         |
+| `[accordion]` / `[item title="..."]`    | Accordion sections                                 |
+| `[carousel]` / `[slide]`                | Image/content carousel                             |
+| `[hero title="..." tagline="..."]`      | Hero section                                       |
+| `[table]`                               | Data table (Markdown table inside)                 |
+| `[badge variant="..."]`                 | Badge/label                                        |
+| `[countdown to="..." /]`                | Countdown timer                                    |
+| `[timeline]` / `[event]`                | Timeline component                                 |
+| `[spacer /]`                            | Vertical spacer                                    |
+| `[center]`                              | Centre-align content                               |
+| `[icon name="..." /]`                   | Inline icon                                        |
+| `[cta action="..."]`                    | Collection action trigger (admin)                  |
+
+### Shortcode Nesting Rules
+
+Processing order (innermost first):
+
+1. `[dconfig]` — always first
+2. `[grid]` / `[row]` / `[col]`
+3. `[card]`
+4. `[tabs]`, `[accordion]`, `[carousel]`, `[hero]`, `[table]`, `[badge]`, `[countdown]`, `[timeline]`, `[spacer]`,
+   `[center]`, `[icon]`, `[cta]`
+5. `[slideover]` — always last (can contain anything above)
+
+Safe nesting: `[card]` inside `[slideover]`, `[grid]` inside `[slideover]`, `[col]` inside `[grid]`.
+Do NOT nest `[slideover]` inside another `[slideover]`.
+
+## Public Site Patterns
+
+The server injects these globals on every public page:
+
+```js
+window.__CMS_NAV__      // Navigation config (brand, items)
+window.__CMS_SITE__     // Site config (title, theme, footer, smtp, etc.)
+window.__CMS_DCONFIG__  // Page-level declarative config (merged with inline [dconfig])
+```
+
+`public/js/site.js` reads these to initialise the Domma navbar, footer, and page components.
+Domma components (tabs, accordion, carousel, etc.) in `.page-body` are auto-initialised by `site.js`.
+Add custom public-site JS to `public/js/site.js` or new files loaded from `public/js/`.
+
+## Plugin Development
+
+Each plugin needs exactly 3 files:
+
+```
+plugins/my-plugin/
+  plugin.json   Required manifest (name, displayName, version, description, author, date, icon)
+  plugin.js     Default export: Fastify plugin function
+  config.js     Default export: plain object of config defaults
+```
+
+See `docs/plugin-development.md` for full plugin API, hooks, and injection points.
+
+## Config Reference
+
+| File                     | Owner                 | Purpose                            |
+|--------------------------|-----------------------|------------------------------------|
+| `config/server.json`     | CMS (merge on update) | Port, host, CORS, uploads          |
+| `config/auth.json`       | CMS (merge on update) | JWT expiry, bcrypt rounds          |
+| `config/content.json`    | CMS (merge on update) | Content dirs, page defaults        |
+| `config/presets.json`    | CMS (merge on update) | Preset collection schemas          |
+| `config/site.json`       | Yours                 | Site title, theme, footer, SMTP    |
+| `config/navigation.json` | Yours                 | Navbar brand + items               |
+| `config/plugins.json`    | Yours                 | Plugin enabled/disabled + settings |
+
+See `docs/configuration.md` for full schema reference.
+
+## Key Gotchas
+
+1. **Navigation sub-items**: use `items` key, NOT `children` — Domma navbar reads `items`.
+2. **Domma collections**: use `.get(0)` NOT `[0]` to get native DOM elements.
+3. **`.html()` strips interactive elements**: `E.modal().setContent(x)` also strips HTML — use light DOM slot
+   projection (`modal.element.appendChild(myDomElement)`) for buttons/inputs.
+4. **Landing layout**: `layout: landing` removes the standard page wrapper — add your own container CSS.
+5. **Grid shortcode**: uses Domma Grid (`grid`, `grid-cols-N`) — NOT the `.col` compatibility class.
+6. **Event delegation namespaces**: `$(doc).on('click.ns', '.sel', cb)` silently fails — use direct `addEventListener`
+   or unnamespaced `$(el).on('click', cb)`.
+7. **Tabs component classes**: wrapper `.tabs`, list `.tab-list`, trigger `button.tab-item`, panel `.tab-panel` (not
+   `.tabs-nav`, `.tabs-content`, `.tabs-pane`).
+
+## Docs
+
+- `docs/getting-started.md` — Installation, first run, setup wizard
+- `docs/markdown-shortcodes.md` — Full shortcode syntax and examples
+- `docs/configuration.md` — Complete config schema for all JSON files
+- `docs/plugin-development.md` — Plugin API, lifecycle hooks, injection points
+- `docs/theming.md` — Available themes, CSS variables, customisation
+- `docs/api-reference.md` — REST API endpoints (for headless / external integrations)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "domma-cms",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "File-based CMS powered by Domma and Fastify. Run npx domma-cms my-site to create a new project.",
   "type": "module",
   "main": "server/server.js",
@@ -29,7 +29,10 @@
     "build": "node scripts/build.js",
     "delete-users": "node -e \"import('fs').then(({readdirSync,rmSync})=>{const d='content/users';readdirSync(d).filter(f=>f.endsWith('.json')).forEach(f=>{rmSync(d+'/'+f);console.log('deleted',f)})})\"",
     "start": "node server/server.js",
-    "start:cluster": "pm2 start server/server.js -i max --name domma-cms",
+    "pm2:start": "pm2 start ecosystem.config.cjs --env production",
+    "pm2:stop": "pm2 stop ecosystem.config.cjs",
+    "pm2:restart": "pm2 reload ecosystem.config.cjs",
+    "pm2:logs": "pm2 logs domma-cms",
     "dev": "node --watch server/server.js",
     "prod": "node server/server.js",
     "setup": "node scripts/setup.js",

package/plugins/example-analytics/stats.json

@@ -6,7 +6,7 @@
   "/resources/typography": 4,
   "/resources": 13,
   "/resources/shortcodes": 14,
-  "/resources/cards": 14,
+  "/resources/cards": 15,
   "/resources/interactive": 13,
   "/resources/grid": 6,
   "/forms": 14,

package/scripts/build.js

@@ -20,6 +20,7 @@ const COPY_AS_IS = [
   'scripts',
   'package.json',
   'README.md',
+    'CLAUDE.md',
   'LICENSE',
   '.npmignore',
 ];

package/server/services/markdown.js

@@ -64,7 +64,7 @@ async function loadBlockTemplate(blockName) {
  * @param {object|null} ctaOpts  - Optional CTA button options
  * @returns {string}
  */
-function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts) {
+function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts, cols) {
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
     }
@@ -88,7 +88,12 @@ function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts) {
         return html;
     });
 
-    return `<div class="dm-collection-display dm-collection-blocks">\n${items.join('\n')}\n</div>`;
+    const validCols = ['2', '3', '4', '5', '6'].includes(String(cols)) ? cols : '';
+    const wrapperClass = validCols
+        ? `dm-collection-display dm-collection-blocks grid grid-cols-${validCols} gap-4`
+        : 'dm-collection-display dm-collection-blocks';
+
+    return `<div class="${wrapperClass}">\n${items.join('\n')}\n</div>`;
 }
 
 function renderCollectionTable(slug, entries, visibleFields, attrs, ctaOpts) {
@@ -333,7 +338,8 @@ async function processCollectionBlocks(markdown) {
                 if (blockName) {
                     try {
                         const tpl = await loadBlockTemplate(blockName);
-                        replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts);
+                        const cols = attrs.cols || '';
+                        replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts, cols);
                     } catch {
                         replacement = `<div class="dm-collection-display dm-collection-empty"><p>Block template &ldquo;${escapeHtmlText(blockName)}&rdquo; not found.</p></div>`;
                     }