@async/framework 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "No-build AsyncLoader app runtime with signals, command events, server calls, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
   "packageManager": "pnpm@11.1.0",
@@ -28,19 +28,21 @@
     "web-framework"
   ],
   "license": "MIT",
-  "unpkg": "./src/index.js",
+  "unpkg": "./framework.js",
   "exports": {
     ".": {
-      "unpkg": "./src/index.js",
-      "browser": "./src/index.js",
+      "unpkg": "./framework.js",
+      "browser": "./framework.js",
       "import": "./src/index.js",
       "default": "./src/index.js"
     },
+    "./framework.js": "./framework.js",
     "./package.json": "./package.json"
   },
   "files": [
     "CHANGELOG.md",
     "README.md",
+    "framework.js",
     "src",
     "examples",
     "LICENSE",
@@ -48,10 +50,12 @@
   ],
   "scripts": {
     "async-pipeline": "async-pipeline",
+    "bundle": "node scripts/build-framework-bundle.js",
+    "bundle:check": "node scripts/build-framework-bundle.js --check",
     "docs:build": "node scripts/build-pages.js",
     "examples": "node --test tests/examples.test.js",
     "examples:check": "node --test tests/examples.test.js",
-    "pack:check": "npm pack --dry-run --ignore-scripts",
+    "pack:check": "pnpm run bundle:check && npm pack --dry-run --ignore-scripts",
     "pipeline:github:check": "async-pipeline github check",
     "pipeline:github:generate": "async-pipeline github generate",
     "pipeline:pages": "async-pipeline run pages",

package/src/async-signal.js

@@ -82,7 +82,18 @@ export function asyncSignal(id, fn) {
         signals: registry,
         id: registeredId,
         get server() {
-          return registry._context?.().server;
+          const context = registry._context?.() ?? {};
+          const server = context.server;
+          if (typeof server?._withContext === "function") {
+            return server._withContext({
+              signals: registry,
+              router: context.router,
+              loader: context.loader,
+              cache: context.cache,
+              abort: activeAbort
+            });
+          }
+          return server;
         },
         get router() {
           return registry._context?.().router;

package/src/attributes.js

@@ -1,5 +1,6 @@
 const defaultPrefixes = Object.freeze({
   async: ["async:"],
+  class: ["class:"],
   signal: ["signal:"],
   on: ["on:"]
 });
@@ -11,6 +12,7 @@ export function defineAttributeConfig(config = {}) {
 export function normalizeAttributeConfig(config = {}) {
   return {
     async: normalizePrefixes(config.async, defaultPrefixes.async),
+    class: normalizePrefixes(config.class, defaultPrefixes.class),
     signal: normalizePrefixes(config.signal, defaultPrefixes.signal),
     on: normalizePrefixes(config.on, defaultPrefixes.on)
   };

package/src/cache.js

@@ -34,6 +34,11 @@ export function createCacheRegistry(initialMap = {}, { now = () => Date.now(), r
       return registryApi;
     },
 
+    unregister(id) {
+      assertId(id);
+      return definitions.delete(id);
+    },
+
     resolve(id) {
       assertId(id);
       return definitions.get(id);

package/src/component.js

@@ -1,4 +1,5 @@
-import { rawHtml, renderTemplate } from "./html.js";
+import { attributeName } from "./attributes.js";
+import { escapeHtml, rawHtml, renderTemplate } from "./html.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
 const componentKind = Symbol.for("@async/framework.component");
@@ -44,6 +45,13 @@ export function createComponentRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(id) {
+      if (typeof id !== "string" || id.length === 0) {
+        throw new TypeError("Component id must be a non-empty string.");
+      }
+      return entries.delete(id);
+    },
+
     resolve(id) {
       if (typeof id !== "string" || id.length === 0) {
         throw new TypeError("Component id must be a non-empty string.");
@@ -71,29 +79,49 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
 
   const scope = `${parentScope}.${componentName(Component)}.${++componentCounter}`;
   const cleanups = [];
-  const mountHooks = [];
+  const attachHooks = [];
   const visibleHooks = [];
+  const destroyHooks = [];
+  const bindingIds = [];
+  const templateOptions = {
+    attributes: runtime.attributes,
+    signals: runtime.signals,
+    bind(value) {
+      const id = runtime.loader?._registerBinding?.(value);
+      if (!id) {
+        throw new Error("Inline template bindings require an AsyncLoader.");
+      }
+      bindingIds.push(id);
+      return id;
+    }
+  };
+  const renderScopedTemplate = (value) => renderTemplate(value, templateOptions);
   const context = createComponentContext({
     runtime,
     scope,
     cleanups,
-    mountHooks,
-    visibleHooks
+    attachHooks,
+    visibleHooks,
+    destroyHooks,
+    renderScopedTemplate
   });
 
   const output = Component.call(context, props);
-  const html = renderTemplate(output);
+  const html = renderScopedTemplate(output);
 
   return {
     html,
-    mount(target) {
-      for (const hook of mountHooks) {
+    attach(target) {
+      for (const hook of attachHooks) {
         const cleanup = hook(target);
         if (typeof cleanup === "function") {
           cleanups.push(cleanup);
         }
       }
     },
+    mount(target) {
+      this.attach(target);
+    },
     visible(target, observeVisible) {
       for (const hook of visibleHooks) {
         const cleanup = observeVisible(target, hook);
@@ -103,15 +131,24 @@ export function renderComponent(Component, props = {}, runtime, parentScope = "c
       }
     },
     cleanup() {
+      while (destroyHooks.length > 0) {
+        destroyHooks.pop()?.();
+      }
       while (cleanups.length > 0) {
         cleanups.pop()?.();
       }
+      while (bindingIds.length > 0) {
+        runtime.loader?._releaseBinding?.(bindingIds.pop());
+      }
     }
   };
 }
 
-function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleHooks }) {
+function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, destroyHooks, renderScopedTemplate }) {
   const { signals, handlers, loader, server, router, cache } = runtime;
+  const generatedHandlers = new WeakMap();
+  let generatedHandlerCounter = 0;
+  let generatedSignalCounter = 0;
   const context = {
     scope,
     signals,
@@ -122,12 +159,28 @@ function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleH
     cache,
 
     signal(name, initial) {
-      return signals.ensure(scoped(scope, name), initial);
+      if (arguments.length === 1) {
+        const id = scoped(scope, `signal.${++generatedSignalCounter}`);
+        const ref = signals.ensure(id, name);
+        cleanups.push(() => signals.unregister?.(id));
+        return ref;
+      }
+      const id = scoped(scope, name);
+      const created = !signals.has(id);
+      const ref = signals.ensure(id, initial);
+      if (created) {
+        cleanups.push(() => signals.unregister?.(id));
+      }
+      return ref;
     },
 
     computed(name, fn) {
       const id = scoped(scope, name);
+      const created = !signals.has(id);
       const ref = signals.ensure(id, undefined);
+      if (created) {
+        cleanups.push(() => signals.unregister?.(id));
+      }
       const cleanup = signals.effect(() => {
         signals.set(id, fn.call(context));
       });
@@ -137,9 +190,13 @@ function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleH
 
     asyncSignal(name, fn) {
       const id = scoped(scope, name);
+      const created = !signals.has(id);
       if (!signals.has(id)) {
         signals.asyncSignal(id, fn);
       }
+      if (created) {
+        cleanups.push(() => signals.unregister?.(id));
+      }
       return signals.ref(id);
     },
 
@@ -150,31 +207,91 @@ function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleH
     },
 
     handler(name, fn) {
-      const id = scoped(scope, name);
-      handlers.register(id, function runComponentHandler(handlerContext) {
-        return fn.call({ ...context, ...handlerContext }, handlerContext);
-      });
-      return id;
+      if (typeof name === "function" && fn === undefined) {
+        const inlineFn = name;
+        if (generatedHandlers.has(inlineFn)) {
+          return generatedHandlers.get(inlineFn);
+        }
+        const id = registerScopedHandler(`handler.${++generatedHandlerCounter}`, inlineFn);
+        generatedHandlers.set(inlineFn, id);
+        return id;
+      }
+      if (typeof fn !== "function") {
+        throw new TypeError("this.handler(name, fn) or this.handler(fn) requires a function.");
+      }
+      return registerScopedHandler(name, fn);
     },
 
     render(Child, childProps = {}) {
       const child = renderComponent(Child, childProps, runtime, scope);
       cleanups.push(child.cleanup);
-      mountHooks.push((target) => child.mount(target));
+      attachHooks.push((target) => child.attach(target));
       visibleHooks.push((target) => child.visible(target, loader._observeVisible));
       return rawHtml(child.html);
     },
 
+    suspense(signalRef, views) {
+      const id = signalRef?.id;
+      if (!id) {
+        throw new TypeError("this.suspense(signalRef, views) requires a signal ref.");
+      }
+
+      const normalized = normalizeSuspenseViews(views);
+      const chunks = [];
+      for (const state of ["loading", "ready", "error"]) {
+        const view = normalized[state];
+        if (!view) {
+          continue;
+        }
+        const attr = attributeName(runtime.attributes, "async", state);
+        const body = renderScopedTemplate(view.call(context, signalRef));
+        chunks.push(`<template ${attr}="${escapeHtml(id)}">${body}</template>`);
+      }
+      return rawHtml(chunks.join(""));
+    },
+
+    on(eventName, fn) {
+      if (typeof eventName !== "string" || eventName.length === 0) {
+        throw new TypeError("Component lifecycle event must be a non-empty string.");
+      }
+      if (typeof fn !== "function") {
+        throw new TypeError(`Component lifecycle "${eventName}" requires a function.`);
+      }
+      const event = eventName === "mount" ? "attach" : eventName;
+      if (event === "attach") {
+        attachHooks.push((target) => fn.call(context, target));
+        return;
+      }
+      if (event === "visible") {
+        visibleHooks.push((target) => fn.call(context, target));
+        return;
+      }
+      if (event === "destroy") {
+        destroyHooks.push(() => fn.call(context));
+        return;
+      }
+      throw new Error(`Unsupported component lifecycle event "${eventName}".`);
+    },
+
     onMount(fn) {
-      mountHooks.push((target) => fn.call(context, target));
+      context.on("attach", fn);
     },
 
     onVisible(fn) {
-      visibleHooks.push((target) => fn.call(context, target));
+      context.on("visible", fn);
     }
   };
 
   return context;
+
+  function registerScopedHandler(name, fn) {
+    const id = scoped(scope, name);
+    handlers.register(id, function runComponentHandler(handlerContext) {
+      return fn.call({ ...context, ...handlerContext }, handlerContext);
+    });
+    cleanups.push(() => handlers.unregister?.(id));
+    return id;
+  }
 }
 
 function scoped(scope, name) {
@@ -184,6 +301,21 @@ function scoped(scope, name) {
   return `${scope}.${name}`;
 }
 
+function normalizeSuspenseViews(views) {
+  const normalized = typeof views === "function" ? { ready: views } : views;
+  if (!normalized || typeof normalized !== "object" || Array.isArray(normalized)) {
+    throw new TypeError("this.suspense(signalRef, views) requires views to be a function or object.");
+  }
+
+  for (const state of ["loading", "ready", "error"]) {
+    if (Object.hasOwn(normalized, state) && normalized[state] !== undefined && typeof normalized[state] !== "function") {
+      throw new TypeError(`this.suspense(signalRef, views) view "${state}" must be a function.`);
+    }
+  }
+
+  return normalized;
+}
+
 function componentName(Component) {
   return Component.displayName || Component.name || "anonymous";
 }

package/src/handlers.js

@@ -6,11 +6,10 @@ import {
 } from "./server.js";
 import { attachRegistryInspection, createRegistryStore } from "./registry-store.js";
 
-const builtInTokens = new Set(["preventDefault", "stopPropagation", "stopImmediatePropagation"]);
+const builtInTokens = new Set(["prevent", "preventDefault", "stopPropagation", "stopImmediatePropagation"]);
 const builtInHandlers = {
-  preventDefault() {
-    this.event?.preventDefault?.();
-  },
+  prevent: preventDefault,
+  preventDefault,
   stopPropagation() {
     this.event?.stopPropagation?.();
   },
@@ -19,6 +18,10 @@ const builtInHandlers = {
   }
 };
 
+function preventDefault() {
+  this.event?.preventDefault?.();
+}
+
 export function createHandlerRegistry(initialMap = {}, options = {}) {
   const registryStore = options.registry ?? createRegistryStore();
   const type = options.type ?? "handler";
@@ -44,6 +47,11 @@ export function createHandlerRegistry(initialMap = {}, options = {}) {
       return registry;
     },
 
+    unregister(id) {
+      assertId(id);
+      return handlers.delete(id);
+    },
+
     resolve(id) {
       assertId(id);
       return handlers.get(id);

package/src/html.js

@@ -1,4 +1,5 @@
 import { isSignalRef } from "./signals.js";
+import { attributeName, matchAttribute, normalizeAttributeConfig } from "./attributes.js";
 
 const templateKind = Symbol.for("@async/framework.template");
 const rawKind = Symbol.for("@async/framework.rawHtml");
@@ -22,29 +23,36 @@ export function rawHtml(value) {
   };
 }
 
-export function renderTemplate(value) {
+export function renderTemplate(value, options = {}) {
   if (isTemplateResult(value)) {
+    const context = createRenderContext(options);
     let output = "";
     for (let index = 0; index < value.strings.length; index += 1) {
       output += value.strings[index];
       if (index < value.values.length) {
-        output += renderValue(value.values[index]);
+        output += renderValue(value.values[index], {
+          ...context,
+          attribute: readAttributeContext(value.strings[index])
+        });
       }
     }
     return output;
   }
-  return renderValue(value);
+  return renderValue(value, createRenderContext(options));
 }
 
-function renderValue(value) {
+function renderValue(value, context = createRenderContext()) {
   if (value?.[rawKind]) {
     return value.html;
   }
   if (isTemplateResult(value)) {
-    return renderTemplate(value);
+    return renderTemplate(value, context);
+  }
+  if (context.attribute) {
+    return renderAttributeValue(value, context);
   }
   if (Array.isArray(value)) {
-    return value.map(renderValue).join("");
+    return value.map((item) => renderValue(item, context)).join("");
   }
   if (isSignalRef(value)) {
     return escapeHtml(value.value);
@@ -55,6 +63,91 @@ function renderValue(value) {
   return escapeHtml(value);
 }
 
+function renderAttributeValue(value, context) {
+  const signalName = matchAttribute(context.attribute.name, context.attributes, "signal");
+  const className = matchAttribute(context.attribute.name, context.attributes, "class");
+  const signalPath = signalPathFor(value, context);
+
+  if (context.attribute.name === "value" && signalPath) {
+    const currentValue = readSignalValue(value, context);
+    const signalValueAttribute = attributeName(context.attributes, "signal", "value");
+    return `${escapeHtml(currentValue)}${context.attribute.quote} ${signalValueAttribute}=${context.attribute.quote}${escapeHtml(signalPath)}`;
+  }
+
+  if (signalName != null || className != null) {
+    if (signalPath) {
+      return escapeHtml(signalPath);
+    }
+    if (isInlineBindingValue(value)) {
+      return escapeHtml(registerInlineBinding(value, context));
+    }
+  }
+
+  return renderValueAsAttributeLiteral(value, context);
+}
+
+function renderValueAsAttributeLiteral(value, context) {
+  if (Array.isArray(value)) {
+    return value.map((item) => renderValueAsAttributeLiteral(item, context)).join("");
+  }
+  if (isSignalRef(value)) {
+    return escapeHtml(value.value);
+  }
+  if (value == null || value === false) {
+    return "";
+  }
+  return escapeHtml(value);
+}
+
+function createRenderContext(options = {}) {
+  return {
+    ...options,
+    attributes: normalizeAttributeConfig(options.attributes)
+  };
+}
+
+function readAttributeContext(source) {
+  const match = source.match(/(?:^|[\s<])([^\s"'=<>`]+)\s*=\s*(["'])$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    name: match[1],
+    quote: match[2]
+  };
+}
+
+function signalPathFor(value, context) {
+  if (isSignalRef(value)) {
+    return value.id;
+  }
+  if (typeof value === "string" && context.signals?.has?.(value)) {
+    return value;
+  }
+  return null;
+}
+
+function readSignalValue(value, context) {
+  if (isSignalRef(value)) {
+    return value.value;
+  }
+  if (typeof value === "string" && context.signals?.has?.(value)) {
+    return context.signals.get(value);
+  }
+  return value;
+}
+
+function isInlineBindingValue(value) {
+  return Boolean(value && typeof value === "object");
+}
+
+function registerInlineBinding(value, context) {
+  if (typeof context.bind !== "function") {
+    return value;
+  }
+  return context.bind(value);
+}
+
 export function escapeHtml(value) {
   return String(value)
     .replaceAll("&", "&amp;")