@transclude/core 0.2.0 → 0.4.0

package/README.md

@@ -1,8 +1,24 @@
-# transclude
+<h1 align="center">transclude</h1>
+
+<p align="center">An HTML-first server-side web framework.</p>
+
+<p align="center">
+  <a href="https://github.com/transclude-dev/transclude/actions/workflows/ci.yml"
+    ><img alt="CI" src="https://github.com/transclude-dev/transclude/actions/workflows/ci.yml/badge.svg"
+  /></a>
+  <a href="https://www.npmjs.com/package/@transclude/core"
+    ><img alt="npm" src="https://img.shields.io/npm/v/%40transclude%2Fcore?color=0b7285"
+  /></a>
+  <a href="https://transclude.dev/docs/runtimes"
+    ><img alt="node" src="https://img.shields.io/node/v/%40transclude%2Fcore?color=0b7285"
+  /></a>
+  <a href="https://github.com/transclude-dev/transclude/blob/main/LICENSE"
+    ><img alt="MIT" src="https://img.shields.io/npm/l/%40transclude%2Fcore?color=0b7285"
+  /></a>
+</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.
@@ -52,7 +68,7 @@ so a swap cannot drift from the page it replaces part of.
 
 ## What is in it
 
-- **Pages and endpoints.** An `.html` file answers GET; its `POST`, `PUT`,
+- **Pages and endpoints.** An `.html` file responds to GET; its `POST`, `PUT`,
   `PATCH` and `DELETE` exports answer the rest, so a plain `<form method="post">`
   works. A `.js` file in the same tree returns a `Response`.
 - **Fragments.** Mark an element `fragment` and it has a URL of its own. htmx,
@@ -106,6 +122,7 @@ npm run htmx          # the same, driven by htmx, on http://localhost:1965
 npm run includes      # transclusion on http://localhost:1966
 npm run auth          # a guarded section on http://localhost:1967
 npm run live          # server-sent events on http://localhost:1968
+npm run elements      # light and shadow elements on http://localhost:1969
 npm run check:src     # type-check the framework itself
 ```
 
@@ -115,7 +132,8 @@ prerendered site with a sitemap and a feed, `search` swaps a fragment into a
 page that works without it, `htmx` does the same with htmx and the
 `HX-Target` header, `includes` shows transclusion from three sources,
 `auth` guards a section with a layout and a signed cookie, `live` pushes
-updates over server-sent events, and `showcase` uses every feature and is where the
+updates over server-sent events, `elements` puts a light and a shadow element
+side by side, and `showcase` uses every feature and is where the
 browser checks live, because those need an app to run against. `www/` is the site at transclude.dev: a landing page, the
 documentation under `/docs`, and itself built with the framework.
 

package/bin/build.js

@@ -16,12 +16,13 @@ import { pathToFileURL } from 'node:url';
 import { build } from 'vite';
 import transclude from '../src/plugin.js';
 import { loadProject } from '../src/project.js';
-import { absoluteFrom, renderRoute, responseOf } from '../src/document.js';
+import { absoluteFrom, renderRoute, responseOf, urlFor } from '../src/document.js';
 import { feed, feedPath } from '../src/feed.js';
 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';
@@ -111,9 +112,15 @@ await build({
   },
 });
 
+// A worker entry imports this bundle, and an editor set to check the app's JS
+// then checks a file nobody wrote. Twenty errors in the showcase, all of them
+// about generated code. The banner is what keeps it out of that program.
+const entry = path.join(dist, 'server/entry.js');
+fs.writeFileSync(entry, `// @ts-nocheck\n${fs.readFileSync(entry, 'utf8')}`);
+
 // ---- prerender ------------------------------------------------------------
 
