@ng-forge/dynamic-forms 0.2.0 → 0.3.0

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

@@ -1,6 +1,6 @@
-import { FormEvent, FieldDef, FormEventConstructor, BaseCheckedField, BaseValueField, DynamicText, FieldOption, ValidationMessages } from '@ng-forge/dynamic-forms';
+import { FormEvent, FieldDef, FormEventConstructor, BaseCheckedField, BaseValueField, DynamicText, FieldMeta, FieldOption, ValidationMessages } from '@ng-forge/dynamic-forms';
 import * as i0 from '@angular/core';
-import { Signal, Injector, PipeTransform } from '@angular/core';
+import { Signal, Injector, ElementRef, PipeTransform } from '@angular/core';
 import { FieldTree } from '@angular/forms/signals';
 
 /**
@@ -43,6 +43,94 @@ interface DatepickerField<TProps> extends BaseValueField<TProps, Date | string>
     startAt?: Date | null;
 }
 
+/**
+ * Autocomplete values for HTML input elements.
+ * Based on the WHATWG HTML specification for autofill.
+ *
+ * @see https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill
+ */
+type AutocompleteValue = 'off' | 'on' | 'name' | 'honorific-prefix' | 'given-name' | 'additional-name' | 'family-name' | 'honorific-suffix' | 'nickname' | 'email' | 'username' | 'new-password' | 'current-password' | 'one-time-code' | 'organization-title' | 'organization' | 'street-address' | 'address-line1' | 'address-line2' | 'address-line3' | 'address-level4' | 'address-level3' | 'address-level2' | 'address-level1' | 'country' | 'country-name' | 'postal-code' | 'cc-name' | 'cc-given-name' | 'cc-additional-name' | 'cc-family-name' | 'cc-number' | 'cc-exp' | 'cc-exp-month' | 'cc-exp-year' | 'cc-csc' | 'cc-type' | 'transaction-currency' | 'transaction-amount' | 'language' | 'bday' | 'bday-day' | 'bday-month' | 'bday-year' | 'sex' | 'tel' | 'tel-country-code' | 'tel-national' | 'tel-area-code' | 'tel-local' | 'tel-extension' | 'impp' | 'url' | 'photo';
+/**
+ * Input mode hints for virtual keyboards on mobile devices.
+ *
+ * @see https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-inputmode-attribute
+ */
+type InputMode = 'none' | 'text' | 'decimal' | 'numeric' | 'tel' | 'search' | 'email' | 'url';
+/**
+ * Enter key hints for virtual keyboards.
+ *
+ * @see https://html.spec.whatwg.org/multipage/interaction.html#input-modalities:-the-enterkeyhint-attribute
+ */
+type EnterKeyHint = 'enter' | 'done' | 'go' | 'next' | 'previous' | 'search' | 'send';
+/**
+ * Autocapitalization hints for virtual keyboards.
+ *
+ * @see https://html.spec.whatwg.org/multipage/interaction.html#attr-autocapitalize
+ */
+type Autocapitalize = 'off' | 'none' | 'on' | 'sentences' | 'words' | 'characters';
+/**
+ * Meta attributes specific to HTML input elements.
+ *
+ * Extends FieldMeta with input-specific native attributes that can be passed through
+ * to the underlying input element.
+ *
+ * @example
+ * ```typescript
+ * // Input field with meta attributes
+ * {
+ *   type: 'input',
+ *   key: 'email',
+ *   meta: {
+ *     autocomplete: 'email',
+ *     inputmode: 'email',
+ *     enterkeyhint: 'next',
+ *     spellcheck: false,
+ *     'data-testid': 'email-input'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+interface InputMeta extends FieldMeta {
+    /**
+     * Hint for form autofill behavior.
+     */
+    autocomplete?: AutocompleteValue;
+    /**
+     * Hint for virtual keyboard type on mobile devices.
+     */
+    inputmode?: InputMode;
+    /**
+     * Hint for the enter key label on virtual keyboards.
+     */
+    enterkeyhint?: EnterKeyHint;
+    /**
+     * Whether to enable spellchecking for the input.
+     */
+    spellcheck?: boolean;
+    /**
+     * Hint for autocapitalization behavior on virtual keyboards.
+     */
+    autocapitalize?: Autocapitalize;
+    /**
+     * Pattern for client-side validation (regex).
+     */
+    pattern?: string;
+    /**
+     * Size hint for the input element (character count).
+     */
+    size?: number;
+    /**
+     * Maximum number of characters allowed.
+     */
+    maxlength?: number;
+    /**
+     * Minimum number of characters required.
+     */
+    minlength?: number;
+}
+
 /**
  * HTML input types supported by input fields
  */
