npm - @transclude/core - Versions diffs - 0.1.1 → 0.3.0 - Mend

@transclude/core 0.1.1 → 0.3.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 (38) hide show

package/LICENSE +1 -1
package/README.md +65 -14
package/bin/build.js +22 -4
package/bin/check.js +30 -8
package/bin/dev.js +10 -2
package/bin/release.js +19 -4
package/package.json +13 -4
package/skills/transclude/SKILL.md +219 -0
package/skills/transclude/references/elements.md +206 -0
package/skills/transclude/references/fragments.md +168 -0
package/skills/transclude/references/server.md +155 -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 +59 -35
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 +63 -11
package/src/compiler/script.js +40 -11
package/src/compiler/shim.js +24 -45
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/negotiate.js +1 -1
package/src/plugin.js +28 -7
package/src/precache.js +11 -1
package/src/project.js +29 -1
package/src/proxy.js +9 -1
package/src/rewrite.js +12 -5
package/src/routes.js +1 -1
package/src/runtime/index.js +12 -9
package/src/server.js +2 -2
package/src/sitemap.js +3 -3
package/src/static-cache.js +6 -3
package/src/typecheck.js +105 -11

package/skills/transclude/references/elements.md ADDED Viewed

@@ -0,0 +1,206 @@
+# Elements
+An `.html` file in `app/elements/` becomes a custom element. The file name is
+the tag name and it needs a dash.
+## Light DOM, the default
+No shadow root, no boundary. Page CSS reaches it, `<label for>` works, and no
+JavaScript is shipped.
+```html
+<!-- app/elements/site-note.html -->
+<script properties>
+  export default {
+    tone: 'neutral',
+  };
+</script>
+<style>
+  :scope {
+    display: block;
+    border-left: 3px solid var(--rule);
+    padding: 0.5rem 0.9rem;
+  }
+  :scope[tone='warn'] {
+    border-color: #b4232c;
+  }
+</style>
+<p><slot>Nothing to say.</slot></p>
+```
+```html
+<site-note tone="warn">Rendered into the page's own DOM.</site-note>
+```
+`:scope` styles the element itself. Those rules are hoisted into `<head>` and
+lose to page CSS of equal specificity, so a page can override an element it did
+not write.
+## Shadow root, opt-in
+```html
+<!-- app/elements/user-card.html -->
+<script properties>
+  export default {
+    name: '',
+    tags: [],
+  };
+  export const shadow = true;
+</script>
+<style>
+  h3 {
+    margin: 0;
+  }
+</style>
+<h3>${name}</h3>
+<ul>
+  <li each="tag of tags">${tag}</li>
+</ul>
+<slot></slot>
+```
+Reach for a shadow root when the element has to seal its styles and DOM off from
+the page, or re-render on its own. Otherwise stay light: it is cheaper, and it
+renders the same way whether the browser asked for a whole page or one fragment.
+## Props
+`<script properties>` declares them, with defaults that set the type. An
+attribute is the value.
+```html
+<user-card name="Ada Lovelace" tags='["math", "engines"]'></user-card>
+```
+An object or an array serializes as JSON, so the browser reads the same data
+back off the element that the server had.
+`false`, `null` and `undefined` drop an attribute rather than writing
+`class="false"`. `true` writes the name bare.
+## State
+`<script state>` is data the element owns. Nothing observes it: assigning to it
+schedules the render, the way an attribute change does for a prop.
+```html
+<!-- app/elements/tally-box.html -->
+<script properties>
+  export default {
+    label: 'tally',
+  };
+</script>
+<script state>
+  export default {
+    n: 0,
+  };
+</script>
+<output>${n}</output>
+<span>${label}</span>
+<script>
+  export const prototype = {
+    bump(by = 1) {
+      this.n += by;
+    },
+  };
+  host.addEventListener('click', () => host.bump(), { signal });
+</script>
+```
+```html
+<tally-box label="clicks"></tally-box>
+<script type="module">
+  const box = document.querySelector('tally-box');
+  box.n = 10; // schedules a re-render
+  box.bump(); // 11
+  await box.updateComplete;
+</script>
+```
+## Behavior
+A plain `<script>` block is the element's own code. `host` is the element,
+`shadow` is its shadow root when it has one, `signal` is an `AbortSignal` that
+fires when the element disconnects, and `internals` is its `ElementInternals`.
+`export const prototype` puts members on the class prototype, shared by every
+instance. The rest of the block is per-element setup and runs once each.
+```js
+export const prototype = {
+  dismiss() {
+    this.hidden = true;
+    this.dispatchEvent(new CustomEvent('dismiss', { bubbles: true }));
+  },
+};
+```
+A prototype member cannot read `host`, `shadow`, `signal` or `internals`. Those
+are per-element, and reaching one from a shared member is a compile error.
+**Always pass `{ signal }` to a listener on `document`, `window` or
+`globalThis`.** One on `host` is collected with the element. One on `document`
+holds its closure forever, and every element after it adds another.
+```js
+document.addEventListener(
+  'keydown',
+  (event) => {
+    if (event.key === 'Escape') host.dismiss();
+  },
+  { signal },
+);
+```
+## Form association
+```html
+<!-- app/elements/tag-picker.html -->
+<script properties>
+  export default {
+    name: '',
+    value: '',
+  };
+  export const formAssociated = true;
+</script>
+<button type="button">${value || 'Pick tags'}</button>
+```
+```html
+<form method="post">
+  <input name="text" />
+  <tag-picker name="tags"></tag-picker>
+  <button type="submit">Add</button>
+</form>
+```
+The element is then a real form field: it submits, resets and validates with the
+rest of them.
+## Traps
+**A light element cannot `if` or `each` over a value that changes.** It does not
+own its children, so it writes into the DOM it already rendered rather than
+replacing it. That is a compile error naming `shadow`. A shadow element compiles
+the same `each` to a block with anchors and rebuilds it.
+**A shadow element in a fragment paints on connect.** A declarative shadow root
+is built when a browser parses a document, and nothing that swaps HTML parses
+one. A light element arrives whole.
+**An element with `<script state>` and no `<script>` still gets registered.**
+State is behavior. Without the definition, `el.n = 1` sets a value no node hears
+about.
+**`setHTMLUnsafe()`, never `innerHTML`,** when inserting markup that holds an
+element. `innerHTML` leaves a nested declarative shadow root as a dead
+`<template>`.

