@mmstack/primitives 19.5.2 → 19.6.0

package/lib/sensors/pointer-drag.d.ts

@@ -25,6 +25,14 @@ export 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;
 };
 export type PointerDragOptions = SensorRunOptions & {
     /**
@@ -37,12 +45,24 @@ export 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()`. */
 export type PointerDragSignal = Signal<PointerDragState> & {

package/lib/store/fork-store.d.ts

@@ -1,6 +1,5 @@
-import { type Injector } from '@angular/core';
-import { type Vivify } from '../util';
-import { type WritableSignalStore } from './store';
+import { type toStoreOptions } from './store';
+import type { WritableSignalStore } from './types';
 /**
  * A 3-way merge of a forked value against a changed base: given the common `ancestor` (the base
  * value the fork last diverged from), `mine` (the fork's current value), and `theirs` (the base
@@ -61,19 +60,10 @@ export type Fork<T> = {
  * leaves compare by value, so equal primitives are correctly seen as unchanged.
  */
 export declare function merge3<T>(ancestor: T, mine: T, theirs: T): T;
-export 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)
+ */
+export 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>;
+};
+export declare function forkStore<T extends Record<string, any>>(base: WritableSignalStore<T>, opt?: ForkStoreOptions<T>): Fork<T>;

package/lib/store/internals.d.ts

@@ -1,7 +1,9 @@
-import { type Signal } from '@angular/core';
+import { InjectionToken, type Signal } from '@angular/core';
 import { type SignalStore } from './types';
 export declare const IS_STORE: unique symbol;
 export declare const SCOPE_PARENT: unique symbol;
+export declare const STORE_SHARED_GLOBALS: unique symbol;
+export declare const STORE_SHARED_OPTIONS: unique symbol;
 /**
  * @internal Brand carrying a store's writability ('mutable' | 'writable' | 'readonly'), stamped
  * on every store proxy. Read by `extendStore` instead of re-deriving via `isWritableSignal`,
@@ -9,27 +11,22 @@ export declare const SCOPE_PARENT: unique symbol;
  */
 export declare const STORE_KIND: unique symbol;
 export type StoreKind = 'mutable' | 'writable' | 'readonly';
-/**
- * @internal Brand exposing the injector a store was built with, so `extendStore` inherits it the
- * same way `store.extend(...)` does (via closure) — no injection context needed at the call site.
- */
-export declare const STORE_INJECTOR: unique symbol;
 export declare const SIGNAL_FN_PROP: Set<string>;
 /**
  * @internal
- * Test-only handle on the proxy cache (deliberately NOT re-exported from the public barrel).
  * Maps a store's backing signal to its lazily-built child proxies, each held via a `WeakRef`.
  */
-export declare const PROXY_CACHE: WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
+export type ProxyCache = WeakMap<object, Map<PropertyKey, WeakRef<Signal<any>>>>;
 /**
  * @internal
- * Test-only handle on the finalization registry (deliberately NOT re-exported from the public
- * barrel). Prunes a cache entry once its proxy is reclaimed by the GC.
+ * Prunes a cache entry once its proxy is reclaimed by the GC.
  */
-export declare const PROXY_CLEANUP: FinalizationRegistry<{
+export type ProxyCleanupRegistry = FinalizationRegistry<{
     target: object;
     prop: PropertyKey;
 }>;
+export declare const PROXY_CACHE_TOKEN: InjectionToken<ProxyCache>;
+export declare const PROXY_CLEANUP_TOKEN: InjectionToken<ProxyCleanupRegistry>;
 /**
  * @internal
  * Validates whether a value is a Signal Store.

package/lib/store/public_api.d.ts

@@ -1,2 +1,6 @@
 export * from './fork-store';
-export { extendStore, isLeaf, isOpaque, isStore, mutableStore, opaque, store, toStore, type MutableSignalStore, type Opaque, type SignalStore, type WritableSignalStore, } from './store';
+export { isStore } from './internals';
+export { isLeaf } from './leaf';
+export { isOpaque, opaque, type Opaque } from './opaque';
+export { extendStore, mutableStore, store, toStore, type ExtendStoreOptions, type StoreOptions, type toStoreOptions, } from './store';
+export type { MutableSignalStore, SignalStore, WritableSignalStore, } from './types';

package/lib/store/store.d.ts

@@ -1,17 +1,46 @@
 import { Injector, type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
 import { type MutableSignal } from '../mutable';
 import { type Vivify } from '../util';
+import { STORE_SHARED_GLOBALS, type ProxyCache, type ProxyCleanupRegistry } from './internals';
 import { type AnyRecord, type MutableSignalStore, type SignalStore, type Simplify, type WritableSignalStore } from './types';
-export { isStore, PROXY_CACHE, PROXY_CLEANUP } from './internals';
-export { isLeaf, LEAF } from './leaf';
-export { isOpaque, OPAQUE, opaque, type Opaque, type UnwrapOpaque, } from './opaque';
-export { type MutableSignalStore, type SignalStore, type WritableSignalStore, } from './types';
-export declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): MutableSignalStore<T>;
-export declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): WritableSignalStore<T>;
-export declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector, vivify?: Vivify, noUnionLeaves?: boolean): SignalStore<T>;
-export 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>>;
-export 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>>;
-export 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>>;
+export 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;
+    };
+};
+export type StoreOptions<T> = CreateSignalOptions<T> & toStoreOptions;
+export declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, options?: toStoreOptions): MutableSignalStore<T>;
+export declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, options?: toStoreOptions): WritableSignalStore<T>;
+export declare function toStore<T extends AnyRecord>(source: Signal<T>, options?: toStoreOptions): SignalStore<T>;
+export type ExtendStoreOptions = Omit<toStoreOptions, 'vivify' | 'noUnionLeaves' | typeof STORE_SHARED_GLOBALS>;
+export 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>>;
+export 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>>;
+export 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}

package/package.json

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