@fluixi/core 1.0.0-alpha.83 → 1.0.0-alpha.84

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

@@ -1 +1,67 @@
-"use strict";var d=Object.defineProperty;var u=Object.getOwnPropertyDescriptor;var l=Object.getOwnPropertyNames;var y=Object.prototype.hasOwnProperty;var C=(e,n)=>{for(var r in n)d(e,r,{get:n[r],enumerable:!0})},P=(e,n,r,a)=>{if(n&&typeof n=="object"||typeof n=="function")for(let o of l(n))!y.call(e,o)&&o!==r&&d(e,o,{get:()=>n[o],enumerable:!(a=u(n,o))||a.enumerable});return e};var z=e=>P(d({},"__esModule",{value:!0}),e);var h={};C(h,{lazy:()=>T});module.exports=z(h);var m=require("@fluixi/dom"),i=require("@fluixi/reactive/signal");function c(e){if(e!=null&&(typeof e=="object"||typeof e=="function"))try{e.$lazy=!0}catch{}return e}function T(e,n){let r,a,o;function f(){return a||(a=e().then(p=>r=p.default)),a}n?.preload&&f();let s=(p=>{if(r){let t=r;return c((0,i.untrack)(()=>t(p)))}if(!o){let[t]=(0,i.createResource)(()=>f(),{transport:!1});if(o=t,t.error)throw t.error}return(0,i.createMemo)(()=>{let t=o();return t?c((0,m.createComponent)(t,p)):void 0})});return s.preload=()=>f().then(()=>{}),s.$lazy=!0,s.loader=e,s}
+"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/lazy.ts
+var lazy_exports = {};
+__export(lazy_exports, {
+  lazy: () => lazy
+});
+module.exports = __toCommonJS(lazy_exports);
+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;
+}

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

@@ -5,7 +5,7 @@
  *  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
+ *  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.
@@ -20,6 +20,27 @@ export interface LazyOptions {
     /** If true, start loading immediately when lazy() is called */
     preload?: boolean;
 }
