@ngx-formbar/core 0.11.0

package/lib/composables/validators.d.ts

@@ -0,0 +1,22 @@
+import { Signal } from '@angular/core';
+import { NgxFbAbstractControl } from '../types/content.type';
+/**
+ * Computes a reactive array of validators based on control content
+ *
+ * Extracts validator keys from content and maps them to actual validator functions
+ * by looking them up in the validator registration service.
+ *
+ * @param content Signal containing control configuration with validator keys
+ * @returns Computed signal that resolves to an array of validator functions
+ */
+export declare function withValidators(content: Signal<NgxFbAbstractControl>): Signal<import("@angular/forms").ValidatorFn[]>;
+/**
+ * Computes a reactive array of async validators based on control content
+ *
+ * Extracts async validator keys from content and maps them to actual async validator
+ * functions by looking them up in the validator registration service.
+ *
+ * @param content Signal containing control configuration with async validator keys
+ * @returns Computed signal that resolves to an array of async validator functions
+ */
+export declare function withAsyncValidators(content: Signal<NgxFbAbstractControl>): Signal<import("@angular/forms").AsyncValidatorFn[]>;

package/lib/config/config.d.ts

@@ -0,0 +1,7 @@
+import { RegistrationRecord } from '../types/validation.type';
+import { FormbarConfig } from '../types/provide.type';
+/**
+ * Type helper to make it easier to use formbar.config.ts
+ * accepts a direct {@link FormbarConfig} object
+ */
+export declare function defineFormbarConfig<S extends RegistrationRecord, A extends RegistrationRecord>(config: FormbarConfig<S, A>): FormbarConfig<S, A>;

package/lib/config/provide-formbar.d.ts

@@ -0,0 +1,38 @@
+import { EnvironmentProviders } from '@angular/core';
+import { RegistrationRecord } from '../types/validation.type';
+import { FormbarConfig } from '../types/provide.type';
+/**
+ * Configures and provides ngx-formbar to your application.
+ *
+ * This function is used in app.config.ts to register form components, validators,
+ * and set global configuration for the formbar library.
+ *
+ * @param config Configuration object for ngx-formbar:
+ *   - componentRegistrations: Optional mapping of control types to component implementations
+ *   - validatorRegistrations: Optional mapping of validator names to validator functions
+ *     (Angular's required, requiredTrue, email, and nullValidator are registered by default)
+ *   - asyncValidatorRegistrations: Optional mapping of async validator names to async validator functions
+ *   - updateOn: Optional default update strategy for all form controls
+ *   - globalConfig: Optional global configuration settings
+ *
+ * @returns Angular environment providers to be included in application configuration
+ *
+ * @example
+ * ```ts
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideFormbar({
+ *       componentRegistrations: {
+ *         text: TextInputComponent,
+ *         select: SelectComponent,
+ *       },
+ *       validatorRegistrations: {
+ *         customValidator: [myCustomValidator]
+ *       }
+ *     })
+ *   ]
+ * };
+ * ```
+ */
+export declare function provideFormbar<S extends RegistrationRecord, A extends RegistrationRecord>(config?: FormbarConfig<S, A>): EnvironmentProviders;

package/lib/directives/ngxfb-abstract-control.directive.d.ts

