@tempots/dom 31.6.1 → 32.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tempots/dom",
-  "version": "31.6.1",
+  "version": "32.0.0",
   "type": "module",
   "main": "./index.cjs",
   "module": "./index.js",

package/renderable/render.d.ts

@@ -5,6 +5,10 @@ import { Value } from '../std/value';
 /**
  * Renders the given `renderable` with the provided `ctx` DOM context.
  *
+ * Creates a DisposalScope for automatic signal disposal. All signals created
+ * during the renderable execution are tracked and disposed when the clear
+ * function is called.
+ *
  * @param renderable - The renderable node to be rendered.
  * @param ctx - The DOM context to be used for rendering.
  * @returns A function that can be called to clear the rendered node.

package/renderable/utils.d.ts

@@ -20,6 +20,7 @@ export declare const handleValueOrSignal: <T, R>(value: Value<T>, onSignal: (sig
  * - Setting up a signal listener that re-renders on changes
  * - Properly cleaning up the old render before creating a new one
  * - Disposing the signal listener and context on cleanup
+ * - Creating a disposal scope for each branch to track signals
  *
  * @param ctx - The parent DOM context
  * @param signal - The signal to watch for changes

package/renderable/with-scope.d.ts

@@ -0,0 +1,39 @@
+import { DisposalScope } from '../std/disposal-scope';
+import { Renderable, TNode } from '../types/domain';
+/**
+ * Creates a renderable that provides explicit access to a DisposalScope.
+ *
+ * This is useful when you need to create signals in async contexts (like setTimeout,
+ * fetch callbacks, event handlers) where automatic scope tracking doesn't work.
+ *
+ * @example
+ * ```typescript
+ * // Using scope in async context
+ * WithScope(scope => {
+ *   setTimeout(() => {
+ *     const signal = scope.prop(42)
+ *     // signal will be disposed when component unmounts
+ *   }, 1000)
+ *
+ *   return html.div('Loading...')
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using scope with fetch
+ * WithScope(scope => {
+ *   fetch('/api/data').then(response => {
+ *     const data = scope.prop(response.data)
+ *     // data will be disposed when component unmounts
+ *   })
+ *
+ *   return html.div('Fetching...')
+ * })
+ * ```
+ *
+ * @param fn - Function that receives the scope and returns content to render
+ * @returns A renderable that manages the scope lifecycle
+ * @public
+ */
+export declare const WithScope: (fn: (scope: DisposalScope) => TNode) => Renderable;

package/std/disposal-scope.d.ts

@@ -0,0 +1,97 @@
+import { AnySignal, Computed, ListenerOptions, Prop } from './signal';
+import { Value } from './value';
+import { ValueTypes } from '../types/domain';
+/**
+ * A DisposalScope tracks signals created during its lifetime and disposes them when the scope ends.
+ * This enables automatic signal disposal without manual OnDispose() calls.
+ *
+ * @public
+ */
+export declare class DisposalScope {
+    private _signals;
+    private _callbacks;
+    private _disposed;
+    /**
+     * Register a signal with this scope for automatic disposal.
+     *
+     * @param signal - The signal to track
+     * @throws Error if the scope has already been disposed
+     * @throws Error if the signal has already been disposed
+     * @public
+     */
+    track(signal: AnySignal): void;
+    /**
+     * Register a disposal callback to be called when this scope is disposed.
+     * Callbacks are called before signals are disposed.
+     * Use this for cleanup that doesn't need the `removeTree` parameter.
+     *
+     * @param callback - The callback to call on disposal
+     * @throws Error if the scope has already been disposed
+     * @public
+     */
+    onDispose(callback: () => void): void;
+    /**
+     * Dispose all signals tracked by this scope.
+     * This method is idempotent - calling it multiple times is safe.
+     *
+     * @public
+     */
+    dispose(): void;
+    /**
+     * Check if this scope has been disposed.
+     *
+     * @returns true if the scope has been disposed
+     * @public
+     */
+    get disposed(): boolean;
+    /**
+     * Creates a prop signal and tracks it in this scope.
+     * Use this method in async contexts where automatic tracking doesn't work.
+     *
+     * @param value - The initial value
+     * @param equals - Optional equality function
+     * @returns A tracked Prop signal
+     * @public
+     */
+    prop<T>(value: T, equals?: (a: T, b: T) => boolean): Prop<T>;
+    /**
+     * Creates a computed signal and tracks it in this scope.
+     * Use this method in async contexts where automatic tracking doesn't work.
+     *
+     * @param fn - The computation function
+     * @param dependencies - Array of signals this computed depends on
+     * @param equals - Optional equality function
+     * @returns A tracked Computed signal
+     * @public
+     */
+    computed<T>(fn: () => T, dependencies: Array<AnySignal>, equals?: (a: T, b: T) => boolean): Computed<T>;
+    /**
+     * Creates an effect and tracks it in this scope.
+     * Use this method in async contexts where automatic tracking doesn't work.
+     *
+     * @param fn - The effect function
+     * @param signals - Array of signals to listen to
+     * @param options - Optional listener options
+     * @returns A clear function (the effect itself is tracked in the scope)
+     * @public
+     */
+    effect(fn: () => void, signals: Array<AnySignal>, options?: ListenerOptions): () => void;
+    /**
+     * Creates a computed signal with curried signature and tracks it in this scope.
+     * Use this method in async contexts where automatic tracking doesn't work.
+     *
+     * @param args - Values or signals to compute from
+     * @returns A function that takes the computation function and returns a tracked Computed signal
+     * @public
+     */
+    computedOf<T extends Value<unknown>[]>(...args: T): <O>(fn: (...args: ValueTypes<T>) => O, equals?: (a: O, b: O) => boolean) => Computed<O>;
+    /**
+     * Creates an effect with curried signature and tracks it in this scope.
+     * Use this method in async contexts where automatic tracking doesn't work.
+     *
+     * @param args - Values or signals to listen to
+     * @returns A function that takes the effect function and returns a clear function
+     * @public
+     */
+    effectOf<T extends Value<unknown>[]>(...args: T): (fn: (...args: ValueTypes<T>) => void, options?: ListenerOptions) => (() => void);
+}

