@b9g/crank 0.6.0 → 0.7.0

package/_utils.d.ts

@@ -0,0 +1,14 @@
+export declare function wrap<T>(value: Array<T> | T | undefined): Array<T>;
+export declare function unwrap<T>(arr: Array<T>): Array<T> | T | undefined;
+export type NonStringIterable<T> = Iterable<T> & object;
+/**
+ * Ensures a value is an array.
+ *
+ * This function does the same thing as wrap() above except it handles nulls
+ * and iterables, so it is appropriate for wrapping user-provided element
+ * children.
+ */
+export declare function arrayify<T>(value: NonStringIterable<T> | T | null | undefined): Array<T>;
+export declare function isIteratorLike(value: any): value is Iterator<unknown> | AsyncIterator<unknown>;
+export declare function isPromiseLike(value: any): value is PromiseLike<unknown>;
+export declare function safeRace<T>(contenders: Iterable<T | PromiseLike<T>>): Promise<Awaited<T>>;

package/async.cjs

@@ -0,0 +1,237 @@
+'use strict';
+
+var crank = require('./crank.cjs');
+require('./event-target.cjs');
+
+/**
+ * Creates a lazy-loaded component from an initializer function.
+ *
+ * @param initializer - Function that returns a Promise resolving to a component or module
+ * @returns A component that loads the target component on first render
+ *
+ * @example
+ * ```jsx
+ * const LazyComponent = lazy(() => import('./MyComponent'));
+ *
+ * <Suspense fallback={<div>Loading...</div>}>
+ *   <LazyComponent prop="value" />
+ * </Suspense>
+ * ```
+ */
+function lazy(initializer) {
+    return async function* LazyComponent(props) {
+        let Component = await initializer();
+        if (Component && typeof Component === "object" && "default" in Component) {
+            Component = Component.default;
+        }
+        if (typeof Component !== "function") {
+            throw new Error("Lazy component initializer must return a Component or a module with a default export that is a Component.");
+        }
+        for (props of this) {
+            yield crank.createElement(Component, props);
+        }
+    };
+}
+async function SuspenseEmpty() {
+    await new Promise((resolve) => setTimeout(resolve));
+    return null;
+}
+async function SuspenseFallback({ children, timeout, schedule, }) {
+    if (schedule) {
+        this.schedule(schedule);
+    }
+    await new Promise((resolve) => setTimeout(resolve, timeout));
+    return children;
+}
+function SuspenseChildren({ children, schedule, }) {
+    if (schedule) {
+        this.schedule(schedule);
+    }
+    return children;
+}
+/**
+ * A component that displays a fallback while its children are loading.
+ *
+ * When used within a SuspenseList, coordinates with siblings to control
+ * reveal order and fallback behavior.
+ *
+ * @param children - The content to display when loading is complete
+ * @param fallback - The content to display while children are loading
+ * @param timeout - Time in milliseconds before showing fallback (defaults to
+ * 300ms standalone, or inherits from SuspenseList)
+ *
+ * @example
+ * ```jsx
+ * <Suspense fallback={<div>Loading...</div>}>
+ *   <AsyncComponent />
+ * </Suspense>
+ * ```
+ */
+async function* Suspense({ children, fallback, timeout, }) {
+    const controller = this.consume(SuspenseListController);
+    if (controller) {
+        controller.register(this);
+    }
+    this.provide(SuspenseListController, undefined);
+    let initial = true;
+    for await ({ children, fallback, timeout } of this) {
+        if (timeout == null) {
+            if (controller) {
+                timeout = controller.timeout;
+            }
+            else {
+                timeout = 300;
+            }
+        }
+        if (!controller) {
+            yield crank.createElement(SuspenseFallback, {
+                timeout: timeout,
+                children: fallback,
+            });
+            yield children;
+            continue;
+        }
+        if (controller.revealOrder !== "together") {
+            if (!controller.isHead(this)) {
+                yield crank.createElement(SuspenseEmpty);
+            }
+            if (controller.tail !== "hidden") {
+                yield crank.createElement(SuspenseFallback, {
+                    timeout: timeout,
+                    schedule: initial
+                        ? () => controller.scheduleFallback(this)
+                        : undefined,
+                    children: fallback,
+                });
+            }
+        }
+        yield crank.createElement(SuspenseChildren, {
+            schedule: initial ? () => controller.scheduleChildren(this) : undefined,
+            children,
+        });
+        initial = false;
+    }
+}
+const SuspenseListController = Symbol.for("SuspenseListController");
+/**
+ * Coordinates the reveal order of multiple <Suspense> children.
+ *
+ * Controls when child <Suspense> components show their content or fallbacks
+ * based on the specified reveal order. The <SuspenseList> resolves when
+ * coordination effort is complete (not necessarily when all content is
+ * loaded).
+ *
+ * @param revealOrder - How children should be revealed:
+ *   - "forwards" (default): Show children in document order, waiting for
+ *     predecessors
+ *   - "backwards": Show children in reverse order, waiting for successors
+ *   - "together": Show all children simultaneously when all are ready
+ *   In Crank, the default behavior of async components is to render together,
+ *   so "together" might not be necessary if you are not using <Suspense>
+ *   fallbacks.
+ * @param tail - How to handle fallbacks:
+ *   - "collapsed" (default): Show only the fallback for the next unresolved
+ *     Suspense component
+ *   - "hidden": Hide all fallbacks
+ *   Tail behavior only applies when revealOrder is not "together".
+ * @param timeout - Default timeout for Suspense children in milliseconds
+ * @param children - The elements containing Suspense components to coordinate.
+ *   Suspense components which are not rendered immediately (because they are
+ *   the children of another async component) will not be coordinated.
+ *
+ * @example
+ * ```jsx
+ * <SuspenseList revealOrder="forwards" tail="collapsed">
+ *   <Suspense fallback={<div>Loading A...</div>}>
+ *     <ComponentA />
+ *   </Suspense>
+ *   <Suspense fallback={<div>Loading B...</div>}>
+ *     <ComponentB />
+ *   </Suspense>
+ * </SuspenseList>
+ * ```
+ */
+function* SuspenseList({ revealOrder = "forwards", tail = "collapsed", timeout, children, }) {
+    let registering = true;
+    const suspenseItems = [];
+    const controller = {
+        timeout,
+        revealOrder,
+        tail,
+        register(ctx) {
+            if (registering) {
+                let childrenResolver;
+                const childrenPromise = new Promise((r) => (childrenResolver = r));
+                suspenseItems.push({
+                    ctx,
+                    childrenResolver: childrenResolver,
+                    childrenPromise,
+                });
+                return;
+            }
+        },
+        isHead(ctx) {
+            const index = suspenseItems.findIndex((item) => item.ctx === ctx);
+            if (index === -1) {
+                return false;
+            }
+            if (revealOrder === "forwards") {
+                return index === 0;
+            }
+            else if (revealOrder === "backwards") {
+                return index === suspenseItems.length - 1;
+            }
+            return false;
+        },
+        async scheduleFallback(ctx) {
+            const index = suspenseItems.findIndex((item) => item.ctx === ctx);
+            if (index === -1) {
+                return;
+            }
+            else if (revealOrder === "forwards") {
+                await Promise.all(suspenseItems.slice(0, index).map((item) => item.childrenPromise));
+            }
+            else if (revealOrder === "backwards") {
+                await Promise.all(suspenseItems.slice(index + 1).map((item) => item.childrenPromise));
+            }
+        },
+        async scheduleChildren(ctx) {
+            const index = suspenseItems.findIndex((item) => item.ctx === ctx);
+            if (index === -1) {
+                return;
+            }
+            // This children content is ready
+            suspenseItems[index].childrenResolver();
+            // Children coordination - determine when this content should show
+            if (revealOrder === "together") {
+                await Promise.all(suspenseItems.map((item) => item.childrenPromise));
+            }
+            else if (revealOrder === "forwards") {
+                await Promise.all(suspenseItems.slice(0, index + 1).map((item) => item.childrenPromise));
+            }
+            else if (revealOrder === "backwards") {
+                await Promise.all(suspenseItems.slice(index).map((item) => item.childrenPromise));
+            }
+        },
+    };
+    this.provide(SuspenseListController, controller);
+    for ({
+        revealOrder = "forwards",
+        tail = "collapsed",
+        timeout,
+        children,
+    } of this) {
+        registering = true;
+        // TODO: Is there a fixed amount of microtasks that we can wait for?
+        setTimeout(() => (registering = false));
+        controller.timeout = timeout;
+        controller.revealOrder = revealOrder;
+        controller.tail = tail;
+        yield children;
+    }
+}
+
+exports.Suspense = Suspense;
+exports.SuspenseList = SuspenseList;
+exports.lazy = lazy;
+//# sourceMappingURL=async.cjs.map

