npm - azoxjs - Versions diffs - 0.2.0 → 1.0.0 - Mend

azoxjs 0.2.0 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.md +125 -6
package/core/build.js +261 -14
package/core/commands/compile.js +5 -1
package/core/commands/create.js +1 -2
package/core/commands/dev.js +10 -1
package/core/compiler/compileToJs.js +256 -19
package/core/compiler/parser.js +33 -2
package/core/compiler/resolveComponents.js +22 -7
package/core/dev/watcher.js +12 -1
package/core/index.js +12 -1
package/core/reactivity/signal.js +101 -1
package/core/renderer/renderToHtml.js +27 -2
package/core/renderer/serverScope.js +29 -3
package/core/routes.js +44 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -11,8 +11,11 @@ third-party CLI dependencies, no borrowed syntax from React, Vue, or
 Next.js. It compiles `.azox` components directly into fine-grained,
 signal-driven DOM updates.
-> Status: early development (v0.2.0). APIs are unstable and will
-> change without notice until v1.0.
+> Status: stable (v1.0.0). The template syntax, the reactivity exports
+> and the shape of the build output will not change without a 2.0. What
+> Azox does **not** do is listed in
+> [Limitations](https://azox.dev/docs/limitations) — those are stopping
+> points, not bugs.
 ## Why Azox
@@ -65,6 +68,46 @@ pages/blog/first-post.azox  →  /blog/first-post
 Build one page with `azox compile --page=blog/first-post`, or by its
 URL: `azox compile --page=/blog/first-post`.
+### Dynamic routes
+A bracketed segment in a filename is a parameter, and the file becomes
+a template that builds one page per entry it declares:
+```html
+<!-- pages/blog/[slug].azox -->
+<script>
+  import posts from '../../posts.json' with { type: 'json' };
+  // Which pages to build.
+  routes(posts.map((p) => ({ slug: p.slug })));
+  // The parameters of the page being built.
+  const { slug } = params();
+  const post = posts.find((p) => p.slug === slug);
+</script>
+<article>
+  <h1>{post.title}</h1>
+  <p>{post.body}</p>
+</article>
+```
+```
+posts.json with two entries  →  /blog/hello
+                             →  /blog/second
+```
+`routes()` takes an array of objects, one per page, each supplying
+every parameter the filename asks for. A filename may hold several
+(`pages/[lang]/[slug].azox`), and `params()` returns them all.
+Both are build-time declarations: neither reaches the browser. The
+parameters for each page are compiled into its module as a constant.
+A missing `routes()` call, an entry missing a parameter, a value
+containing a `/`, and two entries producing the same URL are all
+reported as build errors rather than producing a broken site.
 ## Components
 A component is a `.azox` file that declares what it accepts and
@@ -147,6 +190,75 @@ There is still no component instance at runtime: the compiler wraps
 each use in its own JavaScript scope, which is ordinary scoping
 rather than a framework construct.
+## Lifecycle
+`onMount` runs once the DOM is in the document; `onCleanup` runs when
+the scope goes away.
+```html
+<script>
+  import { signal, onMount, onCleanup } from 'azox/reactivity';
+  const width = signal(0);
+  let box;
+  onMount(() => {
+    // The nodes exist now, so they can be measured.
+    const onResize = () => width.set(box.clientWidth);
+    onResize();
+    window.addEventListener('resize', onResize);
+    // Returned from onMount, so it is the cleanup for this setup.
+    return () => window.removeEventListener('resize', onResize);
+  });
+  onCleanup(() => console.log('gone'));
+</script>
+<div>{width()}px</div>
+```
+A scope goes away when a row leaves a keyed list, or when an `<if>`
+takes the other branch. At the top level of a page nothing ever removes
+it, so `onCleanup` there never runs — that is a page living as long as
+the document, not a failure.
+## Layouts and the document head
+A component can carry a `<head>` block, so one shared component holds
+the stylesheet, fonts and scripts every page needs:
+```html
+<!-- components/Shell.azox -->
+<head>
+  <link rel="stylesheet" href="/style.css" />
+</head>
+<div class="shell">
+  <header>My site</header>
+  <slot />
+</div>
+```
+```html
+<!-- pages/index.azox -->
+<head>
+  <title>Home — my site</title>
+</head>
+<script>
+  import Shell from '../components/Shell.azox';
+</script>
+<Shell><main>Just this page's content.</main></Shell>
+```
+Blocks are merged with the component's first, so the page has the last
+word. Identical lines are emitted once, and a component used twice
+contributes once. A `<title>` or `<meta name="…">` set by the page
+replaces the component's rather than joining it — a document may hold
+only one of each — so a layout's title is a default, not a conflict.
 ## Loops and conditionals
 Control flow is expressed as tags, so it nests inside markup like
@@ -254,10 +366,17 @@ npm run build
 ```
 The build lands in `.azox/build/` as a self-contained static bundle —
-an `index.html` per route, a compiled hydration module beside it, and
-one shared copy of the runtime. No dev machinery is included. Serve
-that directory with any static host and it works with no install
-step and no rewrite configuration.
+an `index.html` per route, a compiled hydration module beside it where
+one is needed, and one shared copy of the runtime. No dev machinery is
+included. Serve that directory with any static host and it works with
+no install step and no rewrite configuration.
+A page with no bindings and no listeners ships **no JavaScript at
+all**: it arrives complete from the build, so the document references
+no module and none is written. An expression that reads only
+build-time constants — a version from `package.json`, say — is folded
+into the markup rather than wrapped in an effect, which is often what
+decides whether a page needs a module in the first place.
 ## CLI

package/core/build.js CHANGED Viewed

@@ -17,12 +17,12 @@ import { createRequire } from 'node:module';
 import { parseAzox } from './compiler/parser.js';
 import { resolveComponents } from './compiler/resolveComponents.js';
-import { compileToModule } from './compiler/compileToJs.js';
+import { compileToModule, STATIC_MARKER } from './compiler/compileToJs.js';
 import { renderToHtml } from './renderer/renderToHtml.js';
 import { parseImports } from './renderer/moduleBindings.js';
 import { evaluateScript } from './renderer/serverScope.js';
 import { escapeHtml } from './compiler/html.js';
-import { collectRoutes, findRoute } from './routes.js';
+import { collectRoutes, findRoute, resolveRoute, PAGE_EXTENSION } from './routes.js';
 import { createNodeResolver } from './nodeResolver.js';
 import { ROOT_DIR } from './meta.js';
 import { BuildError } from './buildError.js';
@@ -68,7 +68,11 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
   // SSR pass: render initial markup without touching browser DOM APIs.
   let html;
   try {
-    html = renderToHtml(ast, buildServerScope(ast.script, inlineModules), inlineModules);
+    html = renderToHtml(
+      ast,
+      buildServerScope(ast.script, inlineModules, route.params),
+      inlineModules
+    );
   } catch (error) {
     if (!(error instanceof BuildError)) throw error;
     throw new BuildError(`in ${PAGES_DIR}/${name}.azox: ${error.message}`);
@@ -97,12 +101,24 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
       rewriteImports: (script, from = sourcePath) =>
         rebaseImports(script, dirname(from), clientPath),
       inlineModules,
+      routeParams: route.params ?? null,
     }),
     runtimeSpecifier
   );
   assertValidJavaScript(clientModule, name);
-  writeFileSync(clientPath, clientModule, 'utf8');
+  // A page with no bindings and no listeners does nothing on load, so
+  // the document does not reference its module — and without a reference
+  // there is no reason to write it. The page still arrives complete,
+  // because the markup was rendered during the build.
+  const isStatic = clientModule.includes(STATIC_MARKER);
+  if (isStatic) {
+    // A previous build may have left one behind.
+    if (existsSync(clientPath)) rmSync(clientPath);
+  } else {
+    writeFileSync(clientPath, clientModule, 'utf8');
+  }
   // One runtime at the build root, shared by every page.
   const runtimePath = resolve(buildRoot, RUNTIME_FILENAME);
@@ -113,8 +129,14 @@ export function buildRoute(projectDir, route, { transformHtml } = {}) {
     copyFileSync(resolve(ROOT_DIR, 'core/router/navigate.js'), resolve(buildRoot, ROUTER_FILENAME));
   }
-  let document = wrapDocument(html, projectTitle(projectDir), ast.head, {
+  // A component's <head> block is merged in behind the page's own, so
+  // a layout can carry the stylesheet and fonts every page needs while
+  // the page keeps the last word on its title and description.
+  const head = mergeHeads(ast.head, ast.componentHeads ?? []);
+  let document = wrapDocument(html, projectTitle(projectDir), head, {
     routerSrc: router ? `${route.assetPrefix}${ROUTER_FILENAME}` : null,
+    clientSrc: isStatic ? null : './page.client.js',
   });
   if (transformHtml) document = transformHtml(document);
@@ -133,13 +155,142 @@ export function buildAll(projectDir, options) {
     );
   }
-  const results = routes.map((route) => buildRoute(projectDir, route, options));
+  const results = expandTemplates(routes).map((route) =>
+    buildRoute(projectDir, route, options)
+  );
   const assets = copyPublicAssets(projectDir);
   removeStaleOutput(projectDir, results, assets);
   return results;
 }
+// Turns each template into the concrete routes it declares, leaving
+// ordinary pages as they are. A template stands in for however many
+// pages its routes() call names, and is never written at its own url.
+function expandTemplates(routes) {
+  const expanded = [];
+  const seen = new Map();
+  for (const route of routes) {
+    if (!route.isTemplate) {
+      expanded.push(route);
+      continue;
+    }
+    for (const values of discoverRoutes(route)) {
+      const resolved = resolveRoute(route, values);
+      // Two entries producing the same url would have one silently
+      // overwrite the other, leaving a page missing with no sign of it.
+      const clash = seen.get(resolved.url);
+      if (clash) {
+        throw new BuildError(
+          `${relative(process.cwd(), route.sourcePath)} declares ${resolved.url} twice — ` +
+            `route parameters must be unique`
+        );
+      }
+      seen.set(resolved.url, route);
+      expanded.push(resolved);
+    }
+  }
+  return expanded;
+}
+// Runs a template's <script> with `routes` bound to a collector, so
+// the page declares its own pages from whatever data it imports.
+//
+// The script runs twice per page in total — once here to discover the
+// list, then once per page to render it. That is the cost of letting
+// the declaration be ordinary JavaScript rather than a separate
+// manifest the author has to keep in step.
+function discoverRoutes(route) {
+  const source = readFileSync(route.sourcePath, 'utf8');
+  const parsed = parseAzox(source);
+  const where = `${PAGES_DIR}/${route.name}${PAGE_EXTENSION}`;
+  if (!/\broutes\s*\(/.test(parsed.script)) {
+    throw new BuildError(
+      `in ${where}: a page with a [parameter] in its name must declare its pages — ` +
+        `add routes([...]) to its <script> block, for example ` +
+        `routes(posts.map((p) => ({ ${route.paramNames[0]}: p.${route.paramNames[0]} })))`
+    );
+  }
+  const collected = [];
+  const body = parsed.script.replace(/^\s*import\s.+?;?\s*$/gm, '');
+  try {
+    evaluateScript(
+      body,
+      [],
+      [],
+      loadModules(parsed.script, route.sourcePath),
+      {
+        routes: (list) => {
+          collected.push(...normaliseRouteList(list, where, route.paramNames));
+          return list;
+        },
+        // Discovery happens before any page exists, so params() has
+        // nothing to report yet. Returning an empty object lets a
+        // script that destructures it run without a special case.
+        params: () => ({}),
+      }
+    );
+  } catch (error) {
+    if (error instanceof BuildError) throw error;
+    throw new BuildError(`in ${where}: failed to work out which pages to build: ${error.message}`);
+  }
+  if (!collected.length) {
+    throw new BuildError(
+      `in ${where}: routes() was called with nothing, so no pages would be built. ` +
+        `If the list can be empty, that is fine — but the build has nothing to write.`
+    );
+  }
+  return collected;
+}
+// Each entry must supply every parameter the filename asks for. A
+// missing one would otherwise land in a url as "undefined".
+function normaliseRouteList(list, where, names) {
+  if (!Array.isArray(list)) {
+    throw new BuildError(
+      `in ${where}: routes() needs an array of objects — got ${typeof list}`
+    );
+  }
+  return list.map((entry, index) => {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+      throw new BuildError(
+        `in ${where}: routes() entry ${index} must be an object like { ${names[0]}: 'value' }`
+      );
+    }
+    for (const name of names) {
+      const value = entry[name];
+      if (value === undefined || value === null || value === '') {
+        throw new BuildError(
+          `in ${where}: routes() entry ${index} is missing "${name}", ` +
+            `which the filename asks for`
+        );
+      }
+      if (String(value).includes('/')) {
+        throw new BuildError(
+          `in ${where}: routes() entry ${index} has "${name}" set to "${value}", ` +
+            `which contains a "/" — a parameter fills one url segment`
+        );
+      }
+    }
+    return entry;
+  });
+}
 // Deletes output belonging to pages that no longer exist. Without
 // this, deleting a page leaves its built copy behind and a deployed
 // site keeps serving it.
@@ -217,13 +368,28 @@ export function copyPublicAssets(projectDir) {
 // Builds a single page by route name or URL.
 export function buildPage(projectDir, pageName, options) {
-  const route = findRoute(listRoutes(projectDir), pageName);
+  const routes = listRoutes(projectDir);
+  const route = findRoute(routes, pageName);
-  if (!route) {
-    throw new BuildError(`page "${PAGES_DIR}/${pageName}.azox" not found in ${projectDir}`);
+  // A template cannot be built at its own url, so naming it builds
+  // every page it declares — which is what the author means by
+  // `azox compile --page=blog/[slug]`.
+  if (route?.isTemplate) {
+    return expandTemplates([route]).map((page) => buildRoute(projectDir, page, options));
   }
-  return buildRoute(projectDir, route, options);
+  if (route) return buildRoute(projectDir, route, options);
+  // Not a file, so it may be one of the pages a template declares.
+  // Expanding them is the only way to know.
+  const generated = findRoute(
+    expandTemplates(routes.filter((candidate) => candidate.isTemplate)),
+    pageName
+  );
+  if (generated) return buildRoute(projectDir, generated, options);
+  throw new BuildError(`page "${PAGES_DIR}/${pageName}.azox" not found in ${projectDir}`);
 }
 // Rewrites the bare specifier a page's own <script> uses to the same
@@ -300,14 +466,21 @@ function projectTitle(projectDir) {
 // evaluate the expressions the template references. The script is
 // trusted project source, not user input — the same assumption any
 // template engine's SSR step makes.
-function buildServerScope(script, modules = {}) {
+function buildServerScope(script, modules = {}, params = null) {
   // Strip imports: the server supplies its own primitives rather than
   // loading the real reactive runtime, and anything else a script
   // imports was resolved by loadModules and is passed in.
   const body = script.replace(/^\s*import\s.+?;?\s*$/gm, '');
+  // A dynamic page reads its own parameters through params(), and its
+  // routes() call has already been answered by discovery — calling it
+  // again here would collect the list a second time to no purpose.
+  const extras = params
+    ? { params: () => params, routes: (list) => list }
+    : {};
   try {
-    return evaluateScript(body, [], [], modules);
+    return evaluateScript(body, [], [], modules, extras);
   } catch (error) {
     if (error instanceof BuildError) throw error;
     throw new BuildError(`failed to evaluate the page's <script> block: ${error.message}`);
@@ -350,6 +523,11 @@ function loadModules(script, sourcePath, componentImports = []) {
     let loaded;
     try {
+      // require caches by resolved path, which is wrong for a build
+      // that runs repeatedly in one process: `azox dev` would keep
+      // serving the data as it was when the server started, so editing
+      // a post changed nothing. Dropping the entry re-reads the file.
+      delete require.cache[require.resolve(specifier)];
       loaded = require(specifier);
     } catch (error) {
       throw new BuildError(`cannot import '${specifier}': ${error.message.split('\n')[0]}`);
@@ -366,9 +544,78 @@ function loadModules(script, sourcePath, componentImports = []) {
 // The client module sits next to the page's index.html, so the src is
 // the same for every route regardless of how deep it is.
+// Combines the <head> blocks a page and its components contributed.
+//
+// Components come first so the page can override them: a <title> or a
+// <meta name="description"> set by a layout is a sensible default, and
+// the page that knows its own subject should win. Identical lines are
+// emitted once, so a layout and a page both asking for the same
+// stylesheet do not produce it twice.
+function mergeHeads(pageHead, componentHeads) {
+  const seen = new Set();
+  const lines = [];
+  // A page's <title> and description replace a component's rather than
+  // appearing alongside: two titles in one document is invalid.
+  const pageTags = uniqueHeadTags(pageHead);
+  for (const block of [...componentHeads, pageHead]) {
+    for (const line of (block ?? '').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const key = normaliseHeadLine(trimmed);
+      if (seen.has(key)) continue;
+      // Dropped in favour of the page's own.
+      const tag = uniqueTagName(trimmed);
+      if (tag && block !== pageHead && pageTags.has(tag)) continue;
+      seen.add(key);
+      lines.push(trimmed);
+    }
+  }
+  return lines.join('\n');
+}
+// Tags a document may only hold one of, so a component's must give way
+// to the page's. Keyed by tag name, plus the `name` of a <meta> — two
+// different meta tags are fine, two descriptions are not.
+function uniqueTagName(line) {
+  const title = /^<title[\s>]/i.test(line);
+  if (title) return 'title';
+  const meta = line.match(/^<meta\s[^>]*name=["']([^"']+)["']/i);
+  if (meta) return `meta:${meta[1].toLowerCase()}`;
+  return null;
+}
+function uniqueHeadTags(head) {
+  const names = new Set();
+  for (const line of (head ?? '').split('\n')) {
+    const tag = uniqueTagName(line.trim());
+    if (tag) names.add(tag);
+  }
+  return names;
+}
+// Whitespace inside a tag should not make two identical links differ.
+function normaliseHeadLine(line) {
+  return line.replace(/\s+/g, ' ');
+}
 // A page's own <head> block wins over the fallback title, so a page
 // can set its own <title>, stylesheets and meta tags.
-function wrapDocument(bodyHtml, title, head = '', { routerSrc = null } = {}) {
+function wrapDocument(
+  bodyHtml,
+  title,
+  head = '',
+  { routerSrc = null, clientSrc = './page.client.js' } = {}
+) {
   const hasOwnTitle = /<title>/i.test(head);
   // The router is loaded after the page's own module, so a page is
@@ -385,7 +632,7 @@ function wrapDocument(bodyHtml, title, head = '', { routerSrc = null } = {}) {
 ${hasOwnTitle ? '' : `  <title>${escapeHtml(title)}</title>\n`}${head ? indent(head) + '\n' : ''}</head>
 <body>
 <div data-azox-root>${bodyHtml}</div>
-<script type="module" src="./page.client.js"></script>${router}
+${clientSrc ? `<script type="module" src="${clientSrc}"></script>` : ''}${router}
 </body>
 </html>
 `;

package/core/commands/compile.js CHANGED Viewed

@@ -15,7 +15,11 @@ export function compileCommand({ flags }) {
   const projectDir = process.cwd();
   try {
-    const results = flags.page ? [buildPage(projectDir, flags.page)] : buildAll(projectDir);
+    // Naming a [parameter] template builds every page it declares, so
+    // buildPage may answer with more than one.
+    const results = flags.page
+      ? [buildPage(projectDir, flags.page)].flat()
+      : buildAll(projectDir);
     console.log(BANNER);
     console.log('');

package/core/commands/create.js CHANGED Viewed

@@ -119,8 +119,7 @@ function starterPage(name) {
   </ul>
   <input
-    value={draft()}
-    on:input={(e) => draft.set(e.target.value)}
+    bind:value={draft}
     placeholder="Add a task"
   />
   <button on:click={() => {

package/core/commands/dev.js CHANGED Viewed

@@ -82,11 +82,20 @@ export async function devCommand({ flags }) {
     // public/ holds stylesheets, fonts and images; any of them
     // changing is worth a reload.
     { dir: resolve(projectDir, PUBLIC_DIR), filter: () => true },
+    // A page can import a .json file for its content, and a dynamic
+    // route builds its pages from one. Editing the data has to rebuild
+    // or the new entry never appears. Not recursive: the project root
+    // also holds the build output, and watching that rebuilds forever.
+    {
+      dir: projectDir,
+      filter: (name) => name.endsWith('.json') && !name.includes('package-lock'),
+      recursive: false,
+    },
   ];
   const stoppers = watched
     .filter(({ dir }) => existsSync(dir))
-    .map(({ dir, filter }) => watchDirectory(dir, onChange, { filter }));
+    .map(({ dir, filter, recursive }) => watchDirectory(dir, onChange, { filter, recursive }));
   const stopWatching = () => {
     for (const stop of stoppers) stop();