@fluixi/core 1.0.0-alpha.100

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

@@ -0,0 +1,105 @@
+/**
+ * Lazy-load a component module.
+ *
+ * SolidJS-aligned pattern:
+ *  1. `comp` signal is shared across all instances of this lazy component (module-level).
+ *  2. `createResource` at the component level registers the load promise with the
+ *     nearest Suspense boundary (trackPromise / resource.loading).
+ *  3. A pure `createMemo` reads `comp()`: undefined while loading (Suspense shows
+ *     fallback), the rendered component once loaded.
+ *  4. `preload()` is exposed so routes / link hover handlers can start the download
+ *     before the component is rendered.
+ */
+import { createComponent } from '@fluixi/dom';
+import { untrack, createMemo, createResource, } from '@fluixi/reactive/signal';
+/**
+ * Say that this came out of a chunk of its own, so devtools can tell a routed component apart
+ * from one that shipped in the first bundle. Nothing but a watcher reads it.
+ */
+function fromChunk(value) {
+    if (value != null && (typeof value === 'object' || typeof value === 'function')) {
+        try {
+            value['$lazy'] = true;
+        }
+        catch {
+            /* frozen or exotic */
+        }
+    }
+    return value;
+}
+// ─── Implementation ──────────────────────────────────────────────────────────
+/**
+ * Defer a component to its own chunk, loaded the first time it renders.
+ *
+ * `loader` is a dynamic import, and its `default` export is the component. The returned
+ * function stands in for it and carries `preload()`, which starts the import without
+ * rendering anything. File routing uses that: `startClient` preloads the matched route
+ * before hydrating.
+ *
+ * Preloading is what keeps hydration intact. If the module has already resolved by the
+ * time this renders, the component renders synchronously on the first pass, so it adopts
+ * the server's DOM in place. On a cold client navigation it goes through a resource
+ * instead, suspends, and a `Suspense` boundary above it shows the fallback.
+ *
+ * @example
+ * ```ts
+ * const Settings = lazy(() => import('./Settings.js'));
+ *
+ * // somewhere that knows the route is next
+ * void Settings.preload();
+ * ```
+ */
+export function lazy(loader, options) {
+    // The resolved component, set once the module loads. The whole hydration story turns on
+    // this: when it's already set when LazyWrapper renders, because the route was preloaded
+    // before hydration (see startClient -> preloadRoutes): we render it SYNCHRONOUSLY on the
+    // first pass. No resource, no Suspense fallback, no late re-render. So the lazy file-route
+    // adopts the server DOM in place instead of resolving a tick later and building a duplicate
+    // next to it. The async path below is only for a cold client navigation.
+    let resolved;
+    // Single in-flight / completed import. Idempotent: repeat calls reuse the same promise.
+    let promise;
+    // Suspense-tracked resource, created lazily on the cold (not-preloaded) path only.
+    let component;
+    function load() {
+        if (!promise) {
+            promise = loader().then((mod) => (resolved = mod.default));
+        }
+        return promise;
+    }
+    if (options?.preload)
+        load();
+    const LazyWrapper = ((props) => {
+        // Fast path: module already loaded (eager preload, or preloaded before hydration).
+        // Render straight through: under hydration this consumes the cursor in place.
+        if (resolved) {
+            const C = resolved;
+            return fromChunk(untrack(() => C(props)));
+        }
+        // Cold path: not loaded yet (client-side navigation to a route whose chunk hasn't been
+        // fetched). Register the import with the nearest Suspense via createResource so the
+        // fallback shows while it downloads, then swap in the component once it resolves.
+        if (!component) {
+            // transport:false, the value here is the component function, which never
+            // travelled to the client, and the id it used to consume made the page's own
+            // resource ids depend on whether this module was already loaded in the
+            // process. The client re-imports the chunk itself either way.
+            const [resource] = createResource(() => load(), { transport: false });
+            component = resource;
+            if (resource.error)
+                throw resource.error;
+        }
+        // Left unnamed: this memo is the routed component's wrapper, so it should end up carrying
+        // that component's name rather than a label of its own.
+        return createMemo(() => {
+            const C = component();
+            return C ? fromChunk(createComponent(C, props)) : undefined;
+        });
+    });
+    // Callers (link hover, router prefetch, the hydration preload pass) start the download
+    // before the component enters the view: <a onMouseEnter={() => LazyFoo.preload()}>.
+    LazyWrapper.preload = () => load().then(() => undefined);
+    LazyWrapper.$lazy = true;
+    LazyWrapper.loader = loader;
+    return LazyWrapper;
+}

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

