azoxjs 1.0.1 → 1.3.0

package/core/compiler/resolveComponents.js

@@ -7,6 +7,7 @@
 // been written by hand.
 
 import { parseAzox } from './parser.js';
+import { scopeId, scopeAttribute, scopeCss } from './scopeStyles.js';
 import { BuildError } from '../buildError.js';
 
 // Extends BuildError so the CLI reports it as a user-facing problem
@@ -20,7 +21,14 @@ 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(), heads = null) {
+export function resolveComponents(
+  ast,
+  sourcePath,
+  resolver,
+  seen = new Set(),
+  heads = null,
+  styles = null
+) {
   // Imports from stateful components are hoisted here: they cannot
   // live inside the scope function the compiler builds for each one.
   //
@@ -37,17 +45,31 @@ export function resolveComponents(ast, sourcePath, resolver, seen = new Set(), h
   // now only a page could put one there.
   const collected = heads ?? new Map();
 
-  const markup = expand(ast.markup, ast, sourcePath, resolver, seen, hoisted, collected);
+  // A component's <style> block is collected the same way and keyed by
+  // the same path, so a component used twice contributes its CSS once.
+  const collectedStyles = styles ?? new Map();
+
+  const markup = expand(
+    ast.markup,
+    ast,
+    sourcePath,
+    resolver,
+    seen,
+    hoisted,
+    collected,
+    collectedStyles
+  );
 
   return {
     ...ast,
     markup,
     componentImports: [...hoisted.values()],
     componentHeads: [...collected.values()],
+    componentStyles: [...collectedStyles.values()],
   };
 }
 
-function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
+function expand(node, ast, sourcePath, resolver, seen, hoisted, heads, styles) {
   if (!node || node.type === 'text') return node;
 
   // <if> keeps its children in two branches rather than in `children`,
@@ -57,16 +79,16 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
     return {
       ...node,
       then: node.then.map((child) =>
-        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads, styles)
       ),
       otherwise: node.otherwise.map((child) =>
-        expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+        expand(child, ast, sourcePath, resolver, seen, hoisted, heads, styles)
       ),
     };
   }
 
   const children = (node.children ?? []).map((child) =>
-    expand(child, ast, sourcePath, resolver, seen, hoisted, heads)
+    expand(child, ast, sourcePath, resolver, seen, hoisted, heads, styles)
   );
 
   if (node.type !== 'component') {
@@ -83,13 +105,27 @@ function expand(node, ast, sourcePath, resolver, seen, hoisted, heads) {
     component.path,
     resolver,
     new Set([...seen, component.path]),
-    heads
+    heads,
+    styles
   );
 
   // 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);
 
+  // A <style> block scopes to this component: its selectors are
+  // rewritten to require an attribute, and that attribute is put on the
+  // markup below. Both halves key off the same path, so the CSS and the
+  // elements it targets always agree.
+  let scope = null;
+
+  if (component.ast.style) {
+    scope = scopeId(component.path);
+    styles.set(component.path, scopeCss(component.ast.style, scope));
+  }
+
+  if (scope) markScope(inner.markup, scopeAttribute(scope));
+
   const values = propValues(node, component.ast.props);
   const { logic, imports } = componentLogic(component.ast.script);
 
@@ -160,6 +196,30 @@ function componentLogic(script) {
   return { logic: meaningful.trim() ? body.trim() : null, imports };
 }
 
+// Puts the scope attribute on every element the component owns.
+//
+// Slot content is skipped: it was written by whoever used the tag, so
+// it belongs to the caller's scope, and a component must not restyle
+// markup it did not write.
+function markScope(node, attribute) {
+  if (!node || node.type === 'text') return;
+
+  if (node.type === 'fragment' && node.slot) return;
+
+  if (node.type === 'element' || node.type === 'component') {
+    node.attrs = { ...node.attrs, [attribute]: { kind: 'static', value: '' } };
+  }
+
+  if (node.type === 'if') {
+    for (const child of [...(node.then ?? []), ...(node.otherwise ?? [])]) {
+      markScope(child, attribute);
+    }
+    return;
+  }
+
+  for (const child of node.children ?? []) markScope(child, attribute);
+}
+
 function loadComponent(name, ast, sourcePath, resolver, seen) {
   const specifier = ast.components[name];
 

package/core/compiler/scopeStyles.js

@@ -0,0 +1,151 @@
+// Scoped styles: a component's CSS applies to that component's markup
+// and nothing else.
+//
+// The mechanism is the one most frameworks settled on, because it needs
+// no runtime: every element the component owns gets an attribute, and
+// every selector in its <style> block is rewritten to require that
+// attribute. The result is plain CSS a browser can parse — no shadow
+// DOM, no class-name mangling, nothing to ship.
+//
+// This file has no Node built-ins on purpose: it runs in the browser
+// playground like the rest of the compiler.
+
+// A short, stable id from the component's path. Not cryptographic — it
+// only has to be stable across builds and unlikely to collide between
+// the files of one project.
+export function scopeId(path) {
+  let hash = 0;
+
+  for (let i = 0; i < path.length; i++) {
+    hash = (hash * 31 + path.charCodeAt(i)) | 0;
+  }
+
+  return `a${(hash >>> 0).toString(36).slice(0, 6)}`;
+}
+
+export const scopeAttribute = (id) => `data-azox-${id}`;
+
+// At-rules whose body is more CSS, so the selectors inside them need
+// rewriting too — a rule in a @media block still belongs to the
+// component.
+const NESTED_AT_RULES = /^@(media|supports|container|layer)\b/;
+
+// At-rules that contain no selectors. @keyframes names its steps `from`
+// and `50%`, and scoping those would break the animation.
+const OPAQUE_AT_RULES =
+  /^@(keyframes|-\w+-keyframes|font-face|import|charset|namespace|property)\b/;
+
+/**
+ * Rewrites every selector in `css` to require the scope attribute.
+ *
+ *   .title { … }        →  .title[data-azox-a1b2c3] { … }
+ *   .a, .b { … }        →  .a[data-azox-a1b2c3], .b[data-azox-a1b2c3] { … }
+ *   :global(.x) { … }   →  .x { … }
+ */
+export function scopeCss(css, id) {
+  return rewriteBlock(css, `[${scopeAttribute(id)}]`);
+}
+
+function rewriteBlock(css, attr) {
+  let out = '';
+  let i = 0;
+
+  while (i < css.length) {
+    const open = css.indexOf('{', i);
+
+    // Trailing text with no rule after it: a stray comment, or nothing.
+    if (open === -1) {
+      out += css.slice(i);
+      break;
+    }
+
+    const prelude = css.slice(i, open);
+    const close = matchingBrace(css, open);
+    const body = css.slice(open + 1, close);
+    const trimmed = prelude.trim();
+
+    if (OPAQUE_AT_RULES.test(trimmed)) {
+      // Kept whole: its body is not selectors.
+      out += `${prelude}{${body}}`;
+    } else if (NESTED_AT_RULES.test(trimmed)) {
+      // The condition stays; what is inside it is scoped.
+      out += `${prelude}{${rewriteBlock(body, attr)}}`;
+    } else {
+      out += `${scopeSelectorList(prelude, attr)}{${body}}`;
+    }
+
+    i = close + 1;
+  }
+
+  return out;
+}
+
+// Finds the brace closing the one at `open`, so a @media body is taken
+// whole rather than cut at its first inner rule.
+function matchingBrace(css, open) {
+  let depth = 0;
+
+  for (let i = open; i < css.length; i++) {
+    if (css[i] === '{') depth++;
+    else if (css[i] === '}' && --depth === 0) return i;
+  }
+
+  return css.length;
+}
+
+// A placeholder for a comment while the selector list is split on
+// commas. Printable on purpose: a control character would be invisible
+// in any output that quotes this source.
+const COMMENT_MARK = (n) => `/*__azox${n}__*/`;
+
+function scopeSelectorList(prelude, attr) {
+  // Comments carry no selectors and may contain commas.
+  const comments = [];
+  const stripped = prelude.replace(/\/\*[\s\S]*?\*\//g, (comment) => {
+    comments.push(comment);
+    return COMMENT_MARK(comments.length - 1);
+  });
+
+  const scoped = stripped
+    .split(',')
+    .map((selector) => scopeSelector(selector, attr))
+    .join(',');
+
+  return scoped.replace(/\/\*__azox(\d+)__\*\//g, (_, n) => comments[Number(n)]);
+}
+
+function scopeSelector(selector, attr) {
+  const trimmed = selector.trim();
+  if (!trimmed) return selector;
+
+  // An escape hatch for the times a component must reach outside
+  // itself — a body class, or markup it renders into a portal.
+  const global = trimmed.match(/^:global\(([\s\S]*)\)$/);
+  if (global) return selector.replace(trimmed, global[1].trim());
+
+  const leading = selector.slice(0, selector.length - selector.trimStart().length);
+  const trailing = selector.slice(selector.trimEnd().length);
+
+  // The attribute goes on the last compound of the selector, so
+  // `.card .title` scopes the element actually being styled rather than
+  // its ancestor. Combinators are left where they are.
+  const parts = trimmed.split(/(\s+|\s*[>+~]\s*)/);
+
+  for (let i = parts.length - 1; i >= 0; i--) {
+    if (!parts[i].trim() || /^[>+~\s]+$/.test(parts[i])) continue;
+    parts[i] = attachAttribute(parts[i], attr);
+    break;
+  }
+
+  return leading + parts.join('') + trailing;
+}
+
+// Placed before any pseudo-element or pseudo-class: `.a[attr]:hover` is
+// what was meant, and `.a:hover[attr]` would not match a browser's
+// reading of it.
+function attachAttribute(compound, attr) {
+  const pseudo = compound.search(/::?[a-z-]/i);
+  if (pseudo === -1) return compound + attr;
+
+  return compound.slice(0, pseudo) + attr + compound.slice(pseudo);
+}

package/core/index.d.ts

@@ -0,0 +1,43 @@
+// Types for `azoxjs`.
+//
+// The whole reactivity surface, plus the compiler and renderer, so this
+// entry point and `azoxjs/reactivity` offer the same thing.
+
+export {
+  signal,
+  effect,
+  computed,
+  dispose,
+  untracked,
+  onMount,
+  onCleanup,
+  adopt,
+  type Signal,
+  type ReadonlySignal,
+  type EffectHandle,
+  type AdoptCursor,
+} from './reactivity/signal.js';
+
+export { parseAzox, compileToModule } from './compiler/index.js';
+
+// Imported as well as re-exported: a type-only re-export names the type
+// for consumers but does not put it in scope here, and renderToHtml
+// below refers to it.
+import type { AzoxAst } from './compiler/index.js';
+export type { AzoxAst, CompileOptions } from './compiler/index.js';
+
+/**
+ * Renders a parsed file to HTML, evaluating its expressions once.
+ *
+ * `scope` holds the bindings the markup reads. `modules` carries what
+ * the file's imports brought in, which the build resolves.
+ */
+export declare function renderToHtml(
+  ast: AzoxAst,
+  scope: Record<string, unknown>,
+  modules?: Record<string, unknown>
+): string;
+
+/** The version this copy of Azox reports. */
+export declare const VERSION: string;
+export declare const TAGLINE: string;

package/core/index.js

@@ -11,6 +11,7 @@ export {
   untracked,
   onMount,
   onCleanup,
+  adopt,
 } from './reactivity/signal.js';
 export { parseAzox } from './compiler/parser.js';
 export { compileToModule } from './compiler/compileToJs.js';

package/core/reactivity/signal.d.ts

@@ -0,0 +1,106 @@
+// Types for `azoxjs/reactivity`.
+//
+// Written by hand rather than generated: the runtime carries no JSDoc,
+// so `tsc --declaration` produces `signal(initialValue: any)`, which
+// type-checks nothing. These describe what the implementation actually
+// guarantees.
+
+/**
+ * A reactive value. Call it to read — and, inside an `effect`, to
+ * subscribe to it.
+ */
+export interface Signal<T> {
+  (): T;
+
+  /**
+   * Replaces the value, or derives it from the current one.
+   *
+   * Setting a value equal to the current one (`===`) notifies nobody.
+   *
+   * A function is treated as an updater, so a signal *holding* a
+   * function cannot be replaced by passing it directly — pass
+   * `() => theFunction` instead.
+   */
+  set(next: T | ((previous: T) => T)): void;
+
+  /** Reads without subscribing, even inside an effect. */
+  peek(): T;
+}
+
+/** A read-only reactive value. `computed` returns one of these. */
+export interface ReadonlySignal<T> {
+  (): T;
+  peek(): T;
+}
+
+/**
+ * The handle `effect` returns. Its only public use is `dispose`; its
+ * internals are not part of the API and may change.
+ */
+export interface EffectHandle {
+  (): void;
+}
+
+/** Creates a reactive value. */
+export declare function signal<T>(initialValue: T): Signal<T>;
+
+/**
+ * Runs `fn` now, and again whenever a signal it read changes.
+ *
+ * Effects created while another is running belong to it, and are
+ * disposed with it. Use `untracked` to opt out of that ownership.
+ */
+export declare function effect(fn: () => void): EffectHandle;
+
+/**
+ * A value derived from other signals, recomputed when they change.
+ *
+ * Read-only by design. The runtime object does carry `set`, but the
+ * deriving effect overwrites whatever you assign on its next run, so
+ * it is not offered here.
+ */
+export declare function computed<T>(fn: () => T): ReadonlySignal<T>;
+
+/**
+ * Runs `fn` with no effect considered active, so anything it creates
+ * is owned by nobody and survives the caller re-running.
+ */
+export declare function untracked<T>(fn: () => T): T;
+
+/** Stops an effect and everything it created. Ignores null. */
+export declare function dispose(handle: EffectHandle | null | undefined): void;
+
+/**
+ * Runs once the DOM this scope built is in the document.
+ *
+ * A function returned from `fn` becomes the scope's cleanup, so setup
+ * and teardown can stay together.
+ */
+export declare function onMount(fn: () => void | (() => void)): void;
+
+/**
+ * Registers work to undo when the surrounding scope goes away: a row
+ * leaving a keyed list, or a branch of an `<if>` no longer taken.
+ *
+ * Called outside any scope it does nothing, which is the case at the
+ * top level of a page — nothing ever removes it.
+ */
+export declare function onCleanup(fn: () => void): void;
+
+/** A cursor over server-rendered nodes, used by hydration. */
+export interface AdoptCursor {
+  /**
+   * The next node if it matches — a tag name, null for text, or
+   * '#comment' for a control-flow marker.
+   */
+  next(expect: string | null): Node | null;
+  /** Removes anything the module did not claim. */
+  done(): void;
+}
+
+/**
+ * Walks a parent's existing children so hydration can bind to them
+ * rather than replacing them. Returns a cursor that yields null on any
+ * mismatch, at which point the caller creates the node instead.
+ */
+export declare function adopt(parent: Node | null): AdoptCursor;

package/core/reactivity/signal.js

@@ -181,3 +181,64 @@ export function computed(fn) {
   effect(() => derived.set(fn()));
   return derived;
 }
+
+/* ---------- hydration ---------- */
+
+// A cursor over server-rendered nodes, so hydration can bind to what is
+// already on the page instead of replacing it. Replacing destroys the
+// reader's focus, caret and anything they had expanded.
+//
+// `next` returns the node the compiled module expected, or null when the
+// markup does not match — a stale cache, an edited page, a host without
+// a walkable DOM. The module then creates that node as it always did, so
+// a mismatch costs the work we already do rather than a broken page.
+export function adopt(parent) {
+  // A minimal DOM stub — the compiler's own tests use one — has no
+  // childNodes to walk. Creating is then the only option.
+  if (!parent || typeof parent !== 'object' || !parent.firstChild) {
+    return { next: () => null, done: () => {} };
+  }
+
+  // Snapshotted rather than walked through `nextSibling`. The caller
+  // appends each node it adopts, and appending a node that is already a
+  // child detaches and re-attaches it — which rewrites `nextSibling` for
+  // whatever preceded it. A lazy walk therefore ends up pointing at a
+  // node it already handed out, and the sweep below deletes the live
+  // page. Measured: every child adopted in the right order, and every
+  // one removed a moment later. The list is fixed before any of that can
+  // happen, so reordering cannot move the cursor.
+  const kids = [];
+  for (let child = parent.firstChild; child; child = child.nextSibling) kids.push(child);
+  let i = 0;
+
+  return {
+    // `expect` is a tag name for an element, null for a text node, or
+    // '#comment' for one of the markers a control-flow block anchors on.
+    // A block's markers are the nodes it later inserts and removes
+    // against, so adopting the region between them means adopting the
+    // pair itself first.
+    next(expect) {
+      const current = kids[i];
+      if (!current) return null;
+
+      const type = current.nodeType;
+      const matches =
+        expect === null
+          ? type === 3
+          : expect === '#comment'
+            ? type === 8
+            : type !== 3 && type !== 8 && current.nodeName?.toLowerCase() === expect;
+
+      if (!matches) return null;
+
+      i++;
+      return current;
+    },
+
+    // Anything the server sent that the module did not claim is stale
+    // and has to go, or it would linger below the adopted nodes.
+    done() {
+      for (; i < kids.length; i++) kids[i].remove?.();
+    },
+  };
+}

package/core/renderer/renderToHtml.js

@@ -102,7 +102,7 @@ function renderScope(node, scope, modules = {}) {
 // so the body sees it the same way the compiled version does.
 function renderEach(node, scope, outer, modules = {}) {
   const items = evalExpr(node.expr, scope);
-  if (items === null || items === undefined) return '';
+  if (items === null || items === undefined) return wrapBlock('');
 
   if (typeof items[Symbol.iterator] !== 'function') {
     throw new BuildError(
@@ -121,12 +121,23 @@ function renderEach(node, scope, outer, modules = {}) {
     index++;
   }
 
-  return html;
+  return wrapBlock(html);
 }
 
 function renderIf(node, scope, outer, modules = {}) {
   const branch = evalExpr(node.expr, scope) ? node.then : node.otherwise;
-  return branch.map((child) => renderNode(child, scope, outer, modules)).join('');
+  const inner = branch.map((child) => renderNode(child, scope, outer, modules)).join('');
+
+  return wrapBlock(inner);
+}
+
+// The same start/end pair the compiler builds, so hydration can adopt
+// the server's nodes instead of discarding them. Labelled, because an
+// empty comment cannot be told apart from its neighbour.
+//
+// See docs/hydration.md.
+function wrapBlock(html) {
+  return `<!--[-->${html}<!--]-->`;
 }
 
 // Reads an attribute expression. A bound one names a signal, so it is

package/core/renderer/serverScope.js

@@ -44,18 +44,25 @@ export function serverOnCleanup() {}
 export function declaredNames(script) {
   const names = new Set();
 
-  for (const match of script.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g)) {
+  // Only what the script declares at its top level. A name declared
+  // inside a callback — `const timer` within onMount, say — is a local
+  // of that function, so returning it from the outer scope throws
+  // "timer is not defined" and takes the whole page down.
+  const topLevel = topLevelSource(script);
+
+  for (const match of topLevel.matchAll(/(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=/g)) {
     names.add(match[1]);
   }
-  for (const match of script.matchAll(/function\s+([A-Za-z_$][\w$]*)\s*\(/g)) {
+  for (const match of topLevel.matchAll(/function\s+([A-Za-z_$][\w$]*)\s*\(/g)) {
     names.add(match[1]);
   }
-  for (const match of script.matchAll(/class\s+([A-Za-z_$][\w$]*)/g)) {
+  for (const match of topLevel.matchAll(/class\s+([A-Za-z_$][\w$]*)/g)) {
     names.add(match[1]);
   }
 
   // Destructured declarations: const { a, b: c, d = 1 } = …
-  for (const match of script.matchAll(/(?:const|let|var)\s*\{([^}]*)\}\s*=/g)) {
+  //
+  for (const match of topLevel.matchAll(/(?:const|let|var)\s*\{([^}]*)\}\s*=/g)) {
     for (const part of match[1].split(',')) {
       const name = part.split(':').pop().split('=')[0].trim();
       if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
@@ -65,6 +72,97 @@ export function declaredNames(script) {
   return [...names];
 }
 
+// Blanks out everything nested inside braces, brackets or parentheses,
+// leaving the top-level text with its offsets intact — so a declaration
+// inside a function body is no longer visible to the patterns above.
+//
+// Strings, template literals and comments are blanked too: a brace in
+// one of them would otherwise throw the depth count off.
+function topLevelSource(script) {
+  let out = '';
+  let depth = 0;
+  let i = 0;
+
+  while (i < script.length) {
+    const c = script[i];
+    const next = script[i + 1];
+
+    // Comments.
+    if (c === '/' && next === '/') {
+      const end = script.indexOf('\n', i);
+      const stop = end === -1 ? script.length : end;
+      out += ' '.repeat(stop - i);
+      i = stop;
+      continue;
+    }
+    if (c === '/' && next === '*') {
+      const end = script.indexOf('*/', i + 2);
+      const stop = end === -1 ? script.length : end + 2;
+      out += ' '.repeat(stop - i);
+      i = stop;
+      continue;
+    }
+
+    // Strings and template literals: skipped whole, so braces inside
+    // them do not count. A template's ${...} is skipped with it, which
+    // is fine — nothing is declared at the top level in there.
+    if (c === '"' || c === "'" || c === '`') {
+      const quote = c;
+      let j = i + 1;
+      while (j < script.length) {
+        if (script[j] === '\\') j += 2;
+        else if (script[j] === quote) break;
+        else j++;
+      }
+      const stop = Math.min(j + 1, script.length);
+      out += ' '.repeat(stop - i);
+      i = stop;
+      continue;
+    }
+
+    // The delimiter itself is kept when it opens at the top level, so
+    // `function f(` and `const { a } =` still match; what is nested
+    // inside is blanked.
+    //
+    // The exception is a destructuring pattern — `const { a, b } = …` —
+    // whose names are the thing being declared, so its contents are
+    // kept even though they sit one level in.
+    if (c === '{' || c === '(' || c === '[') {
+      const destructuring = c === '{' && depth === 0 && /(?:const|let|var)\s*$/.test(out);
+
+      out += depth === 0 ? c : ' ';
+      depth++;
+
+      if (destructuring) {
+        const close = script.indexOf('}', i + 1);
+        if (close !== -1) {
+          out += script.slice(i + 1, close + 1);
+          depth--;
+          i = close + 1;
+          continue;
+        }
+      }
+
+      i++;
+      continue;
+    }
+
+    if (c === '}' || c === ')' || c === ']') {
+      depth = Math.max(0, depth - 1);
+      out += depth === 0 ? c : ' ';
+      i++;
+      continue;
+    }
+
+    // Newlines are kept at any depth so line-anchored patterns still
+    // behave; everything else nested is blanked.
+    out += depth === 0 || c === '\n' ? c : ' ';
+    i++;
+  }
+
+  return out;
+}
+
 // Evaluates a script body and returns its declarations. `params` and
 // `args` pass a component's props in as arguments.
 //