@opentf/web 0.4.0 → 0.5.0

package/runtime/router.js

@@ -0,0 +1,246 @@
+// File-based client router for the OTF Web runtime.
+//
+// Pages/layouts compile to factory functions (default export) that return a DOM
+// node; `mountApp` registers a route table discovered from the filesystem (by the
+// dev server / build) and renders the matching page into the app root, swapping
+// it on navigation. Route state (pathname/params/query) is exposed reactively via
+// the `router` facade so views can read `router.pathname` etc. inside bindings.
+//
+// Dynamic segments use the `[param]` / `[...rest]` folder convention (SPEC §6).
+//
+// NOTE: passing route params to a page via its `props` argument
+// (`function Page(props) { props.params.id }`) and layout `props.children`
+// composition both require signal-free page props, which the compiler does not
+// emit yet — for now pages read params via the reactive `router.params`.
+
+import { clearError, reportError } from "../core/errors.js";
+import { signal } from "../core/signals.js";
+import { runCleanup, runMount } from "./mount.js";
+
+const isBrowser = typeof window !== "undefined";
+
+const state = {
+  pathname: signal(isBrowser ? window.location.pathname : "/"),
+  searchParams: signal(new URLSearchParams(isBrowser ? window.location.search : "")),
+  params: signal({}),
+};
+
+export const routes = { pages: {}, layouts: {}, notFound: null };
+let guard = null;
+let rootEl = null;
+let currentNodes = [];
+
+/** Reactive router facade — getters read signal values (tracked in effects). */
+export const router = {
+  get pathname() {
+    return state.pathname.value;
+  },
+  get searchParams() {
+    return state.searchParams.value;
+  },
+  get query() {
+    return Object.fromEntries(state.searchParams.value);
+  },
+  get params() {
+    return state.params.value;
+  },
+  push: (path) => navigate(path),
+  replace: (path) => navigate(path, true),
+};
+
+/** Derive the route ("/counter", "/") from a `.../app/<route>/page.jsx` path. */
+function routeFromPath(filePath) {
+  const r = filePath
+    .replace(/^.*\/app/, "")
+    .replace(/\/(page|layout|404)\.(jsx|tsx)$/, "");
+  return r === "" ? "/" : r;
+}
+
+/**
+ * Register routes from a `{ path: entry }` map. Each `entry` is either a module
+ * namespace (eager) or a `() => import(...)` loader (lazy, code-split) — both
+ * resolve to a default-export factory at navigation time. `layout.jsx` files
+ * register as layouts (wrapping nested pages), `404.jsx` as the fallback.
+ */
+export function registerRoutes(modules) {
+  for (const file in modules) {
+    const entry = modules[file];
+    if (/\/404\.(jsx|tsx)$/.test(file)) routes.notFound = entry;
+    else if (/\/layout\.(jsx|tsx)$/.test(file)) routes.layouts[routeFromPath(file)] = entry;
+    else routes.pages[routeFromPath(file)] = entry;
+  }
+}
+
+/** Layout entries that wrap `route`, outermost (root) first. */
+export function layoutChain(route) {
+  const chain = [];
+  if (!route) return chain;
+  let p = route;
+  while (true) {
+    if (routes.layouts[p]) chain.unshift(routes.layouts[p]);
+    if (p === "/") break;
+    p = p.slice(0, p.lastIndexOf("/")) || "/";
+  }
+  return chain;
+}
+
+/** Resolve a route entry (module namespace or lazy loader) to its factory. */
+export async function resolveFactory(entry) {
+  const mod = typeof entry === "function" ? await entry() : entry;
+  return mod && mod.default ? mod.default : mod;
+}
+
+/**
+ * Build the DOM node for a matched route: the page factory wrapped by its layout
+ * chain (most-specific inward, root outermost). Returns the outermost `node` plus
+ * the ordered `nodes` list (page → … → root) so callers can run lifecycle on each.
+ * Shared by the client router (`navigate`) and server render (`renderToString`).
+ */
+export async function buildRouteNode(match, query = {}) {
+  const props = { params: match.params, query };
+  const pageFactory = await resolveFactory(match.entry);
+  let node = pageFactory(props);
+  const nodes = [node];
+  const chain = layoutChain(match.route);
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const layout = await resolveFactory(chain[i]);
+    node = layout({ ...props, children: node });
+    nodes.push(node);
+  }
+  return { node, nodes };
+}
+
+/**
+ * Set the reactive route state directly (no history/render). Used by server render
+ * so a page reading `router.pathname`/`params`/`query` resolves to the route being
+ * pre-rendered. The client uses `navigate` instead.
+ */
+export function setRouteState({ pathname = "/", search = "", params = {} } = {}) {
+  state.pathname.value = pathname;
+  state.searchParams.value = new URLSearchParams(search);
+  state.params.value = params;
+}
+
+/** Match `pathname` against the registered routes, resolving `[param]` segments. */
+export function matchRoute(pathname) {
+  for (const route in routes.pages) {
+    const pattern = route
+      .replace(/\[\.\.\.([^\]]+)\]/g, "(?<$1>.+)")
+      .replace(/\[([^\]]+)\]/g, "(?<$1>[^/]+)");
+    const m = pathname.match(new RegExp(`^${pattern}/?$`));
+    if (m) {
+      const params = { ...(m.groups || {}) };
+      for (const k in params) {
+        if (route.includes(`[...${k}]`)) params[k] = params[k].split("/");
+      }
+      return { entry: routes.pages[route], params, route };
+    }
+  }
+  return null;
+}
+
+/**
+ * Navigate to `path`. Runs an optional route guard, swaps the rendered page
+ * (tearing down the previous one's lifecycle), and updates window.history.
+ */
+export async function navigate(path, replace = false, isPop = false) {
+  if (!path || !rootEl) return;
+  const url = new URL(path, window.location.origin);
+
+  if (guard) {
+    let redirected = false;
+    const to = {
+      path: url.pathname,
+      params: matchRoute(url.pathname)?.params || {},
+      query: Object.fromEntries(url.searchParams),
+    };
+    await new Promise((resolve) => {
+      const tools = {
+        next: () => resolve(),
+        redirect: (p) => {
+          redirected = true;
+          navigate(p, true);
+          resolve();
+        },
+        replace: (p) => {
+          redirected = true;
+          navigate(p, true);
+          resolve();
+        },
+      };
+      Promise.resolve(guard(to, tools)).catch(() => resolve());
+    });
+    if (redirected) return;
+  }
+
+  const match =
+    matchRoute(url.pathname) ||
+    (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
+
+  state.pathname.value = url.pathname;
+  state.searchParams.value = url.searchParams;
+  state.params.value = match ? match.params : {};
+
+  if (!isPop) {
+    if (replace) window.history.replaceState({}, "", path);
+    else window.history.pushState({}, "", path);
+  }
+
+  // Resolve (and lazily load) the page + its layout chain before tearing down the
+  // current view, so a slow/failed import doesn't leave a blank page.
+  let nodes = null;
+  if (match) {
+    try {
+      const built = await buildRouteNode(match, Object.fromEntries(url.searchParams));
+      nodes = built.nodes;
+    } catch (e) {
+      reportError(e, { phase: "route", path: url.pathname });
+      rootEl.replaceChildren();
+      rootEl.innerHTML = `<pre style="color:#f87171;padding:1rem">Failed to load ${url.pathname}\n${e?.message ?? e}</pre>`;
+      currentNodes = [];
+      return;
+    }
+  }
+
+  for (const n of currentNodes) runCleanup(n);
+  rootEl.replaceChildren();
+
+  if (nodes) {
+    rootEl.appendChild(nodes[nodes.length - 1]); // outermost node
+    for (const n of nodes) runMount(n); // run onMount for page + every layout
+    currentNodes = nodes;
+    clearError({ phase: "route" }); // a good render dismisses a prior error overlay
+  } else {
+    rootEl.innerHTML = "<h1>404 — Not Found</h1>";
+    currentNodes = [];
+  }
+}
+
+/**
+ * Bootstrap the application: register routes, wire history, and render the page
+ * for the current URL.
+ *
+ * @param {Object} opts
+ * @param {Object} opts.pages  `{ path: module }` route map (from the dev server).
+ * @param {Element} [opts.target]  the app root (defaults to `#app`).
+ * @param {Function} [opts.guard]  optional `(to, tools) => …` route guard.
+ */
+export function mountApp({ pages, target, guard: g } = {}) {
+  rootEl = target || (isBrowser ? document.getElementById("app") : null);
+  if (pages) registerRoutes(pages);
+  guard = g || null;
+  if (isBrowser) {
+    window.addEventListener("popstate", () =>
+      navigate(
+        window.location.pathname + window.location.search + window.location.hash,
+        false,
+        true,
+      ),
+    );
+  }
+  navigate(window.location.pathname + window.location.search + window.location.hash, true, true);
+}
+
+// `<Link>` is a pure JSX component (packages/web/components/Link.jsx), compiled by
+// the app's pipeline like any UI component — it lives there, not as a hand-written
+// Custom Element here. It imports `navigate` from this module.

package/server/builtins.js

@@ -0,0 +1,11 @@
+//! SSG renderers for the built-in runtime components (the ones that are
+//! hand-written Custom Elements, not compiled). Registered on import so the SSG
+//! bundle can render `<Link>`, `<ContextProvider>`, `<Portal>`, `<ErrorBoundary>`.
+
+import { defineSSG } from "./ssg-runtime.js";
+
+// (web-link is provided by the compiled components/Link.jsx, not hand-written.)
+// Passthrough: their effect is structural/client-side; SSG renders children inline.
+defineSSG("web-context-provider", (_props, children) => children);
+defineSSG("web-portal", (_props, children) => children);
+defineSSG("web-error-boundary", (_props, children) => children);

package/server/index.js

@@ -0,0 +1,7 @@
+// Server entry for SSG: the string-building helpers the compiler emits, the
+// render/route API, and the built-in component SSG renderers (registered on
+// import). Imported as "@opentf/web/server".
+
+export * from "./ssg-runtime.js";
+export * from "./render.js";
+import "./builtins.js";

package/server/render.js

@@ -0,0 +1,76 @@
+//! Server render for SSG (ARCHITECTURE.md §6) — composes a route's HTML by
+//! calling the SSG render functions the compiler emits (page/layout factories
+//! that return strings, components registered in the SSG registry). No DOM: this
+//! runs in plain Bun/Node at build time.
+//
+// The route table (registerRoutes/matchRoute/layoutChain) is shared with the
+// client router; here we resolve a route's page + layout chain to string
+// renderers and concatenate them, passing `children` as an HTML string.
+
+import {
+  layoutChain,
+  matchRoute,
+  resolveFactory,
+  routes,
+  setRouteState,
+} from "../runtime/router.js";
+
+/**
+ * Render `pathname` to an HTML string (the markup for inside `#app`). Falls back
+ * to the registered `404` page for an unmatched path; returns `null` if there's
+ * no match and no 404.
+ */
+export async function renderToString(pathname, search = "") {
+  const match =
+    matchRoute(pathname) ||
+    (routes.notFound ? { entry: routes.notFound, params: {}, route: null } : null);
+  if (!match) return null;
+
+  // Let a page reading `router.params`/`pathname`/`query` resolve to this route.
+  setRouteState({ pathname, search, params: match.params });
+
+  const props = { params: match.params, query: Object.fromEntries(new URLSearchParams(search)) };
+  let html = (await resolveFactory(match.entry))(props);
+
+  // Wrap with layouts, most-specific inward to root outermost.
+  const chain = layoutChain(match.route);
+  for (let i = chain.length - 1; i >= 0; i--) {
+    const layout = await resolveFactory(chain[i]);
+    html = layout({ ...props, children: html });
+  }
+  return html;
+}
+
+/** Substitute `[param]` / `[...rest]` in a route with concrete values. */
+function fillRoute(route, params) {
+  return route
+    .replace(/\[\.\.\.([^\]]+)\]/g, (_, k) => [].concat(params[k] ?? []).join("/"))
+    .replace(/\[([^\]]+)\]/g, (_, k) => String(params[k] ?? ""));
+}
+
+/**
+ * Enumerate the concrete paths to pre-render. Static routes are taken as-is;
+ * dynamic routes (`[param]`) are expanded via the page module's optional
+ * `getStaticPaths()` (returning `[{ params }]`), else collected as `skipped`.
+ */
+export async function collectRoutePaths() {
+  const paths = [];
+  const skipped = [];
+  for (const route in routes.pages) {
+    if (!route.includes("[")) {
+      paths.push(route);
+      continue;
+    }
+    const ns = routes.pages[route];
+    const getStaticPaths =
+      ns && (ns.getStaticPaths || (ns.default && ns.default.getStaticPaths));
+    if (typeof getStaticPaths === "function") {
+      for (const entry of (await getStaticPaths()) || []) {
+        paths.push(fillRoute(route, entry.params || entry));
+      }
+    } else {
+      skipped.push(route);
+    }
+  }
+  return { paths, skipped };
+}

