@mmstack/primitives 21.2.2 → 21.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "21.2.2",
+  "version": "21.4.0",
   "keywords": [
     "angular",
     "signals",

package/types/mmstack-primitives.d.ts

@@ -189,8 +189,9 @@ declare function providePaused(source: Signal<boolean>): Provider;
 declare function holdUntilReady<T>(target: Signal<T>, ready: () => boolean): Signal<T>;
 
 /**
- * Handle for an in-progress transition: a `pending` signal (true while the transition's
- * resources are in flight) and a `done` promise that resolves once they all settle.
+ * Handle for an in-progress transition: a `pending` signal (true while the transition's OWN
+ * resources are in flight — loads already in flight when it started are not attributed) and a
+ * `done` promise that resolves once they all settle.
  */
 type TransitionRef = {
     readonly pending: Signal<boolean>;
@@ -292,6 +293,15 @@ declare function createForwardingScope(): ForwardingTransitionScope;
 declare function provideForwardingTransitionScope(): Provider;
 /** Read the transition scope reachable from `injector`, or null if none is provided there. */
 declare function getTransitionScope(injector: Injector): TransitionScope | null;
+/**
+ * @internal Transaction-attributed pending for `startTransition`/`startTransaction`: like
+ * `scope.pending`, but loads already in flight when the tracker is created are NOT attributed —
+ * a pre-existing background load can neither settle the transaction early nor block its settle
+ * forever. A pre-existing flight is excluded only until it first settles; a later re-trigger of
+ * the same resource (e.g. the transaction's write changed its request) counts as the
+ * transaction's own work.
+ */
+declare function createAttributedPending(scope: TransitionScope): Signal<boolean>;
 /**
  * Returns a register function bound to the nearest transition scope: it adds a resource
  * to the scope and removes it when the caller's injection context is destroyed. Pass any
@@ -342,8 +352,7 @@ declare class SuspenseBoundary extends SuspenseBoundaryBase {
 }
 /**
  * Unscoped suspense boundary — **reads the ambient scope** instead of providing one. For cases where
- * the resources to coordinate are registered *above* the boundary (e.g. an app-builder page whose
- * manifests/connectors register at a higher injector), so the boundary observes that outer scope
+ * the resources to coordinate are registered *above* the boundary so the boundary observes that outer scope
  * rather than opening a fresh one. Pair with a `provideTransitionScope()` (or another boundary) in an
  * ancestor.
  */
@@ -368,7 +377,8 @@ type Transaction = {
 declare function createTransaction(): Transaction;
 /** The transaction in effect right now, or `null`. Stateful actions consult this to record undo. */
 declare function activeTransaction(): Transaction | null;
-/** Handle for an in-progress transaction (Tier 3): the transition `pending`/`done`, plus `abort`. */
+/** Handle for an in-progress transaction (Tier 3): the transaction's own `pending`/`done`
+ * (loads already in flight at start are not attributed to it), plus `abort`. */
 type TransactionRef = {
     readonly pending: Signal<boolean>;
     readonly done: Promise<void>;
@@ -1937,6 +1947,21 @@ type PointerDragState = {
     modifiers: PointerModifiers;
     /** Mouse button that started the gesture (`-1` when idle). */
     button: number;
+    /** The pointing device: `'mouse' | 'touch' | 'pen'` (`''` when idle). */
+    pointerType: string;
+    /**
+     * The element the gesture started on: the `handleSelector` match when one is
+     * set (so a single delegated listener can tell which child started the drag),
+     * otherwise the listener's element. `null` when idle.
+     */
+    origin: HTMLElement | null;
+    /**
+     * Whether the LAST gesture ended by being aborted (`pointercancel` /
+     * `lostpointercapture` / Escape / `cancel()`) rather than a normal `pointerup`.
+     * Only meaningful on the idle transition — consumers ending a drag branch on it
+     * to distinguish "drop here" from "abort". Sticky until the next `pointerdown`.
+     */
+    cancelled: boolean;
 };
 type PointerDragOptions = SensorRunOptions & {
     /**
@@ -1949,12 +1974,24 @@ type PointerDragOptions = SensorRunOptions & {
     coordinateSpace?: 'client' | 'page';
     /** Pixels the pointer must travel before `active` flips true. @default 3 */
     activationThreshold?: number;
-    /** Throttle (ms) for `current`/`delta` updates. @default 16 */
+    /**
+     * Throttle (ms) for `current`/`delta` updates. @default 16
+     *
+     * Note: a final sub-throttle move right before `pointerup` may not surface on
+     * the throttled view (it coalesces into the terminal idle). Logic that must act
+     * on the *exact* release position should read {@link PointerDragSignal.unthrottled}.
+     */
     throttle?: number;
     /** Only start when the pointerdown target matches this selector (delegated handles). */
     handleSelector?: string;
     /** Mouse buttons that may start a gesture. @default [0] (primary) */
     buttons?: number[];
+    /**
+     * Stop the `pointerdown` from propagating once this sensor claims it. Lets an
+     * inner sensor win over an outer one on the same element tree (e.g. a nested
+     * sortable inside another). @default false
+     */
+    stopPropagation?: boolean;
 };
 /** A gesture signal with an `unthrottled` view and an imperative `cancel()`. */
 type PointerDragSignal = Signal<PointerDragState> & {
@@ -2592,18 +2629,64 @@ type MutableSignalStore<T> = MutableSignal<UnwrapOpaque<T>> & {
     readonly [LEAF]: () => boolean;
 } : NonNullable<T> extends any[] ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
 
+declare const STORE_SHARED_GLOBALS: unique symbol;
+/**
+ * @internal
+ * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
+ */
+type ProxyCache = WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
+/**
+ * @internal
+ * Prunes a cache entry once its proxy is reclaimed by the GC.
+ */
+type ProxyCleanupRegistry = FinalizationRegistry<{
+    target: object;
+    prop: PropertyKey;
+}>;
 /**
  * @internal
  * Validates whether a value is a Signal Store.
  */
 declare function isStore<T>(value: unknown): value is SignalStore<T>;
 
-declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): MutableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): WritableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): SignalStore<T>;
-declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: MutableSignalStore<T>, source: MutableSignal<L> | L, injector?: Injector): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
-declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: WritableSignalStore<T>, source: WritableSignal<L> | L, injector?: Injector): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
-declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: SignalStore<T>, source: Signal<L> | L, injector?: Injector): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+type toStoreOptions = {
+    injector?: Injector;
+    /**
+     * Opt-in autovivification: when writing through a `null`/`undefined` path, create the
+     * missing intermediate containers instead of dropping the write. Off by default.
+     *
+     * Levels whose current value is a known object/array re-vivify as that same shape — the
+     * knowledge is captured when the path is first accessed and cached, so it holds even after
+     * the value is later nulled. This option governs only genuinely-unknown (currently
+     * `null`/`undefined`) levels: `'auto'` (an array for index keys, an object otherwise), an
+     * explicit `'object'`/`'array'`, or a `() => container` factory. See {@link Vivify}.
+     */
+    vivify?: Vivify;
+    /**
+     * Performance opt-in: promise that no node ever switches between leaf and substore (i.e. no
+     * unions mixing a primitive with an object/array). With this on, each node's leaf-ness is
+     * resolved once on the first {@link isLeaf} probe and cached as a constant, skipping the
+     * reactive `computed`. If a node's shape does change anyway, {@link isLeaf} keeps its first
+     * answer. Off by default.
+     */
+    noUnionLeaves?: boolean;
+    /**
+     * @internal
+     * Shared cleanup singletons, they get injected/passed automatically
+     */
+    [STORE_SHARED_GLOBALS]?: {
+        cache: ProxyCache;
+        registry: ProxyCleanupRegistry;
+    };
+};
+type StoreOptions<T> = CreateSignalOptions<T> & toStoreOptions;
+declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, options?: toStoreOptions): MutableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, options?: toStoreOptions): WritableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: Signal<T>, options?: toStoreOptions): SignalStore<T>;
+type ExtendStoreOptions = Omit<toStoreOptions, 'vivify' | 'noUnionLeaves' | typeof STORE_SHARED_GLOBALS>;
+declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: MutableSignalStore<T>, source: MutableSignal<L> | L, options?: ExtendStoreOptions): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: WritableSignalStore<T>, source: WritableSignal<L> | L, options?: ExtendStoreOptions): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+declare function extendStore<T extends AnyRecord, L extends AnyRecord>(store: SignalStore<T>, source: Signal<L> | L, options?: ExtendStoreOptions): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
@@ -2717,22 +2800,13 @@ type Fork<T> = {
  * leaves compare by value, so equal primitives are correctly seen as unchanged.
  */
 declare function merge3<T>(ancestor: T, mine: T, theirs: T): T;
-declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: {
+/**
+ * ForkStoreOptions, vivify/noUnionLeaves should remain the same & are automatically inherited, override carefully (advanced usecases)
+ */
+type ForkStoreOptions<T> = toStoreOptions & {
     strategy?: ForkStrategy<T>;
-    injector?: Injector;
-    /**
-     * Store config for the FORK's store — NOT inherited from `base` (it's closed over inside
-     * the base's `toStore` and can't be read back). If the base was created with these, pass
-     * the same values or the fork's write semantics will differ:
-     *  - `vivify`: without it, a write through a `null`/`undefined` path is silently dropped on
-     *    the fork even though the base would have created the container. Match the base.
-     *  - `noUnionLeaves`: a perf promise; off just means the slower reactive leaf-probe. NOTE it
-     *    is a whole-store guarantee — a fork that flips a node's type (leaf↔substore) violates it,
-     *    and on `commit` the base receives the flipped value with stale cached leaf-ness.
-     */
-    vivify?: Vivify;
-    noUnionLeaves?: boolean;
-}): Fork<T>;
+};
+declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: ForkStoreOptions<T>): Fork<T>;
 
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
@@ -3192,5 +3266,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(sourceOrValue: WritableSignal<T> | T, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { MmActivity, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
-export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, Fork, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ReconcileFn, RegisterOptions, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore };
+export { MmActivity, PAUSABLE_OPTIONS, SuspenseBoundary, SuspenseBoundaryBase, UnscopedSuspenseBoundary, activeTransaction, batteryStatus, chunked, clipboard, combineWith, createAttributedPending, createForwardingScope, createTransaction, createTransitionScope, debounce, debounced, derived, distinct, elementSize, elementVisibility, extendStore, filter, filterWith, focusWithin, forkStore, geolocation, getTransitionScope, holdUntilReady, idle, indexArray, injectPaused, injectRegisterResource, injectStartTransaction, injectStartTransition, injectTransitionScope, isDerivation, isLeaf, isMutable, isOpaque, isStore, keepPrevious, keyArray, map, mapArray, mapObject, mediaQuery, merge3, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, opaque, orientation, pageVisibility, pairwise, pausableComputed, pausableEffect, pausableSignal, pipeable, piped, pointerDrag, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, provideForwardingTransitionScope, providePausableOptions, providePaused, provideTransitionScope, registerResource, resolvePause, scan, scrollPosition, select, sensor, sensors, signalFromEvent, startWith, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export type { BatteryStatus, ClipboardSignal, Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, ExtendStoreOptions, Fork, ForkStoreOptions, ForkStrategy, ForwardingTransitionScope, Frame, GeolocationOptions, GeolocationSignal, IdleOptions, IdleSignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, Opaque, PausableOptions, PauseOption, PipeableSignal, PointerDragOptions, PointerDragSignal, PointerDragState, PointerModifiers, PointerPoint, ReconcileFn, RegisterOptions, ScreenOrientation, ScreenOrientationState, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SensorRunOptions, SignalFromEventOptions, SignalStore, SignalWithHistory, StoreOptions, StoredSignal, SuspendType, ThrottledSignal, Transaction, TransactionRef, TransitionRef, TransitionScope, UntilOptions, Vivify, WindowSize, WindowSizeOptions, WindowSizeSignal, WithVivify, WritableSignalStore, toStoreOptions };