+/**
+ * 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 declare function lazy<T extends (...args: any[]) => any>(loader: () => Promise<{
     default: T;
 }>, options?: LazyOptions): T & {

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

@@ -1 +1 @@
-{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../../../../src/lib/render/lazy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAmB,MAAM,aAAa,CAAC;AAUzE,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,cAAc,IAAI,MAAM,OAAO,CAAC;IAC5D,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;CACvB,CAAC,CAAC;AAEH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAmBD,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACpD,MAAM,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,EACrC,OAAO,CAAC,EAAE,WAAW,GACpB,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA2DtC"}
+{"version":3,"file":"lazy.d.ts","sourceRoot":"","sources":["../../../../src/lib/render/lazy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,cAAc,EAAmB,MAAM,aAAa,CAAC;AAUzE,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,cAAc,IAAI,MAAM,OAAO,CAAC;IAC5D,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;CACvB,CAAC,CAAC;AAEH,MAAM,WAAW,WAAW;IAC1B,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,GAAG,CAAC;IACf,+DAA+D;IAC/D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAmBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,IAAI,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,EACpD,MAAM,EAAE,MAAM,OAAO,CAAC;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,EACrC,OAAO,CAAC,EAAE,WAAW,GACpB,CAAC,GAAG;IAAE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CA2DtC"}

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

@@ -5,7 +5,7 @@
  *  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
+ *  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.
@@ -28,10 +28,31 @@ function fromChunk(value) {
     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
+    // 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.
@@ -50,7 +71,7 @@ export function lazy(loader, options) {
         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.
+        // Render straight through: under hydration this consumes the cursor in place.
         if (resolved) {
             const C = resolved;
             return fromChunk(untrack(() => C(props)));
@@ -59,7 +80,7 @@ export function lazy(loader, options) {
         // 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
+            // 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.

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

@@ -1 +1,50 @@
-import{createComponent as d}from"@fluixi/dom";import{untrack as c,createMemo as m,createResource as u}from"@fluixi/reactive/signal";function p(e){if(e!=null&&(typeof e=="object"||typeof e=="function"))try{e.$lazy=!0}catch{}return e}function T(e,f){let t,a,i;function s(){return a||(a=e().then(r=>t=r.default)),a}f?.preload&&s();let o=(r=>{if(t){let n=t;return p(c(()=>n(r)))}if(!i){let[n]=u(()=>s(),{transport:!1});if(i=n,n.error)throw n.error}return m(()=>{let n=i();return n?p(d(n,r)):void 0})});return o.preload=()=>s().then(()=>{}),o.$lazy=!0,o.loader=e,o}export{T as lazy};
+// 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

@@ -1 +1,141 @@
-"use strict";var b=Object.defineProperty;var w=Object.getOwnPropertyDescriptor;var C=Object.getOwnPropertyNames;var F=Object.prototype.hasOwnProperty;var P=(e,t)=>{for(var a in t)b(e,a,{get:t[a],enumerable:!0})},g=(e,t,a,i)=>{if(t&&typeof t=="object"||typeof t=="function")for(let c of C(t))!F.call(e,c)&&c!==a&&b(e,c,{get:()=>t[c],enumerable:!(i=w(t,c))||i.enumerable});return e};var A=e=>g(b({},"__esModule",{value:!0}),e);var O={};P(O,{$SUSPENSE:()=>L,Suspense:()=>S,SuspenseList:()=>N,isJSXElement:()=>E,isLitResult:()=>R,isNode:()=>x,isPromise:()=>h});module.exports=A(O);var n=require("@fluixi/reactive/signal"),l=require("@fluixi/dom"),L=Symbol.for("suspense");function x(e){return typeof window>"u"?!1:typeof Node=="function"&&e instanceof Node?!0:!!(e&&typeof e=="object"&&typeof e.nodeType=="number")}function R(e){return!e||typeof e!="object"?!1:!!(typeof e._$litType$<"u"||typeof e._$litDirective$<"u"||Array.isArray(e.strings)&&Array.isArray(e.values))}function h(e){return!!(e&&typeof e=="object"&&typeof e.then=="function"||e instanceof Promise)}function E(e){return!!(e&&typeof e=="object"&&"type"in e&&"props"in e)}var m=(0,n.createContext)(void 0,"suspense-list");function S(e){return(0,l.createComponent)(j,e)}function j(e){let t=(0,n.createSuspenseBoundary)(),a=(0,n.useContext)(m),i=a?a.register(t.inFallback):void 0;function c(o){return o==null||typeof o=="boolean"?null:typeof o=="function"&&(0,l.isComponent)(o)&&!(0,n.isSignal)(o)?o():o}let d=(0,l.runWithoutHydration)(()=>c(e.fallback??null)),r=(0,n.provideSuspense)(t,()=>(0,n.readChildren)(()=>e.children)),s=(o,y)=>{if(!(y>8))if(Array.isArray(o))for(let k of o)s(k,y+1);else typeof o=="function"&&(0,n.isSignal)(o)&&s(o(),y+1)};(0,n.provideSuspense)(t,()=>{(0,n.createRenderEffect)(()=>s(r,0))});let[f,p]=(0,n.createSignal)(void 0),u=h(r);return u&&(t.increment(),r.then(o=>{p(()=>o),t.decrement()},()=>t.decrement())),(0,n.createMemo)(()=>(i?i.showFallback():t.inFallback())?d:u?f():r)}function N(e){return(0,l.createComponent)($,e)}function $(e){let{revealOrder:t="together",tail:a}=e,i=[];function c(){if(t==="together"){let r=i.every(s=>!s.inFallback());i.forEach(s=>{s.setShowContent(r),s.setShowFallback(!r)})}else{let r=t==="backwards"?[...i].reverse():i,s=!1;for(let f of r)s||f.inFallback()?(s=!0,f.setShowContent(!1),f.setShowFallback(a!=="hidden")):(f.setShowContent(!0),f.setShowFallback(!1))}}let d={register:r=>{let[s,f]=(0,n.createSignal)(!0),[p,u]=(0,n.createSignal)(!1);return i.push({inFallback:r,setShowContent:f,setShowFallback:u}),(0,n.createEffect)(()=>{r(),c()}),{showContent:s,showFallback:p}}};return m.Provider({value:d,children:e.children})}(0,l.asSuspense)(S);Object.defineProperty(S,"__suspense",{value:!0,enumerable:!0});
+"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

@@ -19,7 +19,47 @@ 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

@@ -1 +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,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,GAAG,CAElD;AA+ED,wBAAgB,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,GAAG,CAE1D;AAwDD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC"}
+{"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

@@ -29,6 +29,25 @@ 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);
 }
@@ -44,30 +63,30 @@ function SuspenseImpl(props) {
             return val();
         return val;
     }
-    // Build the fallback off the hydration cursor — it isn't shown when the server
+    // 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.
+    // 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
+    // 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
+    // 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 —
+    // 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.
@@ -104,6 +123,27 @@ function SuspenseImpl(props) {
         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);
 }

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

@@ -1 +1,136 @@
-import{createSignal as p,createMemo as w,createEffect as C,createRenderEffect as F,isSignal as y,readChildren as P,useContext as g,createContext as A,createSuspenseBoundary as L,provideSuspense as b}from"@fluixi/reactive/signal";import{asSuspense as x,isComponent as R,createComponent as S,runWithoutHydration as E}from"@fluixi/dom";var _=Symbol.for("suspense");function B(e){return typeof window>"u"?!1:typeof Node=="function"&&e instanceof Node?!0:!!(e&&typeof e=="object"&&typeof e.nodeType=="number")}function I(e){return!e||typeof e!="object"?!1:!!(typeof e._$litType$<"u"||typeof e._$litDirective$<"u"||Array.isArray(e.strings)&&Array.isArray(e.values))}function j(e){return!!(e&&typeof e=="object"&&typeof e.then=="function"||e instanceof Promise)}function D(e){return!!(e&&typeof e=="object"&&"type"in e&&"props"in e)}var h=A(void 0,"suspense-list");function m(e){return S(N,e)}function N(e){let s=L(),a=g(h),i=a?a.register(s.inFallback):void 0;function f(n){return n==null||typeof n=="boolean"?null:typeof n=="function"&&R(n)&&!y(n)?n():n}let l=E(()=>f(e.fallback??null)),o=b(s,()=>P(()=>e.children)),t=(n,d)=>{if(!(d>8))if(Array.isArray(n))for(let k of n)t(k,d+1);else typeof n=="function"&&y(n)&&t(n(),d+1)};b(s,()=>{F(()=>t(o,0))});let[r,u]=p(void 0),c=j(o);return c&&(s.increment(),o.then(n=>{u(()=>n),s.decrement()},()=>s.decrement())),w(()=>(i?i.showFallback():s.inFallback())?l:c?r():o)}function H(e){return S($,e)}function $(e){let{revealOrder:s="together",tail:a}=e,i=[];function f(){if(s==="together"){let o=i.every(t=>!t.inFallback());i.forEach(t=>{t.setShowContent(o),t.setShowFallback(!o)})}else{let o=s==="backwards"?[...i].reverse():i,t=!1;for(let r of o)t||r.inFallback()?(t=!0,r.setShowContent(!1),r.setShowFallback(a!=="hidden")):(r.setShowContent(!0),r.setShowFallback(!1))}}let l={register:o=>{let[t,r]=p(!0),[u,c]=p(!1);return i.push({inFallback:o,setShowContent:r,setShowFallback:c}),C(()=>{o(),f()}),{showContent:t,showFallback:u}}};return h.Provider({value:l,children:e.children})}x(m);Object.defineProperty(m,"__suspense",{value:!0,enumerable:!0});export{_ as $SUSPENSE,m as Suspense,H as SuspenseList,D as isJSXElement,I as isLitResult,B as isNode,j as isPromise};
+// src/lib/render/suspense.ts
+import {
+  createSignal,
+  createMemo,
+  createEffect,
+  createRenderEffect,
+  isSignal,
+  readChildren,
+  useContext,
+  createContext,
+  createSuspenseBoundary,
+  provideSuspense
+} from "@fluixi/reactive/signal";
+import {
+  asSuspense,
+  isComponent,
+  createComponent,
+  runWithoutHydration
+} from "@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 = createContext(void 0, "suspense-list");
+function Suspense(props) {
+  return createComponent(SuspenseImpl, props);
+}
+function SuspenseImpl(props) {
+  const boundary = createSuspenseBoundary();
+  const listCtx = 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" && isComponent(val) && !isSignal(val)) return val();
+    return val;
+  }
+  const fallback = runWithoutHydration(() => instantiateOnce(props.fallback ?? null));
+  const children = provideSuspense(boundary, () => 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" && isSignal(value)) {
+      track(value(), depth + 1);
+    }
+  };
+  provideSuspense(boundary, () => {
+    createRenderEffect(() => track(children, 0));
+  });
+  const [resolved, setResolved] = createSignal(void 0);
+  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;
+  });
+}
+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 {
+  $SUSPENSE,
+  Suspense,
+  SuspenseList,
+  isJSXElement,
+  isLitResult,
+  isNode,
+  isPromise
+};