azoxjs 0.2.0 → 1.0.0

package/core/reactivity/signal.js

@@ -32,6 +32,23 @@ export function signal(initialValue) {
   return read;
 }
 
+// Runs `fn` with no effect considered active, so anything it creates
+// belongs to nobody and survives the caller re-running.
+//
+// A keyed list needs this: its rows are built inside the list's own
+// effect, which would make them its children — and re-running the list
+// then tears down every surviving row, leaving it on screen but no
+// longer reactive.
+export function untracked(fn) {
+  const previous = activeEffect;
+  activeEffect = null;
+  try {
+    return fn();
+  } finally {
+    activeEffect = previous;
+  }
+}
+
 export function effect(fn) {
   const wrapped = () => {
     // Drop last run's subscriptions before re-reading. Without this,
@@ -55,25 +72,108 @@ export function effect(fn) {
   if (activeEffect) activeEffect.children.add(wrapped);
   wrapped.children = new Set();
 
+  // Callbacks registered by onCleanup() while this effect runs.
+  wrapped.cleanups = new Set();
+
   wrapped();
   return wrapped;
 }
 
+// Registers work to undo when the surrounding scope goes away: a
+// timer to clear, a listener to remove, a subscription to close.
+//
+// Called inside a component's script it runs when the component is
+// removed — a row leaving a keyed list, or a branch of an <if> that is
+// no longer taken. Called at the top level of a page there is nothing
+// that ever removes it, so it never runs; that is a page living as long
+// as the document, not a failure.
+export function onCleanup(fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('onCleanup() needs a function to call when the scope goes away');
+  }
+
+  if (!activeEffect) return;
+  activeEffect.cleanups.add(fn);
+}
+
+// Runs after the DOM this scope builds is in the document.
+//
+// A component's script runs while its nodes are still being created,
+// so measuring an element or focusing an input has to wait. Queued as
+// a microtask, which is after the synchronous render and before the
+// browser paints.
+export function onMount(fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('onMount() needs a function to call once the DOM is ready');
+  }
+
+  // Captured now: by the time the microtask runs, the effect that owns
+  // this registration is no longer the active one.
+  const owner = activeEffect;
+
+  queueMicrotask(() => {
+    // The scope was disposed before it ever mounted — a row added and
+    // removed in the same tick. Running setup for something already
+    // gone would leak whatever it creates.
+    if (owner && owner.disposed) return;
+
+    const result = fn();
+
+    // A function returned from onMount is treated as its cleanup, so
+    // the common setup-and-teardown pair can stay in one place.
+    if (typeof result === 'function') {
+      if (owner && !owner.disposed) owner.cleanups.add(result);
+      else result();
+    }
+  });
+}
+
 // Detaches an effect from every signal it read, and disposes anything
 // it created. Called before a re-run and by dispose().
 function unsubscribe(effectFn) {
   for (const child of effectFn.children) unsubscribe(child);
   effectFn.children.clear();
 
+  // Cleanups run before the effect is detached, so they still see the
+  // state they were registered against. One throwing must not stop the
+  // rest — a half-cleaned scope leaks whatever the others held.
+  for (const cleanup of effectFn.cleanups ?? []) {
+    try {
+      cleanup();
+    } catch (error) {
+      reportCleanupError(error);
+    }
+  }
+  effectFn.cleanups?.clear();
+
   for (const subscribers of effectFn.sources) subscribers.delete(effectFn);
   effectFn.sources.clear();
 }
 
