@fluixi/core 1.0.0-alpha.100

package/dist/src/lib/render/deferred.cjs

@@ -0,0 +1,175 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/lib/render/deferred.ts
+var deferred_exports = {};
+__export(deferred_exports, {
+  deferred: () => deferred
+});
+module.exports = __toCommonJS(deferred_exports);
+var import_dom2 = require("@fluixi/dom");
+var import_signal2 = require("@fluixi/reactive/signal");
+var import_utils = require("@fluixi/dom/utils");
+
+// src/lib/render/lazy.ts
+var import_dom = require("@fluixi/dom");
+var import_signal = require("@fluixi/reactive/signal");
+function fromChunk(value) {
+  if (value != null && (typeof value === "object" || typeof value === "function")) {
+    try {
+      value["$lazy"] = true;
+    } catch {
+    }
+  }
+  return value;
+}
+function lazy(loader, options) {
+  let resolved;
+  let promise;
+  let component;
+  function load() {
+    if (!promise) {
+      promise = loader().then((mod) => resolved = mod.default);
+    }
+    return promise;
+  }
+  if (options?.preload) load();
+  const LazyWrapper = ((props) => {
+    if (resolved) {
+      const C = resolved;
+      return fromChunk((0, import_signal.untrack)(() => C(props)));
+    }
+    if (!component) {
+      const [resource] = (0, import_signal.createResource)(() => load(), { transport: false });
+      component = resource;
+      if (resource.error) throw resource.error;
+    }
+    return (0, import_signal.createMemo)(() => {
+      const C = component();
+      return C ? fromChunk((0, import_dom.createComponent)(C, props)) : void 0;
+    });
+  });
+  LazyWrapper.preload = () => load().then(() => void 0);
+  LazyWrapper.$lazy = true;
+  LazyWrapper.loader = loader;
+  return LazyWrapper;
+}
+
+// src/lib/render/deferred.ts
+function deferred(loader, options) {
+  const exportName = options.export ?? "default";
+  const Lazy = lazy(
+    () => loader().then((mod) => {
+      const component = mod[exportName];
+      if (typeof component !== "function") {
+        throw new Error(
+          `deferred(): module has no '${exportName}' export (got ${typeof component}).`
+        );
+      }
+      return { default: component };
+    }),
+    { fallback: options.fallback }
+  );
+  function Deferred(props) {
+    if (options.strategy.kind === "never") return (0, import_dom2.isServer)() ? Lazy(props) : null;
+    if ((0, import_dom2.isServer)() || options.strategy.kind === "eager") return Lazy(props);
+    const [ready, setReady] = (0, import_signal2.createSignal)(false);
+    const start = () => {
+      void Lazy.preload().then(() => setReady(true));
+    };
+    const anchor = options.strategy.kind === "visible" ? createAnchor() : void 0;
+    schedule(options.strategy, start, anchor);
+    return (0, import_signal2.createMemo)(() => ready() ? Lazy(props) : anchor ?? options.fallback ?? null, void 0, {
+      name: "deferred"
+    });
+  }
+  Deferred.preload = Lazy.preload;
+  return Deferred;
+}
+function createAnchor() {
+  const el = document.createElement("span");
+  el.setAttribute("data-fx-load", "visible");
+  el.style.display = "block";
+  return el;
+}
+function schedule(strategy, start, anchor) {
+  let fired = false;
+  const once = () => {
+    if (fired) return;
+    fired = true;
+    start();
+  };
+  switch (strategy.kind) {
+    case "idle": {
+      const ric = globalThis.requestIdleCallback;
+      if (ric) ric(once);
+      else setTimeout(once, 1);
+      return;
+    }
+    case "visible": {
+      if (!anchor || typeof IntersectionObserver === "undefined") {
+        once();
+        return;
+      }
+      const stop = (0, import_utils.observeIntersection)(
+        anchor,
+        (isIntersecting) => {
+          if (!isIntersecting) return;
+          stop();
+          once();
+        },
+        { rootMargin: strategy.rootMargin ?? "0px" }
+      );
+      return;
+    }
+    case "interaction": {
+      const handler = () => {
+        for (const event of strategy.events) {
+          document.removeEventListener(event, handler, true);
+        }
+        once();
+      };
+      for (const event of strategy.events) {
+        document.addEventListener(event, handler, { capture: true, passive: true });
+      }
+      return;
+    }
+    case "media": {
+      if (typeof matchMedia === "undefined") {
+        once();
+        return;
+      }
+      const query = matchMedia(strategy.query);
+      if (query.matches) {
+        once();
+        return;
+      }
+      const onChange = (e) => {
+        if (!e.matches) return;
+        query.removeEventListener("change", onChange);
+        once();
+      };
+      query.addEventListener("change", onChange);
+      return;
+    }
+    /* c8 ignore next 3 */
+    default:
+      once();
+  }
+}

