ngx-vest-forms 2.4.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ngx-vest-forms",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "license": "MIT",
   "author": "Brecht Billiet, Arjen Althoff",
   "description": "Opinionated template-driven forms library for Angular with Vest.js integration",

package/types/ngx-vest-forms.d.ts

@@ -192,6 +192,21 @@ declare class FormErrorDisplayDirective {
 }
 
 type AriaAssociationMode = 'all-controls' | 'single-control' | 'none';
+/**
+ * Splits an `aria-describedby` attribute value into normalized token IDs.
+ */
+declare function parseAriaIdTokens(value: string | null): string[];
+/**
+ * Merges currently-active wrapper IDs into an existing `aria-describedby` value.
+ *
+ * Existing tokens owned by the wrapper are removed first, then current active IDs
+ * are appended while preserving non-owned tokens and token uniqueness.
+ */
+declare function mergeAriaDescribedBy(existing: string | null, activeIds: readonly string[], ownedIds: readonly string[]): string | null;
+/**
+ * Resolves control targets based on ARIA association mode.
+ */
+declare function resolveAssociationTargets(controls: readonly HTMLElement[], mode: AriaAssociationMode): HTMLElement[];
 
 /**
  * Accessible form control wrapper built with WCAG 2.2 AA considerations.
@@ -729,6 +744,27 @@ type LeafFieldPath<T, Prefix extends string = '', Depth extends readonly number[
     [K in keyof T & string]: T[K] extends Primitive ? `${Prefix}${K}` : T[K] extends ReadonlyArray<infer U> ? U extends Primitive ? never : LeafFieldPath<U, `${Prefix}${K}.`, [...Depth, 1]> : LeafFieldPath<T[K], `${Prefix}${K}.`, [...Depth, 1]>;
 }[keyof T & string];
 
+type NgxFirstInvalidOptions = {
+    /** Scroll animation behavior (default: `'smooth'`, or `'auto'` when reduced motion is preferred). */
+    behavior?: ScrollBehavior;
+    /** Vertical alignment when scrolling (default: `'center'`). */
+    block?: ScrollLogicalPosition;
+    /** Horizontal alignment when scrolling (default: `'nearest'`). */
+    inline?: ScrollLogicalPosition;
+    /** Whether to focus after scrolling (default: `true`). */
+    focus?: boolean;
+    /** Passed to `focus()` when focusing (default: `true`). */
+    preventScrollOnFocus?: boolean;
+    /** Opens ancestor `<details>` elements before scroll/focus (default: `true`). */
+    openCollapsedParents?: boolean;
+    /** Selector used to locate the first invalid element. */
+    invalidSelector?: string;
+    /** Selector used to resolve the best focus target within the invalid element. */
+    focusSelector?: string;
+};
+declare const DEFAULT_INVALID_SELECTOR: string;
+declare const DEFAULT_FOCUS_SELECTOR: string;
+
 /**
  * Represents the state of a form managed by scVestForm directive.
  * This is the structure returned by NgxVestFormDirective.formState() or similar.
@@ -998,6 +1034,7 @@ type NgxValidationConfig<T = unknown> = Record<string, string[]> | ValidationCon
 declare class FormDirective<T extends Record<string, unknown>> {
     #private;
     readonly ngForm: NgForm;
+    private readonly elementRef;
     private readonly destroyRef;
     private readonly cdr;
     private readonly configDebounceTime;
@@ -1060,6 +1097,11 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * @param v
      */
     readonly validationConfig: InputSignal<NgxValidationConfig<T>>;
+    /**
+     * Emits whenever validation feedback may have changed, even if the aggregate
+     * root form status string stays the same.
+     */
+    private readonly validationFeedback$;
     private readonly pending$;
     /**
      * Emits every time the form status changes in a state
@@ -1209,6 +1251,23 @@ declare class FormDirective<T extends Record<string, unknown>> {
      * ```
      */
     markAllAsTouched(): void;
