@opentf/web 0.3.0 → 0.5.0

package/runtime/dom.js

@@ -0,0 +1,280 @@
+// Zero-VDOM DOM operations. CSR codegen emits calls into these helpers; they
+// also back runtime-driven updates (reactive text/attributes). No virtual DOM,
+// no diffing — just direct, fine-grained DOM writes wired to signals.
+
+import { effect, signal } from "../core/signals.js";
+
+// Attribute names that must be assigned as JS properties (not setAttribute) for
+// correct behavior. Mirrors the set the old runtime relied on (core/constants).
+const AS_PROPERTY = new Set([
+  "value",
+  "checked",
+  "selected",
+  "disabled",
+  "readOnly",
+  "className",
+  "htmlFor",
+  "indeterminate",
+]);
+
+// Enumerated attributes: their value is a keyword string ("true"/"false"), not a
+// boolean-attribute presence toggle. `draggable={true}` must become
+// draggable="true" — draggable="" reads back as the default (false). ARIA states
+// behave the same (aria-*="true"/"false").
+const ENUMERATED = new Set(["draggable", "spellcheck", "contenteditable"]);
+
+// CSS properties whose numeric values are unitless; every other numeric value
+// gets "px" appended (matching React/JSX conventions, so `style={{ width: 8 }}`
+// means 8px). Mirrors React's CSSProperty unitless list.
+const UNITLESS = new Set([
+  "animationIterationCount", "aspectRatio", "borderImageOutset", "borderImageSlice",
+  "borderImageWidth", "boxFlex", "boxFlexGroup", "boxOrdinalGroup", "columnCount",
+  "columns", "flex", "flexGrow", "flexShrink", "flexOrder", "gridArea", "gridRow",
+  "gridRowEnd", "gridRowStart", "gridColumn", "gridColumnEnd", "gridColumnStart",
+  "fontWeight", "lineClamp", "lineHeight", "opacity", "order", "orphans", "tabSize",
+  "widows", "zIndex", "zoom", "fillOpacity", "floodOpacity", "stopOpacity",
+  "strokeDasharray", "strokeDashoffset", "strokeMiterlimit", "strokeOpacity",
+  "strokeWidth",
+]);
+
+/**
+ * Apply a `style` object to an element. Numbers get "px" appended unless the
+ * property is unitless; CSS custom properties (`--foo`) go through setProperty;
+ * nullish values clear the property. A string value is treated as raw cssText.
+ */
+export function applyStyle(el, value) {
+  if (typeof value === "string") {
+    el.style.cssText = value;
+    return;
+  }
+  for (const key in value) {
+    const v = value[key];
+    if (key.startsWith("--")) {
+      el.style.setProperty(key, v == null ? "" : String(v));
+    } else if (v == null) {
+      el.style[key] = "";
+    } else {
+      el.style[key] = typeof v === "number" && !UNITLESS.has(key) ? `${v}px` : v;
+    }
+  }
+}
+
+/** Render a reactive value to its text form: null/undefined/false → "". */
+export function toText(value) {
+  return value == null || value === false ? "" : String(value);
+}
+
+/**
+ * clsx-style class normalization. Falsy entries are skipped; strings/numbers are
+ * kept; arrays recurse; objects contribute the keys whose values are truthy. Lets
+ * JSX write `class={["btn", active && "on", { lg: size === "lg" }]}`.
+ */
+export function clsx(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (Array.isArray(value)) {
+    const parts = [];
+    for (const v of value) {
+      const s = clsx(v);
+      if (s) parts.push(s);
+    }
+    return parts.join(" ");
+  }
+  if (typeof value === "object") {
+    const parts = [];
+    for (const k in value) if (value[k]) parts.push(k);
+    return parts.join(" ");
+  }
+  return "";
+}
+
+/**
+ * Apply a single static prop/attribute. Handles `style` objects, `on*` event
+ * handlers, property-backed attributes, and boolean/nullish removal; everything
+ * else falls back to `setAttribute`.
+ */
+export function setAttr(el, name, value) {
+  if (name === "style" && value && (typeof value === "object" || typeof value === "string")) {
+    applyStyle(el, value);
+    return;
+  }
+  if (name === "class" && value && typeof value === "object") {
+    const c = clsx(value); // array/object form → a normalized class string
+    if (c) el.setAttribute("class", c);
+    else el.removeAttribute("class");
+    return;
+  }
+  if (name.startsWith("on") && typeof value === "function") {
+    el[name.toLowerCase()] = value;
+    return;
+  }
+  if (AS_PROPERTY.has(name)) {
+    el[name] = value;
+    return;
+  }
+  if (ENUMERATED.has(name) || name.startsWith("aria-")) {
+    if (value == null) el.removeAttribute(name);
+    else el.setAttribute(name, value === true ? "true" : value === false ? "false" : String(value));
+    return;
+  }
+  if (value == null || value === false) {
+    el.removeAttribute(name);
+    return;
+  }
+  if (value === true) {
+    el.setAttribute(name, "");
+    return;
+  }
+  el.setAttribute(name, String(value));
+}
+
+/**
+ * Apply a named prop to a *child component* element. Set it as a property when the
+ * element exposes one (custom-element prop setters, `value`, `checked`, …) so rich
+ * values (objects, signals) reach the component's setter; otherwise fall back to an
+ * attribute so plain ones (`class`, `data-*`, `aria-*`) still land correctly. This
+ * mirrors how JSX libraries target custom elements. If the element is not yet
+ * upgraded `name in el` is false, so the value lands as an attribute and the
+ * component picks it up from `getAttribute` when it upgrades.
+ */
+export function setProp(el, name, value) {
+  if (name in el) el[name] = value;
+  else setAttr(el, name, value);
+}
+
+/**
+ * Apply every own enumerable key of `obj` to `el` (`<div {...obj}/>`, SPEC §5.5).
+ * `asProps` sets element properties (for components) instead of attributes (for
+ * host elements). Keys are applied in object order; the caller wraps this in an
+ * effect so a reactive source re-applies.
+ */
+export function spread(el, obj, asProps) {
+  if (!obj) return;
+  for (const k in obj) {
+    if (asProps) el[k] = obj[k];
+    else setAttr(el, k, obj[k]);
+  }
+}
+
+/**
+ * Wire a text node to a reactive expression. Primitive values update the text in
+ * place; a DOM node (or array of them) — e.g. JSX stored as a value, `{iconMap[k]}`
+ * — is inserted before the text node, which stays as a stable anchor. Returns the
+ * effect disposer so the caller (component lifecycle) can stop updates.
+ */
+export function bindText(node, fn) {
+  let inserted = [];
+  return effect(() => {
+    const value = fn();
+    for (const n of inserted) {
+      if (n.parentNode) n.parentNode.removeChild(n);
+    }
+    inserted = [];
+    if (value instanceof Node || Array.isArray(value)) {
+      node.data = "";
+      const parent = node.parentNode;
+      if (parent) {
+        for (const n of toNodes(value)) {
+          parent.insertBefore(n, node);
+          inserted.push(n);
+        }
+      }
+    } else {
+      node.data = toText(value);
+    }
+  });
+}
+
+/** Wire an element attribute/prop to a reactive expression. Returns the disposer. */
+export function bindAttr(el, name, fn) {
+  return effect(() => setAttr(el, name, fn()));
+}
+
+/** Flatten a reactive child value into DOM nodes: nodes pass through, arrays
+ * recurse, nullish/booleans render nothing, primitives become text nodes. */
+function toNodes(value) {
+  if (value == null || typeof value === "boolean") return [];
+  if (Array.isArray(value)) {
+    const out = [];
+    for (const v of value) for (const n of toNodes(v)) out.push(n);
+    return out;
+  }
+  if (value instanceof Node) return [value];
+  return [document.createTextNode(String(value))];
+}
+
+/**
+ * Wire a dynamic child region (conditional/element-valued holes like
+ * `{cond && <p/>}` or `{cond ? <a/> : <b/>}`) to a reactive expression. The
+ * region is delimited by `anchor` (a comment); on every change the previous
+ * nodes are replaced with the new ones, inserted just before the anchor.
+ * Returns the effect disposer.
+ */
+export function bindChild(anchor, fn) {
+  let current = [];
+  return effect(() => {
+    const next = toNodes(fn());
+    const host = anchor.parentNode;
+    for (const n of current) {
+      if (n.parentNode === host) host.removeChild(n);
+    }
+    if (host) for (const n of next) host.insertBefore(n, anchor);
+    current = next;
+  });
+}
+
+/**
+ * Render a keyed list (`array.map(...)`, SPEC §5.4.4) into `parent`, reconciling
+ * by key on every change to `sourceFn`'s dependencies.
+ *
+ * - `sourceFn()` returns the current array (plain data).
+ * - `renderItem(itemSignal, index)` builds a node for a new item; the item's
+ *   value is a signal so per-item bindings update fine-grained on data changes.
+ * - `keyFn(item, index)` returns a stable key; falls back to `index` when omitted.
+ *
+ * Returns the effect disposer (stops reconciliation; used by component cleanup).
+ */
+export function bindList(parent, sourceFn, renderItem, keyFn) {
+  const anchor = document.createComment("");
+  parent.appendChild(anchor);
+  let cache = new Map(); // key -> { sig, node }
+
+  return effect(() => {
+    const data = sourceFn();
+    const items = Array.isArray(data) ? data : [];
+    const next = new Map();
+    const nodes = [];
+
+    for (let index = 0; index < items.length; index++) {
+      const item = items[index];
+      const key = keyFn ? keyFn(item, index) : index;
+      let entry = cache.get(key);
+      if (entry) {
+        cache.delete(key);
+        entry.sig.value = item; // fine-grained per-item update
+      } else {
+        const sig = signal(item);
+        entry = { sig, node: renderItem(sig, index) };
+      }
+      next.set(key, entry);
+      nodes.push(entry.node);
+    }
+
+    // Remove nodes whose keys disappeared.
+    for (const entry of cache.values()) {
+      if (entry.node.parentNode) entry.node.parentNode.removeChild(entry.node);
+    }
+    cache = next;
+
+    // Place nodes in order, just before the anchor (works even after the
+    // initial fragment has been flushed into the real parent).
+    const host = anchor.parentNode || parent;
+    let ref = anchor;
+    for (let i = nodes.length - 1; i >= 0; i--) {
+      const node = nodes[i];
+      if (node.nextSibling !== ref) host.insertBefore(node, ref);
+      ref = node;
+    }
+  });
+}