package/dist/src/lib/render/deferred.d.ts

@@ -0,0 +1,36 @@
+/** When to fetch. Mirrors the compiler's `IRLoadStrategy`. */
+export type LoadStrategy = {
+    kind: 'eager';
+} | {
+    kind: 'idle';
+} | {
+    kind: 'visible';
+    rootMargin?: string;
+} | {
+    kind: 'interaction';
+    events: string[];
+} | {
+    kind: 'media';
+    query: string;
+} | {
+    kind: 'never';
+};
+export interface DeferredOptions {
+    strategy: LoadStrategy;
+    /** Named export to take from the module. Defaults to `default`. */
+    export?: string;
+    /** Rendered until the module arrives. */
+    fallback?: unknown;
+}
+type AnyComponent = (props: any) => any;
+/**
+ * Wrap a dynamic import so the component loads when its strategy says to.
+ *
+ * The returned component still exposes `preload()`, so a route or a hover handler can
+ * pull the module forward regardless of the strategy.
+ */
+export declare function deferred(loader: () => Promise<Record<string, unknown>>, options: DeferredOptions): AnyComponent & {
+    preload: () => Promise<void>;
+};
+export {};
+//# sourceMappingURL=deferred.d.ts.map

package/dist/src/lib/render/deferred.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deferred.d.ts","sourceRoot":"","sources":["../../../../src/lib/render/deferred.ts"],"names":[],"mappings":"AAmBA,8DAA8D;AAC9D,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,CAAC;IACvB,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,KAAK,YAAY,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,GAAG,CAAC;AAExC;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC9C,OAAO,EAAE,eAAe,GACvB,YAAY,GAAG;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA4CjD"}

package/dist/src/lib/render/deferred.js

