ngx-blocks-studio 0.2.1 → 0.2.2

package/README.md

@@ -113,7 +113,7 @@ JSON route files can include `children`, `data`, `title`, and guard arrays (`can
 
 ## Example: render a block with `[block]`
 
-Register the component key, then pass a **block description** and a shared **`BlockRegistry`** so nested blocks and cross-block refs resolve.
+Register the component key, then pass a **block description** and a shared **`BlockRegistry`** (`BlockRegistryImpl` or `ChainedBlockRegistry`) so nested blocks and cross-block refs resolve. See `docs/core/block-registry.md`.
 
 ```typescript
 ComponentRegistry.getInstance().register('MyPanel', MyPanelComponent);
@@ -153,4 +153,4 @@ ComponentRegistry.getInstance().register('MyPanel', MyPanelComponent);
 
 ## API surface (where to look in docs)
 
-When you have the repo: **Registry** (registries and metadata), **Block loader** (`BlockDirective`, `BlockLoaderService`, refs, outputs), **Route loader** (`RouteLoader`, `RouteConfig`, JSON loading). The source tree under `projects/blocks-studio/src/lib` matches the public exports.
+When you have the repo, see `docs/` in the repository root: **Registry** (type registries), **Block instance registry** (`BlockRegistryImpl`, `ChainedBlockRegistry`, `BlockRegistryService`), **Block loader** (`BlockDirective`, refs, outputs), **Route loader**. The source tree under `projects/blocks-studio/src/lib` matches the public exports.

package/fesm2022/ngx-blocks-studio.mjs

@@ -1414,6 +1414,87 @@ function resolveRefPath(refPath, ctx) {
     // can consistently handle signals and functions at the leaf.
     return { target: current, path: effectiveParts.slice(-1) };
 }
+/** Root value and property keys for a resolved ref (for path reactivity checks). */
+function getRefPathWalk(refPath, ctx) {
+    const parsed = parseRefPath(refPath);
+    const { scopeKey, blockId, serviceOrModel, pathParts } = parsed;
+    if (!serviceOrModel) {
+        return null;
+    }
+    const registry = scopeKey != null ? (ctx.getRegistryForScope?.(scopeKey) ?? null) : ctx.registry;
+    if (scopeKey != null && registry == null) {
+        return null;
+    }
+    let instance;
+    if (blockId != null) {
+        if (scopeKey == null &&
+            ctx.currentBlockId != null &&
+            blockId === ctx.currentBlockId &&
+            ctx.currentInstance != null) {
+            instance = ctx.currentInstance;
+        }
+        else {
+            if (registry == null) {
+                return null;
+            }
+            const handle = registry.get(blockId);
+            if (!handle) {
+                return null;
+            }
+            instance = handle.instance;
+        }
+    }
+    else {
+        instance = ctx.currentInstance ?? undefined;
+    }
+    if (instance == null)
+        return null;
+    if (serviceOrModel === 'model') {
+        const base = instance.model;
+        if (!base) {
+            return null;
+        }
+        return { start: base, parts: pathParts };
+    }
+    const service = instance.services?.[serviceOrModel];
+    const shouldModelFallback = blockId != null && service == null && instance.model != null;
+    const base = shouldModelFallback ? instance.model : service;
+    const effectiveParts = shouldModelFallback ? [serviceOrModel, ...pathParts] : pathParts;
+    if (!base) {
+        return null;
+    }
+    return { start: base, parts: effectiveParts };
+}
+/**
+ * True when any segment on the ref path is (or ends at) a signal or callable leaf.
+ */
+function refPathHasSignalAlongPath(refPath, ctx) {
+    const walk = getRefPathWalk(refPath, ctx);
+    if (walk == null) {
+        return false;
+    }
+    let current = walk.start;
+    if (current != null && isSignal(current)) {
+        return true;
+    }
+    const parts = walk.parts;
+    for (let i = 0; i < parts.length; i++) {
+        if (current == null || typeof current !== 'object') {
+            return false;
+        }
+        const key = parts[i];
+        const next = current[key];
+        const isLast = i === parts.length - 1;
+        if (isLast) {
+            return next != null && (isSignal(next) || typeof next === 'function');
+        }
+        if (next != null && isSignal(next)) {
+            return true;
+        }
+        current = next;
+    }
+    return false;
+}
 /**
  * Get a value from an object by dot-notation path (e.g. "name.firstName" -> obj.name?.firstName).
  * Returns undefined if any segment is null/undefined or not an object.
@@ -1794,7 +1875,10 @@ function interpretFlow(nodes, ctx, scope = {}, options) {
         }
         /* v8 ignore start -- exhaustive node.type chain; non-for nodes handled above */
         if (node.type === 'for') {
-            const arr = resolveRefOrModel(node.refPath, ctx);
+            const rawExpr = node.refPath.trim();
+            const arr = options?.resolveCondition
+                ? options.resolveCondition(rawExpr, scope)
+                : resolveRefOrModel(rawExpr, ctx);
             const list = Array.isArray(arr) ? arr : [];
             for (let idx = 0; idx < list.length; idx++) {
                 out += interpretFlow(node.body, ctx, {
@@ -2081,6 +2165,8 @@ function evalExpr(expr, ctx) {
             if (expr.name === '$event' || expr.name === 'event' || expr.name === 'payload' || expr.name === 'value') {
                 return ctx.payload;
             }
+            if (ctx.scope != null && expr.name in ctx.scope)
+                return ctx.scope[expr.name];
             if (expr.name in ctx.model)
                 return ctx.model[expr.name];
             if (ctx.services != null && expr.name in ctx.services)
@@ -2178,12 +2264,13 @@ function evalExpr(expr, ctx) {
             return evalExpr(expr.test, ctx) ? evalExpr(expr.consequent, ctx) : evalExpr(expr.alternate, ctx);
     }
 }
-function evaluateSafeExpression(expression, resolverContext, payload, resolveRefValue) {
+function evaluateSafeExpression(expression, resolverContext, payload, resolveRefValue, scope) {
     const ast = new Parser(tokenize(expression)).parse();
     return evalExpr(ast, {
         payload,
         model: (resolverContext.currentInstance?.model?.() ?? {}),
         services: resolverContext.currentInstance?.services,
+        scope,
         resolveRefValue: (ref) => resolveRefValue(ref, resolverContext),
     });
 }
@@ -2201,12 +2288,12 @@ function resolveReferenceValue(ref, ctx) {
  * Safe expression evaluation (same as output `{{ }}` / `@if (...)` when used with this module).
  * Falls back to `resolveReferenceValue` if parsing fails (treat whole string as a ref path).
  */
-function evaluateExpression(expression, ctx, payload) {
+function evaluateExpression(expression, ctx, payload, scope) {
     const trimmed = expression.trim();
     if (!trimmed)
         return undefined;
     try {
-        return evaluateSafeExpression(trimmed, ctx, payload, resolveReferenceValue);
+        return evaluateSafeExpression(trimmed, ctx, payload, resolveReferenceValue, scope);
     }
     catch {
         return resolveReferenceValue(trimmed, ctx);
@@ -2254,14 +2341,14 @@ function mustacheSegmentToString(segment, ctx, payload) {
 }
 /**
  * Unified template resolution: flow (`@if`, `@for`, `${}`) plus `{{ }}` in flow text segments.
- * `@if` conditions use `evaluateExpression` (safe expressions + ref fallback).
+ * `@if` / `@for (… of …)` use `evaluateExpression` (safe expressions + ref fallback).
  */
 function resolveTemplateString(value, ctx, payload = undefined, options) {
     const escapeFlowRefs = options?.escapeFlowRefs !== false;
     if (looksLikeFlowTemplate(value)) {
         return interpretFlow(parseFlowTemplate(value), ctx, {}, {
             escapeRefValues: escapeFlowRefs,
-            resolveCondition: (expr) => evaluateExpression(expr, ctx, payload),
+            resolveCondition: (expr, scope) => evaluateExpression(expr, ctx, payload, scope),
             interpolateText: (segment) => mustacheSegmentToString(segment, ctx, payload),
         });
     }
@@ -2614,6 +2701,147 @@ function resolveNestedTemplateValues(value, ctx, path = '', visited = new WeakSe
     }
     return value;
 }
+function parseSingleMustacheExpression(value) {
+    const trimmed = value.trim();
+    if (!trimmed.includes('{{') || !trimmed.includes('}}')) {
+        return undefined;
+    }
+    const re = /\{\{([\s\S]*?)\}\}/g;
+    const matches = [...trimmed.matchAll(re)];
+    if (matches.length !== 1 || matches[0][0] !== trimmed) {
+        return undefined;
+    }
+    return matches[0][1].trim();
+}
+/** Single full-string mustache / two-way ref for nested input materialization. */
+function parseTemplateInputRefLeaf(str, ctx) {
+    const twoWayKind = classifyTwoWayString(str);
+    if (twoWayKind === 'two-way') {
+        const refPath = parseTwoWayRef(str);
+        return refPath ? { refPath, embedLeafSignal: false } : undefined;
+    }
+    const expr = parseSingleMustacheExpression(str);
+    if (expr == null) {
+        return undefined;
+    }
+    const refCall = /^ref\s*\(\s*['"]([^'"]+)['"]\s*(?:,\s*(true|false))?\s*\)$/.exec(expr);
+    if (refCall) {
+        return {
+            refPath: refCall[1],
+            embedLeafSignal: refCall[2] === 'true',
+        };
+    }
+    // Only dotted / BlockId:path shapes — not ternaries (`:`) or other safe expressions.
+    if (!isSimpleDottedRefPathExpression(expr)) {
+        return undefined;
+    }
+    return resolveRefPath(expr, ctx) != null ? { refPath: expr, embedLeafSignal: false } : undefined;
+}
+/** `BlockId:service.path` or `service.path` only (no `ref()`, ternaries, or operators). */
+function isSimpleDottedRefPathExpression(expr) {
+    const t = expr.trim();
+    if (!t || /[?+]|===|!==|&&|\|\||\bref\s*\(/.test(t)) {
+        return false;
+    }
+    return /^[\w./-]+:[\w.]+$|^[\w.-]+(?:\.[\w.-]+)+$|^[\w.-]+$/.test(t);
+}
+function materializeEmbedRefLeaf(ctx, refPath) {
+    const refSignal = getRefSignal(refPath, ctx);
+    if (refSignal != null) {
+        return refSignal;
+    }
+    if (!refPathHasSignalAlongPath(refPath, ctx)) {
+        return getRefValue(refPath, ctx);
+    }
+    return computed(() => getRefValue(refPath, ctx));
+}
+/**
+ * Stable nested graph at bind time: literals and unresolved template strings stay as-is;
+ * only `{{ ref('path', true) }}` embeds the leaf {@link Signal} (or reactive fallback).
+ */
+function materializeNestedReactiveInput(value, ctx, path = '', visited = new WeakSet(), options = {}) {
+    if (typeof value === 'string') {
+        if (!stringNeedsInputResolve(value)) {
+            return value;
+        }
+        const refLeaf = parseTemplateInputRefLeaf(value, ctx);
+        if (refLeaf?.embedLeafSignal) {
+            return materializeEmbedRefLeaf(ctx, refLeaf.refPath);
+        }
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => {
+            const childPath = path ? `${path}[${index}]` : `[${index}]`;
+            return materializeNestedReactiveInput(item, ctx, childPath, visited, options);
+        });
+    }
+    if (value != null && typeof value === 'object') {
+        if (!isPlainObject(value))
+            return value;
+        if (looksLikeBlockDescriptor(value))
+            return value;
+        if (visited.has(value))
+            return value;
+        visited.add(value);
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+            const childPath = path ? `${path}.${key}` : key;
+            return [key, materializeNestedReactiveInput(item, ctx, childPath, visited, options)];
+        }));
+    }
+    return value;
+}
+/**
+ * Resolve a {@link materializeNestedReactiveInput} graph for block input binding:
+ * template strings become plain values; embedded {@link Signal}s are kept as references.
+ */
+function resolveMaterializedNestedInput(value, ctx, path = '', visited = new WeakSet(), options = {}) {
+    if (isSignal(value)) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        if (!stringNeedsInputResolve(value)) {
+            return value;
+        }
+        return resolveStringLeaf(value, ctx, path || 'input', options);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item, index) => {
+            const childPath = path ? `${path}[${index}]` : `[${index}]`;
+            return resolveMaterializedNestedInput(item, ctx, childPath, visited, options);
+        });
+    }
+    if (value != null && typeof value === 'object') {
+        if (!isPlainObject(value))
+            return value;
+        if (looksLikeBlockDescriptor(value))
+            return value;
+        if (visited.has(value))
+            return value;
+        visited.add(value);
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+            const childPath = path ? `${path}.${key}` : key;
+            return [key, resolveMaterializedNestedInput(item, ctx, childPath, visited, options)];
+        }));
+    }
+    return value;
+}
+/**
+ * Deep-read values from {@link materializeNestedReactiveInput}: unwraps embedded
+ * `Signal`s / `computed`s and recurses through plain objects and arrays.
+ */
+function readNestedInputValue(value) {
+    if (isSignal(value)) {
+        return readNestedInputValue(value());
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => readNestedInputValue(item));
+    }
+    if (isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, readNestedInputValue(item)]));
+    }
+    return value;
+}
 
 const NESTED_INPUT_RESOLVE_OPTIONS = {
     resolveTwoWayStringsAsReadonly: true,
@@ -2730,7 +2958,8 @@ function resolveBlockInputsAndOutputs(description, inputKeys, outputKeys, twoWay
         }
         if (Array.isArray(value) || isPlainObject(value)) {
             if (valueNeedsInputResolve(value)) {
-                resolvedInputs[key] = computed(() => resolveNestedTemplateValues(value, ctx, key, new WeakSet(), NESTED_INPUT_RESOLVE_OPTIONS));
+                const materialized = materializeNestedReactiveInput(value, ctx, key, new WeakSet(), NESTED_INPUT_RESOLVE_OPTIONS);
+                resolvedInputs[key] = computed(() => resolveMaterializedNestedInput(materialized, ctx, key, new WeakSet(), NESTED_INPUT_RESOLVE_OPTIONS));
             }
             else if (inputKeys.has(key)) {
                 resolvedInputs[key] = () => value;
@@ -2754,6 +2983,12 @@ function resolveBlockInputsAndOutputs(description, inputKeys, outputKeys, twoWay
     return { resolvedInputs, resolvedOutputs, resolvedTwoWay };
 }
 
+function isBlockLoadStale(options) {
+    if (options?.loadGeneration == null || options.getCurrentLoadGeneration == null) {
+        return false;
+    }
+    return options.loadGeneration !== options.getCurrentLoadGeneration();
+}
 const INTERPOLATE_MAX_PLACEHOLDERS = 200;
 /** Builds a two-way binding when only a read getter exists for the key (used by {@link createInputBindingsWithWarnings}). */
 function linkedTwoWayFromInputGetter(resolvedInputs, key) {
@@ -2794,9 +3029,13 @@ class BlockLoaderService {
     serviceRegistry = ServiceRegistry.getInstance();
     blockRegistryService = inject(BlockRegistryService);
     async load(description, viewContainerRef, model, options) {
+        const blockId = (id) => id != null && id !== '' ? id : null;
         let resolved = description;
         if (isBlockReference(description)) {
             resolved = await resolveBlockReference(description, options?.blockDefinitions);
+            if (isBlockLoadStale(options)) {
+                return null;
+            }
         }
         const parsed = safeParseBlockDescription(resolved);
         if (!parsed.success) {
@@ -2804,10 +3043,10 @@ class BlockLoaderService {
         }
         const desc = parsed.data;
         const registry = options?.registry ?? new BlockRegistryImpl();
-        if (desc.id != null && desc.id !== '' && registry.hasLocal(desc.id)) {
-            throw new Error(`Block id "${desc.id}" is already registered.`);
-        }
         const componentType = await this.componentRegistry.get(desc.component);
+        if (isBlockLoadStale(options)) {
+            return null;
+        }
         if (!componentType) {
             throw new Error(`Component "${desc.component}" is not registered.`);
         }
@@ -2823,13 +3062,16 @@ class BlockLoaderService {
         this.resolveContextModel(ctx, model);
         const resolvedModel = blockInstance.model;
         const handle = { instance: blockInstance };
-        //... Register the block instance with the registry if it has an id
-        if (desc.id != null && desc.id !== '')
-            registry.register(desc.id, handle);
         //... Resolve services for the block
         await this.resolveServices(viewContainerRef, blockInstance, desc, resolvedModel, model);
+        if (isBlockLoadStale(options)) {
+            return null;
+        }
         const directiveIds = normalizeDirectives(desc.directives);
         const directiveTypes = await this.getDirectiveTypes(directiveIds);
+        if (isBlockLoadStale(options)) {
+            return null;
+        }
         const nonNullDirectiveTypes = directiveTypes.filter((d) => d != null);
         // get inputs and outputs from the component and host directives
         const componentMetadata = getBlockInputsAndOutputs([componentType]);
@@ -2861,11 +3103,36 @@ class BlockLoaderService {
                 ...createInputBindingsWithWarnings(`directive "${d.type.name}"`, d.metadata.inputs, d.metadata.twoWay, d.metadata.outputs, initialResolved.resolvedInputs, initialResolved.resolvedTwoWay, initialResolved.resolvedOutputs),
             ],
         }));
-        const componentRef = viewContainerRef.createComponent(componentType, {
-            directives: directiveAndBindings,
-            bindings: componentBindings,
-        });
-        return componentRef;
+        const id = blockId(desc.id);
+        try {
+            if (id != null) {
+                if (registry.hasLocal(id)) {
+                    registry.unregister(id);
+                }
+                if (isBlockLoadStale(options)) {
+                    return null;
+                }
+                registry.register(id, handle);
+            }
+            const componentRef = viewContainerRef.createComponent(componentType, {
+                directives: directiveAndBindings,
+                bindings: componentBindings,
+            });
+            if (isBlockLoadStale(options)) {
+                componentRef.destroy();
+                if (id != null) {
+                    registry.unregister(id);
+                }
+                return null;
+            }
+            return componentRef;
+        }
+        catch (err) {
+            if (id != null) {
+                registry.unregister(id);
+            }
+            throw err;
+        }
     }
     async resolveServices(viewContainerRef, blockInstance, desc, resolvedModel, model) {
         // services are stored under `blockInstance.services`, so `model` no longer collides structurally,
@@ -3040,14 +3307,12 @@ function clearBlockDirective(state, viewContainerRef) {
         state.lastRegistry?.unregister(state.lastId);
         state.lastId = null;
     }
-    if (state.loadResult) {
-        viewContainerRef.clear();
-        state.loadResult = null;
-        state.loadedComponent = null;
-        state.loadedServicesKey = null;
-        state.loadedReloadKey = null;
-        state.loadedDescKey = null;
-    }
+    viewContainerRef.clear();
+    state.loadResult = null;
+    state.loadedComponent = null;
+    state.loadedServicesKey = null;
+    state.loadedReloadKey = null;
+    state.loadedDescKey = null;
 }
 function runBlockDirectiveEffect(state, ctx, desc, inputDefs, blockRegistry, reloadKey) {
     const runId = ++state.effectRunId;
@@ -3091,10 +3356,15 @@ function runBlockDirectiveEffect(state, ctx, desc, inputDefs, blockRegistry, rel
         state.lastId = data.id ?? null;
         const generation = ++state.loadGeneration;
         ctx
-            .loadBlock(resolved, registry, inputDefs ?? undefined)
+            .loadBlock(resolved, registry, inputDefs ?? undefined, generation, () => state.loadGeneration)
             .then((result) => {
-            if (generation !== state.loadGeneration)
+            if (generation !== state.loadGeneration) {
+                result?.destroy();
                 return;
+            }
+            if (result == null) {
+                return;
+            }
             state.loadResult = result;
             state.loadedComponent = data.component;
             state.loadedServicesKey = servicesKey;
@@ -3145,10 +3415,12 @@ class BlockDirective {
      */
     reloadKey = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "reloadKey" }] : /* istanbul ignore next */ []));
-    loadBlock(resolved, registry, blockDefinitions) {
+    loadBlock(resolved, registry, blockDefinitions, loadGeneration, getCurrentLoadGeneration) {
         return this.loader.load(resolved, this.viewContainerRef, this.model, {
             registry,
             blockDefinitions,
+            loadGeneration,
+            getCurrentLoadGeneration,
         });
     }
     constructor() {
@@ -3179,5 +3451,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.2.3", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { BlockDefinitionsRegistry, BlockDirective, BlockLoaderService, BlockRegistryImpl, BlockRegistryService, ChainedBlockRegistry, ComponentRegistry, DirectiveRegistry, GuardRegistry, INTERPOLATE_MAX_PLACEHOLDERS, RegistryMetadataStore, RouteLoader, ServiceRegistry, buildComputedForTemplate, classifyTwoWayString, collectRefPaths, createInputBindingsWithWarnings, createOutputHandler, deepMergeBlockDefinition, evaluateExpression, extractReadonlyRefs, getRefPathFromReadonly, getRefSignal, getRefValue, getValueByPath, interpretFlow, isBlockDefinitionLoader, isBlockReference, isInvalidTwoWayMix, isOutputCallObject, isOutputReference, isPlainObject, isTwoWayRefString, linkedTwoWayFromInputGetter, looksLikeBlockDescriptor, looksLikeFlowTemplate, mustacheSegmentToString, normalizeDirectives, normalizeServices, parseFlowTemplate, parseRefPath, parseTwoWayRef, refPathResolvesToSignal, resolveBlockReference, resolveMustacheInterpolatedString, resolveNestedTemplateValues, resolveRefOrModel, resolveRefPath, resolveReferenceValue, resolveTemplateString, safeParseBlockDescription, setRefValue, shouldDeferInputTemplateResolution, splitCallableRef, valueContainsMustacheInTree, valueNeedsInputResolve };
+export { BlockDefinitionsRegistry, BlockDirective, BlockLoaderService, BlockRegistryImpl, BlockRegistryService, ChainedBlockRegistry, ComponentRegistry, DirectiveRegistry, GuardRegistry, INTERPOLATE_MAX_PLACEHOLDERS, RegistryMetadataStore, RouteLoader, ServiceRegistry, buildComputedForTemplate, classifyTwoWayString, collectRefPaths, createInputBindingsWithWarnings, createOutputHandler, deepMergeBlockDefinition, evaluateExpression, extractReadonlyRefs, getRefPathFromReadonly, getRefSignal, getRefValue, getValueByPath, interpretFlow, isBlockDefinitionLoader, isBlockReference, isInvalidTwoWayMix, isOutputCallObject, isOutputReference, isPlainObject, isTwoWayRefString, linkedTwoWayFromInputGetter, looksLikeBlockDescriptor, looksLikeFlowTemplate, materializeNestedReactiveInput, mustacheSegmentToString, normalizeDirectives, normalizeServices, parseFlowTemplate, parseRefPath, parseTemplateInputRefLeaf, parseTwoWayRef, readNestedInputValue, refPathHasSignalAlongPath, refPathResolvesToSignal, resolveBlockReference, resolveMaterializedNestedInput, resolveMustacheInterpolatedString, resolveNestedTemplateValues, resolveRefOrModel, resolveRefPath, resolveReferenceValue, resolveTemplateString, safeParseBlockDescription, setRefValue, shouldDeferInputTemplateResolution, splitCallableRef, valueContainsMustacheInTree, valueNeedsInputResolve };
 //# sourceMappingURL=ngx-blocks-studio.mjs.map