@opentf/web 0.4.0 → 0.5.0

package/components/Link.jsx

@@ -0,0 +1,29 @@
+// <Link href> — client-side (SPA) navigation.
+//
+// A *pure JSX component*, shipped as source and compiled by the consuming app's
+// pipeline (like a UI library ships components for the user's bundler). The
+// framework dogfoods its own JSX → Custom Element model here instead of a
+// hand-written HTMLElement class — so it gets reactive props, the children slot,
+// and a matching SSG renderer for free, with no separate runtime build step.
+//
+// `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";
+
+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;
+    }
+    e.preventDefault();
+    navigate(href);
+  };
+
+  return (
+    <a href={href} class={className} onclick={onclick}>
+      {children}
+    </a>
+  );
+}

package/core/errors.js

@@ -0,0 +1,48 @@
+//! Central error reporting for the OTF Web runtime.
+//
+// Render, effect, lifecycle, and event errors are funneled here instead of being
+// thrown into the void. Userland (and the dev overlay) subscribe via `onError`;
+// in the browser every report is also dispatched as an `otfw:error` window event
+// so a fully decoupled listener (e.g. the dev server's injected overlay) can show
+// it without importing the bundle.
+
+const handlers = new Set();
+const isBrowser = typeof window !== "undefined";
+
+/**
+ * Subscribe to runtime errors. `handler(error, context)` is called for every
+ * `reportError`. Returns a disposer that unsubscribes.
+ */
+export function onError(handler) {
+  handlers.add(handler);
+  return () => handlers.delete(handler);
+}
+
+/**
+ * Report a caught error. `context` carries where it happened
+ * (`{ phase: "render" | "effect" | "mount" | "event" | "route", … }`).
+ * Notifies subscribers, emits the `otfw:error` window event, and — if nobody is
+ * listening — logs to the console so errors are never silently swallowed.
+ */
+export function reportError(error, context = {}) {
+  for (const handler of handlers) {
+    try {
+      handler(error, context);
+    } catch {
+      // A failing handler must not mask the original error.
+    }
+  }
+  if (isBrowser) {
+    window.dispatchEvent(new CustomEvent("otfw:error", { detail: { error, context } }));
+  }
+  if (handlers.size === 0) {
+    console.error(`[otfw${context.phase ? `:${context.phase}` : ""}]`, error);
+  }
+}
+
+/** Signal that the error condition has cleared (e.g. a successful navigation). */
+export function clearError(context = {}) {
+  if (isBrowser) {
+    window.dispatchEvent(new CustomEvent("otfw:error-clear", { detail: context }));
+  }
+}

package/core/signals.js