@@ -0,0 +1,141 @@
+/**
+ * `deferred(loader, options)`, a component whose module is fetched on a schedule.
+ *
+ * This is the runtime half of the `load:` directive. It adds only the *when*: which
+ * browser signal starts the download. Resolution, Suspense integration and the
+ * synchronous-when-preloaded hydration path all come from {@link lazy}, reused unchanged
+ *, so a deferred component behaves exactly like a lazy one once its trigger fires.
+ *
+ * There is no registry and no runtime name lookup. The compiler emits a call with a
+ * literal `import()`, which is what lets the bundler do chunking, hashing and
+ * tree-shaking as ordinary behaviour rather than as an integration.
+ */
+import { isServer } from '@fluixi/dom';
+import { createMemo, createSignal } from '@fluixi/reactive/signal';
+import { observeIntersection } from '@fluixi/dom/utils';
+import { lazy } from './lazy.js';
+/**
+ * Wrap a dynamic import so the component loads when its strategy says to.
+ *
+ * The returned component still exposes `preload()`, so a route or a hover handler can
+ * pull the module forward regardless of the strategy.
+ */
+export function deferred(loader, options) {
+    const exportName = options.export ?? 'default';
+    // `lazy` wants `{ default }`; the resolver imports named exports, so adapt here rather
+    // than making every call site emit an adapter.
+    const Lazy = lazy(() => loader().then((mod) => {
+        const component = mod[exportName];
+        if (typeof component !== 'function') {
+            throw new Error(`deferred(): module has no '${exportName}' export (got ${typeof component}).`);
+        }
+        return { default: component };
+    }), { fallback: options.fallback });
+    function Deferred(props) {
+        // `never` is server-only: the component renders during SSR and its code is meant to
+        // stay out of the client bundle entirely. The compiler is what actually drops it
+        // this guard only stops the client from fetching it if one slips through.
+        if (options.strategy.kind === 'never')
+            return isServer() ? Lazy(props) : null;
+        if (isServer() || options.strategy.kind === 'eager')
+            return Lazy(props);
+        const [ready, setReady] = createSignal(false);
+        const start = () => {
+            void Lazy.preload().then(() => setReady(true));
+        };
+        // `visible` is the one strategy that needs something in the DOM to watch, so it
+        // renders an anchor and observes that; the others key off global signals and can
+        // render the plain fallback.
+        const anchor = options.strategy.kind === 'visible' ? createAnchor() : undefined;
+        schedule(options.strategy, start, anchor);
+        return createMemo(() => (ready() ? Lazy(props) : (anchor ?? options.fallback ?? null)), undefined, {
+            name: 'deferred',
+        });
+    }
+    Deferred.preload = Lazy.preload;
+    return Deferred;
+}
+/**
+ * A zero-height marker to observe. It occupies the component's slot until the module
+ * arrives, so `IntersectionObserver` has something with a position to report.
+ */
+function createAnchor() {
+    const el = document.createElement('span');
+    el.setAttribute('data-fx-load', 'visible');
+    el.style.display = 'block';
+    return el;
+}
+/** Run `start` when the strategy's trigger fires. Idempotent, it fires at most once. */
+function schedule(strategy, start, anchor) {
+    let fired = false;
+    const once = () => {
+        if (fired)
+            return;
+        fired = true;
+        start();
+    };
+    switch (strategy.kind) {
+        case 'idle': {
+            const ric = globalThis
+                .requestIdleCallback;
+            // Safari has no requestIdleCallback; a timeout keeps the behaviour rather than
+            // silently loading eagerly.
+            if (ric)
+                ric(once);
+            else
+                setTimeout(once, 1);
+            return;
+        }
+        case 'visible': {
+            // Without an observer there is no signal to wait for, so load rather than never
+            // rendering, a missing capability should degrade to eager, not to broken.
+            if (!anchor || typeof IntersectionObserver === 'undefined') {
+                once();
+                return;
+            }
+            const stop = observeIntersection(anchor, (isIntersecting) => {
+                if (!isIntersecting)
+                    return;
+                stop();
+                once();
+            }, { rootMargin: strategy.rootMargin ?? '0px' });
+            return;
+        }
+        case 'interaction': {
+            // Listened for on the document rather than the element: the point is the user's
+            // first interaction anywhere, and the component often has no DOM yet.
+            const handler = () => {
+                for (const event of strategy.events) {
+                    document.removeEventListener(event, handler, true);
+                }
+                once();
+            };
+            for (const event of strategy.events) {
+                document.addEventListener(event, handler, { capture: true, passive: true });
+            }
+            return;
+        }
+        case 'media': {
+            if (typeof matchMedia === 'undefined') {
+                once();
+                return;
+            }
+            const query = matchMedia(strategy.query);
+            if (query.matches) {
+                once();
+                return;
+            }
+            const onChange = (e) => {
+                if (!e.matches)
+                    return;
+                query.removeEventListener('change', onChange);
+                once();
+            };
+            query.addEventListener('change', onChange);
+            return;
+        }
+        /* c8 ignore next 3 */
+        default:
+            once();
+    }
+}

package/dist/src/lib/render/deferred.mjs

