@zvndev/darkmown 1.4.0 → 1.5.0

package/src/compiler/loops.js

@@ -15,6 +15,7 @@ import {
   escapeHtml,
   getPath,
   lookupPath,
+  lookupVar,
   resolveStateKey,
   stripQuotes,
   unescapeHtml
@@ -30,15 +31,15 @@ import { compilePredicate, evalPredicate } from "./predicates.js";
 
 // The fixed corrective suggestion shown for any malformed @loop header.
 const LOOP_USAGE =
-  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [sortable]";
+  "Use: @loop src into item [where …] [sort by …] [reverse] [offset N] [limit N] [paginate N] [sortable]";
 
 /**
  * Parse the optional clause tail of a `@loop` header in FIXED order:
- * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N] [sortable]`.
+ * `[where P] [sort by key [asc|desc]] [reverse] [offset N] [limit N] [paginate N] [sortable]`.
  * @param {string} tail Everything after `@loop src into item`.
  * @param {string} itemName
  * @param {Ctx} ctx
- * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean, sortable: boolean }}
+ * @returns {{ where: string|null, sort: import("./context.js").LoopOpts["sort"], reverse: boolean, offset: NumArg|null, limit: NumArg|null, refsState: boolean, sortable: boolean, paginate: number|null }}
  */
 function parseLoopClauses(tail, itemName, ctx) {
   // Peel clauses off the END in reverse fixed-order (limit, offset, reverse,
@@ -53,6 +54,7 @@ function parseLoopClauses(tail, itemName, ctx) {
   /** @type {NumArg|null} */ let limit = null;
   let refsState = false;
   let sortable = false;
+  /** @type {number|null} */ let paginate = null;
   /** @returns {never} */
   const bad = () => {
     throw new Error(`Malformed @loop clause in ${ctx.file}: "${tail.trim()}". ${LOOP_USAGE}`);
@@ -69,6 +71,20 @@ function parseLoopClauses(tail, itemName, ctx) {
       .trim();
   }
 
+  // `paginate N` slices the listing into static pages. Peel it position-
+  // independently (like `sortable`) so `paginate 2 limit 1` parses and handleLoop
+  // can reject the combination with a precise message rather than failing the
+  // fixed-order parse. The count is a positive integer literal — paginating "by a
+  // state value" makes no sense for a build-time route split.
+  const pm = s.match(/(^|\s)paginate\s+(\d+)(?=\s|$)/);
+  if (pm) {
+    paginate = Number(pm[2]);
+    if (paginate < 1) bad();
+    s = (s.slice(0, pm.index) + s.slice((pm.index ?? 0) + pm[0].length))
+      .replace(/\s+/g, " ")
+      .trim();
+  }
+
   let m = s.match(/(^|\s)limit\s+(\d+|[A-Za-z_$][\w$]*)$/);
   if (m) {
     limit = parseNumArg(m[2], ctx);
@@ -109,7 +125,7 @@ function parseLoopClauses(tail, itemName, ctx) {
     // predicate means a clause was written before `where` finished (wrong order).
     if (/(^|\s)(sort\s+by\s|reverse(\s|$))/.test(where)) bad();
   }
-  return { where, sort, reverse, offset, limit, refsState, sortable };
+  return { where, sort, reverse, offset, limit, refsState, sortable, paginate };
 }
 
 /**
@@ -213,18 +229,32 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
         offset: null,
         limit: null,
         refsState: false,
-        sortable: false
+        sortable: false,
+        paginate: null
       };
   const where = clauses.where ? compilePredicate(clauses.where, itemName, ctx) : null;
   // `sortable` reorders the list directly, so it can't combine with a clause that
   // re-derives the visible order (where/sort/reverse) or shows a partial view
-  // (offset/limit) — those would break the 1:1 DOM↔array index mapping.
+  // (offset/limit/paginate) — those would break the 1:1 DOM↔array index mapping.
   if (
     clauses.sortable &&
-    (where || clauses.sort || clauses.reverse || clauses.offset || clauses.limit)
+    (where ||
+      clauses.sort ||
+      clauses.reverse ||
+      clauses.offset ||
+      clauses.limit ||
+      clauses.paginate)
   ) {
     throw new Error(
-      `@loop sortable cannot combine with where/sort/reverse/offset/limit in ${ctx.file}. ${LOOP_USAGE}`
+      `@loop sortable cannot combine with where/sort/reverse/offset/limit/paginate in ${ctx.file}. ${LOOP_USAGE}`
+    );
+  }
+  // `paginate N` OWNS the page slice, so an explicit offset/limit alongside it is
+  // a conflict (which one wins?). Reject it with a clear hint rather than silently
+  // letting one override the other.
+  if (clauses.paginate && (clauses.offset || clauses.limit)) {
+    throw new Error(
+      `@loop paginate cannot combine with offset/limit in ${ctx.file} — paginate already slices each page. ${LOOP_USAGE}`
     );
   }
   /** @type {LoopOpts} */
@@ -236,7 +266,8 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     limit: clauses.limit,
     empty: emptyLines,
     clauseRefsState: clauses.refsState,
-    sortable: clauses.sortable
+    sortable: clauses.sortable,
+    paginate: clauses.paginate
   };
 
   if (
@@ -245,6 +276,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     source.startsWith("../") ||
     source.endsWith(".json")
   ) {
+    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
     const dataFile = resolveInclude(source, ctx.file, ctx.context, true);
     const rows = JSON.parse(fs.readFileSync(dataFile, "utf8"));
     if (!Array.isArray(rows)) throw new Error(`@loop data must be a JSON array: ${dataFile}`);
@@ -253,6 +285,7 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
 
   const resolved = lookupPath(source, ctx);
   if (resolved.found) {
+    if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
     if (!Array.isArray(resolved.value)) {
       throw new Error(
         `@loop ${source} in ${ctx.file} found an in-scope value, but it is not a list`
@@ -269,9 +302,15 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
     }
     const key = resolveStateKey(segs[0], ctx);
     if (key) {
+      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
       const fullKey = segs.length > 1 ? `${key}.${segs.slice(1).join(".")}` : key;
       return reactiveLoop(fullKey, itemName, bodyLines, ctx, opts);
     }
+    // A bare name matching a collection (any `site/pages/<name>/` subdir) resolves
+    // to its entry rows at build time and static-unrolls — zero JS. This is checked
+    // after state so a declared `:state` of the same name still wins.
+    const collection = segs.length === 1 ? ctx.comp.collections.get(source) : undefined;
+    if (collection) return loopOverCollection(collection, source, itemName, bodyLines, ctx, opts);
     // Inside a reactive loop, `@loop <outerItem>.<path> into x` loops a field of
     // the enclosing row item — an ITEM-RELATIVE loop the runtime fills per row.
     if (ctx.loopItem && segs[0] === ctx.loopItem && segs.length > 1) {
@@ -280,15 +319,93 @@ export function handleLoop(line, bodyLines, emptyLines, ctx) {
           `@loop sortable is not supported on a nested (item-relative) loop in ${ctx.file}. ${LOOP_USAGE}`
         );
       }
+      if (opts.paginate) throw new Error(paginateOnlyCollections(ctx));
       return itemRelativeLoop(segs.slice(1).join("."), itemName, bodyLines, ctx, opts);
     }
   }
 
-  throw new Error(
-    `@loop source "${source}" in ${ctx.file} was not found. Loop over a JSON file (@loop /data.json into row), an in-scope value, or a :state list.`
+  throw new Error(unresolvedSourceError(source, ctx));
+}
+
+/**
+ * The "source not found" error for an unresolved `@loop` bare name. Lists the
+ * valid collection names (the `site/pages/<name>/` subdirs) so a typo'd
+ * collection reference is immediately actionable.
+ * @param {string} source
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function unresolvedSourceError(source, ctx) {
+  const names = [...ctx.comp.collections.keys()].sort();
+  const collectionsHint = names.length ? ` Available collections: ${names.join(", ")}.` : "";
+  return (
+    `@loop source "${source}" in ${ctx.file} was not found. Loop over a collection ` +
+    `(a site/pages/<name>/ subdirectory, by its bare name), a JSON file ` +
+    `(@loop /data.json into row), an in-scope value, or a :state list.${collectionsHint}`
   );
 }
 
+/**
+ * The error for `paginate` on a non-collection source: pagination multiplies
+ * static routes, which only makes sense for a build-time collection listing.
+ * @param {Ctx} ctx
+ * @returns {string}
+ */
+function paginateOnlyCollections(ctx) {
+  return `@loop paginate requires a collection source (a site/pages/<name>/ subdirectory) in ${ctx.file}. ${LOOP_USAGE}`;
+}
+
+/**
+ * Loop over a build-time collection's entry rows. With no `paginate`, this is a
+ * plain static unroll (filter/sort/reverse/offset/limit at build time, zero JS).
+ * With `paginate N`, it records the pagination intent (so the builder multiplies
+ * routes), then renders only the current page's slice using the injected `page`
+ * pager — `offset = (page.current - 1) * N`, `limit = N`.
+ * @param {import("./collections.js").CollectionRow[]} rows
+ * @param {string} name Collection name, for the pagination record.
+ * @param {string} itemName
+ * @param {string[]} bodyLines
+ * @param {Ctx} ctx
+ * @param {LoopOpts} opts
+ * @returns {string}
+ */
+function loopOverCollection(rows, name, itemName, bodyLines, ctx, opts) {
+  if (!opts.paginate) {
+    // No pagination → behave exactly like a JSON-file/in-scope source: a pure
+    // listing static-unrolls (zero JS); a `where` that reads :state turns it into
+    // a reactive baked-rows loop. `loopOverData` makes that call.
+    return loopOverData(rows, itemName, bodyLines, ctx, opts);
+  }
+  // Count rows AFTER where/sort/reverse but BEFORE the page slice, so `total`
+  // reflects what the reader will actually page through. Reuse pipelineRows with
+  // offset/limit stripped for the count.
+  const filtered = pipelineRows(rows, opts.where, { ...opts, offset: null, limit: null }, ctx);
+  const perPage = opts.paginate;
+  const total = Math.max(1, Math.ceil(filtered.length / perPage));
+  ctx.comp.pagination = { perPage, total, collection: name };
+  // `page.current` is the 1-based page the builder is rendering (it seeds the
+  // document scope). Slice this page out of the already-filtered/sorted list.
+  const current = currentPage(ctx);
+  const start = (current - 1) * perPage;
+  return staticUnroll(filtered.slice(start, start + perPage), itemName, bodyLines, ctx, opts.empty);
+}
+
+/**
+ * The 1-based page the builder is currently rendering, read from the injected
+ * `page.current` scope var. Defaults to page 1 (the discovery compile, before the
+ * builder knows the total, runs with `page.current = 1`).
+ * @param {Ctx} ctx
+ * @returns {number}
+ */
+function currentPage(ctx) {
+  const page = lookupVar(ctx.scope, "page");
+  if (page.found && page.value && typeof page.value === "object") {
+    const current = /** @type {Record<string, unknown>} */ (page.value).current;
+    if (typeof current === "number" && current >= 1) return current;
+  }
+  return 1;
+}
+
 // A static source (JSON file / in-scope value). No `where`, or a `where` that
 // only reads the loop item → filter at build time and stay zero-JS. A `where`
 // that reads :state → becomes a reactive filtered loop with the rows baked in.
@@ -440,7 +557,8 @@ function reactiveLoop(key, itemName, bodyLines, ctx, opts = null) {
           : limit,
       empty: null,
       clauseRefsState: false,
-      sortable: false
+      sortable: false,
+      paginate: null
     },
     ctx
   );

package/src/compiler/page.js

@@ -30,13 +30,16 @@ import { selectMd } from "./markdown.js";
  * Compile a page source file into a full HTML document plus its assets.
  * @param {string} file Absolute path to the source `.md`/`.wd` file.
  * @param {Paths} context Resolved project paths.
- * @param {{ feed?: { href: string, title: string } }} [options] When a site-wide
- *   RSS feed is emitted (the home page set `site_url` and the site has dated
- *   posts), `feed` carries its absolute href + title so every page links it.
+ * @param {{ feed?: { href: string, title: string }, collections?: Map<string, import("./collections.js").CollectionRow[]>, vars?: Record<string, unknown> }} [options]
+ *   When a site-wide RSS feed is emitted (the home page set `site_url` and the
+ *   site has dated posts), `feed` carries its absolute href + title so every page
+ *   links it. `collections` is the build-time collection index a bare-name
+ *   `@loop` resolves against; `vars` seeds the document scope (the pager `page`
+ *   object on a paginated route).
  * @returns {CompiledPage}
  */
 export function compilePage(file, context, options = {}) {
-  const compiled = compileDocument(file, context);
+  const compiled = compileDocument(file, context, [], options.vars, options.collections);
   const title = compiled.meta.title || "Darkmown";
   const description = compiled.meta.description || "";
   // Optional `image:` frontmatter sets the social-share preview (absolute URL).
@@ -158,7 +161,8 @@ ${scripts}
 </body>
 </html>`,
     assets: compiled.assets,
-    warnings: compiled.warnings
+    warnings: compiled.warnings,
+    pagination: compiled.pagination
   };
 }
 
@@ -199,28 +203,68 @@ export function enhanceImages(html, paths) {
   });
 }
 
+/**
+ * Raw-text (`script`, `style`) and escapable-raw-text (`textarea`, `title`)
+ * elements per the HTML spec: their CONTENT is not markup, so `<`/`>` inside them
+ * are plain characters and must never be treated as tags. The content runs to the
+ * first matching close tag.
+ * @type {Set<string>}
+ */
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "textarea", "title"]);
+
 /**
  * Stamp `data-wd-scope="<id>"` onto every opening tag of a subtree — the HTML
- * half of compile-time scoped styles, mirroring {@link enhanceImages}: a regex
- * post-pass over assembled HTML, zero runtime JS. Every element start tag that
- * doesn't already carry a scope attribute gets one, so the scoped stylesheet
- * (whose selectors end in `[data-wd-scope="<id>"]`) matches inside this subtree
- * and nowhere else. Void/self-closing tags are stamped too (the attribute is
- * valid on any element). Closing tags, comments, doctype, and the `<!`/`<?`
- * families are left alone. A tag that ALREADY has a `data-wd-scope` (e.g. a
- * nested include with its own scope) keeps its own — first stamp wins.
+ * half of compile-time scoped styles, mirroring {@link enhanceImages}: a
+ * compile-time post-pass over assembled HTML, zero runtime JS. Every element
+ * start tag that doesn't already carry a scope attribute gets one, so the scoped
+ * stylesheet (whose selectors end in `[data-wd-scope="<id>"]`) matches inside
+ * this subtree and nowhere else. Void/self-closing tags are stamped too (the
+ * attribute is valid on any element). Closing tags, comments, doctype, and the
+ * `<!`/`<?` families are left alone. A tag that ALREADY has a `data-wd-scope`
+ * (e.g. a nested include with its own scope) keeps its own — first stamp wins.
+ *
+ * Raw-text / escapable-raw-text elements (`script`, `style`, `textarea`,
+ * `title`) are special-cased: their OPENING tag is stamped (valid), but their
+ * BODY is left byte-intact — `<`/`>` inside a `<script>` are JavaScript, not
+ * markup, so stamping there would corrupt the content. A small tokenizer walks
+ * tag-by-tag (quote-aware in attribute lists) and, on entering a raw-text
+ * element, copies through verbatim until the matching close tag.
  * @param {string} html Subtree HTML to scope.
  * @param {string} scopeId Scope id (from {@link import("../skin.js").scopeIdFor}).
  * @returns {string}
  */
 export function stampScope(html, scopeId) {
-  return html.replace(
-    /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g,
-    (tag, name, attrs, slash) => {
-      if (/\bdata-wd-scope\s*=/.test(attrs)) return tag;
-      return `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
+  // Opening tag: name + (quote-aware) attribute list + optional self-close slash.
+  const openTag = /<([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/g;
+  let out = "";
+  let cursor = 0;
+  for (let m = openTag.exec(html); m; m = openTag.exec(html)) {
+    const [tag, name, attrs, slash] = m;
+    out += html.slice(cursor, m.index); // text/markup before this opening tag
+    const stamped = /\bdata-wd-scope\s*=/.test(attrs)
+      ? tag // first stamp wins — a pre-stamped tag keeps its own scope
+      : `<${name}${attrs} data-wd-scope="${scopeId}"${slash ? " /" : ""}>`;
+    out += stamped;
+    cursor = m.index + tag.length;
+
+    // Raw-text element (not self-closed): copy its body through untouched and
+    // resume scanning after the matching close tag, so nothing inside is stamped.
+    if (!slash && RAW_TEXT_ELEMENTS.has(name.toLowerCase())) {
+      const rest = html.slice(cursor);
+      const closeMatch = new RegExp(`</${name}\\s*>`, "i").exec(rest);
+      if (!closeMatch) {
+        out += rest; // unterminated raw-text element — copy the remainder verbatim
+        cursor = html.length;
+        break;
+      }
+      const through = closeMatch.index + closeMatch[0].length; // body + close tag
+      out += rest.slice(0, through); // byte-intact
+      cursor += through;
+      openTag.lastIndex = cursor; // skip the body the scanner would otherwise re-walk
     }
-  );
+  }
+  out += html.slice(cursor); // trailing text after the last opening tag
+  return out;
 }
 
 /**
@@ -266,12 +310,21 @@ function measureImage(src, paths) {
  * @param {Paths} context Resolved project paths.
  * @param {string[]} [stack] Include stack for cycle detection.
  * @param {Record<string, unknown>} [vars] Initial static scope variables.
+ * @param {Map<string, import("./collections.js").CollectionRow[]>} [collections]
+ *   Build-time collection index a bare-name `@loop` resolves against.
  * @returns {CompiledDocument}
  */
-export function compileDocument(file, context, stack = [], vars = {}) {
+export function compileDocument(file, context, stack = [], vars = {}, collections = new Map()) {
   const comp = createCompilation();
+  comp.collections = collections;
   const result = compileFile(file, context, stack, createScope(null, vars), comp, [], null);
-  return { meta: result.meta, html: result.html, assets: comp.assets, warnings: comp.warnings };
+  return {
+    meta: result.meta,
+    html: result.html,
+    assets: comp.assets,
+    warnings: comp.warnings,
+    pagination: comp.pagination
+  };
 }
 
 /**

package/src/templates/blog/site/pages/index.skin

@@ -1,8 +1,23 @@
 tokens
   ink #1d2530
   paper #fbfaf7
+  panel #ffffff
+  line #e7e3da
   muted #6b7785
   accent #2f6df0
+  accent-deep #2356cc
+  ring #2f6df0
+  radius 10px
+
+tokens dark
+  ink #e7ecf3
+  paper #0f141b
+  panel #161d27
+  line #28303c
+  muted #93a0b2
+  accent #5b8cff
+  accent-deep #80a6ff
+  ring #5b8cff
 
 page
   margin 0
@@ -10,6 +25,7 @@ page
   color $ink
   bg $paper
   line-height 1.6
+  -webkit-font-smoothing antialiased
 
 main
   max-width 720px
@@ -49,3 +65,71 @@ nav a
   margin 0 0 .5rem
   color $muted
   font-size .9rem
+
+/* Buttons & form controls — for newsletter signups, :button actions, etc. */
+button
+  display inline-flex
+  align-items center
+  justify-content center
+  gap .5rem
+  bg $accent
+  color white
+  border 1px solid $accent
+  padding .6rem 1.15rem
+  margin .4rem .5rem .4rem 0
+  radius 999px
+  font-size .94rem
+  font-weight 560
+  line-height 1.15
+  cursor pointer
+  appearance none
+  box-shadow 0 1px 2px rgba(29,37,48,.08)
+  transition transform .14s cubic-bezier(.2,.7,.3,1), box-shadow .14s ease, background .14s ease, border-color .14s ease
+
+button:hover
+  bg $accent-deep
+  border-color $accent-deep
+  transform translateY(-1px)
+  box-shadow 0 8px 18px -8px rgba(47,109,240,.55)
+
+button:active
+  transform translateY(0)
+  box-shadow 0 1px 2px rgba(29,37,48,.08)
+
+button:focus-visible
+  outline 2px solid $ring
+  outline-offset 2px
+
+button:disabled
+  opacity .5
+  cursor not-allowed
+  box-shadow none
+  transform none
+
+input, textarea, select
+  font inherit
+  font-size .95rem
+  color $ink
+  bg $panel
+  border 1px solid $line
+  radius $radius
+  padding .58rem .8rem
+  margin .35rem 0
+  width 100%
+  max-width 24rem
+  appearance none
+  transition border-color .14s ease, box-shadow .14s ease
+
+input:hover, textarea:hover, select:hover
+  border-color $accent
+
+input:focus-visible, textarea:focus-visible, select:focus-visible
+  outline none
+  border-color $accent
+  box-shadow 0 0 0 3px rgba(47,109,240,.18)
+
+@media (prefers-reduced-motion: reduce)
+  button
+    transition none
+  button:hover
+    transform none

package/src/templates/dashboard/site/pages/index.skin

@@ -2,9 +2,13 @@ tokens
   ink #0f1722
   paper #0b1018
   panel #131c28
+  field-bg #0e1620
   line #243245
   muted #8aa0b8
   accent #4f9cff
+  accent-deep #6fb0ff
+  ring #4f9cff
+  radius 12px
 
 page
   margin 0
@@ -12,6 +16,7 @@ page
   color #e7eefc
   bg $paper
   line-height 1.55
+  -webkit-font-smoothing antialiased
 
 main
   max-width 880px
@@ -72,3 +77,82 @@ nav a
   color $muted
   font-size .85rem
   margin-top .5rem
+
+/* Buttons & controls — refresh, filters, range pickers, etc. */
+button
+  display inline-flex
+  align-items center
+  justify-content center
+  gap .5rem
+  bg $accent
+  color #07101d
+  border 1px solid $accent
+  padding .55rem 1.05rem
+  margin .4rem .5rem .4rem 0
+  radius 999px
+  font-size .92rem
+  font-weight 600
+  line-height 1.15
+  cursor pointer
+  appearance none
+  transition transform .14s cubic-bezier(.2,.7,.3,1), box-shadow .14s ease, background .14s ease, border-color .14s ease
+
+button:hover
+  bg $accent-deep
+  border-color $accent-deep
+  transform translateY(-1px)
+  box-shadow 0 8px 20px -8px rgba(79,156,255,.6)
+
+button:active
+  transform translateY(0)
+  box-shadow none
+
+button:focus-visible
+  outline 2px solid $ring
+  outline-offset 2px
+
+button:disabled
+  opacity .5
+  cursor not-allowed
+  transform none
+
+button.ghost
+  bg transparent
+  color #e7eefc
+  border-color $line
+
+button.ghost:hover
+  bg $panel
+  border-color $accent
+  box-shadow none
+
+input, select, textarea
+  font inherit
+  font-size .95rem
+  color #e7eefc
+  bg $field-bg
+  border 1px solid $line
+  radius 10px
+  padding .55rem .8rem
+  margin .35rem 0
+  width 100%
+  max-width 24rem
+  appearance none
+  transition border-color .14s ease, box-shadow .14s ease
+
+input::placeholder, textarea::placeholder
+  color $muted
+
+input:hover, select:hover, textarea:hover
+  border-color #2f4763
+
+input:focus-visible, select:focus-visible, textarea:focus-visible
+  outline none
+  border-color $accent
+  box-shadow 0 0 0 3px rgba(79,156,255,.22)
+
+@media (prefers-reduced-motion: reduce)
+  button
+    transition none
+  button:hover
+    transform none