@@ -77,7 +165,7 @@ interface NumberInputField<TProps extends {
     type?: string;
 } = InputProps> extends BaseValueField<TProps & {
     type: 'number';
-}, number> {
+}, number, InputMeta> {
     type: 'input';
     props: TProps & {
         type: 'number';
@@ -92,7 +180,7 @@ interface StringInputField<TProps extends {
     type?: string;
 } = InputProps> extends BaseValueField<TProps & {
     type?: StringInputType;
-}, string> {
+}, string, InputMeta> {
     type: 'input';
     props?: TProps & {
         type?: StringInputType;
@@ -156,12 +244,12 @@ type InputField<TProps extends {
  */
 interface MultiCheckboxField<TValue, TProps = object> extends BaseValueField<TProps, TValue[]> {
     type: 'multi-checkbox';
-    options: FieldOption<TValue>[];
+    readonly options: readonly FieldOption<TValue>[];
 }
 
 interface RadioField<T, TProps> extends BaseValueField<TProps, T> {
     type: 'radio';
-    options: FieldOption<T>[];
+    readonly options: readonly FieldOption<T>[];
 }
 
 interface SelectProps {
@@ -179,12 +267,75 @@ interface SliderField<TProps> extends BaseValueField<TProps, number> {
     step?: number;
 }
 
+/**
+ * Text wrapping behavior for textarea elements.
+ *
+ * @see https://html.spec.whatwg.org/multipage/form-elements.html#attr-textarea-wrap
+ */
+type TextareaWrap = 'hard' | 'soft' | 'off';
+/**
+ * Meta attributes specific to HTML textarea elements.
+ *
+ * Extends FieldMeta with textarea-specific native attributes that can be passed through
+ * to the underlying textarea element.
+ *
+ * @example
+ * ```typescript
+ * // Textarea field with meta attributes
+ * {
+ *   type: 'textarea',
+ *   key: 'description',
+ *   meta: {
+ *     wrap: 'soft',
+ *     spellcheck: true,
+ *     autocomplete: 'off',
+ *     'data-testid': 'description-textarea'
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+interface TextareaMeta extends FieldMeta {
+    /**
+     * How text should wrap when submitted.
+     * - 'hard': Line breaks are inserted to wrap text at cols width
+     * - 'soft': Text is wrapped for display but not in submitted value
+     * - 'off': No wrapping, horizontal scrolling if needed
+     */
+    wrap?: TextareaWrap;
+    /**
+     * Whether to enable spellchecking for the textarea.
+     */
+    spellcheck?: boolean;
+    /**
+     * Hint for form autofill behavior.
+     */
+    autocomplete?: AutocompleteValue;
+    /**
+     * Hint for autocapitalization behavior on virtual keyboards.
+     */
+    autocapitalize?: Autocapitalize;
+    /**
+     * Hint for the enter key label on virtual keyboards.
+     */
+    enterkeyhint?: EnterKeyHint;
+    /**
+     * Maximum number of characters allowed.
+     */
+    maxlength?: number;
+    /**
+     * Minimum number of characters required.
+     */
+    minlength?: number;
+}
+
 interface TextareaProps {
     placeholder?: DynamicText;
     rows?: number;
     cols?: number | undefined;
 }
-interface TextareaField<TProps = TextareaProps> extends BaseValueField<TProps, string> {
+interface TextareaField<TProps = TextareaProps> extends BaseValueField<TProps, string, TextareaMeta> {
     type: 'textarea';
     maxLength?: number | undefined;
 }
@@ -317,11 +468,76 @@ declare function shouldShowErrors<T>(field: Signal<FieldTree<T>>): Signal<boolea
  */
 declare function isEqual(a: unknown, b: unknown): boolean;
 
+/**
+ * Configuration options for setupMetaTracking.
+ */
+interface MetaTrackingOptions {
+    /**
+     * CSS selector for target elements within the host.
+     * If not provided, meta attributes are applied directly to the host element.
+     *
+     * @example
+     * // Apply to internal radio inputs
+     * selector: 'input[type="radio"]'
+     *
+     * // Apply to host element (for Shadow DOM components)
+     * selector: undefined
+     */
+    selector?: string;
+    /**
+     * Additional signals to track that should trigger re-application of meta.
+     * Useful for components where DOM elements are dynamically created (e.g., radio options).
+     *
+     * @example
+     * // Re-apply when options change
+     * dependents: [this.options]
+     */
+    dependents?: Signal<unknown>[];
+}
+/**
+ * Sets up automatic meta attribute tracking and application for wrapped components.
+ *
+ * This utility creates an `afterRenderEffect` that applies meta attributes to DOM elements
+ * after Angular's render cycle. It efficiently tracks signal dependencies and only re-applies
+ * when the meta signal or any dependent signals change.
+ *
+ * Use this instead of MutationObserver for better performance and integration with Angular's
+ * change detection.
+ *
+ * @param elementRef - Reference to the host element
+ * @param meta - Signal containing meta attributes to apply
+ * @param options - Configuration options
+ *
+ * @example
+ * ```typescript
+ * // For a radio group with dynamic options
+ * constructor() {
+ *   setupMetaTracking(inject(ElementRef), this.meta, {
+ *     selector: 'input[type="radio"]',
+ *     dependents: [this.options]
+ *   });
+ * }
+ *
+ * // For a simple checkbox
+ * constructor() {
+ *   setupMetaTracking(inject(ElementRef), this.meta, {
+ *     selector: 'input[type="checkbox"]'
+ *   });
+ * }
+ *
+ * // For Shadow DOM components (apply to host)
+ * constructor() {
+ *   setupMetaTracking(inject(ElementRef), this.meta);
+ * }
+ * ```
+ */
+declare function setupMetaTracking(elementRef: ElementRef<HTMLElement>, meta: Signal<FieldMeta | undefined>, options?: MetaTrackingOptions): void;
+
 declare class ValueInArrayPipe implements PipeTransform {
     transform<T>(element: T, array: T[] | undefined): boolean;
     static ɵfac: i0.ɵɵFactoryDeclaration<ValueInArrayPipe, never>;
     static ɵpipe: i0.ɵɵPipeDeclaration<ValueInArrayPipe, "inArray", true>;
 }
 
-export { ValueInArrayPipe, buildValueFieldInputs, checkboxFieldMapper, createResolvedErrorsSignal, datepickerFieldMapper, isEqual, optionsFieldMapper, resolveValueFieldContext, shouldShowErrors, valueFieldMapper };
-export type { ButtonField, CheckboxField, DatepickerField, DatepickerProps, EventArgs, FieldWithOptions, InputField, InputProps, InputType, InputTypeToValueType, MultiCheckboxField, RadioField, ResolvedError, SelectField, SelectProps, SliderField, StringInputType, TextareaField, TextareaProps, ToggleField, ValueFieldContext };
+export { ValueInArrayPipe, buildValueFieldInputs, checkboxFieldMapper, createResolvedErrorsSignal, datepickerFieldMapper, isEqual, optionsFieldMapper, resolveValueFieldContext, setupMetaTracking, shouldShowErrors, valueFieldMapper };
+export type { Autocapitalize, AutocompleteValue, ButtonField, CheckboxField, DatepickerField, DatepickerProps, EnterKeyHint, EventArgs, FieldWithOptions, InputField, InputMeta, InputMode, InputProps, InputType, InputTypeToValueType, MetaTrackingOptions, MultiCheckboxField, RadioField, ResolvedError, SelectField, SelectProps, SliderField, StringInputType, TextareaField, TextareaMeta, TextareaProps, TextareaWrap, ToggleField, ValueFieldContext };

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

@@ -402,6 +402,37 @@ interface ComponentTestResult<T = unknown> {
     fixture: ComponentFixture<T>;
 }
 
+/**
+ * Type utilities for exhaustive whitelist type testing.
+ *
+ * These utilities help ensure that type definitions remain stable by detecting
+ * when properties are added, removed, or changed.
+ */
+/**
+ * Extracts only the required keys from a type.
+ *
+ * @example
+ * ```typescript
+ * interface Example { a: string; b?: number; }
+ * type Required = RequiredKeys<Example>; // 'a'
+ * ```
+ */
+type RequiredKeys<T> = {
+    [K in keyof T]-?: object extends Pick<T, K> ? never : K;
+}[keyof T];
+/**
+ * Extracts only the optional keys from a type.
+ *
+ * @example
+ * ```typescript
+ * interface Example { a: string; b?: number; }
+ * type Optional = OptionalKeys<Example>; // 'b'
+ * ```
+ */
+type OptionalKeys<T> = {
+    [K in keyof T]-?: object extends Pick<T, K> ? K : never;
+}[keyof T];
+
 declare class TestInputHarness {
     readonly field: _angular_core.InputSignal<FieldTree<string>>;
     readonly key: _angular_core.InputSignal<string>;
@@ -563,4 +594,4 @@ declare const SPANISH_TEST_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, createSimpleTestField, createTestFieldContext, createTestFormInjector, createTestTranslationService, delay, provideTestLogger, setupSimpleTest, testMapper };
-export type { ComponentTestConfig, ComponentTestResult, DynamicFormTestConfig, DynamicFormTestResult, MockLogger, SimpleComponentTestConfig, SimpleComponentTestResult, SimpleTestConfig, SimpleTestResult, TestConfig, TestFieldContextConfig, TestFormConfig, TestResult };
+export type { ComponentTestConfig, ComponentTestResult, DynamicFormTestConfig, DynamicFormTestResult, MockLogger, OptionalKeys, RequiredKeys, SimpleComponentTestConfig, SimpleComponentTestResult, SimpleTestConfig, SimpleTestResult, TestConfig, TestFieldContextConfig, TestFormConfig, TestResult };