npm - @transclude/core - Versions diffs - 0.2.0 → 0.4.0 - Mend

@transclude/core 0.2.0 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/README.md +23 -5
package/bin/build.js +35 -3
package/bin/check.js +30 -8
package/bin/dev.js +40 -2
package/bin/release.js +53 -5
package/package.json +3 -2
package/skills/transclude/SKILL.md +20 -3
package/skills/transclude/references/elements.md +43 -0
package/skills/transclude/references/server.md +1 -0
package/src/address.js +9 -2
package/src/app.js +110 -81
package/src/compiler/ambient.js +99 -0
package/src/compiler/bind.js +34 -27
package/src/compiler/codegen.js +40 -41
package/src/compiler/directives.js +29 -0
package/src/compiler/expr.js +10 -1
package/src/compiler/html.js +41 -0
package/src/compiler/index.js +46 -8
package/src/compiler/script.js +10 -3
package/src/compiler/shim.js +14 -41
package/src/compiler/types.js +32 -5
package/src/csp.js +7 -1
package/src/document.js +63 -12
package/src/extract.js +9 -8
package/src/icons.js +174 -0
package/src/plugin.js +28 -7
package/src/precache.js +11 -1
package/src/project.js +1 -0
package/src/proxy.js +9 -1
package/src/rewrite.js +12 -5
package/src/runtime/index.js +8 -5
package/src/sitemap.js +3 -3
package/src/static-cache.js +4 -1
package/src/typecheck.js +104 -10

package/src/document.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/icons.js ADDED Viewed

