@mmstack/primitives 22.10.4 → 22.11.1

package/README.md

@@ -369,8 +369,11 @@ The foundation of stale-while-revalidate. Wraps a signal so it **holds its last
 import { keepPrevious } from '@mmstack/primitives';
 
 const held = keepPrevious(resource.value); // drops to undefined mid-reload → keeps last value
+const rows = keepPrevious(resource.value, { fallback: [] }); // [] only until the first value lands
 ```
 
+`fallback` is yielded only while nothing has ever been defined; after the first defined value the previous value covers every gap, never the fallback. Like any linked signal the hold is lazy: it carries a value it has computed with, so place it over the value your readers read — reading is what feeds it. `@mmstack/resource` does exactly that for its `keepPrevious` option.
+
 If the source is writable, `set` / `update` / `asReadonly` (and `mutate` / `inline` / `from` for mutable / derived sources) are forwarded through, so it stays a drop-in replacement. `@mmstack/resource` uses it under the hood for its `keepPrevious` option.
 
 ### Keep-alive — `MmActivity` / `injectPaused` / `providePaused`

package/fesm2022/mmstack-primitives.mjs

@@ -218,10 +218,10 @@ class MmActivity {
         else
             this.view.detach();
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmActivity, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: MmActivity, isStandalone: true, selector: "[mmActivity]", inputs: { visible: { classPropertyName: "visible", publicName: "mmActivity", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MmActivity, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.4", type: MmActivity, isStandalone: true, selector: "[mmActivity]", inputs: { visible: { classPropertyName: "visible", publicName: "mmActivity", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmActivity, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MmActivity, decorators: [{
             type: Directive,
             args: [{
                     selector: '[mmActivity]',
@@ -1129,10 +1129,10 @@ class SuspenseBoundaryBase {
     pending = this.scope.pending;
     suspended = computed(() => this.scope.suspended(this.type()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "suspended" }] : /* istanbul ignore next */ []));
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundaryBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: SuspenseBoundaryBase, isStandalone: true, inputs: { type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: SuspenseBoundaryBase, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.4", type: SuspenseBoundaryBase, isStandalone: true, inputs: { type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundaryBase, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: SuspenseBoundaryBase, decorators: [{
             type: Directive
         }], propDecorators: { type: [{ type: i0.Input, args: [{ isSignal: true, alias: "type", required: false }] }] } });
 const SUSPENSE_TEMPLATE = `
@@ -1160,10 +1160,10 @@ const SUSPENSE_HOST = {
  * `provideTransitionScope()`. The common case.
  */
 class SuspenseBoundary extends SuspenseBoundaryBase {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.2", type: SuspenseBoundary, isStandalone: true, selector: "mm-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, providers: [provideTransitionScope()], usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: SuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.4", type: SuspenseBoundary, isStandalone: true, selector: "mm-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, providers: [provideTransitionScope()], usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: SuspenseBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: SuspenseBoundary, decorators: [{
             type: Component,
             args: [{ selector: 'mm-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, providers: [provideTransitionScope()], styles: [":host{display:contents}\n"] }]
         }] });
@@ -1174,10 +1174,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImpor
  * ancestor.
  */
 class UnscopedSuspenseBoundary extends SuspenseBoundaryBase {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: UnscopedSuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.0.2", type: UnscopedSuspenseBoundary, isStandalone: true, selector: "mm-unscoped-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: UnscopedSuspenseBoundary, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.4", type: UnscopedSuspenseBoundary, isStandalone: true, selector: "mm-unscoped-suspense", host: { properties: { "attr.aria-busy": "pending() ? true : null" } }, usesInheritance: true, ngImport: i0, template: "\n  @if (suspended()) {\n    <ng-content select=\"[placeholder]\"><span>Loading\u2026</span></ng-content>\n  } @else {\n    @if (pending()) {\n      <ng-content select=\"[busy]\" />\n    }\n    <ng-content />\n  }\n", isInline: true, styles: [":host{display:contents}\n"] });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: UnscopedSuspenseBoundary, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: UnscopedSuspenseBoundary, decorators: [{
             type: Component,
             args: [{ selector: 'mm-unscoped-suspense', template: SUSPENSE_TEMPLATE, host: SUSPENSE_HOST, styles: [":host{display:contents}\n"] }]
         }] });