+    /**
+     * Finds the first invalid element in this form, scrolls it into view, and focuses it.
+     *
+     * Useful in custom submit flows where `markAllAsTouched()` is triggered externally
+     * and the app then wants to guide keyboard and assistive-technology users to the
+     * first failing field.
+     *
+     * @returns The focused element when a focusable target exists, otherwise the first
+     *          matched invalid element. Returns `null` when no invalid element is found.
+     */
+    focusFirstInvalidControl(options?: NgxFirstInvalidOptions): HTMLElement | null;
+    /**
+     * Finds and scrolls the first invalid element into view without moving focus.
+     *
+     * @returns The resolved element, or `null` when no invalid element is found.
+     */
+    scrollToFirstInvalidControl(options?: NgxFirstInvalidOptions): HTMLElement | null;
     /**
      * Host handler: called whenever any descendant field loses focus.
      * Used to make touched-path tracking react immediately on blur/tab.
@@ -2506,5 +2565,5 @@ declare const NGX_WARNING_DISPLAY_MODE_TOKEN: InjectionToken<NgxWarningDisplayMo
  */
 declare const NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN: InjectionToken<number>;
 
-export { ControlWrapperComponent, FormControlStateDirective, FormDirective, FormErrorControlDirective, FormErrorDisplayDirective, FormGroupWrapperComponent, FormModelDirective, FormModelGroupDirective, NGX_ERROR_DISPLAY_MODE_TOKEN, NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN, NGX_WARNING_DISPLAY_MODE_TOKEN, NgxVestForms, ROOT_FORM, ROOT_FORM as ROOT_FORM_CONSTANT, SC_ERROR_DISPLAY_MODE_TOKEN, ValidateRootFormDirective, ValidationConfigBuilder, arrayToObject, clearFields, clearFieldsWhen, cloneDeep, createDebouncedPendingState, createEmptyFormState, createValidationConfig, deepArrayToObject, fastDeepEqual, getAllFormErrors, getFormControlField, getFormGroupField, keepFieldsWhen, mergeValuesAndRawValues, objectToArray, parseFieldPath, set, setValueAtPath, shallowEqual, stringifyFieldPath, validateShape, vestForms, vestFormsViewProviders };
-export type { DebouncedPendingStateOptions, DebouncedPendingStateResult, DeepPartial, DeepRequired, FieldPath, FieldPathValue, FormCompatibleDeepRequired, FormFieldName, LeafFieldPath, NgxDeepPartial, NgxDeepRequired, NgxFieldKey, NgxFormCompatibleDeepRequired, NgxFormState, NgxTypedVestSuite, NgxValidationConfig, NgxVestSuite, NgxWarningDisplayMode, ScErrorDisplayMode, ValidateFieldPath, ValidationConfigMap, ValidationOptions };
+export { ControlWrapperComponent, DEFAULT_FOCUS_SELECTOR, DEFAULT_INVALID_SELECTOR, FormControlStateDirective, FormDirective, FormErrorControlDirective, FormErrorDisplayDirective, FormGroupWrapperComponent, FormModelDirective, FormModelGroupDirective, NGX_ERROR_DISPLAY_MODE_TOKEN, NGX_VALIDATION_CONFIG_DEBOUNCE_TOKEN, NGX_WARNING_DISPLAY_MODE_TOKEN, NgxVestForms, ROOT_FORM, ROOT_FORM as ROOT_FORM_CONSTANT, SC_ERROR_DISPLAY_MODE_TOKEN, ValidateRootFormDirective, ValidationConfigBuilder, arrayToObject, clearFields, clearFieldsWhen, cloneDeep, createDebouncedPendingState, createEmptyFormState, createValidationConfig, deepArrayToObject, fastDeepEqual, getAllFormErrors, getFormControlField, getFormGroupField, keepFieldsWhen, mergeAriaDescribedBy, mergeValuesAndRawValues, objectToArray, parseAriaIdTokens, parseFieldPath, resolveAssociationTargets, set, setValueAtPath, shallowEqual, stringifyFieldPath, validateShape, vestForms, vestFormsViewProviders };
+export type { AriaAssociationMode, DebouncedPendingStateOptions, DebouncedPendingStateResult, DeepPartial, DeepRequired, FieldPath, FieldPathValue, FormCompatibleDeepRequired, FormFieldName, LeafFieldPath, NgxDeepPartial, NgxDeepRequired, NgxFieldKey, NgxFirstInvalidOptions, NgxFormCompatibleDeepRequired, NgxFormState, NgxTypedVestSuite, NgxValidationConfig, NgxVestSuite, NgxWarningDisplayMode, ScErrorDisplayMode, ValidateFieldPath, ValidationConfigMap, ValidationOptions };