@@ -0,0 +1,188 @@
+//! Fine-grained reactivity — our own signals core.
+//
+// This replaces the previous `@preact/signals-core` dependency to remove a
+// third-party supply-chain risk (SPEC §1.1). The public surface is the
+// industry-standard `signal` / `computed` / `effect` with a `.value` accessor;
+// more APIs (peek/untracked/subscribe) are added only when a consumer needs them.
+//
+// Model: producers (signals, computeds) hold a set of subscribers; consumers
+// (effects, computeds) track the producers they read. Reads register a
+// dependency on the active consumer; writes mark dependent computeds stale and
+// queue dependent effects, which run once per change/batch (glitch-free: an
+// effect that depends on a signal both directly and via a computed runs once).
+
+import { reportError } from "./errors.js";
+
+/** The consumer (effect or computed) currently executing, if any. */
+let activeConsumer = null;
+/** Depth of nested `batch()` calls; effects flush when this returns to 0. */
+let batchDepth = 0;
+/** Re-entrancy guard for the flush loop. */
+let flushing = false;
+/** Effects queued to run on the next flush. A Set so each runs at most once. */
+const pendingEffects = new Set();
+
+/** Register `producer` as a dependency of the consumer currently running. */
+function track(producer) {
+  if (activeConsumer) {
+    activeConsumer.sources.add(producer);
+    producer.subscribers.add(activeConsumer);
+  }
+}
+
+/** Detach a consumer from all producers it previously read. */
+function clearSources(consumer) {
+  for (const source of consumer.sources) {
+    source.subscribers.delete(consumer);
+  }
+  consumer.sources.clear();
+}
+
+/** Mark dependents stale: computeds recursively, effects into the run queue. */
+function propagate(producer) {
+  for (const sub of producer.subscribers) {
+    if (sub.kind === "computed") {
+      if (!sub.stale) {
+        sub.stale = true;
+        propagate(sub);
+      }
+    } else {
+      pendingEffects.add(sub);
+    }
+  }
+}
+
+/** Run all queued effects, including any they queue in turn. */
+function flush() {
+  if (flushing) return;
+  flushing = true;
+  try {
+    while (pendingEffects.size > 0) {
+      const batch = [...pendingEffects];
+      pendingEffects.clear();
+      for (const effectNode of batch) {
+        if (effectNode.disposed) continue;
+        // A throwing reactive update is reported but must not break the scheduler
+        // (other queued effects still run). Build-time (initial) runs propagate so
+        // the surrounding component/page catch can handle them.
+        try {
+          effectNode.run();
+        } catch (e) {
+          reportError(e, { phase: "effect" });
+        }
+      }
+    }
+  } finally {
+    flushing = false;
+  }
+}
+
+/**
+ * A writable reactive value. Reading `.value` inside an effect/computed
+ * subscribes to it; writing a changed `.value` notifies dependents.
+ */
+export function signal(initial) {
+  const node = { kind: "signal", value: initial, subscribers: new Set() };
+  return {
+    get value() {
+      track(node);
+      return node.value;
+    },
+    set value(next) {
+      if (Object.is(next, node.value)) return;
+      node.value = next;
+      propagate(node);
+      if (batchDepth === 0) flush();
+    },
+  };
+}
+
+/**
+ * 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
+ * dependency changes.
+ */
+export function computed(fn) {
+  const node = {
+    kind: "computed",
+    fn,
+    value: undefined,
+    stale: true,
+    sources: new Set(),
+    subscribers: new Set(),
+  };
+  return {
+    get value() {
+      if (node.stale) {
+        const prev = activeConsumer;
+        clearSources(node);
+        activeConsumer = node;
+        try {
+          node.value = node.fn();
+          node.stale = false;
+        } finally {
+          activeConsumer = prev;
+        }
+      }
+      track(node);
+      return node.value;
+    },
+  };
+}
+
+/**
+ * Run `fn` immediately, tracking the signals it reads, and re-run it whenever
+ * any of them change. `fn` may return a cleanup function, which runs before the
+ * next re-run and on dispose. Returns a disposer that stops the effect.
+ */
+export function effect(fn) {
+  const node = {
+    kind: "effect",
+    fn,
+    cleanup: undefined,
+    sources: new Set(),
+    disposed: false,
+    run() {
+      if (node.disposed) return;
+      runCleanup(node);
+      clearSources(node);
+      const prev = activeConsumer;
+      activeConsumer = node;
+      try {
+        const result = node.fn();
+        if (typeof result === "function") node.cleanup = result;
+      } finally {
+        activeConsumer = prev;
+      }
+    },
+  };
+  node.run();
+  return function dispose() {
+    if (node.disposed) return;
+    node.disposed = true;
+    runCleanup(node);
+    clearSources(node);
+  };
+}
+
+function runCleanup(node) {
+  if (node.cleanup) {
+    const fn = node.cleanup;
+    node.cleanup = undefined;
+    fn();
+  }
+}
+
+/**
+ * Group multiple writes so dependent effects run once after the outermost batch
+ * completes, instead of after each write.
+ */
+export function batch(fn) {
+  batchDepth++;
+  try {
+    return fn();
+  } finally {
+    batchDepth--;
+    if (batchDepth === 0) flush();
+  }
+}

package/index.js

@@ -0,0 +1,12 @@
+// 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/errors.js";
+export * from "./runtime/index.js";
+// `Link` is shipped as JSX source and compiled by the consuming app's pipeline
+// (the `.jsx` lands in the module graph and otfwc transforms it). Its compiled
+// module self-registers `web-link` (CSR `customElements.define` / SSG `defineSSG`).
+// The bare import forces that registration to be retained — `<Link>` is used as a
+// tag, so the `Link` binding alone would be tree-shaken.
+import "./components/Link.jsx";
+export { default as Link } from "./components/Link.jsx";

package/package.json

