@ng-render/angular 0.1.0

package/types/ng-render-angular.d.ts

@@ -0,0 +1,537 @@
+import * as _json_render_core from '@json-render/core';
+import { Catalog, InferCatalogActions, InferActionParams, StateModel, InferCatalogComponents, InferComponentProps, UIElement, ActionHandler, VisibilityContext, VisibilityCondition, ResolvedAction, ActionBinding, ValidationResult, ValidationFunction, ValidationConfig, Spec, JsonPatch, FlatElement } from '@json-render/core';
+export { ActionBinding, Catalog, FlatElement, JsonPatch, Spec, StateModel, UIElement, VisibilityCondition, defineCatalog } from '@json-render/core';
+import * as i0 from '@angular/core';
+import { Type, InjectionToken, EnvironmentProviders, OnDestroy, ViewContainerRef, Signal } from '@angular/core';
+
+/**
+ * The schema for @ng-render/angular.
+ *
+ * Identical to the React schema — the schema is framework-agnostic.
+ */
+declare const schema: _json_render_core.Schema<{
+    spec: _json_render_core.SchemaType<"object", {
+        root: _json_render_core.SchemaType<"string", unknown>;
+        elements: _json_render_core.SchemaType<"record", _json_render_core.SchemaType<"object", {
+            type: _json_render_core.SchemaType<"ref", string>;
+            props: _json_render_core.SchemaType<"propsOf", string>;
+            children: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+            visible: _json_render_core.SchemaType<"any", unknown>;
+        }>>;
+    }>;
+    catalog: _json_render_core.SchemaType<"object", {
+        components: _json_render_core.SchemaType<"map", {
+            props: _json_render_core.SchemaType<"zod", unknown>;
+            slots: _json_render_core.SchemaType<"array", _json_render_core.SchemaType<"string", unknown>>;
+            description: _json_render_core.SchemaType<"string", unknown>;
+            example: _json_render_core.SchemaType<"any", unknown>;
+        }>;
+        actions: _json_render_core.SchemaType<"map", {
+            params: _json_render_core.SchemaType<"zod", unknown>;
+            description: _json_render_core.SchemaType<"string", unknown>;
+        }>;
+    }>;
+}>;
+type AngularSchema = typeof schema;
+
+/**
+ * State setter function for updating application state.
+ */
+type SetState = (updater: (prev: Record<string, unknown>) => Record<string, unknown>) => void;
+/**
+ * Handle returned by the `on()` function for a specific event.
+ */
+interface EventHandle {
+    emit: () => void;
+    shouldPreventDefault: boolean;
+    bound: boolean;
+}
+/**
+ * Context passed to Angular component render functions via defineRegistry.
+ */
+interface ComponentRenderContext<P = Record<string, unknown>> {
+    props: P;
+    emit: (event: string) => void;
+    on: (event: string) => EventHandle;
+    bindings?: Record<string, string>;
+    loading?: boolean;
+}
+/**
+ * Type-safe component render context for a specific catalog component.
+ */
+interface CatalogComponentContext<C extends Catalog, K extends keyof InferCatalogComponents<C>> extends ComponentRenderContext<InferComponentProps<C, K>> {
+}
+/**
+ * Action handler function type.
+ */
+type ActionFn<C extends Catalog, K extends keyof InferCatalogActions<C>> = (params: InferActionParams<C, K> | undefined, setState: SetState, state: StateModel) => Promise<void>;
+/**
+ * Registry of all action handlers for a catalog.
+ */
+type Actions<C extends Catalog> = {
+    [K in keyof InferCatalogActions<C>]: ActionFn<C, K>;
+};
+/**
+ * True when the catalog declares at least one action.
+ */
+type CatalogHasActions<C extends Catalog> = [
+    InferCatalogActions<C>
+] extends [never] ? false : [keyof InferCatalogActions<C>] extends [never] ? false : true;
+
+/**
+ * Maps element type names to Angular component classes.
+ */
+type ComponentRegistry = Record<string, Type<any>>;
+/**
+ * Interface that renderable Angular components should implement.
+ * All inputs are set via ComponentRef.setInput().
+ */
+interface JsonRenderComponent<P = Record<string, unknown>> {
+    element: UIElement<string, P>;
+    emit: (event: string) => void;
+    on: (event: string) => EventHandle;
+    bindings?: Record<string, string>;
+    loading?: boolean;
+}
+
+declare const NG_RENDER_REGISTRY: InjectionToken<ComponentRegistry>;
+declare const NG_RENDER_ACTION_HANDLERS: InjectionToken<Record<string, ActionHandler>>;
+declare const NG_RENDER_NAVIGATE: InjectionToken<(path: string) => void>;
+declare const NG_RENDER_FALLBACK: InjectionToken<Type<any>>;
+
+/**
+ * Result from defineRegistry.
+ */
+interface DefineRegistryResult {
+    registry: ComponentRegistry;
+    handlers: (getSetState: () => SetState | undefined, getState: () => StateModel) => Record<string, (params: Record<string, unknown>) => Promise<void>>;
+    executeAction: (actionName: string, params: Record<string, unknown> | undefined, setState: SetState, state?: StateModel) => Promise<void>;
+}
+/**
+ * Options for defineRegistry. Actions are required when the catalog declares them.
+ */
+type DefineRegistryOptions<C extends Catalog> = {
+    components?: Record<string, Type<any>>;
+} & (CatalogHasActions<C> extends true ? {
+    actions: Actions<C>;
+} : {
+    actions?: Actions<C>;
+});
+/**
+ * Create a type-safe registry from a catalog.
+ * Maps component names to Angular component classes.
+ */
+declare function defineRegistry<C extends Catalog>(_catalog: C, options: DefineRegistryOptions<C>): DefineRegistryResult;
+/**
+ * Options for provideNgRender.
+ */
+interface ProvideNgRenderOptions {
+    registry: ComponentRegistry;
+    handlers?: Record<string, ActionHandler>;
+    navigate?: (path: string) => void;
+    fallback?: Type<any>;
+}
+/**
+ * Provide ng-render configuration at the environment level.
+ * Replaces React's <JSONUIProvider>.
+ */
+declare function provideNgRender(options: ProvideNgRenderOptions): EnvironmentProviders;
+
+declare class SpecStateService {
+    private readonly _state;
+    readonly state: i0.Signal<StateModel>;
+    get(path: string): unknown;
+    set(path: string, value: unknown): void;
+    update(updates: Record<string, unknown>): void;
+    initialize(initialState: StateModel): void;
+    mergeInitialState(state: StateModel): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<SpecStateService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<SpecStateService>;
+}
+
+declare class VisibilityService {
+    private readonly stateService;
+    readonly ctx: i0.Signal<VisibilityContext>;
+    isVisible(condition: VisibilityCondition | undefined): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<VisibilityService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<VisibilityService>;
+}
+
+interface PendingConfirmation {
+    action: ResolvedAction;
+    handler: ActionHandler;
+    resolve: () => void;
+    reject: () => void;
+}
+declare class ActionDispatcherService {
+    private readonly stateService;
+    private readonly handlers;
+    private readonly navigate;
+    readonly loadingActions: i0.WritableSignal<Set<string>>;
+    readonly pendingConfirmation: i0.WritableSignal<PendingConfirmation | null>;
+    execute(binding: ActionBinding): Promise<void>;
+    confirm(): void;
+    cancel(): void;
+    private executeHandler;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ActionDispatcherService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ActionDispatcherService>;
+}
+
+interface FieldValidationState {
+    touched: boolean;
+    validated: boolean;
+    result: ValidationResult | null;
+}
+declare class ValidationService {
+    private readonly stateService;
+    private customFunctions;
+    private fieldConfigs;
+    readonly fieldStates: i0.WritableSignal<Record<string, FieldValidationState>>;
+    setCustomFunctions(fns: Record<string, ValidationFunction>): void;
+    registerField(path: string, config: ValidationConfig): void;
+    validate(path: string, config: ValidationConfig): ValidationResult;
+    touch(path: string): void;
+    clear(path: string): void;
+    validateAll(): boolean;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ValidationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ValidationService>;
+}
+
+declare class RepeatScopeService {
+    item: unknown;
+    index: number;
+    basePath: string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RepeatScopeService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RepeatScopeService>;
+}
+
+declare class JsonRendererComponent {
+    readonly spec: i0.InputSignal<Spec | null>;
+    readonly loading: i0.InputSignal<boolean>;
+    readonly initialState: i0.InputSignal<StateModel>;
+    readonly onStateChange: i0.InputSignal<((path: string, value: unknown) => void) | undefined>;
+    private readonly stateService;
+    private previousSpecState;
+    private previousInitialState;
+    readonly rootElement: i0.Signal<_json_render_core.UIElement<string, Record<string, unknown>> | null>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<JsonRendererComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<JsonRendererComponent, "json-renderer", never, { "spec": { "alias": "spec"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "initialState": { "alias": "initialState"; "required": false; "isSignal": true; }; "onStateChange": { "alias": "onStateChange"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+declare class ElementRendererComponent implements OnDestroy {
+    readonly element: i0.InputSignal<UIElement<string, Record<string, unknown>>>;
+    readonly spec: i0.InputSignal<Spec>;
+    readonly loading: i0.InputSignal<boolean>;
+    private readonly vcr;
+    private readonly injector;
+    private readonly envInjector;
+    private readonly stateService;
+    private readonly visibilityService;
+    private readonly actionDispatcher;
+    private readonly repeatScope;
+    private readonly registry;
+    private readonly fallbackComponent;
+    private componentRef;
+    private childRenderers;
+    private repeatInjectors;
+    constructor();
+    private render;
+    private renderRepeat;
+    private renderChildren;
+    private cleanup;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ElementRendererComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ElementRendererComponent, "jr-element-renderer", never, { "element": { "alias": "element"; "required": true; "isSignal": true; }; "spec": { "alias": "spec"; "required": true; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Directive that marks where children should be rendered inside a
+ * registered component.
+ *
+ * Usage in component templates:
+ * ```html
+ * <div class="card">
+ *   <ng-template jrChildren></ng-template>
+ * </div>
+ * ```
+ */
+declare class ChildrenOutletDirective {
+    readonly vcr: ViewContainerRef;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ChildrenOutletDirective, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<ChildrenOutletDirective, "[jrChildren]", ["jrChildren"], {}, {}, never, never, true, never>;
+}
+
+/**
+ * Default confirmation dialog component.
+ * Renders when an action has a `confirm` field.
+ *
+ * Place inside or near the `<json-renderer>` in your template:
+ * ```html
+ * <json-renderer [spec]="spec">
+ *   <jr-confirm-dialog />
+ * </json-renderer>
+ * ```
+ *
+ * Or use it standalone anywhere the ActionDispatcherService is available.
+ */
+declare class ConfirmDialogComponent {
+    private readonly dispatcher;
+    readonly confirm: i0.Signal<_json_render_core.ActionConfirm | null>;
+    onConfirm(): void;
+    onCancel(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ConfirmDialogComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<ConfirmDialogComponent, "jr-confirm-dialog", never, {}, {}, never, never, true, never>;
+}
+
+/**
+ * Default fallback component for unknown element types.
+ * Displays a warning in development.
+ *
+ * Register via provideNgRender:
+ * ```ts
+ * provideNgRender({
+ *   registry: myRegistry,
+ *   fallback: FallbackComponent,
+ * })
+ * ```
+ */
+declare class FallbackComponent {
+    readonly element: i0.InputSignal<UIElement<string, Record<string, unknown>>>;
+    readonly emit: i0.InputSignal<(event: string) => void>;
+    readonly on: i0.InputSignal<(event: string) => EventHandle>;
+    readonly bindings: i0.InputSignal<Record<string, string> | undefined>;
+    readonly loading: i0.InputSignal<boolean>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FallbackComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<FallbackComponent, "jr-fallback", never, { "element": { "alias": "element"; "required": true; "isSignal": true; }; "emit": { "alias": "emit"; "required": true; "isSignal": true; }; "on": { "alias": "on"; "required": true; "isSignal": true; }; "bindings": { "alias": "bindings"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Token usage metadata from AI generation.
+ */
+interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * Apply an RFC 6902 JSON patch to a Spec.
+ * Returns a new shallow-copied Spec (immutable pattern for signal updates).
+ */
+declare function applyPatch(spec: Spec, patch: JsonPatch): Spec;
+
+/**
+ * Options for createUIStream.
+ */
+interface UIStreamOptions {
+    api: string;
+    onComplete?: (spec: Spec) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for createUIStream.
+ */
+interface UIStreamState {
+    spec: Signal<Spec | null>;
+    isStreaming: Signal<boolean>;
+    error: Signal<Error | null>;
+    usage: Signal<TokenUsage | null>;
+    rawLines: Signal<string[]>;
+    send: (prompt: string, context?: Record<string, unknown>) => Promise<void>;
+    clear: () => void;
+    destroy: () => void;
+}
+/**
+ * Create a streaming UI generator.
+ * Angular equivalent of React's `useUIStream` hook.
+ *
+ * Returns signal-based reactive state + imperative send/clear functions.
+ *
+ * @example
+ * ```ts
+ * // In a component
+ * private stream = createUIStream({ api: '/api/generate' });
+ * spec = this.stream.spec;
+ * isStreaming = this.stream.isStreaming;
+ *
+ * async generate() {
+ *   await this.stream.send('Create a dashboard');
+ * }
+ *
+ * ngOnDestroy() {
+ *   this.stream.destroy();
+ * }
+ * ```
+ */
+declare function createUIStream(options: UIStreamOptions): UIStreamState;
+
+/**
+ * A single message in the chat.
+ */
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    text: string;
+    spec: Spec | null;
+}
+/**
+ * Options for createChatUI.
+ */
+interface ChatUIOptions {
+    api: string;
+    onComplete?: (message: ChatMessage) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Return type for createChatUI.
+ */
+interface ChatUIState {
+    messages: Signal<ChatMessage[]>;
+    isStreaming: Signal<boolean>;
+    error: Signal<Error | null>;
+    send: (text: string) => Promise<void>;
+    clear: () => void;
+    destroy: () => void;
+}
+/**
+ * Create a chat + GenUI interface.
+ * Angular equivalent of React's `useChatUI` hook.
+ *
+ * Manages a multi-turn conversation where each assistant message can contain
+ * both conversational text and a json-render UI spec.
+ *
+ * @example
+ * ```ts
+ * private chat = createChatUI({ api: '/api/chat' });
+ * messages = this.chat.messages;
+ * isStreaming = this.chat.isStreaming;
+ *
+ * async send(text: string) {
+ *   await this.chat.send(text);
+ * }
+ *
+ * ngOnDestroy() {
+ *   this.chat.destroy();
+ * }
+ * ```
+ */
+declare function createChatUI(options: ChatUIOptions): ChatUIState;
+
+/**
+ * Return type for createBoundProp.
+ */
+interface BoundProp<T> {
+    value: T | undefined;
+    setValue: (value: T) => void;
+}
+/**
+ * Create a two-way bound prop helper.
+ * Angular equivalent of React's `useBoundProp` hook.
+ *
+ * Must be called within an injection context (constructor, factory, etc.)
+ * where SpecStateService is available.
+ *
+ * @example
+ * ```ts
+ * // In a component that receives bindings
+ * private stateService = inject(SpecStateService);
+ *
+ * // Create bound prop for a form input
+ * get emailBinding(): BoundProp<string> {
+ *   return boundProp(
+ *     this.element().props['value'] as string,
+ *     this.bindings()?.['value'],
+ *     this.stateService,
+ *   );
+ * }
+ *
+ * onInput(event: Event) {
+ *   this.emailBinding.setValue((event.target as HTMLInputElement).value);
+ * }
+ * ```
+ */
+declare function boundProp<T>(propValue: T | undefined, bindingPath: string | undefined, stateService: SpecStateService): BoundProp<T>;
+/**
+ * Create a two-way bound prop helper using dependency injection.
+ * Convenience wrapper that injects SpecStateService automatically.
+ *
+ * Must be called within an injection context.
+ *
+ * @example
+ * ```ts
+ * // In a component constructor or field initializer
+ * private createBound = injectBoundProp();
+ *
+ * get emailBinding() {
+ *   return this.createBound(
+ *     this.element().props['value'] as string,
+ *     this.bindings()?.['value'],
+ *   );
+ * }
+ * ```
+ */
+declare function injectBoundProp(): <T>(propValue: T | undefined, bindingPath: string | undefined) => BoundProp<T>;
+
+/**
+ * A single part from the AI SDK's `message.parts` array.
+ * Minimal structural type so the library doesn't depend on the AI SDK.
+ */
+interface DataPart {
+    type: string;
+    text?: string;
+    data?: unknown;
+}
+/**
+ * Build a Spec by replaying all spec data parts from a message's parts array.
+ * Returns null if no spec data parts are present.
+ *
+ * Works with the AI SDK's UIMessage.parts array.
+ *
+ * @example
+ * ```ts
+ * const spec = buildSpecFromParts(message.parts);
+ * if (spec) {
+ *   // render with <json-renderer [spec]="spec" />
+ * }
+ * ```
+ */
+declare function buildSpecFromParts(parts: DataPart[]): Spec | null;
+/**
+ * Extract and join all text content from a message's parts array.
+ *
+ * @example
+ * ```ts
+ * const text = getTextFromParts(message.parts);
+ * ```
+ */
+declare function getTextFromParts(parts: DataPart[]): string;
+/**
+ * Convert a flat element list to a Spec.
+ * Input elements use key/parentKey to establish identity and relationships.
+ *
+ * @example
+ * ```ts
+ * const spec = flatToTree([
+ *   { key: 'root', type: 'Stack', props: {}, children: [] },
+ *   { key: 'text', parentKey: 'root', type: 'Text', props: { content: 'Hello' } },
+ * ]);
+ * ```
+ */
+declare function flatToTree(elements: FlatElement[]): Spec;
+/**
+ * Extract both spec and text from message parts.
+ * Combines buildSpecFromParts and getTextFromParts.
+ *
+ * @example
+ * ```ts
+ * const { spec, text, hasSpec } = extractFromParts(message.parts);
+ * ```
+ */
+declare function extractFromParts(parts: DataPart[]): {
+    spec: Spec | null;
+    text: string;
+    hasSpec: boolean;
+};
+
+export { ActionDispatcherService, ChildrenOutletDirective, ConfirmDialogComponent, ElementRendererComponent, FallbackComponent, JsonRendererComponent, NG_RENDER_ACTION_HANDLERS, NG_RENDER_FALLBACK, NG_RENDER_NAVIGATE, NG_RENDER_REGISTRY, RepeatScopeService, SpecStateService, ValidationService, VisibilityService, applyPatch, boundProp, buildSpecFromParts, createChatUI, createUIStream, defineRegistry, extractFromParts, flatToTree, getTextFromParts, injectBoundProp, provideNgRender, schema };
+export type { ActionFn, Actions, AngularSchema, BoundProp, CatalogComponentContext, CatalogHasActions, ChatMessage, ChatUIOptions, ChatUIState, ComponentRegistry, ComponentRenderContext, DataPart, DefineRegistryResult, EventHandle, FieldValidationState, JsonRenderComponent, PendingConfirmation, ProvideNgRenderOptions, SetState, TokenUsage, UIStreamOptions, UIStreamState };