@@ -0,0 +1,50 @@
+// 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;
+}
+export {
+  lazy
+};

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

@@ -0,0 +1,141 @@
+"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/suspense.ts
+var suspense_exports = {};
+__export(suspense_exports, {
+  $SUSPENSE: () => $SUSPENSE,
+  Suspense: () => Suspense,
+  SuspenseList: () => SuspenseList,
+  isJSXElement: () => isJSXElement,
+  isLitResult: () => isLitResult,
+  isNode: () => isNode,
+  isPromise: () => isPromise
+});
+module.exports = __toCommonJS(suspense_exports);
+var import_signal = require("@fluixi/reactive/signal");
+var import_dom = require("@fluixi/dom");
+var $SUSPENSE = /* @__PURE__ */ Symbol.for("suspense");
+function isNode(value) {
+  if (typeof window === "undefined") return false;
+  if (typeof Node === "function" && value instanceof Node) return true;
+  return !!(value && typeof value === "object" && typeof value.nodeType === "number");
+}
+function isLitResult(value) {
+  if (!value || typeof value !== "object") return false;
+  return !!(typeof value["_$litType$"] !== "undefined" || typeof value["_$litDirective$"] !== "undefined" || Array.isArray(value.strings) && Array.isArray(value.values));
+}
+function isPromise(value) {
+  return !!(value && typeof value === "object" && typeof value.then === "function" || value instanceof Promise);
+}
+function isJSXElement(value) {
+  return !!(value && typeof value === "object" && "type" in value && "props" in value);
+}
+var SuspenseListContext = (0, import_signal.createContext)(void 0, "suspense-list");
+function Suspense(props) {
+  return (0, import_dom.createComponent)(SuspenseImpl, props);
+}
+function SuspenseImpl(props) {
+  const boundary = (0, import_signal.createSuspenseBoundary)();
+  const listCtx = (0, import_signal.useContext)(SuspenseListContext);
+  const listState = listCtx ? listCtx.register(boundary.inFallback) : void 0;
+  function instantiateOnce(val) {
+    if (val == null || typeof val === "boolean") return null;
+    if (typeof val === "function" && (0, import_dom.isComponent)(val) && !(0, import_signal.isSignal)(val)) return val();
+    return val;
+  }
+  const fallback = (0, import_dom.runWithoutHydration)(() => instantiateOnce(props.fallback ?? null));
+  const children = (0, import_signal.provideSuspense)(boundary, () => (0, import_signal.readChildren)(() => props.children));
+  const track = (value, depth) => {
+    if (depth > 8) return;
+    if (Array.isArray(value)) {
+      for (const x of value) track(x, depth + 1);
+    } else if (typeof value === "function" && (0, import_signal.isSignal)(value)) {
+      track(value(), depth + 1);
+    }
+  };
+  (0, import_signal.provideSuspense)(boundary, () => {
+    (0, import_signal.createRenderEffect)(() => track(children, 0));
+  });
+  const [resolved, setResolved] = (0, import_signal.createSignal)(void 0);
+  const childIsPromise = isPromise(children);
+  if (childIsPromise) {
+    boundary.increment();
+    children.then(
+      (v) => {
+        setResolved(() => v);
+        boundary.decrement();
+      },
+      () => boundary.decrement()
+    );
+  }
+  return (0, import_signal.createMemo)(() => {
+    const showFallback = listState ? listState.showFallback() : boundary.inFallback();
+    if (showFallback) return fallback;
+    if (childIsPromise) return resolved();
+    return children;
+  });
+}
+function SuspenseList(props) {
+  return (0, import_dom.createComponent)(SuspenseListImpl, props);
+}
+function SuspenseListImpl(props) {
+  const { revealOrder = "together", tail } = props;
+  const registrations = [];
+  function coordinateReveal() {
+    if (revealOrder === "together") {
+      const allResolved = registrations.every((r) => !r.inFallback());
+      registrations.forEach((r) => {
+        r.setShowContent(allResolved);
+        r.setShowFallback(!allResolved);
+      });
+    } else {
+      const items = revealOrder === "backwards" ? [...registrations].reverse() : registrations;
+      let blocked = false;
+      for (const r of items) {
+        if (blocked || r.inFallback()) {
+          blocked = true;
+          r.setShowContent(false);
+          r.setShowFallback(tail !== "hidden");
+        } else {
+          r.setShowContent(true);
+          r.setShowFallback(false);
+        }
+      }
+    }
+  }
+  const coordinator = {
+    register: (inFallback) => {
+      const [showContent, setShowContent] = (0, import_signal.createSignal)(true);
+      const [showFallback, setShowFallback] = (0, import_signal.createSignal)(false);
+      registrations.push({ inFallback, setShowContent, setShowFallback });
+      (0, import_signal.createEffect)(() => {
+        inFallback();
+        coordinateReveal();
+      });
+      return { showContent, showFallback };
+    }
+  };
+  return SuspenseListContext.Provider({
+    value: coordinator,
+    children: props.children
+  });
+}
+(0, import_dom.asSuspense)(Suspense);
+Object.defineProperty(Suspense, "__suspense", { value: true, enumerable: true });

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

