dalila 1.4.2 → 1.4.4

package/dist/context/context.js

@@ -0,0 +1,283 @@
+import { getCurrentScope } from "../core/scope.js";
+import { isInDevMode } from "../core/dev.js";
+/**
+ * Create a new context token.
+ *
+ * Notes:
+ * - Tokens are identity-based: the same token instance is the key.
+ * - `name` is for developer-facing errors and debugging only.
+ * - `defaultValue` is returned by inject/tryInject when no provider is found.
+ */
+export function createContext(name, defaultValue) {
+    return { name, defaultValue };
+}
+let globalRevision = 0;
+let warnedDeepHierarchy = false;
+/**
+ * Configurable deep hierarchy warning threshold.
+ */
+let deepHierarchyWarnDepth = 50;
+/**
+ * Configure the depth at which context lookup warns about deep hierarchies.
+ * Set to Infinity to disable the warning.
+ */
+export function setDeepHierarchyWarnDepth(depth) {
+    deepHierarchyWarnDepth = depth;
+}
+function bumpRevision() {
+    globalRevision++;
+}
+function maybeWarnDeepHierarchy(depth) {
+    if (!isInDevMode())
+        return;
+    if (warnedDeepHierarchy)
+        return;
+    if (depth < deepHierarchyWarnDepth)
+        return;
+    warnedDeepHierarchy = true;
+    console.warn(`[Dalila] Context lookup traversed ${depth} parent scopes. ` +
+        `Consider flattening scope hierarchy or caching static contexts.`);
+}
+/**
+ * Per-scope registry that stores context values and links to a parent registry.
+ *
+ * Lookup:
+ * - `get()` checks current registry first.
+ * - If not found, it delegates to the parent registry (if any).
+ */
+class ContextRegistry {
+    constructor(ownerScope, parent) {
+        this.contexts = new Map();
+        this.resolveCache = new Map();
+        this.ownerScope = ownerScope;
+        this.parent = parent;
+    }
+    set(token, value) {
+        this.contexts.set(token, { token, value });
+        this.resolveCache.delete(token);
+    }
+    get(token) {
+        const res = this.resolve(token);
+        return res ? res.value : undefined;
+    }
+    resolve(token) {
+        const cached = this.resolveCache.get(token);
+        if (cached && cached.rev === globalRevision)
+            return cached.res;
+        const hit = this.contexts.get(token);
+        if (hit !== undefined) {
+            const res = { value: hit.value, ownerScope: this.ownerScope, depth: 0 };
+            this.resolveCache.set(token, { rev: globalRevision, res });
+            return res;
+        }
+        if (this.parent) {
+            const parentRes = this.parent.resolve(token);
+            if (parentRes) {
+                const res = {
+                    value: parentRes.value,
+                    ownerScope: parentRes.ownerScope,
+                    depth: parentRes.depth + 1,
+                };
+                this.resolveCache.set(token, { rev: globalRevision, res });
+                return res;
+            }
+        }
+        this.resolveCache.set(token, { rev: globalRevision, res: undefined });
+        return undefined;
+    }
+    listTokens(maxPerLevel) {
+        const tokens = [];
+        for (const entry of this.contexts.values()) {
+            tokens.push(entry.token);
+            if (maxPerLevel != null && tokens.length >= maxPerLevel)
+                break;
+        }
+        return tokens;
+    }
+    /**
+     * Release references eagerly.
+     *
+     * Safety:
+     * - Scopes in Dalila cascade: disposing a parent scope disposes children,
+     *   so no child scope should outlive a parent registry.
+     */
+    clear() {
+        bumpRevision();
+        this.contexts.clear();
+        this.parent = undefined;
+        this.resolveCache.clear();
+    }
+}
+/**
+ * Registry storage keyed by Scope.
+ *
+ * Why WeakMap:
+ * - Avoid keeping scopes alive through registry bookkeeping.
+ */
+const scopeRegistries = new WeakMap();
+/**
+ * Get (or lazily create) the registry for a given scope.
+ *
+ * Key detail:
+ * - Parent linkage is derived from `scope.parent` (captured at createScope time),
+ *   not from `getCurrentScope()`. This makes the hierarchy stable and explicit.
+ *
+ * Cleanup:
+ * - When the scope is disposed, we clear the registry and remove it from the WeakMap.
+ */
+function getScopeRegistry(scope) {
+    let registry = scopeRegistries.get(scope);
+    if (registry)
+        return registry;
+    const parentScope = scope.parent;
+    const parentRegistry = parentScope ? getScopeRegistry(parentScope) : undefined;
+    registry = new ContextRegistry(scope, parentRegistry);
+    scopeRegistries.set(scope, registry);
+    const registryRef = registry;
+    scope.onCleanup(() => {
+        registryRef.clear();
+        scopeRegistries.delete(scope);
+    });
+    return registry;
+}
+/**
+ * Provide a context value in the current scope.
+ *
+ * Rules:
+ * - Must be called inside a scope.
+ * - Overrides any existing value for the same token in this scope.
+ */
+export function provide(token, value) {
+    const scope = getCurrentScope();
+    if (!scope) {
+        throw new Error("[Dalila] provide() must be called within a scope. " +
+            "Use withScope(createScope(), () => provide(...)) or the auto-scope API.");
+    }
+    const registry = getScopeRegistry(scope);
+    bumpRevision();
+    registry.set(token, value);
+}
+/**
+ * Inject a context value from the current scope hierarchy.
+ *
+ * Rules:
+ * - Must be called inside a scope.
+ * - Walks up the parent chain until it finds the token.
+ * - If not found and token has a defaultValue, returns that.
+ * - Throws a descriptive error if not found and no default.
+ */
+export function inject(token) {
+    const scope = getCurrentScope();
+    if (!scope) {
+        throw new Error("[Dalila] inject() must be called within a scope. " +
+            "Wrap your code in withScope(...) or use the auto-scope API.");
+    }
+    const registry = getScopeRegistry(scope);
+    const res = registry.resolve(token);
+    if (res) {
+        maybeWarnDeepHierarchy(res.depth);
+        return res.value;
+    }
+    // Check for default value
+    if (token.defaultValue !== undefined) {
+        return token.defaultValue;
+    }
+    const name = token.name || "unnamed";
+    let message = `[Dalila] Context "${name}" not found in scope hierarchy.`;
+    if (isInDevMode()) {
+        const levels = debugListAvailableContexts(8);
+        if (levels.length > 0) {
+            message += `\n\nAvailable contexts by depth:\n`;
+            for (const level of levels) {
+                const names = level.tokens.map((t) => t.name).join(", ") || "(none)";
+                message += `  depth ${level.depth}: ${names}\n`;
+            }
+        }
+    }
+    throw new Error(message);
+}
+/**
+ * Inject a context value from the current scope hierarchy if present.
+ *
+ * Rules:
+ * - Must be called inside a scope.
+ * - Returns { found: true, value } when found.
+ * - Returns { found: false, value: undefined } when not found (or uses defaultValue if available).
+ */
+export function tryInject(token) {
+    const scope = getCurrentScope();
+    if (!scope) {
+        throw new Error("[Dalila] tryInject() must be called within a scope. " +
+            "Wrap your code in withScope(...) or use the auto-scope API.");
+    }
+    const registry = getScopeRegistry(scope);
+    const res = registry.resolve(token);
+    if (res) {
+        maybeWarnDeepHierarchy(res.depth);
+        return { found: true, value: res.value };
+    }
+    // Check for default value
+    if (token.defaultValue !== undefined) {
+        return { found: true, value: token.defaultValue };
+    }
+    return { found: false, value: undefined };
+}
+/**
+ * Inject a context value and return metadata about where it was resolved.
+ */
+export function injectMeta(token) {
+    const scope = getCurrentScope();
+    if (!scope) {
+        throw new Error("[Dalila] injectMeta() must be called within a scope. " +
+            "Wrap your code in withScope(...) or use the auto-scope API.");
+    }
+    const registry = getScopeRegistry(scope);
+    const res = registry.resolve(token);
+    if (!res) {
+        const name = token.name || "unnamed";
+        let message = `[Dalila] Context "${name}" not found in scope hierarchy.`;
+        if (isInDevMode()) {
+            const levels = debugListAvailableContexts(8);
+            if (levels.length > 0) {
+                message += `\n\nAvailable contexts by depth:\n`;
+                for (const level of levels) {
+                    const names = level.tokens.map((t) => t.name).join(", ") || "(none)";
+                    message += `  depth ${level.depth}: ${names}\n`;
+                }
+            }
+        }
+        throw new Error(message);
+    }
+    maybeWarnDeepHierarchy(res.depth);
+    return { value: res.value, ownerScope: res.ownerScope, depth: res.depth };
+}
+/**
+ * Debug helper: list available context tokens per depth.
+ */
+export function debugListAvailableContexts(maxPerLevel) {
+    const scope = getCurrentScope();
+    if (!scope)
+        return [];
+    const levels = [];
+    let depth = 0;
+    let current = scope;
+    while (current) {
+        const registry = scopeRegistries.get(current);
+        const tokens = registry
+            ? registry.listTokens(maxPerLevel).map((token) => ({
+                name: token.name || "unnamed",
+                token,
+            }))
+            : [];
+        levels.push({ depth, tokens });
+        current = current.parent;
+        depth++;
+    }
+    return levels;
+}
+/**
+ * Alias for debugListAvailableContexts (public helper name).
+ */
+export function listAvailableContexts(maxPerLevel) {
+    return debugListAvailableContexts(maxPerLevel);
+}