package/std/element-position.d.ts

@@ -52,5 +52,13 @@ export declare class ElementPosition {
      * @returns `true` if the element is the last element, `false` otherwise.
      */
     get isLast(): Signal<boolean>;
+    /**
+     * Disposes the internal signal created by `isLast`.
+     *
+     * **Note:** With automatic signal disposal, this method is now a no-op when used within
+     * a disposal scope (e.g., inside a renderable). The signal created by `isLast` is
+     * automatically tracked and disposed when the scope ends. This method is kept for
+     * backward compatibility and for cases where ElementPosition is used outside a scope.
+     */
     readonly dispose: () => void;
 }

package/std/scope-stack.d.ts

@@ -0,0 +1,76 @@
+import { DisposalScope } from './disposal-scope';
+/**
+ * Global scope stack for tracking active disposal scopes.
+ * The last element in the array is the current scope.
+ *
+ * @internal
+ */
+export declare const scopeStack: DisposalScope[];
+/**
+ * Push a scope onto the stack, making it the current scope.
+ *
+ * @param scope - The scope to push
+ * @internal
+ */
+export declare const pushScope: (scope: DisposalScope) => void;
+/**
+ * Pop the current scope from the stack.
+ *
+ * @throws Error if the stack is empty
+ * @internal
+ */
+export declare const popScope: () => void;
+/**
+ * Get the current active scope.
+ *
+ * @returns The current scope, or null if no scope is active
+ * @public
+ */
+export declare const getCurrentScope: () => DisposalScope | null;
+/**
+ * Get the full scope stack.
+ * Useful for debugging scope hierarchy.
+ *
+ * @advanced Most users don't need this. Use getCurrentScope() instead.
+ * @returns Read-only array of active scopes
+ * @public
+ */
+export declare const getScopeStack: () => readonly DisposalScope[];
+/**
+ * Get the parent scope of the current scope.
+ *
+ * @advanced Most users don't need this. Accessing parent scopes can lead to
+ * unexpected behavior. Only use this for debugging or advanced use cases.
+ * @returns The parent scope or null if no parent exists
+ * @public
+ */
+export declare const getParentScope: () => DisposalScope | null;
+/**
+ * Execute a function within a scope context.
+ * The scope is pushed before the function executes and popped after.
+ * The scope is NOT disposed - the caller is responsible for disposal.
+ *
+ * @param scope - The scope to use
+ * @param fn - The function to execute
+ * @returns The result of the function
+ * @public
+ */
+export declare const withScope: <T>(scope: DisposalScope, fn: () => T) => T;
+/**
+ * Execute a function in a new scope and dispose the scope immediately after.
+ * Useful for one-off scoped operations.
+ *
+ * @param fn - The function to execute, receives the scope as parameter
+ * @returns The result of the function
+ * @public
+ */
+export declare const scoped: <T>(fn: (scope: DisposalScope) => T) => T;
+/**
+ * Execute a function without any scope tracking.
+ * Signals created inside will NOT be automatically tracked.
+ *
+ * @param fn - The function to execute
+ * @returns The result of the function
+ * @public
+ */
+export declare const untracked: <T>(fn: () => T) => T;