+// A cleanup that throws is a bug in the callback, not in the scope
+// being torn down. Reported rather than swallowed, and rather than
+// taking the rest of the teardown with it.
+function reportCleanupError(error) {
+  if (typeof console !== 'undefined') {
+    console.error('Azox: an onCleanup callback threw', error);
+  }
+}
+
 // Stops an effect permanently. Control-flow blocks use this to clean
 // up the effects belonging to content they are about to remove;
 // without it, every list item ever rendered would stay subscribed.
 export function dispose(effectFn) {
-  if (effectFn) unsubscribe(effectFn);
+  if (!effectFn) return;
+
+  // Marked before the walk, so an onMount microtask that has not run
+  // yet knows its scope is gone and skips its setup.
+  markDisposed(effectFn);
+  unsubscribe(effectFn);
+}
+
+function markDisposed(effectFn) {
+  effectFn.disposed = true;
+  for (const child of effectFn.children) markDisposed(child);
 }
 
 export function computed(fn) {

package/core/renderer/renderToHtml.js

@@ -45,8 +45,26 @@ function renderNode(node, scope, outer, modules = {}) {
   const attrs = Object.entries(node.attrs)
     .filter(([key]) => !key.startsWith('on:'))
     .map(([key, attr]) => {
-      const value = attr.kind === 'static' ? attr.value : String(evalExpr(attr.expr, scope));
-      return ` ${key}="${escapeHtml(value)}"`;
+      // bind:value={draft} renders as the plain attribute, so the input
+      // arrives holding its value rather than showing "bind:value" in
+      // the markup and filling in once scripts run.
+      //
+      // A binding names the signal rather than calling it — that is what
+      // lets it write back — so it has to be read here.
+      const bound = key.startsWith('bind:');
+      const name = bound ? key.slice(5) : key;
+
+      const raw = attr.kind === 'static'
+        ? attr.value
+        : readAttrValue(attr.expr, scope, bound);
+
+      // A checkbox is checked by the attribute being present at all, so
+      // a falsy value must omit it rather than render checked="false".
+      if (name === 'checked' || name === 'selected') {
+        return raw ? ` ${name}` : '';
+      }
+
+      return ` ${name}="${escapeHtml(String(raw ?? ''))}"`;
     })
     .join('');
 
@@ -111,6 +129,13 @@ function renderIf(node, scope, outer, modules = {}) {
   return branch.map((child) => renderNode(child, scope, outer, modules)).join('');
 }
 
+// Reads an attribute expression. A bound one names a signal, so it is
+// called; anything else is evaluated as written.
+function readAttrValue(expr, scope, bound) {
+  const value = evalExpr(expr, scope);
+  return bound && typeof value === 'function' ? value() : value;
+}
+
 // Three kinds of text, three rules:
 //   static  — markup the author wrote, so an entity they typed
 //             (<) is meant to stay an entity. Passed through.

package/core/renderer/serverScope.js

@@ -28,6 +28,16 @@ export function serverComputed(fn) {
   return () => fn();
 }
 
+// Server rendering produces a string: there is no DOM to mount into,
+// and nothing is ever removed, so both hooks do nothing here. The real
+// ones take over in the browser.
+//
+// They still have to exist, or a component that uses them fails the
+// build with "onMount is not defined" — the page would be unbuildable
+// rather than merely non-reactive on the server.
+export function serverOnMount() {}
+export function serverOnCleanup() {}
+
 // Every top-level binding the script introduces, so they can all be
 // handed to the markup. Function and class declarations count too — a
 // component may well define a helper the template calls.
@@ -58,24 +68,40 @@ export function declaredNames(script) {
 // Evaluates a script body and returns its declarations. `params` and
 // `args` pass a component's props in as arguments.
 //
+// `extras` are further bindings the caller supplies by name — `params`
+// for a dynamic page, and `routes` while its route list is collected.
+//
 // `modules` carries what the script's imports brought in, as local
 // name → value. The body runs inside a `new Function`, which cannot
 // use `import`, so the bindings arrive as arguments instead — the
 // build resolves them, since loading a module needs the filesystem
 // and this file has to stay usable in a browser.
-export function evaluateScript(body, params = [], args = [], modules = {}) {
+export function evaluateScript(body, params = [], args = [], modules = {}, extras = {}) {
   const imported = Object.keys(modules);
-  const names = declaredNames(body).filter((name) => !imported.includes(name));
+  const extraNames = Object.keys(extras);
+  const reserved = new Set([...imported, ...extraNames]);
+  const names = declaredNames(body).filter((name) => !reserved.has(name));
 
   const fn = new Function(
     'signal',
     'computed',
+    'onMount',
+    'onCleanup',
     ...imported,
+    ...extraNames,
     ...params,
     `${body}\nreturn { ${names.join(', ')} };`
   );
 
-  const declared = fn(serverSignal, serverComputed, ...imported.map((n) => modules[n]), ...args);
+  const declared = fn(
+    serverSignal,
+    serverComputed,
+    serverOnMount,
+    serverOnCleanup,
+    ...imported.map((n) => modules[n]),
+    ...extraNames.map((n) => extras[n]),
+    ...args
+  );
 
   // An imported binding is in scope for the markup too, the same way
   // it is in the compiled module.

package/core/routes.js

@@ -5,6 +5,11 @@
 //   pages/blog/index.azox   →  /blog          →  blog/index.html
 //   pages/blog/first.azox   →  /blog/first    →  blog/first/index.html
 //
+// A segment in brackets is a parameter, and the file is a template
+// rather than a route of its own:
+//
+//   pages/blog/[slug].azox  →  one page per entry the file declares
+//
 // Emitting a directory with an index.html means clean URLs work on
 // any static host without rewrite rules, since serving index.html
 // for a directory is universal behaviour.
@@ -43,6 +48,38 @@ function walk(dir, pagesDir) {
   return found;
 }
 
+// A bracketed segment names a parameter: [slug] matches one segment
+// and binds it to `slug`.
+const PARAM_SEGMENT = /^\[([A-Za-z_$][\w$]*)\]$/;
+
+export function paramNames(segments) {
+  return segments.map((segment) => segment.match(PARAM_SEGMENT)?.[1]).filter(Boolean);
+}
+
+// Fills a template's bracketed segments from a set of parameter
+// values, producing the concrete route that will be written.
+export function resolveRoute(route, values) {
+  const segments = route.templateSegments.map((segment) => {
+    const name = segment.match(PARAM_SEGMENT)?.[1];
+    if (!name) return segment;
+    return String(values[name]);
+  });
+
+  const url = segments.length ? `/${segments.join('/')}` : '/';
+  const outputDir = segments.join('/');
+
+  return {
+    ...route,
+    params: values,
+    isTemplate: false,
+    name: segments.join('/'),
+    url,
+    htmlPath: outputDir ? `${outputDir}/index.html` : 'index.html',
+    assetPrefix: '../'.repeat(segments.length) || './',
+    outputDir,
+  };
+}
+
 function describeRoute(pagesDir, sourcePath) {
   const relativePath = relative(pagesDir, sourcePath);
   const segments = relativePath.slice(0, -PAGE_EXTENSION.length).split(sep);
@@ -54,6 +91,8 @@ function describeRoute(pagesDir, sourcePath) {
   const url = routeSegments.length ? `/${routeSegments.join('/')}` : '/';
   const outputDir = routeSegments.join('/');
 
+  const params = paramNames(routeSegments);
+
   return {
     // The name used on the command line: `azox compile --page=blog/first`
     name: segments.join('/'),
@@ -64,6 +103,11 @@ function describeRoute(pagesDir, sourcePath) {
     // back out to reach the shared runtime at the build root.
     assetPrefix: '../'.repeat(routeSegments.length) || './',
     outputDir,
+    // A template is not a page: it stands in for however many the
+    // file declares, and is never written at this url.
+    isTemplate: params.length > 0,
+    paramNames: params,
+    templateSegments: routeSegments,
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "azoxjs",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Azox Framework — The Sound of Future Web",
   "type": "module",
   "license": "MIT",