@b9g/crank 0.7.0 → 0.7.2

package/crank.d.ts

@@ -193,17 +193,81 @@ declare class Retainer<TNode, TScope = unknown> {
     constructor(el: Element);
 }
 /**
- * Interface for adapting the rendering process to a specific target
- * environment. This interface is implemented by Renderer subclasses and passed
- * to the Renderer constructor.
+ * Interface for adapting the rendering process to a specific target environment.
+ *
+ * The RenderAdapter defines how Crank elements are mapped to nodes in your target
+ * rendering environment (DOM, Canvas, WebGL, Terminal, etc.). Each method handles
+ * a specific part of the element lifecycle, from creation to removal.
+ *
+ * @template TNode - The type representing a node in your target environment
+ * @template TScope - Additional context data passed down the component tree
+ * @template TRoot - The type of the root container (defaults to TNode)
+ * @template TResult - The type returned when reading element values (defaults to ElementValue<TNode>)
+ *
+ * @example
+ * ```typescript
+ * const adapter: RenderAdapter<MyNode, MyScope> = {
+ *   create: ({ tag, props }) => new MyNode(tag, props),
+ *   patch: ({ node, props }) => node.update(props),
+ *   arrange: ({ node, children }) => node.replaceChildren(children),
+ *   // ... other methods
+ * };
+ * ```
  */
 export interface RenderAdapter<TNode, TScope, TRoot extends TNode | undefined = TNode, TResult = ElementValue<TNode>> {
+    /**
+     * Creates a new node for the given element tag and props.
+     *
+     * This method is called when Crank encounters a new element that needs to be
+     * rendered for the first time. You should create and return a node appropriate
+     * for your target environment.
+     *
+     * @param data.tag - The element tag (e.g., "div", "sprite", or a symbol)
+     * @param data.tagName - String representation of the tag for debugging
+     * @param data.props - The element's props object
+     * @param data.scope - Current scope context (can be undefined)
+     * @returns A new node instance
+     *
+     * @example
+     * ```typescript
+     * create: ({ tag, props, scope }) => {
+     *   if (tag === "sprite") {
+     *     return new PIXI.Sprite(props.texture);
+     *   }
+     *   throw new Error(`Unknown tag: ${tag}`);
+     * }
+     * ```
+     */
     create(data: {
         tag: string | symbol;
         tagName: string;
         props: Record<string, any>;
         scope: TScope | undefined;
     }): TNode;
+    /**
+     * Adopts existing nodes during hydration.
+     *
+     * Called when hydrating server-rendered content or reusing existing nodes.
+     * Should return an array of child nodes if the provided node matches the
+     * expected tag, or undefined if hydration should fail.
+     *
+     * @param data.tag - The element tag being hydrated
+     * @param data.tagName - String representation of the tag
+     * @param data.props - The element's props
+     * @param data.node - The existing node to potentially adopt
+     * @param data.scope - Current scope context
+     * @returns Array of child nodes to hydrate, or undefined if adoption fails
+     *
+     * @example
+     * ```typescript
+     * adopt: ({ tag, node }) => {
+     *   if (node && node.tagName.toLowerCase() === tag) {
+     *     return Array.from(node.children);
+     *   }
+     *   return undefined; // Hydration mismatch
+     * }
+     * ```
+     */
     adopt(data: {
         tag: string | symbol;
         tagName: string;
@@ -211,23 +275,124 @@ export interface RenderAdapter<TNode, TScope, TRoot extends TNode | undefined =
         node: TNode | undefined;
         scope: TScope | undefined;
     }): Array<TNode> | undefined;
+    /**
+     * Creates or updates a text node.
+     *
+     * Called when rendering text content. Should create a new text node or
+     * update an existing one with the provided value.
+     *
+     * @param data.value - The text content to render
+     * @param data.scope - Current scope context
+     * @param data.oldNode - Previous text node to potentially reuse
+     * @param data.hydrationNodes - Nodes available during hydration
+     * @returns A text node containing the given value
+     *
+     * @example
+     * ```typescript
+     * text: ({ value, oldNode }) => {
+     *   if (oldNode && oldNode.text !== value) {
+     *     oldNode.text = value;
+     *     return oldNode;
+     *   }
+     *   return new TextNode(value);
+     * }
+     * ```
+     */
     text(data: {
         value: string;
         scope: TScope | undefined;
         oldNode: TNode | undefined;
         hydrationNodes: Array<TNode> | undefined;
     }): TNode;
+    /**
+     * Computes scope context for child elements.
+     *
+     * Called to determine what scope context should be passed to child elements.
+     * The scope can be used to pass rendering context like theme, coordinate systems,
+     * or namespaces down the component tree.
+     *
+     * @param data.tag - The element tag
+     * @param data.tagName - String representation of the tag
+     * @param data.props - The element's props
+     * @param data.scope - Current scope context
+     * @returns New scope for children, or undefined to inherit current scope
+     *
+     * @example
+     * ```typescript
+     * scope: ({ tag, props, scope }) => {
+     *   if (tag === "svg") {
+     *     return { ...scope, namespace: "http://www.w3.org/2000/svg" };
+     *   }
+     *   return scope;
+     * }
+     * ```
+     */
     scope(data: {
         tag: string | symbol;
         tagName: string;
         props: Record<string, any>;
         scope: TScope | undefined;
     }): TScope | undefined;
+    /**
+     * Handles raw values (strings or nodes) that bypass normal element processing.
+     *
+     * Called when rendering Raw elements or other direct node insertions.
+     * Should convert string values to appropriate nodes for your environment.
+     *
+     * @param data.value - Raw string or node value to render
+     * @param data.scope - Current scope context
+     * @param data.hydrationNodes - Nodes available during hydration
+     * @returns ElementValue that can be handled by arrange()
+     *
+     * @example
+     * ```typescript
+     * raw: ({ value, scope }) => {
+     *   if (typeof value === "string") {
+     *     const container = new Container();
+     *     container.innerHTML = value;
+     *     return Array.from(container.children);
+     *   }
+     *   return value;
+     * }
+     * ```
+     */
     raw(data: {
         value: string | TNode;
         scope: TScope | undefined;
         hydrationNodes: Array<TNode> | undefined;
     }): ElementValue<TNode>;
+    /**
+     * Updates a node's properties.
+     *
+     * Called when element props change. Should efficiently update only the
+     * properties that have changed. This is where you implement prop-to-attribute
+     * mapping, event listener binding, and other property synchronization.
+     *
+     * @param data.tag - The element tag
+     * @param data.tagName - String representation of the tag
+     * @param data.node - The node to update
+     * @param data.props - New props object
+     * @param data.oldProps - Previous props object (undefined for initial render)
+     * @param data.scope - Current scope context
+     * @param data.copyProps - Props to skip (used for copying between renderers)
+     * @param data.isHydrating - Whether currently hydrating
+     * @param data.quietProps - Props to not warn about during hydration
+     *
+     * @example
+     * ```typescript
+     * patch: ({ node, props, oldProps }) => {
+     *   for (const [key, value] of Object.entries(props)) {
+     *     if (oldProps?.[key] !== value) {
+     *       if (key.startsWith("on")) {
+     *         node.addEventListener(key.slice(2), value);
+     *       } else {
+     *         node[key] = value;
+     *       }
+     *     }
+     *   }
+     * }
+     * ```
+     */
     patch(data: {
         tag: string | symbol;
         tagName: string;
@@ -239,6 +404,32 @@ export interface RenderAdapter<TNode, TScope, TRoot extends TNode | undefined =
         isHydrating: boolean;
         quietProps: Set<string> | undefined;
     }): void;
+    /**
+     * Arranges child nodes within their parent.
+     *
+     * Called after child elements are rendered to organize them within their
+     * parent node. Should efficiently insert, move, or remove child nodes to
+     * match the provided children array.
+     *
+     * @param data.tag - The parent element tag
+     * @param data.tagName - String representation of the tag
+     * @param data.node - The parent node
+     * @param data.props - The parent element's props
+     * @param data.children - Array of child nodes in correct order
+     * @param data.oldProps - Previous props (for reference)
+     *
+     * @example
+     * ```typescript
+     * arrange: ({ node, children }) => {
+     *   // Remove existing children
+     *   node.removeChildren();
+     *   // Add new children in order
+     *   for (const child of children) {
+     *     node.addChild(child);
+     *   }
+     * }
+     * ```
+     */
     arrange(data: {
         tag: string | symbol;
         tagName: string;
@@ -247,12 +438,73 @@ export interface RenderAdapter<TNode, TScope, TRoot extends TNode | undefined =
         children: Array<TNode>;
         oldProps: Record<string, any> | undefined;
     }): void;
+    /**
+     * Removes a node from its parent.
+     *
+     * Called when an element is being unmounted. Should clean up the node
+     * and remove it from its parent if appropriate.
+     *
+     * @param data.node - The node to remove
+     * @param data.parentNode - The parent node
+     * @param data.isNested - Whether this is a nested removal (child of removed element)
+     *
+     * @example
+     * ```typescript
+     * remove: ({ node, parentNode, isNested }) => {
+     *   // Clean up event listeners, resources, etc.
+     *   node.cleanup?.();
+     *   // Remove from parent unless it's a nested removal
+     *   if (!isNested && parentNode.contains(node)) {
+     *     parentNode.removeChild(node);
+     *   }
+     * }
+     * ```
+     */
     remove(data: {
         node: TNode;
         parentNode: TNode;
         isNested: boolean;
     }): void;
+    /**
+     * Reads the final rendered value from an ElementValue.
+     *
+     * Called to extract the final result from rendered elements. This allows
+     * you to transform the internal node representation into the public API
+     * that users of your renderer will see.
+     *
+     * @param value - The ElementValue to read (array, single node, or undefined)
+     * @returns The public representation of the rendered value
+     *
+     * @example
+     * ```typescript
+     * read: (value) => {
+     *   if (Array.isArray(value)) {
+     *     return value.map(node => node.publicAPI);
+     *   }
+     *   return value?.publicAPI;
+     * }
+     * ```
+     */
     read(value: ElementValue<TNode>): TResult;
+    /**
+     * Performs final rendering to the root container.
+     *
+     * Called after the entire render cycle is complete. This is where you
+     * trigger the actual rendering/presentation in your target environment
+     * (e.g., calling render() on a canvas, flushing to the screen, etc.).
+     *
+     * @param root - The root container
+     *
+     * @example
+     * ```typescript
+     * finalize: (root) => {
+     *   // Trigger actual rendering
+     *   if (root instanceof PIXIApplication) {
+     *     root.render();
+     *   }
+     * }
+     * ```
+     */
     finalize(root: TRoot): void;
 }
 /**

package/crank.js

@@ -1,102 +1,6 @@
 /// <reference types="crank.d.ts" />
 import { removeEventTargetDelegates, addEventTargetDelegates, clearEventListeners, CustomEventTarget } from './event-target.js';
-
-function wrap(value) {
-    return value === undefined ? [] : Array.isArray(value) ? value : [value];
-}
-function unwrap(arr) {
-    return arr.length === 0 ? undefined : arr.length === 1 ? arr[0] : arr;
-}
-/**
- * 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.
- */
-function arrayify(value) {
-    return value == null
-        ? []
-        : Array.isArray(value)
-            ? value
-            : typeof value === "string" ||
-                typeof value[Symbol.iterator] !== "function"
-                ? [value]
-                : [...value];
-}
-function isIteratorLike(value) {
-    return value != null && typeof value.next === "function";
-}
-function isPromiseLike(value) {
-    return value != null && typeof value.then === "function";
-}
-function createRaceRecord(contender) {
-    const deferreds = new Set();
-    const record = { deferreds, settled: false };
-    // This call to `then` happens once for the lifetime of the value.
-    Promise.resolve(contender).then((value) => {
-        for (const { resolve } of deferreds) {
-            resolve(value);
-        }
-        deferreds.clear();
-        record.settled = true;
-    }, (err) => {
-        for (const { reject } of deferreds) {
-            reject(err);
-        }
-        deferreds.clear();
-        record.settled = true;
-    });
-    return record;
-}
-// Promise.race is memory unsafe. This is alternative which is. See:
-// https://github.com/nodejs/node/issues/17469#issuecomment-685235106
-// Keys are the values passed to race.
-// Values are a record of data containing a set of deferreds and whether the
-// value has settled.
-const wm = new WeakMap();
-function safeRace(contenders) {
-    let deferred;
-    const result = new Promise((resolve, reject) => {
-        deferred = { resolve, reject };
-        for (const contender of contenders) {
-            if (!isPromiseLike(contender)) {
-                // If the contender is a not a then-able, attempting to use it as a key
-                // in the weakmap would throw an error. Luckily, it is safe to call
-                // `Promise.resolve(contender).then` on regular values multiple
-                // times because the promise fulfills immediately.
-                Promise.resolve(contender).then(resolve, reject);
-                continue;
-            }
-            let record = wm.get(contender);
-            if (record === undefined) {
-                record = createRaceRecord(contender);
-                record.deferreds.add(deferred);
-                wm.set(contender, record);
-            }
-            else if (record.settled) {
-                // If the value has settled, it is safe to call
-                // `Promise.resolve(contender).then` on it.
-                Promise.resolve(contender).then(resolve, reject);
-            }
-            else {
-                record.deferreds.add(deferred);
-            }
-        }
-    });
-    // The finally callback executes when any value settles, preventing any of
-    // the unresolved values from retaining a reference to the resolved value.
-    return result.finally(() => {
-        for (const contender of contenders) {
-            if (isPromiseLike(contender)) {
-                const record = wm.get(contender);
-                if (record) {
-                    record.deferreds.delete(deferred);
-                }
-            }
-        }
-    });
-}
+import { isPromiseLike, unwrap, wrap, arrayify, safeRace, isIteratorLike } from './_utils.js';
 
 const NOOP = () => { };
 function getTagName(tag) {
@@ -261,6 +165,7 @@ const IsInForOfLoop = 1 << 13;
 const IsInForAwaitOfLoop = 1 << 14;
 const NeedsToYield = 1 << 15;
 const PropsAvailable = 1 << 16;
+const IsSchedulingRefresh = 1 << 17;
 function getFlag(ret, flag) {
     return !!(ret.f & flag);
 }
@@ -614,10 +519,10 @@ function diffChildren(adapter, root, host, ctx, scope, parent, newChildren) {
                     }
                 }
                 else if (ret) {
+                    let candidateFound = false;
                     // we do not need to add the retainer to the graveyard if it is the
                     // fallback of another retainer
                     // search for the tag in fallback chain
-                    let candidateFound = false;
                     for (let predecessor = ret, candidate = ret.fallback; candidate; predecessor = candidate, candidate = candidate.fallback) {
                         if (candidate.el.tag === child.tag) {
                             // If we find a retainer in the fallback chain with the same tag,
@@ -1452,6 +1357,9 @@ class Context extends CustomEventTarget {
                 });
             }
         }