@@ -0,0 +1,65 @@
+/**
+ * Suspense on the TC39 boundary. A createResource read throws its promise while
+ * pending; the effect running it reports that to the nearest boundary (stamped as
+ * SuspenseContext on this component's owner), which flips inFallback. The output
+ * memo swaps between fallback and children on that signal.
+ */
+export interface SuspenseProps {
+    fallback?: any;
+    children?: any;
+    id?: string;
+}
+export interface SuspenseListProps {
+    children: any;
+    revealOrder?: 'forwards' | 'backwards' | 'together';
+    tail?: 'collapsed' | 'hidden';
+}
+export declare const $SUSPENSE: unique symbol;
+declare function isNode(value: any): value is Node;
+declare function isLitResult(value: any): boolean;
+declare function isPromise<T = any>(value: any): value is Promise<T>;
+declare function isJSXElement(value: any): boolean;
+/**
+ * Show `fallback` while anything below is still pending.
+ *
+ * A boundary is a counter on the owner tree. A read that suspends, which is a resource
+ * throwing its pending promise, bubbles to the effect that was reading, and the runtime
+ * hands it to the nearest boundary above. The promise settling decrements the counter,
+ * and the content replaces the fallback through ordinary reactivity.
+ *
+ * Nothing needs to be wired by hand. Anything that suspends reports here on its own,
+ * including a `lazy` component on a cold navigation and a `createResource` still loading.
+ *
+ * @example
+ * ```ts
+ * html`
+ *   <${Suspense} fallback=${html`<p>loading...</p>`}>
+ *     <${Profile} />
+ *   </${Suspense}>`;
+ * ```
+ */
+export declare function Suspense(props: SuspenseProps): any;
+/**
+ * Order how a group of sibling `Suspense` boundaries reveal themselves.
+ *
+ * Without it, each boundary swaps its fallback for content the moment its own work
+ * finishes, so a list of independently-loading rows appears in whatever order the
+ * network happened to return. `revealOrder` imposes one instead.
+ *
+ * `forwards` and `backwards` hold a boundary in its fallback until the ones before it in
+ * that direction have resolved. `together`, the default, holds all of them until every
+ * one has. `tail` decides what the unrevealed ones show: `collapsed` keeps only the next
+ * fallback, `hidden` shows none.
+ *
+ * @example
+ * ```ts
+ * html`
+ *   <${SuspenseList} revealOrder="forwards" tail="collapsed">
+ *     <${Suspense} fallback=${skeleton}><${Row} id=${1} /></${Suspense}>
+ *     <${Suspense} fallback=${skeleton}><${Row} id=${2} /></${Suspense}>
+ *   </${SuspenseList}>`;
+ * ```
+ */
+export declare function SuspenseList(props: SuspenseListProps): any;
+export { isNode, isLitResult, isPromise, isJSXElement };
+//# sourceMappingURL=suspense.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"suspense.d.ts","sourceRoot":"","sources":["../../../../src/lib/render/suspense.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,GAAG,CAAC;IACd,WAAW,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,UAAU,CAAC;IACpD,IAAI,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC;CAC/B;AAED,eAAO,MAAM,SAAS,eAAyB,CAAC;AAEhD,iBAAS,MAAM,CAAC,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,IAAI,CAIzC;AAED,iBAAS,WAAW,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAOxC;AAED,iBAAS,SAAS,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,GAAG,GAAG,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAK3D;AAED,iBAAS,YAAY,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEzC;AAYD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,GAAG,CAElD;AA+ED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,GAAG,CAE1D;AAwDD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC"}

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