package/runtime/error-boundary.js

@@ -0,0 +1,109 @@
+//! ErrorBoundary — catch render/mount errors from descendant components and show
+//! a fallback instead of letting the broken subtree (or its siblings) take the
+//! page down.
+//
+//   <ErrorBoundary fallback={(error, reset) => `Oops: ${error.message}`}>
+//     <Risky/>
+//   </ErrorBoundary>
+//
+// A descendant component's connectedCallback funnels a thrown error through
+// `handleError(this, …)` (emitted by the compiler): it reports the error (dev
+// overlay / logging) and walks up the DOM — hopping across portals, like
+// `readContext` — to the nearest `web-error-boundary`, which swaps its children
+// for the fallback. `reset()` rebuilds the original subtree (snapshotted before it
+// ran) to retry. Only synchronous render/mount errors are caught; later
+// effect/event errors still go to global reporting (as with React boundaries).
+
+import { reportError } from "../core/errors.js";
+
+/**
+ * Report a caught render/mount error and route it to the nearest enclosing
+ * `<ErrorBoundary>`. Called from a throwing component's connectedCallback catch.
+ */
+export function handleError(el, error, context = {}) {
+  reportError(error, context); // always log / surface in the dev overlay
+  let node = el;
+  while (node) {
+    const boundary = node.closest ? node.closest("web-error-boundary") : null;
+    if (boundary) {
+      boundary.catch(error, context);
+      return;
+    }
+    const portal = node.closest ? node.closest("[data-otfw-portal]") : null;
+    node = portal ? portal.__portalHost : null;
+  }
+}
+
+// A self-contained fallback (inline-styled so it reads fine without any app CSS).
+function defaultFallback(message, reset) {
+  const box = document.createElement("div");
+  box.setAttribute("role", "alert");
+  box.setAttribute("data-otfw-fallback", "");
+  box.style.cssText =
+    "display:flex;align-items:center;gap:.75rem;padding:.75rem 1rem;border:1px solid #ef4444;" +
+    "border-radius:.5rem;background:rgba(239,68,68,.1);color:#fca5a5;font:14px system-ui,sans-serif";
+  const text = document.createElement("span");
+  text.textContent = message;
+  box.appendChild(text);
+  const retry = document.createElement("button");
+  retry.textContent = "Retry";
+  retry.style.cssText =
+    "margin-left:auto;padding:.25rem .75rem;border-radius:.375rem;border:none;cursor:pointer;" +
+    "background:#ef4444;color:#fff;font:inherit";
+  retry.addEventListener("click", reset);
+  box.appendChild(retry);
+  return box;
+}
+
+export class ErrorBoundaryElement extends HTMLElement {
+  set fallback(fn) {
+    this._fallback = fn;
+  }
+  get fallback() {
+    return this._fallback;
+  }
+
+  connectedCallback() {
+    if (this._mounted) return;
+    this._mounted = true;
+    // Snapshot the children before they connect (and possibly throw) so reset()
+    // can rebuild a pristine subtree.
+    this._blueprint = Array.from(this.childNodes).map((n) => n.cloneNode(true));
+  }
+
+  // Invoked by handleError when a descendant throws during render/mount. Deferred
+  // to a microtask so we never mutate the tree mid-connectedCallback (re-entrancy).
+  catch(error) {
+    if (this._failed) return; // first error wins; ignore the cascade
+    this._failed = true;
+    queueMicrotask(() => this.#renderFallback(error));
+  }
+
+  #renderFallback(error) {
+    this.replaceChildren(); // tear the broken subtree down (runs disconnect cleanups)
+    const reset = () => this.reset();
+    let view = null;
+    try {
+      view = this._fallback ? this._fallback(error, reset) : null;
+    } catch (e) {
+      reportError(e, { phase: "fallback" });
+    }
+    const message = typeof view === "string" ? view : (error && error.message) || "Something went wrong";
+    this.appendChild(view instanceof Node ? view : defaultFallback(message, reset));
+  }
+
+  reset() {
+    if (!this._failed) return;
+    this._failed = false;
+    // Re-clone the blueprint: the rebuilt subtree connects fresh and may throw
+    // again (→ catch), or render cleanly if the cause is gone.
+    this.replaceChildren(...this._blueprint.map((n) => n.cloneNode(true)));
+  }
+}
+
+// Exported so `import { ErrorBoundary } from "@opentf/web"` resolves; the import
+// side effect registers the element (JSX uses the `web-error-boundary` tag).
+export const ErrorBoundary = ErrorBoundaryElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-error-boundary")) {
+  customElements.define("web-error-boundary", ErrorBoundaryElement);
+}

