@ngx-formbar/core 0.11.0

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

@@ -0,0 +1,253 @@
+import { OnDestroy, Signal } from '@angular/core';
+import { NgxFbFormGroup, 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 groups in ngx-formbar.
+ *
+ * This directive handles the integration between Angular's reactive forms and
+ * ngx-formbar's declarative configuration for FormGroups. It manages:
+ *
+ * - Group registration and lifecycle within parent forms
+ * - State management (hidden, disabled, readonly)
+ * - Validation setup
+ * - Test ID generation
+ * - Dynamic title support
+ * - Child control management
+ *
+ * Use this directive with hostDirectives in your custom group components:
+ *
+ * ```typescript
+ * @Component({
+ *   hostDirectives: [
+ *     {
+ *       directive: NgxfbGroupDirective,
+ *       inputs: ['content', 'name'],
+ *     }
+ *   ],
+ * })
+ * export class GroupComponent {
+ *   private readonly control = inject(NgxfbGroupDirective<Group>);
+ *   readonly content = this.control.content;
+ *   readonly controls = this.control.controls;
+ * }
+ * ```
+ *
+ * @template T Type of the group configuration, must extend NgxFbFormGroup
+ */
+export declare class NgxfbGroupDirective<T extends NgxFbFormGroup> implements OnDestroy {
+    private parentContainer;
+    private readonly parentGroupDirective;
+    /**
+     * Required input containing the group configuration
+     * Defines properties like type, controls, validation, and state expressions
+     */
+    readonly content: import("@angular/core").InputSignal<T>;
+    /**
+     * Required input for the group's name
+     * Used as the key in the parent FormGroup
+     */
+    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 managing the disabled state handling strategy ('auto' or 'manual')
+     * - 'auto': directive handles disabled state via FormGroup methods
+     * - 'manual': component handles disabled state in its own template
+     */
+    private readonly disabledHandling;
+    /**
+     * Signal for the test ID builder function
+     * Used to customize how test IDs are generated
+     */
+    private readonly testIdBuilder;
+    /**
+     * Computed test ID derived from the group's name
+     * Used for automated testing identification
+     *
+     * Access this in your component template:
+     * ```html
+     * <div [attr.data-testid]="testId()">...</div>
+     * ```
+     */
+    readonly testId: Signal<string>;
+    /**
+     * Computed signal for the group's hide strategy
+     * Determines how the group behaves when hidden (keep or remove from form)
+     */
+    readonly hideStrategy: Signal<import("@ngx-formbar/core").HideStrategy | undefined>;
+    /**
+     * Computed signal for the group's value strategy
+     * Determines how the group's values are managed when visibility changes:
+     * - 'last': preserves last values
+     * - 'default': reverts to default values
+     * - 'reset': clears values
+     */
+    readonly valueStrategy: Signal<ValueStrategy | undefined>;
+    /**
+     * Computed signal for the parent's value strategy
+     * Used when group doesn't define its own strategy
+     */
+    readonly parentValueStrategy: Signal<ValueStrategy | undefined>;
+    /**
+     * Computed signal for the hidden state
+     * True when the group 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: Signal<boolean>;
+    /**
+     * Computed signal for the hidden attribute
+     * Used in DOM binding to show/hide the group element
+     */
+    readonly hiddenAttribute: Signal<true | null>;
+    /**
+     * Computed signal for the disabled state
+     * True when the group 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: Signal<boolean>;
+    /**
+     * Computed signal for the readonly state
+     * True when the group should be readonly based on 'readonly' expression
+     *
+     * Use this in your component to implement readonly behavior:
+     * ```typescript
+     * readonly readonly = this.control.readonly;
+     * ```
+     */
+    readonly readonly: Signal<boolean>;
+    /**
+     * Computed signal for the update strategy
+     * Determines when form values are updated ('change', 'blur', or 'submit')
+     */
+    readonly updateStrategy: Signal<import("@ngx-formbar/core").UpdateStrategy>;
+    /**
+     * Computed signal for the dynamic title
+     * Contains the evaluated result of the dynamicTitle expression
+     *
+     * Use this in your component to display dynamic titles:
+     * ```typescript
+     * readonly displayTitle = computed(() => {
+     *   const dynamic = this.control.dynamicTitle();
+     *   return dynamic || this.content().title || '';
+     * });
+     * ```
+     */
+    readonly dynamicTitle: 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 form group instance
+     * Creates a new FormGroup with appropriate validators and configuration
+     */
+    private readonly groupInstance;
+    /**
+     * Computed signal for the title of the group
+     * Returns the static title from the configuration
+     */
+    readonly title: Signal<string | undefined>;
+    /**
+     * Computed signal for the child controls of the group
+     * Returns an array of [name, control] pairs for rendering
+     */
+    readonly controls: Signal<[string, import("@ngx-formbar/core").NgxFbContent][]>;
+    /**
+     * Access to the parent FormGroup containing this group
+     */
+    get parentFormGroup(): FormGroup | null;
+    /**
+     * Access to this group's FormGroup instance
+     * Use this to access validation state, errors, and other FormGroup methods
+     */
+    get formGroup(): FormControl | 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)
+     *
+     * Use 'manual' when implementing custom disabled state handling in your component:
+     * ```typescript
+     * constructor() {
+     *   this.control.setDisabledHandling('manual');
+     * }
+     * ```
+     *
+     * @param disabledHandling Strategy for handling disabled state ('auto' or 'manual')
+     */
+    setDisabledHandling(disabledHandling: 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;
+    /**
+     * Registers this group with the parent FormGroup
+     * @private
+     */
+    private setGroup;
+    /**
+     * Removes this group from the parent FormGroup
+     * @private
+     */
+    private removeGroup;
+    /**
+     * Enables the form group
+     * @private
+     */
+    private enableGroup;
+    /**
+     * Disables the form group
+     * @private
+     */
+    private disableGroup;
+    /**
+     * Handles value changes when visibility changes
+     * @param valueStrategy Strategy for handling values
+     * @private
+     */
+    private handleValue;
+    /**
+     * Removes the group when the directive is destroyed
+     */
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxfbGroupDirective<any>, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgxfbGroupDirective<any>, "[ngxfbGroup]", never, { "content": { "alias": "content"; "required": true; "isSignal": true; }; "name": { "alias": "name"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}

package/lib/helper/control-container-view-providers.d.ts

@@ -0,0 +1,33 @@
+import { ControlContainer } from '@angular/forms';
+/**
+ * Provides the parent ControlContainer to child components
+ *
+ * This provider configuration allows child form components to access their parent's
+ * ControlContainer through dependency injection. This is particularly useful for
+ * creating nested form components that inherit the parent form context without
+ * explicitly passing FormGroup instances.
+ *
+ * @remarks
+ * The `skipSelf` option ensures the provider looks for the ControlContainer in parent
+ * components rather than trying to resolve it from the component where this is used.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-child-form',
+ *   template: '...',
+ *   viewProviders: [controlContainerViewProviders]
+ * })
+ * export class ChildFormComponent {
+ *   // Now this component can access the parent form
+ *   private controlContainer = inject(ControlContainer);
+ *
+ *   get parentFormGroup() {
+ *     return this.parentContainer.control as FormGroup | null;
+ *   }
+ * }
+ */
+export declare const controlContainerViewProviders: {
+    provide: typeof ControlContainer;
+    useFactory: () => ControlContainer;
+}[];

package/lib/index.d.ts

@@ -0,0 +1,23 @@
+export * from './components/form/ngxfb-form.component';
+export * from './types/component-resolver.type';
+export * from './types/content.type';
+export * from './types/expression.type';
+export * from './types/form.type';
+export * from './types/functions.type';
+export * from './types/global-configuration.type';
+export * from './types/provide.type';
+export * from './types/registration.type';
+export * from './types/validation.type';
+export * from './types/validator-resolver.type';
+export * from './config/config';
+export * from './config/provide-formbar';
+export * from './directives/ngxfb-control.directive';
+export * from './directives/ngxfb-group.directive';
+export * from './directives/ngxfb-block.directive';
+export * from './directives/ngxfb-abstract-control.directive';
+export * from './tokens/component-registrations';
+export * from './tokens/component-resolver';
+export * from './tokens/default-update-strategy';
+export * from './tokens/global-config';
+export * from './tokens/validator-registrations';
+export * from './tokens/validator-resolver';

package/lib/services/component-registration.service.d.ts

@@ -0,0 +1,8 @@
+import { ComponentResolver } from '../types/component-resolver.type';
+import * as i0 from "@angular/core";
+export declare class ComponentRegistrationService implements ComponentResolver {
+    private readonly _registrations;
+    readonly registrations: import("@angular/core").Signal<ReadonlyMap<string, import("@angular/core").Type<unknown>>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ComponentRegistrationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ComponentRegistrationService>;
+}

package/lib/services/configuration.service.d.ts

@@ -0,0 +1,8 @@
+import { TestIdBuilderFn } from '../types/functions.type';
+import * as i0 from "@angular/core";
+export declare class NgxFbConfigurationService {
+    private readonly _config;
+    get testIdBuilder(): TestIdBuilderFn | undefined;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgxFbConfigurationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<NgxFbConfigurationService>;
+}

package/lib/services/expression.service.d.ts

@@ -0,0 +1,148 @@
+import type { Program } from 'acorn';
+import type { FormContext } from '../types/expression.type';
+import * as i0 from "@angular/core";
+/**
+ * Service for parsing and evaluating JavaScript expressions within a context object
+ */
+export declare class ExpressionService {
+    /**
+     * Cache for parsed ASTs to avoid re-parsing the same expression
+     */
+    private readonly astCache;
+    /**
+     * Parses an expression string into an abstract syntax tree (AST)
+     * @param expressionString - The expression to parse
+     * @returns The parsed AST or null
+     */
+    parseExpressionToAst(expressionString?: string): Program | null;
+    /**
+     * Evaluates an expression AST within the provided context
+     * @param ast - The parsed AST to evaluate
+     * @param context - The context containing variables and objects referenced in the expression
+     * @returns The result of evaluating the expression
+     */
+    evaluateExpression(ast?: Program | null, context?: FormContext): unknown;
+    /**
+     * Evaluates a node in the AST
+     * @param node - The AST node to evaluate
+     * @param context - The context containing variables and objects
+     * @returns The result of evaluating the node
+     */
+    private evaluateAstNode;
+    /**
+     * Evaluates a literal value node
+     * @param node - The literal node to evaluate
+     * @returns The literal value
+     */
+    private evaluateLiteral;
+    /**
+     * Evaluates a binary expression (e.g., a + b, x > y)
+     * @param node - The binary expression node
+     * @param context - The context containing variables and objects
+     * @returns The result of the binary operation
+     */
+    private evaluateBinaryExpression;
+    /**
+     * Executes a binary operation with the given values and operator
+     * @param leftValue - The left operand
+     * @param operator - The binary operator
+     * @param rightValue - The right operand
+     * @returns The result of applying the operator to the operands
+     */
+    private executeBinaryOperation;
+    /**
+     * Evaluates a member expression (e.g., obj.prop, arr[0]) with improved safety
+     * @param node - The member expression node
+     * @param context - The context containing variables and objects
+     * @returns The value of the member
+     */
+    private evaluateMemberExpression;
+    /**
+     * Gets a property from an object by key
+     * @param object - The object to retrieve the property from
+     * @param propertyKey - The property key (string or number)
+     * @returns The value of the property
+     */
+    private getPropertyFromObject;
+    /**
+     * Evaluates an identifier node by looking it up in the context
+     * @param node - The identifier node
+     * @param context - The context containing variables and objects
+     * @returns The value of the identifier from the context
+     */
+    private evaluateIdentifier;
+    /**
+     * Evaluates an array expression node
+     * @param node - The array expression node
+     * @param context - The context containing variables and objects
+     * @returns The evaluated array
+     */
+    private evaluateArrayExpression;
+    /**
+     * Evaluates a unary expression (e.g., !x, -value, typeof obj)
+     * @param node - The unary expression node
+     * @param context - The context containing variables and objects
+     * @returns The result of the unary operation
+     */
+    private evaluateUnaryExpression;
+    /**
+     * Evaluates a logical expression (&&, ||, ??)
+     * @param node - The logical expression node
+     * @param context - The context containing variables and objects
+     * @returns The result of the logical operation
+     */
+    private evaluateLogicalExpression;
+    /**
+     * Evaluates a conditional (ternary) expression (condition ? trueValue : falseValue)
+     * @param node - The conditional expression node
+     * @param context - The context containing variables and objects
+     * @returns The result based on the condition evaluation
+     */
+    private evaluateConditionalExpression;
+    /**
+     * Evaluates an object expression (object literal)
+     * @param node - The object expression node
+     * @param context - The context containing variables and objects
+     * @returns The evaluated object
+     */
+    private evaluateObjectExpression;
+    /**
+     * Evaluates a sequence expression (comma-separated expressions)
+     * @param node - The sequence expression node
+     * @param context - The context containing variables and objects
+     * @returns The result of the last expression in the sequence
+     */
+    private evaluateSequenceExpression;
+    /**
+     * Evaluates a template literal
+     * @param node - The template literal node
+     * @param context - The context containing variables and objects
+     * @returns The evaluated template string
+     */
+    private evaluateTemplateLiteral;
+    /**
+     * Evaluates a function call expression with strict type checking
+     * @param node - The function call expression node
+     * @param context - The context containing variables and objects
+     * @returns The result of the function call
+     */
+    private evaluateCallExpression;
+    /**
+     * Calls a method on an object after verifying it's safe to do so
+     * @param object - The object to call the method on
+     * @param methodName - The name of the method to call
+     * @param args - The arguments to pass to the method
+     * @returns The result of the method call
+     */
+    private callSafeMethod;
+    private isAllowedMethod;
+    /**
+     * Evaluates an arrow function expression
+     * @param node - The arrow function expression node
+     * @param context - The context containing variables and objects
+     * @returns A function that can be called from other expressions
+     */
+    private evaluateArrowFunctionExpression;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ExpressionService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ExpressionService>;
+}

package/lib/services/form.service.d.ts

@@ -0,0 +1,10 @@
+import { FormGroup } from '@angular/forms';
+import { FormContext } from '../types/expression.type';
+import * as i0 from "@angular/core";
+export declare class FormService {
+    private controlContainer;
+    readonly formGroup: FormGroup;
+    readonly formValue: import("@angular/core").Signal<FormContext | undefined>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FormService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FormService>;
+}

package/lib/services/validator-registration.service.d.ts

@@ -0,0 +1,10 @@
+import { ValidatorResolver } from '../types/validator-resolver.type';
+import * as i0 from "@angular/core";
+export declare class ValidatorRegistrationService implements ValidatorResolver {
+    private readonly _registrations;
+    readonly registrations: import("@angular/core").Signal<ReadonlyMap<string, import("@angular/forms").ValidatorFn[]>>;
+    private readonly _asyncRegistrations;
+    readonly asyncRegistrations: import("@angular/core").Signal<ReadonlyMap<string, import("@angular/forms").AsyncValidatorFn[]>>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<ValidatorRegistrationService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<ValidatorRegistrationService>;
+}

package/lib/tokens/component-registrations.d.ts

@@ -0,0 +1,2 @@
+import { InjectionToken, Type } from '@angular/core';
+export declare const NGX_FW_COMPONENT_REGISTRATIONS: InjectionToken<ReadonlyMap<string, Type<unknown>>>;

package/lib/tokens/component-resolver.d.ts

@@ -0,0 +1,3 @@
+import { InjectionToken } from '@angular/core';
+import { ComponentResolver } from '../types/component-resolver.type';
+export declare const NGX_FW_COMPONENT_RESOLVER: InjectionToken<ComponentResolver>;

package/lib/tokens/default-update-strategy.d.ts

@@ -0,0 +1,3 @@
+import { InjectionToken } from '@angular/core';
+import { UpdateStrategy } from '../types/content.type';
+export declare const NGX_FW_DEFAULT_UPDATE_STRATEGY: InjectionToken<UpdateStrategy>;

package/lib/tokens/global-config.d.ts

@@ -0,0 +1,5 @@
+import { InjectionToken } from '@angular/core';
+import { NgxFbGlobalConfiguration } from '../types/global-configuration.type';
+export declare const NGX_FW_DEFAULT_CONFIG: InjectionToken<NgxFbGlobalConfiguration>;
+export declare const NGX_FW_CONFIG: InjectionToken<readonly Partial<NgxFbGlobalConfiguration>[]>;
+export declare const NGX_FW_CONFIG_RESOLVED: InjectionToken<NgxFbGlobalConfiguration>;

package/lib/tokens/validator-registrations.d.ts

@@ -0,0 +1,8 @@
+import { InjectionToken } from '@angular/core';
+import { AsyncValidatorFn, ValidatorFn } from '@angular/forms';
+export declare const NGX_FW_DEFAULT_VALIDATOR_REGISTRATIONS: InjectionToken<ReadonlyMap<string, ValidatorFn[]>>;
+export declare const NGX_FW_DEFAULT_ASYNC_VALIDATOR_REGISTRATIONS: InjectionToken<ReadonlyMap<string, AsyncValidatorFn[]>>;
+export declare const NGX_FW_VALIDATOR_REGISTRATIONS: InjectionToken<ReadonlyMap<string, ValidatorFn[]>[]>;
+export declare const NGX_FW_ASYNC_VALIDATOR_REGISTRATIONS: InjectionToken<ReadonlyMap<string, AsyncValidatorFn[]>[]>;
+export declare const NGX_FW_VALIDATOR_REGISTRATIONS_RESOLVED: InjectionToken<ReadonlyMap<string, ValidatorFn[]>>;
+export declare const NGX_FW_ASYNC_VALIDATOR_REGISTRATIONS_RESOLVED: InjectionToken<ReadonlyMap<string, AsyncValidatorFn[]>>;

package/lib/tokens/validator-resolver.d.ts

@@ -0,0 +1,3 @@
+import { InjectionToken } from '@angular/core';
+import { ValidatorResolver } from '../types/validator-resolver.type';
+export declare const NGX_VALIDATOR_RESOLVER: InjectionToken<ValidatorResolver>;

package/lib/types/component-resolver.type.d.ts

@@ -0,0 +1,4 @@
+import { Signal, Type } from '@angular/core';
+export interface ComponentResolver {
+    registrations: Signal<ReadonlyMap<string, Type<unknown>>>;
+}