package/dist/context/index.d.ts

@@ -0,0 +1,2 @@
+export { createContext, setDeepHierarchyWarnDepth, listAvailableContexts, type ContextToken, type TryInjectResult, } from "./context.js";
+export { provide, inject, tryInject, scope, createProvider, createSignalContext, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, type SignalContext, } from "./auto-scope.js";

package/dist/context/index.js

@@ -0,0 +1,2 @@
+export { createContext, setDeepHierarchyWarnDepth, listAvailableContexts, } from "./context.js";
+export { provide, inject, tryInject, scope, createProvider, createSignalContext, provideGlobal, injectGlobal, setAutoScopePolicy, hasGlobalScope, getGlobalScope, resetGlobalScope, } from "./auto-scope.js";

package/dist/context/raw.d.ts

@@ -0,0 +1,2 @@
+export { createContext, setDeepHierarchyWarnDepth, type ContextToken, type TryInjectResult, } from "./context.js";
+export { provide, inject, tryInject, injectMeta, debugListAvailableContexts, listAvailableContexts, } from "./context.js";

package/dist/context/raw.js

@@ -0,0 +1,2 @@
+export { createContext, setDeepHierarchyWarnDepth, } from "./context.js";
+export { provide, inject, tryInject, injectMeta, debugListAvailableContexts, listAvailableContexts, } from "./context.js";

