@transclude/core 0.3.0 → 0.4.0

package/README.md

@@ -18,8 +18,7 @@
 </p>
 
 HTML is the product. 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. Nothing has to run in the
-browser for the page to be correct.
+table, and any fragment of a page is a URL of its own.
 
 The same app runs on Node, Bun, Deno and workerd, the runtime behind
 Cloudflare Workers, and ships no client JavaScript by default.

package/bin/build.js

@@ -22,6 +22,7 @@ import { includeContext } from '../src/include.js';
 import { nodeLookup } from '../src/lookup.js';
 import { sitemap } from '../src/sitemap.js';
 import { etagOf, loadAssets, loadStatic } from '../src/static-cache.js';
+import { buildSprite, readIcons, refuseSpriteClash, SPRITE_PATH } from '../src/icons.js';
 import { PRECACHE_PATH, precacheDocument, precacheList } from '../src/precache.js';
 import { cookiesOf } from '../src/cookies.js';
 import { pool } from '../src/pool.js';
@@ -347,6 +348,30 @@ function countFiles(dir) {
   return total;
 }
 
+// ---- icons ----------------------------------------------------------------
+//
+// Written into `dist/public` after the author's own files are copied there, so
+// everything below that reads the directory picks the sprite up: the asset
+// module a runtime with no disk imports, the precache list, and precompression.
+// It is not counted as a public file, because the author did not write it.
+//
+// An icon named for a file the author can see is worth a stop: `buildSprite`
+// throws on a missing viewBox or two files claiming one name, and the build ends
+// there rather than shipping icons that render wrong.
+
+const iconsSrc = config.iconsDir ? path.join(root, config.appDir, config.iconsDir) : null;
+let iconCount = 0;
+
+if (iconsSrc) {
+  const icons = readIcons(iconsSrc, root);
+  if (icons.length) {
+    refuseSpriteClash(publicSrc);
+    fs.mkdirSync(publicOut, { recursive: true });
+    fs.writeFileSync(path.join(publicOut, path.basename(SPRITE_PATH)), buildSprite(icons));
+    iconCount = icons.length;
+  }
+}
+
 // ---- assets, for runtimes with no filesystem ------------------------------
 //
 // The Node server reads `dist` off a disk. A worker cannot, so the same bytes are
@@ -470,6 +495,7 @@ const summary = [
   `${dynamic.length} route${dynamic.length === 1 ? '' : 's'} left to the server`,
   `${assets.size} client entr${assets.size === 1 ? 'y' : 'ies'}`,
   ...(publicFiles ? [`${publicFiles} public file${publicFiles === 1 ? '' : 's'}`] : []),
+  ...(iconCount ? [`${iconCount} icon${iconCount === 1 ? '' : 's'}`] : []),
 ];
 console.log(`\n${summary.join(', ')}`);
 for (const url of prerendered) console.log(`  ${url}`);

package/bin/dev.js

@@ -7,6 +7,7 @@ import http from 'node:http';
 import path from 'node:path';
 import { getRequestListener } from '@hono/node-server';
 import { publicFiles as publicHandler } from '../src/public-files.js';
+import { buildSprite, readIcons, refuseSpriteClash, SPRITE_PATH } from '../src/icons.js';
 import { createServer as createViteServer } from 'vite';
 import {
   ACTION_METHODS,
@@ -62,6 +63,26 @@ const publicFiles =
     ? publicHandler(path.relative(process.cwd(), publicRoot) || '.')
     : null;
 
+const iconsRoot = config.iconsDir ? path.join(root, config.appDir, config.iconsDir) : null;
+
+/**
+ * The sprite the build writes, built per request instead.
+ *
+ * Reading a directory of small files on every request is what the rest of dev
+ * already does, and it is what makes adding an icon show up on reload. A refusal
+ * from `buildSprite` is returned as text rather than thrown, so a missing
+ * viewBox reads the same here as the message that would stop the build.
+ */
+function sprite() {
+  try {
+    const icons = readIcons(iconsRoot, root);
+    refuseSpriteClash(publicRoot);
+    return { status: 200, type: 'image/svg+xml; charset=utf-8', body: buildSprite(icons) };
+  } catch (error) {
+    return { status: 500, type: 'text/plain; charset=utf-8', body: error.message };
+  }
+}
+
 // Built before Vite, because Vite needs it: in middleware mode with no `hmr`
 // option Vite starts its own WebSocket server on another port, the browser
 // refuses that socket as cross-origin, and every edit needs a manual reload.
@@ -260,6 +281,15 @@ async function buildApp() {
     middleware: await loadMiddleware(),
   });
 
