dalila 1.9.21 → 1.9.22

package/README.md

@@ -58,7 +58,9 @@ bind(document.getElementById('app')!, ctx);
 ### Core
 
 - [Signals](./docs/core/signals.md)
+- [Effects Guide](./docs/core/effects-guide.md)
 - [Scopes](./docs/core/scope.md)
+- [Scopes Guide](./docs/core/scopes-guide.md)
 - [Persist](./docs/core/persist.md)
 - [Context](./docs/context.md)
 - [Scheduler](./docs/core/scheduler.md)
@@ -88,11 +90,6 @@ bind(document.getElementById('app')!, ctx);
 - [Template Check CLI](./docs/cli/check.md)
 - [Devtools Extension](./devtools-extension/README.md)
 
-Firefox extension workflows:
-
-- `npm run devtools:firefox:run` — launch Firefox with extension loaded for dev
-- `npm run devtools:firefox:build` — package extension artifact for submission/signing
-
 ## Packages
 
 ```txt
@@ -110,6 +107,7 @@ npm install
 npm run build
 npm run serve   # Dev server with HMR
 npm test
+npm run test:watch
 ```
 
 ## License

package/dist/components/ui/ui-types.d.ts

@@ -1,4 +1,4 @@
-import type { Signal } from "../../core/signal.js";
+import type { ComputedSignal, ReadonlySignal, Signal } from "../../core/signal.js";
 export interface DialogOptions {
     closeOnBackdrop?: boolean;
     closeOnEscape?: boolean;
@@ -56,9 +56,9 @@ export interface Tabs {
     _attachTo(el: HTMLElement): void;
 }
 export interface TabBindings {
-    tabClass: Signal<string>;
-    selected: Signal<string>;
-    visible: Signal<boolean>;
+    tabClass: ComputedSignal<string>;
+    selected: ComputedSignal<string>;
+    visible: ComputedSignal<boolean>;
 }
 export interface DropdownOptions {
     closeOnSelect?: boolean;
@@ -84,7 +84,7 @@ export interface Combobox {
     query: Signal<string>;
     value: Signal<string>;
     label: Signal<string>;
-    filtered: Signal<ComboboxOption[]>;
+    filtered: ReadonlySignal<ComboboxOption[]>;
     highlightedIndex: Signal<number>;
     show(): void;
     close(): void;
@@ -103,7 +103,7 @@ export interface Accordion {
     toggle(itemId: string): void;
     open(itemId: string): void;
     close(itemId: string): void;
-    isOpen(itemId: string): Signal<boolean>;
+    isOpen(itemId: string): ReadonlySignal<boolean>;
     _attachTo(el: HTMLElement): void;
 }
 export interface CalendarDay {
@@ -125,8 +125,8 @@ export interface Calendar {
     year: Signal<number>;
     month: Signal<number>;
     selected: Signal<Date | null>;
-    title: Signal<string>;
-    days: Signal<CalendarDay[]>;
+    title: ReadonlySignal<string>;
+    days: ReadonlySignal<CalendarDay[]>;
     dayLabels: string[];
     prev(): void;
     next(): void;

package/dist/core/signal.d.ts

@@ -24,6 +24,10 @@ export interface ReadonlySignal<T> {
     /** Subscribe to value changes manually (outside of effects). Returns unsubscribe function. */
     on(callback: (value: T) => void): () => void;
 }
+export interface ComputedSignal<T> extends ReadonlySignal<T> {
+    /** Nominal marker to improve IntelliSense/readability in docs and types. */
+    readonly __dalilaComputed?: true;
+}
 export interface DebounceSignalOptions {
     /** Emit immediately on the first update in a burst. Default: false */
     leading?: boolean;
@@ -107,7 +111,11 @@ export declare function effect(fn: () => void): () => void;
  * Subscription:
  * - other effects can subscribe to the computed like a normal signal
  */
-export declare function computed<T>(fn: () => T): Signal<T>;
+export declare function computed<T>(fn: () => T): ComputedSignal<T>;
+/** Short alias for `debounceSignal()`. */
+export declare function debounce<T>(source: ReadonlySignal<T>, waitMs: number, options?: DebounceSignalOptions): ReadonlySignal<T>;
+/** Short alias for `throttleSignal()`. */
+export declare function throttle<T>(source: ReadonlySignal<T>, waitMs: number, options?: ThrottleSignalOptions): ReadonlySignal<T>;
 /**
  * Async effect with cancellation.
  *

package/dist/core/signal.js

@@ -100,6 +100,31 @@ function trySubscribeActiveEffect(subscribers, signalRef) {
     (activeEffect.deps ?? (activeEffect.deps = new Set())).add(subscribers);
     trackDependency(signalRef, activeEffect);
 }
+function cleanupEffectDeps(run) {
+    if (!run.deps)
+        return;
+    for (const depSet of run.deps) {
+        depSet.delete(run);
+        untrackDependencyBySet(depSet, run);
+    }
+    run.deps.clear();
+}
+function runTrackedEffectBody(run, owningScope, exec) {
+    const prevEffect = activeEffect;
+    const prevScope = activeScope;
+    activeEffect = run;
+    activeScope = owningScope ?? null;
+    try {
+        if (owningScope)
+            withScope(owningScope, exec);
+        else
+            exec();
+    }
+    finally {
+        activeEffect = prevEffect;
+        activeScope = prevScope;
+    }
+}
 /**
  * Create a signal: a mutable value with automatic dependency tracking.
  *
@@ -348,20 +373,11 @@ export function throttleSignal(source, waitMs, options = {}) {
  */
 export function effect(fn) {
     const owningScope = getCurrentScope();
-    const cleanupDeps = () => {
-        if (!run.deps)
-            return;
-        for (const depSet of run.deps) {
-            depSet.delete(run);
-            untrackDependencyBySet(depSet, run);
-        }
-        run.deps.clear();
-    };
     const dispose = () => {
         if (run.disposed)
             return;
         run.disposed = true;
-        cleanupDeps();
+        cleanupEffectDeps(run);
         run.queued = false;
         trackEffectDispose(run);
     };
@@ -370,22 +386,12 @@ export function effect(fn) {
             return;
         trackEffectRunStart(run);
         // Dynamic deps: unsubscribe from previous reads.
-        cleanupDeps();
-        const prevEffect = activeEffect;
-        const prevScope = activeScope;
-        activeEffect = run;
-        activeScope = owningScope ?? null;
+        cleanupEffectDeps(run);
         try {
-            // Run inside owning scope so resources created by the effect are scoped.
-            if (owningScope)
-                withScope(owningScope, fn);
-            else
-                fn();
+            runTrackedEffectBody(run, owningScope ?? null, fn);
         }
         finally {
             trackEffectRunEnd(run);
-            activeEffect = prevEffect;
-            activeScope = prevScope;
         }
     });
     registerEffect(run, 'effect', owningScope);
@@ -439,34 +445,33 @@ export function computed(fn) {
         if (markDirty.deps)
             markDirty.deps.clear();
     };
+    const recomputeIfDirty = () => {
+        if (!dirty)
+            return;
+        trackComputedRunStart(signalRef);
+        cleanupDeps();
+        const prevEffect = activeEffect;
+        const prevScope = activeScope;
+        // Collect deps into markDirty.
+        activeEffect = markDirty;
+        activeScope = null;
+        try {
+            value = fn();
+            dirty = false;
+            if (markDirty.deps)
+                trackedDeps = new Set(markDirty.deps);
+        }
+        finally {
+            trackComputedRunEnd(signalRef);
+            activeEffect = prevEffect;
+            activeScope = prevScope;
+        }
+    };
     const read = () => {
         trackSignalRead(signalRef);
         // Allow effects to subscribe to this computed (same rules as signal()).
         trySubscribeActiveEffect(subscribers, signalRef);
-        if (dirty) {
-            trackComputedRunStart(signalRef);
-            cleanupDeps();
-            const prevEffect = activeEffect;
-            const prevScope = activeScope;
-            // Collect deps into markDirty.
-            activeEffect = markDirty;
-            // During dependency collection for computed:
-            // - we want to subscribe to its dependencies regardless of the caller scope.
-            // - the computed's deps belong to the computed itself, not to whoever read it.
-            activeScope = null;
-            try {
-                value = fn();
-                dirty = false;
-                // Snapshot the current dep sets for later unsubscription.
-                if (markDirty.deps)
-                    trackedDeps = new Set(markDirty.deps);
-            }
-            finally {
-                trackComputedRunEnd(signalRef);
-                activeEffect = prevEffect;
-                activeScope = prevScope;
-            }
-        }
+        recomputeIfDirty();
         return value;
     };
     read.set = () => {
@@ -477,25 +482,7 @@ export function computed(fn) {
     };
     read.peek = () => {
         // For computed, peek still needs to compute if dirty, but without tracking
-        if (dirty) {
-            trackComputedRunStart(signalRef);
-            cleanupDeps();
-            const prevEffect = activeEffect;
-            const prevScope = activeScope;
-            activeEffect = markDirty;
-            activeScope = null;
-            try {
-                value = fn();
-                dirty = false;
-                if (markDirty.deps)
-                    trackedDeps = new Set(markDirty.deps);
-            }
-            finally {
-                trackComputedRunEnd(signalRef);
-                activeEffect = prevEffect;
-                activeScope = prevScope;
-            }
-        }
+        recomputeIfDirty();
         return value;
     };
     read.on = (callback) => {
@@ -525,6 +512,14 @@ export function computed(fn) {
     registerEffect(markDirty, 'effect', owningScope);
     return read;
 }
+/** Short alias for `debounceSignal()`. */
+export function debounce(source, waitMs, options = {}) {
+    return debounceSignal(source, waitMs, options);
+}
+/** Short alias for `throttleSignal()`. */
+export function throttle(source, waitMs, options = {}) {
+    return throttleSignal(source, waitMs, options);
+}
 /**
  * Async effect with cancellation.
  *
@@ -536,22 +531,13 @@ export function computed(fn) {
 export function effectAsync(fn) {
     const owningScope = getCurrentScope();
     let controller = null;
-    const cleanupDeps = () => {
-        if (!run.deps)
-            return;
-        for (const depSet of run.deps) {
-            depSet.delete(run);
-            untrackDependencyBySet(depSet, run);
-        }
-        run.deps.clear();
-    };
     const dispose = () => {
         if (run.disposed)
             return;
         run.disposed = true;
         controller?.abort();
         controller = null;
-        cleanupDeps();
+        cleanupEffectDeps(run);
         run.queued = false;
         trackEffectDispose(run);
     };
@@ -562,22 +548,12 @@ export function effectAsync(fn) {
         // Abort previous run (if any), then create a new controller for this run.
         controller?.abort();
         controller = new AbortController();
-        cleanupDeps();
-        const prevEffect = activeEffect;
-        const prevScope = activeScope;
-        activeEffect = run;
-        activeScope = owningScope ?? null;
+        cleanupEffectDeps(run);
         try {
-            const exec = () => fn(controller.signal);
-            if (owningScope)
-                withScope(owningScope, exec);
-            else
-                exec();
+            runTrackedEffectBody(run, owningScope ?? null, () => fn(controller.signal));
         }
         finally {
             trackEffectRunEnd(run);
-            activeEffect = prevEffect;
-            activeScope = prevScope;
         }
     });
     registerEffect(run, 'effectAsync', owningScope);

package/dist/form/field-array.d.ts

@@ -0,0 +1,12 @@
+import { type Signal } from '../core/signal.js';
+import type { Scope } from '../core/scope.js';
+import type { FieldArray, FieldErrors } from './form-types.js';
+export interface FieldArrayOptions {
+    form: HTMLFormElement | null;
+    scope: Scope | null;
+    onMutate?: () => void;
+    errors?: Signal<FieldErrors>;
+    touchedSet?: Signal<Set<string>>;
+    dirtySet?: Signal<Set<string>>;
+}
+export declare function createFieldArray<TItem = unknown>(basePath: string, options: FieldArrayOptions): FieldArray<TItem>;

package/dist/form/field-array.js

@@ -0,0 +1,306 @@
+import { signal } from '../core/signal.js';
+export function createFieldArray(basePath, options) {
+    const keys = signal([]);
+    const values = signal(new Map());
+    let keyCounter = 0;
+    function generateKey() {
+        return `${basePath}_${keyCounter++}`;
+    }
+    function remapMetaState(oldIndices, newIndices) {
+        if (!options.errors && !options.touchedSet && !options.dirtySet)
+            return;
+        const indexMap = new Map();
+        for (let i = 0; i < oldIndices.length; i++) {
+            indexMap.set(oldIndices[i], newIndices[i]);
+        }
+        if (options.errors) {
+            options.errors.update((prev) => {
+                const next = {};
+                for (const [path, message] of Object.entries(prev)) {
+                    const newPath = remapPath(path, indexMap);
+                    next[newPath] = message;
+                }
+                return next;
+            });
+        }
+        if (options.touchedSet) {
+            options.touchedSet.update((prev) => {
+                const next = new Set();
+                for (const path of prev) {
+                    next.add(remapPath(path, indexMap));
+                }
+                return next;
+            });
+        }
+        if (options.dirtySet) {
+            options.dirtySet.update((prev) => {
+                const next = new Set();
+                for (const path of prev) {
+                    next.add(remapPath(path, indexMap));
+                }
+                return next;
+            });
+        }
+    }
+    function remapPath(path, indexMap) {
+        const regex = new RegExp(`^${escapeRegExp(basePath)}\\[(\\d+)\\](.*)$`);
+        const match = path.match(regex);
+        if (!match)
+            return path;
+        const oldIndex = parseInt(match[1], 10);
+        const rest = match[2];
+        const newIndex = indexMap.get(oldIndex);
+        if (newIndex === undefined)
+            return path;
+        return `${basePath}[${newIndex}]${rest}`;
+    }
+    function escapeRegExp(string) {
+        return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+    function fields() {
+        const currentKeys = keys();
+        const currentValues = values();
+        return currentKeys.map((key) => ({
+            key,
+            value: currentValues.get(key),
+        }));
+    }
+    function length() {
+        return keys().length;
+    }
+    function _getIndex(key) {
+        return keys().indexOf(key);
+    }
+    function _translatePath(path) {
+        const match = path.match(/^([^\[]+)\[(\d+)\](.*)$/);
+        if (!match)
+            return null;
+        const [, arrayPath, indexStr, rest] = match;
+        if (arrayPath !== basePath)
+            return null;
+        const index = parseInt(indexStr, 10);
+        const currentKeys = keys();
+        const key = currentKeys[index];
+        if (!key)
+            return null;
+        return `${arrayPath}:${key}${rest}`;
+    }
+    function append(value) {
+        const items = Array.isArray(value) ? value : [value];
+        const newKeys = items.map(() => generateKey());
+        keys.update((prev) => [...prev, ...newKeys]);
+        values.update((prev) => {
+            const next = new Map(prev);
+            newKeys.forEach((key, i) => next.set(key, items[i]));
+            return next;
+        });
+        options.onMutate?.();
+    }
+    function remove(key) {
+        const removeIndex = _getIndex(key);
+        const currentLength = keys().length;
+        keys.update((prev) => prev.filter((k) => k !== key));
+        values.update((prev) => {
+            const next = new Map(prev);
+            next.delete(key);
+            return next;
+        });
+        if (removeIndex >= 0) {
+            const prefix = `${basePath}[${removeIndex}]`;
+            if (options.errors) {
+                options.errors.update((prev) => {
+                    const next = {};
+                    for (const [path, message] of Object.entries(prev)) {
+                        if (!path.startsWith(prefix))
+                            next[path] = message;
+                    }
+                    return next;
+                });
+            }
+            if (options.touchedSet) {
+                options.touchedSet.update((prev) => {
+                    const next = new Set();
+                    for (const path of prev) {
+                        if (!path.startsWith(prefix))
+                            next.add(path);
+                    }
+                    return next;
+                });
+            }
+            if (options.dirtySet) {
+                options.dirtySet.update((prev) => {
+                    const next = new Set();
+                    for (const path of prev) {
+                        if (!path.startsWith(prefix))
+                            next.add(path);
+                    }
+                    return next;
+                });
+            }
+            const oldIndices = [];
+            const newIndices = [];
+            for (let i = removeIndex + 1; i < currentLength; i++) {
+                oldIndices.push(i);
+                newIndices.push(i - 1);
+            }
+            if (oldIndices.length > 0)
+                remapMetaState(oldIndices, newIndices);
+        }
+        options.onMutate?.();
+    }
+    function removeAt(index) {
+        if (index < 0 || index >= keys().length)
+            return;
+        const key = keys()[index];
+        if (key)
+            remove(key);
+    }
+    function insert(index, value) {
+        const len = keys().length;
+        if (index < 0 || index > len)
+            return;
+        const key = generateKey();
+        const currentLength = len;
+        const oldIndices = [];
+        const newIndices = [];
+        for (let i = index; i < currentLength; i++) {
+            oldIndices.push(i);
+            newIndices.push(i + 1);
+        }
+        if (oldIndices.length > 0)
+            remapMetaState(oldIndices, newIndices);
+        keys.update((prev) => {
+            const next = [...prev];
+            next.splice(index, 0, key);
+            return next;
+        });
+        values.update((prev) => {
+            const next = new Map(prev);
+            next.set(key, value);
+            return next;
+        });
+        options.onMutate?.();
+    }
+    function move(fromIndex, toIndex) {
+        const len = keys().length;
+        if (fromIndex < 0 || fromIndex >= len || toIndex < 0 || toIndex >= len)
+            return;
+        if (fromIndex === toIndex)
+            return;
+        const oldIndices = [];
+        const newIndices = [];
+        if (fromIndex < toIndex) {
+            oldIndices.push(fromIndex);
+            newIndices.push(toIndex);
+            for (let i = fromIndex + 1; i <= toIndex; i++) {
+                oldIndices.push(i);
+                newIndices.push(i - 1);
+            }
+        }
+        else {
+            oldIndices.push(fromIndex);
+            newIndices.push(toIndex);
+            for (let i = toIndex; i < fromIndex; i++) {
+                oldIndices.push(i);
+                newIndices.push(i + 1);
+            }
+        }
+        remapMetaState(oldIndices, newIndices);
+        keys.update((prev) => {
+            const next = [...prev];
+            const [item] = next.splice(fromIndex, 1);
+            next.splice(toIndex, 0, item);
+            return next;
+        });
+        options.onMutate?.();
+    }
+    function swap(indexA, indexB) {
+        const len = keys().length;
+        if (indexA < 0 || indexA >= len || indexB < 0 || indexB >= len)
+            return;
+        if (indexA === indexB)
+            return;
+        remapMetaState([indexA, indexB], [indexB, indexA]);
+        keys.update((prev) => {
+            const next = [...prev];
+            [next[indexA], next[indexB]] = [next[indexB], next[indexA]];
+            return next;
+        });
+        options.onMutate?.();
+    }
+    function replace(newValues) {
+        const newKeys = newValues.map(() => generateKey());
+        if (options.errors) {
+            options.errors.update((prev) => {
+                const next = {};
+                for (const [path, message] of Object.entries(prev)) {
+                    if (!path.startsWith(`${basePath}[`))
+                        next[path] = message;
+                }
+                return next;
+            });
+        }
+        if (options.touchedSet) {
+            options.touchedSet.update((prev) => {
+                const next = new Set();
+                for (const path of prev) {
+                    if (!path.startsWith(`${basePath}[`))
+                        next.add(path);
+                }
+                return next;
+            });
+        }
+        if (options.dirtySet) {
+            options.dirtySet.update((prev) => {
+                const next = new Set();
+                for (const path of prev) {
+                    if (!path.startsWith(`${basePath}[`))
+                        next.add(path);
+                }
+                return next;
+            });
+        }
+        keys.set(newKeys);
+        values.set(new Map(newKeys.map((key, i) => [key, newValues[i]])));
+        options.onMutate?.();
+    }
+    function update(key, value) {
+        values.update((prev) => {
+            const next = new Map(prev);
+            next.set(key, value);
+            return next;
+        });
+        options.onMutate?.();
+    }
+    function updateAt(index, value) {
+        if (index < 0 || index >= keys().length)
+            return;
+        const key = keys()[index];
+        if (key)
+            update(key, value);
+    }
+    function clear() {
+        replace([]);
+    }
+    if (options.scope) {
+        options.scope.onCleanup(() => {
+            clear();
+        });
+    }
+    return {
+        fields,
+        append,
+        remove,
+        removeAt,
+        insert,
+        move,
+        swap,
+        replace,
+        update,
+        updateAt,
+        clear,
+        length,
+        _getIndex,
+        _translatePath,
+    };
+}

package/dist/form/form-dom.d.ts

@@ -0,0 +1,6 @@
+export declare function findFormFieldElement(formElement: HTMLFormElement | null, path: string): HTMLElement | null;
+/**
+ * Reset all `[d-field]` DOM controls to the provided defaults.
+ * Keeps field arrays and meta-state handling to the caller.
+ */
+export declare function resetFormDomFields<T>(formElement: HTMLFormElement | null, defaultValues: Partial<T>): void;