@mmstack/primitives 19.5.2 → 19.6.0

package/README.md

@@ -117,6 +117,8 @@ Each level's shape is resolved from what's known: a value that is currently an o
 
 Top-level array support isn't exposed yet — use `indexArray` / `keyArray` for those.
 
+**Union leaves (perf opt-in).** `noUnionLeaves: true` promises no node ever flips between a leaf and a sub-store, so each node's leaf-ness is resolved once on first access and cached instead of staying reactive. Off by default — leave it off if a value can switch between a primitive and an object/array.
+
 ### `extendStore` (scoped overlay)
 
 `extendStore(store, seed)` (on any store kind) creates a **scoped overlay** — a child store that **shares** the parent's signals for inherited keys (the same `WritableSignal`: writes go through to the parent and parent changes flow down) while keeping the seed and any new keys in a **local layer** that never propagates upward. No diffing, no syncing — local keys simply aren't wired to the parent.
@@ -145,7 +147,7 @@ const scope = extendStore(app, draft); // writes to scope.title flow out to `dra
 
 A few release notes:
 
-- The local layer is a plain store (vivify off). Inherited paths vivify when the _parent_ was created with `vivify`; to autovivify local keys, seed with a vivify-enabled store — `extendStore(app, store(seed, { vivify: 'auto' }))`.
+- The scope inherits the parent's config (`vivify` / `noUnionLeaves`) and its injector-scoped proxy cache, so **both** inherited and local paths vivify when the parent was created with `vivify`. `extendStore` doesn't accept `vivify` / `noUnionLeaves` — they always come from the parent.
 - Reserved names — `asReadonlyStore` and the signal methods (`set` / `update` / `mutate` / `inline` / `asReadonly`) — shadow same-named data keys, as on any store.
 - `scope.asReadonlyStore()` returns a read-only **snapshot view** of the merge (reactive reads, no writes); it does not share sub-store identity.
 
@@ -173,7 +175,7 @@ The fork is a full store (`draft.store.user.name(...)`, `extendStore`, deep read
 - **`'coarse'`** — any base change resets the whole fork. Cheapest; correct when the base is held for the fork's lifetime (e.g. a transition). The default for a mutable base.
 - **a `ReconcileFn<T>`** — `(ancestor, mine, theirs) => merged`, for bring-your-own merge (array-by-id, Immer patches, CRDT-ish).
 
-> Pass the same `vivify` / `noUnionLeaves` the base was created with — fork config isn't inherited (it's closed over inside the base), so mismatched config gives the fork different write semantics.
+> The fork inherits the base's `vivify` / `noUnionLeaves` and its injector-scoped proxy cache automatically, so its write semantics match the base. Pass them explicitly only to override (advanced).
 
 ### `toWritable`
 
@@ -668,6 +670,13 @@ once the pointer travels past `activationThreshold`, so the same element stays
 clickable. Uses `setPointerCapture`, supports a delegated `handleSelector`, and
 cancels on Escape or via `.cancel()`.
 
+A delegated `handleSelector` reports which child actually started the drag via
+`drag().origin` (so one listener on a container can serve many handles), and
+`stopPropagation: true` lets an inner sensor claim the `pointerdown` over an
+outer one on the same tree (e.g. a nested sortable). Reads are throttled
+(`throttle`, default 16ms); `drag.unthrottled()` exposes the un-throttled view
+for logic that needs the exact release position.
+
 ```typescript
 import { sensor } from '@mmstack/primitives';
 
@@ -678,7 +687,7 @@ const position = computed(() => {
   const d = drag();
   return d.active ? { x: base.x + d.delta.x, y: base.y + d.delta.y } : base;
 });
-// drag().modifiers.shift → e.g. constrain axis · drag.cancel() → revert
+// drag().modifiers.shift → e.g. constrain axis · drag().origin → the handle · drag.cancel() → revert
 ```
 
 ### `signalFromEvent`

package/fesm2022/mmstack-primitives.mjs

