@opentf/web 0.4.0 → 0.6.0

package/runtime/hydrate.js

@@ -0,0 +1,121 @@
+// Hydration primitives (Phase 2 — see docs/HYDRATION.md). The client *adopts* the
+// server-rendered DOM instead of rebuilding it: it claims existing nodes and wires
+// reactivity (bindText/bindAttr/events from dom.js) onto them. There is no separate
+// "hydrate" binding logic — those helpers already operate on existing nodes; the only
+// new work is *node acquisition*, which is what this module provides.
+//
+// Acquisition is a **cursor walk** (the decided approach, like Solid): the Hydrate
+// codegen emits claim calls in the exact order the SSG backend emitted nodes, so a
+// cursor over a parent's childNodes lines up 1:1 with the template. The server output
+// carries no inter-element whitespace (ssg.rs concatenates with no padding), so the
+// re-parsed DOM has text nodes only where the template does — the walk stays aligned.
+//
+// Markers (only where structure is variable): a dynamic text hole is delimited by
+// `<!--$-->value<!--/-->` so it is findable even when the value is empty or adjacent
+// to static text (which the HTML parser would otherwise merge into one text node).
+// Static structure carries no markers and is claimed by position.
+
+/** Comment markers bounding a dynamic text hole in server HTML. */
+export const HOLE_START = "$";
+export const HOLE_END = "/";
+
+const ELEMENT = 1;
+const TEXT = 3;
+const COMMENT = 8;
+
+/** Thrown when the server DOM doesn't match the template at a claim site. The
+ * component boundary catches this and recovers by rebuilding via CSR (never silent;
+ * see docs/HYDRATION.md §3.5). */
+export class HydrationMismatch extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "HydrationMismatch";
+  }
+}
+
+// ── the hydration flag ────────────────────────────────────────────────────────
+// True during the initial hydration pass. A component's connectedCallback reads it
+// to decide whether to *adopt* its server children or *build* a fresh subtree — the
+// custom-element-as-island coordination (docs/HYDRATION.md §3.4).
+let _hydrating = false;
+
+/** Is the client mid-hydration right now? */
+export function isHydrating() {
+  return _hydrating;
+}
+
+/** Run `fn` with the hydration flag set, restoring the prior value (nesting-safe). */
+export function runHydration(fn) {
+  const prev = _hydrating;
+  _hydrating = true;
+  try {
+    return fn();
+  } finally {
+    _hydrating = prev;
+  }
+}
+
+// ── the cursor ────────────────────────────────────────────────────────────────
+
+/** A walker over `parent`'s children, positioned at the next node to claim. */
+export function cursor(parent) {
+  return { node: parent.firstChild };
+}
+
+/** Advance past the next node without claiming it (a static text node between
+ * dynamic siblings), returning it. */
+export function skipNode(cur) {
+  const n = cur.node;
+  cur.node = n ? n.nextSibling : null;
+  return n;
+}
+
+/**
+ * Claim the next node as an element, optionally asserting its tag, and advance the
+ * cursor past it. Returns the element so the caller can claim its children with a
+ * fresh `cursor(el)`. A wrong/absent node throws {@link HydrationMismatch}.
+ */
+export function claimElement(cur, tag) {
+  const el = cur.node;
+  if (!el || el.nodeType !== ELEMENT || (tag && el.tagName.toLowerCase() !== tag.toLowerCase())) {
+    throw new HydrationMismatch(`expected <${tag ?? "element"}>, found ${describe(el)}`);
+  }
+  cur.node = el.nextSibling;
+  return el;
+}
+
+/**
+ * Claim a dynamic text hole delimited by `<!--$-->…<!--/-->`, returning the text node
+ * to bind onto (created empty when the server rendered no value), and advance the
+ * cursor past the closing marker. Wire reactivity with `bindText(node, fn)` from
+ * dom.js — the binding logic is shared with CSR; only the node is adopted, not built.
+ */
+export function claimText(cur) {
+  const start = cur.node;
+  if (!start || start.nodeType !== COMMENT || start.data !== HOLE_START) {
+    throw new HydrationMismatch(`expected a text-hole marker, found ${describe(start)}`);
+  }
+  let node = start.nextSibling;
+  let textNode = null;
+  while (node && !(node.nodeType === COMMENT && node.data === HOLE_END)) {
+    if (node.nodeType === TEXT && !textNode) textNode = node;
+    node = node.nextSibling;
+  }
+  const end = node; // the `<!--/-->` marker (or null if the markup is malformed)
+  if (!textNode) {
+    // Empty hole (`<!--$--><!--/-->`): synthesize the anchor bindText will write into.
+    textNode = document.createTextNode("");
+    (start.parentNode || document).insertBefore(textNode, end);
+  }
+  cur.node = end ? end.nextSibling : null;
+  return textNode;
+}
+
+/** A short human description of a node for mismatch messages. */
+function describe(node) {
+  if (!node) return "nothing";
+  if (node.nodeType === ELEMENT) return `<${node.tagName.toLowerCase()}>`;
+  if (node.nodeType === TEXT) return `text "${(node.data || "").slice(0, 20)}"`;
+  if (node.nodeType === COMMENT) return `comment <!--${node.data}-->`;
+  return `node(${node.nodeType})`;
+}

package/runtime/index.js

@@ -0,0 +1,22 @@
+// Built-in custom elements self-register on import. They're used in JSX as *tags*
+// (`<Portal>` → `web-internal-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";
+import "./raw-html.js";
+import "./code-block.js";
+
+export * from "./dom.js";
+export * from "./events.js";
+export * from "./mount.js";
+export * from "./hydrate.js";
+export * from "./lifecycle.js";
+export * from "./router.js";
+export * from "./context.js";
+export * from "./error-boundary.js";
+export * from "./portal.js";
+export * from "./raw-html.js";
+export * from "./code-block.js";
+export * from "./clipboard.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-internal-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-internal-portal` tag).
+export const Portal = PortalElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-portal")) {
+  customElements.define("web-internal-portal", PortalElement);
+}

package/runtime/raw-html.js

@@ -0,0 +1,33 @@
+//! RawHtml — render a trusted HTML string as light-DOM content.
+//
+//   <RawHtml html={"<pre>…</pre>"} />   // compiles to the built-in `web-internal-raw-html`
+//
+// Used by the MDX front-end for build-time syntax-highlighted code blocks: the
+// highlighted markup is static (no reactivity), so the element just assigns its
+// `html` property to `innerHTML`. The string is treated as trusted — it comes from
+// the compiler, not user input. SSG renders the string inline (server/builtins.js).
+
+export class RawHtmlElement extends HTMLElement {
+  set html(v) {
+    this._html = v;
+    if (this.isConnected) this.innerHTML = v == null ? "" : String(v);
+  }
+  get html() {
+    return this._html;
+  }
+
+  connectedCallback() {
+    // Apply once on connect (the property is set before append during CSR build).
+    if (this._html != null && !this._applied) {
+      this.innerHTML = String(this._html);
+      this._applied = true;
+    }
+  }
+}
+
+// Exported so `import { RawHtml } from "@opentf/web"` resolves; the import side
+// effect registers the element (JSX uses the `web-internal-raw-html` tag).
+export const RawHtml = RawHtmlElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-raw-html")) {
+  customElements.define("web-internal-raw-html", RawHtmlElement);
+}