package/runtime/events.js

@@ -0,0 +1,17 @@
+//! Events — the dispatch half of the hybrid event model.
+//
+// Two channels (SPEC §5.4):
+//   • callback props  — `<Picker onSelect={fn}>` sets a property; the component
+//     calls `this.onSelect?.(detail)`. Direct parent→child, no bubbling.
+//   • event listeners — `<Picker onSelect:listen={fn}>` compiles to
+//     `addEventListener("select", fn, opts)` (with `:capture`/`:passive`/`:once`),
+//     for bubbling/interop/multiple subscribers. `emit` is the matching dispatch.
+//
+// `emit(el, "select", detail)` fires a CustomEvent that bubbles and crosses shadow
+// boundaries by default, so a `web-*` element is a first-class event source for any
+// framework consuming it. Returns false if a listener called preventDefault().
+
+export function emit(el, name, detail, options = {}) {
+  const { bubbles = true, composed = true, cancelable = false } = options;
+  return el.dispatchEvent(new CustomEvent(name, { detail, bubbles, composed, cancelable }));
+}

package/runtime/index.js

@@ -0,0 +1,16 @@
+// Built-in custom elements self-register on import. They're used in JSX as *tags*
+// (`<Portal>` → `web-portal`), so their bindings are never referenced and a plain
+// re-export would be tree-shaken away (the element never registers). Bare imports
+// force the registration side effect to be retained.
+import "./context.js";
+import "./error-boundary.js";
+import "./portal.js";
+
+export * from "./dom.js";
+export * from "./events.js";
+export * from "./mount.js";
+export * from "./lifecycle.js";
+export * from "./router.js";
+export * from "./context.js";
+export * from "./error-boundary.js";
+export * from "./portal.js";

