@transclude/core 0.2.0 → 0.3.0

package/src/compiler/shim.js

@@ -14,6 +14,8 @@
 // came from.
 
 import { parse, parseExpressionAt } from 'acorn';
+import { ambientJsdoc } from './ambient.js';
+import { parseEach } from './directives.js';
 import { childrenOf } from './codegen.js';
 import { splitInterpolations } from './interp.js';
 import { splitBlocks } from './index.js';
@@ -46,23 +48,7 @@ const PASS_THROUGH = /^(?:data|aria|hx)-/;
  * it type-checked happily and caught nothing. The endpoint shim
  * did exactly that.
  */
-const COOKIES_TYPEDEF =
-  '/**\n' +
-  ' * @typedef {{ path?: string; domain?: string; maxAge?: number; expires?: Date;\n' +
-  ' *   httpOnly?: boolean; secure?: boolean; sameSite?: "Strict" | "Lax" | "None" }} __CookieOptions\n' +
-  ' */\n' +
-  '/**\n' +
-  ' * @typedef {{\n' +
-  ' *   get(name: string): string | undefined;\n' +
-  ' *   all(): Record<string, string>;\n' +
-  ' *   set(name: string, value: string, options?: __CookieOptions): void;\n' +
-  ' *   delete(name: string, options?: __CookieOptions): void;\n' +
-  ' *   signed: {\n' +
-  ' *     get(name: string): Promise<string | undefined>;\n' +
-  ' *     all(): Promise<Record<string, string>>;\n' +
-  ' *     set(name: string, value: string, options?: __CookieOptions): Promise<void>;\n' +
-  ' *   };\n' +
-  ' * }} __Cookies\n */\n\n';
+const COOKIES_TYPEDEF = `${ambientJsdoc(['__CookieOptions', '__Cookies'])}\n`;
 
 class Builder {
   constructor() {
@@ -278,20 +264,9 @@ export function buildShim(source, { kind, shadow = false, contextType = null, co
   // types its own.
   out.add('export {};\n');
 
-  // Two jobs, both about letting the author write plain JS.
-  //
-  // The mapping is what keeps `${user.nmae}` an error. TypeScript treats a type
-  // that came straight from an object literal in a .js file as open for expando
-  // properties, so reading an undeclared one is allowed. Remapping the keys gives
-  // an ordinary object type, where it is not.
-  //
-  // The conditional widens a bare `[]`, which otherwise infers `never[]` and
-  // turns "no annotation" from "less checking" into a page of errors about a
-  // type nobody wrote.
-  out.add(
-    '/**\n * @template T\n' +
-      ' * @typedef {{ [K in keyof T]: T[K] extends never[] ? any[] : T[K] }} __Shape\n */\n',
-  );
+  // Both jobs `__Shape` does are about letting the author write plain JS, and
+  // both are written out in `ambient.js`.
+  out.add(ambientJsdoc(['__Shape']));
 
   out.add(COOKIES_TYPEDEF);
 
@@ -573,20 +548,18 @@ function emitNodes(nodes, out, scope, components, depth) {
     let closes = 0;
 
     if (each) {
-      const spec = /^\s*([A-Za-z_$][\w$]*)\s*(?:,\s*([A-Za-z_$][\w$]*)\s*)?\s+of\s+([\s\S]+?)\s*$/.exec(
-        each.value,
-      );
+      const spec = parseEach(each.value);
       if (spec) {
-        const listOffset = attrValueOffset(node, 'each') + each.value.indexOf(spec[3]);
+        const listOffset = attrValueOffset(node, 'each') + each.value.indexOf(spec.list);
         indent(out, depth);
-        out.add(`for (const ${spec[1]} of `);
-        emitExpression(spec[3], listOffset, out, scope);
+        out.add(`for (const ${spec.item} of `);
+        emitExpression(spec.list, listOffset, out, scope);
         out.add(') {\n');
-        inner.add(spec[1]);
-        if (spec[2]) {
+        inner.add(spec.item);
+        if (spec.index) {
           indent(out, depth + 1);
-          out.add(`const ${spec[2]}: number = 0;\n`);
-          inner.add(spec[2]);
+          out.add(`const ${spec.index}: number = 0;\n`);
+          inner.add(spec.index);
         }
         closes++;
       }

package/src/compiler/types.js

@@ -3,15 +3,24 @@
 // Everything here is a type *string* produced by tsc's own printer, so this file
 // formats and names things and nothing else. Nothing infers.
 
+import { ambientDeclarations } from './ambient.js';
+
 /**
  * @param {{ components?: object[], partials?: object[], layouts?: object[],
- *   pages?: object[] }} [what] each element carries its `tag`, its props `type`,
- *   its `members`, its `state` and whether anything `upgrades` it. `partials` is
- *   the light elements: the key is the old name and is load-bearing until the
- *   callers change with it.
+ *   pages?: object[], types?: {name: string, type: string}[] }} [what] each
+ *   element carries its `tag`, its props `type`, its `members`, its `state` and
+ *   whether anything `upgrades` it. `partials` is the light elements: the key is
+ *   the old name and is load-bearing until the callers change with it. `types`
+ *   are the names the app declared that the strings below use.
  * @returns {string} the contents of transclude-env.d.ts
  */
-export function emitTypes({ components = [], partials = [], layouts = [], pages = [] } = {}) {
+export function emitTypes({
+  components = [],
+  partials = [],
+  layouts = [],
+  pages = [],
+  types = [],
+} = {}) {
   const out = [
     '// Generated by transclude. Do not edit. `npm run check` rewrites it.',
     '//',
@@ -21,6 +30,9 @@ export function emitTypes({ components = [], partials = [], layouts = [], pages
     '',
   ];
 
+  // Where the declarations go once it is known which are needed.
+  const head = out.length;
+
   for (const { tag, type, members, state } of [...components, ...partials]) {
     out.push(`/** Properties of \`<${tag}>\`, from its <script properties> block. */`);
     out.push(`export type ${interfaceName(tag)}Props = ${pretty(type)};`);
@@ -83,6 +95,21 @@ export function emitTypes({ components = [], partials = [], layouts = [], pages
     out.push('');
   }
 
+  // Written last and put first. What has to be declared is whatever the types
+  // above ended up naming, which is not known until they are all built.
+  const body = out.slice(head).join('\n');
+  const declared = [
+    ...ambientDeclarations(body, (type) => pretty(type)),
+    ...(types.length
+      ? [
+          '// Declared by the app, in the file each was written in.',
+          ...types.map(({ name, type }) => `type ${name} = ${pretty(type)};`),
+          '',
+        ]
+      : []),
+  ];
+
+  out.splice(head, 0, ...declared);
   return out.join('\n');
 }
 

package/src/csp.js

@@ -104,9 +104,15 @@ export async function policyFor(html, { directives = CSP_DEFAULTS } = {}) {
     inline.filter((one) => one.kind === 'style').map((one) => sha256(one.body)),
   );
 
+  // Which set `'hashes'` stands for, by directive. Anything else gets none:
+  // there is nothing to hash for `default-src`, and a directive carrying a hash
+  // ignores `'unsafe-inline'` outright, so handing it an empty list is wrong in a
+  // way that only shows up in a browser.
+  const hashesFor = { 'script-src': scripts, 'style-src': styles };
+
   const parts = [];
   for (const [name, sources] of Object.entries(directives)) {
-    const hashes = name === 'script-src' ? scripts : name === 'style-src' ? styles : [];
+    const hashes = hashesFor[name] ?? [];
     const resolved = sources.flatMap((source) => (source === "'hashes'" ? hashes : [source]));
 
     // A directive left with nothing is dropped. An empty source list means

package/src/document.js

@@ -192,29 +192,36 @@ const escapeAttr = (value) => String(value).replace(/[&<>"]/g, (c) => ESCAPES[c]
  * as one tag, because two `data-theme` attributes would leave the parser taking
  * the first, which is the outermost, which is backwards.
  */
-function htmlAttrsOf(chain, datas) {
+function attrsOf(chain, datas, render) {
   const merged = { __proto__: null };
   for (let i = 0; i < chain.length; i++) {
-    Object.assign(merged, chain[i].renderHtmlAttrs?.(datas[i]));
+    Object.assign(merged, chain[i][render]?.(datas[i]));
   }
   return merged;
 }
 
-function htmlOpenTag(lang, attrs) {
+/**
+ * `<html …>` or `<body …>`, from a merged attribute object.
+ *
+ * @param {string} tag
+ * @param {object} attrs
+ * @returns {string} the open tag
+ */
+function openTag(tag, attrs) {
   const parts = [];
 
-  for (const [name, value] of Object.entries({ lang, ...attrs })) {
+  for (const [name, value] of Object.entries(attrs)) {
     if (value === false || value === null || value === undefined) continue;
     if (!ATTR_NAME.test(name)) {
       throw new Error(
-        `[transclude] \`${name}\` cannot be an attribute on <html>. ` +
+        `[transclude] \`${name}\` cannot be an attribute on <${tag}>. ` +
           `Use lowercase letters, digits and dashes.`,
       );
     }
     parts.push(value === true ? name : `${name}="${escapeAttr(value)}"`);
   }
 
-  return `<html ${parts.join(' ')}>`;
+  return parts.length ? `<${tag} ${parts.join(' ')}>` : `<${tag}>`;
 }
 
 /**
@@ -290,9 +297,19 @@ export const INCLUDE_DEPTH = 10;
  */
 export function paramsFor(route, pathname) {
   const names = [];
+
+  const catchAll = (_, name) => {
+    names.push(name);
+    return '/(.+)';
+  };
+  const segment = (_, name) => {
+    names.push(name);
+    return '([^/]+)';
+  };
+
   const source = route.pattern
-    .replace(/\/:([A-Za-z0-9_]+)\{\.\+\}/g, (_, name) => (names.push(name), '/(.+)'))
-    .replace(/:([A-Za-z0-9_]+)/g, (_, name) => (names.push(name), '([^/]+)'));
+    .replace(/\/:([A-Za-z0-9_]+)\{\.\+\}/g, catchAll)
+    .replace(/:([A-Za-z0-9_]+)/g, segment);
 
   const found = new RegExp(`^${source}$`).exec(pathname);
   if (!found) return null;
@@ -300,6 +317,22 @@ export function paramsFor(route, pathname) {
   return Object.fromEntries(names.map((name, at) => [name, decodeURIComponent(found[at + 1])]));
 }
 
+/**
+ * The URL a route and a set of params name. The other direction from
+ * `paramsFor`, and the two have to agree.
+ *
+ * The build writes a file at this URL and the sitemap advertises it. Each had
+ * its own copy of the substitution, so a pattern shape one handled and the other
+ * did not would have meant a sitemap listing URLs that were never written.
+ *
+ * @param {{ pattern: string }} route
+ * @param {Record<string, string>} params
+ * @returns {string} the pattern with every `:name` filled in
+ */
+export function urlFor(route, params) {
+  return route.pattern.replace(/:(\w+)(\{[^}]*\})?/g, (_, name) => String(params[name] ?? ''));
+}
+
 /**
  * @param {Array<{ key: string, kind: string, where: string, id: string }>} includes
  * @param {object} ctx
@@ -401,9 +434,15 @@ export async function renderFragment(page, ctx, { region = null, ...options } =
     data = { ...data, __included: await resolveIncludes(last.includes, ctx, request) };
   }
 
+  // `true` is `__named`: the fragment keeps the id it was declared with, because
+  // that is what a swap is matched against. An include of the same region passes
+  // false, since two copies of one id in a document is the bug that rule exists
+  // to stop.
+  const named = true;
+
   // No region named: the page's whole body, still without its layouts.
-  if (!target) return page.render(data, {}, true).default ?? '';
-  return target(data, {}, true);
+  if (!target) return page.render(data, {}, named).default ?? '';
+  return target(data, {}, named);
 }
 
 /**
@@ -518,6 +557,18 @@ export function methodsOf(page) {
   return ['GET', ...ACTION_METHODS.filter((method) => typeof page?.[method] === 'function')];
 }
 
+/**
+ * The whole document, from the innermost page outward.
+ *
+ * `chain` is the layouts and then the page; `datas` is what each one's loader
+ * returned, in the same order. Both are walked from the end, because a level
+ * renders into the slot map of the one above it.
+ *
+ * @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 }} [options]
+ * @returns {string} the document, starting at `<!doctype html>`
+ */
 export function renderDocument(
   chain,
   datas,
@@ -585,7 +636,7 @@ export function renderDocument(
   ];
 
   return `<!doctype html>
-${htmlOpenTag(lang, htmlAttrsOf(chain, datas))}
+${openTag('html', { lang, ...attrsOf(chain, datas, 'renderHtmlAttrs') })}
 <head>
 <meta charset="utf-8">
 ${defaults}
@@ -595,7 +646,7 @@ ${stylesheet ? `<link rel="stylesheet" href="${stylesheet}">` : ''}
 ${head.join('\n')}
 ${css.join('\n')}
 </head>
-<body>
+${openTag('body', attrsOf(chain, datas, 'renderBodyAttrs'))}
 ${body}
 ${clientEntry ? `<script type="module" src="${clientEntry}"></script>` : ''}
 </body>

package/src/extract.js

@@ -327,13 +327,14 @@ export function listFragments(input) {
   return doc.order.map(({ id, element, implicit }) => {
     const tag = tagOf(element);
     const rank = rankOf(element);
-    return {
-      id,
-      implicit,
-      tag,
-      rank,
-      kind: rank ? 'heading-run' : tag === 'dt' ? 'dt-run' : 'element',
-      text: textOf(element).replace(/\s+/g, ' ').trim().slice(0, 120),
-    };
+    // A heading and a `<dt>` each name the run of content that follows them. Any
+    // other element is only itself.
+    let kind = 'element';
+    if (rank) kind = 'heading-run';
+    else if (tag === 'dt') kind = 'dt-run';
+
+    const collapsed = textOf(element).replace(/\s+/g, ' ').trim();
+
+    return { id, implicit, tag, rank, kind, text: collapsed.slice(0, 120) };
   });
 }

package/src/plugin.js

@@ -164,11 +164,25 @@ export default function transclude({
     };
   };
 
+  /** The 404 or the 500 page, as the manifest holds it, or null if there is none. */
+  const errorPageEntry = (route) => {
+    if (!route) return null;
+    return { id: route.id, rel: route.rel, params: [], client: clientManifest(route) };
+  };
+
   const report = (label, warnings) => {
     for (const w of warnings ?? []) console.warn(`[transclude] ${label}: ${w}`);
   };
 
-  return {
+  // The bins pass this plugin to Vite themselves, and Vite merges a project's
+  // own `vite.config.js` rather than deduping, so a project that registers it
+  // again gets two: the second scans the app a second time and adds a second
+  // dev watcher, which reloads the browser twice for one edit. `api` is the one
+  // thing Vite keeps by reference when it copies a plugin, so it is how an
+  // instance recognizes itself in the resolved list.
+  let duplicate = false;
+
+  const plugin = {
     name: 'transclude',
     enforce: 'pre',
 
@@ -194,12 +208,10 @@ export default function transclude({
             rel: route.rel,
             params: route.params,
           })),
-          notFound: scanned.notFound
-            ? { id: scanned.notFound.id, rel: scanned.notFound.rel, params: [], client: clientManifest(scanned.notFound) }
-            : null,
-          error: scanned.error
-            ? { id: scanned.error.id, rel: scanned.error.rel, params: [], client: clientManifest(scanned.error) }
-            : null,
+          // Neither is a route: both are reached for rather than matched, so
+          // they carry no pattern and no params.
+          notFound: errorPageEntry(scanned.notFound),
+          error: errorPageEntry(scanned.error),
         };
       },
       configure(config) {
@@ -211,6 +223,9 @@ export default function transclude({
     },
 
     configResolved(config) {
+      duplicate = config.plugins.find((p) => p.name === 'transclude')?.api !== plugin.api;
+      if (duplicate) return;
+
       root = config.root;
       app = path.resolve(root, appDir);
       runtime = '/' + path.relative(root, RUNTIME_FILE).split(path.sep).join('/');
@@ -218,6 +233,7 @@ export default function transclude({
     },
 
     resolveId(id, importer) {
+      if (duplicate) return null;
       if (id === SERVER_ENTRY || id === ELEMENTS_ENTRY) return '\0' + id;
       if (
         id.startsWith(P_COMPONENT) ||
@@ -237,6 +253,7 @@ export default function transclude({
     },
 
     load(id) {
+      if (duplicate) return null;
       if (!id.startsWith('\0virtual:transclude-')) return null;
       const virt = id.slice(1);
 
@@ -350,6 +367,8 @@ export const middleware = ${hasMiddleware ? '__middleware ?? null' : 'null'};
     },
 
     configureServer(server) {
+      if (duplicate) return;
+
       server.watcher.on('all', (_event, file) => {
         if (!file.endsWith('.html')) return;
         if (!file.startsWith(app)) return;
@@ -363,6 +382,8 @@ export const middleware = ${hasMiddleware ? '__middleware ?? null' : 'null'};
       });
     },
   };
+
+  return plugin;
 }
 
 /**

package/src/precache.js

@@ -20,6 +20,13 @@
  * @typedef {{ url: string, revision: string|null }} Entry
  */
 
+/** Orders two entries by URL. */
+function byUrl(a, b) {
+  if (a.url < b.url) return -1;
+  if (a.url > b.url) return 1;
+  return 0;
+}
+
 /**
  * @param {object} sources
  * @param {Iterable<[string, object]>} sources.pages prerendered documents
@@ -46,7 +53,10 @@ export function precacheList({ pages, assets, files = [] }) {
     }
   }
 
-  entries.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+  // Sorted by URL so two builds of the same site write the same file. Compared
+  // as code units rather than with `localeCompare`, which is locale-dependent
+  // and would order the list differently on different machines.
+  entries.sort(byUrl);
   return entries;
 }
 

package/src/proxy.js

@@ -163,6 +163,11 @@ export function documentStore(max = DEFAULTS.cache) {
   };
 }
 
+/** The entries with a value, so an empty one is left out rather than sent blank. */
+function present(headers) {
+  return Object.fromEntries(Object.entries(headers).filter(([, value]) => value));
+}
+
 /**
  * A foreign document, fetched, cleaned and indexed.
  *
@@ -183,6 +188,9 @@ export async function readForeign(url, options = {}, deps = {}) {
   const held = store?.get(url) ?? null;
   if (held && now() - held.at < config.maxAge) return held;
 
+  // A held copy with no ETag and no Last-Modified gives nothing to revalidate
+  // against, and sending the headers empty would ask the origin to compare
+  // against nothing. `present` drops them.
   const revalidate = held
     ? { 'if-none-match': held.etag ?? '', 'if-modified-since': held.lastModified ?? '' }
     : {};
@@ -192,7 +200,7 @@ export async function readForeign(url, options = {}, deps = {}) {
     ? (at, init) =>
         get(at, {
           ...init,
-          headers: { ...init.headers, ...Object.fromEntries(Object.entries(revalidate).filter(([, v]) => v)) },
+          headers: { ...init.headers, ...present(revalidate) },
         })
     : get;
 

package/src/rewrite.js

@@ -167,6 +167,9 @@ const absolute = (value, base) => {
   }
 };
 
+/** What HTML counts as whitespace between srcset candidates. */
+const SRCSET_SPACE = new Set([' ', '\t', '\n', '\r', '\f']);
+
 /**
  * A `srcset`, as a list of candidates.
  *
@@ -180,7 +183,7 @@ const absolute = (value, base) => {
  */
 export function parseSrcset(value) {
   const out = [];
-  const ws = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f';
+  const ws = (c) => SRCSET_SPACE.has(c);
   let i = 0;
 
   while (i < value.length) {
@@ -260,10 +263,14 @@ export function absolutize(root, base) {
         if (!holdsUrl || !attr.value.trim()) continue;
         if (/^(data|blob|mailto:|tel:|javascript:)/i.test(attr.value.trim())) continue;
 
-        attr.value =
-          attr.name === 'ping'
-            ? attr.value.split(/\s+/).filter(Boolean).map((u) => absolute(u, base)).join(' ')
-            : absolute(attr.value, base);
+        // `ping` is the one attribute here holding a list rather than a URL.
+        if (attr.name !== 'ping') {
+          attr.value = absolute(attr.value, base);
+          continue;
+        }
+
+        const urls = attr.value.split(/\s+/).filter(Boolean);
+        attr.value = urls.map((url) => absolute(url, base)).join(' ');
       }
 
       if (child.tagName === 'style') {

package/src/runtime/index.js

@@ -954,14 +954,17 @@ export function defineLight(def, init) {
 
   if (typeof customElements === 'undefined') return;
   if (customElements.get(def.tag)) return;
+
   // No behavior to attach means nothing to register. A light element with no
   // <script> is markup that was already rendered, and it ships no JavaScript at
-  // all, accessors included. That is the trade the
-  // zero-JS default makes.
+  // all, accessors included. That is the trade the zero-JS default makes.
   //
-  // Being a form control counts as behavior: a shadow root is not required to be
-  // one, and an element that submits a value has to exist to do it.
-  if (!init && !hasMembers(def) && !def.formAssociated && !hasState(def)) return;
+  // Being a form control counts: a shadow root is not required to be one, and an
+  // element that submits a value has to exist to do it. So does state, because
+  // its accessor is what schedules the write.
+  const hasBehavior =
+    Boolean(init) || hasMembers(def) || def.formAssociated === true || hasState(def);
+  if (!hasBehavior) return;
 
   class Light extends HTMLElement {
     // Every declared prop, so a change reaches the template. A light element

package/src/sitemap.js

@@ -6,6 +6,8 @@
 // else (a route with no `paths`, an endpoint, an error page) is not a page a
 // crawler can reach by guessing, so it is left out.
 
+import { urlFor } from './document.js';
+
 /** The protocol's cap for one file. Past it the response is an index of files. */
 const LIMIT = 50000;
 
@@ -56,9 +58,7 @@ export async function sitemapEntries(manifest, pages, { entries = [], exclude =
     if (typeof page?.paths !== 'function') continue;
 
     for (const params of (await page.paths()) ?? []) {
-      found.push({
-        path: route.pattern.replace(/:(\w+)(\{[^}]*\})?/g, (_, name) => String(params[name] ?? '')),
-      });
+      found.push({ path: urlFor(route, params) });
     }
   }
 

package/src/static-cache.js

@@ -139,7 +139,10 @@ function read(file) {
  * @returns {string} a quoted ETag
  */
 export function etagOf(body) {
-  return `"${createHash('sha1').update(body).digest('base64url').slice(0, 20)}"`;
+  const digest = createHash('sha1').update(body).digest('base64url');
+  // Twenty characters of base64url is 120 bits, which is far more than a cache
+  // key needs and short enough to read in a header.
+  return `"${digest.slice(0, 20)}"`;
 }
 
 function variantSize(file) {