@webjsdev/core 0.7.1

package/src/directives.js

@@ -0,0 +1,454 @@
+/**
+ * Built-in directives for the webjs `html` tagged template system.
+ *
+ * lit-html parity. Imports look like:
+ *
+ * ```js
+ * import { html } from '@webjsdev/core';
+ * import {
+ *   unsafeHTML, live,
+ *   keyed, guard, templateContent, ref, createRef,
+ *   cache, until, asyncAppend, asyncReplace,
+ * } from '@webjsdev/core/directives';
+ * ```
+ *
+ * `repeat()` lives in `./repeat.js` (re-exported from the package root).
+ *
+ * @module directives
+ */
+
+/* ================================================================
+ * unsafeHTML
+ * ================================================================ */
+
+/**
+ * Render a raw HTML string without escaping. The string is injected
+ * directly into the DOM as parsed HTML nodes.
+ *
+ * **When to use (AI hint):** Use ONLY for trusted HTML: CMS content,
+ * markdown-to-HTML output, or sanitized rich text. NEVER use for
+ * user-supplied input: this is an XSS vector.
+ *
+ * ```js
+ * import { html } from '@webjsdev/core';
+ * import { unsafeHTML } from '@webjsdev/core/directives';
+ *
+ * // Good: trusted markdown output
+ * html`<article>${unsafeHTML(markdownToHtml(post.body))}</article>`;
+ *
+ * // DANGEROUS: user input: use ${text} instead (auto-escaped)
+ * // html`<p>${unsafeHTML(userInput)}</p>`;  // ← XSS!
+ * ```
+ *
+ * @param {string | null | undefined} htmlString
+ *   Trusted HTML string to render without escaping.
+ * @returns {{ _$webjs: 'unsafe-html', value: string }}
+ */
+export function unsafeHTML(htmlString) {
+  return { _$webjs: 'unsafe-html', value: String(htmlString ?? '') };
+}
+
+/**
+ * Type guard: returns `true` if `x` is a marker produced by `unsafeHTML()`.
+ * @param {unknown} x
+ * @returns {x is { _$webjs: 'unsafe-html', value: string }}
+ */
+export function isUnsafeHTML(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'unsafe-html';
+}
+
+/* ================================================================
+ * live
+ * ================================================================ */
+
+/**
+ * Dirty-check a value against the **live DOM value** instead of the
+ * last rendered value. Essential for `<input>` two-way binding where
+ * the user can modify the DOM value between renders.
+ *
+ * **When to use (AI hint):** Use `live()` on `.value` or `.checked`
+ * bindings for `<input>`, `<textarea>`, `<select>` elements where the
+ * user types/selects between renders. Without `live()`, the renderer
+ * skips the update because its cached value matches: even though the
+ * DOM value has changed.
+ *
+ * ```js
+ * import { html } from '@webjsdev/core';
+ * import { live } from '@webjsdev/core/directives';
+ *
+ * html`<input .value=${live(this.query)}
+ *             @input=${e => { this.query = e.target.value; }}>`;
+ * ```
+ *
+ * On the server, `live()` is a no-op: it unwraps to the inner value.
+ *
+ * @param {unknown} value  The value to set on the element.
+ * @returns {{ _$webjs: 'live', value: unknown }}
+ */
+export function live(value) {
+  return { _$webjs: 'live', value };
+}
+
+/**
+ * Type guard: returns `true` if `x` is a marker produced by `live()`.
+ * @param {unknown} x
+ * @returns {x is { _$webjs: 'live', value: unknown }}
+ */
+export function isLive(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'live';
+}
+
+/* ================================================================
+ * keyed (lit-html parity)
+ * ================================================================ */
+
+/**
+ * Wrap a template with a key. When the key changes between renders, the
+ * renderer discards the prior DOM and creates fresh. Useful for forcing
+ * a remount when the logical identity of the rendered content changes
+ * even though the template literal structure is the same.
+ *
+ * ```js
+ * import { keyed } from '@webjsdev/core/directives';
+ *
+ * // Form fully resets (input values, focus, etc.) when userId changes.
+ * html`${keyed(this.userId, html`<edit-form .user=${this.user}></edit-form>`)}`;
+ * ```
+ *
+ * On the server, the key is ignored (one-shot render). In the browser,
+ * the renderer compares the new key to the previously-rendered key at
+ * the same position and remounts on inequality.
+ *
+ * @template T
+ * @param {unknown} key  Compared with `Object.is` against the previous render.
+ * @param {T} template   Any value the renderer accepts (typically a `TemplateResult`).
+ * @returns {{ _$webjs: 'keyed', key: unknown, value: T }}
+ */
+export function keyed(key, template) {
+  return { _$webjs: 'keyed', key, value: template };
+}
+
+/** @param {unknown} x */
+export function isKeyed(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'keyed';
+}
+
+/* ================================================================
+ * guard (lit-html parity)
+ * ================================================================ */
+
+/**
+ * Memoize a sub-template by its dependencies. If the deps array hasn't
+ * changed shallowly between renders, the renderer skips re-evaluating
+ * the value-producing function.
+ *
+ * ```js
+ * import { guard } from '@webjsdev/core/directives';
+ *
+ * render() {
+ *   return html`
+ *     <header>${guard([this.title], () => html`<h1>${this.title}</h1>`)}</header>
+ *     <main>${this.body}</main>
+ *   `;
+ * }
+ * ```
+ *
+ * On the server, `fn()` is always invoked (one-shot render, no cache).
+ * In the browser, the renderer maintains a per-part cache keyed by the
+ * shallow-compared deps array.
+ *
+ * @template T
+ * @param {readonly unknown[]} deps  Shallow-compared between renders
+ * @param {() => T} fn               Value-producing function
+ * @returns {{ _$webjs: 'guard', deps: readonly unknown[], fn: () => T }}
+ */
+export function guard(deps, fn) {
+  return { _$webjs: 'guard', deps, fn };
+}
+
+/** @param {unknown} x */
+export function isGuard(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'guard';
+}
+
+/* ================================================================
+ * templateContent (lit-html parity)
+ * ================================================================ */
+
+/**
+ * Render the content of a `<template>` element. The template's content
+ * is cloned on the client; on the server, its `innerHTML` is emitted.
+ *
+ * ```js
+ * import { templateContent } from '@webjsdev/core/directives';
+ *
+ * const tpl = document.querySelector('#my-tpl');
+ * html`<div>${templateContent(tpl)}</div>`;
+ * ```
+ *
+ * The HTML inside the template element is trusted: it is NOT escaped.
+ * Do not pass templates whose content was assembled from user input.
+ *
+ * @param {HTMLTemplateElement | { innerHTML?: string, content?: DocumentFragment }} template
+ * @returns {{ _$webjs: 'template-content', template: any }}
+ */
+export function templateContent(template) {
+  return { _$webjs: 'template-content', template };
+}
+
+/** @param {unknown} x */
+export function isTemplateContent(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'template-content';
+}
+
+/* ================================================================
+ * ref (lit-html parity)
+ * ================================================================ */
+
+/**
+ * Bind a Ref object or callback to the element produced at this position.
+ *
+ * ```js
+ * import { createRef, ref } from '@webjsdev/core/directives';
+ *
+ * class MyForm extends WebComponent {
+ *   _input = createRef();
+ *   render() {
+ *     return html`<input ${ref(this._input)}>`;
+ *   }
+ *   firstUpdated() {
+ *     this._input.value?.focus();
+ *   }
+ * }
+ * ```
+ *
+ * Pass a callback instead of a Ref object to receive the element directly:
+ *
+ * ```js
+ * html`<input ${ref((el) => this._captureEl(el))}>`;
+ * ```
+ *
+ * On the server, `ref()` is a no-op: no DOM exists yet. The reference is
+ * populated after the first client-side render. The callback receives
+ * `undefined` when the element is removed.
+ *
+ * @param {{ value: unknown } | ((el: Element | undefined) => void)} refOrCallback
+ * @returns {{ _$webjs: 'ref', target: any }}
+ */
+export function ref(refOrCallback) {
+  return { _$webjs: 'ref', target: refOrCallback };
+}
+
+/** @param {unknown} x */
+export function isRef(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'ref';
+}
+
+/**
+ * Create a Ref object suitable for `ref()`. The element is assigned to
+ * `ref.value` after the first render commit.
+ *
+ * @template {Element} T
+ * @returns {{ value: T | undefined }}
+ */
+export function createRef() {
+  return { value: undefined };
+}
+
+/* ================================================================
+ * cache (lit-html parity)
+ * ================================================================ */
+
+/**
+ * Cache prior template instances by their `strings` array so that
+ * toggling between sub-templates preserves their detached DOM (input
+ * state, scroll position, focus). When the inner value is a template
+ * whose `strings` were cached on a previous render, the renderer
+ * re-attaches the stashed nodes and reconciles values against the new
+ * template instead of creating fresh DOM.
+ *
+ * ```js
+ * import { cache } from '@webjsdev/core/directives';
+ *
+ * render() {
+ *   return html`
+ *     <button @click=${() => this.tab = 'a'}>A</button>
+ *     <button @click=${() => this.tab = 'b'}>B</button>
+ *     ${cache(this.tab === 'a' ? html`<panel-a></panel-a>` : html`<panel-b></panel-b>`)}
+ *   `;
+ * }
+ * ```
+ *
+ * On the server, `cache` is a pass-through (one-shot render, no DOM to
+ * cache).
+ *
+ * @template T
+ * @param {T} value
+ * @returns {{ _$webjs: 'cache', value: T }}
+ */
+export function cache(value) {
+  return { _$webjs: 'cache', value };
+}
+
+/** @param {unknown} x */
+export function isCache(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'cache';
+}
+
+/* ================================================================
+ * until (lit-html parity)
+ * ================================================================ */
+
+/**
+ * Render the first synchronous value from a list of candidates. Any
+ * Promises in the list are unwrapped on the server (the first to
+ * resolve wins).
+ *
+ * ```js
+ * import { until } from '@webjsdev/core/directives';
+ *
+ * html`<div>${until(this.dataPromise, html`<p>Loading…</p>`)}</div>`;
+ * ```
+ *
+ * Priority is left-to-right: `args[0]` is highest priority. The
+ * highest-priority synchronous candidate (if any) renders immediately.
+ * Higher-priority Promises that later resolve replace the rendered
+ * value; lower-priority Promises are ignored once a higher-priority
+ * candidate is in place. When the marker is torn down (e.g. the
+ * parent re-renders with a different value), in-flight tracking is
+ * cleared so late Promise resolutions cannot overwrite newer DOM.
+ *
+ * SSR awaits `Promise.race` when all candidates are Promises;
+ * otherwise SSR renders the highest-priority synchronous candidate.
+ * For component-scoped async data with full pending/error states,
+ * prefer the `Task` controller (`@webjsdev/core/task`).
+ *
+ * @param  {...unknown} args
+ * @returns {{ _$webjs: 'until', args: unknown[] }}
+ */
+export function until(...args) {
+  return { _$webjs: 'until', args };
+}
+
+/** @param {unknown} x */
+export function isUntil(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'until';
+}
+
+/* ================================================================
+ * asyncAppend / asyncReplace (lit-html parity)
+ * ================================================================ */
+
+/**
+ * Render values from an `AsyncIterable` as they arrive, appending each
+ * mapped result before the marker. Iteration runs in the background;
+ * tearing down the marker (via a re-render that replaces the directive)
+ * aborts the loop.
+ *
+ * ```js
+ * import { asyncAppend } from '@webjsdev/core/directives';
+ *
+ * async function* logTail() {
+ *   for await (const line of stream) yield line;
+ * }
+ *
+ * html`<ul>${asyncAppend(logTail(), (line, i) => html`<li>${i}: ${line}</li>`)}</ul>`;
+ * ```
+ *
+ * SSR renders empty (no iteration on a one-shot server render). For
+ * page-level streaming, prefer `Suspense({ fallback, children })`.
+ *
+ * @template T
+ * @param {AsyncIterable<T>} iterable
+ * @param {(value: T, index: number) => unknown} [mapper]
+ * @returns {{ _$webjs: 'async-append', iterable: AsyncIterable<T>, mapper?: (v: T, i: number) => unknown }}
+ */
+export function asyncAppend(iterable, mapper) {
+  return { _$webjs: 'async-append', iterable, mapper };
+}
+
+/** @param {unknown} x */
+export function isAsyncAppend(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'async-append';
+}
+
+/**
+ * Render values from an `AsyncIterable`, replacing the previous output
+ * each time a new value arrives. The latest yielded value is the only
+ * one that remains in the DOM.
+ *
+ * ```js
+ * import { asyncReplace } from '@webjsdev/core/directives';
+ *
+ * async function* ticker() {
+ *   for (let i = 0; ; i++) {
+ *     yield new Date().toLocaleTimeString();
+ *     await new Promise(r => setTimeout(r, 1000));
+ *   }
+ * }
+ *
+ * html`<time>${asyncReplace(ticker())}</time>`;
+ * ```
+ *
+ * SSR renders empty. Iteration aborts on teardown.
+ *
+ * @template T
+ * @param {AsyncIterable<T>} iterable
+ * @param {(value: T, index: number) => unknown} [mapper]
+ * @returns {{ _$webjs: 'async-replace', iterable: AsyncIterable<T>, mapper?: (v: T, i: number) => unknown }}
+ */
+export function asyncReplace(iterable, mapper) {
+  return { _$webjs: 'async-replace', iterable, mapper };
+}
+
+/** @param {unknown} x */
+export function isAsyncReplace(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'async-replace';
+}
+
+/* ================================================================
+ * watch (signal binding)
+ * ================================================================ */
+
+/**
+ * Fine-grained reactive binding for a signal. Reads the signal at
+ * render time and subscribes the rendered template hole to subsequent
+ * changes. When the signal's value changes, only THIS hole updates,
+ * the surrounding component does not re-render.
+ *
+ * ```js
+ * import { html } from '@webjsdev/core';
+ * import { signal } from '@webjsdev/core';
+ * import { watch } from '@webjsdev/core/directives';
+ *
+ * const count = signal(0);
+ *
+ * class Counter extends WebComponent {
+ *   render() {
+ *     return html`
+ *       <p>Count: ${watch(count)}</p>
+ *       <button @click=${() => count.set(count.get() + 1)}>+</button>
+ *     `;
+ *   }
+ * }
+ * ```
+ *
+ * Without `watch()`, a plain `${count.get()}` works too (the host
+ * component subscribes automatically through its built-in
+ * SignalWatcher), but the whole component re-renders on each change.
+ * Use `watch()` when the surrounding template is expensive to re-run
+ * or when you want signal changes to bypass `shouldUpdate` / `willUpdate`.
+ *
+ * On SSR, `watch()` reads the signal once and inlines the value.
+ *
+ * @param {{ get: () => unknown, __isSignal: true }} sig
+ * @returns {{ _$webjs: 'watch', signal: { get: () => unknown, __isSignal: true } }}
+ */
+export function watch(sig) {
+  return { _$webjs: 'watch', signal: sig };
+}
+
+/** @param {unknown} x */
+export function isWatch(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'watch';
+}