@@ -0,0 +1,174 @@
+// A directory of SVG files, as one sprite.
+//
+// An icon stays a file the author manages: `app/icons/check.svg` is a whole SVG
+// document they can open, edit and diff. What a browser wants is the other
+// shape, one file of `<symbol>`s, so `<use href="/icons.svg#check">` costs one
+// cached request however many icons a page shows.
+//
+// Build-time only, like `public-files.js` and outside the portable core: the
+// sprite is bytes on disk by the time any server answers for it. `buildSprite`
+// takes contents rather than a directory anyway, so the half that decides what
+// the markup is can be tested without fixtures.
+//
+// The dev server and the build both call `readIcons` then `buildSprite`. They
+// used to be the same two lines written twice, which is how `/icons.svg` served
+// in production and 404'd in dev.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse, serializeOuter } from 'parse5';
+const SVG_NS = 'http://www.w3.org/2000/svg';
+/** Where the sprite is served. Fixed, because `<use href>` is written by hand. */
+export const SPRITE_PATH = '/icons.svg';
+/**
+ * Root attributes that must not survive into a `<symbol>`.
+ *
+ * `width` and `height` are the ones that matter: an icon file carries them so it
+ * renders on its own, and inside a sprite they fight whatever CSS sizes the
+ * `<use>`. Everything else here would be a second element's identity or a
+ * document's namespace, neither of which means anything on a symbol.
+ *
+ * Presentation attributes are deliberately not listed. `fill="none"
+ * stroke="currentColor"` on the root is how most icon sets say what they are,
+ * and dropping those turns every icon into a black blob.
+ */
+const DROPPED = new Set(['width', 'height', 'xmlns', 'xmlns:xlink', 'version', 'id', 'role']);
+const kept = (attr) => !DROPPED.has(attr.name) && !attr.name.startsWith('aria-');
+/** The `<svg>` a file starts with, or null. Parsed as HTML, which is where SVG lives. */
+function rootSvgOf(source) {
+  const find = (node) => {
+    for (const child of node.childNodes ?? []) {
+      if (child.tagName === 'svg' && child.namespaceURI === SVG_NS) return child;
+      const found = find(child);
+      if (found) return found;
+    }
+    return null;
+  };
+  return find(parse(source));
+}
+/**
+ * One file as one `<symbol>`.
+ *
+ * The parsed node is renamed and re-serialized rather than rebuilt from strings.
+ * parse5 already knows how to escape an attribute value and which SVG attributes
+ * keep their capitals, and a second hand-written serializer here would get
+ * `viewBox` wrong first.
+ *
+ * @param {{ id: string, file: string, svg: string }} icon
+ * @returns {string}
+ * @throws when the file is not an SVG, or has no `viewBox`
+ */
+function symbolFor({ id, file, svg }) {
+  const root = rootSvgOf(svg);
+  if (!root) {
+    throw new Error(`[transclude] ${file} has no <svg> in it, so it is not an icon.`);
+  }
+  // Refused rather than warned. Without a viewBox the symbol has no coordinate
+  // system to scale into, so the icon renders at some other size and nothing
+  // says why. That is the failure this check exists for.
+  const viewBox = root.attrs.find((attr) => attr.name === 'viewBox');
+  if (!viewBox) {
+    throw new Error(
+      `[transclude] ${file} has no viewBox. A symbol scales by its viewBox, so ` +
+        `without one the icon renders at the wrong size and says nothing. ` +
+        `Add viewBox="0 0 24 24", with the numbers the artwork was drawn at.`,
+    );
+  }
+  root.tagName = 'symbol';
+  root.nodeName = 'symbol';
+  root.attrs = [{ name: 'id', value: id }, ...root.attrs.filter(kept)];
+  return serializeOuter(root);
+}
+/**
+ * Every icon as one SVG document.
+ *
+ * Sorted by id, so two builds of the same directory produce the same bytes and
+ * an ETag means what it says.
+ *
+ * @param {Array<{ id: string, file: string, svg: string }>} icons
+ * @returns {string} an SVG document of `<symbol>`s
+ * @throws when two files claim one id
+ */
+export function buildSprite(icons) {
+  const byId = new Map();
+  for (const icon of icons) {
+    const first = byId.get(icon.id);
+    if (first) {
+      throw new Error(
+        `[transclude] ${first.file} and ${icon.file} would both be #${icon.id}. ` +
+          `An icon is named by its file, so two files cannot share a name even in ` +
+          `different directories. Rename one.`,
+      );
+    }
+    byId.set(icon.id, icon);
+  }
+  const sorted = [...icons].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  const symbols = sorted.map(symbolFor).join('');
+  // No `display:none` and no `<defs>`. A `<symbol>` renders nothing on its own,
+  // which is the whole reason the sprite is symbols rather than groups.
+  return `<svg xmlns="${SVG_NS}">${symbols}</svg>`;
+}
+/**
+ * Refuses a hand-written public file at the sprite's URL.
+ *
+ * Two things would answer for `/icons.svg`, and the two servers pick different
+ * winners: the build copies the public directory first and writes the sprite
+ * over it, while dev asks the public handler first and never reaches the sprite.
+ * Rather than pick one, neither runs until the author has.
+ *
+ * @param {string|null} publicDir the author's public directory, not the copy
+ * @throws when a file already sits at the sprite's URL
+ */
+export function refuseSpriteClash(publicDir) {
+  if (!publicDir) return;
+  const clash = path.join(publicDir, path.basename(SPRITE_PATH));
+  if (!fs.existsSync(clash)) return;
+  throw new Error(
+    `[transclude] ${clash} and the icons directory both answer for ${SPRITE_PATH}. ` +
+      `The sprite is built from the icons, so rename the public file or delete it.`,
+  );
+}
+/**
+ * Every `.svg` under `dir`, ready for `buildSprite`.
+ *
+ * Nested directories are read, and an icon is still named by its file alone, so
+ * `ui/check.svg` and `nav/check.svg` collide. `buildSprite` says so by name.
+ * Sorting is left to it, so one directory reads the same on any filesystem.
+ *
+ * @param {string} dir
+ * @param {string} [root] what the reported file paths are relative to
+ * @returns {Array<{ id: string, file: string, svg: string }>} empty if `dir` is absent
+ */
+export function readIcons(dir, root = dir) {
+  if (!fs.existsSync(dir)) return [];
+  const icons = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) icons.push(...readIcons(full, root));
+    else if (entry.name.endsWith('.svg')) {
+      icons.push({
+        id: path.basename(entry.name, '.svg'),
+        file: path.relative(root, full),
+        svg: fs.readFileSync(full, 'utf8'),
+      });
+    }
+  }
+  return icons;
+}

package/src/plugin.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/project.js CHANGED Viewed

@@ -86,6 +86,7 @@ const DEFAULTS = {
   routesDir: 'routes',
   elementsDir: 'elements',
   publicDir: 'public',
+  iconsDir: 'icons',
   outDir: 'dist',
   typesFile: 'app/transclude-env.d.ts',
   stylesheet: null,

package/src/proxy.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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) {