@transclude/core 0.11.3 → 0.12.0

package/bin/build.js

@@ -207,6 +207,7 @@ async function render(route, { url, params }) {
     stylesheet,
     csp: config.csp,
     lang: config.lang,
+    canonical: config.canonical,
     speculate: speculateRules,
     include,
   });

package/bin/dev.js

@@ -191,6 +191,7 @@ const renderPage = async (route, c, status = null, extra = {}) => {
     stylesheet: config.stylesheet ? `/${config.stylesheet}` : null,
     csp: config.csp,
     lang: config.lang,
+    canonical: config.canonical,
     include,
   });
   // A loader answered for itself: a redirect, or something that is not a page.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.11.3",
+  "version": "0.12.0",
   "description": "An HTML-first server framework. A page is an .html file, the directory tree is the route table, and any fragment of a page is a URL of its own. Runs on Node, Bun, Deno and workerd, and ships no client JavaScript by default.",
   "keywords": [
     "html",

package/src/app.js

@@ -358,6 +358,7 @@ export function createApp({
                 stylesheet: manifest.stylesheet,
                 csp: config.csp,
                 lang: config.lang,
+                canonical: config.canonical,
                 // Written by the build and carried here, so a server-rendered
                 // page says the same thing about speculation that a file does.
                 speculate: manifest.speculate ?? null,
@@ -429,6 +430,7 @@ export function createApp({
             stylesheet: manifest.stylesheet,
             csp: config.csp,
             lang: config.lang,
+            canonical: config.canonical,
             speculate: manifest.speculate ?? null,
             include,
           });

package/src/compiler/bind.js

@@ -69,6 +69,7 @@ class Bindgen {
     components = new Map(),
     shadowTags = new Set(),
     blockOf = new Map(),
+    anchoredOf = new Set(),
     refs = new Map(),
   } = {}) {
     this.components = components;
@@ -76,6 +77,10 @@ class Bindgen {
     // Which tree node owns which compiled block. Sharing the map is what keeps
     // this pass and the renderer from drifting apart over the same tree.
     this.blockOf = blockOf;
+    // The blocks the renderer fenced in anchors, which is more of them than it
+    // compiled. Shared for the same reason, and read for one question: is this a
+    // block the walk can step over.
+    this.anchoredOf = anchoredOf;
     // tag -> the local name the renderer imported that component under.
     this.refs = refs;
     this.frames = [new Frame(new Scope())];
@@ -165,6 +170,11 @@ class Bindgen {
     }
   }
 
+  /** A `<slot>` the renderer fenced, which is a light element's and never a shadow one's. */
+  isHole(node) {
+    return node.tagName === 'slot' && this.anchoredOf.has(node);
+  }
+
   abandon(slot) {
     if (slot.kind === 'text') {
       for (const node of slot.nodes) this.giveUpText(node.value);
@@ -208,14 +218,36 @@ class Bindgen {
       if (slot.kind === 'block') {
         const ref = this.bindBlock(slot, here);
         if (ref === null) {
-          for (const rest of rendered.slice(i)) this.abandon(rest);
-          this.frame.gaveUp = true;
-          return;
+          // A light element's block: rendered once and never rebuilt. What it
+          // read is volatile and its nodes are nothing to hold, but its anchors
+          // are in the markup, so the walk goes on past it. A block without them
+          // has no past it, and nothing after it binds.
+          if (!this.anchoredOf.has(slot.nodes[0])) {
+            for (const rest of rendered.slice(i)) this.abandon(rest);
+            this.frame.gaveUp = true;
+            return;
+          }
+          this.abandon(slot);
         }
         // Past a block the node count is not knowable, so addressing becomes
         // relative from here on.
         cursor = cursor ?? this.cursor();
-        this.locate(`${cursor} = __b[${ref}].end.nextSibling;`);
+        const past = ref === null ? `__afterBlock(${here})` : `__b[${ref}].end.nextSibling`;
+        this.locate(`${cursor} = ${past};`);
+        continue;
+      }
+
+      // A light element's `<slot>` is a compile-time hole holding the caller's
+      // markup, which is fenced for the same reason a block is. Nothing in it is
+      // ours to write, and the walk steps over it to reach what follows.
+      //
+      // The tag is asked for, not just the set: a branch arrives at its own part
+      // bare, with its directive already consumed, so a block's node reaches here
+      // as an ordinary element and is in the set too.
+      if (slot.kind === 'element' && this.isHole(slot.nodes[0])) {
+        this.abandon(slot);
+        cursor = cursor ?? this.cursor();
+        this.locate(`${cursor} = __afterBlock(${here});`);
         continue;
       }
 

package/src/compiler/codegen.js

@@ -98,6 +98,7 @@ export function compileFragment(nodes, opts = {}) {
     at,
     blockDefs: gen.blockDefs.join('\n'),
     blockOf: gen.blockOf,
+    anchoredOf: gen.anchoredOf,
     slots: Object.fromEntries(slots.map(([name, out]) => [name, out.code])),
     regions: Object.fromEntries(regions.map(([name, out]) => [name, out.code])),
     regionIncludes: gen.regionIncludes,
@@ -129,13 +130,16 @@ class Codegen {
     // `blocks` on, an `if` or `each` compiles to its own module-scope function,
     // and a `__fragment` passed from render would not be in scope inside it.
     this.fragments = fragments;
-    // With `blocks` on, `if` and `each` at the top level compile to their own
-    // function and are wrapped in comment anchors, so an update can re-render
-    // one region instead of the whole shadow root. Only an element is ever
-    // updated, so nothing else pays for the anchors.
-    this.blocks = blocks && !layout;
+    // With `blocks` on, every `if` and `each` is wrapped in comment anchors, so
+    // whatever binds this markup can find where one ends. Only an element is ever
+    // updated, so nothing else pays for them.
+    this.blocks = blocks;
     this.blockDefs = [];
     this.blockOf = new Map();
+    // Every block that got anchors, whether or not it also got a function. The
+    // binding pass reads it the way it reads `blockOf`: to know that a block it
+    // cannot bind is still one it can step over.
+    this.anchoredOf = new Set();
     this.inBlock = 0;
     // The loop variables in scope, outermost first, two per level. A block
     // inside a loop renders from them, so its function has to take them.
@@ -360,14 +364,25 @@ class Codegen {
   }
 
   /**
-   * True where a structural block is addressable on its own. Anchors nest and
-   * the runtime counts depth, and a block inside a loop takes that loop's
-   * variables as arguments, so nesting is not a reason to give up on either.
+   * True where a block is wrapped in anchors, which is where anything binds this
+   * markup at all. Anchors nest and the runtime counts depth, so nesting is not a
+   * reason to give up.
    */
-  standalone() {
+  anchored() {
     return this.blocks && this.inHead === 0;
   }
 
+  /**
+   * True where a block also compiles to a function of its own, which is what
+   * re-rendering one region rather than the whole root needs. Not in a layout,
+   * and a light element is compiled as one: `<slot>` there is a compile-time hole
+   * reading `__slots`, a parameter of `render` that a module-scope block function
+   * would not have. A light element rebuilds nothing anyway.
+   */
+  standalone() {
+    return this.anchored() && !this.layout;
+  }
+
   /** Flat list of the loop variables in scope, outermost first. */
   loopArgs() {
     return this.loops.flatMap((loop) => [loop.item, loop.index]);
@@ -382,6 +397,7 @@ class Codegen {
     const id = this.blockDefs.length;
     const params = ['__d', ...args].join(', ');
     this.blockOf.set(node, id);
+    this.anchoredOf.add(node);
     this.blockDefs.push(
       `const __blk${id} = { ${extra}html: (${params}) => { let __o = '';\n${joinOut(body).code}\nreturn __o; } };`,
     );
@@ -400,7 +416,16 @@ class Codegen {
       this.emitBlock(chain[0].node, out, body, '', args);
       return;
     }
+    // Emitted where it stands, and still fenced. The markup is rendered once and
+    // nothing will replace it, but the anchors are how a walk gets to the nodes
+    // after it: what a branch renders is only known once the data is.
+    const fenced = this.anchored();
+    if (fenced) {
+      this.anchoredOf.add(chain[0].node);
+      this.s(out, ANCHOR_OPEN);
+    }
     this.emitBranches(chain, out, scope, topLevel);
+    if (fenced) this.s(out, ANCHOR_CLOSE);
   }
 
   emitBranches(chain, out, scope, topLevel) {
@@ -537,6 +562,7 @@ class Codegen {
       const id = this.blockDefs.length;
       this.blockDefs.push('');
       this.blockOf.set(el, id);
+      this.anchoredOf.add(el);
 
       // A <template each> renders several nodes per item, so an item is a
       // region rather than a node and needs anchors of its own to be found.
@@ -562,7 +588,15 @@ class Codegen {
       return;
     }
 
+    // The same fence an inline `if` gets, and for the same reason: how many nodes
+    // the loop produces is a question only the data answers.
+    const fenced = this.anchored();
+    if (fenced) {
+      this.anchoredOf.add(el);
+      this.s(out, ANCHOR_OPEN);
+    }
     this.emitEachBody(el, out, scope, topLevel);
+    if (fenced) this.s(out, ANCHOR_CLOSE);
   }
 
   /** `list`, `key` and `item`. One loop, taken apart so it can be reconciled. */
@@ -653,13 +687,24 @@ class Codegen {
       const filled = `__slots[${JSON.stringify(name)}]`;
       const fallback = childrenOf(el);
 
-      if (!fallback.length) {
+      // The caller's markup, and how many nodes it is only this render knows. So
+      // it is fenced like a block, and for the same reason: nothing that binds
+      // this markup afterwards can count its way past it.
+      const fenced = this.anchored();
+      if (fenced) {
+        this.anchoredOf.add(el);
+        this.s(out, ANCHOR_OPEN);
+      }
+
+      if (fallback.length) {
+        this.c(out, `if (${filled}) { __o += ${filled}; } else {`);
+        this.emitChildren(fallback, out, scope);
+        this.c(out, `}`);
+      } else {
         this.c(out, `__o += ${filled} ?? '';`);
-        return;
       }
-      this.c(out, `if (${filled}) { __o += ${filled}; } else {`);
-      this.emitChildren(fallback, out, scope);
-      this.c(out, `}`);
+
+      if (fenced) this.s(out, ANCHOR_CLOSE);
       return;
     }
 

package/src/compiler/index.js

@@ -279,6 +279,7 @@ export function compileComponent(
         components,
         shadowTags,
         blockOf: template.blockOf,
+        anchoredOf: template.anchoredOf,
         refs: new Map(template.components.map(({ tag: name, ref }) => [name, ref])),
         // The runtime prepends <style> to the shadow root, so a component's own
         // first node is not at index 0. A light element's styles are hoisted
@@ -851,7 +852,7 @@ function unusedProps(defaultNode, reads, blocks) {
 // ---- module assembly helpers ---------------------------------------------
 
 function runtimeImport(runtime) {
-  return `import { escape as __e, attr as __a, attrProp as __ap, str as __str, json, shadow as __sh, data as __data, included as __incl, textAt as __textAt, setText as __setText, setParts as __setParts, setAttr as __setAttr, setAttrProp as __setAttrProp, blockAt as __blockAt, updateBlock as __updateBlock, coerceProps, defineComponent, defineLight, html } from ${JSON.stringify(runtime)};`;
+  return `import { escape as __e, attr as __a, attrProp as __ap, str as __str, json, shadow as __sh, data as __data, included as __incl, textAt as __textAt, setText as __setText, setParts as __setParts, setAttr as __setAttr, setAttrProp as __setAttrProp, blockAt as __blockAt, afterBlock as __afterBlock, updateBlock as __updateBlock, coerceProps, defineComponent, defineLight, html } from ${JSON.stringify(runtime)};`;
 }
 
 function layoutImports(layouts) {

package/src/defaults.js

@@ -34,6 +34,11 @@ export const DEFAULTS = {
   csrf: true,
   csp: false,
   speculate: false,
+  // `<link rel="canonical">` on every page, pointing at the page's own URL. Off
+  // by default because a page mounted at a second URL on purpose would get a
+  // wrong one, and a wrong canonical is worse than none: it hands the ranking to
+  // the other URL.
+  canonical: false,
   // `(source, file) => html`, and a `.md` page under `routes/` without one is an
   // error naming the file. This package ships no Markdown parser: which flavor
   // and which extensions are the app's to pick, the same way `cache` is a store
@@ -41,6 +46,31 @@ export const DEFAULTS = {
   markdown: null,
 };
 
+/**
+ * Keys a config may set that have no default, listed so the check below does not
+ * read them as typos.
+ *
+ * A key is here when leaving it out has to mean something other than a value.
+ * There is no feed to write down as the default feed, and no store to write down
+ * as the default `cache`: absent is how an app says it wants neither.
+ */
+const UNDEFAULTED = [
+  'cache',
+  'cookieSecret',
+  'feed',
+  'fragmentHeader',
+  'metadataBase',
+  'onError',
+  'port',
+  'precache',
+  'proxy',
+  'sitemap',
+  'watchElements',
+];
+
+/** Every key `transclude.config.js` may set. */
+export const KEYS = new Set([...Object.keys(DEFAULTS), ...UNDEFAULTED]);
+
 /**
  * A config with every default filled in.
  *
@@ -50,7 +80,34 @@ export const DEFAULTS = {
  *
  * @param {object} [config] whatever `transclude.config.js` exported
  * @returns {object} the same keys, plus the ones it did not mention
+ * @throws when `canonical` is on and there is no origin to build a URL from
  */
 export function withDefaults(config = {}) {
-  return { ...DEFAULTS, ...config };
+  // A key nothing reads is a line the author believes is doing something. The
+  // failure it replaces is silent and expensive: `stylesheeet` cost a site its
+  // whole stylesheet and said nothing, because an ignored key looks exactly like
+  // a key that worked.
+  const unknown = Object.keys(config).filter((key) => !KEYS.has(key));
+  if (unknown.length) {
+    throw new Error(
+      `[transclude] transclude.config.js sets ${unknown.join(', ')}, which nothing reads. ` +
+        `The keys are ${[...KEYS].sort().join(', ')}.`,
+    );
+  }
+
+  const merged = { ...DEFAULTS, ...config };
+
+  // Refused here because there are four places that render a page and only two of
+  // them could fall back to a request's origin. Left to the render, `canonical`
+  // would work in dev and throw in the build, which is the dev-and-production
+  // disagreement this file exists to stop.
+  if (merged.canonical && !merged.metadataBase) {
+    throw new Error(
+      `[transclude] \`canonical: true\` needs \`metadataBase\`, which is the origin the ` +
+        `URL is built from. A request's own origin is the wrong one twice: behind a proxy ` +
+        `it is the internal address, and a prerendered page has no request at all.`,
+    );
+  }
+
+  return merged;
 }

package/src/document.js

@@ -177,6 +177,23 @@ const ESCAPES = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' };
 
 const escapeAttr = (value) => String(value).replace(/[&<>"]/g, (c) => ESCAPES[c]);
 
+/**
+ * The head the framework writes, as the outermost level of the merge.
+ *
+ * Through `mergeHead` rather than beside it, so a page or a layout writing its
+ * own `viewport` or `canonical` replaces this one instead of shipping a second
+ * copy. `charset` is not here: it has to be inside the first 1024 bytes, and it
+ * is not something to override.
+ *
+ * @param {string|null} canonical the page's own URL, absolute, or null for none
+ * @returns {string} one level's worth of head markup
+ */
+function frameworkHead(canonical) {
+  const tags = ['<meta name="viewport" content="width=device-width, initial-scale=1">'];
+  if (canonical) tags.push(`<link rel="canonical" href="${escapeAttr(canonical)}">`);
+  return tags.join('\n');
+}
+
 /**
  * `<html …>`, with `lang` first and whatever a loader added after it.
  *
@@ -239,7 +256,8 @@ function openTag(tag, attrs) {
  *
  * @param {object} page a compiled page module
  * @param {object} ctx the request context
- * @param {object} [options] `clientEntry`, `stylesheet`, `csp`, `lang`, `include`
+ * @param {object} [options] `clientEntry`, `stylesheet`, `csp`, `lang`, `include`,
+ *   `canonical`
  * @returns {Promise<string|Response>} a Response when a loader answered for itself
  */
 export async function renderRoute(page, ctx, options = {}) {
@@ -266,7 +284,18 @@ export async function renderRoute(page, ctx, options = {}) {
     if (mod !== page) inherited = { ...inherited, ...data };
   }
 
-  const html = renderDocument(chain, datas, options);
+  // The config's `canonical` is a yes or no; the document's is the URL. Turned
+  // into one here because this is the layer that holds the request, and because
+  // the four callers that render a page would otherwise each compute it.
+  //
+  // `route.path` and not the request's URL: a canonical URL names the page, so a
+  // query parameter has no place in it. That the path is already free of a
+  // trailing slash is Hono's doing under `trailingSlash: 'ignore'`, which is the
+  // setting that makes this option worth having.
+  const html = renderDocument(chain, datas, {
+    ...options,
+    canonical: options.canonical ? ctx.absolute(ctx.route.path) : null,
+  });
 
   // After the document exists, because the policy is built from what it inlined.
   // A prerendered page runs this once at build time and carries the result.
@@ -598,13 +627,15 @@ export function methodsOf(page) {
  * @param {object[]} chain the compiled modules, outermost first
  * @param {object[]} datas one per level, in the same order
  * @param {{ clientEntry?: string|null, stylesheet?: string|null, lang?: string,
- *   speculate?: string|null }} [options]
+ *   speculate?: string|null, canonical?: string|null }} [options] `canonical` is
+ *   the URL itself, already absolute. `renderRoute` is what turns the config's
+ *   yes-or-no into one, because this function sees no request.
  * @returns {string} the document, starting at `<!doctype html>`
  */
 export function renderDocument(
   chain,
   datas,
-  { clientEntry, stylesheet, lang = 'en', speculate = null } = {},
+  { clientEntry, stylesheet, lang = 'en', speculate = null, canonical = null } = {},
 ) {
   // Each level renders to a slot map and hands it to the level above, so a page
   // can fill more than one hole in its layout.
@@ -624,13 +655,10 @@ export function renderDocument(
   }
 
   // Everything else accumulates outermost first, so a page's <meta> comes last
-  // and a page's <style> can override a layout's.
-  // The framework's own defaults go through the merge as the outermost level, so
-  // a page or a layout writing its own `viewport` replaces this one instead of
-  // shipping beside it. `charset` is not here: it has to be inside the first
-  // 1024 bytes and is not something to override.
+  // and a page's <style> can override a layout's. The framework's own head is the
+  // outermost level; `frameworkHead` says what is in it and why.
   const [defaults, ...rest] = mergeHead([
-    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    frameworkHead(canonical),
     ...chain.map((mod, i) => mod.renderHead(datas[i])),
   ]);
   const head = rest.filter(Boolean);

package/src/runtime/index.js

@@ -308,6 +308,20 @@ function closingAnchor(open) {
   return null;
 }
 
+/**
+ * The node after a block nobody bound.
+ *
+ * A light element renders its blocks once and never rebuilds them, so it holds
+ * no state for one. The walk that finds every node after it still has to get
+ * past it, and how wide it is only the anchors say.
+ *
+ * @param {Comment} open the opening anchor
+ * @returns {Node|null}
+ */
+export function afterBlock(open) {
+  return closingAnchor(open)?.nextSibling ?? null;
+}
+
 /**
  * An item spans one node or, where it renders several, the region between its
  * own anchors. Everything downstream works on the range, so a single-element

package/src/server.js

@@ -69,7 +69,9 @@ export function baseApp(options = {}) {
    * So 'never' means strict routing plus a 301 to the one URL, and every
    * URL this framework generates is already that form: `routes/about.html` is
    * `/about`. 'ignore' is the loose router, which answers both with 200. Two URLs
-   * for one page, and nothing emits <link rel="canonical">.
+   * for one page, which is what `canonical: true` in the config answers: the
+   * loose router hands `c.req.path` over with the slash already gone, so the URL
+   * the tag names is the one form either way.
    *
    * `alwaysRedirect` matters because Hono's default only redirects a request that
    * already 404'd, and a catch-all route answers before it can. `/docs/intro/`