@mmstack/primitives 19.2.3 → 20.0.0

package/lib/with-history.d.ts

@@ -1,94 +0,0 @@
-import { type CreateSignalOptions, type Signal, type ValueEqualityFn, type WritableSignal } from '@angular/core';
-/**
- * A WritableSignal enhanced with undo/redo capabilities and history tracking.
- *
- * @template T The type of value held by the signal.
- */
-export type SignalWithHistory<T> = WritableSignal<T> & {
-    /** A read-only signal of the undo history stack. The oldest changes are at the start of the array. */
-    history: Signal<T[]>;
-    /** Reverts the signal to its most recent previous state in the history. */
-    undo: () => void;
-    /** Re-applies the last state that was undone. */
-    redo: () => void;
-    /** A signal that is `true` if there are states in the redo stack. */
-    canRedo: Signal<boolean>;
-    /** A signal that is `true` if there are states in the undo history. */
-    canUndo: Signal<boolean>;
-    /** Clears both the undo and redo history stacks. */
-    clear: () => void;
-    /** A signal that is `true` if there is any history that can be cleared. */
-    canClear: Signal<boolean>;
-};
-/**
- * Options for creating a signal with history tracking.
- *
- * @template T The type of value held by the signal.
- */
-export type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
-    /**
-     * Optional custom equality function to determine if a value has changed before
-     * adding it to history. Defaults to the source signal's equality function or `Object.is`.
-     */
-    equal?: ValueEqualityFn<T>;
-    /**
-     * The maximum number of undo states to keep in the history.
-     * @default Infinity
-     */
-    maxSize?: number;
-    /**
-     * The strategy for trimming the history when `maxSize` is reached.
-     * - `shift`: Removes the single oldest entry from the history.
-     * - `halve`: Removes the oldest half of the history stack.
-     * @default 'halve'
-     */
-    cleanupStrategy?: 'shift' | 'halve';
-};
-/**
- * Enhances an existing `WritableSignal` by adding a complete undo/redo history
- * stack and an API to control it.
- *
- * @template T The type of value held by the signal.
- * @param source The source `WritableSignal` to add history tracking to.
- * @param options Optional configuration for the history behavior.
- * @returns A `SignalWithHistory<T>` instance, augmenting the source signal with history APIs.
- *
- * @remarks
- * - Any new `.set()` or `.update()` call on the signal will clear the entire redo stack.
- * - The primitive attempts to automatically use the source signal's own `equal` function,
- * but this relies on an internal Angular API. For maximum stability across Angular
- * versions, it is recommended to provide an explicit `equal` function in the options.
- *
- * @example
- * ```ts
- * import { signal } from '@angular/core';
- * import { withHistory } from '@mmstack/primitives';
- *
- * const name = withHistory(signal('John'), { maxSize: 5 });
- *
- * console.log('Initial value:', name()); // "John"
- *
- * name.set('John Doe');
- * name.set('Jane Doe');
- *
- * console.log('Current value:', name()); // "Jane Doe"
- * console.log('History:', name.history()); // ["John", "John Doe"]
- * console.log('Can undo:', name.canUndo()); // true
- * console.log('Can redo:', name.canRedo()); // false
- *
- * name.undo();
- * console.log('After undo:', name()); // "John Doe"
- * console.log('Can redo:', name.canRedo()); // true
- *
- * name.redo();
- * console.log('After redo:', name()); // "Jane Doe"
- *
- * // A new change will clear the redo history
- * name.set('Janine Doe');
- * console.log('Can redo:', name.canRedo()); // false
- *
- * name.clear();
- * console.log('Can undo:', name.canUndo()); // false
- * ```
- */
-export declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;