dalila 1.4.2 → 1.4.3

package/dist/core/watch.js

@@ -0,0 +1,353 @@
+import { effect, effectAsync, signal } from './signal.js';
+import { getCurrentScope, withScope } from './scope.js';
+/**
+ * Global registry: Document -> WatchContext.
+ * WeakMap ensures cleanup when Document is garbage collected.
+ */
+const documentWatchers = new WeakMap();
+/**
+ * One-time warning flags to avoid flooding console.
+ */
+let hasWarnedNoScope = false;
+const warnedFunctions = new Set();
+/**
+ * Reset warning flags (used by src/internal/watch-testing.ts for deterministic tests).
+ * @internal
+ */
+export function __resetWarningsForTests() {
+    warnedFunctions.clear();
+    hasWarnedNoScope = false;
+}
+/**
+ * Walk a subtree recursively, calling visitor for each node.
+ * Supports any Node type (Element, Text, Comment, etc.) via childNodes.
+ */
+function walkSubtree(root, visitor) {
+    visitor(root);
+    if (root.childNodes && root.childNodes.length > 0) {
+        for (let i = 0; i < root.childNodes.length; i++) {
+            walkSubtree(root.childNodes[i], visitor);
+        }
+    }
+}
+/**
+ * Start a watch entry effect inside the entry's captured scope (if any).
+ *
+ * Why:
+ * - `effect()` captures getCurrentScope() at creation time.
+ * - watch entries can start later (when a node becomes connected), so we must re-enter
+ *   the original scope to preserve cleanup semantics.
+ */
+function startEntryEffect(entry) {
+    if (entry.effectStarted || entry.cleanup)
+        return;
+    entry.effectStarted = true;
+    const create = () => effect(entry.fn);
+    // Ensure the *creation* of the effect happens inside the captured scope.
+    // effect() captures getCurrentScope() at creation time.
+    entry.cleanup = entry.scope ? withScope(entry.scope, create) : create();
+}
+/**
+ * Gets or creates a watch context for a document.
+ * Ensures only ONE MutationObserver per document.
+ */
+function getDocumentWatchContext(doc) {
+    let ctx = documentWatchers.get(doc);
+    if (!ctx) {
+        const watches = new WeakMap();
+        const observer = new MutationObserver((records) => {
+            const candidates = new Set();
+            // 1) removedNodes: collect candidates for cleanup (ONLY affected subtrees)
+            for (const record of records) {
+                for (let i = 0; i < record.removedNodes.length; i++) {
+                    const removed = record.removedNodes[i];
+                    walkSubtree(removed, (node) => {
+                        const entries = watches.get(node);
+                        if (entries && entries.size > 0)
+                            candidates.add(node);
+                    });
+                }
+            }
+            // 2) addedNodes: mark connected and start effects (ONLY affected subtrees)
+            for (const record of records) {
+                for (let i = 0; i < record.addedNodes.length; i++) {
+                    const added = record.addedNodes[i];
+                    walkSubtree(added, (node) => {
+                        const entries = watches.get(node);
+                        if (!entries || entries.size === 0)
+                            return;
+                        for (const entry of entries) {
+                            entry.hasConnected = true;
+                            // Start effect if not started yet and node is connected
+                            if (!entry.effectStarted && node.isConnected) {
+                                startEntryEffect(entry);
+                            }
+                        }
+                        // Handles "move": remove+add in same batch
+                        candidates.delete(node);
+                    });
+                }
+            }
+            // 3) Cleanup disconnected candidates in microtask (handles move correctly)
+            if (candidates.size > 0) {
+                queueMicrotask(() => {
+                    for (const node of candidates) {
+                        if (node.isConnected)
+                            continue;
+                        const entries = watches.get(node);
+                        if (!entries || entries.size === 0)
+                            continue;
+                        for (const entry of entries) {
+                            // Only cleanup if it was connected at least once
+                            if (entry.hasConnected && entry.cleanup) {
+                                entry.cleanup();
+                                entry.cleanup = null;
+                                // Allow restart if node reconnects later
+                                entry.effectStarted = false;
+                            }
+                        }
+                    }
+                });
+            }
+        });
+        observer.observe(doc, { childList: true, subtree: true });
+        ctx = { observer, watches, watchCount: 0 };
+        documentWatchers.set(doc, ctx);
+    }
+    return ctx;
+}
+/**
+ * watch(node, fn)
+ *
+ * Runs `fn` inside a reactive effect while `node` is connected to the document.
+ * - Signal reads inside `fn` are tracked (because `fn` runs inside effect()).
+ * - When the node disconnects, the effect is disposed.
+ * - If the node reconnects later, the effect may start again (best-effort, based on DOM mutations).
+ *
+ * Implementation notes / fixes:
+ * 1) Scope capture: the scope at watch() time is stored on the entry so effects that start later
+ *    still get created "inside" the original scope (fixes late-start effects created outside scope).
+ * 2) Memory safety: watches uses WeakMap<Node, ...> so detached nodes are not kept alive.
+ * 3) Observer lifecycle: we track ctx.watchCount (WeakMap has no .size) to know when to disconnect.
+ */
+export function watch(node, fn) {
+    const currentScope = getCurrentScope();
+    // Warn if no scope (one-time warning to avoid flooding)
+    if (!currentScope && !hasWarnedNoScope) {
+        hasWarnedNoScope = true;
+        console.warn('[Dalila] watch() called outside scope. ' +
+            'The watch will work but you must call the returned dispose() function manually to avoid memory leaks. ' +
+            'Consider using createScope() + withScope() for automatic cleanup.');
+    }
+    // Get document (default to global document if node.ownerDocument is null)
+    const doc = node.ownerDocument || document;
+    const ctx = getDocumentWatchContext(doc);
+    // Create watch entry (capture scope NOW)
+    const entry = {
+        fn,
+        cleanup: null,
+        hasConnected: node.isConnected,
+        effectStarted: false,
+        scope: currentScope ?? null
+    };
+    // Register in watches (WeakMap) and increment count
+    let set = ctx.watches.get(node);
+    if (!set) {
+        set = new Set();
+        ctx.watches.set(node, set);
+    }
+    set.add(entry);
+    ctx.watchCount++;
+    // Start effect immediately if node is already connected (inside captured scope)
+    if (node.isConnected) {
+        startEntryEffect(entry);
+    }
+    // Dispose function (idempotent)
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        // Stop effect if running
+        if (entry.cleanup) {
+            entry.cleanup();
+            entry.cleanup = null;
+        }
+        entry.effectStarted = false;
+        // Remove entry from set (if set still exists)
+        const entries = ctx.watches.get(node);
+        if (entries) {
+            entries.delete(entry);
+            // If empty, delete the entry from WeakMap to free the Set immediately
+            if (entries.size === 0)
+                ctx.watches.delete(node);
+        }
+        // Decrement active watch count and disconnect observer if none left
+        ctx.watchCount--;
+        if (ctx.watchCount <= 0) {
+            ctx.observer.disconnect();
+            documentWatchers.delete(doc);
+        }
+    };
+    // Register cleanup in scope if available
+    if (currentScope) {
+        currentScope.onCleanup(dispose);
+    }
+    return dispose;
+}
+/**
+ * onMount(fn)
+ *
+ * Executes fn immediately. Minimal semantic helper to document mount-time logic in DOM-first code.
+ * Unlike React, there's no deferred execution or batching — it runs synchronously.
+ */
+export function onMount(fn) {
+    fn();
+}
+/**
+ * onCleanup(fn)
+ *
+ * Registers fn to run when the current scope is disposed.
+ * If called outside a scope, fn is never called (no-op).
+ */
+export function onCleanup(fn) {
+    const scope = getCurrentScope();
+    if (scope)
+        scope.onCleanup(fn);
+}
+/**
+ * useEvent(target, type, handler, options?)
+ *
+ * Attaches an event listener and returns an idempotent dispose() function.
+ * - Inside a scope: listener is removed automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
+export function useEvent(target, type, handler, options) {
+    const scope = getCurrentScope();
+    if (!scope && !warnedFunctions.has('useEvent')) {
+        warnedFunctions.add('useEvent');
+        console.warn('[Dalila] useEvent() called outside scope. ' +
+            'Event listener will not auto-cleanup. Call the returned dispose() function manually.');
+    }
+    target.addEventListener(type, handler, options);
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        target.removeEventListener(type, handler, options);
+    };
+    if (scope)
+        scope.onCleanup(dispose);
+    return dispose;
+}
+/**
+ * useInterval(fn, ms)
+ *
+ * Starts an interval and returns an idempotent dispose() function.
+ * - Inside a scope: interval is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
+export function useInterval(fn, ms) {
+    const scope = getCurrentScope();
+    if (!scope && !warnedFunctions.has('useInterval')) {
+        warnedFunctions.add('useInterval');
+        console.warn('[Dalila] useInterval() called outside scope. ' +
+            'Interval will not auto-cleanup. Call the returned dispose() function manually.');
+    }
+    const intervalId = setInterval(fn, ms);
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        clearInterval(intervalId);
+    };
+    if (scope)
+        scope.onCleanup(dispose);
+    return dispose;
+}
+/**
+ * useTimeout(fn, ms)
+ *
+ * Starts a timeout and returns an idempotent dispose() function.
+ * - Inside a scope: timeout is cleared automatically on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ */
+export function useTimeout(fn, ms) {
+    const scope = getCurrentScope();
+    if (!scope && !warnedFunctions.has('useTimeout')) {
+        warnedFunctions.add('useTimeout');
+        console.warn('[Dalila] useTimeout() called outside scope. ' +
+            'Timeout will not auto-cleanup. Call the returned dispose() function manually.');
+    }
+    const timeoutId = setTimeout(fn, ms);
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        clearTimeout(timeoutId);
+    };
+    if (scope)
+        scope.onCleanup(dispose);
+    return dispose;
+}
+/**
+ * useFetch(url, options)
+ *
+ * Small convenience for "fetch + reactive state + abort" built on effectAsync().
+ * Returns { data, loading, error, dispose }.
+ *
+ * Behavior:
+ * - Runs the fetch inside effectAsync, which provides an AbortSignal.
+ * - If url is a function, it tracks signal reads (reactive).
+ * - Calling dispose() aborts the in-flight request (via effectAsync's signal).
+ * - Inside a scope: auto-disposed on scope.dispose().
+ * - Outside a scope: you must call dispose() manually (warns once).
+ *
+ * Limitations:
+ * - No refresh(), no caching, no invalidation.
+ * - For those features, use createResource / query().
+ */
+export function useFetch(url, options) {
+    const scope = getCurrentScope();
+    if (!scope && !warnedFunctions.has('useFetch')) {
+        warnedFunctions.add('useFetch');
+        console.warn('[Dalila] useFetch() called outside scope. ' +
+            'Request will not auto-cleanup. Call the returned dispose() function manually.');
+    }
+    const data = signal(null);
+    const loading = signal(false);
+    const error = signal(null);
+    const dispose = effectAsync(async (signal) => {
+        try {
+            loading.set(true);
+            error.set(null);
+            const fetchUrl = typeof url === 'function' ? url() : url;
+            const response = await fetch(fetchUrl, {
+                ...options,
+                signal
+            });
+            if (!response.ok) {
+                throw new Error(`HTTP error! status: ${response.status}`);
+            }
+            const result = (await response.json());
+            data.set(result);
+        }
+        catch (err) {
+            if (signal.aborted)
+                return;
+            error.set(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            if (!signal.aborted) {
+                loading.set(false);
+            }
+        }
+    });
+    // Match the other lifecycle helpers: if we are inside a scope, dispose automatically.
+    if (scope)
+        scope.onCleanup(dispose);
+    return { data, loading, error, dispose };
+}

package/dist/core/when.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Conditional DOM rendering with per-branch lifetime.
+ *
+ * `when()` returns a DocumentFragment containing two stable comment markers:
+ *   <!-- when:start --> ...branch nodes... <!-- when:end -->
+ *
+ * Why markers?
+ * - The markers act as a permanent insertion point, so the branch can be swapped
+ *   without the caller managing placeholders or re-appending anything.
+ *
+ * Semantics:
+ * - Initial render is synchronous (prevents “flash”).
+ * - Updates track only `test()` (the condition), not the branch internals.
+ * - Branch swaps are coalesced in a microtask to:
+ *   1) merge rapid toggles into a single swap, and
+ *   2) run branch rendering outside reactive tracking (avoid accidental subscriptions).
+ *
+ * Lifetime:
+ * - Each mounted branch owns its own Scope.
+ * - Swapping branches disposes the previous scope, cleaning up effects/listeners/timers
+ *   created inside that branch.
+ */
+export declare function when(test: () => any, thenFn: () => Node | Node[], elseFn?: () => Node | Node[]): DocumentFragment;