@@ -0,0 +1,196 @@
+/**
+ * Suspense on the TC39 boundary. A createResource read throws its promise while
+ * pending; the effect running it reports that to the nearest boundary (stamped as
+ * SuspenseContext on this component's owner), which flips inFallback. The output
+ * memo swaps between fallback and children on that signal.
+ */
+import { createSignal, createMemo, createEffect, createRenderEffect, isSignal, readChildren, useContext, createContext, createSuspenseBoundary, provideSuspense, } from '@fluixi/reactive/signal';
+import { asSuspense, isComponent, createComponent, runWithoutHydration, } from '@fluixi/dom';
+export const $SUSPENSE = Symbol.for('suspense');
+function isNode(value) {
+    if (typeof window === 'undefined')
+        return false;
+    if (typeof Node === 'function' && value instanceof Node)
+        return true;
+    return !!(value && typeof value === 'object' && typeof value.nodeType === 'number');
+}
+function isLitResult(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return !!(typeof value['_$litType$'] !== 'undefined' ||
+        typeof value['_$litDirective$'] !== 'undefined' ||
+        (Array.isArray(value.strings) && Array.isArray(value.values)));
+}
+function isPromise(value) {
+    return !!((value && typeof value === 'object' && typeof value.then === 'function') ||
+        value instanceof Promise);
+}
+function isJSXElement(value) {
+    return !!(value && typeof value === 'object' && 'type' in value && 'props' in value);
+}
+const SuspenseListContext = createContext(undefined, 'suspense-list');
+/**
+ * Show `fallback` while anything below is still pending.
+ *
+ * A boundary is a counter on the owner tree. A read that suspends, which is a resource
+ * throwing its pending promise, bubbles to the effect that was reading, and the runtime
+ * hands it to the nearest boundary above. The promise settling decrements the counter,
+ * and the content replaces the fallback through ordinary reactivity.
+ *
+ * Nothing needs to be wired by hand. Anything that suspends reports here on its own,
+ * including a `lazy` component on a cold navigation and a `createResource` still loading.
+ *
+ * @example
+ * ```ts
+ * html`
+ *   <${Suspense} fallback=${html`<p>loading...</p>`}>
+ *     <${Profile} />
+ *   </${Suspense}>`;
+ * ```
+ */
+export function Suspense(props) {
+    return createComponent(SuspenseImpl, props);
+}
+function SuspenseImpl(props) {
+    const boundary = createSuspenseBoundary();
+    // SuspenseList coordination, if any.
+    const listCtx = useContext(SuspenseListContext);
+    const listState = listCtx ? listCtx.register(boundary.inFallback) : undefined;
+    function instantiateOnce(val) {
+        if (val == null || typeof val === 'boolean')
+            return null;
+        if (typeof val === 'function' && isComponent(val) && !isSignal(val))
+            return val();
+        return val;
+    }
+    // Build the fallback off the hydration cursor, it isn't shown when the server
+    // already rendered content, so it must not adopt (and duplicate) server nodes.
+    const fallback = runWithoutHydration(() => instantiateOnce(props.fallback ?? null));
+    // Read the children under the boundary so the memos they create capture its owner;
+    // then a suspended resource read inside them throws to this boundary, not the parent.
+    //
+    // `readChildren`, not a bare `props.children` read: a component child arrives as a THUNK
+    // that instantiates when called, so reading the prop alone hands back a function and the
+    // component never runs here. It would then be instantiated later, downstream of the output
+    // memo, where a suspend has no boundary that can re-run it, the failure that produced an
+    // empty node on a client navigation into a not-yet-loaded lazy route: no fallback, no
+    // content, no error. `readChildren` unwraps the thunks (so the lazy component runs under
+    // this boundary), stops at signals so dynamic children stay reactive, and memoises the
+    // result so the tracking effect below and the output render the same instantiation.
+    const children = provideSuspense(boundary, () => readChildren(() => props.children));
+    // Instantiate the children now, in their own effect under the boundary. A suspended
+    // resource read inside them throws here synchronously, a sibling of the output memo
+    // below, so the increment reschedules the output cleanly (matching the canary). If we
+    // only rendered children through the output's return, the resource read would be nested
+    // inside the output's own insert effect, which then never re-runs to show the fallback.
+    //
+    // Follow NESTED accessors, not just the outer one: the compiler wraps a dynamic child in
+    // its own memo, and `readChildren` stops at signals on purpose so they stay reactive. Stop
+    // at the outer read and a lazy component behind a condition is never instantiated here
+    // it runs later, downstream, where its suspend reaches no boundary. Reading a memo is
+    // idempotent (it caches, and the output reads the same one), so following the chain costs
+    // nothing and cannot duplicate the subtree.
+    const track = (value, depth) => {
+        if (depth > 8)
+            return;
+        if (Array.isArray(value)) {
+            for (const x of value)
+                track(x, depth + 1);
+        }
+        else if (typeof value === 'function' && isSignal(value)) {
+            track(value(), depth + 1);
+        }
+    };
+    provideSuspense(boundary, () => {
+        createRenderEffect(() => track(children, 0));
+    });
+    // A raw promise child: track it directly on the boundary.
+    const [resolved, setResolved] = createSignal(undefined);
+    const childIsPromise = isPromise(children);
+    if (childIsPromise) {
+        boundary.increment();
+        children.then((v) => {
+            setResolved(() => v);
+            boundary.decrement();
+        }, () => boundary.decrement());
+    }
+    return createMemo(() => {
+        const showFallback = listState ? listState.showFallback() : boundary.inFallback();
+        if (showFallback)
+            return fallback;
+        if (childIsPromise)
+            return resolved();
+        return children;
+    });
+}
+/**
+ * Order how a group of sibling `Suspense` boundaries reveal themselves.
+ *
+ * Without it, each boundary swaps its fallback for content the moment its own work
+ * finishes, so a list of independently-loading rows appears in whatever order the
+ * network happened to return. `revealOrder` imposes one instead.
+ *
+ * `forwards` and `backwards` hold a boundary in its fallback until the ones before it in
+ * that direction have resolved. `together`, the default, holds all of them until every
+ * one has. `tail` decides what the unrevealed ones show: `collapsed` keeps only the next
+ * fallback, `hidden` shows none.
+ *
+ * @example
+ * ```ts
+ * html`
+ *   <${SuspenseList} revealOrder="forwards" tail="collapsed">
+ *     <${Suspense} fallback=${skeleton}><${Row} id=${1} /></${Suspense}>
+ *     <${Suspense} fallback=${skeleton}><${Row} id=${2} /></${Suspense}>
+ *   </${SuspenseList}>`;
+ * ```
+ */
+export function SuspenseList(props) {
+    return createComponent(SuspenseListImpl, props);
+}
+function SuspenseListImpl(props) {
+    const { revealOrder = 'together', tail } = props;
+    const registrations = [];
+    function coordinateReveal() {
+        if (revealOrder === 'together') {
+            const allResolved = registrations.every((r) => !r.inFallback());
+            registrations.forEach((r) => {
+                r.setShowContent(allResolved);
+                r.setShowFallback(!allResolved);
+            });
+        }
+        else {
+            const items = revealOrder === 'backwards' ? [...registrations].reverse() : registrations;
+            let blocked = false;
+            for (const r of items) {
+                if (blocked || r.inFallback()) {
+                    blocked = true;
+                    r.setShowContent(false);
+                    r.setShowFallback(tail !== 'hidden');
+                }
+                else {
+                    r.setShowContent(true);
+                    r.setShowFallback(false);
+                }
+            }
+        }
+    }
+    const coordinator = {
+        register: (inFallback) => {
+            const [showContent, setShowContent] = createSignal(true);
+            const [showFallback, setShowFallback] = createSignal(false);
+            registrations.push({ inFallback, setShowContent, setShowFallback });
+            createEffect(() => {
+                inFallback();
+                coordinateReveal();
+            });
+            return { showContent, showFallback };
+        },
+    };
+    return SuspenseListContext.Provider({
+        value: coordinator,
+        children: props.children,
+    });
+}
+asSuspense(Suspense);
+Object.defineProperty(Suspense, '__suspense', { value: true, enumerable: true });
+export { isNode, isLitResult, isPromise, isJSXElement };