package/async.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.cjs","sources":["../src/async.ts"],"sourcesContent":["import type {Children, Component, Context} from \"./crank.js\";\nimport {createElement} from \"./crank.js\";\n\n/**\n * Creates a lazy-loaded component from an initializer function.\n *\n * @param initializer - Function that returns a Promise resolving to a component or module\n * @returns A component that loads the target component on first render\n *\n * @example\n * ```jsx\n * const LazyComponent = lazy(() => import('./MyComponent'));\n *\n * <Suspense fallback={<div>Loading...</div>}>\n *   <LazyComponent prop=\"value\" />\n * </Suspense>\n * ```\n */\nexport function lazy<T extends Component>(\n\tinitializer: () => Promise<T | {default: T}>,\n): T {\n\treturn async function* LazyComponent(\n\t\tthis: Context,\n\t\tprops: any,\n\t): AsyncGenerator<Children> {\n\t\tlet Component = await initializer();\n\t\tif (Component && typeof Component === \"object\" && \"default\" in Component) {\n\t\t\tComponent = Component.default;\n\t\t}\n\n\t\tif (typeof Component !== \"function\") {\n\t\t\tthrow new Error(\n\t\t\t\t\"Lazy component initializer must return a Component or a module with a default export that is a Component.\",\n\t\t\t);\n\t\t}\n\n\t\tfor (props of this) {\n\t\t\tyield createElement(Component, props);\n\t\t}\n\t} as unknown as T;\n}\n\nasync function SuspenseEmpty() {\n\tawait new Promise((resolve) => setTimeout(resolve));\n\treturn null;\n}\n\nasync function SuspenseFallback(\n\tthis: Context,\n\t{\n\t\tchildren,\n\t\ttimeout,\n\t\tschedule,\n\t}: {\n\t\tchildren: Children;\n\t\ttimeout: number;\n\t\tschedule?: () => Promise<unknown>;\n\t},\n): Promise<Children> {\n\tif (schedule) {\n\t\tthis.schedule(schedule);\n\t}\n\n\tawait new Promise((resolve) => setTimeout(resolve, timeout));\n\treturn children;\n}\n\nfunction SuspenseChildren(\n\tthis: Context,\n\t{\n\t\tchildren,\n\t\tschedule,\n\t}: {\n\t\tchildren: Children;\n\t\tschedule?: () => Promise<unknown>;\n\t},\n) {\n\tif (schedule) {\n\t\tthis.schedule(schedule);\n\t}\n\n\treturn children;\n}\n\n/**\n * A component that displays a fallback while its children are loading.\n *\n * When used within a SuspenseList, coordinates with siblings to control\n * reveal order and fallback behavior.\n *\n * @param children - The content to display when loading is complete\n * @param fallback - The content to display while children are loading\n * @param timeout - Time in milliseconds before showing fallback (defaults to\n * 300ms standalone, or inherits from SuspenseList)\n *\n * @example\n * ```jsx\n * <Suspense fallback={<div>Loading...</div>}>\n *   <AsyncComponent />\n * </Suspense>\n * ```\n */\nexport async function* Suspense(\n\tthis: Context,\n\t{\n\t\tchildren,\n\t\tfallback,\n\t\ttimeout,\n\t}: {children: Children; fallback: Children; timeout?: number},\n): AsyncGenerator<Children> {\n\tconst controller = this.consume(SuspenseListController);\n\tif (controller) {\n\t\tcontroller.register(this);\n\t}\n\n\tthis.provide(SuspenseListController, undefined);\n\tlet initial = true;\n\tfor await ({children, fallback, timeout} of this) {\n\t\tif (timeout == null) {\n\t\t\tif (controller) {\n\t\t\t\ttimeout = controller.timeout;\n\t\t\t} else {\n\t\t\t\ttimeout = 300;\n\t\t\t}\n\t\t}\n\n\t\tif (!controller) {\n\t\t\tyield createElement(SuspenseFallback, {\n\t\t\t\ttimeout: timeout!,\n\t\t\t\tchildren: fallback,\n\t\t\t});\n\t\t\tyield children;\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (controller.revealOrder !== \"together\") {\n\t\t\tif (!controller.isHead(this)) {\n\t\t\t\tyield createElement(SuspenseEmpty);\n\t\t\t}\n\n\t\t\tif (controller.tail !== \"hidden\") {\n\t\t\t\tyield createElement(SuspenseFallback, {\n\t\t\t\t\ttimeout: timeout!,\n\t\t\t\t\tschedule: initial\n\t\t\t\t\t\t? () => controller.scheduleFallback(this)\n\t\t\t\t\t\t: undefined,\n\t\t\t\t\tchildren: fallback,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\tyield createElement(SuspenseChildren, {\n\t\t\tschedule: initial ? () => controller.scheduleChildren(this) : undefined,\n\t\t\tchildren,\n\t\t});\n\n\t\tinitial = false;\n\t}\n}\n\nconst SuspenseListController = Symbol.for(\"SuspenseListController\");\n\ninterface SuspenseListController {\n\ttimeout?: number;\n\trevealOrder?: \"forwards\" | \"backwards\" | \"together\";\n\ttail?: \"collapsed\" | \"hidden\";\n\tregister(ctx: Context): void;\n\tisHead(ctx: Context): boolean;\n\tscheduleFallback(ctx: Context): Promise<void>;\n\tscheduleChildren(ctx: Context): Promise<void>;\n}\n\ndeclare global {\n\tnamespace Crank {\n\t\tinterface ProvisionMap {\n\t\t\t[SuspenseListController]: SuspenseListController;\n\t\t}\n\t}\n}\n\n/**\n * Coordinates the reveal order of multiple <Suspense> children.\n *\n * Controls when child <Suspense> components show their content or fallbacks\n * based on the specified reveal order. The <SuspenseList> resolves when\n * coordination effort is complete (not necessarily when all content is\n * loaded).\n *\n * @param revealOrder - How children should be revealed:\n *   - \"forwards\" (default): Show children in document order, waiting for\n *     predecessors\n *   - \"backwards\": Show children in reverse order, waiting for successors\n *   - \"together\": Show all children simultaneously when all are ready\n *   In Crank, the default behavior of async components is to render together,\n *   so \"together\" might not be necessary if you are not using <Suspense>\n *   fallbacks.\n * @param tail - How to handle fallbacks:\n *   - \"collapsed\" (default): Show only the fallback for the next unresolved\n *     Suspense component\n *   - \"hidden\": Hide all fallbacks\n *   Tail behavior only applies when revealOrder is not \"together\".\n * @param timeout - Default timeout for Suspense children in milliseconds\n * @param children - The elements containing Suspense components to coordinate.\n *   Suspense components which are not rendered immediately (because they are\n *   the children of another async component) will not be coordinated.\n *\n * @example\n * ```jsx\n * <SuspenseList revealOrder=\"forwards\" tail=\"collapsed\">\n *   <Suspense fallback={<div>Loading A...</div>}>\n *     <ComponentA />\n *   </Suspense>\n *   <Suspense fallback={<div>Loading B...</div>}>\n *     <ComponentB />\n *   </Suspense>\n * </SuspenseList>\n * ```\n */\nexport function* SuspenseList(\n\tthis: Context,\n\t{\n\t\trevealOrder = \"forwards\",\n\t\ttail = \"collapsed\",\n\t\ttimeout,\n\t\tchildren,\n\t}: {\n\t\trevealOrder?: \"forwards\" | \"backwards\" | \"together\";\n\t\ttail?: \"collapsed\" | \"hidden\";\n\t\ttimeout?: number;\n\t\tchildren: Children;\n\t},\n): Generator<Children> {\n\tlet registering = true;\n\tconst suspenseItems: Array<{\n\t\tctx: Context;\n\t\tchildrenResolver: () => void;\n\t\tchildrenPromise: Promise<void>;\n\t}> = [];\n\n\tconst controller: SuspenseListController = {\n\t\ttimeout,\n\t\trevealOrder,\n\t\ttail,\n\t\tregister(ctx: Context) {\n\t\t\tif (registering) {\n\t\t\t\tlet childrenResolver: () => void;\n\n\t\t\t\tconst childrenPromise = new Promise<void>(\n\t\t\t\t\t(r) => (childrenResolver = r),\n\t\t\t\t);\n\n\t\t\t\tsuspenseItems.push({\n\t\t\t\t\tctx,\n\t\t\t\t\tchildrenResolver: childrenResolver!,\n\t\t\t\t\tchildrenPromise,\n\t\t\t\t});\n\t\t\t\treturn;\n\t\t\t}\n\t\t},\n\n\t\tisHead(ctx: Context): boolean {\n\t\t\tconst index = suspenseItems.findIndex((item) => item.ctx === ctx);\n\t\t\tif (index === -1) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tif (revealOrder === \"forwards\") {\n\t\t\t\treturn index === 0;\n\t\t\t} else if (revealOrder === \"backwards\") {\n\t\t\t\treturn index === suspenseItems.length - 1;\n\t\t\t}\n\n\t\t\treturn false;\n\t\t},\n\n\t\tasync scheduleFallback(ctx: Context) {\n\t\t\tconst index = suspenseItems.findIndex((item) => item.ctx === ctx);\n\t\t\tif (index === -1) {\n\t\t\t\treturn;\n\t\t\t} else if (revealOrder === \"forwards\") {\n\t\t\t\tawait Promise.all(\n\t\t\t\t\tsuspenseItems.slice(0, index).map((item) => item.childrenPromise),\n\t\t\t\t);\n\t\t\t} else if (revealOrder === \"backwards\") {\n\t\t\t\tawait Promise.all(\n\t\t\t\t\tsuspenseItems.slice(index + 1).map((item) => item.childrenPromise),\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\n\t\tasync scheduleChildren(ctx: Context) {\n\t\t\tconst index = suspenseItems.findIndex((item) => item.ctx === ctx);\n\t\t\tif (index === -1) {\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\t// This children content is ready\n\t\t\tsuspenseItems[index].childrenResolver();\n\t\t\t// Children coordination - determine when this content should show\n\t\t\tif (revealOrder === \"together\") {\n\t\t\t\tawait Promise.all(suspenseItems.map((item) => item.childrenPromise));\n\t\t\t} else if (revealOrder === \"forwards\") {\n\t\t\t\tawait Promise.all(\n\t\t\t\t\tsuspenseItems.slice(0, index + 1).map((item) => item.childrenPromise),\n\t\t\t\t);\n\t\t\t} else if (revealOrder === \"backwards\") {\n\t\t\t\tawait Promise.all(\n\t\t\t\t\tsuspenseItems.slice(index).map((item) => item.childrenPromise),\n\t\t\t\t);\n\t\t\t}\n\t\t},\n\t};\n\n\tthis.provide(SuspenseListController, controller);\n\tfor ({\n\t\trevealOrder = \"forwards\",\n\t\ttail = \"collapsed\",\n\t\ttimeout,\n\t\tchildren,\n\t} of this) {\n\t\tregistering = true;\n\t\t// TODO: Is there a fixed amount of microtasks that we can wait for?\n\t\tsetTimeout(() => (registering = false));\n\t\tcontroller.timeout = timeout;\n\t\tcontroller.revealOrder = revealOrder;\n\t\tcontroller.tail = tail;\n\t\tyield children;\n\t}\n}\n"],"names":["createElement"],"mappings":"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"}