@@ -2905,6 +2905,8 @@ const IDLE = {
     pointerId: null,
     modifiers: { shift: false, alt: false, ctrl: false, meta: false },
     button: -1,
+    pointerType: '',
+    origin: null,
 };
 function stateEqual(a, b) {
     return (a.active === b.active &&
@@ -2912,6 +2914,8 @@ function stateEqual(a, b) {
         a.current.x === b.current.x &&
         a.current.y === b.current.y &&
         a.button === b.button &&
+        a.pointerType === b.pointerType &&
+        a.origin === b.origin &&
         a.modifiers.shift === b.modifiers.shift &&
         a.modifiers.alt === b.modifiers.alt &&
         a.modifiers.ctrl === b.modifiers.ctrl &&
@@ -2945,7 +2949,7 @@ function createPointerDrag(opt) {
         return base;
     }
     const hostRef = inject((ElementRef), { optional: true });
-    const { target = hostRef?.nativeElement, coordinateSpace = 'client', activationThreshold = 3, throttle = 16, handleSelector, buttons = [0], debugName = 'pointerDrag', } = opt ?? {};
+    const { target = hostRef?.nativeElement, coordinateSpace = 'client', activationThreshold = 3, throttle = 16, handleSelector, buttons = [0], stopPropagation = false, debugName = 'pointerDrag', } = opt ?? {};
     const resolve = (t) => {
         if (!t)
             return null;
@@ -2966,9 +2970,12 @@ function createPointerDrag(opt) {
         equal: stateEqual,
         debugName,
     });
+    const threshold2 = activationThreshold * activationThreshold;
     let startPoint = { x: 0, y: 0 };
     let activePointerId = null;
     let activeButton = -1;
+    let activePointerType = '';
+    let activeOrigin = null;
     let activated = false;
     let gesture = null;
     const coord = (e) => coordinateSpace === 'page'
@@ -2985,6 +2992,8 @@ function createPointerDrag(opt) {
         gesture = null;
         activePointerId = null;
         activeButton = -1;
+        activePointerType = '';
+        activeOrigin = null;
         activated = false;
         state.set(IDLE);
         state.flush(); // terminal transition: reflect IDLE now, not on the trailing edge
@@ -2994,8 +3003,8 @@ function createPointerDrag(opt) {
             return;
         const current = coord(e);
         const delta = { x: current.x - startPoint.x, y: current.y - startPoint.y };
-        if (!activated && Math.hypot(delta.x, delta.y) >= activationThreshold) {
-            activated = true;
+        if (!activated && delta.x * delta.x + delta.y * delta.y >= threshold2) {
+            activated = true; // squared compare — no sqrt on the pre-activation path
         }
         state.set({
             active: activated,
@@ -3005,6 +3014,8 @@ function createPointerDrag(opt) {
             pointerId: activePointerId,
             modifiers: mods(e),
             button: activeButton, // pointermove button is -1; keep the down-button
+            pointerType: activePointerType,
+            origin: activeOrigin,
         });
     };
     const onUp = (e) => {
@@ -3024,11 +3035,17 @@ function createPointerDrag(opt) {
             return;
         if (!buttons.includes(e.button))
             return;
-        if (handleSelector && !e.target?.closest?.(handleSelector)) {
-            return;
-        }
+        const matched = handleSelector
+            ? e.target?.closest?.(handleSelector)
+            : el;
+        if (!matched)
+            return; // handleSelector set but pointerdown landed outside a handle
+        if (stopPropagation)
+            e.stopPropagation(); // claim it: an outer sensor won't also start
         activePointerId = e.pointerId;
         activeButton = e.button;
+        activePointerType = e.pointerType;
+        activeOrigin = matched;
         activated = false;
         startPoint = coord(e);
         try {
@@ -3054,6 +3071,8 @@ function createPointerDrag(opt) {
             pointerId: e.pointerId,
             modifiers: mods(e),
             button: e.button,
+            pointerType: activePointerType,
+            origin: activeOrigin,
         });
     };
     const attach = (el) => {
@@ -3432,17 +3451,14 @@ function signalFromEvent(target, eventName, initial, projectOrOpt, maybeOpt) {
 
 const IS_STORE = Symbol('@mmstack/primitives::store/IS_STORE');
 const SCOPE_PARENT = Symbol('@mmstack/primitives::store/SCOPE_PARENT');
+const STORE_SHARED_GLOBALS = Symbol('@mmstack/primitives::store/STORE_SHARED_GLOBALS');
+const STORE_SHARED_OPTIONS = Symbol('@mmstack/primitives::store/STORE_SHARED_OPTIONS');
 /**
  * @internal Brand carrying a store's writability ('mutable' | 'writable' | 'readonly'), stamped
  * on every store proxy. Read by `extendStore` instead of re-deriving via `isWritableSignal`,
  * which would mis-classify a readonly scoped store (its backing `toWritable` still has a `set`).
  */
 const STORE_KIND = Symbol('@mmstack/primitives::store/STORE_KIND');
-/**
- * @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.
- */
-const STORE_INJECTOR = Symbol('@mmstack/primitives::store/STORE_INJECTOR');
 const SIGNAL_FN_PROP = new Set([
     'set',
     'update',
@@ -3450,21 +3466,20 @@ const SIGNAL_FN_PROP = new Set([
     'inline',
     'asReadonly',
 ]);
-/**
- * @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`.
- */
-const PROXY_CACHE = new WeakMap();
-/**
- * @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.
- */
-const PROXY_CLEANUP = new FinalizationRegistry(({ target, prop }) => {
-    const storeCache = PROXY_CACHE.get(target);
-    if (storeCache)
-        storeCache.delete(prop);
+const PROXY_CACHE_TOKEN = new InjectionToken('@mmstack/primitives:store-proxy-cache', {
+    providedIn: 'root',
+    factory: () => new WeakMap(),
+});
+const PROXY_CLEANUP_TOKEN = new InjectionToken('@mmstack/primitives:store-proxy-cleanup', {
+    providedIn: 'root',
+    factory: () => {
+        const cache = inject(PROXY_CACHE_TOKEN);
+        return new FinalizationRegistry(({ target, prop }) => {
+            const store = cache.get(target);
+            if (store)
+                store.delete(prop);
+        });
+    },
 });
 /**
  * @internal
@@ -3658,11 +3673,11 @@ function isLeaf(value) {
  * holding it via a `WeakRef` and registering it for finalizer-driven cache pruning. The cache
  * is keyed per backing signal, so child identity is stable across repeat reads.
  */
-function getCachedChild(target, prop, build) {
-    let storeCache = PROXY_CACHE.get(target);
+function getCachedChild(target, prop, build, cache, cleanupRegistry) {
+    let storeCache = cache.get(target);
     if (!storeCache) {
         storeCache = new Map();
-        PROXY_CACHE.set(target, storeCache);
+        cache.set(target, storeCache);
     }
     const cachedRef = storeCache.get(prop);
     if (cachedRef) {
@@ -3670,12 +3685,12 @@ function getCachedChild(target, prop, build) {
         if (cached)
             return cached;
         storeCache.delete(prop);
-        PROXY_CLEANUP.unregister(cachedRef);
+        cleanupRegistry.unregister(cachedRef);
     }
     const proxy = build();
     const ref = new WeakRef(proxy);
     storeCache.set(prop, ref);
-    PROXY_CLEANUP.register(proxy, { target, prop }, ref);
+    cleanupRegistry.register(proxy, { target, prop }, ref);
     return proxy;
 }
 /**
@@ -3684,11 +3699,11 @@ function getCachedChild(target, prop, build) {
  * `onChange` path. Shared verbatim by the array and object proxies — the only place a child node
  * is constructed.
  */
-function buildChildNode(target, prop, isMutableSource, injector, vivify, noUnionLeaves) {
+function buildChildNode(target, prop, isMutableSource, options) {
     const value = untracked(target);
     const valueIsRecord = isRecord(value);
     const valueIsArray = Array.isArray(value);
-    const nodeVivify = resolveVivify(value, vivify);
+    const nodeVivify = resolveVivify(value, options.vivify);
     const vivifyFn = createVivify(nodeVivify);
     const equalFn = (valueIsRecord || valueIsArray) &&
         isMutableSource &&
@@ -3703,9 +3718,9 @@ function buildChildNode(target, prop, isMutableSource, injector, vivify, noUnion
             equal: equalFn,
         });
     const childSample = untracked(computation);
-    const childVivify = resolveVivify(childSample, vivify);
-    const proxy = toStore(computation, injector, childVivify, noUnionLeaves);
-    markAsLeaf(proxy, computation, childVivify !== false, noUnionLeaves);
+    const childVivify = resolveVivify(childSample, options.vivify);
+    const proxy = toStore(computation, options);
+    markAsLeaf(proxy, computation, childVivify !== false, options.noUnionLeaves);
     return proxy;
 }
 /**
@@ -3723,7 +3738,7 @@ function buildChildNode(target, prop, isMutableSource, injector, vivify, noUnion
  * const state = store({ user: { name: 'John' } });
  * const nameSignal = state.user.name; // WritableSignal<string>
  */
-function toStore(source, injector, vivify = false, noUnionLeaves = false) {
+function toStore(source, { injector, vivify = false, noUnionLeaves = false, ...rest } = {}) {
     if (isStore(source))
         return source;
     if (!injector)
@@ -3743,6 +3758,16 @@ function toStore(source, injector, vivify = false, noUnionLeaves = false) {
             return 'record';
         return 'primitive';
     });
+    const STORE_OPTIONS = {
+        injector,
+        vivify,
+        noUnionLeaves,
+        [STORE_SHARED_GLOBALS]: {
+            cache: rest[STORE_SHARED_GLOBALS]?.cache ?? injector.get(PROXY_CACHE_TOKEN),
+            registry: rest[STORE_SHARED_GLOBALS]?.registry ??
+                injector.get(PROXY_CLEANUP_TOKEN),
+        },
+    };
     // built lazily so non-array nodes never allocate it
     let length;
     const arrayLength = () => (length ??= computed(() => {
@@ -3796,21 +3821,23 @@ function toStore(source, injector, vivify = false, noUnionLeaves = false) {
             return { enumerable: true, configurable: true };
         },
         get(target, prop, receiver) {
-            if (prop === IS_STORE)
-                return true;
-            if (prop === STORE_KIND)
-                return isMutableSource
-                    ? 'mutable'
-                    : isWritableSource
-                        ? 'writable'
-                        : 'readonly';
-            if (prop === STORE_INJECTOR)
-                return injector;
+            if (typeof prop === 'symbol') {
+                if (prop === IS_STORE)
+                    return true;
+                if (prop === STORE_KIND)
+                    return isMutableSource
+                        ? 'mutable'
+                        : isWritableSource
+                            ? 'writable'
+                            : 'readonly';
+                if (prop === STORE_SHARED_OPTIONS)
+                    return STORE_OPTIONS;
+            }
             if (prop === 'asReadonlyStore')
                 return () => {
                     if (!isWritableSource)
                         return s;
-                    return untracked(() => toStore(source.asReadonly(), injector, vivify, noUnionLeaves));
+                    return untracked(() => toStore(source.asReadonly(), { injector, vivify, noUnionLeaves }));
                 };
             const k = untracked(kind);
             if (prop === 'extend' && k !== 'array')
@@ -3818,7 +3845,7 @@ function toStore(source, injector, vivify = false, noUnionLeaves = false) {
                     ? 'mutable'
                     : isWritableSource
                         ? 'writable'
-                        : 'readonly', injector);
+                        : 'readonly', STORE_OPTIONS);
             if (k === 'array') {
                 if (prop === 'length')
                     return arrayLength();
@@ -3835,7 +3862,7 @@ function toStore(source, injector, vivify = false, noUnionLeaves = false) {
                 return target[prop];
             if (k === 'array' && !isIndexProp(prop))
                 return Reflect.get(target, prop, receiver);
-            return getCachedChild(target, prop, () => buildChildNode(target, k === 'array' ? +prop : prop, isMutableSource, injector, vivify, noUnionLeaves));
+            return getCachedChild(target, prop, () => buildChildNode(target, k === 'array' ? +prop : prop, isMutableSource, STORE_OPTIONS), STORE_OPTIONS[STORE_SHARED_GLOBALS].cache, STORE_OPTIONS[STORE_SHARED_GLOBALS].registry);
         },
     });
     return s;
@@ -3849,14 +3876,14 @@ function toStore(source, injector, vivify = false, noUnionLeaves = false) {
  * identity + two-way), while local keys never propagate upward. A merged `computed` is derived
  * only for whole-object reads / `has` / iteration — never for routing.
  */
-function scopedStore(parent, seed, kind, injector) {
+function scopedStore(parent, seed, kind, options) {
     const local = isSignal(seed)
-        ? toStore(seed, injector)
+        ? toStore(seed, options)
         : kind === 'mutable'
-            ? mutableStore(seed, { injector })
+            ? mutableStore(seed, options)
             : kind === 'readonly'
-                ? store(seed, { injector }).asReadonlyStore()
-                : store(seed, { injector });
+                ? store(seed, options).asReadonlyStore()
+                : store(seed, options);
     const localValue = () => untracked(local);
     const parentValue = () => untracked(parent);
     const view = computed(() => ({
@@ -3887,18 +3914,20 @@ function scopedStore(parent, seed, kind, injector) {
     }
     const scope = new Proxy(base, {
         get(target, prop) {
-            if (prop === IS_STORE)
-                return true;
-            if (prop === STORE_KIND)
-                return kind;
-            if (prop === STORE_INJECTOR)
-                return injector;
-            if (prop === SCOPE_PARENT)
-                return parent;
+            if (typeof prop === 'symbol') {
+                if (prop === IS_STORE)
+                    return true;
+                if (prop === STORE_KIND)
+                    return kind;
+                if (prop === SCOPE_PARENT)
+                    return parent;
+                if (prop === STORE_SHARED_OPTIONS)
+                    return options;
+            }
             if (prop === 'extend')
-                return (childSeed) => scopedStore(scope, childSeed, kind, injector);
+                return (childSeed) => scopedStore(scope, childSeed, kind, options);
             if (prop === 'asReadonlyStore')
-                return () => toStore(computed(() => ({ ...parent(), ...local() })), injector);
+                return () => toStore(computed(() => ({ ...parent(), ...local() })), options);
             if (typeof prop === 'symbol' || SIGNAL_FN_PROP.has(prop))
                 return target[prop];
             // Route by consulting both signals: local first, then parent, else local (new → local).
@@ -3944,22 +3973,34 @@ function storeKind(s) {
  * scoped.count.set(1); // writes through to base
  * scoped.label.set('x'); // stays local
  */
-function extendStore(store, source, injector) {
-    return scopedStore(store, source, storeKind(store), injector ?? store[STORE_INJECTOR] ?? inject(Injector));
+function extendStore(store, source, options) {
+    const opt = {
+        ...store[STORE_SHARED_OPTIONS],
+        ...options,
+    };
+    return scopedStore(store, source, storeKind(store), opt);
 }
 /**
  * Creates a WritableSignalStore from a value.
  * @see {@link toStore}
  */
 function store(value, opt) {
-    return toStore(signal(value, opt), opt?.injector, opt?.vivify ?? false, opt?.noUnionLeaves ?? false);
+    return toStore(signal(value, opt), {
+        vivify: false,
+        noUnionLeaves: false,
+        ...opt,
+    });
 }
 /**
  * Creates a MutableSignalStore from a value.
  * @see {@link toStore}
  */
 function mutableStore(value, opt) {
-    return toStore(mutable(value, opt), opt?.injector, opt?.vivify ?? false, opt?.noUnionLeaves ?? false);
+    return toStore(mutable(value, opt), {
+        vivify: false,
+        noUnionLeaves: false,
+        ...opt,
+    });
 }
 
 function isPlainRecord(value) {
@@ -4023,7 +4064,13 @@ function forkStore(base, opt) {
         source: () => base(),
         computation: (theirs, prev) => prev === undefined ? theirs : merge(prev.source, prev.value, theirs),
     });
-    const store = toStore(staged, opt?.injector, opt?.vivify, opt?.noUnionLeaves);
+    // Inherit the base's shared options (injector, vivify, noUnionLeaves + the
+    // proxy cache/registry), same as extendStore — a fork should vivify like its
+    // base and share its injector-scoped cache. `opt` overrides (advanced use).
+    const store = toStore(staged, {
+        ...base[STORE_SHARED_OPTIONS],
+        ...opt,
+    });
     return {
         store,
         commit: () => base.set(untracked(staged)),