@@ -0,0 +1,158 @@
+// src/lib/render/deferred.ts
+import { isServer } from "@fluixi/dom";
+import { createMemo as createMemo2, createSignal } from "@fluixi/reactive/signal";
+import { observeIntersection } from "@fluixi/dom/utils";
+
+// src/lib/render/lazy.ts
+import { createComponent } from "@fluixi/dom";
+import {
+  untrack,
+  createMemo,
+  createResource
+} from "@fluixi/reactive/signal";
+function fromChunk(value) {
+  if (value != null && (typeof value === "object" || typeof value === "function")) {
+    try {
+      value["$lazy"] = true;
+    } catch {
+    }
+  }
+  return value;
+}
+function lazy(loader, options) {
+  let resolved;
+  let promise;
+  let component;
+  function load() {
+    if (!promise) {
+      promise = loader().then((mod) => resolved = mod.default);
+    }
+    return promise;
+  }
+  if (options?.preload) load();
+  const LazyWrapper = ((props) => {
+    if (resolved) {
+      const C = resolved;
+      return fromChunk(untrack(() => C(props)));
+    }
+    if (!component) {
+      const [resource] = createResource(() => load(), { transport: false });
+      component = resource;
+      if (resource.error) throw resource.error;
+    }
+    return createMemo(() => {
+      const C = component();
+      return C ? fromChunk(createComponent(C, props)) : void 0;
+    });
+  });
+  LazyWrapper.preload = () => load().then(() => void 0);
+  LazyWrapper.$lazy = true;
+  LazyWrapper.loader = loader;
+  return LazyWrapper;
+}
+
+// src/lib/render/deferred.ts
+function deferred(loader, options) {
+  const exportName = options.export ?? "default";
+  const Lazy = lazy(
+    () => loader().then((mod) => {
+      const component = mod[exportName];
+      if (typeof component !== "function") {
+        throw new Error(
+          `deferred(): module has no '${exportName}' export (got ${typeof component}).`
+        );
+      }
+      return { default: component };
+    }),
+    { fallback: options.fallback }
+  );
+  function Deferred(props) {
+    if (options.strategy.kind === "never") return isServer() ? Lazy(props) : null;
+    if (isServer() || options.strategy.kind === "eager") return Lazy(props);
+    const [ready, setReady] = createSignal(false);
+    const start = () => {
+      void Lazy.preload().then(() => setReady(true));
+    };
+    const anchor = options.strategy.kind === "visible" ? createAnchor() : void 0;
+    schedule(options.strategy, start, anchor);
+    return createMemo2(() => ready() ? Lazy(props) : anchor ?? options.fallback ?? null, void 0, {
+      name: "deferred"
+    });
+  }
+  Deferred.preload = Lazy.preload;
+  return Deferred;
+}
+function createAnchor() {
+  const el = document.createElement("span");
+  el.setAttribute("data-fx-load", "visible");
+  el.style.display = "block";
+  return el;
+}
+function schedule(strategy, start, anchor) {
+  let fired = false;
+  const once = () => {
+    if (fired) return;
+    fired = true;
+    start();
+  };
+  switch (strategy.kind) {
+    case "idle": {
+      const ric = globalThis.requestIdleCallback;
+      if (ric) ric(once);
+      else setTimeout(once, 1);
+      return;
+    }
+    case "visible": {
+      if (!anchor || typeof IntersectionObserver === "undefined") {
+        once();
+        return;
+      }
+      const stop = observeIntersection(
+        anchor,
+        (isIntersecting) => {
+          if (!isIntersecting) return;
+          stop();
+          once();
+        },
+        { rootMargin: strategy.rootMargin ?? "0px" }
+      );
+      return;
+    }
+    case "interaction": {
+      const handler = () => {
+        for (const event of strategy.events) {
+          document.removeEventListener(event, handler, true);
+        }
+        once();
+      };
+      for (const event of strategy.events) {
+        document.addEventListener(event, handler, { capture: true, passive: true });
+      }
+      return;
+    }
+    case "media": {
+      if (typeof matchMedia === "undefined") {
+        once();
+        return;
+      }
+      const query = matchMedia(strategy.query);
+      if (query.matches) {
+        once();
+        return;
+      }
+      const onChange = (e) => {
+        if (!e.matches) return;
+        query.removeEventListener("change", onChange);
+        once();
+      };
+      query.addEventListener("change", onChange);
+      return;
+    }
+    /* c8 ignore next 3 */
+    default:
+      once();
+  }
+}
+export {
+  deferred
+};