+        if (getFlag(ctx.ret, IsScheduling)) {
+            setFlag(ctx.ret, IsSchedulingRefresh);
+        }
         let diff;
         const schedulePromises = [];
         try {
@@ -1797,10 +1705,11 @@ function runComponent(ctx) {
         if (getFlag(ctx.ret, IsInForOfLoop) &&
             !getFlag(ctx.ret, NeedsToYield) &&
             !getFlag(ctx.ret, IsUnmounted) &&
-            !getFlag(ctx.ret, IsScheduling)) {
+            !getFlag(ctx.ret, IsSchedulingRefresh)) {
             console.error(`Component <${getTagName(ctx.ret.el.tag)}> yielded/returned more than once in for...of loop`);
         }
         setFlag(ctx.ret, NeedsToYield, false);
+        setFlag(ctx.ret, IsSchedulingRefresh, false);
         if (iteration.done) {
             setFlag(ctx.ret, IsSyncGen, false);
             ctx.iterator = undefined;
@@ -1846,11 +1755,12 @@ function runComponent(ctx) {
                     if (getFlag(ctx.ret, IsInForOfLoop) &&
                         !getFlag(ctx.ret, NeedsToYield) &&
                         !getFlag(ctx.ret, IsUnmounted) &&
-                        !getFlag(ctx.ret, IsScheduling)) {
+                        !getFlag(ctx.ret, IsSchedulingRefresh)) {
                         console.error(`Component <${getTagName(ctx.ret.el.tag)}> yielded/returned more than once in for...of loop`);
                     }
                 }
                 setFlag(ctx.ret, NeedsToYield, false);
+                setFlag(ctx.ret, IsSchedulingRefresh, false);
                 if (iteration.done) {
                     setFlag(ctx.ret, IsAsyncGen, false);
                     ctx.iterator = undefined;
@@ -2082,18 +1992,17 @@ function commitComponent(ctx, schedulePromises, hydrationNodes) {
         });
         return getValue(ctx.ret);
     }
-    const wasScheduling = getFlag(ctx.ret, IsScheduling);
     const values = commitChildren(ctx.adapter, ctx.host, ctx, ctx.scope, ctx.ret, ctx.index, schedulePromises, hydrationNodes);
     if (getFlag(ctx.ret, IsUnmounted)) {
         return;
     }
     addEventTargetDelegates(ctx.ctx, values);
     // Execute schedule callbacks early to check for async deferral
-    const callbacks = scheduleMap.get(ctx);
+    const wasScheduling = getFlag(ctx.ret, IsScheduling);
     let schedulePromises1;
+    const callbacks = scheduleMap.get(ctx);
     if (callbacks) {
         scheduleMap.delete(ctx);
-        // TODO: think about error handling for schedule callbacks
         setFlag(ctx.ret, IsScheduling);
         const result = ctx.adapter.read(unwrap(values));
         for (const callback of callbacks) {
@@ -2104,7 +2013,7 @@ function commitComponent(ctx, schedulePromises, hydrationNodes) {
         }
         if (schedulePromises1 && !getFlag(ctx.ret, DidCommit)) {
             const scheduleCallbacksP = Promise.all(schedulePromises1).then(() => {
-                setFlag(ctx.ret, IsScheduling, false);
+                setFlag(ctx.ret, IsScheduling, wasScheduling);
                 propagateComponent(ctx);
                 if (ctx.ret.fallback) {
                     unmount(ctx.adapter, ctx.host, ctx.parent, ctx.ret.fallback, false);
@@ -2144,6 +2053,37 @@ function commitComponent(ctx, schedulePromises, hydrationNodes) {
     // if schedule callbacks call refresh() or async mounting is happening.
     return getValue(ctx.ret, true);
 }
+/**
+ * Checks if a target retainer is active (contributing) in the host's retainer tree.
+ * Performs a downward traversal from host to find if target is in the active path.
+ */
+function isRetainerActive(target, host) {
+    const stack = [host];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current === target) {
+            return true;
+        }
+        // Add direct children to stack (skip if this is a host boundary)
+        // Host boundaries are: DOM elements (string tags) or Portal, but NOT Fragment
+        const isHostBoundary = current !== host &&
+            ((typeof current.el.tag === "string" && current.el.tag !== Fragment) ||
+                current.el.tag === Portal);
+        if (current.children && !isHostBoundary) {
+            const children = wrap(current.children);
+            for (const child of children) {
+                if (child) {
+                    stack.push(child);
+                }
+            }
+        }
+        // Add fallback chains (only if current retainer is using fallback)
+        if (current.fallback && !getFlag(current, DidDiff)) {
+            stack.push(current.fallback);
+        }
+    }
+    return false;
+}
 /**
  * Propagates component changes up to ancestors when rendering starts from a
  * component via refresh() or multiple for await...of renders. This handles
@@ -2154,14 +2094,20 @@ function propagateComponent(ctx) {
     const values = getChildValues(ctx.ret, ctx.index);
     addEventTargetDelegates(ctx.ctx, values, (ctx1) => ctx1[_ContextState].host === ctx.host);
     const host = ctx.host;
+    const initiator = ctx.ret;
+    // Check if initiator is active in the host's tree
+    if (!isRetainerActive(initiator, host)) {
+        return;
+    }
     const props = stripSpecialProps(host.el.props);
+    const hostChildren = getChildValues(host, 0);
     ctx.adapter.arrange({
         tag: host.el.tag,
         tagName: getTagName(host.el.tag),
         node: host.value,
         props,
         oldProps: props,
-        children: getChildValues(host, 0),
+        children: hostChildren,
     });
     flush(ctx.adapter, ctx.root, ctx);
 }