@async/framework 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@async/framework",
-  "version": "0.3.0",
+  "version": "0.4.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/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/component.js

@@ -71,29 +71,46 @@ 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 context = createComponentContext({
     runtime,
     scope,
     cleanups,
-    mountHooks,
-    visibleHooks
+    attachHooks,
+    visibleHooks,
+    destroyHooks
   });
 
   const output = Component.call(context, props);
-  const html = renderTemplate(output);
+  const html = renderTemplate(output, {
+    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;
+    }
+  });
 
   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 +120,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 }) {
   const { signals, handlers, loader, server, router, cache } = runtime;
+  const generatedHandlers = new WeakMap();
+  let generatedHandlerCounter = 0;
+  let generatedSignalCounter = 0;
   const context = {
     scope,
     signals,
@@ -122,6 +148,9 @@ function createComponentContext({ runtime, scope, cleanups, mountHooks, visibleH
     cache,
 
     signal(name, initial) {
+      if (arguments.length === 1) {
+        return signals.ensure(scoped(scope, `signal.${++generatedSignalCounter}`), name);
+      }
       return signals.ensure(scoped(scope, name), initial);
     },
 
@@ -150,31 +179,70 @@ 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);
     },
 
+    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);
+    });
+    return id;
+  }
 }
 
 function scoped(scope, name) {

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;")

package/src/loader.js

@@ -1,8 +1,10 @@
 import { renderComponent } from "./component.js";
 import { createHandlerRegistry } from "./handlers.js";
-import { createSignalRegistry } from "./signals.js";
+import { createSignalRegistry, isSignalRef } from "./signals.js";
 import { matchAttribute, normalizeAttributeConfig, readAttribute } from "./attributes.js";
 
+const inlineBindingPrefix = "__async:inline:";
+
 export function AsyncLoader({ root, signals, handlers, server, router, cache, attributes } = {}) {
   const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
   const rootNode = root ?? documentRef;
@@ -16,6 +18,8 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
   const visibleElements = new WeakSet();
   const boundaryState = new WeakMap();
   const renderingBoundaries = new WeakSet();
+  const inlineBindings = new Map();
+  let inlineBindingCounter = 0;
   let destroyed = false;
 
   const api = {
@@ -36,6 +40,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
     scan(rootOrFragment = rootNode) {
       assertActive();
       bindSignalAttributes(rootOrFragment);
+      bindClassAttributes(rootOrFragment);
       bindEventAttributes(rootOrFragment);
       bindBoundaries(rootOrFragment);
       runPseudoEvents(rootOrFragment);
@@ -85,6 +90,16 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
 
     _observeVisible(target, fn) {
       return observeVisible(target, fn);
+    },
+
+    _registerBinding(value) {
+      const id = `${inlineBindingPrefix}${++inlineBindingCounter}`;
+      inlineBindings.set(id, value);
+      return id;
+    },
+
+    _releaseBinding(id) {
+      inlineBindings.delete(id);
     }
   };
 
@@ -100,7 +115,7 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
         if (!eventName) {
           continue;
         }
-        if (eventName === "mount" || eventName === "visible") {
+        if (eventName === "attach" || eventName === "mount" || eventName === "visible") {
           continue;
         }
         bindEvent(element, eventName, element.getAttribute(name));
@@ -175,15 +190,62 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
         if (signalName.startsWith("class:")) {
           const className = signalName.slice("class:".length);
           const path = element.getAttribute(name);
-          bindSignal(element, `class:${className}:${path}`, path, (value) => {
-            element.classList.toggle(className, Boolean(value));
-          });
+          if (className === "" || className === "{}") {
+            bindClass(element, className, path);
+          } else {
+            bindSignal(element, `class:${className}:${path}`, path, (value) => {
+              element.classList.toggle(className, Boolean(value));
+            });
+          }
+          continue;
+        }
+        if (signalName === "class") {
+          const path = element.getAttribute(name);
+          bindClass(element, "{}", path);
         }
       }
     }
   }
 
-  function bindSignal(element, key, path, apply) {
+  function bindClassAttributes(scope) {
+    for (const element of elementsIn(scope)) {
+      for (const name of element.getAttributeNames?.() ?? []) {
+        const className = matchAttribute(name, attributeConfig, "class");
+        if (className == null) {
+          continue;
+        }
+        bindClass(element, className, element.getAttribute(name));
+      }
+    }
+  }
+
+  function bindClass(element, className, path) {
+    if (className === "" || className === "{}") {
+      const staticClasses = readClassTokens(element);
+      let previous = new Set();
+      bindSignal(element, `class:{}:${path}`, path, (value) => {
+        const next = normalizeClassTokens(value);
+        const current = readClassTokens(element);
+        for (const token of previous) {
+          if (!next.has(token) && !staticClasses.has(token)) {
+            current.delete(token);
+          }
+        }
+        for (const token of next) {
+          current.add(token);
+        }
+        writeClassTokens(element, current);
+        previous = next;
+      }, { rawInline: true });
+      return;
+    }
+
+    bindSignal(element, `class:${className}:${path}`, path, (value) => {
+      updateClassToken(element, className, Boolean(value));
+    });
+  }
+
+  function bindSignal(element, key, path, apply, options = {}) {
     const bound = signalBindings.get(element) ?? new Set();
     if (bound.has(key)) {
       return;
@@ -191,8 +253,9 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
     bound.add(key);
     signalBindings.set(element, bound);
 
-    apply(signalRegistry.get(path));
-    cleanups.add(signalRegistry.subscribe(path, apply));
+    const read = () => readBinding(path, options);
+    apply(read());
+    cleanups.add(subscribeBinding(path, () => apply(read())));
   }
 
   function bindValueWriter(element, path) {
@@ -200,11 +263,42 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
     bindEvent(element, "change", `__async:set:${path}`);
     if (!handlerRegistry.resolve(`__async:set:${path}`)) {
       handlerRegistry.register(`__async:set:${path}`, function writeValue({ element }) {
-        signalRegistry.set(path, element.value);
+        writeBinding(path, element.value);
       });
     }
   }
 
+  function readBinding(path, options = {}) {
+    if (isInlineBinding(path)) {
+      const value = inlineBindings.get(path);
+      return options.rawInline ? value : resolveInlineValue(value);
+    }
+    return signalRegistry.get(path);
+  }
+
+  function writeBinding(path, value) {
+    if (!isInlineBinding(path)) {
+      return signalRegistry.set(path, value);
+    }
+    const binding = inlineBindings.get(path);
+    if (isSignalRef(binding)) {
+      return binding.set(value);
+    }
+    throw new Error(`Inline binding "${path}" is not writable.`);
+  }
+
+  function subscribeBinding(path, fn) {
+    if (!isInlineBinding(path)) {
+      return signalRegistry.subscribe(path, fn);
+    }
+    const cleanups = collectSignalRefs(inlineBindings.get(path)).map((ref) => ref.subscribe(fn));
+    return () => {
+      for (const cleanup of cleanups) {
+        cleanup();
+      }
+    };
+  }
+
   function bindBoundaries(scope) {
     for (const boundary of elementsIn(scope)) {
       if (renderingBoundaries.has(boundary)) {
@@ -252,15 +346,17 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
 
   function runPseudoEvents(scope) {
     for (const element of elementsIn(scope)) {
-      const ref = readAttribute(element, attributeConfig, "on", "mount");
-      if (ref == null) {
+      const refs = readPseudoRefs(element, ["attach", "mount"]);
+      if (refs.length === 0) {
         continue;
       }
       if (mountedElements.has(element)) {
         continue;
       }
       mountedElements.add(element);
-      runPseudo(element, ref);
+      for (const ref of refs) {
+        runPseudo(element, ref);
+      }
     }
 
     for (const element of elementsIn(scope)) {
@@ -276,6 +372,17 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
     }
   }
 
+  function readPseudoRefs(element, names) {
+    const refs = [];
+    for (const name of names) {
+      const ref = readAttribute(element, attributeConfig, "on", name);
+      if (ref != null) {
+        refs.push(ref);
+      }
+    }
+    return refs;
+  }
+
   async function runPseudo(element, ref) {
     try {
       const results = await handlerRegistry.run(ref, {
@@ -330,6 +437,110 @@ export function AsyncLoader({ root, signals, handlers, server, router, cache, at
   return api;
 }
 
+function normalizeClassTokens(value, tokens = new Set()) {
+  if (value == null || value === false) {
+    return tokens;
+  }
+  if (isSignalRef(value)) {
+    const signalValue = value.value;
+    if (signalValue === true) {
+      tokens.add(signalClassName(value.id));
+      return tokens;
+    }
+    return normalizeClassTokens(signalValue, tokens);
+  }
+  if (typeof value === "string") {
+    for (const token of value.split(/\s+/).filter(Boolean)) {
+      tokens.add(token);
+    }
+    return tokens;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      normalizeClassTokens(item, tokens);
+    }
+    return tokens;
+  }
+  if (typeof value === "object") {
+    for (const [token, enabled] of Object.entries(value)) {
+      const value = isSignalRef(enabled) ? enabled.value : enabled;
+      if (value) {
+        normalizeClassTokens(token, tokens);
+      }
+    }
+    return tokens;
+  }
+  if (value !== true) {
+    tokens.add(String(value));
+  }
+  return tokens;
+}
+
+function resolveInlineValue(value) {
+  if (isSignalRef(value)) {
+    return value.value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(resolveInlineValue);
+  }
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, resolveInlineValue(entry)]));
+  }
+  return value;
+}
+
+function collectSignalRefs(value, refs = new Map()) {
+  if (isSignalRef(value)) {
+    refs.set(value.id, value);
+    return [...refs.values()];
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectSignalRefs(item, refs);
+    }
+    return [...refs.values()];
+  }
+  if (value && typeof value === "object") {
+    for (const item of Object.values(value)) {
+      collectSignalRefs(item, refs);
+    }
+  }
+  return [...refs.values()];
+}
+
+function isInlineBinding(value) {
+  return typeof value === "string" && value.startsWith(inlineBindingPrefix);
+}
+
+function signalClassName(id) {
+  return id.split(".").at(-1);
+}
+
+function updateClassToken(element, className, enabled) {
+  const tokens = readClassTokens(element);
+  for (const token of normalizeClassTokens(className)) {
+    if (enabled) {
+      tokens.add(token);
+    } else {
+      tokens.delete(token);
+    }
+  }
+  writeClassTokens(element, tokens);
+}
+
+function readClassTokens(element) {
+  return normalizeClassTokens(element.getAttribute("class") ?? "");
+}
+
+function writeClassTokens(element, tokens) {
+  const value = [...tokens].join(" ");
+  if (value.length === 0) {
+    element.removeAttribute("class");
+    return;
+  }
+  element.setAttribute("class", value);
+}
+
 function collectBoundaryTemplates(boundary, id, attributeConfig) {
   const templates = {};
   for (const template of [...boundary.children].filter((child) => child.tagName === "TEMPLATE")) {