package/src/escape.js

@@ -0,0 +1,15 @@
+/** @param {string} s */
+export function escapeText(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+/** @param {string} s */
+export function escapeAttr(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;');
+}

package/src/expose.js

@@ -0,0 +1,90 @@
+/**
+ * Expose a server action as a first-class HTTP endpoint in addition to its
+ * internal RPC URL.
+ *
+ * ```js
+ * // actions/posts.server.js
+ * 'use server';
+ * import { expose } from '@webjsdev/core';
+ *
+ * export const createPost = expose('POST /api/posts', async ({ title, body }) => {
+ *   // same function body you'd write without expose()
+ * });
+ * ```
+ *
+ * The action is reachable two ways, both backed by the exact same code:
+ *   - from a client component:   `import { createPost } from '.../posts.server.js'`
+ *   - from curl / another service: `POST /api/posts` with a JSON body
+ *
+ * Adapter rules when invoked over HTTP:
+ *   - URL path params ({`:slug`}) and query string are merged into a single
+ *     object argument.
+ *   - For methods with a body (POST/PUT/PATCH/DELETE), the parsed JSON body
+ *     is merged on top of params/query. The function receives ONE argument:
+ *     the merged object.
+ *   - If `opts.validate` is provided, it runs BEFORE the function and can
+ *     transform / reject the input. Throw to fail (→ 400 response). Return
+ *     value replaces the input. Works cleanly with zod, valibot, or any
+ *     parser that throws: `expose('...', fn, { validate: Schema.parse })`.
+ *   - Return value becomes a JSON `Response`; throw or return a `Response`
+ *     directly for full control.
+ *
+ *
+ * `cors` toggles browser CORS support for cross-origin callers:
+ *   - `true`             - allow any origin (`*`), reflects requested headers
+ *   - string             - allow that single origin (sets `Access-Control-Allow-Credentials: true`)
+ *   - string[]           - allow-list; non-matching origins are not granted
+ *   - { origin, credentials, maxAge, headers }: full control
+ *
+ * When CORS is enabled, an `OPTIONS` preflight at the same path is auto-served
+ * with `Access-Control-Allow-Methods: <route's method>, OPTIONS`.
+ *
+ * @param {string} pattern e.g. `"POST /api/posts"` or `"GET /api/posts/:slug"`
+ * @param {Function} fn the async implementation
+ * @param {{
+ *   validate?: (input: any) => any,
+ *   cors?: boolean | string | string[] | { origin: string | string[], credentials?: boolean, maxAge?: number, headers?: string[] }
+ * }} [opts]
+ * @returns {Function} same function, tagged with HTTP metadata
+ */
+export function expose(pattern, fn, opts) {
+  const match = /^\s*([A-Z]+)\s+(\/\S*)\s*$/.exec(pattern);
+  if (!match) {
+    throw new Error(
+      `expose(): bad pattern ${JSON.stringify(pattern)}: expected "METHOD /path"`
+    );
+  }
+  const [, method, path] = match;
+  /** @type any */ (fn).__webjsHttp = {
+    method,
+    path,
+    validate: opts && typeof opts.validate === 'function' ? opts.validate : null,
+    cors: opts && 'cors' in opts ? normaliseCors(opts.cors) : null,
+  };
+  return fn;
+}
+
+/** @param {any} c */
+function normaliseCors(c) {
+  if (!c) return null;
+  if (c === true) {
+    return { origin: '*', credentials: false, maxAge: 86400, headers: null };
+  }
+  if (typeof c === 'string') {
+    return { origin: c, credentials: true, maxAge: 86400, headers: null };
+  }
+  if (Array.isArray(c)) {
+    return { origin: c, credentials: true, maxAge: 86400, headers: null };
+  }
+  return {
+    origin: c.origin,
+    credentials: !!c.credentials,
+    maxAge: typeof c.maxAge === 'number' ? c.maxAge : 86400,
+    headers: Array.isArray(c.headers) ? c.headers : null,
+  };
+}
+
+/** @param {unknown} fn */
+export function getExposed(fn) {
+  return fn && typeof fn === 'function' ? /** @type any */ (fn).__webjsHttp || null : null;
+}

package/src/html.js

@@ -0,0 +1,30 @@
+/**
+ * Tagged template literal producing a {@link TemplateResult}.
+ *
+ * A TemplateResult is an isomorphic description of HTML: the static string
+ * pieces plus the dynamic values. Server and client renderers both consume it.
+ *
+ * @typedef {{ _$webjs: 'template', strings: TemplateStringsArray | string[], values: unknown[] }} TemplateResult
+ *
+ * @param {TemplateStringsArray | string[]} strings
+ * @param {...unknown} values
+ * @returns {TemplateResult}
+ */
+export function html(strings, ...values) {
+  return { _$webjs: 'template', strings, values };
+}
+
+/**
+ * Identity check for TemplateResult.
+ * @param {unknown} x
+ * @returns {x is TemplateResult}
+ */
+export function isTemplate(x) {
+  return !!x && typeof x === 'object' && /** @type {any} */ (x)._$webjs === 'template';
+}
+
+/**
+ * Marker used in the DOM to find hydration points.
+ * Same marker emitted by server and client so hydration can align.
+ */
+export const MARKER = 'w$';

package/src/lazy-loader.js

@@ -0,0 +1,107 @@
+/**
+ * Lazy component loader using IntersectionObserver.
+ *
+ * Components with `static lazy = true` are NOT loaded eagerly via
+ * `<link rel="modulepreload">`. Instead, their `<script>` import is
+ * deferred and the module is only fetched when the element enters the
+ * viewport (or is within a generous margin of it).
+ *
+ * Usage (automatic: the SSR pipeline sets this up):
+ *
+ *   <script type="module">
+ *     import { observeLazy } from '@webjsdev/core/lazy-loader';
+ *     observeLazy({
+ *       'my-lazy-widget': '/components/my-lazy-widget.ts',
+ *     });
+ *   </script>
+ *
+ * Or manually: mark a component and the framework handles the rest.
+ *
+ *   class MyWidget extends WebComponent {
+ *     static lazy = true;
+ *     // ...
+ *   }
+ *   MyWidget.register('my-lazy-widget');
+ */
+
+/** @type {Map<string, string>} tag → module URL */
+const pending = new Map();
+
+/** @type {IntersectionObserver | null} */
+let observer = null;
+
+/** @type {Map<string, Promise<unknown>>} in-flight module loads, keyed by URL */
+const inflight = new Map();
+
+/**
+ * Load a module, deduplicating concurrent requests for the same URL.
+ * @param {string} url
+ * @returns {Promise<unknown>}
+ */
+function loadModule(url) {
+  let p = inflight.get(url);
+  if (p) return p;
+  p = import(url).finally(() => inflight.delete(url));
+  inflight.set(url, p);
+  return p;
+}
+
+/**
+ * Register tag → URL pairs for lazy loading. When any element matching
+ * a registered tag enters the viewport, its module is fetched via
+ * dynamic import(). The custom element class registers itself on load,
+ * upgrading the element.
+ *
+ * @param {Record<string, string>} entries  { tagName: moduleUrl }
+ */
+export function observeLazy(entries) {
+  for (const [tag, url] of Object.entries(entries)) {
+    pending.set(tag.toLowerCase(), url);
+  }
+
+  if (typeof IntersectionObserver === 'undefined') {
+    // No IO support: load everything immediately (SSR-only / old browser).
+    for (const url of pending.values()) loadModule(url);
+    pending.clear();
+    return;
+  }
+
+  if (!observer) {
+    observer = new IntersectionObserver(onIntersect, {
+      // Load when within 200px of the viewport: gives the module time
+      // to fetch before the element is fully visible.
+      rootMargin: '200px',
+    });
+  }
+
+  // Observe all matching elements currently in the DOM.
+  scan();
+
+  // Also watch for dynamically added elements via MutationObserver.
+  if (typeof MutationObserver !== 'undefined') {
+    const mo = new MutationObserver(() => scan());
+    mo.observe(document.body, { childList: true, subtree: true });
+  }
+}
+
+function scan() {
+  if (!observer || !pending.size) return;
+  for (const tag of pending.keys()) {
+    for (const el of document.querySelectorAll(tag)) {
+      observer.observe(el);
+    }
+  }
+}
+
+/** @param {IntersectionObserverEntry[]} entries */
+function onIntersect(entries) {
+  for (const entry of entries) {
+    if (!entry.isIntersecting) continue;
+    const tag = entry.target.tagName.toLowerCase();
+    const url = pending.get(tag);
+    if (!url) continue;
+    loadModule(url);
+    pending.delete(tag);
+    observer?.unobserve(entry.target);
+  }
+}