package/std/signal.d.ts

@@ -157,6 +157,15 @@ export declare class Signal<T> {
      * @param options - Options for the listener.
      */
     readonly on: (listener: (value: T, previousValue: T | undefined) => void, options?: ListenerOptions) => () => void;
+    /**
+     * Registers a listener function to be called whenever the value of the signal changes.
+     * The listener function will not be called with the current value of the signal.
+     * Returns a function that can be called to unregister the listener.
+     *
+     * @param listener - The listener function to be called when the value of the signal changes.
+     * @param options - Options for the listener.
+     */
+    readonly onChange: (listener: (value: T, previousValue: T) => void, options?: ListenerOptions) => () => void;
     /**
      * @internal
      */
@@ -225,10 +234,22 @@ export declare class Signal<T> {
      * )
      * ```
      *
+     * **Auto-Disposal:** The returned computed signal is automatically registered with the current
+     * disposal scope (if one exists). When used within a renderable or `WithScope()`, the signal
+     * will be automatically disposed when the component unmounts. No manual `OnDispose()` needed!
+     *
+     * ```typescript
+     * const MyComponent: Renderable = (ctx) => {
+     *   const count = prop(0);
+     *   const doubled = count.map(x => x * 2);  // ✅ Auto-disposed
+     *   return html.div(doubled);
+     * };
+     * ```
+     *
      * @typeParam O - The type of the transformed value
      * @param fn - Function that transforms the signal's value to a new value
      * @param equals - Optional function to determine if two transformed values are equal (defaults to strict equality)
-     * @returns A new computed signal with the transformed value
+     * @returns A new computed signal with the transformed value (auto-registered with current scope)
      */
     readonly map: <O>(fn: (value: T) => O, equals?: (a: O, b: O) => boolean) => Computed<O>;
     /**
@@ -365,9 +386,28 @@ export declare class Computed<T> extends Signal<T> {
      */
     protected _isDirty: boolean;
     /**
-     * Represents a Signal object.
-     * @param _fn - The function that returns the value of the signal.
+     * Creates a new Computed signal.
+     *
+     * **Auto-Registration:** This constructor automatically registers the signal with the current
+     * disposal scope (if one exists). This ensures that computed signals created by methods like
+     * `.map()`, `.flatMap()`, `.filter()`, etc. are automatically tracked and disposed.
+     *
+     * When a computed signal is created within a renderable or `WithScope()`, it will be
+     * automatically disposed when the component unmounts or the scope is disposed.
+     *
+     * To create a computed signal that outlives the current scope, use `untracked()`:
+     * ```typescript
+     * const globalSignal = untracked(() => mySignal.map(x => x * 2));
+     * // Remember to dispose manually: globalSignal.dispose()
+     * ```
+     *
+     * @param _fn - The function that computes the value of the signal.
      * @param equals - The function used to compare two values of type T for equality.
+     *
+     * @see {@link computed} - Factory function for creating computed signals with explicit dependencies
+     * @see {@link Signal.map} - Creates a computed signal by transforming values
+     * @see {@link getCurrentScope} - Get the current disposal scope
+     * @see {@link untracked} - Create signals outside of scope tracking
      */
     constructor(_fn: () => T, equals: (a: T, b: T) => boolean);
     /**
@@ -390,6 +430,12 @@ export declare class Computed<T> extends Signal<T> {
     readonly get: () => T;
     /** {@inheritDoc Signal.value} */
     get value(): T;
+    /**
+     * Disposes the computed signal and cancels any pending recomputations.
+     * This override increments the schedule count to invalidate all pending
+     * microtasks before disposing the signal.
+     */
+    readonly dispose: () => void;
 }
 /**
  * Represents the data passed to a reducer effect.

package/std/value.d.ts

@@ -57,6 +57,14 @@ export declare const Value: {
      * @param value - The value or Signal instance to dispose of.
      */
     dispose: <T>(value: Value<T>) => void;
+    /**
+     * Returns a function that disposes of a value or a Signal.
+     * If the value is a Signal, it returns a function that disposes of the Signal.
+     * If the value is not a Signal, it returns a function that does nothing.
+     * @param value - The value or Signal instance to dispose of.
+     * @returns A function to dispose of the value or Signal.
+     */
+    disposeFn: <T>(value: Value<T>) => () => void;
     /**
      * Derives a Prop from a Signal.
      * If the value is a Signal, it returns a new Prop with the derived value.