package/skills/transclude/references/fragments.md ADDED Viewed

@@ -0,0 +1,168 @@
+# Fragments and includes
+## Fragments
+A fragment is a part of a page that has its own URL. Give the element an `id`
+and a `fragment` attribute.
+```html
+<script server>
+  import { people } from '../data/people.js';
+  export default async ({ url }) => {
+    const q = new URL(url).searchParams.get('q') ?? '';
+    return { q, matches: people.filter((p) => p.name.includes(q)) };
+  };
+</script>
+<h1>People</h1>
+<input name="q" value="${q}" />
+<ul id="matches" fragment>
+  <li each="person of matches">${person.name}</li>
+</ul>
+```
+That page answers three URLs.
+| | |
+| --- | --- |
+| `GET /?q=ada` | the whole document |
+| `GET /?q=ada&fragment=matches` | the `<ul>` and nothing else |
+| `GET /?fragment=nope` | 404 |
+The `id` is the name. The page and the fragment come from one template, so the
+two always agree.
+### Asking for one
+A fragment is an ordinary URL. Anything that fetches HTML can use it.
+```js
+const res = await fetch('/?q=ada&fragment=matches');
+document.getElementById('matches').setHTMLUnsafe(await res.text());
+```
+**This framework ships nothing that swaps a fragment into a page.** htmx, Turbo,
+htmz or a short `fetch` does that. Do not look for a trigger attribute and do
+not invent one.
+htmx sends the target's id in an `HX-Target` header. Setting `fragmentHeader:
+'HX-Target'` in the config makes `?fragment=` optional. The query parameter is
+strict and an unknown name is a 404; a header naming an unknown fragment is
+ignored, because clients send it on every request.
+### Actions and fragments
+`POST /?fragment=nope` changes nothing and returns 404. The fragment is checked
+before the action runs. `ctx.fragment` tells a form submission from a fetch: the
+first wants a redirect, the second wants markup.
+### Styles for swapped-in markup
+A fragment can land on a page that never rendered the elements inside it. Set
+`watchElements: true` in the config and every page carries a small script that
+notices a new tag, loads its definition and adds its styles once. It is off by
+default.
+## Includes
+`<transclude src>` puts the same content in more than one place. It is resolved
+on the server and leaves no trace in the output.
+### Same page
+```html
+<div id="pricing" fragment>
+  <p>Two pounds.</p>
+</div>
+<aside>
+  <transclude src="#pricing"></transclude>
+</aside>
+```
+Renders as:
+```html
+<div id="pricing">
+  <p>Two pounds.</p>
+</div>
+<aside>
+  <div>
+    <p>Two pounds.</p>
+  </div>
+</aside>
+```
+The included copy drops the `id`. Two elements carrying one id is invalid, and a
+swap aimed at it would find the wrong one.
+### Another route
+```html
+<transclude src="/notes#notes">
+  <p>The notes could not be read.</p>
+</transclude>
+```
+The children are the fallback. The route is rendered in this process, not
+fetched over HTTP.
+### Another site
+Off unless a host is allowed. Default deny.
+```js
+export default {
+  proxy: {
+    allow: ['developer.mozilla.org', '*.docs.example'],
+  },
+};
+```
+```html
+<transclude src="https://developer.mozilla.org/en-US/docs/Web/HTML#reference">
+  <p>The reference could not be read just now.</p>
+</transclude>
+```
+This copies someone else's work onto your origin. Name a host only when you have
+the right to republish what it holds, and read its license: a share-alike
+license can put conditions on the page you put the fragment in. Nothing is
+attributed for you. Write the credit yourself.
+Tuning:
+```js
+proxy: {
+  allow: ['developer.mozilla.org'],
+  maxBytes: 5 * 1024 * 1024,
+  timeout: 10_000,
+  redirects: 5,
+  maxAge: 60_000,
+  sanitize: true,
+  styles: 'keep',
+}
+```
+`<base>`, `<link>` and `<style>` are stripped from foreign markup, because none
+of them stops at the fragment. `styles: 'strip'` drops `style` attributes too.
+## Traps
+**`<transclude>` has no self-closing form.** `<transclude src="#a" />` is read
+as an open tag. The children are the fallback, so the rest of the page becomes
+them, silently, and the include still works.
+**An interpolated `src` is a compile error.** `src="/docs/${slug}#intro"` cannot
+be resolved, because the set of includes has to be known before the render that
+would produce the value.
+**A page including itself is refused,** and so is a chain that comes back
+around.
+**A route include shares the host page's cookies.** That is deliberate: it makes
+the host page personal too, so one visitor's render is never served to the next.

package/skills/transclude/references/server.md ADDED Viewed

@@ -0,0 +1,155 @@
+# The server
+The server is [Hono](https://hono.dev). An app adds its own middleware in
+`app/server.js`.
+```js
+// app/server.js
+export default (app) => {
+  app.use('*', async (c, next) => {
+    await next();
+    c.res.headers.set('X-Served-By', 'transclude');
+  });
+};
+```
+It runs before anything that serves bytes, so a guard there covers prerendered
+pages and public files.
+## Cookies
+`ctx.cookies` reads and writes.
+```js
+export default async ({ cookies }) => {
+  const theme = cookies.get('theme') ?? 'light';
+  return { theme };
+};
+export const POST = async ({ cookies, request }) => {
+  const form = await request.formData();
+  cookies.set('theme', String(form.get('theme')), { maxAge: 31536000 });
+  return Response.redirect('/', 303);
+};
+```
+`cookies.signed.get` and `cookies.signed.set` need `cookieSecret` in the config.
+A signed cookie can be read by the client and not forged, which is what a
+session needs. Without a secret, `cookies.signed` throws.
+`Secure` follows the connection, so `http://localhost` works in dev and a
+proxied TLS connection still gets it.
+**Reading a cookie makes a page personal.** It is then not cached and not
+prerendered. Writing one does not.
+## Security
+CSRF is on by default. A Content-Security-Policy is not:
+```js
+export default {
+  csp: true,
+};
+```
+Each page gets a policy built from the hashes of what that page inlines. There
+is nothing to stamp and no nonce to thread through.
+Every `${…}` is escaped. `html(value)` turns that off for one value and
+sanitizes nothing, so never wrap anything a visitor typed.
+`frame-ancestors`, `report-uri`, `report-to` and `sandbox` are ignored in a
+`<meta>` tag, so they ride in a response header. A static host serves the meta
+half and not the header.
+## Types
+```sh
+npm run check
+```
+Runs TypeScript over every `.html` and `.js` route. With no annotations it
+catches a misspelled field in a template, an unknown prop on an element, and a
+prop given the wrong type. `strict: true` in the config turns on full
+strictness.
+Source is JavaScript with JSDoc. Do not convert it to TypeScript.
+## Configuration
+`transclude.config.js` at the project root. An unknown key throws.
+| Key | Default | What it does |
+| --- | --- | --- |
+| `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`. |
+| `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. |
+| `port` | `1960` | Dev and production both listen here. `PORT` wins. |
+| `lang` | `'en'` | The `lang` on `<html>`. |
+| `strict` | `false` | Full TypeScript strictness. |
+| `csrf` | `true` | `false` to turn it off, or an object for `hono/csrf`. |
+| `csp` | `false` | `true`, or `{ directives, reportOnly }`. |
+| `cookieSecret` | `null` | Signs cookies. |
+| `fragmentParam` | `'fragment'` | The query parameter that asks for a fragment. |
+| `fragmentHeader` | `null` | A request header that may name one. Adds it to `Vary`. |
+| `watchElements` | `false` | Defines and styles an element arriving in a swap. |
+| `trailingSlash` | `'never'` | `'never'` redirects. `'ignore'` serves both. |
+| `metadataBase` | — | The origin `ctx.absolute()` resolves against. |
+| `sitemap` | `false` | `{ hostname }` mounts `/sitemap.xml`. |
+| `feed` | `false` | `{ hostname, title, items }` mounts a feed. |
+| `proxy` | `false` | `{ allow: [...] }` for cross-site includes. |
+| `precache` | `false` | `true` writes `/precache.json`. |
+| `onError` | `null` | `(error, { request, url, method })` per failed request. |
+## The build
+```sh
+npm run build
+```
+Writes `dist/`. Every route with no per-request state is rendered to a file. Add
+this to a page that has to run for each request:
+```js
+export const prerender = false;
+```
+`prerender` is read off the page, never off its layouts. A layout that reads a
+cookie makes every page under it request-dependent, and nothing says so.
+## Runtimes
+The same app runs on Node, Bun, Deno and workerd. `bin/serve.js`,
+`bin/serve.bun.js` and `bin/serve.deno.js` only listen.
+**workerd refuses to compile WebAssembly at runtime.** A loader that reaches
+something built on Wasm fails there and nowhere else. A prerendered page never
+runs its loader in production, so this stays hidden until something asks for a
+fragment.
+## Testing
+The app is a function from a request to a response.
+```js
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { app } from '@transclude/core/production';
+test('the notes page lists notes', async () => {
+  const res = await app.request('http://localhost/notes');
+  assert.equal(res.status, 200);
+  assert.match(await res.text(), /<li/);
+});
+```
+`app` is a named export, and the URL has to be absolute. A relative one skips
+the origin checks a real request goes through.
+Nothing is stubbed. `node --test` does not read `.env` the way `npm start`
+does, so add `--env-file-if-exists=.env` to the test script when the config
+reads a secret.

package/src/address.js CHANGED Viewed

@@ -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]) : [];