domma-cms 0.18.0 → 0.21.0

package/server/services/markdown.js

@@ -11,6 +11,8 @@ import {fileURLToPath} from 'url';
 import {applyTransforms, getSanitizeExtensions, getShortcodeProcessors} from './hooks.js';
 import {getConfig} from '../config.js';
 import {getCollection, listEntries} from './collections.js';
+import {getMenu, resolveLocation} from './menus.js';
+import {checkVisibility} from '../middleware/auth.js';
 
 const __dirname_md = path.dirname(fileURLToPath(import.meta.url));
 const BLOCKS_DIR = path.resolve(__dirname_md, '../../content/blocks');
@@ -22,7 +24,7 @@ const BUILTIN_SHORTCODES = new Set([
     'text', 'button', 'link', 'cta', 'grid', 'row', 'col', 'card',
     'banner', 'slideover', 'counter', 'celebrate', 'firework', 'fireworks', 'scribe',
     'reveal', 'breathe', 'pulse', 'shake', 'scramble', 'ripple', 'twinkle',
-    'ticker-tape', 'animate', 'ambient', 'list-group',
+    'ticker-tape', 'animate', 'ambient', 'list-group', 'menu',
 ]);
 
 // Configure marked for safe output
@@ -43,13 +45,49 @@ function escapeHtmlText(str) {
         .replace(/"/g, '"');
 }
 
-function sortEntries(entries, sort, order) {
-    const dir = order === 'asc' ? 1 : -1;
-    return [...entries].sort((a, b) => {
-        const av = sort === 'createdAt' ? (a.meta?.createdAt || '') : (a.data?.[sort] ?? '');
-        const bv = sort === 'createdAt' ? (b.meta?.createdAt || '') : (b.data?.[sort] ?? '');
-        return av < bv ? -dir : av > bv ? dir : 0;
-    });
+/**
+ * Build a structured filter object from `[collection]` shortcode attributes.
+ *
+ * Two attribute styles are recognised and merged (with where_* taking precedence):
+ *
+ *   1. Legacy `where="field1=value1,field2=value2"` — equality only, comma-separated.
+ *      Predates the structured DSL; preserved for backward compat.
+ *
+ *   2. New `where_<field>[_<op>]="value"` attributes — full operator support.
+ *      Example: `where_location="London" where_salary_gte="50000"
+ *               where_tags_in="remote,hybrid"`.
+ *      Maps directly onto the filterEngine DSL.
+ *
+ * The combined object is passed to `listEntries({ filter })` so the work is
+ * pushed down to the adapter (Mongo gets a native query; File runs in-memory).
+ *
+ * @param {Record<string, string>} attrs - All parsed shortcode attributes
+ * @returns {Record<string, string>} Filter object suitable for filterEngine
+ */
+function buildShortcodeFilter(attrs) {
+    const filter = {};
+
+    // Legacy where="a=1,b=2"
+    const legacy = typeof attrs.where === 'string' ? attrs.where.trim() : '';
+    if (legacy) {
+        for (const part of legacy.split(',')) {
+            const eq = part.indexOf('=');
+            if (eq === -1) continue;
+            const key = part.slice(0, eq).trim();
+            const val = part.slice(eq + 1).trim();
+            if (key) filter[key] = val;
+        }
+    }
+
+    // Modern where_<field>[_<op>]="value"
+    for (const [k, v] of Object.entries(attrs)) {
+        if (!k.startsWith('where_')) continue;
+        const inner = k.slice('where_'.length);
+        if (!inner) continue;
+        filter[inner] = v;
+    }
+
+    return filter;
 }
 
 /**
@@ -306,12 +344,79 @@ async function processStaticBlocks(content, tagSet) {
     return output;
 }
 
+/**
+ * Detect a stored file reference — the object shape produced by the form's
+ * multipart parser: { url, name, size?, mime? }.
+ */
+function isFileRef(v) {
+    return v && typeof v === 'object' && typeof v.url === 'string' && typeof v.name === 'string';
+}
+
+/**
+ * Resolve the display value for one field on one entry.
+ *
+ * For a `type: reference` field, returns the resolved label from `_refs`
+ * (set by `references.resolveReferences()`); arrays join with ", ", missing
+ * targets render as "<id> (missing)". For a `type: file` field (or any field
+ * holding a stored file ref), returns the filename. Everything else returns
+ * the raw value with `null`/`undefined` collapsed to '' and arrays joined.
+ *
+ * @param {object} entry
+ * @param {object} field
+ * @returns {string}
+ */
+function displayValue(entry, field) {
+    if (field.type === 'reference') {
+        const r = entry._refs?.[field.name];
+        if (r != null) {
+            if (Array.isArray(r)) return r.map(x => x.missing ? `${x.id} (missing)` : x.display).join(', ');
+            return r.missing ? `${r.id} (missing)` : r.display;
+        }
+    }
+    const raw = entry.data?.[field.name];
+    if (isFileRef(raw)) return raw.name;
+    if (raw == null) return '';
+    if (Array.isArray(raw)) return raw.join(', ');
+    return String(raw);
+}
+
+/**
+ * As `displayValue` but returns an HTML fragment. References with a
+ * `linkTemplate` render as `<a>`; file references render as `<img>` (image
+ * mimes) or `<a download>` (everything else). The caller is responsible
+ * for sanitisation — values pass through `escapeHtmlText`/`escapeAttr`.
+ */
+function displayValueHtml(entry, field) {
+    if (field.type === 'reference') {
+        const r = entry._refs?.[field.name];
+        if (r != null) {
+            const render = (one) => {
+                if (one.missing) return escapeHtmlText(`${one.id} (missing)`);
+                const text = escapeHtmlText(one.display);
+                return one.link ? `<a href="${escapeAttr(one.link)}">${text}</a>` : text;
+            };
+            if (Array.isArray(r)) return r.map(render).join(', ');
+            return render(r);
+        }
+    }
+    const raw = entry.data?.[field.name];
+    if (isFileRef(raw)) {
+        const url  = escapeAttr(raw.url);
+        const name = escapeHtmlText(raw.name);
+        if (String(raw.mime || '').startsWith('image/')) {
+            return `<a href="${url}" target="_blank" rel="noopener"><img src="${url}" alt="${name}" loading="lazy" class="dm-file-thumb"></a>`;
+        }
+        return `<a href="${url}" download>${name}</a>`;
+    }
+    return escapeHtmlText(displayValue(entry, field));
+}
+
 function renderCollectionTable(slug, entries, visibleFields, attrs, ctaOpts) {
     const columns = visibleFields.map(f => ({key: f.name, title: f.label || f.name}));
     const rows = entries.map(e => {
         const row = {};
         visibleFields.forEach(f => {
-            row[f.name] = e.data?.[f.name] ?? '';
+            row[f.name] = displayValue(e, f);
         });
         if (ctaOpts) row._entryId = e.id || '';
         return row;
@@ -337,11 +442,12 @@ function renderCollectionCards(entries, visibleFields, titleField, columns, empt
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
     }
     const cards = entries.map(e => {
-        const title = titleField ? escapeHtmlText(e.data?.[titleField] ?? '') : '';
+        const titleFld = visibleFields.find(f => f.name === titleField);
+        const title = titleFld ? displayValueHtml(e, titleFld) : (titleField ? escapeHtmlText(e.data?.[titleField] ?? '') : '');
         const body  = visibleFields
             .filter(f => f.name !== titleField)
             .map(f => {
-                const val = escapeHtmlText(e.data?.[f.name] ?? '');
+                const val = displayValueHtml(e, f);
                 return val ? `<p><strong>${escapeHtmlText(f.label || f.name)}:</strong> ${val}</p>` : '';
             }).join('');
         let footer = '';
@@ -363,11 +469,12 @@ function renderCollectionList(entries, visibleFields, titleField, emptyMsg, ctaO
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
     }
     const items = entries.map(e => {
-        const title = titleField ? escapeHtmlText(e.data?.[titleField] ?? '') : '';
+        const titleFld = visibleFields.find(f => f.name === titleField);
+        const title = titleFld ? displayValueHtml(e, titleFld) : (titleField ? escapeHtmlText(e.data?.[titleField] ?? '') : '');
         const rest  = visibleFields
             .filter(f => f.name !== titleField)
             .map(f => {
-                const val = escapeHtmlText(e.data?.[f.name] ?? '');
+                const val = displayValueHtml(e, f);
                 return val ? `<p>${val}</p>` : '';
             }).join('');
         let ctaHtml = '';
@@ -478,6 +585,17 @@ async function processViewBlocks(markdown, tagSet) {
         }
         tagSet?.add(`view:${slug}`);
 
+        // Interactive `[view]` — when searchable / sortable / paginate is set,
+        // emit a Collection Browser shell against the view's executed dataset.
+        // No filter rail (views own their own filter logic) but search, sort,
+        // and pagination work as on `[collection]`. This is how cross-collection
+        // browsing happens without the shortcode itself having to learn joins.
+        if (isInteractiveCollection(attrs)) {
+            const shell = await renderViewBrowserShell(attrs);
+            result = result.replace(fullMatch, shell);
+            continue;
+        }
+
         const displayAttr = attrs.display || '';
         const emptyMsg   = attrs.empty      || 'No results found';
         const titleField = attrs['title-field'] || '';
@@ -601,114 +719,433 @@ async function processCollectionBlocks(markdown, tagSet) {
         }
         tagSet?.add(`collection:${slug}`);
 
-        const display    = attrs.display || 'table';
-        const limitAttr  = parseInt(attrs.limit, 10) || 0;
-        const sort       = attrs.sort  || 'createdAt';
-        const order      = attrs.order || 'desc';
-        const titleField = attrs['title-field'] || '';
-        const columns    = attrs.columns || '3';
-        const emptyMsg   = attrs.empty  || 'No entries found';
-        const fieldFilter = attrs.fields ? attrs.fields.split(',').map(f => f.trim()).filter(Boolean) : null;
-        const ctaAction  = attrs.cta || '';
-        const ctaOpts    = ctaAction ? {
-            action:  ctaAction,
+        // scope="mine" can't share the per-role page cache (data is per-user),
+        // so emit a hydration placeholder. The public site JS POSTs the raw
+        // attrs to /api/collections/render-scope, which re-runs renderCollectionFragment
+        // server-side with `createdBy = <current user>` injected — keeping rendering
+        // logic in ONE place (no client-side template duplication).
+        if (attrs.scope === 'mine') {
+            const encoded    = Buffer.from(JSON.stringify(attrs), 'utf8').toString('base64');
+            const wrapperCls = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
+            const wrapperId  = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+            result = result.replace(fullMatch,
+                `<div class="dm-collection-hydrate${wrapperCls}"${wrapperId} ` +
+                `data-collection-scope="mine" data-collection-attrs="${encoded}">` +
+                `<div class="dm-collection-loading"><p>${escapeHtmlText('Loading…')}</p></div>` +
+                `</div>`
+            );
+            continue;
+        }
+
+        // Interactive Collection Browser — searchable / filterable / sortable
+        // turns the block into a full client-side browser with auto-derived
+        // filter UI, sort dropdown, search box, and pagination. We still emit
+        // a server-rendered fragment as the no-JS fallback (visible until the
+        // browser hydrates and replaces it).
+        if (isInteractiveCollection(attrs)) {
+            const shell = await renderCollectionBrowserShell(attrs, schemaForFallback => schemaForFallback);
+            result = result.replace(fullMatch, shell);
+            continue;
+        }
+
+        const replacement = await renderCollectionFragment(attrs);
+        result = result.replace(fullMatch, replacement);
+    }
+
+    return restore(result);
+}
+
+/**
+ * Detect whether a `[collection]` shortcode opts into the interactive Browser.
+ * Any of `searchable`, `sortable`, `filterable`, or `paginate` flips it on.
+ *
+ * @param {Record<string, unknown>} attrs
+ * @returns {boolean}
+ */
+function isInteractiveCollection(attrs) {
+    return isTruthyAttr(attrs.searchable)
+        || isTruthyAttr(attrs.sortable)
+        || !!attrs.filterable
+        || isTruthyAttr(attrs.paginate);
+}
+
+/**
+ * Coerce a shortcode attribute value to a boolean. Bare flags parse as `true`,
+ * `"true"` / `"1"` are truthy, everything else is false.
+ *
+ * @param {unknown} v
+ * @returns {boolean}
+ */
+function isTruthyAttr(v) {
+    return v === true || v === 'true' || v === '1';
+}
+
+/**
+ * Build the hydration shell for the Collection Browser component.
+ *
+ * The shell ships three things to the client:
+ *   1. **config**  — display mode, columns, page size, which fields are
+ *                    sortable/filterable, mode (client|server), labels.
+ *   2. **schema**  — the collection's field definitions, used to auto-derive
+ *                    the right filter control per field type (text → input,
+ *                    select → dropdown, number → range, date → from/to, etc.).
+ *   3. **data**    — for mode=client, ALL entries (capped at `maxClientEntries`)
+ *                    so filtering is instant. For mode=server, only the first
+ *                    page is shipped and subsequent pages are fetched via the
+ *                    existing `/api/collections/:slug/public` endpoint with
+ *                    `filter[…]`, `sort`, `order`, `page`, `limit` params.
+ *
+ * A static server-rendered fragment is also embedded as the no-JS fallback —
+ * visible until `collection-browser.js` hydrates and replaces the shell.
+ *
+ * @param {Record<string, string>} attrs - Parsed shortcode attributes
+ * @returns {Promise<string>} HTML for the hydration shell
+ */
+async function renderCollectionBrowserShell(attrs) {
+    const slug = attrs.slug;
+    const pageSize = parseInt(attrs['page-size'], 10) || 12;
+    const declaredMode = attrs.mode === 'server' ? 'server' : 'client';
+    const maxClientEntries = parseInt(attrs['max-client-entries'], 10) || 1000;
+
+    // Parse comma lists once.
+    const filterable = (attrs.filterable && typeof attrs.filterable === 'string')
+        ? attrs.filterable.split(',').map(s => s.trim()).filter(Boolean) : [];
+    const sortableFields = (typeof attrs.sortable === 'string' && attrs.sortable !== 'true' && attrs.sortable !== 'false')
+        ? attrs.sortable.split(',').map(s => s.trim()).filter(Boolean) : [];
+
+    let schema  = null;
+    let entries = [];
+    let total   = 0;
+    let mode    = declaredMode;
+
+    try {
+        schema = await getCollection(slug);
+        if (!schema) throw new Error('not found');
+
+        // Build the seed listEntries() opts — push any author-baked where_* filter
+        // and the initial sort/order down to the adapter, just like the static path.
+        const seedFilter = buildShortcodeFilter(attrs);
+        const seedOpts   = {
+            sort:  attrs.sort  || 'createdAt',
+            order: attrs.order || 'desc'
+        };
+        if (Object.keys(seedFilter).length) seedOpts.filter = seedFilter;
+
+        seedOpts.resolveRefs = true;     // ship resolved labels in the inline payload
+
+        if (mode === 'client') {
+            // Cap the inline payload to avoid bloating cached HTML for huge collections.
+            // If we hit the cap, transparently downgrade to mode=server so pagination
+            // still works — the author gets correct UX even on misconfigured pages.
+            seedOpts.limit = maxClientEntries + 1;
+            const r = await listEntries(slug, seedOpts);
+            if (r.total > maxClientEntries) {
+                mode    = 'server';
+                seedOpts.limit = pageSize;
+                seedOpts.page  = 1;
+                const r2 = await listEntries(slug, seedOpts);
+                entries = r2.entries;
+                total   = r2.total;
+            } else {
+                entries = r.entries;
+                total   = r.total;
+            }
+        } else {
+            // mode=server — ship only the first page; subsequent pages fetched live.
+            seedOpts.limit = pageSize;
+            seedOpts.page  = 1;
+            const r = await listEntries(slug, seedOpts);
+            entries = r.entries;
+            total   = r.total;
+        }
+    } catch {
+        // Slug unknown / read error — emit an empty shell so the page still renders.
+        schema  = {fields: [], title: attrs.slug};
+        entries = [];
+        total   = 0;
+    }
+
+    const config = {
+        slug,
+        id:          attrs.id || `cb-${slug}-${Math.random().toString(36).slice(2, 7)}`,
+        display:     attrs.display || 'cards',
+        columns:     parseInt(attrs.columns, 10) || 3,
+        titleField:  attrs['title-field'] || '',
+        bodyField:   attrs['body-field']  || '',
+        dateField:   attrs['date-field']  || '',
+        statusField: attrs['status-field'] || '',
+        iconField:   attrs['icon-field']  || '',
+        layout:      attrs.layout || '',
+        theme:       attrs.theme  || '',
+        timelineMode: attrs.mode === 'roadmap' ? 'roadmap' : 'timeline',
+        block:       attrs.block || '',
+        fields:      attrs.fields ? attrs.fields.split(',').map(s => s.trim()).filter(Boolean) : null,
+        pageSize,
+        mode,
+        pagination:  attrs.pagination === 'scroll' ? 'scroll' : 'pages',  // 'pages' = prev/next, 'scroll' = infinite
+        searchable:  isTruthyAttr(attrs.searchable),
+        sortable:    isTruthyAttr(attrs.sortable) || sortableFields.length > 0,
+        sortableFields,                                            // empty array = all fields sortable
+        filterable,                                                // [] = no filter rail
+        exportable:  isTruthyAttr(attrs.exportable),               // adds "Export CSV" button
+        savedSearches: !isTruthyAttr(attrs['no-saved-searches']),  // opt-out flag (defaults on)
+        transitions: isTruthyAttr(attrs.transitions),              // render per-row transition buttons
+        emptyMsg:    attrs.empty || 'No entries found',
+        cta:         attrs.cta ? {
+            action:  attrs.cta,
             label:   attrs['cta-label']   || 'Run',
             icon:    attrs['cta-icon']    || '',
             style:   attrs['cta-style']   || 'primary',
             confirm: attrs['cta-confirm'] || ''
-        } : null;
+        } : null,
+        baked: buildShortcodeFilter(attrs),                        // author's where_* filter — locked in, not user-tweakable
+        initial: { sort: attrs.sort || 'createdAt', order: attrs.order || 'desc' },
+        syncUrl: !isTruthyAttr(attrs['no-url-sync'])               // default ON
+    };
 
-        let replacement = `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
+    // No-JS fallback — render the same first-page state with the static renderer.
+    const fallbackAttrs = {...attrs, limit: String(pageSize)};
+    const fallback      = await renderCollectionFragment(fallbackAttrs);
 
-        try {
-            const schema  = await getCollection(slug);
-            if (!schema) throw new Error('not found');
-
-            let {entries} = await listEntries(slug);
-
-            // Row-level filter: where="field=value" (simple equality only).
-            // Comma-separate multiple predicates, all AND'd together.
-            // Example: where="tab=developers" or where="tab=developers,status=live"
-            const whereAttr = typeof attrs.where === 'string' ? attrs.where.trim() : '';
-            if (whereAttr) {
-                const predicates = whereAttr.split(',').map(p => p.trim()).filter(Boolean).map(p => {
-                    const eq = p.indexOf('=');
-                    if (eq === -1) return null;
-                    return { key: p.slice(0, eq).trim(), val: p.slice(eq + 1).trim() };
-                }).filter(Boolean);
-                if (predicates.length) {
-                    entries = entries.filter(e => predicates.every(({key, val}) => String(e.data?.[key] ?? '') === val));
-                }
-            }
+    // Encode payloads. Schema can be modest; data can be large in client mode,
+    // so we base64 once each and let the browser decode.
+    const enc = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64');
 
-            entries = sortEntries(entries, sort, order);
-            if (limitAttr > 0) entries = entries.slice(0, limitAttr);
+    const wrapperCls = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
+    const wrapperId  = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : ` id="${escapeAttr(config.id)}"`;
 
-            // Determine visible fields from schema (optionally filtered)
-            let fields = schema.fields || [];
-            if (fieldFilter?.length) {
-                fields = fieldFilter.map(name => fields.find(f => f.name === name) || { name, label: name });
-            }
-            if (!fields.length && entries.length) {
-                // No schema fields — derive from first entry's data keys
-                fields = Object.keys(entries[0].data || {}).map(k => ({ name: k, label: k }));
-            }
+    return `<div class="dm-collection-browser${wrapperCls}"${wrapperId} ` +
+        `data-cb-config="${enc(config)}" ` +
+        `data-cb-schema="${enc({fields: schema?.fields || [], title: schema?.title || ''})}" ` +
+        `data-cb-data="${enc({entries, total, page: 1, pageSize})}">` +
+        `<div class="dm-cb-fallback">${fallback}</div>` +
+        `</div>`;
+}
 
-            if (display === 'cards') {
-                replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts);
-            } else if (display === 'list') {
-                replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts);
-            } else if (display === 'accordion') {
-                const accordionTitleField = attrs['title-field'] || 'title';
-                const bodyField           = attrs['body-field']  || 'description';
-                const multiple            = attrs.multiple === 'true';
-                replacement = renderCollectionAccordion(entries, accordionTitleField, bodyField, multiple, emptyMsg);
-            } else if (display === 'timeline') {
-                const timelineLayout = ['vertical', 'centred', 'horizontal'].includes(attrs.layout) ? attrs.layout : 'vertical';
-                const timelineTheme  = ['minimal', 'corporate', 'modern'].includes(attrs.theme)   ? attrs.theme  : 'minimal';
-                const timelineMode   = ['timeline', 'roadmap'].includes(attrs.mode)                ? attrs.mode   : 'timeline';
-                replacement = renderCollectionTimeline(entries, {
-                    titleField:  attrs['title-field']  || 'title',
-                    dateField:   attrs['date-field']   || '',
-                    statusField: attrs['status-field'] || '',
-                    iconField:   attrs['icon-field']   || '',
-                    bodyField:   attrs['body-field']   || '',
-                    layout: timelineLayout,
-                    theme:  timelineTheme,
-                    mode:   timelineMode,
-                    emptyMsg,
-                });
-            } else if (display === 'block') {
-                const blockName = attrs.block || '';
-                if (blockName) {
-                    try {
-                        const [tpl, css] = await Promise.all([
-                            loadBlockTemplate(blockName),
-                            loadBlockCss(blockName),
-                        ]);
-                        const cols = attrs.cols || '';
-                        replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts, cols, blockName, css);
-                    } catch {
-                        replacement = `<div class="dm-collection-display dm-collection-empty"><p>Block template &ldquo;${escapeHtmlText(blockName)}&rdquo; not found.</p></div>`;
-                    }
-                }
-            } else {
-                replacement = renderCollectionTable(slug, entries, fields, attrs, ctaOpts);
-            }
-        } catch {
-            // Collection not found or read error — show empty message
+/**
+ * Interactive `[view]` hydration shell. Saved views compose collections,
+ * joins, and pre-filters that aren't expressible in plain `where_*` syntax —
+ * so the browser treats a view as a read-only data source: search, sort,
+ * and pagination work; the filter rail is off by default (the view's own
+ * filter logic is the authoritative source). Authors can still expose user
+ * filters by setting `filterable="…"`, but the field names must exist on the
+ * view's projected document shape.
+ *
+ * @param {Record<string, string>} attrs
+ * @returns {Promise<string>}
+ */
+async function renderViewBrowserShell(attrs) {
+    const slug      = attrs.slug;
+    const pageSize  = parseInt(attrs['page-size'], 10) || parseInt(attrs.limit, 10) || 12;
+    const declaredMode = attrs.mode === 'server' ? 'server' : 'client';
+
+    let entries = [];
+    let total   = 0;
+    let viewConfig = null;
+
+    try {
+        const {executeView, getView} = await import('./views.js');
+        viewConfig = await getView(slug).catch(() => null);
+
+        if (declaredMode === 'client') {
+            // For views we cap aggressively — views can be expensive aggregations.
+            const r = await executeView(slug, {page: 1, limit: 500});
+            entries = (r.results || []).map(doc => ({id: doc.id || '', data: doc.data || doc}));
+            total   = r.total ?? entries.length;
+        } else {
+            const r = await executeView(slug, {page: 1, limit: pageSize});
+            entries = (r.results || []).map(doc => ({id: doc.id || '', data: doc.data || doc}));
+            total   = r.total ?? entries.length;
         }
+    } catch {
+        // executeView errored (no Pro / view missing) — emit empty shell.
+    }
 
-        if (attrs.class || attrs.id) {
-            const cls = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
-            const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
-            replacement = `<div class="dm-collection-wrapper${cls}"${id}>${replacement}</div>`;
+    // Derive a schema-like fields list from the first row so the browser can
+    // wire up sort dropdown labels even when the view has no explicit schema.
+    const schemaFields = entries.length
+        ? Object.keys(entries[0].data || {})
+              .filter(k => !['_id', 'id', 'meta'].includes(k))
+              .map(k => ({name: k, label: k, type: 'text'}))
+        : (viewConfig?.fields || []);
+
+    const filterable = (attrs.filterable && typeof attrs.filterable === 'string')
+        ? attrs.filterable.split(',').map(s => s.trim()).filter(Boolean) : [];
+    const sortableFields = (typeof attrs.sortable === 'string' && attrs.sortable !== 'true' && attrs.sortable !== 'false')
+        ? attrs.sortable.split(',').map(s => s.trim()).filter(Boolean) : [];
+
+    const config = {
+        slug,
+        id:          attrs.id || `cb-view-${slug}-${Math.random().toString(36).slice(2, 7)}`,
+        display:     attrs.display || viewConfig?.display?.mode || 'cards',
+        columns:     parseInt(attrs.columns, 10) || 3,
+        titleField:  attrs['title-field'] || viewConfig?.display?.titleField || '',
+        bodyField:   attrs['body-field']  || '',
+        dateField:   attrs['date-field']  || '',
+        statusField: attrs['status-field'] || '',
+        iconField:   attrs['icon-field']  || '',
+        layout:      attrs.layout || '',
+        theme:       attrs.theme  || '',
+        timelineMode: attrs.mode === 'roadmap' ? 'roadmap' : 'timeline',
+        block:       attrs.block || '',
+        fields:      attrs.fields ? attrs.fields.split(',').map(s => s.trim()).filter(Boolean) : null,
+        pageSize,
+        mode:        declaredMode,
+        pagination:  attrs.pagination === 'scroll' ? 'scroll' : 'pages',
+        searchable:  isTruthyAttr(attrs.searchable),
+        sortable:    isTruthyAttr(attrs.sortable) || sortableFields.length > 0,
+        sortableFields,
+        filterable,
+        exportable:  isTruthyAttr(attrs.exportable),
+        savedSearches: !isTruthyAttr(attrs['no-saved-searches']),
+        emptyMsg:    attrs.empty || 'No results found',
+        cta:         attrs.action ? {
+            action:  attrs.action,
+            label:   attrs['cta-label']   || 'Run',
+            icon:    attrs['cta-icon']    || '',
+            style:   attrs['cta-style']   || 'primary',
+            confirm: attrs['cta-confirm'] || ''
+        } : null,
+        baked: {},      // views don't accept baked where_*; the view itself is the filter
+        initial: { sort: attrs.sort || 'createdAt', order: attrs.order || 'desc' },
+        syncUrl: !isTruthyAttr(attrs['no-url-sync']),
+        sourceKind: 'view'       // hint for client-side: server-mode would need a different fetch endpoint
+    };
+
+    const enc = (obj) => Buffer.from(JSON.stringify(obj), 'utf8').toString('base64');
+    const wrapperCls = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
+    const wrapperId  = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : ` id="${escapeAttr(config.id)}"`;
+
+    return `<div class="dm-collection-browser dm-cb-source-view${wrapperCls}"${wrapperId} ` +
+        `data-cb-config="${enc(config)}" ` +
+        `data-cb-schema="${enc({fields: schemaFields, title: viewConfig?.title || slug})}" ` +
+        `data-cb-data="${enc({entries, total, page: 1, pageSize})}">` +
+        `<div class="dm-cb-fallback"></div>` +
+        `</div>`;
+}
+
+/**
+ * Render a `[collection]` block's HTML fragment from parsed attributes.
+ *
+ * Used by:
+ *   - The Markdown shortcode pipeline (server-side render at page build time)
+ *   - The collection hydration endpoint (client-side render when scope="mine"
+ *     forces per-user data that can't share the page cache)
+ *
+ * `extraFilter` is merged on top of any filter derived from `where_*` attrs —
+ * this is how the hydration endpoint injects `createdBy = <current user>`
+ * for scope=mine without trusting the client to set it.
+ *
+ * Returns a complete HTML fragment including the optional outer wrapper for
+ * `class=` / `id=` attributes. Always succeeds — render errors fall back to
+ * the empty-state HTML rather than throwing, so a typo in a single shortcode
+ * can't break a whole page render.
+ *
+ * @param {Record<string, string>} attrs        - Parsed shortcode attributes
+ * @param {object}                 [opts]
+ * @param {Record<string, unknown>} [opts.extraFilter]  - Additional filter conditions to AND in
+ * @returns {Promise<string>} HTML fragment ready to inject into a page
+ */
+export async function renderCollectionFragment(attrs, { extraFilter = null } = {}) {
+    const slug = attrs.slug || '';
+    if (!slug) return '';
+
+    const display    = attrs.display || 'table';
+    const limitAttr  = parseInt(attrs.limit, 10) || 0;
+    const sort       = attrs.sort  || 'createdAt';
+    const order      = attrs.order || 'desc';
+    const titleField = attrs['title-field'] || '';
+    const columns    = attrs.columns || '3';
+    const emptyMsg   = attrs.empty  || 'No entries found';
+    const fieldFilter = attrs.fields ? attrs.fields.split(',').map(f => f.trim()).filter(Boolean) : null;
+    const ctaAction  = attrs.cta || '';
+    const ctaOpts    = ctaAction ? {
+        action:  ctaAction,
+        label:   attrs['cta-label']   || 'Run',
+        icon:    attrs['cta-icon']    || '',
+        style:   attrs['cta-style']   || 'primary',
+        confirm: attrs['cta-confirm'] || ''
+    } : null;
+
+    let replacement = `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
+
+    try {
+        const schema = await getCollection(slug);
+        if (!schema) throw new Error('not found');
+
+        const filter = buildShortcodeFilter(attrs);
+        if (extraFilter) Object.assign(filter, extraFilter);
+
+        const listOpts = {
+            sort,
+            order,
+            limit: limitAttr > 0 ? limitAttr : 0,
+            resolveRefs: true        // decorate entries with display labels for reference fields
+        };
+        if (Object.keys(filter).length) listOpts.filter = filter;
+
+        const {entries} = await listEntries(slug, listOpts);
+
+        let fields = schema.fields || [];
+        if (fieldFilter?.length) {
+            fields = fieldFilter.map(name => fields.find(f => f.name === name) || { name, label: name });
+        }
+        if (!fields.length && entries.length) {
+            fields = Object.keys(entries[0].data || {}).map(k => ({ name: k, label: k }));
         }
 
-        result = result.replace(fullMatch, replacement);
+        if (display === 'cards') {
+            replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts);
+        } else if (display === 'list') {
+            replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts);
+        } else if (display === 'accordion') {
+            const accordionTitleField = attrs['title-field'] || 'title';
+            const bodyField           = attrs['body-field']  || 'description';
+            const multiple            = attrs.multiple === 'true';
+            replacement = renderCollectionAccordion(entries, accordionTitleField, bodyField, multiple, emptyMsg);
+        } else if (display === 'timeline') {
+            const timelineLayout = ['vertical', 'centred', 'horizontal'].includes(attrs.layout) ? attrs.layout : 'vertical';
+            const timelineTheme  = ['minimal', 'corporate', 'modern'].includes(attrs.theme)   ? attrs.theme  : 'minimal';
+            const timelineMode   = ['timeline', 'roadmap'].includes(attrs.mode)                ? attrs.mode   : 'timeline';
+            replacement = renderCollectionTimeline(entries, {
+                titleField:  attrs['title-field']  || 'title',
+                dateField:   attrs['date-field']   || '',
+                statusField: attrs['status-field'] || '',
+                iconField:   attrs['icon-field']   || '',
+                bodyField:   attrs['body-field']   || '',
+                layout: timelineLayout,
+                theme:  timelineTheme,
+                mode:   timelineMode,
+                emptyMsg,
+            });
+        } else if (display === 'block') {
+            const blockName = attrs.block || '';
+            if (blockName) {
+                try {
+                    const [tpl, css] = await Promise.all([
+                        loadBlockTemplate(blockName),
+                        loadBlockCss(blockName),
+                    ]);
+                    const cols = attrs.cols || '';
+                    replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts, cols, blockName, css);
+                } catch {
+                    replacement = `<div class="dm-collection-display dm-collection-empty"><p>Block template &ldquo;${escapeHtmlText(blockName)}&rdquo; not found.</p></div>`;
+                }
+            }
+        } else {
+            replacement = renderCollectionTable(slug, entries, fields, attrs, ctaOpts);
+        }
+    } catch {
+        // Collection not found or read error — show empty message
     }
 
-    return restore(result);
+    if (attrs.class || attrs.id) {
+        const cls = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
+        const id = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
+        replacement = `<div class="dm-collection-wrapper${cls}"${id}>${replacement}</div>`;
+    }
+
+    return replacement;
 }
 
 /**
@@ -2625,6 +3062,68 @@ function processIconBlocks(markdown) {
  */
 const FORMS_DIR = path.resolve(__dirname_md, '../../content/forms');
 
+/**
+ * Transform `type: 'reference'` fields on a form definition into select-style
+ * fields populated from the target collection. Mutates the form in place.
+ *
+ * Strategy: lazy server-side expansion at render time — the embedded form
+ * doesn't know about references, it just sees a select with options. This
+ * keeps the client-side form engine (`F.create`) ignorant of the schema
+ * vocabulary and works without any extra round-trips at form render time.
+ *
+ * Limits: ships the first 200 entries per referenced collection. Beyond that,
+ * a future enhancement can swap in an async-search picker; logged here as a
+ * known cap so authors with huge target collections know what to do.
+ *
+ * @param {object} form - Mutated in place: reference fields → select fields
+ * @returns {Promise<void>}
+ */
+async function expandReferenceFields(form) {
+    const fields = form?.fields;
+    if (!Array.isArray(fields) || !fields.length) return;
+
+    const REF_LIMIT = 200;
+
+    for (let i = 0; i < fields.length; i++) {
+        const f = fields[i];
+        if (f.type !== 'reference') continue;
+        const ref = f.reference || {};
+        if (!ref.collection) continue;
+
+        const targetSlug   = ref.collection;
+        const displayField = ref.displayField || 'title';
+
+        try {
+            const r = await listEntries(targetSlug, {limit: REF_LIMIT, sort: displayField, order: 'asc'});
+            const options = (r.entries || []).map(e => ({
+                value: e.id,
+                label: (e.data?.[displayField] != null && e.data[displayField] !== '')
+                    ? String(e.data[displayField])
+                    : e.id
+            }));
+
+            // Replace with a select; preserve label/required/helper from the original.
+            fields[i] = {
+                ...f,
+                type:    f.multiple ? 'multiselect' : 'select',
+                options,
+                // Keep the original reference metadata around so future code can
+                // recognise that this select was reference-derived (e.g. for an
+                // upgrade to an async picker without changing the form file).
+                _ref: {collection: targetSlug, displayField, originalType: 'reference'}
+            };
+        } catch {
+            // Target collection missing — render a disabled input with an explanatory placeholder.
+            fields[i] = {
+                ...f,
+                type: 'text',
+                placeholder: `(reference target "${targetSlug}" unavailable)`,
+                _ref: {collection: targetSlug, displayField, originalType: 'reference', error: true}
+            };
+        }
+    }
+}
+
 async function processFormBlocks(markdown, tagSet) {
   const {scrubbed, restore} = scrubCodeRegions(markdown);
   const regex = /\[form([^\]]*?)\/\]/gi;
@@ -2653,6 +3152,7 @@ async function processFormBlocks(markdown, tagSet) {
       if (!filePath.startsWith(FORMS_DIR + path.sep)) throw new Error('Invalid slug');
       const raw = await readFile(filePath, 'utf8');
       const form = JSON.parse(raw);
+      await expandReferenceFields(form);
       const encoded = Buffer.from(JSON.stringify(form)).toString('base64');
         const extraClass = attrs.class ? ` ${escapeAttr(attrs.class)}` : '';
         const idAttr = attrs.id ? ` id="${escapeAttr(attrs.id)}"` : '';
@@ -2847,6 +3347,78 @@ function processSlideoverBlocks(markdown) {
  * @param {string} markdown
  * @returns {string}
  */
+/**
+ * Pre-process [menu] shortcodes into rendered `<nav><ul>...</ul></nav>` markup.
+ *
+ * Forms:
+ *   [menu slug="my-menu" /]
+ *   [menu location="navbar" /]
+ *   [menu slug="..." depth="2" variant="..." class="..." /]
+ *
+ * Items flagged `hidden: true` are dropped. Items with a `visibility` field
+ * are filtered against the supplied user via `checkVisibility`. The `depth`
+ * attribute caps the nesting depth (1-indexed; depth="1" = top-level only).
+ *
+ * @param {string} markdown
+ * @param {object|null} user
+ * @returns {Promise<string>}
+ */
+async function processMenuBlocks(markdown, user) {
+    const re = /\[menu(\s+[^\]]*?)?\s*\/\]/gi;
+    const matches = [...markdown.matchAll(re)];
+    if (!matches.length) return markdown;
+
+    let out = markdown;
+    for (const m of matches) {
+        const attrs = parseShortcodeAttrs(m[1] || '');
+        let menu = null;
+        if (attrs.slug)          menu = await getMenu(attrs.slug);
+        else if (attrs.location) menu = await resolveLocation(attrs.location, user || null);
+        if (!menu) { out = out.replace(m[0], ''); continue; }
+
+        // The slug path skipped resolveLocation, so filter visibility + hidden manually here.
+        const items = attrs.slug
+            ? filterMenuForUser(menu.items || [], user || null)
+            : menu.items;
+
+        const depth = Number.parseInt(attrs.depth, 10);
+        const capped = Number.isFinite(depth) && depth > 0 ? capDepth(items, depth) : items;
+        const klass        = attrs.class   ? ` ${escapeAttr(attrs.class)}`                    : '';
+        const variantClass = attrs.variant ? ` dm-menu--variant-${escapeAttr(attrs.variant)}` : '';
+        const html = `<nav class="dm-menu dm-menu--${escapeAttr(menu.slug)}${variantClass}${klass}" data-menu="${escapeAttr(menu.slug)}">${renderMenuItemsAsUl(capped)}</nav>`;
+        out = out.replace(m[0], html);
+    }
+    return out;
+}
+
+function renderMenuItemsAsUl(items) {
+    if (!items.length) return '';
+    const lis = items.map(it => {
+        const href  = escapeAttr(it.url || '#');
+        const text  = escapeAttr(it.text || '');
+        const child = Array.isArray(it.items) && it.items.length ? renderMenuItemsAsUl(it.items) : '';
+        return `<li><a href="${href}">${text}</a>${child}</li>`;
+    }).join('');
+    return `<ul>${lis}</ul>`;
+}
+
+function capDepth(items, max, depth = 1) {
+    return items.map(it => ({
+        ...it,
+        items: depth < max && Array.isArray(it.items) ? capDepth(it.items, max, depth + 1) : []
+    }));
+}
+
+function filterMenuForUser(items, user) {
+    const out = [];
+    for (const item of items) {
+        if (item.hidden) continue;
+        if (item.visibility != null && !checkVisibility(user, item.visibility)) continue;
+        out.push({...item, items: Array.isArray(item.items) ? filterMenuForUser(item.items, user) : []});
+    }
+    return out;
+}
+
 function processDConfigBlocks(markdown) {
   const {scrubbed, restore} = scrubCodeRegions(markdown);
   const processed = scrubbed.replace(
@@ -2913,14 +3485,18 @@ function processCtaBlocks(markdown) {
  * Parse a Markdown file string into frontmatter data and rendered HTML.
  *
  * @param {string} raw - Raw file content (frontmatter + Markdown body)
+ * @param {object} [opts]
+ * @param {object|null} [opts.user] - Authenticated user (`{role, additionalRoles}`)
+ *   or null for anonymous. Used to filter menu items gated by `visibility` in
+ *   the `[menu]` shortcode. Backwards compatible — defaults to anonymous.
  * @returns {{ data: object, content: string, html: string }}
  */
-export async function parseMarkdown(raw) {
+export async function parseMarkdown(raw, opts = {}) {
   const {data, content} = matter(raw);
   const extensions = getSanitizeExtensions();
 
   // Pipeline:
-    // beforeParse → collection → view → staticBlock → dconfig → effects → plugin shortcodes → tabs → accordion → carousel
+    // beforeParse → collection → view → staticBlock → menu → dconfig → effects → plugin shortcodes → tabs → accordion → carousel
   //   → countdown → timeline → spacer → center → icon → form → hero → table → badge → button → link → cta
   //   → grid → card → slideover → marked → sanitize → afterParse
   const preprocessed = applyTransforms('markdown:beforeParse', content);
@@ -2929,7 +3505,8 @@ export async function parseMarkdown(raw) {
   const withCollection = await processCollectionBlocks(withComponents, tagSet);
   const withView = await processViewBlocks(withCollection, tagSet);
   const withStaticBlock = await processStaticBlocks(withView, tagSet);
-  const withDconfig = processDConfigBlocks(withStaticBlock);
+  const withMenu = await processMenuBlocks(withStaticBlock, opts.user || null);
+  const withDconfig = processDConfigBlocks(withMenu);
     const withEffects = processEffectsBlocks(withDconfig);
     const withPluginShortcodes = await processPluginShortcodes(withEffects);
   const withTabs = processTabsBlocks(withPluginShortcodes);