package/async.d.ts

@@ -0,0 +1,104 @@
+import type { Children, Component, Context } from "./crank.js";
+/**
+ * Creates a lazy-loaded component from an initializer function.
+ *
+ * @param initializer - Function that returns a Promise resolving to a component or module
+ * @returns A component that loads the target component on first render
+ *
+ * @example
+ * ```jsx
+ * const LazyComponent = lazy(() => import('./MyComponent'));
+ *
+ * <Suspense fallback={<div>Loading...</div>}>
+ *   <LazyComponent prop="value" />
+ * </Suspense>
+ * ```
+ */
+export declare function lazy<T extends Component>(initializer: () => Promise<T | {
+    default: T;
+}>): T;
+/**
+ * A component that displays a fallback while its children are loading.
+ *
+ * When used within a SuspenseList, coordinates with siblings to control
+ * reveal order and fallback behavior.
+ *
+ * @param children - The content to display when loading is complete
+ * @param fallback - The content to display while children are loading
+ * @param timeout - Time in milliseconds before showing fallback (defaults to
+ * 300ms standalone, or inherits from SuspenseList)
+ *
+ * @example
+ * ```jsx
+ * <Suspense fallback={<div>Loading...</div>}>
+ *   <AsyncComponent />
+ * </Suspense>
+ * ```
+ */
+export declare function Suspense(this: Context, { children, fallback, timeout, }: {
+    children: Children;
+    fallback: Children;
+    timeout?: number;
+}): AsyncGenerator<Children>;
+declare const SuspenseListController: unique symbol;
+interface SuspenseListController {
+    timeout?: number;
+    revealOrder?: "forwards" | "backwards" | "together";
+    tail?: "collapsed" | "hidden";
+    register(ctx: Context): void;
+    isHead(ctx: Context): boolean;
+    scheduleFallback(ctx: Context): Promise<void>;
+    scheduleChildren(ctx: Context): Promise<void>;
+}
+declare global {
+    namespace Crank {
+        interface ProvisionMap {
+            [SuspenseListController]: SuspenseListController;
+        }
+    }
+}
+/**
+ * Coordinates the reveal order of multiple <Suspense> children.
+ *
+ * Controls when child <Suspense> components show their content or fallbacks
+ * based on the specified reveal order. The <SuspenseList> resolves when
+ * coordination effort is complete (not necessarily when all content is
+ * loaded).
+ *
+ * @param revealOrder - How children should be revealed:
+ *   - "forwards" (default): Show children in document order, waiting for
+ *     predecessors
+ *   - "backwards": Show children in reverse order, waiting for successors
+ *   - "together": Show all children simultaneously when all are ready
+ *   In Crank, the default behavior of async components is to render together,
+ *   so "together" might not be necessary if you are not using <Suspense>
+ *   fallbacks.
+ * @param tail - How to handle fallbacks:
+ *   - "collapsed" (default): Show only the fallback for the next unresolved
+ *     Suspense component
+ *   - "hidden": Hide all fallbacks
+ *   Tail behavior only applies when revealOrder is not "together".
+ * @param timeout - Default timeout for Suspense children in milliseconds
+ * @param children - The elements containing Suspense components to coordinate.
+ *   Suspense components which are not rendered immediately (because they are
+ *   the children of another async component) will not be coordinated.
+ *
+ * @example
+ * ```jsx
+ * <SuspenseList revealOrder="forwards" tail="collapsed">
+ *   <Suspense fallback={<div>Loading A...</div>}>
+ *     <ComponentA />
+ *   </Suspense>
+ *   <Suspense fallback={<div>Loading B...</div>}>
+ *     <ComponentB />
+ *   </Suspense>
+ * </SuspenseList>
+ * ```
+ */
+export declare function SuspenseList(this: Context, { revealOrder, tail, timeout, children, }: {
+    revealOrder?: "forwards" | "backwards" | "together";
+    tail?: "collapsed" | "hidden";
+    timeout?: number;
+    children: Children;
+}): Generator<Children>;
+export {};

