ngx-blocks-studio 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-blocks-studio",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/winghei/ngx-blocks-studio.git"

package/types/ngx-blocks-studio.d.ts

@@ -539,6 +539,10 @@ declare function resolveRefPath(refPath: string, ctx: ResolverContext): {
     target: unknown;
     path: string[];
 } | null;
+/**
+ * True when any segment on the ref path is (or ends at) a signal or callable leaf.
+ */
+declare function refPathHasSignalAlongPath(refPath: string, ctx: ResolverContext): boolean;
 /**
  * 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.
@@ -593,7 +597,7 @@ interface InterpretFlowOptions {
      */
     interpolateText?: (segment: string) => string;
     /**
-     * When set, `@if (…)` evaluates this instead of `resolveRefOrModel` (e.g. safe expressions + payload).
+     * When set, `@if (…)` and `@for (… of …)` evaluate collection/condition via this instead of `resolveRefOrModel`.
      */
     resolveCondition?: (expression: string, scope: FlowScope) => unknown;
     /**
@@ -625,7 +629,7 @@ declare function resolveReferenceValue(ref: string, ctx: ResolverContext): unkno
  * 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).
  */
-declare function evaluateExpression(expression: string, ctx: ResolverContext, payload: unknown): unknown;
+declare function evaluateExpression(expression: string, ctx: ResolverContext, payload: unknown, scope?: Record<string, unknown>): unknown;
 /**
  * Resolves only `{{ … }}` segments via `evaluateExpression`.
  * Single full-string `{{ expr }}` preserves the evaluated type; mixed templates return a string.
@@ -641,7 +645,7 @@ interface ResolveTemplateStringOptions {
 }
 /**
  * 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).
  */
 declare function resolveTemplateString(value: string, ctx: ResolverContext, payload?: unknown, options?: ResolveTemplateStringOptions): unknown;
 
@@ -659,6 +663,10 @@ interface BlockLoadOptions {
     registry?: BlockRegistry;
     /** Map of block id → full description or loader; used when description is a block reference. */
     blockDefinitions?: Record<string, BlockDefinitionOrLoader>;
+    /** Generation captured when the directive started this load; paired with {@link getCurrentLoadGeneration}. */
+    loadGeneration?: number;
+    /** Returns the directive's current load generation (invalidates in-flight loads when it changes). */
+    getCurrentLoadGeneration?: () => number;
 }
 declare const INTERPOLATE_MAX_PLACEHOLDERS = 200;
 /** Builds a two-way binding when only a read getter exists for the key (used by {@link createInputBindingsWithWarnings}). */