-const { pages } = await import(pathToFileURL(path.join(dist, 'server/entry.js')).href);
+const { pages } = await import(pathToFileURL(entry).href);
 
 /**
  * A static route has one URL. A dynamic route has as many as its `paths` export
@@ -134,7 +141,7 @@ async function urlsFor(route) {
 
   const listed = (await paths()) ?? [];
   return listed.map((params) => ({
-    url: route.pattern.replace(/:(\w+)(\{[^}]*\})?/g, (_, name) => String(params[name] ?? '')),
+    url: urlFor(route, params),
     params,
   }));
 }
@@ -341,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
@@ -464,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/check.js

@@ -23,7 +23,22 @@ if (!fs.existsSync(types) || fs.readFileSync(types, 'utf8') !== next) {
 
 // Nothing downstream reads this file, so nothing else would notice it being
 // wrong. Parse what we just wrote, or a bad identifier ships silently.
-const emitted = ts.createProgram([types], { noEmit: true, skipLibCheck: true });
+//
+// `skipLibCheck` has to be off, and it was on. This is a .d.ts, which is the one
+// kind of file that flag skips, so the guard checked nothing at all: every
+// project shipped a file naming `__Cookies` and declaring it nowhere. An editor
+// missed it too, because a jsconfig.json implies the same flag.
+//
+// `types: []` keeps it to this file: whatever `@types` a project happens to have
+// installed is not what is being checked here, and one of them failing to
+// resolve its own dependency would read as our file being broken.
+const emitted = ts.createProgram([types], {
+  noEmit: true,
+  skipLibCheck: false,
+  types: [],
+  target: ts.ScriptTarget.ESNext,
+  lib: ['lib.esnext.d.ts', 'lib.dom.d.ts'],
+});
 const broken = [
   ...emitted.getSyntacticDiagnostics(),
   ...emitted.getSemanticDiagnostics(),
@@ -63,16 +78,23 @@ for (const file of files) {
     const text = lines[line - 1] ?? '';
     const trimmed = text.replace(/^\s+/, '');
     const shift = text.length - trimmed.length;
+    // The caret line is drawn under the trimmed source, so the column moves left
+    // by however much indentation was cut. A run is capped so one long span does
+    // not wrap the terminal.
+    const pad = ' '.repeat(Math.max(0, column - shift));
+    const run = '~'.repeat(Math.max(1, Math.min(diagnostic.length, 60)));
+
     console.log(`\n    ${trimmed}`);
-    console.log(`    ${' '.repeat(Math.max(0, column - shift))}${'~'.repeat(Math.max(1, Math.min(diagnostic.length, 60)))}`);
+    console.log(`    ${pad}${run}`);
   }
 }
 
-const total = errors + warnings;
-console.log(
-  total
-    ? `\n${errors} error${errors === 1 ? '' : 's'}, ${warnings} warning${warnings === 1 ? '' : 's'} in ${files.length} files`
-    : `\nNo type errors in ${files.length} files.`,
-);
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+if (errors + warnings) {
+  console.log(`\n${plural(errors, 'error')}, ${plural(warnings, 'warning')} in ${files.length} files`);
+} else {
+  console.log(`\nNo type errors in ${files.length} files.`);
+}
 
 process.exitCode = errors ? 1 : 0;

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,
@@ -19,7 +20,7 @@ import {
   runAction,
   withEnvelope,
 } from '../src/document.js';
-import { clientEntryUrl, pageModuleId } from '../src/plugin.js';
+import transclude, { clientEntryUrl, pageModuleId } from '../src/plugin.js';
 import { resolveRoutesDir, scanRoutes } from '../src/routes.js';
 import { baseApp, endpointMethods, runEndpoint, SERVER_FILE } from '../src/server.js';
 import { randomBytes } from 'node:crypto';
@@ -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.
@@ -71,6 +92,11 @@ const server = http.createServer();
 const vite = await createViteServer({
   root,
   appType: 'custom',
+  // Passed here rather than left to the project's own `vite.config.js`, which is
+  // where dev used to get it. A project needs no Vite config at all, and the one
+  // built here is the one `loadProject` filled in, so dev compiles against the
+  // same config the build does. `configResolved` ignores a second registration.
+  plugins: [transclude(config)],
   server: { middlewareMode: true, hmr: { server } },
   // Vite would serve these itself, ahead of Hono, and production would serve
   // them a different way, which is how dev and production come to disagree. One
@@ -229,7 +255,10 @@ async function loadMiddleware() {
   if (!fs.existsSync(serverFile)) return null;
 
   const url = `/${config.appDir}/${SERVER_FILE}`;
-  const node = await vite.moduleGraph.getModuleByUrl(url, true);
+  // Vite's second argument is `ssr`. This module is only ever loaded through
+  // `ssrLoadModule`, so the SSR graph is the one holding it.
+  const ssr = true;
+  const node = await vite.moduleGraph.getModuleByUrl(url, ssr);
   if (node) vite.moduleGraph.invalidateModule(node);
 
   const mod = await vite.ssrLoadModule(url);
@@ -252,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.2.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",
@@ -57,7 +57,7 @@
   ],
   "scripts": {
     "test": "node --test \"test/**/*.test.js\"",
-    "test:examples": "npm test --prefix examples/showcase && npm test --prefix examples/todomvc && npm test --prefix examples/blog && npm test --prefix examples/search && npm test --prefix examples/htmx && npm test --prefix examples/includes && npm test --prefix examples/auth && npm test --prefix examples/live",
+    "test:examples": "npm test --prefix examples/showcase && npm test --prefix examples/todomvc && npm test --prefix examples/blog && npm test --prefix examples/search && npm test --prefix examples/htmx && npm test --prefix examples/includes && npm test --prefix examples/auth && npm test --prefix examples/live && npm test --prefix examples/elements",
     "test:www": "npm test --prefix www",
     "showcase": "npm run dev --prefix examples/showcase",
     "todomvc": "npm run dev --prefix examples/todomvc",
@@ -67,6 +67,7 @@
     "includes": "npm run dev --prefix examples/includes",
     "auth": "npm run dev --prefix examples/auth",
     "live": "npm run dev --prefix examples/live",
+    "elements": "npm run dev --prefix examples/elements",
     "www": "npm run dev --prefix www",
     "check:src": "tsc -p tsconfig.src.json",
     "release": "node bin/release.js"

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
 ```
@@ -96,7 +97,7 @@ the render, which is how a layout does a login redirect.
 
 ## Forms and actions
 
-A page answers GET with its loader. Other verbs are named exports on the same
+A page responds to GET with its loader. Other verbs are named exports on the same
 file.
 
 ```html
@@ -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/address.js

@@ -69,8 +69,15 @@ export function parseV6(text) {
   const halves = body.split('::');
   if (halves.length > 2) return null;
 
-  const read = (part) =>
-    part === '' ? [] : part.split(':').map((g) => (/^[0-9a-f]{1,4}$/i.test(g) ? parseInt(g, 16) : NaN));
+  // Each half of a `::` is groups of up to four hex digits. A group that is not
+  // becomes NaN, which the caller checks for rather than throwing here.
+  const read = (part) => {
+    if (part === '') return [];
+    return part.split(':').map((group) => {
+      if (!/^[0-9a-f]{1,4}$/i.test(group)) return NaN;
+      return parseInt(group, 16);
+    });
+  };
 
   const head = read(halves[0]);
   const rest = halves.length === 2 ? read(halves[1]) : [];