@async/framework 0.11.22 → 0.11.23

package/browser.ts

@@ -2043,10 +2043,11 @@ const __componentModule = (() => {
   const { createLazyRegistry, isLazyDescriptor } = __lazyRegistryModule;
   const componentKind = Symbol.for("@async/framework.component");
   let componentCounter = 0;
+  let defineComponentWarned = false;
 
-  function defineComponent(fn) {
+  function component(fn) {
     if (typeof fn !== "function") {
-      throw new TypeError("defineComponent(fn) requires a function.");
+      throw new TypeError("component(fn) requires a function.");
     }
     Object.defineProperty(fn, componentKind, {
       configurable: true,
@@ -2055,7 +2056,13 @@ const __componentModule = (() => {
     return fn;
   }
 
-  const component = defineComponent;
+  function defineComponent(fn) {
+    if (!defineComponentWarned) {
+      defineComponentWarned = true;
+      console.warn?.("defineComponent(...) is deprecated. Use component(...) instead.");
+    }
+    return component(fn);
+  }
 
   function createComponentRegistry(initialMap = {}, options = {}) {
     const registryStore = options.registry ?? createRegistryStore();
@@ -2254,10 +2261,11 @@ const __componentModule = (() => {
   }
 
   function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, intersectionHooks, destroyHooks, renderScopedTemplate }) {
-    const { signals, handlers, loader, server, router, cache, scheduler } = runtime;
+    const { signals, handlers, loader, server, router, cache, components, scheduler } = runtime;
     const generatedHandlers = new WeakMap();
     let generatedHandlerCounter = 0;
     let generatedSignalCounter = 0;
+    let generatedSlotCounter = 0;
     const context = {
       scope,
       signals,
@@ -2266,6 +2274,7 @@ const __componentModule = (() => {
       server,
       router,
       cache,
+      components,
       scheduler,
 
       signal(name, initial) {
@@ -2345,6 +2354,38 @@ const __componentModule = (() => {
         return rawHtml(child.html);
       },
 
+      slot(Child, propsOrFn = {}) {
+        let target;
+        let latestProps = {};
+        const renderSlot = () => {
+          if (!target) {
+            return;
+          }
+          loader.mount(target, Child, latestProps);
+        };
+        const attach = registerScopedHandler(`slot.${++generatedSlotCounter}.attach`, function ({ element }) {
+          target = element;
+          renderSlot();
+          return () => {
+            target = undefined;
+          };
+        });
+        const cleanup = signals.effect(() => {
+          latestProps = typeof propsOrFn === "function" ? propsOrFn.call(context) : propsOrFn;
+          renderSlot();
+        }, {
+          scheduler,
+          phase: "effect",
+          scope,
+          key: `slot:${generatedSlotCounter}`
+        });
+        cleanups.push(cleanup);
+        return {
+          attach,
+          render: renderSlot
+        };
+      },
+
       suspense(signalRef, views) {
         const id = signalRef?.id;
         if (!id) {
@@ -2464,7 +2505,7 @@ const __componentModule = (() => {
   function componentName(Component) {
     return Component.displayName || Component.name || "anonymous";
   }
-  return { defineComponent, createComponentRegistry, isComponent, renderComponent, component };
+  return { component, defineComponent, createComponentRegistry, isComponent, renderComponent };
 })();
 
 const __serverModule = (() => {
@@ -3521,7 +3562,7 @@ const __loaderModule = (() => {
   const { matchAttribute, normalizeAttributeConfig, readAttribute } = __attributesModule;
   const inlineBindingPrefix = "__async:inline:";
 
-  function Loader({ root, signals, handlers, server, router, cache, attributes, scheduler } = {}) {
+  function Loader({ root, signals, handlers, server, router, cache, components, attributes, scheduler } = {}) {
     const documentRef = root?.ownerDocument ?? root ?? globalThis.document;
     const rootNode = root ?? documentRef;
     const signalRegistry = signals ?? createSignalRegistry();
@@ -3537,6 +3578,7 @@ const __loaderModule = (() => {
     const intersectionBindings = new WeakMap();
     const boundaryState = new WeakMap();
     const renderingBoundaries = new WeakSet();
+    const componentBindings = new WeakSet();
     const inlineBindings = new Map();
     const scopedCleanups = new WeakMap();
     let inlineBindingCounter = 0;
@@ -3549,6 +3591,7 @@ const __loaderModule = (() => {
       server,
       router,
       cache,
+      components,
       scheduler: schedulerInstance,
       attributes: attributeConfig,
 
@@ -3565,6 +3608,7 @@ const __loaderModule = (() => {
         bindClassAttributes(rootOrFragment);
         bindEventAttributes(rootOrFragment);
         bindBoundaries(rootOrFragment);
+        bindComponentAttributes(rootOrFragment);
         runPseudoEvents(rootOrFragment);
         return api;
       },
@@ -3590,6 +3634,7 @@ const __loaderModule = (() => {
           server: api.server,
           router: api.router,
           cache: api.cache,
+          components: api.components,
           scheduler: schedulerInstance,
           attributes: attributeConfig
         });
@@ -3884,6 +3929,32 @@ const __loaderModule = (() => {
       }
     }
 
+    function bindComponentAttributes(scope) {
+      for (const element of elementsIn(scope)) {
+        const id = readAttribute(element, attributeConfig, "async", "component");
+        if (id == null) {
+          continue;
+        }
+        if (componentBindings.has(element)) {
+          continue;
+        }
+        if (!components?.resolve) {
+          throw new Error(`Component "${id}" cannot be mounted because no component registry is available.`);
+        }
+        const Component = components.resolve(id);
+        if (!Component) {
+          throw new Error(`Component "${id}" was not found.`);
+        }
+        componentBindings.add(element);
+        try {
+          api.mount(element, Component);
+        } catch (error) {
+          componentBindings.delete(element);
+          throw error;
+        }
+      }
+    }
+
     function renderBoundary(boundary) {
       const state = boundaryState.get(boundary);
       if (!state) {
@@ -5263,9 +5334,12 @@ const __appModule = (() => {
     const registry = createRegistryStore(undefined, { target: "browser" });
     const runtimes = new Set();
     const createRuntime = options.createRuntime ?? createApp;
+    const loaderFacade = createLoaderFacade();
+    let currentRuntime;
 
     const app = {
       registry,
+      loader: loaderFacade,
 
       use(typeOrModule, entries) {
         const normalized = normalizeUse(typeOrModule, entries);
@@ -5282,7 +5356,7 @@ const __appModule = (() => {
 
       start(options = {}) {
         const runtime = createRuntime(app, options).start();
-        app.runtime = runtime;
+        setCurrentRuntime(runtime);
         return runtime;
       },
 
@@ -5291,12 +5365,12 @@ const __appModule = (() => {
       },
 
       detachRoot(root) {
-        return app.runtime?.detachRoot(root) ?? app;
+        return currentRuntime?.detachRoot(root) ?? app;
       },
 
       applySnapshot(snapshot, snapshotOptions = {}) {
-        if (app.runtime) {
-          app.runtime.applySnapshot(snapshot, snapshotOptions);
+        if (currentRuntime) {
+          currentRuntime.applySnapshot(snapshot, snapshotOptions);
           return app;
         }
         appendSnapshotDeclarations(registry, snapshot, snapshotOptions);
@@ -5304,7 +5378,11 @@ const __appModule = (() => {
       },
 
       inspectRoots() {
-        return app.runtime?.inspectRoots() ?? { count: 0, roots: [] };
+        return currentRuntime?.inspectRoots() ?? { count: 0, roots: [] };
+      },
+
+      inspectRuntime() {
+        return inspectRuntimeState(currentRuntime, loaderFacade);
       },
 
       _attach(runtime) {
@@ -5314,14 +5392,36 @@ const __appModule = (() => {
 
       _detach(runtime) {
         runtimes.delete(runtime);
+        if (currentRuntime === runtime) {
+          currentRuntime = latestRuntime(runtimes);
+        }
       }
     };
 
+    Object.defineProperties(app, {
+      _runtime: {
+        get() {
+          return currentRuntime;
+        }
+      },
+      _setRuntime: {
+        value(runtime) {
+          setCurrentRuntime(runtime);
+        }
+      }
+    });
+
     if (initial) {
       app.use(initial);
     }
 
     return app;
+
+    function setCurrentRuntime(runtime) {
+      if (runtime) {
+        currentRuntime = runtime;
+      }
+    }
   }
 
   function createApp(appOrDefinition = Async, options = {}) {
@@ -5384,6 +5484,7 @@ const __appModule = (() => {
           return runtime;
         }
         started = true;
+        app._setRuntime?.(runtime);
 
         if (target !== "server") {
           configureServerContext({ cache: browserCache });
@@ -5393,6 +5494,7 @@ const __appModule = (() => {
             registerRootLoader(loader.root, loader);
             loader.start();
             startRouterFor(loader.root);
+            app.loader._setCurrent(runtime.loader);
           } else if (startupRoot != null) {
             runtime.attachRoot(startupRoot);
           }
@@ -5429,6 +5531,7 @@ const __appModule = (() => {
               handlers,
               server,
               cache: browserCache,
+              components,
               scheduler,
               attributes
             });
@@ -5437,6 +5540,7 @@ const __appModule = (() => {
         configureServerContext({ cache: browserCache });
         signals._setContext?.({ server, loader: runtime.loader, cache: browserCache, scheduler });
         startRouterFor(root);
+        app.loader._setCurrent(runtime.loader);
         return runtime;
       },
 
@@ -5446,6 +5550,7 @@ const __appModule = (() => {
           return runtime;
         }
         if (root == null) {
+          const detachedLoaders = [...new Set(rootLoaders.values())];
           for (const rootLoader of new Set(rootLoaders.values())) {
             rootLoader.destroy?.();
           }
@@ -5456,6 +5561,7 @@ const __appModule = (() => {
           loader = undefined;
           runtime.loader = undefined;
           runtime.router = undefined;
+          app.loader._clearCurrent(detachedLoaders);
           return runtime;
         }
         const rootLoader = rootLoaders.get(root);
@@ -5474,6 +5580,9 @@ const __appModule = (() => {
           runtime.router = undefined;
           if (next) {
             startRouterFor(next.root);
+            app.loader._setCurrent(next);
+          } else {
+            app.loader._clearCurrent(rootLoader);
           }
         }
         return runtime;
@@ -5561,6 +5670,8 @@ const __appModule = (() => {
         if (loader && !destroyedLoaders.has(loader)) {
           loader?.destroy?.();
         }
+        app.loader._clearCurrent([...destroyedLoaders, loader]);
+        app.loader._rejectPending(new Error("Async loader queue was cleared because the runtime was destroyed."));
         signals.destroy?.();
         if (ownsScheduler) {
           scheduler.destroy();
@@ -5572,6 +5683,22 @@ const __appModule = (() => {
       }
     };
 
+    Object.defineProperties(runtime, {
+      _inspect: {
+        value() {
+          return {
+            active: !destroyed,
+            started,
+            destroyed,
+            target,
+            roots: runtime.inspectRoots(),
+            loader: app.loader.inspect(),
+            router: Boolean(runtime.router)
+          };
+        }
+      }
+    });
+
     server.cache = serverCache;
     runtime.server.cache = serverCache;
     runtime.applySnapshot(initialSnapshot, { strict: options.strictSnapshots ?? true });
@@ -5648,6 +5775,107 @@ const __appModule = (() => {
 
   const Async = defineApp();
 
+  function createLoaderFacade() {
+    let current;
+    const pending = [];
+    const readyWaiters = [];
+
+    const facade = {
+      get current() {
+        return current;
+      },
+
+      ready() {
+        if (current) {
+          return Promise.resolve(current);
+        }
+        return new Promise((resolve, reject) => {
+          readyWaiters.push({ resolve, reject });
+        });
+      },
+
+      scan(rootOrFragment) {
+        return enqueue("scan", [rootOrFragment]);
+      },
+
+      swap(boundaryId, fragmentOrTemplate) {
+        return enqueue("swap", [boundaryId, fragmentOrTemplate]);
+      },
+
+      mount(target, Component, props) {
+        return enqueue("mount", [target, Component, props]);
+      },
+
+      inspect() {
+        return {
+          ready: Boolean(current),
+          pending: pending.length,
+          root: current?.root
+        };
+      }
+    };
+
+    Object.defineProperties(facade, {
+      _setCurrent: {
+        value(loader) {
+          if (!loader) {
+            return;
+          }
+          current = loader;
+          while (readyWaiters.length > 0) {
+            readyWaiters.shift().resolve(loader);
+          }
+          flushPending(loader);
+        }
+      },
+      _clearCurrent: {
+        value(loaderOrLoaders) {
+          if (loaderOrLoaders === undefined) {
+            current = undefined;
+            return;
+          }
+          const loaders = Array.isArray(loaderOrLoaders) ? loaderOrLoaders : [loaderOrLoaders];
+          if (loaders.includes(current)) {
+            current = undefined;
+          }
+        }
+      },
+      _rejectPending: {
+        value(error) {
+          while (pending.length > 0) {
+            pending.shift().reject(error);
+          }
+          while (readyWaiters.length > 0) {
+            readyWaiters.shift().reject(error);
+          }
+        }
+      }
+    });
+
+    return facade;
+
+    function enqueue(method, args) {
+      if (current) {
+        return invoke(current, method, args);
+      }
+      return new Promise((resolve, reject) => {
+        pending.push({ method, args, resolve, reject });
+      });
+    }
+
+    function flushPending(loader) {
+      while (pending.length > 0) {
+        const operation = pending.shift();
+        invoke(loader, operation.method, operation.args)
+          .then(operation.resolve, operation.reject);
+      }
+    }
+
+    async function invoke(loader, method, args) {
+      return loader[method](...args);
+    }
+  }
+
   function readSnapshot(root = globalThis.document, { attributes } = {}) {
     const attributeConfig = normalizeAttributeConfig(attributes);
     const snapshotAttr = attributeName(attributeConfig, "async", "snapshot");
@@ -5798,10 +6026,33 @@ const __appModule = (() => {
   }
 
   function ensureRuntime(app) {
-    if (!app.runtime) {
+    if (!app._runtime) {
       app.start();
     }
-    return app.runtime;
+    return app._runtime;
+  }
+
+  function latestRuntime(runtimes) {
+    let latest;
+    for (const runtime of runtimes) {
+      latest = runtime;
+    }
+    return latest;
+  }
+
+  function inspectRuntimeState(runtime, loaderFacade) {
+    if (runtime?._inspect) {
+      return runtime._inspect();
+    }
+    return {
+      active: Boolean(runtime),
+      started: Boolean(runtime),
+      destroyed: false,
+      target: runtime?.target,
+      roots: runtime?.inspectRoots?.() ?? { count: 0, roots: [] },
+      loader: loaderFacade.inspect(),
+      router: Boolean(runtime?.router)
+    };
   }
 
   function applySnapshotToRuntime(runtime, snapshot = {}, options = {}) {
@@ -6582,7 +6833,7 @@ const __boundaryReceiverModule = (() => {
     if (options.receiver && typeof options.receiver.apply === "function") {
       return options.receiver;
     }
-    const runtime = options.runtime ?? globalThis.Async?.runtime;
+    const runtime = options.runtime ?? globalThis.Async?._runtime;
     const loader = options.loader ?? runtime?.loader;
     if (!loader) {
       throw new TypeError("AsyncStream requires receiver, loader, or runtime.loader.");
@@ -7179,7 +7430,7 @@ const __elementsModule = (() => {
         if (this.__asyncAttached) {
           return;
         }
-        const runtime = app.runtime ?? app.start?.();
+        const runtime = app._runtime ?? app.start?.();
         runtime?.attachRoot?.(this);
         this.__asyncRuntime = runtime;
         this.__asyncAttached = true;