@@ -1,29 +1,38 @@
 {
   "name": "@opentf/web",
-  "version": "0.4.0",
-  "description": "The core engine of the Web App Framework, including the zero-VDOM compiler and signal-based runtime.",
-  "main": "dist/index.js",
-  "module": "dist/index.js",
+  "version": "0.5.0",
+  "description": "The native-first OTF Web runtime — signal-based reactivity and zero-VDOM DOM operations, paired with the IR-based compiler.",
   "type": "module",
-  "scripts": {
-    "build": "babel . --out-dir dist --extensions .js,.jsx --copy-files --config-file ./babel.config.cjs --ignore \"node_modules,dist,package.json,bun.lock,*.md\"",
-    "prepublishOnly": "npm run build"
-  },
   "exports": {
-    ".": "./dist/index.js",
-    "./compiler": "./dist/compiler/babel-plugin.cjs",
-    "./runtime": "./dist/runtime/index.js",
-    "./router": "./dist/router/index.js"
+    ".": "./index.js",
+    "./signals": "./core/signals.js",
+    "./runtime": "./runtime/index.js",
+    "./server": "./server/index.js"
   },
   "files": [
-    "dist"
+    "index.js",
+    "core",
+    "runtime",
+    "components",
+    "server",
+    "!**/*.test.js"
+  ],
+  "keywords": [
+    "opentf",
+    "web-components",
+    "signals",
+    "reactivity",
+    "runtime",
+    "ssg"
   ],
-  "dependencies": {
-    "@preact/signals-core": "^1.14.1",
-    "@babel/core": "^7.29.0",
-    "@babel/helper-module-imports": "^7.28.6",
-    "@babel/plugin-syntax-jsx": "^7.28.6"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Open-Tech-Foundation/Web-App-Framework.git",
+    "directory": "packages/web"
   },
+  "homepage": "https://github.com/Open-Tech-Foundation/Web-App-Framework#readme",
+  "bugs": "https://github.com/Open-Tech-Foundation/Web-App-Framework/issues",
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   }

package/runtime/context.js

@@ -0,0 +1,89 @@
+//! Context API — scoped dependency injection over the component tree.
+//
+// Unlike a module-level signal (which is global) or a prop (which must be drilled),
+// context provides a value to a *subtree* and lets a nested provider override it.
+// Because components compile to Custom Elements, the component tree *is* the DOM
+// tree, so we resolve a consumer's provider with `closest()` — no special graph.
+//
+//   const ThemeContext = createContext("dark");
+//   <ContextProvider context={ThemeContext} value={theme}> … </ContextProvider>
+//   const theme = $context(ThemeContext);   // compiler macro; use the bare name
+//
+// `value` flows through the provider's element as a signal, so a reactive `value`
+// (e.g. backed by `$state`) updates every consumer fine-grained.
+
+import { signal } from "../core/signals.js";
+
+let nextId = 0;
+
+// Stack of the elements whose component bodies are currently executing. A stack
+// (not a single slot) because filling a component's children slot connects nested
+// components synchronously inside the parent's connect — each push is balanced by
+// a pop in the generated `finally`, so the parent's host is restored after.
+const hostStack = [];
+
+/** Push the current component host (compiler-emitted, paired with `exitHost`). */
+export function enterHost(el) {
+  hostStack.push(el);
+}
+
+/** Pop the current component host (compiler-emitted, in a `finally`). */
+export function exitHost() {
+  hostStack.pop();
+}
+
+/**
+ * Create a context with a default value. The returned token is passed to
+ * `<ContextProvider context={…}>` and `$context(…)`.
+ */
+export function createContext(defaultValue) {
+  return { id: `otfw-ctx-${nextId++}`, fallback: signal(defaultValue) };
+}
+
+/**
+ * Resolve the value provided by the nearest ancestor `ContextProvider` for
+ * `context`, or the context's default if there is none. Returns a **signal**. This
+ * is what the `$context(Ctx)` compiler macro lowers to; the macro registers the
+ * binding as a signal so the bare name reads `.value` reactively.
+ */
+export function readContext(context) {
+  let el = hostStack[hostStack.length - 1];
+  const sel = `[data-otfw-ctx~="${context.id}"]`;
+  // Walk up the DOM; when the search reaches a portal boundary without finding a
+  // provider, hop to the portal's logical location (`__portalHost`) and continue,
+  // so context resolves across a <Portal> as if the content were still in place.
+  while (el) {
+    const provider = el.closest(sel);
+    if (provider) return provider._signal;
+    const boundary = el.closest("[data-otfw-portal]");
+    el = boundary ? boundary.__portalHost : null;
+  }
+  return context.fallback;
+}
+
+// `<ContextProvider context={Ctx} value={v}>`: a host element that publishes `v`
+// (as a signal) for `Ctx` to its subtree. `context`/`value` arrive as element
+// properties (the compiler sets component props reactively), so a changing `value`
+// propagates to consumers automatically.
+export class ContextProviderElement extends HTMLElement {
+  constructor() {
+    super();
+    this._signal = signal(undefined);
+  }
+  set context(ctx) {
+    if (ctx && ctx.id) this.setAttribute("data-otfw-ctx", ctx.id);
+  }
+  set value(v) {
+    this._signal.value = v;
+  }
+  get value() {
+    return this._signal.value;
+  }
+}
+
+// Exported so `import { ContextProvider } from "@opentf/web"` resolves; the import
+// side effect registers the element (JSX uses the `web-context-provider` tag).
+export const ContextProvider = ContextProviderElement;
+if (typeof customElements !== "undefined" && !customElements.get("web-context-provider")) {
+  customElements.define("web-context-provider", ContextProviderElement);
+}