@opentf/web 0.5.0 → 0.7.0

package/README.md

@@ -0,0 +1,43 @@
+# @opentf/web
+
+The native-first **OTF Web** runtime — signal-based reactivity and zero-VDOM DOM
+operations, paired with the IR-based compiler ([`@opentf/web-compiler`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/web-compiler)).
+
+You normally don't call this API by hand. You write `.jsx` components; the compiler
+lowers them to plain DOM code that imports its helpers (`signal`, `computed`,
+`bindText`, `bindList`, …) from this package. Components compile to self-registering
+`web-*` Custom Elements.
+
+## Installation
+
+```bash
+bun add @opentf/web
+```
+
+Scaffold a ready-to-run app with [`@opentf/create-web`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/create-web)
+and drive it with [`@opentf/web-cli`](https://github.com/Open-Tech-Foundation/Web-App-Framework/tree/main/packages/web-cli).
+
+## What's inside
+
+- **Reactivity** — a from-scratch `signal` / `computed` / `effect` core.
+- **DOM runtime** — fine-grained bindings (`bindText`, `bindAttr`, `bindList`,
+  `bindChild`, `setProp`, `spread`, `clsx`) the compiler targets, plus `Context`,
+  `Portal`, `ErrorBoundary`, and event dispatch (`emit`).
+- **Compiler macros** — authored in your components, resolved at compile time:
+  `$state`, `$derived`, `$ref`, `$context`, `$effect`, `$expose`, and the
+  `onMount` / `onCleanup` lifecycle hooks.
+- **`<Link>`** — client-side navigation, shipped as JSX source and compiled by your
+  app's pipeline.
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@opentf/web` | runtime + reactivity + `Link` (what compiled components import) |
+| `@opentf/web/signals` | the reactivity core on its own |
+| `@opentf/web/runtime` | DOM helpers, Context, Portal, ErrorBoundary |
+| `@opentf/web/server` | string-composed render helpers for SSG |
+
+## License
+
+MIT © [Open Tech Foundation](https://github.com/Open-Tech-Foundation)

package/components/Link.jsx

@@ -9,20 +9,34 @@
 // `class` is a declared prop, so it lands on the rendered <a> (the link), not on
 // the <web-link> host — no duplicated styling.
 
-import { navigate } from "../runtime/router.js";
+import { localizePath, navigate, shouldInterceptNav } from "../runtime/router.js";
+
+export default function Link({ href, class: className, reload, children }) {
+  // Keep the link in the active locale (no-op when i18n is off). Locale is a
+  // per-load constant under URL-prefix routing, so resolving it once here is
+  // correct — a navigation that changes the locale rebuilds this component.
+  const target = localizePath(href);
+  // `reload` (a bare attribute → "") forces a full-page navigation for this link.
+  // Absent resolves to null (getAttribute), so use loose `!= null` to treat only a
+  // present, non-false value as opting out.
+  const forceReload = reload != null && reload !== false;
 
-export default function Link({ href, class: className, children }) {
   const onclick = (e) => {
     // Let the browser handle modified clicks (new tab, etc.) and non-primary buttons.
     if (e.defaultPrevented || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0) {
       return;
     }
+    // Full-page navigation when this link opts out (`reload`) or the app runs in MPA
+    // mode (docs/HYDRATION.md §7) — leave the click to the browser.
+    if (forceReload || !shouldInterceptNav()) {
+      return;
+    }
     e.preventDefault();
-    navigate(href);
+    navigate(target);
   };
 
   return (
-    <a href={href} class={className} onclick={onclick}>
+    <a href={target} class={className} onclick={onclick}>
       {children}
     </a>
   );

package/core/reactive.js

@@ -0,0 +1,190 @@
+//! Deep reactive store — a fine-grained, signal-backed reactive object.
+//
+// `reactive(obj)` returns a deep proxy over plain data. Reading a property
+// inside an effect/computed subscribes to *just that path*; writing a property
+// notifies *only* the effects that read it. Object/array nodes are wrapped
+// lazily on access, so a 100-field store costs nothing until a field is touched.
+//
+// This is the public primitive SPEC §1.1 requires to live in `@opentf/web`:
+// apps `import { reactive }` and read values directly (no provider object), and
+// `@opentf/web-form` builds its values/errors trees on top of it instead of a
+// private proxy. It is forward-compatible with the `$signal()` compiler bridge
+// (SPEC §3.5): each node is itself reactive, so a future First-Access unwrap can
+// read `store.user.value` without changing this runtime.
+//
+// Model (mirrors the signals core, one level up):
+//   - per *key* signal  → fine-grained leaf subscription (read `a.b.c`)
+//   - per *node* "struct" signal → bumped on key add/remove so `in`, `ownKeys`,
+//     iteration and array `length` stay reactive.
+// State is mutated in place (the store owns it); reads always go through the
+// proxy, so callers never observe the raw object directly. No per-write tree
+// clone, no broadcast — the two costs the old form proxy paid on every keystroke.
+
+import { signal, untracked, batch } from "./signals.js";
+
+/** Unwrap a reactive proxy back to its underlying plain object. */
+const RAW = Symbol.for("otfw.reactive.raw");
+/** Brand a proxy so `isReactive` is a cheap, collision-free check. */
+const IS_REACTIVE = Symbol.for("otfw.reactive.is");
+
+// Per raw-object bookkeeping, kept off the data itself so the data stays clean.
+const proxyCache = new WeakMap(); // raw object  → its proxy (stable identity)
+const keySignals = new WeakMap(); // raw object  → Map<key, signal(value)>
+const structSignals = new WeakMap(); // raw object → signal(int) bumped on shape change
+
+// Array methods that mutate in place; routed through a `batch` so the many
+// internal index/length writes collapse into a single notification.
+const ARRAY_MUTATORS = new Set([
+  "push", "pop", "shift", "unshift", "splice", "reverse", "sort", "fill", "copyWithin",
+]);
+
+/** Only plain objects and arrays are wrapped; class instances, Dates, etc. pass through. */
+function isWrappable(v) {
+  if (v === null || typeof v !== "object") return false;
+  if (Array.isArray(v)) return true;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+function getKeySig(target, key) {
+  let map = keySignals.get(target);
+  if (!map) keySignals.set(target, (map = new Map()));
+  let sig = map.get(key);
+  if (!sig) map.set(key, (sig = signal(target[key])));
+  return sig;
+}
+
+function getStructSig(target) {
+  let sig = structSignals.get(target);
+  if (!sig) structSignals.set(target, (sig = signal(0)));
+  return sig;
+}
+
+/** Strip a reactive wrapper from a value before it is stored. */
+function toRaw(v) {
+  return v && typeof v === "object" && v[RAW] !== undefined ? v[RAW] : v;
+}
+
+const handler = {
+  get(target, key, receiver) {
+    if (key === RAW) return target;
+    if (key === IS_REACTIVE) return true;
+
+    if (typeof key === "symbol") {
+      // Spreading/iterating walks length+indices through the proxy, but the
+      // iterator lookup itself should subscribe to shape so a re-spread re-runs.
+      if (key === Symbol.iterator) getStructSig(target).value;
+      return Reflect.get(target, key, receiver);
+    }
+
+    // `length` is structural for arrays — push/splice change it.
+    if (key === "length" && Array.isArray(target)) {
+      getStructSig(target).value;
+      return target.length;
+    }
+
+    const value = target[key];
+
+    if (typeof value === "function") {
+      if (Array.isArray(target)) {
+        // Mutators re-enter the `set` trap via `receiver`; batch their internal
+        // writes so an effect re-runs once.
+        if (ARRAY_MUTATORS.has(key)) {
+          return (...args) => batch(() => value.apply(receiver, args));
+        }
+        // Read methods (map/filter/forEach/…) subscribe to *structure* only and
+        // run over the raw array, so they re-run when the list grows/shrinks but
+        // not when an individual element's value changes. This is what keeps a
+        // `list.map(i => <input/>)` from re-rendering (and dropping focus) on
+        // every keystroke — the element's own binding handles its value.
+        getStructSig(target).value;
+        return value.bind(target);
+      }
+      return value.bind(receiver);
+    }
+
+    getKeySig(target, key).value; // subscribe to this leaf/branch
+    return isWrappable(value) ? wrap(value) : value;
+  },
+
+  set(target, key, value) {
+    const raw = toRaw(value);
+
+    if (key === "length" && Array.isArray(target)) {
+      if (target.length !== raw) {
+        target.length = raw;
+        getStructSig(target).value++;
+      }
+      return true;
+    }
+
+    const had = Object.prototype.hasOwnProperty.call(target, key);
+    if (had && Object.is(target[key], raw)) return true;
+
+    target[key] = raw;
+    const map = keySignals.get(target);
+    const sig = map && map.get(key);
+    if (sig) sig.value = raw; // notify only if someone is listening
+    if (!had) getStructSig(target).value++; // new key → shape changed
+    return true;
+  },
+
+  deleteProperty(target, key) {
+    if (!Object.prototype.hasOwnProperty.call(target, key)) return true;
+    delete target[key];
+    const map = keySignals.get(target);
+    const sig = map && map.get(key);
+    if (sig) sig.value = undefined;
+    getStructSig(target).value++;
+    return true;
+  },
+
+  has(target, key) {
+    getStructSig(target).value;
+    return Reflect.has(target, key);
+  },
+
+  ownKeys(target) {
+    getStructSig(target).value;
+    return Reflect.ownKeys(target);
+  },
+};
+
+function wrap(target) {
+  const cached = proxyCache.get(target);
+  if (cached) return cached;
+  const proxy = new Proxy(target, handler);
+  proxyCache.set(target, proxy);
+  return proxy;
+}
+
+/**
+ * Create a deep reactive store over a plain object/array. Property reads inside
+ * an effect subscribe fine-grained; writes (`s.a.b = x`, `s.items.push(y)`)
+ * notify only dependents of the touched paths.
+ */
+export function reactive(init = {}) {
+  if (!isWrappable(init)) {
+    throw new TypeError("reactive() expects a plain object or array");
+  }
+  return wrap(init);
+}
+
+/** Whether `v` is a store created by `reactive()`. */
+export function isReactive(v) {
+  return !!(v && typeof v === "object" && v[IS_REACTIVE]);
+}
+
+/** The underlying plain object of a store (live, not a copy); identity for non-stores. */
+export function toRawValue(v) {
+  return isReactive(v) ? v[RAW] : v;
+}
+
+/**
+ * A plain, non-reactive deep copy of a store's current value — for submit
+ * payloads, validation input, or persistence. Reads are untracked, so taking a
+ * snapshot never subscribes the caller.
+ */
+export function snapshot(v) {
+  return untracked(() => structuredClone(toRawValue(v)));
+}

package/core/signals.js

@@ -94,9 +94,28 @@ export function signal(initial) {
       propagate(node);
       if (batchDepth === 0) flush();
     },
+    /** Read the current value without subscribing the active consumer. */
+    peek() {
+      return node.value;
+    },
   };
 }
 
+/**
+ * Run `fn` without subscribing the active consumer to any signals it reads.
+ * Use inside an effect/computed to read reactive state without depending on it
+ * (e.g. validation that reads many fields but should not re-run on each).
+ */
+export function untracked(fn) {
+  const prev = activeConsumer;
+  activeConsumer = null;
+  try {
+    return fn();
+  } finally {
+    activeConsumer = prev;
+  }
+}
+
 /**
  * A derived, read-only reactive value. Lazy and cached: the compute function
  * runs only when `.value` is read while stale, and recomputes only after a

package/index.js

@@ -1,6 +1,7 @@
 // Public entry for the OTF Web runtime: reactivity + DOM operations.
 // CSR-generated modules import their helpers (signal/computed/bindText/…) from here.
 export * from "./core/signals.js";
+export * from "./core/reactive.js";
 export * from "./core/errors.js";
 export * from "./runtime/index.js";
 // `Link` is shipped as JSX source and compiled by the consuming app's pipeline

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opentf/web",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "The native-first OTF Web runtime — signal-based reactivity and zero-VDOM DOM operations, paired with the IR-based compiler.",
   "type": "module",
   "exports": {

package/runtime/clipboard.js

@@ -0,0 +1,47 @@
+//! Clipboard helpers for "copy" affordances (code blocks, etc.).
+//
+// Behavior travels with the component that needs it — these are imported by the
+// `web-internal-code-block` built-in and by `@opentf/web-docs`'s `CodeBlock`, so a
+// copy button works wherever it's rendered, with no cooperation from an ancestor
+// layout. `copyText` prefers the async Clipboard API and falls back to a hidden
+// `<textarea>` + `execCommand` for non-secure contexts / older browsers.
+
+export function copyText(text) {
+  if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+    navigator.clipboard.writeText(text).catch(() => fallbackCopy(text));
+  } else {
+    fallbackCopy(text);
+  }
+}
+
+function fallbackCopy(text) {
+  try {
+    const ta = document.createElement("textarea");
+    ta.value = text;
+    ta.style.position = "fixed";
+    ta.style.opacity = "0";
+    document.body.appendChild(ta);
+    ta.select();
+    document.execCommand("copy");
+    document.body.removeChild(ta);
+  } catch {
+    /* clipboard unavailable */
+  }
+}
+
+/**
+ * Copy `text`, then give `button` the standard "Copied" feedback: add `is-copied`,
+ * swap its `.otfw-copy-label` to "Copied", and revert after 2s. Idempotent across
+ * rapid clicks (the pending revert is reset each time).
+ */
+export function copyWithFeedback(button, text) {
+  copyText(text);
+  const label = button.querySelector(".otfw-copy-label");
+  button.classList.add("is-copied");
+  if (label) label.textContent = "Copied";
+  clearTimeout(button._otfwCopyT);
+  button._otfwCopyT = setTimeout(() => {
+    button.classList.remove("is-copied");
+    if (label) label.textContent = "Copy";
+  }, 2000);
+}

package/runtime/code-block.js

@@ -0,0 +1,47 @@
+//! Code block — a built-in that renders a (build-time syntax-highlighted) code block
+//! and **owns its copy behavior**.
+//
+//   <CodeFence html={"<div class='otfw-code'>…<button class='otfw-copy'>…</button><pre>…</pre></div>"} />
+//
+// The MDX front-end emits this for fenced code (compiles to `web-internal-code-block`,
+// like `<RawHtml>` → `web-internal-raw-html`). The highlighted markup is a trusted
+// string from the compiler, so it's assigned to `innerHTML`; the difference from
+// `RawHtml` is that on connect this element wires its own `.otfw-copy` button to copy
+// the `<pre>` text. That keeps copy working wherever a code block is rendered (docs,
+// blog, anywhere) — no delegated listener in a layout. SSG renders the string inline
+// (server/builtins.js); the behavior wires when the element upgrades in the browser.
+
+import { copyWithFeedback } from "./clipboard.js";
+
+export class CodeBlockElement extends HTMLElement {
+  set html(v) {
+    this._html = v;
+    if (this.isConnected) this.render();
+  }
+  get html() {
+    return this._html;
+  }
+
+  connectedCallback() {
+    // The `html` property is set before append during a CSR build; render once.
+    if (!this._rendered) this.render();
+  }
+
+  render() {
+    this.innerHTML = this._html == null ? "" : String(this._html);
+    const button = this.querySelector(".otfw-copy");
+    const pre = this.querySelector("pre");
+    if (button && pre && !button._otfwWired) {
+      button._otfwWired = true;
+      button.addEventListener("click", () => copyWithFeedback(button, pre.innerText));
+    }
+    this._rendered = true;
+  }
+}
+
+// Exported so the bare import in runtime/index.js retains the registration side
+// effect; JSX addresses it by the `web-internal-code-block` tag (no import needed).
+export const CodeFence = CodeBlockElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-code-block")) {
+  customElements.define("web-internal-code-block", CodeBlockElement);
+}

package/runtime/context.js

@@ -32,6 +32,16 @@ export function exitHost() {
   hostStack.pop();
 }
 
+/**
+ * The component host element currently executing its body, or `null` outside a
+ * component (e.g. a form created in module scope or a test). Libraries use this
+ * as a per-instance identity to scope state to the mounting component — the
+ * compiler emits `enterHost(this)` around every component body (csr.rs).
+ */
+export function getCurrentInstance() {
+  return hostStack[hostStack.length - 1] ?? null;
+}
+
 /**
  * Create a context with a default value. The returned token is passed to
  * `<ContextProvider context={…}>` and `$context(…)`.
@@ -82,8 +92,8 @@ export class ContextProviderElement extends HTMLElement {
 }
 
 // Exported so `import { ContextProvider } from "@opentf/web"` resolves; the import
-// side effect registers the element (JSX uses the `web-context-provider` tag).
+// side effect registers the element (JSX uses the `web-internal-context-provider` tag).
 export const ContextProvider = ContextProviderElement;
-if (typeof customElements !== "undefined" && !customElements.get("web-context-provider")) {
-  customElements.define("web-context-provider", ContextProviderElement);
+if (typeof customElements !== "undefined" && !customElements.get("web-internal-context-provider")) {
+  customElements.define("web-internal-context-provider", ContextProviderElement);
 }