package/async.js

@@ -0,0 +1,234 @@
+/// <reference types="async.d.ts" />
+import { createElement } from './crank.js';
+import './event-target.js';
+
+/**
+ * Creates a lazy-loaded component from an initializer function.
+ *
+ * @param initializer - Function that returns a Promise resolving to a component or module
+ * @returns A component that loads the target component on first render
+ *
+ * @example
+ * ```jsx
+ * const LazyComponent = lazy(() => import('./MyComponent'));
+ *
+ * <Suspense fallback={<div>Loading...</div>}>
+ *   <LazyComponent prop="value" />
+ * </Suspense>
+ * ```
+ */
+function lazy(initializer) {
+    return async function* LazyComponent(props) {
+        let Component = await initializer();
+        if (Component && typeof Component === "object" && "default" in Component) {
+            Component = Component.default;
+        }
+        if (typeof Component !== "function") {
+            throw new Error("Lazy component initializer must return a Component or a module with a default export that is a Component.");
+        }
+        for (props of this) {
+            yield createElement(Component, props);
+        }
+    };
+}
+async function SuspenseEmpty() {
+    await new Promise((resolve) => setTimeout(resolve));
+    return null;
+}
+async function SuspenseFallback({ children, timeout, schedule, }) {
+    if (schedule) {
+        this.schedule(schedule);
+    }
+    await new Promise((resolve) => setTimeout(resolve, timeout));
+    return children;
+}
+function SuspenseChildren({ children, schedule, }) {
+    if (schedule) {
+        this.schedule(schedule);
+    }
+    return children;
+}
+/**
+ * A component that displays a fallback while its children are loading.
+ *
+ * When used within a SuspenseList, coordinates with siblings to control
+ * reveal order and fallback behavior.
+ *
+ * @param children - The content to display when loading is complete
+ * @param fallback - The content to display while children are loading
+ * @param timeout - Time in milliseconds before showing fallback (defaults to
+ * 300ms standalone, or inherits from SuspenseList)
+ *
+ * @example
+ * ```jsx
+ * <Suspense fallback={<div>Loading...</div>}>
+ *   <AsyncComponent />
+ * </Suspense>
+ * ```
+ */
+async function* Suspense({ children, fallback, timeout, }) {
+    const controller = this.consume(SuspenseListController);
+    if (controller) {
+        controller.register(this);
+    }
+    this.provide(SuspenseListController, undefined);
+    let initial = true;
+    for await ({ children, fallback, timeout } of this) {
+        if (timeout == null) {
+            if (controller) {
+                timeout = controller.timeout;
+            }
+            else {
+                timeout = 300;
+            }
+        }
+        if (!controller) {
+            yield createElement(SuspenseFallback, {
+                timeout: timeout,
+                children: fallback,
+            });
+            yield children;
+            continue;
+        }
+        if (controller.revealOrder !== "together") {
+            if (!controller.isHead(this)) {
+                yield createElement(SuspenseEmpty);
+            }
+            if (controller.tail !== "hidden") {
+                yield createElement(SuspenseFallback, {
+                    timeout: timeout,
+                    schedule: initial
+                        ? () => controller.scheduleFallback(this)
+                        : undefined,
+                    children: fallback,
+                });
+            }
+        }
+        yield createElement(SuspenseChildren, {
+            schedule: initial ? () => controller.scheduleChildren(this) : undefined,
+            children,
+        });
+        initial = false;
+    }
+}
+const SuspenseListController = Symbol.for("SuspenseListController");
+/**
+ * Coordinates the reveal order of multiple <Suspense> children.
+ *
+ * Controls when child <Suspense> components show their content or fallbacks
+ * based on the specified reveal order. The <SuspenseList> resolves when
+ * coordination effort is complete (not necessarily when all content is
+ * loaded).
+ *
+ * @param revealOrder - How children should be revealed:
+ *   - "forwards" (default): Show children in document order, waiting for
+ *     predecessors
+ *   - "backwards": Show children in reverse order, waiting for successors
+ *   - "together": Show all children simultaneously when all are ready
+ *   In Crank, the default behavior of async components is to render together,
+ *   so "together" might not be necessary if you are not using <Suspense>
+ *   fallbacks.
+ * @param tail - How to handle fallbacks:
+ *   - "collapsed" (default): Show only the fallback for the next unresolved
+ *     Suspense component
+ *   - "hidden": Hide all fallbacks
+ *   Tail behavior only applies when revealOrder is not "together".
+ * @param timeout - Default timeout for Suspense children in milliseconds
+ * @param children - The elements containing Suspense components to coordinate.
+ *   Suspense components which are not rendered immediately (because they are
+ *   the children of another async component) will not be coordinated.
+ *
+ * @example
+ * ```jsx
+ * <SuspenseList revealOrder="forwards" tail="collapsed">
+ *   <Suspense fallback={<div>Loading A...</div>}>
+ *     <ComponentA />
+ *   </Suspense>
+ *   <Suspense fallback={<div>Loading B...</div>}>
+ *     <ComponentB />
+ *   </Suspense>
+ * </SuspenseList>
+ * ```
+ */
+function* SuspenseList({ revealOrder = "forwards", tail = "collapsed", timeout, children, }) {
+    let registering = true;
+    const suspenseItems = [];
+    const controller = {
+        timeout,
+        revealOrder,
+        tail,
+        register(ctx) {
+            if (registering) {
+                let childrenResolver;
+                const childrenPromise = new Promise((r) => (childrenResolver = r));
+                suspenseItems.push({
+                    ctx,
+                    childrenResolver: childrenResolver,
+                    childrenPromise,
+                });
+                return;
+            }
+        },
+        isHead(ctx) {
+            const index = suspenseItems.findIndex((item) => item.ctx === ctx);
+            if (index === -1) {
+                return false;
+            }
+            if (revealOrder === "forwards") {
+                return index === 0;
+            }
+            else if (revealOrder === "backwards") {
+                return index === suspenseItems.length - 1;
+            }
+            return false;
+        },
+        async scheduleFallback(ctx) {
+            const index = suspenseItems.findIndex((item) => item.ctx === ctx);
+            if (index === -1) {
+                return;
+            }
+            else if (revealOrder === "forwards") {
+                await Promise.all(suspenseItems.slice(0, index).map((item) => item.childrenPromise));
+            }
+            else if (revealOrder === "backwards") {
+                await Promise.all(suspenseItems.slice(index + 1).map((item) => item.childrenPromise));
+            }
+        },
+        async scheduleChildren(ctx) {
+            const index = suspenseItems.findIndex((item) => item.ctx === ctx);
+            if (index === -1) {
+                return;
+            }
+            // This children content is ready
+            suspenseItems[index].childrenResolver();
+            // Children coordination - determine when this content should show
+            if (revealOrder === "together") {
+                await Promise.all(suspenseItems.map((item) => item.childrenPromise));
+            }
+            else if (revealOrder === "forwards") {
+                await Promise.all(suspenseItems.slice(0, index + 1).map((item) => item.childrenPromise));
+            }
+            else if (revealOrder === "backwards") {
+                await Promise.all(suspenseItems.slice(index).map((item) => item.childrenPromise));
+            }
+        },
+    };
+    this.provide(SuspenseListController, controller);
+    for ({
+        revealOrder = "forwards",
+        tail = "collapsed",
+        timeout,
+        children,
+    } of this) {
+        registering = true;
+        // TODO: Is there a fixed amount of microtasks that we can wait for?
+        setTimeout(() => (registering = false));
+        controller.timeout = timeout;
+        controller.revealOrder = revealOrder;
+        controller.tail = tail;
+        yield children;
+    }
+}
+
+export { Suspense, SuspenseList, lazy };
+//# sourceMappingURL=async.js.map