@@ -0,0 +1,53 @@
+import { NgxFbBaseContent } from '../types/content.type';
+import * as i0 from "@angular/core";
+/**
+ * Structural directive that renders the appropriate component based on the control's type.
+ *
+ * This directive acts as a dynamic renderer for form controls, blocks, and groups.
+ * It works by:
+ * 1. Receiving a content configuration and name
+ * 2. Looking up the registered component for the content's type
+ * 3. Creating an instance of that component and binding the content and name to it
+ *
+ * This allows forms to be composed declaratively through configuration objects
+ * rather than explicit templates.
+ *
+ * @example
+ * ```html
+ * <!-- Used with ngFor to render a list of controls -->
+ * @for (control of controls(); track control[0]) {
+ *   <ng-template *ngxfbAbstractControl="control" />
+ * }
+ *
+ * <!-- Used directly with a specific control -->
+ * <ng-template *ngxfbAbstractControl="['name', nameControlConfig]" />
+ * ```
+ */
+export declare class NgxfbAbstractControlDirective<T extends NgxFbBaseContent> {
+    private viewContainerRef;
+    /**
+     * Service for component registration
+     * Provides access to component type mappings
+     */
+    private readonly contentRegistrationService;
+    /**
+     * Required input for control configuration
+     * Defines properties like type, validation, and other control-specific settings
+     */
+    readonly content: import("@angular/core").InputSignal<[string, T]>;
+    readonly controlName: import("@angular/core").Signal<string>;
+    readonly controlConfig: import("@angular/core").Signal<T>;
+    /**
+     * Registration map of component types
+     * Maps control types to component implementations
+     */
+    readonly registrations: import("@angular/core").Signal<ReadonlyMap<string, import("@angular/core").Type<unknown>>>;
+    /**
+     * Computed component type based on content.type
+     * Looks up the component implementation from registrations map
+     */
+    readonly component: import("@angular/core").Signal<import("@angular/core").Type<unknown> | null>;
+    constructor();
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxfbAbstractControlDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxfbAbstractControlDirective<any>, "[ngxfbAbstractControl]", never, { "content": { "alias": "ngxfbAbstractControl"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}

package/lib/directives/ngxfb-block.directive.d.ts

@@ -0,0 +1,124 @@
+import { ControlContainer } from '@angular/forms';
+import { StateHandling } from '../types/registration.type';
+import { TestIdBuilderFn } from '../types/functions.type';
+import { NgxFbBaseContent } from '../types/content.type';
+import * as i0 from "@angular/core";
+/**
+ * Core directive for non-form elements that appear in forms.
+ *
+ * Block elements represent UI components that don't contribute to the form's value
+ * but provide information or functionality within forms, such as:
+ * - Information blocks
+ * - Images
+ * - Dividers
+ * - Help text
+ * - Custom UI elements
+ *
+ * This directive handles visibility conditions and test ID generation for block elements.
+ *
+ * Use this directive with hostDirectives in your custom block components:
+ *
+ * ```typescript
+ * @Component({
+ *   hostDirectives: [
+ *     {
+ *       directive: NgxfbBlockDirective,
+ *       inputs: ['content', 'name'],
+ *     }
+ *   ],
+ * })
+ * export class InfoBlockComponent {
+ *   private readonly blockDirective = inject(NgxfbBlockDirective<InfoBlock>);
+ *   readonly content = this.blockDirective.content;
+ *   readonly message = computed(() => this.content().message);
+ * }
+ * ```
+ *
+ * @template T Type of the block configuration, must extend NgxFbBaseContent
+ */
+export declare class NgxfbBlockDirective<T extends NgxFbBaseContent> {
+    /**
+     * Reference to the parent form container.
+     * Provides access to the form that contains this block.
+     */
+    private parentContainer;
+    /**
+     * Required input containing the block configuration.
+     * Defines properties like type, hidden condition, and custom properties.
+     */
+    readonly content: import("@angular/core").InputSignal<T>;
+    /**
+     * Required input for the block's name.
+     * Used as an identifier within the form.
+     */
+    readonly name: import("@angular/core").InputSignal<string>;
+    /**
+     * Signal for managing the visibility handling strategy ('auto' or 'manual').
+     * - 'auto': directive handles visibility via hidden attribute
+     * - 'manual': component handles visibility in its own template
+     */
+    private readonly visibilityHandling;
+    /**
+     * Signal for the test ID builder function.
+     * Used to customize how test IDs are generated.
+     */
+    private readonly testIdBuilder;
+    /**
+     * Computed test ID derived from the block's name.
+     * Used for automated testing identification.
+     *
+     * Access this in your component template:
+     * ```html
+     * <div [attr.data-testid]="testId()">...</div>
+     * ```
+     */
+    readonly testId: import("@angular/core").Signal<string>;
+    /**
+     * Computed signal for the hidden state.
+     * True when the block should be hidden based on 'hidden' expression.
+     *
+     * Use this in your component when implementing custom visibility handling:
+     * ```typescript
+     * readonly isHidden = this.blockDirective.isHidden;
+     * ```
+     */
+    readonly isHidden: import("@angular/core").Signal<boolean>;
+    /**
+     * Computed signal for the hidden attribute.
+     * Used in DOM binding to show/hide the block element.
+     */
+    readonly hiddenAttribute: import("@angular/core").Signal<true | null>;
+    /**
+     * Returns the parent form container.
+     * Provides access to the form instance that contains this block.
+     *
+     * Use this to access form data or methods:
+     * ```typescript
+     * const formData = this.blockDirective.rootForm.control.value;
+     * ```
+     */
+    get rootForm(): ControlContainer;
+    /**
+     * Sets the visibility handling strategy.
+     * Determines if visibility should be managed by the component (manual) or by Formbar (auto).
+     *
+     * Use 'manual' when implementing custom visibility handling in your component:
+     * ```typescript
+     * constructor() {
+     *   this.blockDirective.setVisibilityHandling('manual');
+     * }
+     * ```
+     *
+     * @param visibilityHandling Strategy for handling visibility ('auto' or 'manual')
+     */
+    setVisibilityHandling(visibilityHandling: StateHandling): void;
+    /**
+     * Sets the function to use for building a test id.
+     * This allows custom test ID generation strategies to be used.
+     *
+     * @param builderFn Function that returns the test id
+     */
+    setTestIdBuilderFn(builderFn: TestIdBuilderFn | undefined): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxfbBlockDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxfbBlockDirective<any>, "[ngxfbBlock]", never, { "content": { "alias": "content"; "required": true; "isSignal": true; }; "name": { "alias": "name"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}

package/lib/directives/ngxfb-control.directive.d.ts

@@ -0,0 +1,203 @@
+import { OnDestroy } from '@angular/core';
+import { NgxFbControl, ValueStrategy } from '../types/content.type';
+import { FormControl, FormGroup } from '@angular/forms';
+import { StateHandling } from '../types/registration.type';
+import { TestIdBuilderFn } from '../types/functions.type';
+import * as i0 from "@angular/core";
+/**
+ * Core directive for creating form controls in ngx-formbar.
+ *
+ * This directive handles the integration between Angular's reactive forms and
+ * ngx-formbar's declarative configuration. It manages:
+ *
+ * - Control registration and lifecycle within parent form groups
+ * - State management (hidden, disabled, readonly)
+ * - Validation setup
+ * - Dynamic value computation
+ * - Test ID generation
+ * - Dynamic label support
+ *
+ * Use this directive with hostDirectives in your custom control components:
+ *
+ * ```typescript
+ * @Component({
+ *   hostDirectives: [
+ *     {
+ *       directive: NgxfbControlDirective,
+ *       inputs: ['content', 'name'],
+ *     }
+ *   ],
+ * })
+ * export class TextControlComponent {
+ *   private readonly control = inject(NgxfbControlDirective<TextControl>);
+ *   readonly content = this.control.content;
+ *   readonly name = this.control.name;
+ * }
+ * ```
+ *
+ * @template T Type of the control configuration, must extend NgxFbControl
+ */
+export declare class NgxfbControlDirective<T extends NgxFbControl> implements OnDestroy {
+    private parentContainer;
+    private readonly parentGroupDirective;
+    /**
+     * Required input containing the control configuration
+     * Defines properties like ID, default value, validation, and state expressions
+     */
+    readonly content: import("@angular/core").InputSignal<T>;
+    /**
+     * Required input for the controls name
+     */
+    readonly name: import("@angular/core").InputSignal<string>;
+    private readonly visibilityHandling;
+    private readonly disabledHandling;
+    private readonly testIdBuilder;
+    /**
+     * Computed test ID derived from the control's ID
+     * Used for automated testing identification
+     *
+     * Access this in your component template:
+     * ```html
+     * <input [attr.data-testid]="testId()" ... />
+     * ```
+     */
+    readonly testId: import("@angular/core").Signal<string>;
+    /**
+     * Computed signal for the control's hide strategy
+     * Determines how the control behaves when hidden (keep or remove from form)
+     */
+    readonly hideStrategy: import("@angular/core").Signal<import("@ngx-formbar/core").HideStrategy | undefined>;
+    /**
+     * Computed signal for the control's value strategy
+     * Determines how the control's value is managed when visibility changes
+     */
+    readonly valueStrategy: import("@angular/core").Signal<ValueStrategy | undefined>;
+    /**
+     * Computed signal for the parent's value strategy
+     * Used when control doesn't define its own strategy
+     */
+    readonly parentValueStrategy: import("@angular/core").Signal<ValueStrategy | undefined>;
+    /**
+     * Computed signal for the hidden state
+     * True when the control should be hidden based on 'hidden' expression
+     *
+     * Use this in your component when implementing custom visibility handling:
+     * ```typescript
+     * readonly isHidden = this.control.isHidden;
+     * ```
+     */
+    readonly isHidden: import("@angular/core").Signal<boolean>;
+    /**
+     * Computed signal for the hidden attribute
+     * Used in DOM binding to show/hide the control element
+     */
+    readonly hiddenAttribute: import("@angular/core").Signal<true | null>;
+    /**
+     * Computed signal for the disabled state
+     * True when the control should be disabled based on 'disabled' expression
+     *
+     * Use this in your component for custom disabled state handling:
+     * ```typescript
+     * readonly disabled = this.control.disabled;
+     * ```
+     */
+    readonly disabled: import("@angular/core").Signal<boolean>;
+    /**
+     * Computed signal for the readonly state
+     * True when the control should be readonly based on 'readonly' expression
+     *
+     * Use this in your component to implement readonly behavior:
+     * ```html
+     * <input [attr.readonly]="readonly() || null" ... />
+     * ```
+     */
+    readonly readonly: import("@angular/core").Signal<boolean>;
+    /**
+     * Computed signal for the update strategy
+     * Determines when form values are updated ('change', 'blur', or 'submit')
+     */
+    readonly updateStrategy: import("@angular/core").Signal<import("@ngx-formbar/core").UpdateStrategy>;
+    /**
+     * Computed signal for the dynamic label
+     * Contains the evaluated result of the dynamicLabel expression
+     *
+     * Use this in your component to display dynamic labels:
+     * ```typescript
+     * readonly displayLabel = computed(() => {
+     *   const dynamic = this.control.dynamicLabel();
+     *   return dynamic || this.content().label;
+     * });
+     * ```
+     */
+    readonly dynamicLabel: import("@angular/core").Signal<string | undefined>;
+    /**
+     * Computed signal for the validators
+     * Contains validator functions derived from configuration keys
+     */
+    private readonly validators;
+    /**
+     * Computed signal for the async validators
+     * Contains async validator functions derived from configuration keys
+     */
+    private readonly asyncValidators;
+    /**
+     * Computed signal for the computed value
+     * Contains the evaluated result of computedValue expressions
+     */
+    private readonly computedValue;
+    /**
+     * Computed signal for the form control instance
+     * Creates a new FormControl with appropriate validators and configuration
+     */
+    private readonly controlInstance;
+    /**
+     * Access to the parent FormGroup containing this control
+     */
+    get parentFormGroup(): FormGroup | null;
+    /**
+     * Access to this control's FormControl instance
+     * Use this to access validation state, errors, and other FormControl methods
+     *
+     * Example:
+     * ```typescript
+     * get hasError() {
+     *   return this.control.formControl?.hasError('required');
+     * }
+     * ```
+     */
+    get formControl(): FormControl<any> | null;
+    constructor();
+    /**
+     * Sets the visibility handling strategy
+     * Determines if visibility should be managed by the component (manual) or by Formbar (auto)
+     *
+     * Use 'manual' when implementing custom visibility handling in your component:
+     * ```typescript
+     * constructor() {
+     *   this.control.setVisibilityHandling('manual');
+     * }
+     * @param visibilityHandling Strategy for handling visibility ('auto' or 'manual')
+     */
+    setVisibilityHandling(visibilityHandling: StateHandling): void;
+    /**
+     * Sets the disabled handling strategy
+     * Determines if disabled state should be managed by the component (manual) or by Formbar (auto)
+     *
+     * @param disabledHandling Strategy for handling disabled state ('auto' or 'manual')
+     */
+    setDisabledHandling(disabledHandling: StateHandling): void;
+    /**
+     * Sets the function to use for building a test id.
+     *
+     * @param builderFn Function that returns the test id
+     */
+    setTestIdBuilderFn(builderFn: TestIdBuilderFn | undefined): void;
+    private setControl;
+    private removeControl;
+    private enableControl;
+    private disableControl;
+    private handleValue;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxfbControlDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxfbControlDirective<any>, "[ngxfbControl]", never, { "content": { "alias": "content"; "required": true; "isSignal": true; }; "name": { "alias": "name"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}