@async/framework 0.11.14 → 0.11.16

package/framework.ts

@@ -1164,6 +1164,7 @@ const __attributesModule = (() => {
     async: ["async:"],
     class: ["class:"],
     signal: ["signal:"],
+    intersect: ["intersect:"],
     on: ["on:"]
   });
 
@@ -1176,6 +1177,7 @@ const __attributesModule = (() => {
       async: normalizePrefixes(config.async, defaultPrefixes.async),
       class: normalizePrefixes(config.class, defaultPrefixes.class),
       signal: normalizePrefixes(config.signal, defaultPrefixes.signal),
+      intersect: normalizePrefixes(config.intersect, defaultPrefixes.intersect),
       on: normalizePrefixes(config.on, defaultPrefixes.on)
     };
   }
@@ -2141,6 +2143,7 @@ const __componentModule = (() => {
     const cleanups = [];
     const attachHooks = [];
     const visibleHooks = [];
+    const intersectionHooks = [];
     const destroyHooks = [];
     const bindingIds = [];
     const templateOptions = {
@@ -2162,6 +2165,7 @@ const __componentModule = (() => {
       cleanups,
       attachHooks,
       visibleHooks,
+      intersectionHooks,
       destroyHooks,
       renderScopedTemplate
     });
@@ -2213,6 +2217,15 @@ const __componentModule = (() => {
           cleanups.push(cleanup);
         }
       },
+      intersection(target, observeIntersection) {
+        if (intersectionHooks.length === 0) {
+          return;
+        }
+        for (let index = 0; index < intersectionHooks.length; index += 1) {
+          const hook = intersectionHooks[index];
+          hook(target, observeIntersection);
+        }
+      },
       cleanup() {
         while (destroyHooks.length > 0) {
           destroyHooks.pop()?.();
@@ -2242,7 +2255,7 @@ const __componentModule = (() => {
     }
   }
 
-  function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, destroyHooks, renderScopedTemplate }) {
+  function createComponentContext({ runtime, scope, cleanups, attachHooks, visibleHooks, intersectionHooks, destroyHooks, renderScopedTemplate }) {
     const { signals, handlers, loader, server, router, cache, scheduler } = runtime;
     const generatedHandlers = new WeakMap();
     let generatedHandlerCounter = 0;
@@ -2330,6 +2343,7 @@ const __componentModule = (() => {
         cleanups.push(child.cleanup);
         attachHooks.push((target) => child.attach(target));
         visibleHooks.push((target) => child.visible(target, loader._observeVisible));
+        intersectionHooks.push((target) => child.intersection(target, loader._observeIntersection));
         return rawHtml(child.html);
       },
 
@@ -2353,14 +2367,22 @@ const __componentModule = (() => {
         return rawHtml(chunks.join(""));
       },
 
-      on(eventName, fn) {
+      on(eventName, optionsOrFn, maybeFn) {
         if (typeof eventName !== "string" || eventName.length === 0) {
           throw new TypeError("Component lifecycle event must be a non-empty string.");
         }
-        if (typeof fn !== "function") {
+        const event = eventName === "mount" ? "attach" : eventName;
+        if (event === "intersect") {
+          const { options, fn } = normalizeOptionsCallback(`Component lifecycle "${eventName}"`, optionsOrFn, maybeFn);
+          intersectionHooks.push((target) => {
+            context.intersect(target, options, fn);
+          });
+          return;
+        }
+        if (maybeFn !== undefined || typeof optionsOrFn !== "function") {
           throw new TypeError(`Component lifecycle "${eventName}" requires a function.`);
         }
-        const event = eventName === "mount" ? "attach" : eventName;
+        const fn = optionsOrFn;
         if (event === "attach") {
           attachHooks.push((target) => fn.call(context, target));
           return;
@@ -2382,6 +2404,18 @@ const __componentModule = (() => {
 
       onVisible(fn) {
         context.on("visible", fn);
+      },
+
+      intersect(target, optionsOrFn, maybeFn) {
+        const { options, fn } = normalizeOptionsCallback("this.intersect(target, ...)", optionsOrFn, maybeFn);
+        const cleanup = loader._observeIntersection(target, (event) => fn.call(context, event), {
+          ...options,
+          scope
+        });
+        if (typeof cleanup === "function") {
+          cleanups.push(cleanup);
+        }
+        return cleanup;
       }
     };
 
@@ -2397,6 +2431,16 @@ const __componentModule = (() => {
     }
   }
 
+  function normalizeOptionsCallback(label, optionsOrFn, maybeFn) {
+    if (typeof optionsOrFn === "function" && maybeFn === undefined) {
+      return { options: {}, fn: optionsOrFn };
+    }
+    if ((optionsOrFn == null || (typeof optionsOrFn === "object" && !Array.isArray(optionsOrFn))) && typeof maybeFn === "function") {
+      return { options: optionsOrFn ?? {}, fn: maybeFn };
+    }
+    throw new TypeError(`${label} requires (fn) or (options, fn).`);
+  }
+
   function scoped(scope, name) {
     if (typeof name !== "string" || name.length === 0) {
       throw new TypeError("Scoped signal or handler name must be a non-empty string.");
@@ -3492,6 +3536,7 @@ const __loaderModule = (() => {
     const signalBindings = new WeakMap();
     const mountedElements = new WeakSet();
     const visibleElements = new WeakSet();
+    const intersectionBindings = new WeakMap();
     const boundaryState = new WeakMap();
     const renderingBoundaries = new WeakSet();
     const inlineBindings = new Map();
@@ -3555,6 +3600,7 @@ const __loaderModule = (() => {
         api.scan(target);
         rendered.mount(target);
         rendered.visible(target, api._observeVisible);
+        rendered.intersection(target, api._observeIntersection);
         addCleanup(rendered.cleanup, target, "children");
         return rendered;
       },
@@ -3578,6 +3624,10 @@ const __loaderModule = (() => {
         return observeVisible(target, fn);
       },
 
+      _observeIntersection(target, fn, options = {}) {
+        return observeIntersection(target, fn, options);
+      },
+
       _registerBinding(value) {
         const id = `${inlineBindingPrefix}${++inlineBindingCounter}`;
         inlineBindings.set(id, value);
@@ -3609,7 +3659,7 @@ const __loaderModule = (() => {
           if (!eventName) {
             continue;
           }
-          if (eventName === "attach" || eventName === "mount" || eventName === "visible") {
+          if (eventName === "attach" || eventName === "mount" || eventName === "visible" || eventName === "intersect") {
             continue;
           }
           bindEvent(element, eventName, element.getAttribute(name));
@@ -3882,6 +3932,25 @@ const __loaderModule = (() => {
         visibleElements.add(element);
         addCleanup(observeVisible(element, () => scheduleLifecycle(element, () => runPseudo(element, ref), `visible:${ref}`)), element);
       }
+
+      for (const element of elementsIn(scope)) {
+        const ref = readAttribute(element, attributeConfig, "on", "intersect");
+        if (ref == null) {
+          continue;
+        }
+        const options = readIntersectionOptions(element);
+        const key = `intersect:${ref}:${serializeIntersectionOptions(options)}`;
+        const bound = intersectionBindings.get(element) ?? new Set();
+        if (bound.has(key)) {
+          continue;
+        }
+        bound.add(key);
+        intersectionBindings.set(element, bound);
+        addCleanup(observeIntersection(element, (event) => runPseudo(element, ref, event), {
+          ...options,
+          key
+        }), element);
+      }
     }
 
     function readPseudoRefs(element, names) {
@@ -3895,7 +3964,7 @@ const __loaderModule = (() => {
       return refs;
     }
 
-    async function runPseudo(element, ref) {
+    async function runPseudo(element, ref, context = {}) {
       try {
         const results = await handlerRegistry.run(ref, {
           signals: signalRegistry,
@@ -3907,7 +3976,8 @@ const __loaderModule = (() => {
           scheduler: schedulerInstance,
           element,
           el: element,
-          root: rootNode
+          root: rootNode,
+          ...context
         });
         for (const result of results) {
           if (typeof result === "function") {
@@ -3920,28 +3990,230 @@ const __loaderModule = (() => {
     }
 
     function observeVisible(target, fn) {
+      return observeIntersection(target, (event) => {
+        if (event.isIntersecting) {
+          fn(target);
+        }
+      }, {
+        once: true,
+        threshold: 0
+      });
+    }
+
+    function observeIntersection(target, fn, options = {}) {
+      if (typeof fn !== "function") {
+        throw new TypeError("observeIntersection(target, fn) requires a callback.");
+      }
+      const normalized = normalizeIntersectionOptions(target, options);
       const ownerWindow = target.ownerDocument?.defaultView ?? globalThis;
       const Observer = ownerWindow.IntersectionObserver ?? globalThis.IntersectionObserver;
       if (!Observer) {
-        schedulerInstance.enqueue("lifecycle", () => {
-          if (!destroyed) {
-            fn(target);
+        let cleaned = false;
+        const event = createIntersectionEvent({
+          target,
+          root: normalized.root,
+          entry: createFallbackIntersectionEntry(target),
+          observer: null,
+          unsupported: true
+        });
+        const cancel = schedulerInstance.enqueue("lifecycle", () => {
+          if (!cleaned && !destroyed) {
+            fn(event);
           }
         }, {
-          scope: target,
-          key: "visible:fallback"
+          scope: normalized.scope,
+          key: normalized.key ?? "intersect:fallback"
         });
-        return () => {};
+        return () => {
+          cleaned = true;
+          cancel?.();
+        };
       }
 
+      let cleaned = false;
+      let stopped = false;
       const observer = new Observer((entries) => {
-        if (entries.some((entry) => entry.isIntersecting)) {
+        if (cleaned || stopped || destroyed) {
+          return;
+        }
+        const observedEntries = entries.filter((entry) => entry.target === target);
+        const targetEntries = observedEntries.length > 0 ? observedEntries : entries;
+        const entry = targetEntries[0];
+        if (!entry) {
+          return;
+        }
+        const event = createIntersectionEvent({
+          target,
+          root: normalized.root,
+          entry,
+          entries: targetEntries,
+          observer,
+          unsupported: false
+        });
+        if (normalized.once && event.isIntersecting) {
+          stopped = true;
           observer.disconnect();
-          fn(target);
         }
+        runIntersectionCallback(fn, event, normalized, () => !cleaned);
+      }, {
+        root: normalized.root,
+        rootMargin: normalized.rootMargin,
+        threshold: normalized.threshold
       });
       observer.observe(target);
-      return () => observer.disconnect();
+      return () => {
+        if (cleaned) {
+          return;
+        }
+        cleaned = true;
+        stopped = true;
+        observer.disconnect();
+      };
+    }
+
+    function readIntersectionOptions(element) {
+      const options = {};
+      const threshold = readAttribute(element, attributeConfig, "intersect", "threshold");
+      if (threshold != null) {
+        options.threshold = parseIntersectionThreshold(threshold);
+      }
+      const rootMargin = readAttribute(element, attributeConfig, "intersect", "root-margin")
+        ?? readAttribute(element, attributeConfig, "intersect", "rootMargin");
+      if (rootMargin != null) {
+        options.rootMargin = rootMargin;
+      }
+      const once = readAttribute(element, attributeConfig, "intersect", "once");
+      if (once != null) {
+        options.once = parseBooleanAttribute(once);
+      }
+      return options;
+    }
+
+    function parseIntersectionThreshold(value) {
+      const parts = String(value).split(",").map((part) => part.trim()).filter(Boolean);
+      if (parts.length === 0) {
+        throw new TypeError("intersect:threshold must include a number from 0 to 1.");
+      }
+      const thresholds = parts.map((part) => {
+        const number = Number(part);
+        return validateIntersectionThreshold(number);
+      });
+      return thresholds.length === 1 ? thresholds[0] : thresholds;
+    }
+
+    function parseBooleanAttribute(value) {
+      const normalized = String(value).trim().toLowerCase();
+      return normalized === "" || normalized === "true" || normalized === "1";
+    }
+
+    function serializeIntersectionOptions(options) {
+      return JSON.stringify({
+        rootMargin: options.rootMargin ?? "0px",
+        threshold: options.threshold ?? 0,
+        once: Boolean(options.once)
+      });
+    }
+
+    function normalizeIntersectionOptions(target, options) {
+      const ownerWindow = target?.ownerDocument?.defaultView ?? globalThis;
+      if (!isElement(target, ownerWindow)) {
+        throw new TypeError("Intersection target must be an Element.");
+      }
+      const root = options.root ?? null;
+      if (root !== null && !isElement(root, ownerWindow) && !isDocument(root, ownerWindow)) {
+        throw new TypeError("Intersection root must be an Element, Document, or null.");
+      }
+      const rootMargin = options.rootMargin ?? "0px";
+      if (typeof rootMargin !== "string") {
+        throw new TypeError("Intersection rootMargin must be a string.");
+      }
+      const threshold = normalizeIntersectionThreshold(options.threshold ?? 0);
+      const schedule = options.schedule ?? "lifecycle";
+      if (schedule !== "lifecycle" && schedule !== "sync") {
+        throw new TypeError('Intersection schedule must be "lifecycle" or "sync".');
+      }
+      return {
+        root,
+        rootMargin,
+        threshold,
+        once: Boolean(options.once),
+        schedule,
+        scope: options.scope ?? target,
+        key: options.key
+      };
+    }
+
+    function normalizeIntersectionThreshold(threshold) {
+      if (Array.isArray(threshold)) {
+        return threshold.map(validateIntersectionThreshold);
+      }
+      return validateIntersectionThreshold(threshold);
+    }
+
+    function validateIntersectionThreshold(value) {
+      if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) {
+        throw new TypeError("Intersection threshold must be a number from 0 to 1.");
+      }
+      return value;
+    }
+
+    function runIntersectionCallback(fn, event, options, isActive = () => true) {
+      if (options.schedule === "sync") {
+        if (isActive()) {
+          fn(event);
+        }
+        return;
+      }
+      schedulerInstance.enqueue("lifecycle", () => {
+        if (!destroyed && isActive()) {
+          fn(event);
+        }
+      }, {
+        scope: options.scope,
+        key: options.key
+      });
+    }
+
+    function createIntersectionEvent({ target, root, entry, entries = [entry], observer, unsupported }) {
+      const isIntersecting = Boolean(entry?.isIntersecting);
+      const intersectionRatio = typeof entry?.intersectionRatio === "number"
+        ? entry.intersectionRatio
+        : (isIntersecting ? 1 : 0);
+      return {
+        target,
+        element: target,
+        el: target,
+        root: root ?? rootNode,
+        entry,
+        entries,
+        observer,
+        isIntersecting,
+        intersectionRatio,
+        unsupported: Boolean(unsupported)
+      };
+    }
+
+    function createFallbackIntersectionEntry(target) {
+      const rect = target.getBoundingClientRect?.() ?? null;
+      return {
+        target,
+        isIntersecting: true,
+        intersectionRatio: 1,
+        time: 0,
+        rootBounds: null,
+        boundingClientRect: rect,
+        intersectionRect: rect
+      };
+    }
+
+    function isElement(value, ownerWindow = globalThis) {
+      const ElementRef = ownerWindow.Element ?? globalThis.Element;
+      return Boolean(ElementRef && value instanceof ElementRef);
+    }
+
+    function isDocument(value, ownerWindow = globalThis) {
+      const DocumentRef = ownerWindow.Document ?? globalThis.Document;
+      return Boolean(DocumentRef && value instanceof DocumentRef);
     }
 
     function assertActive() {

package/package.json

@@ -1,13 +1,9 @@
 {
   "name": "@async/framework",
-  "version": "0.11.14",
+  "version": "0.11.16",
   "description": "No-build Loader app runtime with browser and server entrypoints, signals, command events, route partials, cache split, SSR activation, and streaming boundaries.",
   "type": "module",
-  "main": "./server.js",
-  "module": "./browser.min.js",
-  "browser": "./browser.min.js",
   "sideEffects": false,
-  "packageManager": "pnpm@11.1.0",
   "engines": {
     "node": ">=24"
   },
@@ -32,7 +28,6 @@
     "web-framework"
   ],
   "license": "MIT",
-  "types": "./framework.d.ts",
   "unpkg": "./browser.umd.min.js",
   "jsdelivr": "./browser.umd.min.js",
   "exports": {
@@ -65,41 +60,27 @@
       "import": "./server.js",
       "default": "./server.js"
     },
-    "./browser.js": {
-      "types": "./browser.d.ts",
-      "default": "./browser.js"
+    "./runtime": {
+      "types": "./runtime.d.ts",
+      "import": "./runtime.js",
+      "default": "./runtime.js"
     },
-    "./browser.min.js": {
-      "types": "./browser.d.ts",
-      "default": "./browser.min.js"
+    "./runtime/signals": {
+      "types": "./runtime/signals.d.ts",
+      "import": "./runtime/signals.js",
+      "default": "./runtime/signals.js"
     },
-    "./browser.umd.js": {
-      "types": "./browser.d.ts",
-      "default": "./browser.umd.js"
+    "./runtime/events": {
+      "types": "./runtime/events.d.ts",
+      "import": "./runtime/events.js",
+      "default": "./runtime/events.js"
     },
-    "./browser.umd.min.js": {
-      "types": "./browser.d.ts",
-      "default": "./browser.umd.min.js"
-    },
-    "./browser.ts": {
-      "types": "./browser.d.ts",
-      "default": "./browser.ts"
-    },
-    "./browser.d.ts": "./browser.d.ts",
-    "./server.js": {
-      "types": "./framework.d.ts",
-      "default": "./server.js"
-    },
-    "./framework.ts": {
-      "types": "./framework.d.ts",
-      "default": "./framework.ts"
-    },
-    "./framework.d.ts": "./framework.d.ts",
     "./package.json": "./package.json"
   },
   "files": [
     "CHANGELOG.md",
     "README.md",
+    "LICENSE",
     "browser.d.ts",
     "browser.js",
     "browser.min.js",
@@ -108,40 +89,14 @@
     "browser.ts",
     "framework.d.ts",
     "framework.ts",
+    "package.json",
     "server.js",
-    "LICENSE",
-    "package.json"
-  ],
-  "scripts": {
-    "async-pipeline": "async-pipeline",
-    "bundle": "node scripts/build-framework-bundle.js",
-    "bundle:check": "node scripts/build-framework-bundle.js --check",
-    "bundle:size": "node scripts/bundle-size.js",
-    "bundle:size:check": "node scripts/bundle-size.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": "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-task docs.site",
-    "pipeline:publish": "async-pipeline run publish",
-    "pipeline:publish:github:release": "async-pipeline publish github release --package . --registry https://npm.pkg.github.com",
-    "pipeline:publish:npm": "async-pipeline publish npm --package .",
-    "pipeline:release-doctor": "async-pipeline run release-doctor",
-    "pipeline:release:doctor": "async-pipeline release doctor --package .",
-    "pipeline:release:ensure": "async-pipeline release ensure --package .",
-    "pipeline:sync:check": "async-pipeline sync check",
-    "pipeline:sync:generate": "async-pipeline sync generate",
-    "pipeline:task:docs.site": "async-pipeline run-task docs.site",
-    "pipeline:verify": "async-pipeline run verify",
-    "registry:lint": "node scripts/registry-lint.js",
-    "release:check": "pnpm run pipeline:verify -- --force && pnpm run bundle:size:check && pnpm run pipeline:pages -- --force && pnpm run pipeline:sync:check && pnpm run pipeline:github:check",
-    "test": "node --test tests/*.test.js"
-  },
-  "devDependencies": {
-    "@async/pipeline": "0.9.1",
-    "happy-dom": "20.10.5",
-    "terser": "5.48.0"
-  }
+    "runtime.d.ts",
+    "runtime/signals.d.ts",
+    "runtime/events.d.ts",
+    "runtime.js",
+    "runtime/signals.js",
+    "runtime/events.js",
+    "runtime/shared.js"
+  ]
 }

package/runtime/events.d.ts

@@ -0,0 +1,48 @@
+// Generated by scripts/build-framework-bundle.js. Do not edit by hand.
+// Type declarations for @async/framework/runtime/events.
+
+export type ElementLocator = string | { readonly selector: string; readonly optional?: boolean };
+export type EventRuntimeContext = {
+  event: Event;
+  element: Element;
+  el: Element;
+  root: ParentNode;
+  signals?: { set(path: string, value: unknown): void };
+};
+export type EventValueSource =
+  | readonly ["event.target.value"]
+  | readonly ["event.target.checked"]
+  | readonly ["constant", value: unknown];
+export type EventCommand =
+  | readonly ["handler", id: string]
+  | readonly ["preventDefault"]
+  | readonly ["stopPropagation"]
+  | readonly ["stopImmediatePropagation"]
+  | readonly ["setSignal", path: string, valueSource: EventValueSource];
+export type EventBindingRecord = readonly [element: number, event: string, commands: readonly EventCommand[]];
+export type StrictHandlerDescriptor = {
+  readonly mode?: "strict";
+  readonly module?: string;
+  readonly browserImport: string;
+  readonly exportName: string;
+  readonly version?: string;
+  readonly integrity?: string;
+};
+export type HandlerDescriptor = ((context: EventRuntimeContext) => unknown | Promise<unknown>) | StrictHandlerDescriptor;
+export type EventRuntimePlan = {
+  readonly version?: 1;
+  readonly events: readonly EventBindingRecord[];
+  readonly handlers?: Record<string, HandlerDescriptor>; 
+};
+export type EventRuntimeOptions = {
+  readonly elements?: readonly ElementLocator[];
+  readonly signal?: AbortSignal;
+  readonly signals?: { set(path: string, value: unknown): void };
+  readonly importModule?: (specifier: string) => Promise<Record<string, unknown>>;
+  readonly onDiagnostic?: (diagnostic: Record<string, unknown>) => void;
+};
+export type EventRuntimeController = {
+  readonly stopped: boolean;
+  stop(): void;
+};
+export declare function startEvents(rootOrOptions: ParentNode | ({ root: ParentNode; plan: EventRuntimePlan } & EventRuntimeOptions), plan?: EventRuntimePlan, options?: EventRuntimeOptions): EventRuntimeController;