package/server/ssg-runtime.js

@@ -0,0 +1,109 @@
+//! SSG runtime helpers — the string-building primitives the SSG codegen emits
+//! (ARCHITECTURE.md §6). No DOM: these run in plain Bun/Node at build time and
+//! return HTML strings. Component output is composed via a tag→renderer registry,
+//! mirroring how CSR composes by Custom Element tag.
+
+const VOID = new Set([
+  "area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta",
+  "param", "source", "track", "wbr",
+]);
+
+const UNITLESS = new Set([
+  "opacity", "zIndex", "fontWeight", "lineHeight", "flex", "flexGrow", "flexShrink",
+  "order", "zoom", "tabSize", "columnCount", "fillOpacity", "strokeOpacity",
+]);
+
+const registry = {};
+
+/** Register a component's SSG renderer under its Custom Element tag. */
+export function defineSSG(tag, render) {
+  registry[tag] = render;
+}
+
+/** Escape text content for HTML. */
+export function escapeHtml(s) {
+  return String(s).replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));
+}
+
+/** Escape an attribute value. */
+export function escapeAttr(s) {
+  return String(s).replace(/[&"]/g, (c) => (c === "&" ? "&amp;" : "&quot;"));
+}
+
+/** clsx-style class normalization (mirrors runtime/dom.js). */
+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 "";
+}
+
+/** Serialize a style value (string passthrough, or object → `prop:val;`). */
+export function styleString(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  let s = "";
+  for (const k in value) {
+    const v = value[k];
+    if (v == null) continue;
+    const prop = k.startsWith("--") ? k : k.replace(/[A-Z]/g, (m) => "-" + m.toLowerCase());
+    const val = typeof v === "number" && !UNITLESS.has(k) ? `${v}px` : v;
+    s += `${prop}:${val};`;
+  }
+  return s;
+}
+
+/** Render one attribute: ` name="value"`, ` name` (true), or "" (null/false). */
+export function attr(name, value) {
+  if (name === "class") value = clsx(value);
+  else if (name === "style") value = styleString(value);
+  if (value == null || value === false) return "";
+  if (value === true) return ` ${name}`;
+  return ` ${name}="${escapeAttr(String(value))}"`;
+}
+
+/** A dynamic hole's value → HTML: trusted `{__html}` raw, else escaped text. */
+export function ssgText(v) {
+  if (v == null || v === false || v === true) return "";
+  if (typeof v === "object" && v.__html != null) return v.__html;
+  return escapeHtml(String(v));
+}
+
+/** Render an array.map list to concatenated HTML. */
+export function ssgList(arr, fn) {
+  return (Array.isArray(arr) ? arr : []).map(fn).join("");
+}
+
+/**
+ * Render a child component `<tag>inner</tag>` via the registry. Props are passed to
+ * the renderer (which decides where they land — declared props become properties /
+ * forward into the view), so the host tag carries no reflected attributes — exactly
+ * as CSR composes a component (props go through `setProp`, declared ones as
+ * properties, not host attributes). Avoids duplicating e.g. `class` on both the
+ * host and the element the component renders.
+ */
+export function ssgComponent(tag, props, children) {
+  const render = registry[tag];
+  let inner;
+  try {
+    inner = render ? render(props || {}, children ?? "") : (children ?? "");
+  } catch {
+    inner = ""; // fail soft (client renders/handles it)
+  }
+  return `<${tag}>${inner}</${tag}>`;
+}
+
+export { VOID };

package/README.md

@@ -1,41 +0,0 @@
-# @opentf/web
-
-The core engine of the **Web App Framework**, a lightweight, high-performance SPA framework designed for the modern web.
-
-## Features
-
-- 🚀 **Zero-VDOM**: Compiles JSX directly to imperative DOM operations for maximum speed.
-- ⚡ **Signal-Based Reactivity**: Powered by `@preact/signals-core` for fine-grained, surgical updates.
-- 📦 **Web Component Native**: Every component is a standard Custom Element, ensuring perfect encapsulation and interoperability.
-- 🛠️ **Convention-over-Configuration**: File-based routing and automatic component registration.
-- 📏 **Ultra-Lightweight**: Minimal runtime footprint.
-
-## Installation
-
-```bash
-npm install @opentf/web
-```
-
-## Basic Usage
-
-```jsx
-export default function Counter() {
-  let count = $state(0);
-
-  return (
-    <div className="counter">
-      <button onclick={() => count--}>-</button>
-      <span>{count}</span>
-      <button onclick={() => count++}>+</button>
-    </div>
-  );
-}
-```
-
-## Documentation
-
-Visit [web.opentf.workers.dev](https://web.opentf.workers.dev) for full documentation and guides.
-
-## License
-
-MIT © [Open Tech Foundation](https://github.com/Open-Tech-Foundation)

package/dist/CHANGELOG.md

@@ -1,49 +0,0 @@
-# @opentf/web
-
-## 0.4.0
-
-### Minor Changes
-
-- ba984c2: Here is a summary of the changes for your changelog:
-
-  ### 🚀 Features
-
-  - **Compiler:** Added comprehensive support for **SVG camelCase attributes** (e.g., `viewBox`, `strokeWidth`, `strokeLinecap`). The compiler now preserves the original casing for these attributes, ensuring icons and SVGs render correctly in the browser.
-  - **Router:** Improved route matching to support **optional trailing slashes** (e.g., `/about` and `/about/` now match the same route).
-  - **Playground:** Added a new **SVG Icons Showcase** page to demonstrate seamless integration with icon libraries like Lucide and Heroicons.
-
-  ### 🐞 Bug Fixes
-
-  - **Compiler:** Fixed a critical bug where **imported components** were incorrectly compiled as dynamic variables (e.g., `document.createElement(Link)`) instead of using their registered custom element tag names (e.g., `document.createElement("web-link")`).
-  - **Playground:** Resolved a build failure in the Icons page by correcting an illegal `const` reassignment of a reactive state variable.
-  - **Performance:** Reduced the simulated network delay in `routeGuard.js` from 800ms to 100ms for a snappier development experience.
-
-  ### 🏠 Internal & Maintenance
-
-  - **Refactoring:** Optimized the Babel plugin by moving large static lists (SVG tags, properties, etc.) to the top-level scope, improving compilation speed.
-  - **Testing:** Expanded the test suite with new cases for **icon libraries** and **complex React patterns** (dynamic tags, render props, spread overrides).
-
-  ***
-
-## 0.3.0
-
-### Minor Changes
-
-- 476d65a: Fix reactivity issues by re-exporting all signals from the core package and updating the compiler to use a unified reactivity instance. This prevents state-update failures in complex project structures.
-
-## 0.2.0
-
-### Minor Changes
-
-- a56fdfe: Fix the core components to prebuilt before publishing
-
-## 0.1.0
-
-### Minor Changes
-
-- Global rebranding to Web App Framework and monorepo restructuring.
-  - Renamed all packages from `@opentf/mwaf-*` to `@opentf/web-*`.
-  - Updated Custom Element prefix from `mwaf-` to `web-`.
-  - Restructured the repository into a scoped monorepo.
-  - Updated scaffolding tool `@opentf/create-web` with new templates.
-  - Aligned all package versions to 0.1.0-alpha.1.

package/dist/README.md

@@ -1,41 +0,0 @@
-# @opentf/web
-
-The core engine of the **Web App Framework**, a lightweight, high-performance SPA framework designed for the modern web.
-
-## Features
-
-- 🚀 **Zero-VDOM**: Compiles JSX directly to imperative DOM operations for maximum speed.
-- ⚡ **Signal-Based Reactivity**: Powered by `@preact/signals-core` for fine-grained, surgical updates.
-- 📦 **Web Component Native**: Every component is a standard Custom Element, ensuring perfect encapsulation and interoperability.
-- 🛠️ **Convention-over-Configuration**: File-based routing and automatic component registration.
-- 📏 **Ultra-Lightweight**: Minimal runtime footprint.
-
-## Installation
-
-```bash
-npm install @opentf/web
-```
-
-## Basic Usage
-
-```jsx
-export default function Counter() {
-  let count = $state(0);
-
-  return (
-    <div className="counter">
-      <button onclick={() => count--}>-</button>
-      <span>{count}</span>
-      <button onclick={() => count++}>+</button>
-    </div>
-  );
-}
-```
-
-## Documentation
-
-Visit [web.opentf.workers.dev](https://web.opentf.workers.dev) for full documentation and guides.
-
-## License
-
-MIT © [Open Tech Foundation](https://github.com/Open-Tech-Foundation)

package/dist/babel.config.cjs

@@ -1,6 +0,0 @@
-module.exports = {
-  plugins: [
-    "@babel/plugin-syntax-jsx",
-    ["./compiler/babel-plugin.cjs", { "runtimeSource": "../index.js" }]
-  ]
-};