package/runtime/lifecycle.js

@@ -0,0 +1,9 @@
+// Lifecycle hooks. `onMount`/`onCleanup` are compiler macros: the OpenTF
+// compiler collects their callbacks and wires them into a component's
+// connect/disconnect (Custom Element) or a page/layout factory's `__lifecycle`
+// record. These exports exist so the source-level `import { onMount } from
+// "@opentf/web"` resolves, and so calling them outside a compiled component (or
+// during SSR) is a safe no-op rather than a crash.
+
+export function onMount() {}
+export function onCleanup() {}

package/runtime/mount.js

@@ -0,0 +1,49 @@
+// Mounting a factory-style view (pages/layouts compile to factory functions;
+// SPEC §2.2). Components compile to Custom Elements and mount via the DOM.
+
+import { reportError } from "../core/errors.js";
+
+/**
+ * Mount a view into `target`. `view` is either a factory function returning a
+ * DOM node or an already-built node. Returns the mounted node.
+ *
+ * Page/layout factories may attach a `__lifecycle` record (`{ mounts, cleanups }`)
+ * built from `onMount`/`onCleanup`. After insertion we run the `onMount` callbacks,
+ * collecting any returned disposer into `cleanups` so a caller (e.g. the router)
+ * can tear the page down on navigation.
+ */
+export function mount(view, target) {
+  const node = typeof view === "function" ? view() : view;
+  target.appendChild(node);
+  runMount(node);
+  return node;
+}
+
+/** Run a node's `onMount` callbacks, collecting returned disposers as cleanups. */
+export function runMount(node) {
+  const lc = node && node.__lifecycle;
+  if (!lc) return;
+  for (const cb of lc.mounts) {
+    try {
+      const disposer = cb();
+      if (typeof disposer === "function") lc.cleanups.push(disposer);
+    } catch (e) {
+      reportError(e, { phase: "mount" });
+    }
+  }
+  lc.mounts = [];
+}
+
+/** Run a node's collected `onCleanup`/disposer teardown (idempotent). */
+export function runCleanup(node) {
+  const lc = node && node.__lifecycle;
+  if (!lc) return;
+  for (const cb of lc.cleanups) {
+    try {
+      cb();
+    } catch (e) {
+      console.error(e);
+    }
+  }
+  lc.cleanups = [];
+}