package/dist/core/when.js

@@ -0,0 +1,124 @@
+import { effect } from './signal.js';
+import { createScope, getCurrentScope, isScopeDisposed, withScope } from './scope.js';
+import { scheduleMicrotask } from './scheduler.js';
+/**
+ * Conditional DOM rendering with per-branch lifetime.
+ *
+ * `when()` returns a DocumentFragment containing two stable comment markers:
+ *   <!-- when:start --> ...branch nodes... <!-- when:end -->
+ *
+ * Why markers?
+ * - The markers act as a permanent insertion point, so the branch can be swapped
+ *   without the caller managing placeholders or re-appending anything.
+ *
+ * Semantics:
+ * - Initial render is synchronous (prevents “flash”).
+ * - Updates track only `test()` (the condition), not the branch internals.
+ * - Branch swaps are coalesced in a microtask to:
+ *   1) merge rapid toggles into a single swap, and
+ *   2) run branch rendering outside reactive tracking (avoid accidental subscriptions).
+ *
+ * Lifetime:
+ * - Each mounted branch owns its own Scope.
+ * - Swapping branches disposes the previous scope, cleaning up effects/listeners/timers
+ *   created inside that branch.
+ */
+export function when(test, thenFn, elseFn) {
+    /** Stable DOM anchors delimiting the dynamic range. */
+    const start = document.createComment('when:start');
+    const end = document.createComment('when:end');
+    /** Nodes currently mounted between start/end. */
+    let currentNodes = [];
+    /** Scope owning resources created by the mounted branch. */
+    let branchScope = null;
+    /** Last resolved boolean (used to avoid unnecessary remounts). */
+    let lastCond = undefined;
+    /** Coalescing state: ensure at most one scheduled swap per tick. */
+    let swapScheduled = false;
+    let pendingCond = undefined;
+    /** Disposal guard to prevent orphan microtasks from touching dead DOM. */
+    let disposed = false;
+    /** Parent scope captured at creation time (if any). */
+    const parentScope = getCurrentScope();
+    const resolveParentScope = () => {
+        if (!parentScope)
+            return null;
+        return isScopeDisposed(parentScope) ? null : parentScope;
+    };
+    /** Removes mounted nodes and disposes their branch scope. */
+    const clear = () => {
+        branchScope?.dispose();
+        branchScope = null;
+        for (const n of currentNodes) {
+            n.parentNode?.removeChild(n);
+        }
+        currentNodes = [];
+    };
+    /** Inserts nodes before the end marker and records ownership. */
+    const mount = (nodes, scope) => {
+        currentNodes = nodes;
+        branchScope = scope;
+        end.before(...nodes);
+    };
+    /** Clears old branch and mounts the branch for `cond`. */
+    const swap = (cond) => {
+        clear();
+        const nextScope = createScope(resolveParentScope());
+        try {
+            // Render inside an isolated scope so branch resources are tied to that branch.
+            const result = withScope(nextScope, () => (cond ? thenFn() : elseFn?.()));
+            if (!result) {
+                // Allow “empty branch”: keep anchors, dispose the unused scope.
+                nextScope.dispose();
+                return;
+            }
+            const nodes = Array.isArray(result) ? result : [result];
+            mount(nodes, nextScope);
+        }
+        catch (err) {
+            // Never leak the newly created scope if branch rendering throws.
+            nextScope.dispose();
+            throw err;
+        }
+    };
+    // Create the stable slot (anchors first, content inserted between them).
+    const frag = document.createDocumentFragment();
+    frag.append(start, end);
+    // Initial render is synchronous so the caller sees the correct branch immediately
+    // after appending the fragment to the DOM.
+    const initialCond = !!test();
+    lastCond = initialCond;
+    swap(initialCond);
+    /**
+     * Reactive driver:
+     * - tracks only `test()`
+     * - swaps only when the boolean changes
+     * - coalesces swaps via microtask (outside tracking)
+     */
+    effect(() => {
+        const cond = !!test();
+        if (lastCond === cond)
+            return;
+        lastCond = cond;
+        pendingCond = cond;
+        if (swapScheduled)
+            return;
+        swapScheduled = true;
+        scheduleMicrotask(() => {
+            swapScheduled = false;
+            if (disposed)
+                return;
+            const next = pendingCond;
+            pendingCond = undefined;
+            swap(next);
+        });
+    });
+    // If `when()` is created inside a parent scope, dispose branch resources with it.
+    if (parentScope) {
+        parentScope.onCleanup(() => {
+            disposed = true;
+            clear();
+        });
+    }
+    return frag;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./core/index.js";
+export * from "./context/index.js";
+export * from "./router/index.js";
+export * from "./runtime/index.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from "./core/index.js";
+export * from "./context/index.js";
+export * from "./router/index.js";
+export * from "./runtime/index.js";

package/dist/internal/watch-testing.d.ts

@@ -0,0 +1 @@
+export declare function resetWarnings(): void;

package/dist/internal/watch-testing.js

@@ -0,0 +1,8 @@
+/**
+ * Testing utilities for watch.ts
+ * @internal
+ */
+import { __resetWarningsForTests } from '../core/watch.js';
+export function resetWarnings() {
+    __resetWarningsForTests();
+}

package/dist/router/index.d.ts

@@ -0,0 +1 @@
+export * from "./router.js";

package/dist/router/index.js

@@ -0,0 +1 @@
+export * from "./router.js";

package/dist/router/route.d.ts

@@ -0,0 +1,23 @@
+export interface RouteDef {
+    path: string;
+    view: () => Node | Node[];
+    children?: RouteDef[];
+    loader?: (route: RouteState) => Promise<any>;
+    beforeEnter?: (to: RouteState, from: RouteState) => boolean | Promise<boolean>;
+    afterLeave?: (from: RouteState, to: RouteState) => void | Promise<void>;
+}
+export interface RouteState {
+    path: string;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    hash: string;
+    signal?: AbortSignal;
+}
+export interface RouteMatch {
+    route: RouteDef;
+    params: Record<string, string>;
+    query: URLSearchParams;
+    hash: string;
+}
+export declare function matchRoute(path: string, routeDef: RouteDef): RouteMatch | null;
+export declare function findRoute(path: string, routes: RouteDef[]): RouteMatch | null;

package/dist/router/route.js

@@ -0,0 +1,48 @@
+function parsePath(path) {
+    const paramNames = [];
+    const pattern = path
+        .replace(/:([^\/]+)/g, (_, paramName) => {
+        paramNames.push(paramName);
+        return '([^/]+)';
+    })
+        .replace(/\*/g, '.*');
+    return {
+        pattern: new RegExp(`^${pattern}$`),
+        paramNames
+    };
+}
+export function matchRoute(path, routeDef) {
+    const { pattern, paramNames } = parsePath(routeDef.path);
+    const match = path.match(pattern);
+    if (!match) {
+        return null;
+    }
+    const params = {};
+    paramNames.forEach((name, index) => {
+        params[name] = match[index + 1];
+    });
+    const url = new URL(path, 'http://localhost');
+    const query = url.searchParams;
+    const hash = url.hash.slice(1); // Remove the #
+    return {
+        route: routeDef,
+        params,
+        query,
+        hash
+    };
+}
+export function findRoute(path, routes) {
+    for (const route of routes) {
+        const match = matchRoute(path, route);
+        if (match) {
+            return match;
+        }
+        if (route.children) {
+            const childMatch = findRoute(path, route.children);
+            if (childMatch) {
+                return childMatch;
+            }
+        }
+    }
+    return null;
+}

package/dist/router/router.d.ts

@@ -0,0 +1,23 @@
+import { Signal } from '../core/signal.js';
+import { RouteDef, RouteState } from './route.js';
+export interface Router {
+    mount(outlet: Element): void;
+    push(path: string): void;
+    replace(path: string): void;
+    back(): void;
+    link(event: MouseEvent): void;
+    outlet(): Element;
+    route: Signal<RouteState>;
+    beforeEnter?: (to: RouteState, from: RouteState) => boolean | Promise<boolean>;
+    afterLeave?: (from: RouteState, to: RouteState) => void | Promise<void>;
+}
+export interface RouteDefWithLoader extends RouteDef {
+    loader?: (route: RouteState) => Promise<any>;
+    beforeEnter?: (to: RouteState, from: RouteState) => boolean | Promise<boolean>;
+    afterLeave?: (from: RouteState, to: RouteState) => void | Promise<void>;
+}
+export interface RouterConfig {
+    routes: RouteDef[];
+}
+export declare function getCurrentRouter(): Router | null;
+export declare function createRouter(config: RouterConfig): Router;