@continuum-js/dom 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -8,6 +8,14 @@ export declare function scope<T>(fn: () => T): {
 };
 /** Register a cleanup in the current owner (no-op outside any owner). */
 export declare function onCleanup(fn: () => void): void;
+/**
+ * Register a callback to run once the current scope's nodes are inserted into
+ * the DOM — after `mount`, or right after a dynamic region (`dyn`/`each`)
+ * inserts a freshly built subtree. Use it for focus, measurement, and
+ * third-party libraries that need a live element. No-op outside any owner.
+ */
+export declare function onMount(fn: () => void): void;
+/** Anything placeable in JSX: nodes, behaviors (live-bound), primitives, arrays. */
 export type Child = Node | Behavior<unknown> | string | number | boolean | null | undefined | Child[];
 type Props = Record<string, unknown> | null;
 /** Fragment marker for `--jsxFragmentFactory Fragment`. */
@@ -21,10 +29,12 @@ export declare function h(tag: string | Component | typeof Fragment, props: Prop
 export declare function dyn<T>(b: Behavior<T>, render: (v: T) => Child): Node;
 /** Keyed list: reuses rows by key, reorders with minimal moves (LIS). */
 export declare function each<T, K>(items: Behavior<T[]>, key: (item: T) => K, render: (item: T) => Child): Node;
+/** A context handle: identity plus the value used when nothing was provided. */
 export interface Context<T> {
     readonly id: symbol;
     readonly defaultValue: T;
 }
+/** Create a context. Provide with `provide`, read with `use`. */
 export declare function createContext<T>(defaultValue: T): Context<T>;
 /** Write a context value into the current owner. */
 export declare function provide<T>(ctx: Context<T>, value: T): void;

package/dist/index.js

@@ -6,6 +6,8 @@ let currentOwner = null;
 function createOwner(parent) {
     const owner = {
         cleanups: [],
+        mounts: null,
+        mounted: false,
         children: [],
         parent,
         contexts: null,
@@ -28,6 +30,7 @@ function disposeOwner(owner) {
         owner.cleanups[i]();
     }
     owner.cleanups.length = 0;
+    owner.mounts = null; // never mounted → its onMount callbacks never run
     // detach from parent
     if (owner.parent) {
         const siblings = owner.parent.children;
@@ -63,6 +66,32 @@ export function onCleanup(fn) {
     if (currentOwner)
         currentOwner.cleanups.push(fn);
 }
+// Run the subtree's pending onMount callbacks: child scopes first, then this
+// owner's own, newest registration first. With the idiomatic `onMount` at the
+// top of a component body, that yields children-before-parents.
+function flushMounts(owner) {
+    if (owner.disposed)
+        return;
+    for (const child of owner.children)
+        flushMounts(child);
+    owner.mounted = true;
+    const mounts = owner.mounts;
+    if (mounts) {
+        owner.mounts = null;
+        for (let i = mounts.length - 1; i >= 0; i--)
+            mounts[i]();
+    }
+}
+/**
+ * Register a callback to run once the current scope's nodes are inserted into
+ * the DOM — after `mount`, or right after a dynamic region (`dyn`/`each`)
+ * inserts a freshly built subtree. Use it for focus, measurement, and
+ * third-party libraries that need a live element. No-op outside any owner.
+ */
+export function onMount(fn) {
+    if (currentOwner)
+        (currentOwner.mounts ?? (currentOwner.mounts = [])).push(fn);
+}
 /** Attach an frp subscription to the current owner's lifecycle. */
 function bind(un) {
     onCleanup(un);
@@ -251,21 +280,26 @@ export function h(tag, props, ...children) {
 // Dynamic regions (§7)
 // ---------------------------------------------------------------------------
 // Build `child` into a fragment under a fresh scope of `owner`. Returns the
-// fragment's top-level nodes and the scope's dispose handle.
+// fragment's top-level nodes, the scope's dispose handle, and a `flush` that
+// runs the scope's pending onMount callbacks (call it after insertion).
 function buildScoped(owner, build) {
-    const s = runUnder(owner, () => scope(() => {
+    const scopeOwner = createOwner(owner);
+    const nodes = runUnder(scopeOwner, () => {
         const built = build();
         // Fast path: a single element/text node (the common row/component case)
         // needs no fragment or NodeList copy.
-        if (built instanceof Node &&
-            built.nodeType !== 11 /* DocumentFragment */) {
+        if (built instanceof Node && built.nodeType !== 11 /* DocumentFragment */) {
             return [built];
         }
         const frag = document.createDocumentFragment();
         appendChild(frag, built);
         return Array.from(frag.childNodes);
-    }));
-    return { nodes: s.value, dispose: s.dispose };
+    });
+    return {
+        nodes,
+        dispose: () => disposeOwner(scopeOwner),
+        flush: () => flushMounts(scopeOwner),
+    };
 }
 /** Conditional / switching subtree: rebuilds on each change of `b`. */
 export function dyn(b, render) {
@@ -276,17 +310,39 @@ export function dyn(b, render) {
     frag.appendChild(start);
     frag.appendChild(end);
     let current = null;
-    const update = (v) => {
+    // Level-triggered: render the behavior's CURRENT value, not the delivered
+    // occurrence. A listener that runs earlier in the post phase may re-enter
+    // with a new moment (e.g. a router redirect); the stale queued delivery
+    // then must not clobber the newer render. Deduping by Object.is also makes
+    // duplicate deliveries free.
+    let hasRendered = false;
+    let renderedValue;
+    const update = () => {
+        const v = b.sampleNoTrans();
+        if (hasRendered && Object.is(renderedValue, v))
+            return;
+        hasRendered = true;
+        renderedValue = v;
         if (current) {
             current.dispose();
-            for (const n of current.nodes)
-                if (n.parentNode)
-                    n.parentNode.removeChild(n);
+            // Sweep the whole live range between the markers: a nested dynamic
+            // region at the root of this one may have swapped nodes since build,
+            // so the recorded node list can be stale.
+            let n = start.nextSibling;
+            while (n && n !== end) {
+                const next = n.nextSibling;
+                n.parentNode?.removeChild(n);
+                n = next;
+            }
         }
         current = buildScoped(owner, () => render(v));
         const parent = end.parentNode;
         for (const n of current.nodes)
             parent.insertBefore(n, end);
+        // During the initial build the whole tree flushes at mount; afterwards
+        // each freshly inserted subtree flushes here.
+        if (!owner || owner.mounted)
+            current.flush();
     };
     bind(b.listen(update));
     onCleanup(() => current?.dispose());
@@ -338,6 +394,7 @@ export function each(items, key, render) {
         const seen = new Set();
         const next = [];
         const seq = [];
+        const freshFlushes = [];
         for (const item of list) {
             const k = key(item);
             if (seen.has(k))
@@ -352,6 +409,7 @@ export function each(items, key, render) {
                 const built = buildScoped(owner, () => render(item));
                 next.push({ key: k, nodes: built.nodes, dispose: built.dispose });
                 seq.push(-1);
+                freshFlushes.push(built.flush);
             }
         }
         // dispose rows whose key disappeared
@@ -378,6 +436,9 @@ export function each(items, key, render) {
         if (active instanceof HTMLElement && active.isConnected)
             active.focus();
         rows = next;
+        if (!owner || owner.mounted)
+            for (const f of freshFlushes)
+                f();
     };
     bind(items.listen(update));
     onCleanup(() => {
@@ -386,6 +447,7 @@ export function each(items, key, render) {
     });
     return frag;
 }
+/** Create a context. Provide with `provide`, read with `use`. */
 export function createContext(defaultValue) {
     return { id: Symbol("context"), defaultValue };
 }
@@ -458,6 +520,8 @@ export function mount(container, view) {
                 if (n.parentNode)
                     n.parentNode.removeChild(n);
         });
+        if (currentOwner)
+            flushMounts(currentOwner);
         return () => dispose();
     });
 }
@@ -480,6 +544,14 @@ export function animationFrames() {
 }
 // ---------------------------------------------------------------------------
 // Control-flow components — JSX wrappers over the rendering helpers.
+//
+// The function/component pairing is a deliberate symmetry, not duplication:
+//   when(b, then, else)  ↔  <Show when={b}>       — conditional region
+//   dyn(b, render)       ↔  <Dynamic of={b}>      — switching subtree
+//   each(b, by, render)  ↔  <Each of={b} by={..}> — keyed list
+//   portal(target, ch)   ↔  <Portal mount={..}>   — render elsewhere
+// Functions compose in plain code (no JSX required); components read better
+// inside markup. Both call the same implementation.
 // ---------------------------------------------------------------------------
 // JSX always delivers children as the rest array; a single render function
 // arrives as `[fn]`. Normalize to a render callback.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@continuum-js/dom",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Continuum DOM renderer — fine-grained bindings, dynamic regions, ownership, context",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,6 @@
     "access": "public"
   },
   "dependencies": {
-    "@continuum-js/frp": "0.3.0"
+    "@continuum-js/frp": "0.4.0"
   }
 }