azoxjs 0.2.0 → 1.0.0

package/core/compiler/compileToJs.js

@@ -10,6 +10,52 @@
 let uid = 0;
 const nextId = () => `_el${uid++}`;
 
+// Names the build resolved to constants — an inlined JSON import, say.
+// An expression reading only these can never change, so it is emitted
+// as text rather than wrapped in an effect. Set per compile.
+let constantNames = new Set();
+let constantValues = {};
+
+// True when `expr` reads nothing that could ever change: literals,
+// operators, and property paths rooted in a build-time constant.
+//
+// Deliberately conservative. A call, an unknown identifier, or anything
+// it cannot account for means "assume it changes" — being wrong that way
+// costs an effect that never fires, while the opposite silently freezes
+// a binding that should update.
+function isConstantExpression(expr) {
+  if (!constantNames.size) return false;
+
+  const source = expr.trim();
+  if (!source) return false;
+
+  // A call could return anything, and assignment or increment means the
+  // value is meant to change.
+  if (/[(]/.test(source)) return false;
+  if (/(\+\+|--|[^=!<>]=[^=])/.test(source)) return false;
+
+  // Strip strings and template literals before looking at identifiers,
+  // so words inside them are not mistaken for names.
+  const withoutStrings = source
+    .replace(/'(?:[^'\\]|\\.)*'/g, "''")
+    .replace(/"(?:[^"\\]|\\.)*"/g, '""')
+    .replace(/`(?:[^`\\$]|\\.|\$(?!\{))*`/g, '``');
+
+  // A template literal with a placeholder is not handled here.
+  if (/`/.test(withoutStrings) && /\$\{/.test(source)) return false;
+
+  // Every identifier that is not a property access must be a known
+  // constant. `pkg.version` yields `pkg`; `a.b.c` yields `a`.
+  const roots = [...withoutStrings.matchAll(/(\.)?\b([A-Za-z_$][\w$]*)\b/g)]
+    .filter(([, dot]) => !dot)
+    .map(([, , name]) => name);
+
+  if (!roots.length) return false;
+
+  const allowed = new Set(['true', 'false', 'null', 'undefined']);
+  return roots.every((name) => constantNames.has(name) || allowed.has(name));
+}
+
 // runtimeSpecifier: how the emitted module should import the Azox
 //   runtime — a relative path to the copied runtime for a build, or
 //   whatever the playground wants to point at.
@@ -23,12 +69,25 @@ const nextId = () => `_el${uid++}`;
 //   value, whose import must not reach the browser. A JSON import
 //   points outside the build directory at a file that is never
 //   deployed, so the value is emitted as a constant instead.
