@ng-forge/dynamic-forms 0.1.1 → 0.1.3

package/types/ng-forge-dynamic-forms-testing.d.ts

@@ -0,0 +1,565 @@
+import { Mock } from 'vitest';
+import { DynamicFormLogger, FieldDef, FormConfig, DynamicForm, ValidationMessages, FieldSignalContext } from '@ng-forge/dynamic-forms';
+import { ComponentFixture } from '@angular/core/testing';
+import { ValidationError, form, FieldTree } from '@angular/forms/signals';
+import * as _angular_core from '@angular/core';
+import { Injector, WritableSignal, Type } from '@angular/core';
+import { Observable } from 'rxjs';
+
+/**
+ * Creates a promise that resolves after the specified delay.
+ *
+ * Utility function for testing scenarios where you need to wait for
+ * asynchronous operations, animations, or timing-dependent behavior.
+ *
+ * @param ms - Delay in milliseconds (defaults to 0 for next tick)
+ * @returns Promise that resolves after the specified delay
+ *
+ * @example
+ * ```typescript
+ * // Wait for async operations in tests
+ * await delay(100);
+ * expect(component.isLoaded).toBe(true);
+ *
+ * // Wait for next tick (micro-task)
+ * await delay();
+ * fixture.detectChanges();
+ * ```
+ */
+declare function delay(ms?: number): Promise<void>;
+
+/**
+ * Mock logger with vitest spies for testing.
+ */
+interface MockLogger extends DynamicFormLogger {
+    debug: Mock;
+    info: Mock;
+    warn: Mock;
+    error: Mock;
+}
+/**
+ * Creates a mock logger with vitest spies for all methods.
+ * Useful for testing code that uses the logger.
+ */
+declare function createMockLogger(): MockLogger;
+/**
+ * Creates a silent logger that doesn't output anything.
+ * Useful for tests where logging output is not relevant.
+ */
+declare function createSilentLogger(): DynamicFormLogger;
+
+/**
+ * Configuration for creating a dynamic form test
+ */
+interface DynamicFormTestConfig {
+    config: FormConfig;
+    initialValue?: Record<string, unknown>;
+    registerTestFields?: boolean;
+}
+/**
+ * Result of creating a dynamic form test
+ */
+interface DynamicFormTestResult {
+    component: DynamicForm;
+    fixture: ComponentFixture<DynamicForm>;
+}
+/**
+ * Fluent API for building form configurations
+ */
+declare class FormConfigBuilder {
+    private fields;
+    field(field: FieldDef<any>): FormConfigBuilder;
+    inputField(key: string, props?: Record<string, unknown>): FormConfigBuilder;
+    requiredInputField(key: string, props?: Record<string, unknown>): FormConfigBuilder;
+    selectField(key: string, options: Array<{
+        value: string;
+        label: string;
+    }>, props?: Record<string, unknown>): FormConfigBuilder;
+    checkboxField(key: string, props?: Record<string, unknown>): FormConfigBuilder;
+    rowField(key: string, fields: FieldDef<any>[]): FormConfigBuilder;
+    groupField(key: string, fields: FieldDef<any>[]): FormConfigBuilder;
+    buttonField(key: string, props?: Record<string, unknown>): FormConfigBuilder;
+    pageField(key: string, fields: FieldDef<any>[], title?: string): FormConfigBuilder;
+    build(): FormConfig;
+}
+/**
+ * Utility class for testing dynamic forms
+ */
+declare class DynamicFormTestUtils {
+    /**
+     * Creates a new form config builder
+     */
+    static builder(): FormConfigBuilder;
+    /**
+     * Creates a dynamic form test setup with optional test field registration
+     */
+    static createTest(testConfig: DynamicFormTestConfig): Promise<DynamicFormTestResult>;
+    /**
+     * Registers common test field types including built-in types like page, row, group
+     * @internal
+     */
+    private static registerTestFields;
+    /**
+     * Waits for the dynamic form to initialize.
+     * Uses the initialized$ observable directly which has shareReplay for late subscribers.
+     * @param fixture - The component fixture
+     * @param timeoutMs - Maximum time to wait for initialization (default: 100ms)
+     */
+    static waitForInit(fixture: ComponentFixture<DynamicForm>, timeoutMs?: number): Promise<void>;
+    /**
+     * Waits for an element to appear in the DOM with retries
+     */
+    private static waitForElement;
+    /**
+     * Simulates user input on a field element
+     */
+    static simulateInput(fixture: ComponentFixture<DynamicForm>, selector: string, value: string): Promise<void>;
+    /**
+     * Simulates user blur on a field element
+     */
+    static simulateBlur(fixture: ComponentFixture<DynamicForm>, selector: string): Promise<void>;
+    /**
+     * Simulates user selection on a select element
+     */
+    static simulateSelect(fixture: ComponentFixture<DynamicForm>, selector: string, value: string): Promise<void>;
+    /**
+     * Simulates checkbox toggle
+     */
+    static simulateCheckbox(fixture: ComponentFixture<DynamicForm>, selector: string, checked: boolean): Promise<void>;
+    /**
+     * Simulates button click
+     */
+    static simulateButtonClick(fixture: ComponentFixture<DynamicForm>, selector: string): Promise<void>;
+    /**
+     * Gets the current form value from the component
+     */
+    static getFormValue(component: DynamicForm): Record<string, unknown> | undefined;
+    /**
+     * Gets validation errors from the component
+     */
+    static getFormErrors(component: DynamicForm): ValidationError[];
+    /**
+     * Checks if the form is valid
+     */
+    static isFormValid(component: DynamicForm): boolean;
+    /**
+     * Gets all field elements from the fixture
+     */
+    static getFieldElements(fixture: ComponentFixture<DynamicForm>, fieldType: string): NodeListOf<Element>;
+    /**
+     * Asserts that a field has a specific value
+     */
+    static assertFieldValue(fixture: ComponentFixture<DynamicForm>, fieldSelector: string, expectedValue: string): Promise<void>;
+    /**
+     * Asserts that the form has a specific value
+     */
+    static assertFormValue(component: DynamicForm, expectedValue: Record<string, unknown>): void;
+}
+
+/**
+ * Configuration for creating a test form injector with field signal context
+ */
+interface TestFieldContextConfig<TModel extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Parent injector to use. If not provided, uses an empty injector.
+     */
+    parentInjector?: Injector;
+    /**
+     * Initial value for the form. If not provided, uses an empty object.
+     */
+    initialValue?: Partial<TModel>;
+    /**
+     * Default values function. If not provided, returns the initial value.
+     */
+    defaultValues?: () => TModel;
+    /**
+     * Default validation messages for the form.
+     */
+    defaultValidationMessages?: ValidationMessages;
+    /**
+     * Custom value signal. If provided, this will be used instead of creating a new one.
+     */
+    valueSignal?: WritableSignal<Partial<TModel> | undefined>;
+    /**
+     * Custom form instance. If provided, this will be used instead of creating a new one.
+     */
+    form?: ReturnType<typeof form<TModel>>;
+}
+/**
+ * Creates a test injector with FIELD_SIGNAL_CONTEXT provided.
+ *
+ * This utility simplifies testing of mappers and components that inject FIELD_SIGNAL_CONTEXT.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const testInjector = createTestFormInjector();
+ *
+ * // With custom initial value
+ * const testInjector = createTestFormInjector({
+ *   initialValue: { username: 'test' }
+ * });
+ *
+ * // With validation messages
+ * const testInjector = createTestFormInjector({
+ *   defaultValidationMessages: { required: 'This field is required' }
+ * });
+ * ```
+ */
+declare function createTestFormInjector<TModel extends Record<string, unknown> = Record<string, unknown>>(config?: TestFieldContextConfig<TModel>): Injector;
+/**
+ * Runs a mapper function in a test injection context.
+ *
+ * This is a convenience wrapper that creates a test injector and runs the mapper
+ * function within it, returning the result.
+ *
+ * @example
+ * ```typescript
+ * // Test a mapper without context overrides
+ * const bindings = testMapper(() => mapValueField(fieldDef));
+ *
+ * // Test a mapper with custom context
+ * const bindings = testMapper(
+ *   () => mapValueField(fieldDef),
+ *   { initialValue: { username: 'test' } }
+ * );
+ *
+ * // Test a mapper with validation messages
+ * const bindings = testMapper(
+ *   () => mapValueField(fieldDef),
+ *   { defaultValidationMessages: { required: 'Required field' } }
+ * );
+ * ```
+ */
+declare function testMapper<T>(mapperFn: () => T, context?: TestFieldContextConfig<Record<string, unknown>>): T;
+/**
+ * Creates a field signal context for testing without creating an injector.
+ *
+ * Useful when you need to manually provide the context or test context creation logic.
+ *
+ * @example
+ * ```typescript
+ * const context = createTestFieldContext({
+ *   initialValue: { name: 'test' }
+ * });
+ *
+ * // Use in your own injector
+ * const injector = Injector.create({
+ *   providers: [
+ *     { provide: FIELD_SIGNAL_CONTEXT, useValue: context }
+ *   ]
+ * });
+ * ```
+ */
+declare function createTestFieldContext<TModel extends Record<string, unknown> = Record<string, unknown>>(config?: TestFieldContextConfig<TModel>): FieldSignalContext<TModel>;
+
+/**
+ * Simple form configuration interface for testing
+ */
+interface TestFormConfig$1 {
+    fields: FieldDef<any>[];
+}
+/**
+ * Configuration for creating a dynamic form test
+ */
+interface SimpleTestConfig<T = Record<string, unknown>> {
+    config: TestFormConfig$1;
+    initialValue?: T;
+}
+/**
+ * Result of creating a dynamic form test
+ */
+interface SimpleTestResult {
+    component: any;
+    fixture: any;
+}
+/**
+ * Fluent API for building form configurations using existing field structure
+ */
+declare class TestFormConfigBuilder<T = Record<string, unknown>> {
+    private fields;
+    field(field: FieldDef<any>): TestFormConfigBuilder<T>;
+    inputField(key: string, props?: Record<string, unknown>): TestFormConfigBuilder<T>;
+    requiredInputField(key: string, props?: Record<string, unknown>): TestFormConfigBuilder<T>;
+    checkboxField(key: string, props?: Record<string, unknown>): TestFormConfigBuilder<T>;
+    build(): TestFormConfig$1;
+}
+/**
+ * Simple utility class for testing dynamic forms
+ */
+declare class SimpleTestUtils {
+    /**
+     * Creates a new form config builder
+     */
+    static builder<T = Record<string, unknown>>(): TestFormConfigBuilder<T>;
+    /**
+     * Creates a simple test component - assumes TestBed is already configured
+     */
+    static createComponent<T = Record<string, unknown>>(config?: TestFormConfig$1, initialValue?: T): SimpleTestResult;
+    /**
+     * Waits for the dynamic form to initialize
+     */
+    static waitForInit(fixture: any): Promise<void>;
+    /**
+     * Simulates user input on a field element
+     */
+    static simulateInput(fixture: any, selector: string, value: string): Promise<void>;
+    /**
+     * Simulates checkbox toggle
+     */
+    static simulateCheckbox(fixture: any, selector: string, checked: boolean): Promise<void>;
+    /**
+     * Gets the current form value from the component
+     */
+    static getFormValue(component: any): Record<string, unknown> | undefined;
+    /**
+     * Checks if the form is valid
+     */
+    static isFormValid(component: any): boolean;
+    /**
+     * Asserts that the form has a specific value
+     */
+    static assertFormValue(component: any, expectedValue: Record<string, unknown>): void;
+}
+declare class TestFieldComponent {
+    value: _angular_core.WritableSignal<string>;
+    key: _angular_core.InputSignal<string>;
+    label: _angular_core.InputSignal<string>;
+    className: _angular_core.InputSignal<string>;
+    tabIndex: _angular_core.InputSignal<number | undefined>;
+    props: _angular_core.InputSignal<Record<string, unknown> | undefined>;
+    placeholder: _angular_core.InputSignal<string>;
+    fields: _angular_core.InputSignal<unknown[]>;
+    arrayContext: _angular_core.InputSignal<unknown>;
+    validationMessages: _angular_core.InputSignal<Record<string, string> | undefined>;
+    defaultValidationMessages: _angular_core.InputSignal<Record<string, string> | undefined>;
+    field: _angular_core.InputSignal<unknown>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TestFieldComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TestFieldComponent, "df-test-field", never, { "key": { "alias": "key"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "fields": { "alias": "fields"; "required": false; "isSignal": true; }; "arrayContext": { "alias": "arrayContext"; "required": false; "isSignal": true; }; "validationMessages": { "alias": "validationMessages"; "required": false; "isSignal": true; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; "field": { "alias": "field"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+/**
+ * Configuration for setting up a simple component test
+ */
+interface SimpleComponentTestConfig<T = any> {
+    field: FieldDef<any>;
+    value?: T;
+    pageIndex?: number;
+    isVisible?: boolean;
+    [key: string]: any;
+}
+/**
+ * Result of setting up a simple component test
+ */
+interface SimpleComponentTestResult<T = any> {
+    component: T;
+    fixture: ComponentFixture<T>;
+}
+/**
+ * Creates a simple test setup for individual field components
+ */
+declare function setupSimpleTest<T>(componentType: Type<T>, config: SimpleComponentTestConfig): SimpleComponentTestResult<T>;
+/**
+ * Creates a simple test field definition
+ */
+declare function createSimpleTestField(key: string, label: string): FieldDef<any>;
+
+/**
+ * Simple form configuration interface for testing
+ */
+interface TestFormConfig {
+    fields: FieldDef<any>[];
+}
+/**
+ * Unified configuration for creating dynamic form tests
+ * Replaces DynamicFormTestConfig and SimpleTestConfig
+ */
+interface TestConfig<T = Record<string, unknown>> {
+    config: FormConfig | TestFormConfig;
+    initialValue?: T;
+    registerTestFields?: boolean;
+}
+/**
+ * Unified result interface for dynamic form tests
+ * Replaces DynamicFormTestResult and SimpleTestResult
+ */
+interface TestResult<T = unknown> {
+    component: T;
+    fixture: ComponentFixture<T>;
+}
+/**
+ * Configuration for setting up individual field component tests
+ */
+interface ComponentTestConfig<T = unknown> {
+    field: FieldDef<any>;
+    value?: T;
+}
+/**
+ * Result of setting up individual field component tests
+ */
+interface ComponentTestResult<T = unknown> {
+    component: T;
+    fixture: ComponentFixture<T>;
+}
+
+declare class TestInputHarness {
+    readonly field: _angular_core.InputSignal<FieldTree<string>>;
+    readonly key: _angular_core.InputSignal<string>;
+    readonly label: _angular_core.InputSignal<string>;
+    readonly placeholder: _angular_core.InputSignal<string>;
+    readonly type: _angular_core.InputSignal<string>;
+    readonly props: _angular_core.InputSignal<Record<string, unknown>>;
+    readonly className: _angular_core.InputSignal<string>;
+    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
+    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TestInputHarness, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TestInputHarness, "df-test-input", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "validationMessages": { "alias": "validationMessages"; "required": false; "isSignal": true; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+declare class TestCheckboxHarness {
+    readonly field: _angular_core.InputSignal<FieldTree<boolean>>;
+    readonly key: _angular_core.InputSignal<string>;
+    readonly label: _angular_core.InputSignal<string>;
+    readonly props: _angular_core.InputSignal<Record<string, unknown>>;
+    readonly className: _angular_core.InputSignal<string>;
+    readonly validationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
+    readonly defaultValidationMessages: _angular_core.InputSignal<ValidationMessages | undefined>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TestCheckboxHarness, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TestCheckboxHarness, "df-test-checkbox", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "validationMessages": { "alias": "validationMessages"; "required": false; "isSignal": true; }; "defaultValidationMessages": { "alias": "defaultValidationMessages"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Test harness component for select fields
+ */
+declare class TestSelectHarness {
+    readonly field: _angular_core.InputSignal<FieldTree<string>>;
+    readonly key: _angular_core.InputSignal<string>;
+    readonly label: _angular_core.InputSignal<string>;
+    readonly options: _angular_core.InputSignal<{
+        value: string;
+        label: string;
+    }[]>;
+    readonly className: _angular_core.InputSignal<string>;
+    readonly tabIndex: _angular_core.InputSignal<number | undefined>;
+    readonly hidden: _angular_core.InputSignal<boolean>;
+    readonly readonly: _angular_core.InputSignal<boolean>;
+    readonly props: _angular_core.InputSignal<Record<string, unknown>>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<TestSelectHarness, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<TestSelectHarness, "df-test-select", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "key": { "alias": "key"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "className": { "alias": "className"; "required": false; "isSignal": true; }; "tabIndex": { "alias": "tabIndex"; "required": false; "isSignal": true; }; "hidden": { "alias": "hidden"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "props": { "alias": "props"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Fake translation service for testing dynamic text functionality.
+ * Provides Observable-based translation methods with language switching simulation.
+ *
+ * @example
+ * ```typescript
+ * TestBed.configureTestingModule({
+ *   providers: [
+ *     { provide: TranslationService, useClass: FakeTranslationService }
+ *   ]
+ * });
+ *
+ * const service = TestBed.inject(FakeTranslationService);
+ * service.setTranslations({
+ *   'form.username.label': 'Username',
+ *   'validation.required': 'This field is required'
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class FakeTranslationService {
+    private readonly translations;
+    private readonly currentLanguage;
+    /**
+     * Set the translation dictionary
+     */
+    setTranslations(translations: Record<string, string>): void;
+    /**
+     * Add translations to the existing dictionary
+     */
+    addTranslations(translations: Record<string, string>): void;
+    /**
+     * Simulate language change
+     */
+    setLanguage(language: string): void;
+    /**
+     * Get current language as signal
+     */
+    getLanguage(): _angular_core.WritableSignal<string>;
+    /**
+     * Translate a key and return an Observable
+     * Supports parameter interpolation using {{param}} syntax
+     */
+    translate(key: string, params?: Record<string, unknown>): Observable<string>;
+    /**
+     * Get instant translation (synchronous)
+     * Supports parameter interpolation using {{param}} syntax
+     */
+    instant(key: string, params?: Record<string, unknown>): string;
+    /**
+     * Simulate translation for validation errors
+     * Uses validation.${errorKind} pattern
+     */
+    translateValidationError(errorKind: string, params?: Record<string, unknown>): Observable<string>;
+    /**
+     * Get all current translations
+     */
+    getTranslations(): Record<string, string>;
+    /**
+     * Clear all translations
+     */
+    clearTranslations(): void;
+    private interpolateParams;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<FakeTranslationService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<FakeTranslationService>;
+}
+/**
+ * Default translations for common form fields and validation messages
+ * Useful for quick testing setup
+ */
+declare const DEFAULT_TEST_TRANSLATIONS: {
+    'form.username.label': string;
+    'form.email.label': string;
+    'form.password.label': string;
+    'form.firstName.label': string;
+    'form.lastName.label': string;
+    'form.phone.label': string;
+    'form.address.label': string;
+    'form.username.placeholder': string;
+    'form.email.placeholder': string;
+    'form.password.placeholder': string;
+    'validation.required': string;
+    'validation.email': string;
+    'validation.min': string;
+    'validation.max': string;
+    'validation.minLength': string;
+    'validation.maxLength': string;
+    'validation.pattern': string;
+    'buttons.submit': string;
+    'buttons.cancel': string;
+    'buttons.save': string;
+    'buttons.delete': string;
+    'buttons.edit': string;
+    greeting: string;
+    goodbye: string;
+};
+/**
+ * Alternative translations for testing language switching
+ */
+declare const SPANISH_TEST_TRANSLATIONS: {
+    'form.username.label': string;
+    'form.email.label': string;
+    'form.password.label': string;
+    'validation.required': string;
+    'validation.email': string;
+    greeting: string;
+    goodbye: string;
+};
+/**
+ * Test utility to create a configured FakeTranslationService with default translations
+ */
+declare function createTestTranslationService(initialTranslations?: Record<string, string>): FakeTranslationService;
+
+export { DEFAULT_TEST_TRANSLATIONS, DynamicFormTestUtils, FakeTranslationService, FormConfigBuilder, SPANISH_TEST_TRANSLATIONS, TestFormConfigBuilder as SimpleFormConfigBuilder, SimpleTestUtils, TestCheckboxHarness as TestCheckboxHarnessComponent, TestFieldComponent, TestInputHarness as TestInputHarnessComponent, TestSelectHarness as TestSelectHarnessComponent, createMockLogger, createSilentLogger, createSimpleTestField, createTestFieldContext, createTestFormInjector, createTestTranslationService, delay, setupSimpleTest, testMapper };
+export type { ComponentTestConfig, ComponentTestResult, DynamicFormTestConfig, DynamicFormTestResult, MockLogger, SimpleComponentTestConfig, SimpleComponentTestResult, SimpleTestConfig, SimpleTestResult, TestConfig, TestFieldContextConfig, TestFormConfig, TestResult };