@@ -669,7 +677,7 @@ declare class BlockLoaderService {
     private readonly directiveRegistry;
     private readonly serviceRegistry;
     private readonly blockRegistryService;
-    load(description: BlockInput | BlockReference, viewContainerRef: ViewContainerRef, model: Signal<unknown | undefined>, options?: BlockLoadOptions): Promise<ComponentRef<unknown>>;
+    load(description: BlockInput | BlockReference, viewContainerRef: ViewContainerRef, model: Signal<unknown | undefined>, options?: BlockLoadOptions): Promise<ComponentRef<unknown> | null>;
     private resolveServices;
     private buildChildInjectorFromTypes;
     /** Resolve all service types in parallel (single batch for load). */
@@ -701,11 +709,59 @@ declare class BlockDirective {
      * Useful for "same component, different inputs" scenarios like tabs/switch blocks.
      */
     readonly reloadKey: _angular_core.InputSignal<unknown>;
-    loadBlock(resolved: BlockInput | BlockReference, registry?: BlockRegistry, blockDefinitions?: Record<string, BlockDefinitionOrLoader>): Promise<_angular_core.ComponentRef<unknown>>;
+    loadBlock(resolved: BlockInput | BlockReference, registry?: BlockRegistry, blockDefinitions?: Record<string, BlockDefinitionOrLoader>, loadGeneration?: number, getCurrentLoadGeneration?: () => number): Promise<_angular_core.ComponentRef<unknown> | null>;
     constructor();
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<BlockDirective, never>;
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<BlockDirective, "[block]", never, { "description": { "alias": "description"; "required": false; "isSignal": true; }; "blockRegistry": { "alias": "blockRegistry"; "required": false; "isSignal": true; }; "blockDefinitions": { "alias": "blockDefinitions"; "required": false; "isSignal": true; }; "model": { "alias": "model"; "required": false; "isSignal": true; }; "reloadKey": { "alias": "reloadKey"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-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, isTwoWayRefString, linkedTwoWayFromInputGetter, looksLikeFlowTemplate, mustacheSegmentToString, normalizeDirectives, normalizeServices, parseFlowTemplate, parseRefPath, parseTwoWayRef, refPathResolvesToSignal, resolveBlockReference, resolveMustacheInterpolatedString, resolveRefOrModel, resolveRefPath, resolveReferenceValue, resolveTemplateString, safeParseBlockDescription, setRefValue, splitCallableRef };
-export type { AllRegistryMetadata, BlockDefinitionLoader, BlockDefinitionOrLoader, BlockDescription, BlockInput, BlockInstanceHandle, BlockLoadOptions, BlockOutputValue, BlockReference, BlockRegistry, CurrentInstance, FlowNode, FlowScope, GuardLoader, GuardOrLoader, GuardOrType, InterpretFlowOptions, OutputCallObject, OutputOnError, OutputReference, ParsedRefPath, RegistryEntryType, RegistryMetadataRecord, ResolveTemplateStringOptions, ResolverContext, RouteConfig, RouteConfigs, SafeParseBlockDescriptionResult, ScopedRegistryNode, ServiceEntry, ThenChainStep };
+/** JSON-like objects only — skip class instances, Date, Map, etc. */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Child block entry in a parent input tree (`blocks`, `rows`, `columns`, etc.).
+ * Template refs inside these objects are resolved when that block is loaded, not on the parent.
+ */
+declare function looksLikeBlockDescriptor(value: unknown): boolean;
+/** Same as {@link looksLikeBlockDescriptor}; use in custom layout blocks if needed. */
+declare const shouldDeferInputTemplateResolution: typeof looksLikeBlockDescriptor;
+/** True when any string leaf in the tree needs input-style resolution (mustache, flow, or `[( )]`). */
+declare function valueNeedsInputResolve(value: unknown, visited?: WeakSet<object>): boolean;
+/** True when any string leaf contains `{{ }}` (block model seeding). */
+declare function valueContainsMustacheInTree(value: unknown, visited?: WeakSet<object>): boolean;
+interface ResolveNestedTemplateOptions {
+    /**
+     * When true, exact `[(refPath)]` strings resolve to the current ref value (read-only).
+     * Does not create Angular two-way bindings on nested keys.
+     */
+    resolveTwoWayStringsAsReadonly?: boolean;
+    escapeFlowRefs?: boolean;
+}
+/**
+ * Deep-resolve template strings in plain objects and arrays (new object graph each call).
+ */
+declare function resolveNestedTemplateValues(value: unknown, ctx: ResolverContext, path?: string, visited?: WeakSet<object>, options?: ResolveNestedTemplateOptions): unknown;
+interface TemplateInputRefLeaf {
+    refPath: string;
+    /** When true (`ref('path', true)`), embed the leaf {@link Signal} on nested inputs when present. */
+    embedLeafSignal: boolean;
+}
+/** Single full-string mustache / two-way ref for nested input materialization. */
+declare function parseTemplateInputRefLeaf(str: string, ctx: ResolverContext): TemplateInputRefLeaf | undefined;
+/**
+ * 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).
+ */
+declare function materializeNestedReactiveInput(value: unknown, ctx: ResolverContext, path?: string, visited?: WeakSet<object>, options?: ResolveNestedTemplateOptions): unknown;
+/**
+ * Resolve a {@link materializeNestedReactiveInput} graph for block input binding:
+ * template strings become plain values; embedded {@link Signal}s are kept as references.
+ */
+declare function resolveMaterializedNestedInput(value: unknown, ctx: ResolverContext, path?: string, visited?: WeakSet<object>, options?: ResolveNestedTemplateOptions): unknown;
+/**
+ * Deep-read values from {@link materializeNestedReactiveInput}: unwraps embedded
+ * `Signal`s / `computed`s and recurses through plain objects and arrays.
+ */
+declare function readNestedInputValue<T>(value: T): T;
+
+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 };
+export type { AllRegistryMetadata, BlockDefinitionLoader, BlockDefinitionOrLoader, BlockDescription, BlockInput, BlockInstanceHandle, BlockLoadOptions, BlockOutputValue, BlockReference, BlockRegistry, CurrentInstance, FlowNode, FlowScope, GuardLoader, GuardOrLoader, GuardOrType, InterpretFlowOptions, OutputCallObject, OutputOnError, OutputReference, ParsedRefPath, RegistryEntryType, RegistryMetadataRecord, ResolveNestedTemplateOptions, ResolveTemplateStringOptions, ResolverContext, RouteConfig, RouteConfigs, SafeParseBlockDescriptionResult, ScopedRegistryNode, ServiceEntry, TemplateInputRefLeaf, ThenChainStep };