package/dist/core/dev.d.ts

@@ -0,0 +1,7 @@
+export declare function setDevMode(enabled: boolean): void;
+export declare function isInDevMode(): boolean;
+/**
+ * Initialize dev tools. Currently just enables dev mode.
+ * Returns a promise for future async initialization support.
+ */
+export declare function initDevTools(): Promise<void>;

package/dist/core/dev.js

@@ -0,0 +1,14 @@
+let isDevMode = true;
+export function setDevMode(enabled) {
+    isDevMode = enabled;
+}
+export function isInDevMode() {
+    return isDevMode;
+}
+/**
+ * Initialize dev tools. Currently just enables dev mode.
+ * Returns a promise for future async initialization support.
+ */
+export async function initDevTools() {
+    setDevMode(true);
+}

package/dist/core/for.d.ts

@@ -0,0 +1,42 @@
+interface DisposableFragment extends DocumentFragment {
+    dispose(): void;
+}
+/**
+ * Low-level keyed list rendering with fine-grained reactivity.
+ *
+ * Uses keyed diffing to efficiently update only changed items.
+ * Each item gets its own scope for automatic cleanup.
+ *
+ * @param items - Signal or function returning array of items
+ * @param template - Function that renders each item (receives item and reactive index)
+ * @param keyFn - Optional function to extract unique key from item (defaults to index)
+ *
+ * @example
+ * ```ts
+ * const todos = signal([
+ *   { id: 1, text: 'Learn Dalila' },
+ *   { id: 2, text: 'Build app' }
+ * ]);
+ *
+ * forEach(
+ *   () => todos(),
+ *   (todo, index) => {
+ *     const li = document.createElement('li');
+ *     li.textContent = `${index()}: ${todo.text}`;
+ *     return li;
+ *   },
+ *   (todo) => todo.id.toString()
+ * );
+ * ```
+ *
+ * @internal Prefer createList() for most use cases
+ */
+export declare function forEach<T>(items: () => T[], template: (item: T, index: () => number) => Node | Node[], keyFn?: (item: T, index: number) => string): DisposableFragment;
+/**
+ * Stable API for rendering keyed lists.
+ *
+ * Renders a reactive list with automatic updates when items change.
+ * Only re-renders items that actually changed (keyed diffing).
+ */
+export declare function createList<T>(items: () => T[], template: (item: T, index: number) => Node | Node[], keyFn?: (item: T, index: number) => string): DisposableFragment;
+export {};