-export function compileToModule(ast, { runtimeSpecifier, rewriteImports, inlineModules }) {
+// routeParams: the resolved parameters for this page of a dynamic
+//   route. routes() is a build-time declaration and params() is
+//   answered before the browser is involved, so both are removed from
+//   the emitted module and the values are inlined.
+export function compileToModule(
+  ast,
+  { runtimeSpecifier, rewriteImports, inlineModules, routeParams }
+) {
   uid = 0;
+  // Values the build resolved: their bindings need no effect, which is
+  // what lets a page whose only "dynamic" text is a version number ship
+  // as a static page.
+  constantValues = inlineModules ?? {};
+  constantNames = new Set(Object.keys(constantValues));
   const statements = [];
   const rootVar = emitNode(ast.markup, statements, 'root');
 
   let script = dropComponentImports(ast.script);
+  script = resolveRouteDeclarations(script, routeParams);
   if (rewriteImports) script = rewriteImports(script);
 
   // A page with no bindings and no listeners has nothing to hydrate:
@@ -57,13 +116,15 @@ export function compileToModule(ast, { runtimeSpecifier, rewriteImports, inlineM
   // A keyed list disposes the effects of rows that leave, so the
   // module needs dispose as well as effect.
   const needsDispose = statements.some((line) => line.includes('dispose('));
+  const needsUntracked = statements.some((line) => line.includes('untracked('));
 
   const { imports, body } = mergeImports(
     script,
     hoisted,
     runtimeSpecifier,
     needsDispose,
-    inlineModules
+    inlineModules,
+    needsUntracked
   );
 
   // Narrowed to what the module actually reads, so importing
@@ -94,7 +155,8 @@ function mergeImports(
   componentImports,
   runtimeSpecifier,
   needsDispose = false,
-  inlineModules = null
+  inlineModules = null,
+  needsUntracked = false
 ) {
   const pageImports = [...script.matchAll(/^\s*(import\s[^;\n]+;?)\s*$/gm)]
     .map((m) => m[1].trim())
@@ -108,6 +170,24 @@ function mergeImports(
   const named = new Map();
   const verbatim = new Set();
 
+  // A page writes `azox/reactivity`; the compiler's own imports use
+  // whatever runtimeSpecifier it was given. They name the same module,
+  // so they are grouped under one key — otherwise a page importing
+  // `signal` and a keyed list needing it emit two imports that the
+  // build later rewrites to the same path, which is a redeclaration and
+  // a syntax error.
+  //
+  // Only the grouping is normalised. The emitted specifier stays as
+  // written, because rewriting it to a path on disk is the build's job —
+  // the playground compiles in the browser with no build at all.
+  const RUNTIME_ALIASES = new Set([
+    'azox',
+    'azox/reactivity',
+    'azoxjs',
+    'azoxjs/reactivity',
+    runtimeSpecifier,
+  ]);
+
   const record = (statement) => {
     const match = statement.match(/^import\s*\{([^}]*)\}\s*from\s*['"]([^'"]+)['"]/);
 
@@ -116,7 +196,13 @@ function mergeImports(
       return;
     }
 
-    const [, bindings, specifier] = match;
+    const [, bindings, rawSpecifier] = match;
+    // Grouped under the first spelling seen for the runtime, so the
+    // page's own `azox/reactivity` survives into the output when that is
+    // what was written.
+    const specifier = RUNTIME_ALIASES.has(rawSpecifier)
+      ? runtimeKey(named, rawSpecifier, RUNTIME_ALIASES)
+      : rawSpecifier;
     const set = named.get(specifier) ?? new Set();
     for (const binding of bindings.split(',')) {
       if (binding.trim()) set.add(binding.trim());
@@ -124,10 +210,17 @@ function mergeImports(
     named.set(specifier, set);
   };
 
+  // The author's imports are recorded first, so the runtime group keeps
+  // the spelling they wrote — `azox/reactivity`, which the build rewrites
+  // later. Recording the compiler's own first would name the group after
+  // runtimeSpecifier and rewrite the author's import here, which is the
+  // build's job and would break the playground's build-free compile.
+  for (const statement of [...componentImports, ...pageImports]) record(statement);
+
   // `effect` is always needed: the compiler emits calls to it.
   record(`import { effect } from '${runtimeSpecifier}';`);
   if (needsDispose) record(`import { dispose } from '${runtimeSpecifier}';`);
-  for (const statement of [...componentImports, ...pageImports]) record(statement);
+  if (needsUntracked) record(`import { untracked } from '${runtimeSpecifier}';`);
 
   const lines = [
     ...[...named].map(([specifier, bindings]) => {
@@ -139,6 +232,15 @@ function mergeImports(
   return { imports: lines.join('\n'), body };
 }
 
+// Returns the key the runtime's imports are already grouped under, or
+// this spelling if it is the first one seen.
+function runtimeKey(named, specifier, aliases) {
+  for (const existing of named.keys()) {
+    if (aliases.has(existing)) return existing;
+  }
+  return specifier;
+}
+
 // An import is inlined when every binding it declares was loaded by
 // the build. Matching on the specifier would be wrong: the same file
 // could be imported for some other reason.
@@ -187,10 +289,20 @@ function emitInlineModules(inlineModules, usage = '') {
   const entries = Object.entries(inlineModules);
   if (!entries.length) return '';
 
-  const lines = entries.map(
-    ([name, value]) => `const ${name} = ${JSON.stringify(narrow(name, value, usage))};`
-  );
-  return `${lines.join('\n')}\n`;
+  const lines = entries
+    // A value whose every read was folded into the markup needs no
+    // declaration at all. Emitting it anyway would publish the rest of
+    // the file — an author's address included — for nothing.
+    .filter(([name]) => isRead(name, usage))
+    .map(([name, value]) => `const ${name} = ${JSON.stringify(narrow(name, value, usage))};`);
+
+  return lines.length ? `${lines.join('\n')}\n` : '';
+}
+
+// Whether the emitted code still mentions the binding.
+function isRead(name, usage) {
+  const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`\\b${escaped}\\b`).test(usage);
 }
 
 // Keeps only the properties the module reads by name. A page that
@@ -230,11 +342,32 @@ function narrow(name, value, usage) {
   return narrowed;
 }
 
+// Removes the build-time route declarations from a page's script.
+//
+// routes([...]) says which pages to build, which the browser has no
+// use for — and calling it there is a ReferenceError that leaves the
+// page inert. params() is replaced by the values this page was built
+// with, so the markup reads them as plain data.
+function resolveRouteDeclarations(script, routeParams) {
+  if (!routeParams) return script;
+
+  return script
+    // A whole statement, so the trailing semicolon and newline go too.
+    .replace(/^[ \t]*routes\s*\([\s\S]*?\)\s*;?[ \t]*$/gm, '')
+    .replace(/\bparams\s*\(\s*\)/g, JSON.stringify(routeParams));
+}
+
+// Marks a module that does nothing on load. The build reads it to decide
+// whether the page needs to reference the module at all — a static page
+// that still downloads it pays for a render() nobody calls, and pulls in
+// the runtime with it.
+export const STATIC_MARKER = 'azox:static';
+
 function staticNote() {
   return `
-// This page has no bindings and no listeners, so the server-rendered
-// markup is already complete and is left untouched. render() is
-// exported for anyone who wants to mount it somewhere else.
+// ${STATIC_MARKER} — this page has no bindings and no listeners, so the
+// server-rendered markup is already complete and is left untouched.
+// render() is exported for anyone who wants to mount it somewhere else.
 `;
 }
 
@@ -274,7 +407,7 @@ function emitNode(node, statements, fallbackVar) {
   statements.push(`const ${varName} = document.createElement(${JSON.stringify(node.name)});`);
 
   for (const [key, attr] of Object.entries(node.attrs)) {
-    emitAttr(varName, key, attr, statements);
+    emitAttr(varName, key, attr, statements, node.name);
   }
 
   appendChildren(varName, node.children, statements, fallbackVar);
@@ -387,7 +520,7 @@ function emitEach(node, statements) {
 // inside their own effect scope rather than inside the block's, since
 // re-running the block must not tear down rows it is keeping.
 function emitKeyedEach(node, statements) {
-  const params = node.index ? `${node.alias}, ${node.index}` : node.alias;
+  const buildParams = node.index ? `${node.alias}, ${node.index}` : node.alias;
 
   const start = nextId();
   const end = nextId();
@@ -409,12 +542,21 @@ function emitKeyedEach(node, statements) {
   const bodyLines = [];
   const roots = node.children.map((child) => emitNode(child, bodyLines, 'root'));
 
-  statements.push(`const ${build} = (${params}) => {`);
+  // The index is the position the row was built at, and a keyed row is
+  // built once. Reordering therefore moves rows without renumbering
+  // them — the cost of keeping a row rather than rebuilding it. Use the
+  // index for a stable list, and read the position from the data when a
+  // list reorders.
+  statements.push(`const ${build} = (${buildParams}) => {`);
   statements.push(`  let _nodes;`);
-  statements.push(`  const _scope = effect(() => {`);
+  // untracked: the row is built while the list's effect is running, so
+  // without this it becomes that effect's child — and the next list
+  // change tears the row down even though it survived, leaving its
+  // bindings dead and its onCleanup callbacks fired.
+  statements.push(`  const _scope = untracked(() => effect(() => {`);
   for (const line of bodyLines) statements.push(`    ${line}`);
   statements.push(`    _nodes = [${roots.filter((r) => r !== 'null').join(', ')}];`);
-  statements.push(`  });`);
+  statements.push(`  }));`);
   statements.push(`  return { nodes: _nodes, scope: _scope };`);
   statements.push(`};`);
 
@@ -552,7 +694,7 @@ function foldLiteralParts(parts) {
 
 function emitText(node, statements, fallbackVar) {
   const isFixed = (part) => part.kind === 'static' || part.kind === 'literal';
-  node = { ...node, parts: foldLiteralParts(node.parts) };
+  node = { ...node, parts: foldConstantParts(foldLiteralParts(node.parts)) };
 
   // Nothing dynamic: one text node, no effect needed.
   if (node.parts.every(isFixed)) {
@@ -572,6 +714,46 @@ function emitText(node, statements, fallbackVar) {
   return varName;
 }
 
+// Turns an expression the build already resolved into a literal part, so
+// the text node is created with the value rather than an effect being
+// attached to write it. The page whose only "dynamic" text is a version
+// number then ships as a static page.
+function foldConstantParts(parts) {
+  if (!constantNames.size) return parts;
+
+  return parts.map((part) => {
+    if (part.kind !== 'expr' || !isConstantExpression(part.expr)) return part;
+
+    const value = evaluateInlinedExpression(part.expr);
+    if (value === undefined) return part;
+
+    return { kind: 'literal', value: String(value) };
+  });
+}
+
+// Evaluates a constant expression against the values the build resolved.
+// Returns undefined when it cannot be evaluated, which leaves the part
+// dynamic — the safe direction.
+//
+// Named for this file: the playground concatenates the compiler's
+// modules into one scope, so a bare `evaluateConstant` collides with the
+// one in resolveComponents.js and the whole bundle fails to parse.
+function evaluateInlinedExpression(expr) {
+  try {
+    const names = [...constantNames];
+    const fn = new Function(...names, `return (${expr});`);
+    const value = fn(...names.map((name) => constantValues[name]));
+
+    // Only a primitive can be written into the markup as text.
+    if (value === null || value === undefined) return undefined;
+    if (typeof value === 'object' || typeof value === 'function') return undefined;
+
+    return value;
+  } catch {
+    return undefined;
+  }
+}
+
 // The five entities that matter for text content. Numeric forms are
 // handled too, since documentation snippets tend to use them.
 function decodeEntities(text) {
@@ -585,22 +767,77 @@ function decodeEntities(text) {
     .replace(/&amp;/g, '&');
 }
 
-function emitAttr(varName, key, attr, statements) {
+// Properties that must be set as properties rather than attributes:
+// setAttribute("value") only sets the *initial* value, so after a user
+// types, writing the attribute changes nothing they can see.
+const DOM_PROPERTIES = new Set(['value', 'checked', 'selected', 'indeterminate']);
+
+function emitAttr(varName, key, attr, statements, tagName) {
   if (key.startsWith('on:')) {
     const event = key.slice(3);
     statements.push(`${varName}.addEventListener(${JSON.stringify(event)}, ${attr.expr});`);
     return;
   }
 
+  if (key.startsWith('bind:')) {
+    emitBinding(varName, key.slice(5), attr, statements, tagName);
+    return;
+  }
+
   if (attr.kind === 'static') {
     statements.push(`${varName}.setAttribute(${JSON.stringify(key)}, ${JSON.stringify(attr.value)});`);
     return;
   }
 
+  // A property has to be assigned, not set as an attribute — see
+  // DOM_PROPERTIES. Everything else is an attribute.
+  if (DOM_PROPERTIES.has(key)) {
+    statements.push(`effect(() => { ${varName}.${key} = ${attr.expr}; });`);
+    return;
+  }
+
   // Dynamic attribute: wrap in its own effect, same fine-grained rule as text.
   statements.push(`effect(() => { ${varName}.setAttribute(${JSON.stringify(key)}, String(${attr.expr})); });`);
 }
 
+// Two-way binding: the element shows the signal, and the signal follows
+// the element. Writing it by hand means a value= and an on:input= that
+// have to agree, and getting the event or the property wrong is easy —
+// a checkbox reports `checked`, not `value`, and a number input reports
+// a string.
+function emitBinding(varName, property, attr, statements, tagName) {
+  const signal = attr.expr.trim();
+
+  // The signal itself, not a call: `bind:value={draft}`. Binding needs
+  // to write back, which a value cannot do.
+  if (!/^[A-Za-z_$][\w$]*$/.test(signal)) {
+    throw new Error(
+      `Azox: bind:${property}={${signal}} needs a signal by name — ` +
+        `write bind:${property}={draft}, not bind:${property}={draft()}`
+    );
+  }
+
+  // A checkbox's state is `checked`, and the event that reports it is
+  // "change" rather than "input".
+  const isCheckbox = property === 'checked';
+  const event = isCheckbox || tagName === 'select' ? 'change' : 'input';
+
+  statements.push(`effect(() => { ${varName}.${property} = ${signal}(); });`);
+  statements.push(
+    `${varName}.addEventListener(${JSON.stringify(event)}, (_e) => ` +
+      `${signal}.set(${readTarget(property, tagName)}));`
+  );
+}
+
+// How the value is read back off the element. A number input reports a
+// string, so it is converted — otherwise arithmetic on the signal
+// silently concatenates.
+function readTarget(property, tagName) {
+  if (property === 'checked') return '_e.target.checked';
+  if (tagName === 'input') return '(_e.target.type === "number" ? _e.target.valueAsNumber : _e.target.value)';
+  return '_e.target.value';
+}
+
 // Component imports are resolved at build time and inlined, so the
 // .azox specifier must not survive into JavaScript the browser loads.
 function dropComponentImports(script) {

package/core/compiler/parser.js

@@ -31,17 +31,36 @@ export function parseAzox(source) {
     .trim();
 
   const tokens = tokenize(template);
-  const { node, rest } = parseNode(tokens);
+
+  // Several roots become one fragment, so a component can return a pair
+  // of <li>s or a label beside its input without a wrapper element that
+  // exists only to satisfy the parser.
+  const roots = [];
+  let rest = tokens;
+
+  while (rest.length) {
+    const parsed = parseNode(rest);
+    if (!parsed.node) break;
+
+    roots.push(parsed.node);
+    rest = parsed.rest;
+  }
+
   if (rest.length) {
     throw new ParseError(`Azox parse error: unexpected trailing markup near "${rest[0]?.value ?? ''}"`);
   }
 
+  const markup = roots.length === 1 ? roots[0] : { type: 'fragment', children: roots };
+
   return {
     script,
     head,
-    markup: node,
+    markup,
     components: parseComponentImports(script),
     props: parsePropNames(script),
+    // A dynamic page destructures its route parameters the same way a
+    // component destructures its props.
+    params: parseParamNames(script),
   };
 }
 
@@ -63,6 +82,18 @@ function parseComponentImports(script) {
 // `const { title, count } = props();` declares what a component
 // accepts. Declaring them explicitly lets the compiler reject a
 // caller that passes something the component never asked for.
+// `const { slug } = params()` names the route parameters the page
+// reads, mirroring how props() declares a component's inputs.
+function parseParamNames(script) {
+  const match = script.match(/const\s*\{([^}]*)\}\s*=\s*params\(\)/);
+  if (!match) return [];
+
+  return match[1]
+    .split(',')
+    .map((name) => name.trim())
+    .filter(Boolean);
+}
+
 function parsePropNames(script) {
   const match = script.match(/const\s*\{([^}]*)\}\s*=\s*props\(\)/);
   if (!match) return [];

package/core/compiler/resolveComponents.js

@@ -20,7 +20,7 @@ export class ComponentError extends BuildError {}
 // `resolver` decides how an import specifier becomes source text, so
 // this runs unchanged against disk or against an in-memory map. See
 // sourceResolver.js.
-export function resolveComponents(ast, sourcePath, resolver, seen = new Set()) {
+export function resolveComponents(ast, sourcePath, resolver, seen = new Set(), heads = null) {
   // Imports from stateful components are hoisted here: they cannot
   // live inside the scope function the compiler builds for each one.
   //
@@ -30,16 +30,24 @@ export function resolveComponents(ast, sourcePath, resolver, seen = new Set()) {
   // rebasing a component's import against the page's directory points
   // it at a file that is not there.
   const hoisted = new Map();
-  const markup = expand(ast.markup, ast, sourcePath, resolver, seen, hoisted);
+
+  // A component's <head> block is collected the same way, keyed by the
+  // file it came from so the same component used twice contributes
+  // once. A stylesheet link belongs in the document head, and until
+  // now only a page could put one there.
+  const collected = heads ?? new Map();
+
+  const markup = expand(ast.markup, ast, sourcePath, resolver, seen, hoisted, collected);
 
   return {
     ...ast,
     markup,
     componentImports: [...hoisted.values()],
+    componentHeads: [...collected.values()],
   };
 }
 
-function expand(node, ast, sourcePath, resolver, seen, hoisted) {
+function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
   if (!node || node.type === 'text') return node;
 
   // <if> keeps its children in two branches rather than in `children`,
@@ -48,15 +56,17 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted) {
   if (node.type === 'if') {
     return {
       ...node,
-      then: node.then.map((child) => expand(child, ast, sourcePath, resolver, seen, hoisted)),
+      then: node.then.map((child) =>
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+      ),
       otherwise: node.otherwise.map((child) =>
-        expand(child, ast, sourcePath, resolver, seen, hoisted)
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
       ),
     };
   }
 
   const children = (node.children ?? []).map((child) =>
-    expand(child, ast, sourcePath, resolver, seen, hoisted)
+    expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
   );
 
   if (node.type !== 'component') {
@@ -72,9 +82,14 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted) {
     component.ast,
     component.path,
     resolver,
-    new Set([...seen, component.path])
+    new Set([...seen, component.path]),
+    heads
   );
 
+  // Keyed by path: a component used on a page twice must not emit its
+  // stylesheet link twice.
+  if (component.ast.head) heads.set(component.path, component.ast.head);
+
   const values = propValues(node, component.ast.props);
   const { logic, imports } = componentLogic(component.ast.script);
 

package/core/dev/watcher.js

@@ -11,7 +11,10 @@ import { join } from 'node:path';
 
 const DEBOUNCE_MS = 40;
 
-export function watchDirectory(dir, onChange, { filter = () => true } = {}) {
+// `recursive: false` watches only the directory itself. The project
+// root holds the build output and node_modules, so sweeping it
+// recursively would rebuild in a loop.
+export function watchDirectory(dir, onChange, { filter = () => true, recursive = true } = {}) {
   const watchers = [];
   let timer = null;
 
@@ -22,6 +25,14 @@ export function watchDirectory(dir, onChange, { filter = () => true } = {}) {
     timer = setTimeout(() => onChange(filename), DEBOUNCE_MS);
   };
 
+  if (!recursive) {
+    watchers.push(watch(dir, (_event, filename) => trigger(filename)));
+    return () => {
+      clearTimeout(timer);
+      for (const watcher of watchers) watcher.close();
+    };
+  }
+
   try {
     watchers.push(watch(dir, { recursive: true }, (_event, filename) => trigger(filename)));
   } catch {

package/core/index.js

@@ -1,6 +1,17 @@
 // Public entry point for `import ... from 'azoxjs'`.
 
-export { signal, effect, computed } from './reactivity/signal.js';
+// The whole reactivity surface, so `azoxjs` and `azoxjs/reactivity`
+// offer the same thing rather than the main entry quietly omitting the
+// newer half.
+export {
+  signal,
+  effect,
+  computed,
+  dispose,
+  untracked,
+  onMount,
+  onCleanup,
+} from './reactivity/signal.js';
 export { parseAzox } from './compiler/parser.js';
 export { compileToModule } from './compiler/compileToJs.js';
 export { renderToHtml } from './renderer/renderToHtml.js';