+  // A public file at this URL is refused rather than raced, so registering after
+  // `baseApp` costs nothing: the public handler can only fall through to here.
+  if (iconsRoot) {
+    app.get(SPRITE_PATH, (c) => {
+      const { status, type, body } = sprite();
+      return c.body(body, status, { 'content-type': type });
+    });
+  }
+
   // Already ordered most-specific first, so registration order is deterministic
   // rather than something to reason about per-router.
   for (const route of routes) {

package/bin/release.js

@@ -23,14 +23,44 @@ const read = (rel) => JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
 
 function usage() {
   return [
-    'Usage: node bin/release.js <version|major|minor|patch> [--dry-run]',
+    'Usage: node bin/release.js <version|major|minor|patch> --notes <file> [--dry-run]',
     '',
     '  Sets the version in both packages, verifies, commits and tags.',
+    '  The notes become the tag message, and CI makes the release page from it.',
     '  Pushing the tag is what publishes. Nothing here talks to a registry.',
     '',
   ].join('\n');
 }
 
+/**
+ * The release notes, which are the tag's message and nothing else's.
+ *
+ * They used to be typed into the GitHub release form after the fact, which is
+ * a step with nothing holding it: v0.1.0 and v0.1.1 went to npm with no release
+ * page at all. Held in the tag, they are written before the thing that publishes
+ * exists, and `publish.yml` reads them back rather than asking anyone.
+ *
+ * @param {string|undefined} file
+ * @returns {string} the notes, trimmed
+ * @throws when there is no file, it is missing, or it says nothing
+ */
+function notesFrom(file) {
+  if (!file) {
+    throw new Error(
+      'no --notes <file>. The notes are the release page, so a release without ' +
+        'them is one nobody can read. Write them, then pass the file.',
+    );
+  }
+
+  const full = path.resolve(root, file);
+  if (!fs.existsSync(full)) throw new Error(`no notes file at ${full}`);
+
+  const notes = fs.readFileSync(full, 'utf8').trim();
+  if (!notes) throw new Error(`${full} is empty`);
+
+  return notes;
+}
+
 /** `1.2.3`, or what `major`/`minor`/`patch` makes of the current one. */
 function nextVersion(current, asked) {
   if (/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(asked)) return asked;
@@ -135,7 +165,12 @@ function packed() {
 function main() {
   const args = process.argv.slice(2);
   const dryRun = args.includes('--dry-run');
-  const asked = args.find((a) => !a.startsWith('-'));
+
+  const notesAt = args.indexOf('--notes');
+  // Its value, or nowhere. Written out because `notesAt + 1` is 0 when there is
+  // no `--notes`, which is the first argument and is the version.
+  const notesValueAt = notesAt === -1 ? -1 : notesAt + 1;
+  const asked = args.find((arg, i) => !arg.startsWith('-') && i !== notesValueAt);
 
   if (!asked || args.includes('--help')) {
     process.stdout.write(usage());
@@ -145,6 +180,11 @@ function main() {
   const current = assertReleasable();
   const version = nextVersion(current, asked);
   assertUntagged(version);
+
+  // Read before the verify, which takes minutes. A missing notes file should
+  // cost a second, the way every other refusal here does.
+  const notes = notesFrom(args[notesValueAt]);
+
   process.stdout.write(`\n${current} -> ${version}\n\n`);
 
   setVersion(version);
@@ -171,14 +211,22 @@ function main() {
   const staged = run('git', ['diff', '--cached', '--name-only']).trim();
   if (staged) run('git', ['commit', '-m', `Release ${version}`]);
 
-  run('git', ['tag', '-a', `v${version}`, '-m', `Release ${version}`]);
+  // The notes are the message, not `Release x.y.z`. `publish.yml` reads them
+  // back with `git tag -l --format=%(contents)` and makes the release page from
+  // them, so this is the only copy.
+  //
+  // `--cleanup=verbatim` because the default strips every line beginning with
+  // `#` as a comment. Release notes are markdown, so that silently deletes each
+  // heading and leaves the paragraphs under it, which reads as a formatting bug
+  // on the release page and is a git default doing what it was asked.
+  run('git', ['tag', '-a', `v${version}`, '--cleanup=verbatim', '-m', notes]);
 
   process.stdout.write(
     [
       `\nTagged v${version}. Nothing has been published yet.\n\n`,
       '  git push --follow-tags\n\n',
-      'That is what publishes. The workflow builds from the tag and signs\n',
-      'provenance against it.\n\n',
+      'That is what publishes. The workflow builds from the tag, signs\n',
+      'provenance against it, and writes the release page from its message.\n\n',
     ].join(''),
   );
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transclude/core",
-  "version": "0.3.0",
+  "version": "0.4.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/skills/transclude/SKILL.md

@@ -10,8 +10,7 @@ metadata:
 # transclude
 
 HTML is the product. A page is an `.html` file, the server renders it, and what
-arrives is markup a browser already knows how to display. Nothing has to run in
-the browser for the page to be correct.
+arrives is markup a browser already knows how to display.
 
 The directory tree is the route table. The same app runs on Node, Bun, Deno and
 workerd.
@@ -38,6 +37,8 @@ app/
     api/_shared.js # not a route, the _ prefix says so
   elements/        # every custom element, one file each
     note-card.html # <note-card>, the name needs a dash
+  icons/           # one SVG file per icon, compiled to /icons.svg
+    check.svg      # <use href="/icons.svg#check">
   public/          # copied to the site root as-is
 transclude.config.js
 ```
@@ -157,6 +158,22 @@ into `<slot>`. Layouts nest, and each one loads its own data.
 <footer>${year}</footer>
 ```
 
+## Icons
+
+`app/icons/` holds one SVG file per icon. The build compiles them into a single
+`/icons.svg` of `<symbol>`s, so a page fetches one file however many icons it
+shows. The file name is the id.
+
+```html
+<svg width="16" height="16"><use href="/icons.svg#check"></use></svg>
+```
+
+Every icon file needs a `viewBox`, and two files cannot share a name. The build
+refuses either rather than shipping an icon that renders wrong.
+
+Most apps wrap this in a light element so a page names an icon instead of a URL.
+See [references/elements.md](references/elements.md).
+
 ## Commands
 
 ```sh

package/skills/transclude/references/elements.md

@@ -186,6 +186,49 @@ document.addEventListener(
 The element is then a real form field: it submits, resets and validates with the
 rest of them.
 
+## An icon element
+
+The framework compiles `app/icons/` into one `/icons.svg` and ships no element
+for it. This is the one most apps write, and it is worth copying rather than
+inventing.
+
+```html
+<script properties>
+  export default {
+    name: '',
+    label: '',
+  };
+</script>
+
+<style>
+  :scope {
+    display: inline-flex;
+    vertical-align: -0.125em;
+  }
+  svg {
+    width: 1em;
+    height: 1em;
+  }
+</style>
+
+<svg if="label" role="img" aria-label="${label}"><use href="/icons.svg#${name}"></use></svg>
+<svg else aria-hidden="true"><use href="/icons.svg#${name}"></use></svg>
+```
+
+`<svg-icon name="check">` is decorative and hidden from a screen reader, which is
+right when the icon sits beside its own label. `<svg-icon name="check"
+label="Mark as done">` is announced, which is what a control holding nothing but
+an icon needs. Do not pass a label for a decorative icon: `aria-hidden` and a
+label together leave a screen reader nothing to say.
+
+Set no `fill` or `stroke` here. Each symbol carries what its own file declared,
+and an attribute on the symbol beats a value inherited from the element, so
+setting them wins for some icon sets and loses for others. `1em` and
+`currentColor` put size and color under the surrounding text instead.
+
+Put a space between text and an icon with a `gap`, not a text node. A space is
+underlined by a link and the icon is not, which reads as a typo.
+
 ## Traps
 
 **A light element cannot `if` or `each` over a value that changes.** It does not

package/skills/transclude/references/server.md

@@ -85,6 +85,7 @@ Source is JavaScript with JSDoc. Do not convert it to TypeScript.
 | `appDir` | `'app'` | Where the app lives, relative to the project root. |
 | `routesDir` | `'routes'` | Pages and endpoints. Relative to `appDir`. |
 | `elementsDir` | `'elements'` | Custom elements. Relative to `appDir`. |
+| `iconsDir` | `'icons'` | One SVG file per icon, compiled to `/icons.svg`. Relative to `appDir`. |
 | `publicDir` | `'public'` | Copied to the site root as-is. Relative to `appDir`. |
 | `outDir` | `'dist'` | Where the build writes. |
 | `stylesheet` | — | One global stylesheet, relative to the project root. |

package/src/icons.js

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

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