package/dist/core/for.js

@@ -0,0 +1,311 @@
+import { effect, signal } from './signal.js';
+import { isInDevMode } from './dev.js';
+import { createScope, withScope, getCurrentScope } from './scope.js';
+const autoDisposeByDocument = new WeakMap();
+const getMutationObserverCtor = (doc) => {
+    if (doc.defaultView?.MutationObserver)
+        return doc.defaultView.MutationObserver;
+    if (typeof MutationObserver !== 'undefined')
+        return MutationObserver;
+    return null;
+};
+const registerAutoDispose = (start, end, cleanup) => {
+    const doc = start.ownerDocument;
+    const MutationObserverCtor = getMutationObserverCtor(doc);
+    if (!MutationObserverCtor)
+        return () => { };
+    let ctx = autoDisposeByDocument.get(doc);
+    if (!ctx) {
+        const entries = new Set();
+        const observer = new MutationObserverCtor(() => {
+            entries.forEach(entry => {
+                const connected = entry.start.isConnected && entry.end.isConnected;
+                if (!entry.attached && connected) {
+                    entry.attached = true;
+                    return;
+                }
+                if (entry.attached && !connected)
+                    entry.cleanup();
+            });
+            if (entries.size === 0) {
+                observer.disconnect();
+                autoDisposeByDocument.delete(doc);
+            }
+        });
+        observer.observe(doc, { childList: true, subtree: true });
+        ctx = { observer, entries };
+        autoDisposeByDocument.set(doc, ctx);
+    }
+    const entry = {
+        start,
+        end,
+        cleanup,
+        attached: start.isConnected && end.isConnected
+    };
+    ctx.entries.add(entry);
+    return () => {
+        ctx?.entries.delete(entry);
+        if (ctx && ctx.entries.size === 0) {
+            ctx.observer.disconnect();
+            autoDisposeByDocument.delete(doc);
+        }
+    };
+};
+/**
+ * Low-level keyed list rendering with fine-grained reactivity.
+ *
+ * Uses keyed diffing to efficiently update only changed items.
+ * Each item gets its own scope for automatic cleanup.
+ *
+ * @param items - Signal or function returning array of items
+ * @param template - Function that renders each item (receives item and reactive index)
+ * @param keyFn - Optional function to extract unique key from item (defaults to index)
+ *
+ * @example
+ * ```ts
+ * const todos = signal([
+ *   { id: 1, text: 'Learn Dalila' },
+ *   { id: 2, text: 'Build app' }
+ * ]);
+ *
+ * forEach(
+ *   () => todos(),
+ *   (todo, index) => {
+ *     const li = document.createElement('li');
+ *     li.textContent = `${index()}: ${todo.text}`;
+ *     return li;
+ *   },
+ *   (todo) => todo.id.toString()
+ * );
+ * ```
+ *
+ * @internal Prefer createList() for most use cases
+ */
+export function forEach(items, template, keyFn) {
+    const start = document.createComment('for:start');
+    const end = document.createComment('for:end');
+    let currentItems = [];
+    let disposeEffect = null;
+    const parentScope = getCurrentScope();
+    let disposed = false;
+    let stopAutoDispose = null;
+    const getKey = (item, index) => {
+        if (keyFn)
+            return keyFn(item, index);
+        // Using index as key is an anti-pattern for dynamic lists
+        // but we allow it as a fallback. Items will be re-rendered on reorder.
+        return `__idx_${index}`;
+    };
+    const removeNode = (node) => {
+        if (node.parentNode)
+            node.parentNode.removeChild(node);
+    };
+    const removeRange = (keyedItem) => {
+        // Dispose scope first to cleanup effects/listeners
+        if (keyedItem.scope) {
+            keyedItem.scope.dispose();
+            keyedItem.scope = null;
+        }
+        // Remove DOM nodes (including markers)
+        let node = keyedItem.start;
+        while (node) {
+            const next = node.nextSibling;
+            removeNode(node);
+            if (node === keyedItem.end)
+                break;
+            node = next;
+        }
+    };
+    const clearBetween = (startNode, endNode) => {
+        let node = startNode.nextSibling;
+        while (node && node !== endNode) {
+            const next = node.nextSibling;
+            removeNode(node);
+            node = next;
+        }
+    };
+    const moveRangeBefore = (startNode, endNode, referenceNode) => {
+        const parent = referenceNode.parentNode;
+        if (!parent)
+            return;
+        let node = startNode;
+        while (node) {
+            const next = node.nextSibling;
+            parent.insertBefore(node, referenceNode);
+            if (node === endNode)
+                break;
+            node = next;
+        }
+    };
+    let hasValidatedOnce = false;
+    const throwDuplicateKey = (key, scheduleFatal) => {
+        const error = new Error(`[Dalila] Duplicate key "${key}" detected in forEach. ` +
+            `Keys must be unique within the same list. Check your keyFn implementation.`);
+        if (scheduleFatal) {
+            queueMicrotask(() => {
+                throw error;
+            });
+        }
+        throw error;
+    };
+    const validateNoDuplicateKeys = (arr) => {
+        if (!isInDevMode())
+            return;
+        const scheduleFatal = hasValidatedOnce;
+        hasValidatedOnce = true;
+        const seenKeys = new Set();
+        arr.forEach((item, index) => {
+            const key = getKey(item, index);
+            if (seenKeys.has(key)) {
+                throwDuplicateKey(key, scheduleFatal);
+            }
+            seenKeys.add(key);
+        });
+    };
+    const disposeItemScope = (item) => {
+        if (!item.scope)
+            return;
+        item.scope.dispose();
+        item.scope = null;
+    };
+    const cleanup = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        stopAutoDispose?.();
+        stopAutoDispose = null;
+        disposeEffect?.();
+        disposeEffect = null;
+        currentItems.forEach(item => {
+            removeRange(item);
+        });
+        currentItems = [];
+        removeNode(start);
+        removeNode(end);
+    };
+    // Validate first render synchronously (let throw escape in dev)
+    validateNoDuplicateKeys(items());
+    const update = () => {
+        if (disposed)
+            return;
+        const newItems = items();
+        // Validate again on updates (will be caught by effect error handler)
+        validateNoDuplicateKeys(newItems);
+        const oldMap = new Map();
+        currentItems.forEach(item => oldMap.set(item.key, item));
+        const nextItems = [];
+        const itemsToUpdate = new Set();
+        const seenNextKeys = new Set();
+        // Phase 1: Build next list + detect updates/new
+        newItems.forEach((item, index) => {
+            const key = getKey(item, index);
+            if (seenNextKeys.has(key))
+                return; // prod-mode: ignore dup keys silently
+            seenNextKeys.add(key);
+            const existing = oldMap.get(key);
+            if (existing) {
+                if (existing.value !== item) {
+                    itemsToUpdate.add(key);
+                    existing.value = item;
+                }
+                nextItems.push(existing);
+            }
+            else {
+                itemsToUpdate.add(key);
+                nextItems.push({
+                    key,
+                    value: item,
+                    start: document.createComment(`for:${key}:start`),
+                    end: document.createComment(`for:${key}:end`),
+                    scope: null,
+                    indexSignal: signal(index)
+                });
+            }
+        });
+        // Phase 2: Remove items no longer present
+        const nextKeys = new Set(nextItems.map(i => i.key));
+        currentItems.forEach(item => {
+            if (!nextKeys.has(item.key))
+                removeRange(item);
+        });
+        // Phase 3: Move/insert items to correct positions
+        const parent = end.parentNode;
+        if (parent) {
+            let cursor = start;
+            nextItems.forEach(item => {
+                const nextSibling = cursor.nextSibling;
+                const inDom = item.start.parentNode === parent;
+                if (!inDom) {
+                    const referenceNode = nextSibling || end;
+                    referenceNode.before(item.start, item.end);
+                }
+                else if (nextSibling !== item.start) {
+                    const referenceNode = nextSibling || end;
+                    moveRangeBefore(item.start, item.end, referenceNode);
+                }
+                cursor = item.end;
+            });
+        }
+        // Phase 4: Dispose scopes and clear content for changed items
+        nextItems.forEach(item => {
+            if (!itemsToUpdate.has(item.key))
+                return;
+            disposeItemScope(item);
+            clearBetween(item.start, item.end);
+        });
+        // Phase 5: Update reactive indices for ALL items
+        nextItems.forEach((item, index) => {
+            item.indexSignal.set(index);
+        });
+        // Phase 6: Render changed items
+        nextItems.forEach(item => {
+            if (!itemsToUpdate.has(item.key))
+                return;
+            item.scope = createScope();
+            withScope(item.scope, () => {
+                const indexGetter = () => item.indexSignal();
+                const templateResult = template(item.value, indexGetter);
+                const nodes = Array.isArray(templateResult) ? templateResult : [templateResult];
+                item.end.before(...nodes);
+            });
+        });
+        currentItems = nextItems;
+    };
+    // IMPORTANT: append markers BEFORE creating the effect,
+    // so a synchronous effect run can still render into the fragment safely.
+    const frag = document.createDocumentFragment();
+    frag.append(start, end);
+    frag.dispose = cleanup;
+    // Run update reactively and capture dispose
+    disposeEffect = effect(() => {
+        if (disposed)
+            return;
+        update();
+    });
+    // Cleanup on parent scope disposal
+    if (parentScope) {
+        parentScope.onCleanup(cleanup);
+    }
+    else {
+        stopAutoDispose = registerAutoDispose(start, end, cleanup);
+        if (isInDevMode()) {
+            console.warn('[Dalila] forEach() called outside of a scope. ' +
+                'The effect will not be tied to a scope. ' +
+                'It will auto-dispose when removed from the DOM, ' +
+                'or call fragment.dispose() for manual cleanup if needed.');
+        }
+    }
+    return frag;
+}
+/**
+ * Stable API for rendering keyed lists.
+ *
+ * Renders a reactive list with automatic updates when items change.
+ * Only re-renders items that actually changed (keyed diffing).
+ */
+export function createList(items, template, keyFn) {
+    return forEach(items, (item, index) => {
+        const idx = index();
+        return template(item, idx);
+    }, keyFn);
+}

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./scope.js";
+export * from "./signal.js";
+export * from "./watch.js";
+export * from "./when.js";
+export * from "./match.js";
+export * from "./for.js";
+export * from "./virtual.js";
+export * from "./dev.js";
+export * from "./key.js";
+export * from "./resource.js";
+export * from "./query.js";
+export * from "./mutation.js";
+export { batch, measure, mutate, configureScheduler, getSchedulerConfig } from "./scheduler.js";
+export { persist, createJSONStorage, clearPersisted, createPreloadScript, createThemeScript, type StateStorage, type PersistOptions, type Serializer, type PreloadScriptOptions } from "./persist.js";