@@ -1440,10 +1440,10 @@ class MmTransition {
                 node.style.display = hidden ? 'none' : '';
         }
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmTransition, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: MmTransition, isStandalone: true, selector: "[mmTransition]", inputs: { value: { classPropertyName: "value", publicName: "mmTransition", isSignal: true, isRequired: true, transformFunction: null }, immediate: { classPropertyName: "immediate", publicName: "mmTransitionImmediate", isSignal: true, isRequired: false, transformFunction: null }, viewTransition: { classPropertyName: "viewTransition", publicName: "mmTransitionViewTransition", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["mmTransition"], ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MmTransition, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.4", type: MmTransition, isStandalone: true, selector: "[mmTransition]", inputs: { value: { classPropertyName: "value", publicName: "mmTransition", isSignal: true, isRequired: true, transformFunction: null }, immediate: { classPropertyName: "immediate", publicName: "mmTransitionImmediate", isSignal: true, isRequired: false, transformFunction: null }, viewTransition: { classPropertyName: "viewTransition", publicName: "mmTransitionViewTransition", isSignal: true, isRequired: false, transformFunction: null } }, exportAs: ["mmTransition"], ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmTransition, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MmTransition, decorators: [{
             type: Directive,
             args: [{
                     selector: '[mmTransition]',
@@ -1488,10 +1488,10 @@ class MmViewTransitionName {
                 el.style.removeProperty('view-transition-name');
         });
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmViewTransitionName, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.0.2", type: MmViewTransitionName, isStandalone: true, selector: "[mmViewTransitionName]", inputs: { mmViewTransitionName: { classPropertyName: "mmViewTransitionName", publicName: "mmViewTransitionName", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MmViewTransitionName, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.4", type: MmViewTransitionName, isStandalone: true, selector: "[mmViewTransitionName]", inputs: { mmViewTransitionName: { classPropertyName: "mmViewTransitionName", publicName: "mmViewTransitionName", isSignal: true, isRequired: true, transformFunction: null } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MmViewTransitionName, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MmViewTransitionName, decorators: [{
             type: Directive,
             args: [{ selector: '[mmViewTransitionName]' }]
         }], ctorParameters: () => [], propDecorators: { mmViewTransitionName: [{ type: i0.Input, args: [{ isSignal: true, alias: "mmViewTransitionName", required: true }] }] } });
@@ -1890,14 +1890,19 @@ function isDerivation(sig) {
 
 function keepPrevious(src, opt) {
     const mutableSrc = isWritableSignal$2(src) && isMutable(src);
+    const { fallback, ...signalOpt } = opt ?? {};
     let cnt = 0;
     const baseEqual = opt?.equal;
     const equal = mutableSrc
         ? (a, b) => cnt > 0 ? false : baseEqual ? baseEqual(a, b) : Object.is(a, b)
         : baseEqual;
-    const persisted = linkedSignal({ ...(ngDevMode ? { debugName: "persisted" } : /* istanbul ignore next */ {}), ...opt,
+    const persisted = linkedSignal({ ...(ngDevMode ? { debugName: "persisted" } : /* istanbul ignore next */ {}), ...signalOpt,
         source: () => src(),
-        computation: (next, prev) => next === undefined && prev !== undefined ? prev.value : next,
+        computation: (next, prev) => {
+            if (next !== undefined)
+                return next;
+            return prev !== undefined ? prev.value : fallback;
+        },
         equal });
     if (isWritableSignal$2(src)) {
         persisted.set = src.set;
@@ -5152,6 +5157,81 @@ function validateEnvelope(env) {
     }
     return null;
 }
+function wireValueViolation(value) {
+    return violationAt(value, false, []);
+}
+function violationAt(value, nested, ancestors) {
+    if (value === undefined)
+        return nested ? 'undefined-in-container' : null;
+    if (value === null)
+        return null;
+    const t = typeof value;
+    if (t === 'boolean' || t === 'string')
+        return null;
+    if (t === 'number') {
+        if (!Number.isFinite(value))
+            return 'non-finite-number';
+        return Object.is(value, -0) ? 'negative-zero' : null;
+    }
+    if (t === 'bigint')
+        return 'bigint';
+    if (t === 'function')
+        return 'function';
+    if (t === 'symbol')
+        return 'symbol';
+    if (ancestors.includes(value))
+        return 'cycle';
+    ancestors.push(value);
+    try {
+        if (Array.isArray(value)) {
+            for (let i = 0; i < value.length; i++) {
+                if (!Object.hasOwn(value, i))
+                    return 'sparse-array';
+                const reason = violationAt(value[i], true, ancestors);
+                if (reason)
+                    return reason;
+            }
+            const keys = Object.keys(value);
+            if (keys.length !== value.length)
+                return 'array-named-property';
+            for (const key of keys) {
+                const idx = Number(key);
+                if (String(idx) !== key ||
+                    !Number.isInteger(idx) ||
+                    idx < 0 ||
+                    idx >= value.length) {
+                    return 'array-named-property';
+                }
+            }
+            return null;
+        }
+        const proto = Object.getPrototypeOf(value);
+        if (proto !== Object.prototype && proto !== null)
+            return 'non-plain-object';
+        for (const key of Object.keys(value)) {
+            const reason = violationAt(value[key], true, ancestors);
+            if (reason)
+                return reason;
+        }
+        return null;
+    }
+    finally {
+        ancestors.pop();
+    }
+}
+// dev-only: one warning per offending batch names the first violating op, then stops
+const lintWireValues = (ops) => {
+    for (const op of ops) {
+        const reason = (op.kind === 'set' ? wireValueViolation(op.next) : null) ??
+            (op.kind !== 'clear' && Object.hasOwn(op, 'prev')
+                ? wireValueViolation(op.prev)
+                : null);
+        if (!reason)
+            continue;
+        console.warn(`[@mmstack/primitives] op value at "${op.path.join('.')}" will not survive a JSON transport (${reason}): peers materialize a different value than this emitter, and the room can diverge. Op values must round-trip JSON unchanged; encode rich leaves as strings.`);
+        return;
+    }
+};
 const lww = (_ancestor, mine) => mine;
 const mergeThree = (ancestor, mine, theirs) => merge3(ancestor, mine, theirs);
 const preserve = (ancestor, mine, theirs) => ({
@@ -5700,6 +5780,17 @@ function createConvergingApply(opt) {
             const reg = registers.get(keyOf$1(path));
             return reg ? liveOf(reg) : [];
         },
+        liveUnder: (path) => {
+            const key = keyOf$1(path);
+            const out = [];
+            const at = registers.get(key);
+            for (const reg of at ? [at, ...descendantsOf(key)] : descendantsOf(key)) {
+                const siblings = liveOf(reg);
+                if (siblings.length)
+                    out.push({ path: reg.path, siblings });
+            }
+            return out;
+        },
         materialize: () => {
             const root = registers.get('');
             const res = root?.result;
@@ -5906,6 +5997,8 @@ function opSync(source, opt) {
     const emitLocal = (ops) => {
         const frontier = scopeFrontier;
         const stamped = conv.stamp(ops, { bump: bumping, frontier });
+        if (isDevMode())
+            lintWireValues(stamped);
         const nextVersion = (versions.get(origin) ?? 0) + 1;
         const env = {
             proto: OP_PROTO_VERSION,
@@ -6010,6 +6103,7 @@ function opSync(source, opt) {
             log.flush(); // fold pending base writes in first, so they count as observed
             return conv.captureFrontier();
         },
+        liveUnder: (path) => conv.liveUnder(path),
         commitScope: (frontier, fn) => {
             log.flush(); // earlier pending writes emit against the live frontier, not this one
             scopeFrontier = frontier;
@@ -7037,10 +7131,10 @@ class MessageBus {
             post: (value) => this.channel.postMessage({ id, value }),
         };
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MessageBus, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.2", ngImport: i0, type: MessageBus, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.4", ngImport: i0, type: MessageBus, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',