ngx-blocks-studio 0.0.1

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

@@ -0,0 +1,520 @@
+import * as _angular_core from '@angular/core';
+import { Type, Injector, Signal, ComponentRef, ViewContainerRef } from '@angular/core';
+import { CanActivateFn, RunGuardsAndResolvers } from '@angular/router';
+import { z } from 'zod';
+
+/**
+ * Registry entry type: component, service, or guard.
+ */
+type RegistryEntryType = 'component' | 'service' | 'guard';
+/**
+ * Metadata value stored per registry key.
+ */
+type RegistryMetadataRecord = Record<string, unknown>;
+interface AllRegistryMetadata {
+    components: Map<string, RegistryMetadataRecord>;
+    services: Map<string, RegistryMetadataRecord>;
+    guards: Map<string, RegistryMetadataRecord>;
+}
+/**
+ * Single source of truth for metadata across component, service, and guard registries.
+ * All registries delegate to this store so metadata can be queried uniformly
+ * and all metadata can be retrieved in one call.
+ */
+declare class RegistryMetadataStore {
+    private static instance;
+    private entries;
+    private constructor();
+    static getInstance(): RegistryMetadataStore;
+    /**
+     * Set metadata for a registry key (component, service, or guard).
+     */
+    set(key: string, type: RegistryEntryType, data: RegistryMetadataRecord): void;
+    /**
+     * Get metadata for a key. Returns undefined if the key is not registered.
+     */
+    get(key: string): RegistryMetadataRecord | undefined;
+    /**
+     * Alias for get(); allows registries to expose getMetadata(key).
+     */
+    getMetadata(key: string): RegistryMetadataRecord | undefined;
+    /**
+     * Get all metadata for a given type (components or services).
+     */
+    getByType(type: RegistryEntryType): Map<string, RegistryMetadataRecord>;
+    /**
+     * Get all metadata for component, service, and guard registries in one call.
+     */
+    getAllMetadata(): AllRegistryMetadata;
+    /**
+     * Remove metadata for a key (e.g. when unregistering).
+     */
+    remove(key: string): boolean;
+    /**
+     * Check if metadata exists for a key.
+     */
+    has(key: string): boolean;
+    /**
+     * Clear all metadata (e.g. when clearing registries).
+     */
+    clear(): void;
+}
+
+type ComponentLoader = () => Promise<Type<any>>;
+declare class ComponentRegistry {
+    private static instance;
+    private components;
+    private loadedComponents;
+    private readonly metadataStore;
+    private constructor();
+    static getInstance(): ComponentRegistry;
+    register(name: string, component: Type<any> | ComponentLoader, metadata?: RegistryMetadataRecord): void;
+    get(name: string): Promise<Type<any> | undefined>;
+    getSync(name: string): Type<any> | undefined;
+    has(name: string): boolean;
+    getAll(): Map<string, Type<any>>;
+    unregister(name: string): boolean;
+    clear(): void;
+    getMetadata(key: string): RegistryMetadataRecord | undefined;
+    getAllWithMetadata(): Map<string, {
+        component: Type<any>;
+        metadata?: RegistryMetadataRecord;
+    }>;
+}
+
+/**
+ * Guard type: functional guard or class-based guard type.
+ * Registered by name; resolved by RouteLoader from route config guards array.
+ */
+type GuardOrType = CanActivateFn | Type<unknown>;
+/** Loader for lazy-loaded guards. Must be a function with no parameters that returns Promise<GuardOrType>. */
+type GuardLoader = () => Promise<GuardOrType>;
+type GuardOrLoader = GuardOrType | GuardLoader;
+declare class GuardRegistry {
+    private static instance;
+    private guards;
+    private loadedGuards;
+    private readonly metadataStore;
+    private constructor();
+    static getInstance(): GuardRegistry;
+    register(name: string, guard: GuardOrLoader, metadata?: RegistryMetadataRecord): void;
+    /**
+     * Resolve guard by name (async; runs loader if needed).
+     */
+    get(name: string): Promise<GuardOrType | undefined>;
+    /**
+     * Resolve guard synchronously. Returns undefined if the entry is a lazy loader not yet loaded.
+     */
+    getSync(name: string): GuardOrType | undefined;
+    has(name: string): boolean;
+    getMetadata(key: string): RegistryMetadataRecord | undefined;
+    getAllWithMetadata(): Map<string, {
+        guard: GuardOrType;
+        metadata?: RegistryMetadataRecord;
+    }>;
+    unregister(name: string): boolean;
+    clear(): void;
+    private isLoader;
+}
+
+type ServiceLoader = () => Promise<Type<any>>;
+declare class ServiceRegistry {
+    private static instance;
+    private services;
+    private loadedServices;
+    private injector;
+    private readonly metadataStore;
+    private constructor();
+    static getInstance(): ServiceRegistry;
+    /**
+     * Set the injector to use for service resolution
+     */
+    setInjector(injector: Injector): void;
+    /**
+     * Register a service by name (supports lazy loading)
+     */
+    register(name: string, service: Type<any> | ServiceLoader, metadata?: RegistryMetadataRecord): void;
+    /**
+     * Get a service instance by name (supports lazy loading)
+     * Requires injector to be set first
+     */
+    get(name: string): Promise<any>;
+    /**
+     * Get a service instance synchronously (only works for already loaded services)
+     */
+    getSync(name: string): any;
+    /**
+     * Inject a service type using the injector
+     */
+    private injectService;
+    /**
+     * Get the service Type (class) by name (supports lazy loading).
+     * Use this to scope the provider to a child injector (e.g. "self" context).
+     */
+    getType(name: string): Promise<Type<any> | undefined>;
+    /**
+     * Get the service Type synchronously (only for already loaded services).
+     */
+    getTypeSync(name: string): Type<any> | undefined;
+    /**
+     * Check if a service is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Get all registered service names
+     */
+    getAllNames(): string[];
+    /**
+     * Get metadata for a registered service by key.
+     */
+    getMetadata(key: string): RegistryMetadataRecord | undefined;
+    /**
+     * Unregister a service
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all registered services
+     */
+    clear(): void;
+}
+
+/**
+ * Route configuration for the router.
+ * @param path - The path of the route.
+ * @param component - The component key to load for the route using the ComponentRegistry.
+ * @param title - The title of the route.
+ * @param canActivate - The guards keys to activate for the route using the GuardRegistry.
+ * @param canDeactivate - The guards keys to deactivate for the route using the GuardRegistry.
+ * @param canLoad - The guards keys to load for the route using the GuardRegistry.
+ * @param canMatch - The guards keys to match for the route using the GuardRegistry.
+ * @param pathMatch - The path match strategy for the route.
+ * @param outlet - The outlet of the route.
+ * @param canActivateChild - The guards keys to activate the children routes for the route using the GuardRegistry.
+ * @param runGuardsAndResolvers - The strategy to run guards and resolvers for the route.
+ * @param data - The data to pass to the route. It will be merged with the data from the route config file.
+ * @param children - Nested routes and optional defaultRedirect/catchAllRedirect for the child segment.
+ */
+interface RouteConfig {
+    path: string;
+    component: string;
+    title?: string;
+    canActivate?: string[];
+    canDeactivate?: string[];
+    canLoad?: string[];
+    canMatch?: string[];
+    outlet?: string;
+    pathMatch?: 'full' | 'prefix';
+    canActivateChild?: string[];
+    runGuardsAndResolvers?: RunGuardsAndResolvers;
+    data?: Record<string, any>;
+    /** Child routes; can include defaultRedirect and catchAllRedirect for this segment. */
+    children?: RouteConfigs;
+}
+interface RouteConfigs {
+    routes: RouteConfig[];
+    /** Redirect path for empty route (path: ''). Omit to not add a default redirect. */
+    defaultRedirect?: string;
+    /** Redirect path for unknown routes (path: '**'). Omit to not add a catch-all. */
+    catchAllRedirect?: string;
+}
+declare class RouteLoader {
+    private router;
+    private http;
+    private componentRegistry;
+    private guardRegistry;
+    private readonly _routeConfigFile;
+    private readonly _configPath;
+    /** Currently loaded route config file, or null if not yet loaded. */
+    readonly routeConfigFile: _angular_core.Signal<RouteConfigs | null>;
+    /** Path from which the config was loaded. */
+    readonly configPath: _angular_core.Signal<string>;
+    /** Route config array from the loaded file. */
+    readonly routeConfig: _angular_core.Signal<RouteConfig[]>;
+    /**
+     * Load routes from a config object. Updates signals and resets the router.
+     */
+    loadRoutes(config: RouteConfigs): Promise<void>;
+    /**
+     * Fetch route config from a URL (HTTP GET), then load it. Sets configPath signal to the requested URL.
+     */
+    loadRoutesFromUrl(configPath: string): Promise<void>;
+    private updateRoutes;
+    private convertRouteConfig;
+    private resolveGuards;
+    private loadComponent;
+    private getGuard;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<RouteLoader, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<RouteLoader>;
+}
+
+/**
+ * Service entry: root-scoped (string id) or self-scoped ({ id, scope: "self" }).
+ */
+declare const ServiceEntrySchema: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    id: z.ZodString;
+    scope: z.ZodLiteral<"self">;
+}, z.core.$strip>]>;
+/**
+ * Output handler: empty (use directive-provided handler) or reference-based (call method on ref).
+ */
+declare const OutputReferenceSchema: z.ZodObject<{
+    type: z.ZodLiteral<"reference">;
+    reference: z.ZodString;
+    method: z.ZodString;
+    params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    then: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        reference: z.ZodString;
+        method: z.ZodString;
+        params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    }, z.core.$strip>>>;
+    onSuccess: z.ZodOptional<z.ZodObject<{
+        reference: z.ZodString;
+        method: z.ZodString;
+        params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    }, z.core.$strip>>;
+    onError: z.ZodOptional<z.ZodObject<{
+        reference: z.ZodString;
+        method: z.ZodString;
+        params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Block description: JSON-serializable descriptor for dynamic block loading.
+ * Refs in inputs use instance namespace: instance.FormState.firstName or UserForm.instance.FormState.firstName.
+ */
+declare const BlockDescriptionSchema: z.ZodObject<{
+    component: z.ZodString;
+    id: z.ZodOptional<z.ZodString>;
+    services: z.ZodDefault<z.ZodOptional<z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        scope: z.ZodLiteral<"self">;
+    }, z.core.$strip>]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        id: z.ZodString;
+        scope: z.ZodLiteral<"self">;
+    }, z.core.$strip>]>>]>>>;
+    inputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    outputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodObject<{
+        type: z.ZodLiteral<"reference">;
+        reference: z.ZodString;
+        method: z.ZodString;
+        params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        then: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            reference: z.ZodString;
+            method: z.ZodString;
+            params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        }, z.core.$strip>>>;
+        onSuccess: z.ZodOptional<z.ZodObject<{
+            reference: z.ZodString;
+            method: z.ZodString;
+            params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        }, z.core.$strip>>;
+        onError: z.ZodOptional<z.ZodObject<{
+            reference: z.ZodString;
+            method: z.ZodString;
+            params: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodUnknown>, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>]>>>;
+}, z.core.$strip>;
+type BlockDescription = z.infer<typeof BlockDescriptionSchema>;
+type ServiceEntry = z.infer<typeof ServiceEntrySchema>;
+type OutputReference = z.infer<typeof OutputReferenceSchema>;
+/** Normalize services to array. */
+declare function normalizeServices(services: BlockDescription['services']): ServiceEntry[];
+declare function parseBlockDescription(data: unknown): BlockDescription;
+declare function safeParseBlockDescription(data: unknown): ReturnType<typeof BlockDescriptionSchema.safeParse>;
+declare function isOutputReference(value: unknown): value is OutputReference;
+/**
+ * Reference to a registered block: { id: string } or { blockId: string, blockDefinition?: object }.
+ * When blockDefinition is provided, it is deep-merged onto the base definition so only
+ * specified properties override (e.g. inputs.model); other keys are preserved.
+ */
+interface BlockReference {
+    id?: string;
+    blockId?: string;
+    blockDefinition?: Record<string, unknown>;
+}
+declare function isBlockReference(value: unknown): value is BlockReference;
+/** @deprecated Use isBlockReference. Id-only is still supported as { id: string }. */
+declare function isIdReference(value: unknown): value is {
+    id: string;
+};
+/**
+ * Deep-merge override onto base. Only keys present in override are changed; nested objects
+ * are merged recursively so e.g. override.inputs.model does not remove base.inputs.rows.
+ * Arrays and primitives in override replace the base value.
+ */
+declare function deepMergeBlockDefinition(base: Record<string, unknown>, override: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Resolve a block reference to a full description using blockDefinitions.
+ * If blockDefinition is present, it is deep-merged onto the base; otherwise returns the base.
+ */
+declare function resolveBlockReference(ref: BlockReference, blockDefinitions: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * Global registry of block id → definition. Register block configs at app init
+ * so they can be used as templates anywhere (e.g. nested blocks that reference
+ * { id: 'AppNav' } resolve without passing blockDefinitions down).
+ * Per-call blockDefinitions (e.g. from route data) override global entries.
+ */
+declare class BlockDefinitionsRegistry {
+    private static instance;
+    private readonly definitions;
+    private constructor();
+    static getInstance(): BlockDefinitionsRegistry;
+    /** Register a block template by id. Can be called before the block is needed. */
+    register(id: string, definition: Record<string, unknown>): void;
+    /** Get one definition by id. */
+    get(id: string): Record<string, unknown> | undefined;
+    /** Get all registered definitions (id → definition). Used to merge with per-call definitions. */
+    getAll(): Record<string, unknown>;
+    unregister(id: string): boolean;
+}
+
+/**
+ * Handle for a registered block: exposes instance (services/state by name) for ref resolution.
+ */
+interface BlockInstanceHandle {
+    /** Instance: services and state by name (e.g. FormState, value). */
+    instance: Record<string, unknown>;
+    /** Optional cleanup when block is destroyed. */
+    destroy?: () => void;
+}
+/**
+ * Registry of block instances by (full) id within a tree.
+ * One registry per logical tree; duplicate id throws.
+ */
+interface BlockRegistry {
+    register(id: string, handle: BlockInstanceHandle): void;
+    unregister(id: string): void;
+    get(id: string): BlockInstanceHandle | undefined;
+    has(id: string): boolean;
+}
+/**
+ * Default in-memory BlockRegistry.
+ */
+declare class BlockRegistryImpl implements BlockRegistry {
+    private readonly map;
+    register(id: string, handle: BlockInstanceHandle): void;
+    unregister(id: string): void;
+    get(id: string): BlockInstanceHandle | undefined;
+    has(id: string): boolean;
+}
+
+/**
+ * Parse ref paths and detect {{ref}} (read-only) and [(ref)] (two-way) in strings.
+ */
+interface ParsedRefPath {
+    blockId?: string;
+    instancePath: string;
+    pathParts: string[];
+}
+declare function parseRefPath(refPath: string): ParsedRefPath;
+declare function extractReadonlyRefs(template: string): string[];
+declare function isTwoWayRefString(value: unknown): value is string;
+/**
+ * True when a string contains two-way ref delimiters `[(` or `)]` but is not a valid
+ * standalone two-way ref (exact form `[(refPath)]`). Mixing two-way with literals or {{ }} is invalid.
+ */
+declare function isInvalidTwoWayMix(value: unknown): value is string;
+/**
+ * One trim + one pass: classify string for two-way ref handling. Use instead of calling
+ * isInvalidTwoWayMix and isTwoWayRefString separately to avoid double trim/regex.
+ */
+declare function classifyTwoWayString(value: unknown): 'two-way' | 'invalid-mix' | 'none';
+declare function parseTwoWayRef(value: string): string | null;
+declare function getRefPathFromReadonly(template: string, match: string): string;
+
+interface ResolverContext {
+    registry: BlockRegistry;
+    /** Current block's full id (nearest block with id). */
+    currentBlockId?: string;
+    /** Current block's instance (services/state by name). */
+    currentInstance?: Record<string, unknown>;
+}
+/**
+ * Resolve a ref path to the target object and path.
+ * Path format: "instance.FormState.firstName" (context) or "UserForm.instance.FormState.firstName" (registry).
+ */
+declare function resolveRefPath(refPath: string, ctx: ResolverContext): {
+    target: unknown;
+    path: string[];
+} | null;
+/**
+ * Get value at ref path (read-only). Returns undefined if not found.
+ */
+declare function getRefValue(refPath: string, ctx: ResolverContext): unknown;
+/**
+ * Set value at ref path (write). No-op if target is not writable.
+ */
+declare function setRefValue(refPath: string, ctx: ResolverContext, value: unknown): void;
+/**
+ * Build a computed signal for a template string with {{refPath}} placeholders.
+ */
+declare function buildComputedForTemplate(template: string, refPaths: string[], ctx: ResolverContext): Signal<string>;
+
+declare function resolveOutputReference(ref: OutputReference, eventValue: unknown, registry: BlockRegistry): (value: unknown) => void;
+declare function createOutputHandler(outputValue: unknown, outputKey: string, registry: BlockRegistry, directiveHandlers?: Record<string, (value: unknown) => void>): (value: unknown) => void;
+
+interface BlockLoadOptions {
+    outputHandlers?: Record<string, (value: unknown) => void>;
+    registry?: BlockRegistry;
+    /** Map of block id → full description; used when description is an id-only reference. */
+    blockDefinitions?: Record<string, unknown>;
+}
+interface BlockLoadResult {
+    componentRef: ComponentRef<unknown>;
+    destroy: () => void;
+    updateInputs: (description: unknown) => void;
+}
+declare class BlockLoaderService {
+    private readonly injector;
+    private readonly componentRegistry;
+    private readonly serviceRegistry;
+    load(description: unknown, viewContainerRef: ViewContainerRef, options?: BlockLoadOptions): Promise<BlockLoadResult>;
+    /** Resolve all service types in parallel (single batch for load). */
+    private getServiceTypes;
+    private buildChildInjectorFromTypes;
+    /** Set inputs and wire template/two-way effects. Single pass over inputs for large configs. */
+    private setInputs;
+    /** Replace all {{ refPath }} with resolved values. Uses parts array + join to avoid N string concats. */
+    private static readonly INTERPOLATE_MAX_PLACEHOLDERS;
+    private interpolateTemplate;
+    /**
+     * Resolve a single input value: resolve two-way refs, recurse into arrays/objects.
+     * Strings with {{ }} are left as-is so child blocks receive the template for reactive interpolation.
+     * Two-way refs inside nested block descriptors (object with "component" + "inputs") are left as-is
+     * so that when a child block is loaded it still sees value: '[(ref)]' and can wire two-way binding.
+     */
+    private resolveInputValue;
+    private wireOutputs;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<BlockLoaderService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<BlockLoaderService>;
+}
+
+declare class BlockDirective {
+    private readonly viewContainerRef;
+    private readonly loader;
+    private readonly destroyRef;
+    /** Full description, or { id } / { blockId, blockDefinition? } to reuse/override from blockDefinitions. */
+    readonly description: _angular_core.InputSignal<unknown>;
+    /** Handlers for component outputs; keys match descriptor.outputs. */
+    readonly outputHandlers: _angular_core.InputSignal<Record<string, (value: unknown) => void>>;
+    /** Registry for block instances by id; pass from root so nested blocks share it. */
+    readonly blockRegistry: _angular_core.InputSignal<BlockRegistry | null>;
+    /** Map id → full description; used when description is a block reference (id/blockId). */
+    readonly blockDefinitions: _angular_core.InputSignal<Record<string, unknown> | null>;
+    private loadResult;
+    private loadedComponent;
+    private loadedServicesKey;
+    private loadGeneration;
+    /** Avoid re-parsing when the same description reference is passed (e.g. stable signal). */
+    private lastDescRef;
+    private lastParsedData;
+    constructor();
+    private clear;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<BlockDirective, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<BlockDirective, "[block]", never, { "description": { "alias": "description"; "required": false; "isSignal": true; }; "outputHandlers": { "alias": "outputHandlers"; "required": false; "isSignal": true; }; "blockRegistry": { "alias": "blockRegistry"; "required": false; "isSignal": true; }; "blockDefinitions": { "alias": "blockDefinitions"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+export { BlockDefinitionsRegistry, BlockDescriptionSchema, BlockDirective, BlockLoaderService, BlockRegistryImpl, ComponentRegistry, GuardRegistry, RegistryMetadataStore, RouteLoader, ServiceRegistry, buildComputedForTemplate, classifyTwoWayString, createOutputHandler, deepMergeBlockDefinition, extractReadonlyRefs, getRefPathFromReadonly, getRefValue, isBlockReference, isIdReference, isInvalidTwoWayMix, isOutputReference, isTwoWayRefString, normalizeServices, parseBlockDescription, parseRefPath, parseTwoWayRef, resolveBlockReference, resolveOutputReference, resolveRefPath, safeParseBlockDescription, setRefValue };
+export type { AllRegistryMetadata, BlockDescription, BlockInstanceHandle, BlockLoadOptions, BlockLoadResult, BlockReference, BlockRegistry, GuardLoader, GuardOrLoader, GuardOrType, OutputReference, ParsedRefPath, RegistryEntryType, RegistryMetadataRecord, ResolverContext, RouteConfig, ServiceEntry };