package/runtime/portal.js

@@ -0,0 +1,59 @@
+//! Portal — render a subtree into a different DOM location (a modal/tooltip/toast
+//! escaping an ancestor's overflow/z-index/transform).
+//
+//   <Portal to="#toast-root"> … </Portal>   // selector, element, or default body
+//
+// `<Portal>` compiles to this built-in `web-portal` element (capitalized name →
+// tag, like <ContextProvider>) — no compiler changes. At connect it moves its
+// light-DOM children to the target; on disconnect it removes them so their
+// custom-element disconnect + effect cleanups run (the part userland leaks).
+//
+// Context is preserved across the boundary: each relocated root is marked
+// `data-otfw-portal` with a `__portalHost` back-pointer to this element, and
+// `readContext` (context.js) hops across it. Note that for modals/dialogs the
+// native top layer (`<dialog>.showModal()`, the popover API) is usually a better
+// fit than a portal — Portal is the general escape hatch for everything else.
+
+function resolveTarget(to) {
+  if (to && to.nodeType === 1) return to; // an element
+  if (typeof to === "string" && to) return document.querySelector(to) || document.body;
+  return document.body;
+}
+
+export class PortalElement extends HTMLElement {
+  set to(v) {
+    this._to = v;
+  }
+  get to() {
+    return this._to;
+  }
+
+  connectedCallback() {
+    if (this._mounted) return;
+    this._mounted = true;
+    const target = resolveTarget(this._to);
+    // Snapshot children, mark each element root for the context hop, then move
+    // them — markers must be set before the move connects them at the target.
+    this._moved = Array.from(this.childNodes);
+    for (const n of this._moved) {
+      if (n.nodeType === 1) {
+        n.__portalHost = this;
+        n.setAttribute("data-otfw-portal", "");
+      }
+    }
+    for (const n of this._moved) target.appendChild(n);
+  }
+
+  disconnectedCallback() {
+    for (const n of this._moved || []) n.remove(); // triggers descendants' cleanup
+    this._moved = [];
+    this._mounted = false;
+  }
+}
+
+// Exported so `import { Portal } from "@opentf/web"` resolves; the import side
+// effect registers the element (JSX uses the `web-portal` tag).
+export const Portal = PortalElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-portal")) {
+  customElements.define("web-portal", PortalElement);
+}