@a.nemreen/dga-dynamic-form 0.1.6 → 0.1.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@a.nemreen/dga-dynamic-form",
-  "version": "0.1.6",
-  "description": "Schema-driven dynamic forms for Angular, rendered with @a.nemreen/dga-ui controls",
+  "version": "0.1.8",
+  "description": "Schema-driven Angular dynamic forms — 18 field types, wizard, cross-field validators (password, Saudi phone, date range), staged uploads, lookup, reCAPTCHA v3, and conditional visibility. Built on @a.nemreen/dga-ui.",
   "license": "MIT",
   "author": {
     "name": "Ahmed Nemreen",
@@ -22,6 +22,10 @@
     "dynamic-form",
     "schema-form",
     "reactive-forms",
+    "wizard",
+    "validators",
+    "file-upload",
+    "recaptcha",
     "dga",
     "design-system",
     "rtl",
@@ -33,6 +37,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "fesm2022",
+    "types",
+    "LICENSE",
+    "README.md"
+  ],
   "engines": {
     "node": ">=18"
   },
@@ -40,8 +50,8 @@
     "@angular/common": "^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
     "@angular/core": "^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
     "@angular/forms": "^19.0.0 || ^20.0.0 || ^21.0.0 || ^22.0.0",
-    "@a.nemreen/dga-tokens": "^0.2.0",
-    "@a.nemreen/dga-ui": "^0.2.0"
+    "@a.nemreen/dga-tokens": "^0.2.0 || ^0.3.0",
+    "@a.nemreen/dga-ui": "^0.2.0 || ^0.3.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"

package/types/a.nemreen-dga-dynamic-form.d.ts

@@ -1,6 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { InjectionToken, Type, OnInit, EnvironmentProviders } from '@angular/core';
-import { FormGroup, FormControl, FormBuilder, ValidatorFn, AbstractControl } from '@angular/forms';
+import { FormGroup, FormControl, FormBuilder, ValidatorFn, AbstractControl, ValidationErrors } from '@angular/forms';
 import { DgaStep, DgaSelectOption, DgaToastService } from '@a.nemreen/dga-ui';
 import { Observable } from 'rxjs';
 import { HttpClient } from '@angular/common/http';
@@ -24,7 +24,24 @@ interface DgaFormFieldOption {
     disabled?: boolean;
     [key: string]: unknown;
 }
-type DgaFormFieldType = 'text' | 'email' | 'textarea' | 'select' | 'multiselect' | 'checkbox' | 'radio' | 'phone' | 'file' | 'date' | 'chips' | 'toggle' | 'hidden' | 'number' | 'otp';
+type DgaFormFieldType = 'text' | 'email' | 'textarea' | 'select' | 'multiselect' | 'checkbox' | 'radio' | 'phone' | 'file' | 'multifile' | 'multifilestaged' | 'date' | 'chips' | 'toggle' | 'hidden' | 'number' | 'otp' | 'password';
+/** Pre-populated attachment from the server (edit mode). */
+interface DgaExistingAttachment {
+    Id: number;
+    FileName: string;
+    ContentType: string;
+}
+type DgaStagedFileStatus = 'uploading' | 'success' | 'error';
+/** Value shape for `multifilestaged` fields. */
+interface DgaStagedFileRef {
+    fileId: string;
+    fileName: string;
+    sizeBytes?: number;
+    status?: DgaStagedFileStatus;
+    errorMessage?: string;
+    /** Client-only list identity when server reuses fileId. */
+    listKey?: string;
+}
 type DgaInputRestriction = 'numbers' | 'english' | 'arabic';
 type DgaHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 interface DgaFormField {
@@ -40,10 +57,22 @@ interface DgaFormField {
     hidden?: boolean;
     dependsOn?: string;
     showOnValues?: unknown[];
+    /** Show when selected option English label matches. */
+    showOnTitleEn?: string;
+    /** Show when selected option Arabic label matches. */
+    showOnTitleAr?: string;
+    /** Extra text field shown when selected option has `requiresTextInput`. */
+    extraField?: boolean;
+    /** Trigger field for `extraField` (defaults to `dependsOn`). */
+    extraFieldTrigger?: string;
     showWhenOptionProperty?: {
         property: string;
         value: unknown;
     };
+    /** CMS consent key — fetched from `consentBaseUrl` on the form config. */
+    consentServiceName?: string;
+    /** Keep select dropdown open (DGA select `openMode="always"`). */
+    alwaysOpen?: boolean;
     lookupDomain?: string;
     lookupName?: string;
     lookupFilter?: {
@@ -60,6 +89,11 @@ interface DgaFormField {
     acceptedFileTypes?: string;
     maxFileSize?: number;
     maxFiles?: number;
+    /** POST URL for `multifilestaged` staging uploads. Response: `{ fileId, fileName? }`. */
+    uploadEndpoint?: string;
+    /** DELETE/POST URL for staged file removal. Use `:id` or `:fileId` placeholder. */
+    deleteEndpoint?: string;
+    deleteMethod?: 'DELETE' | 'POST';
     rows?: number;
     minDate?: string;
     maxDate?: string;
@@ -72,6 +106,13 @@ interface DgaFormField {
     columns?: DgaFormFieldColumns;
     optionsLayout?: 'stack' | 'grid';
     excludeFromPayload?: boolean;
+    /**
+     * When true, the field value is never written to draft storage.
+     * OTP / file fields are always excluded even without this flag.
+     */
+    excludeFromDraft?: boolean;
+    /** Treat as sensitive in drafts (same effect as excludeFromDraft). */
+    sensitive?: boolean;
     inputRestriction?: DgaInputRestriction;
     requiredWhen?: {
         field: string;
@@ -87,7 +128,9 @@ interface DgaFormField {
         required?: boolean;
         min?: number;
         max?: number;
-        errorMessages?: Partial<Record<'required' | 'pattern' | 'minLength' | 'maxLength' | 'email' | 'min' | 'max' | 'minDate' | 'maxDate' | 'maxChips' | 'invalidFormat', DgaFormLabel>>;
+        minDate?: string;
+        maxDate?: string;
+        errorMessages?: Partial<Record<'required' | 'pattern' | 'minLength' | 'maxLength' | 'email' | 'min' | 'max' | 'minDate' | 'maxDate' | 'maxChips' | 'invalidFormat' | 'invalidPrefix' | 'invalidLength' | 'passwordMismatch' | 'endDateAfterStartDate' | 'uploadInProgress' | 'maxFiles', DgaFormLabel>>;
     };
 }
 interface DgaFormStep {
@@ -96,6 +139,8 @@ interface DgaFormStep {
     description?: DgaFormLabel;
     fields: DgaFormField[];
     optional?: boolean;
+    /** Pre-fill values when entering this wizard step. */
+    initialData?: Record<string, unknown>;
 }
 interface DgaWizardConfig {
     enabled: boolean;
@@ -131,6 +176,11 @@ interface DgaDynamicFormConfig {
     idempotencyKey?: string;
     /** When true, HTTP submit is skipped and only `formSubmitted` is emitted. */
     emitOnly?: boolean;
+    /**
+     * Base URL for CMS consent fetch (`consentServiceName` fields).
+     * e.g. `https://cms.example.com/api` → GET `{base}/consents/{name}`.
+     */
+    consentBaseUrl?: string;
 }
 type DgaFormLocale = 'ar' | 'en';
 
@@ -184,6 +234,10 @@ declare const DGA_LOOKUP_ADAPTER: InjectionToken<DgaLookupAdapter>;
 declare const DGA_SUBMIT_ADAPTER: InjectionToken<DgaSubmitAdapter>;
 declare const DGA_FORM_TOAST_ADAPTER: InjectionToken<DgaFormToastAdapter>;
 declare const DGA_CAPTCHA_ADAPTER: InjectionToken<DgaCaptchaAdapter>;
+interface DgaHttpSecurityOptions {
+    allowedOrigins?: string[];
+}
+declare const DGA_HTTP_SECURITY: InjectionToken<DgaHttpSecurityOptions>;
 declare const DGA_FORM_I18N_ADAPTER: InjectionToken<DgaFormI18nAdapter>;
 declare const DGA_DYNAMIC_FORM_FIELD_REGISTRY: InjectionToken<DgaDynamicFieldRenderer[]>;
 /** Context passed into custom field renderer components (optional inject). */
@@ -219,8 +273,10 @@ declare class DgaDynamicForm {
     readonly formError: _angular_core.OutputEmitterRef<unknown>;
     readonly clearButtonClick: _angular_core.OutputEmitterRef<void>;
     readonly draftSaved: _angular_core.OutputEmitterRef<Record<string, unknown>>;
+    readonly fileDownload: _angular_core.OutputEmitterRef<DgaExistingAttachment>;
     private readonly fb;
     private readonly formService;
+    private readonly submitAdapter;
     private readonly toast;
     private readonly i18n;
     private readonly destroyRef;
@@ -261,7 +317,10 @@ declare class DgaDynamicForm {
         options: DgaFormFieldOption[];
     }): void;
     previousStep(): void;
+    /** Keep stepper clicks aligned with Next validation / allowSkip rules. */
+    readonly canActivateStep: (next: number, current: number) => boolean;
     nextStep(): void;
+    private skipEmptyStepsForward;
     onClear(): void;
     onSaveDraft(): void;
     onSubmit(): void;
@@ -274,7 +333,7 @@ declare class DgaDynamicForm {
     private visibleValid;
     private collectVisibleFieldNames;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DgaDynamicForm, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DgaDynamicForm, "dga-dynamic-form", never, { "config": { "alias": "config"; "required": true; "isSignal": true; }; "localeInput": { "alias": "locale"; "required": false; "isSignal": true; }; }, { "formSubmitted": "formSubmitted"; "formError": "formError"; "clearButtonClick": "clearButtonClick"; "draftSaved": "draftSaved"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DgaDynamicForm, "dga-dynamic-form", never, { "config": { "alias": "config"; "required": true; "isSignal": true; }; "localeInput": { "alias": "locale"; "required": false; "isSignal": true; }; }, { "formSubmitted": "formSubmitted"; "formError": "formError"; "clearButtonClick": "clearButtonClick"; "draftSaved": "draftSaved"; "fileDownload": "fileDownload"; }, never, never, true, never>;
 }
 
 declare class DgaDynamicFormField implements OnInit {
@@ -284,11 +343,14 @@ declare class DgaDynamicFormField implements OnInit {
     readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly error: _angular_core.InputSignal<string>;
     readonly runtimeOptions: _angular_core.InputSignal<DgaFormFieldOption[]>;
+    readonly consentBaseUrl: _angular_core.InputSignal<string | undefined>;
     readonly optionsLoaded: _angular_core.OutputEmitterRef<{
         name: string;
         options: DgaFormFieldOption[];
     }>;
+    readonly fileDownload: _angular_core.OutputEmitterRef<DgaExistingAttachment>;
     private readonly lookup;
+    private readonly http;
     private readonly destroyRef;
     readonly loadedOptions: _angular_core.WritableSignal<DgaFormFieldOption[]>;
     readonly controlId: string;
@@ -299,14 +361,19 @@ declare class DgaDynamicFormField implements OnInit {
     readonly resolvedOptions: _angular_core.Signal<DgaFormFieldOption[]>;
     readonly selectOptions: _angular_core.Signal<DgaSelectOption[]>;
     ngOnInit(): void;
+    private mapExistingFileValue;
+    private fetchConsent;
+    private fetchLookup;
     optionLabel(opt: DgaFormFieldOption): string;
+    isPasswordField(): boolean;
     isChecked(value: unknown): boolean;
     toggleCheckbox(value: unknown, checked: boolean): void;
-    onSelectSearch(_value: string | string[]): void;
+    onSelectSearchQuery(query: string): void;
+    onStagedFileDownload(event: DgaExistingAttachment): void;
     onRestrict(event: Event): void;
     private applyLookupFilter;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DgaDynamicFormField, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DgaDynamicFormField, "dga-dynamic-form-field", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "form": { "alias": "form"; "required": true; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "runtimeOptions": { "alias": "runtimeOptions"; "required": false; "isSignal": true; }; }, { "optionsLoaded": "optionsLoaded"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DgaDynamicFormField, "dga-dynamic-form-field", never, { "field": { "alias": "field"; "required": true; "isSignal": true; }; "form": { "alias": "form"; "required": true; "isSignal": true; }; "locale": { "alias": "locale"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "runtimeOptions": { "alias": "runtimeOptions"; "required": false; "isSignal": true; }; "consentBaseUrl": { "alias": "consentBaseUrl"; "required": false; "isSignal": true; }; }, { "optionsLoaded": "optionsLoaded"; "fileDownload": "fileDownload"; }, never, never, true, never>;
 }
 
 declare class DgaDynamicFormService {
@@ -319,9 +386,14 @@ declare class DgaDynamicFormService {
     hasFileValues(data: Record<string, unknown>): boolean;
     toFormData(data: Record<string, unknown>): FormData;
     submitForm(config: DgaDynamicFormConfig, values: Record<string, unknown>, fields: DgaFormField[]): Observable<unknown>;
-    saveDraft(formId: string, values: Record<string, unknown>): void;
+    /**
+     * Persist a draft. Sensitive fields (otp, file, password-like names,
+     * `excludeFromDraft` / `sensitive`) are stripped before writing.
+     */
+    saveDraft(formId: string, values: Record<string, unknown>, fields?: DgaFormField[]): void;
     loadDraft(formId: string): Record<string, unknown> | null;
     clearDraft(formId: string): void;
+    private isDraftBlocked;
     private storageKey;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DgaDynamicFormService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<DgaDynamicFormService>;
@@ -340,8 +412,19 @@ declare function dgaFindSelectedOption(field: DgaFormField | undefined, value: u
 /**
  * Whether a field should be visible given the current form values.
  */
-declare function dgaIsFieldVisible(field: DgaFormField, values: Record<string, unknown>, getOptions?: (name: string) => DgaFormFieldOption[] | undefined): boolean;
-declare function dgaIsRequiredWhen(field: DgaFormField, values: Record<string, unknown>, getOptions?: (name: string) => DgaFormFieldOption[] | undefined): boolean;
+declare function dgaIsFieldVisible(field: DgaFormField, values: Record<string, unknown>, getOptions?: (name: string) => DgaFormFieldOption[] | undefined, getField?: (name: string) => DgaFormField | undefined): boolean;
+declare function dgaIsRequiredWhen(field: DgaFormField, values: Record<string, unknown>, getOptions?: (name: string) => DgaFormFieldOption[] | undefined, getField?: (name: string) => DgaFormField | undefined): boolean;
+
+/** Known start/end date field pairs used by cross-field validators. */
+declare const DGA_DATE_RANGE_PAIRS: ReadonlyArray<[string, string]>;
+declare function dgaPasswordMatchValidator(passwordControl: AbstractControl): ValidatorFn;
+/**
+ * Saudi mobile validation for type: phone fields.
+ * Accepts E.164 (+966…) or national digits (0xxxxxxxx or 5xxxxxxxx).
+ */
+declare function dgaSaudiMobileValidator(control: AbstractControl): ValidationErrors | null;
+/** Wire password match + date-range validators after form group is built. */
+declare function dgaApplyCrossFieldValidators(form: FormGroup, fields: DgaFormField[]): void;
 
 /** Default bilingual label resolver. */
 declare const defaultFormI18nAdapter: DgaFormI18nAdapter;
@@ -349,13 +432,7 @@ declare const defaultFormI18nAdapter: DgaFormI18nAdapter;
 declare const noopCaptchaAdapter: DgaCaptchaAdapter;
 /** Empty lookup (returns []). Override in the host app. */
 declare const emptyLookupAdapter: DgaLookupAdapter;
-interface DgaHttpAdapterSecurityOptions {
-    /**
-     * Allowed URL origins for schema-driven HTTP (e.g. `https://api.example.com`).
-     * When set, requests outside the list are rejected.
-     * When omitted, only `http:` / `https:` are accepted (no `file:` / opaque URLs).
-     */
-    allowedOrigins?: string[];
+interface DgaHttpAdapterSecurityOptions extends DgaHttpSecurityOptions {
 }
 /**
  * Validates schema-supplied URLs before HttpClient calls.
@@ -378,6 +455,11 @@ interface ProvideDgaDynamicFormOptions {
     dgaToast?: boolean;
     /** Optional origin allowlist for HTTP adapters (recommended for CMS schemas). */
     allowedOrigins?: string[];
+    /**
+     * When true, `allowedOrigins` is required if httpLookup or httpSubmit is enabled.
+     * Defaults to false (warn in dev). Set true for CMS / untrusted schemas.
+     */
+    requireAllowedOrigins?: boolean;
 }
 /**
  * Registers default adapters for lookup, submit, toast, captcha, and i18n.
@@ -393,5 +475,5 @@ declare function resolveFormLabel(label: {
 declare function dgaResolveLabel(label: DgaFormLabel | undefined, locale: DgaFormLocale, fallback?: string): string;
 declare function dgaDetectLocale(): DgaFormLocale;
 
-export { DGA_CAPTCHA_ADAPTER, DGA_DYNAMIC_FORM_FIELD_REGISTRY, DGA_FORM_I18N_ADAPTER, DGA_FORM_TOAST_ADAPTER, DGA_LOOKUP_ADAPTER, DGA_SUBMIT_ADAPTER, DgaDynamicForm, DgaDynamicFormField, DgaDynamicFormFieldRegistry, DgaDynamicFormService, createDgaToastAdapter, createHttpLookupAdapter, createHttpSubmitAdapter, defaultFormI18nAdapter, dgaAssertSafeHttpUrl, dgaBuildFormGroup, dgaBuildValidators, dgaCollectFields, dgaCreateControl, dgaDefaultValueForField, dgaDetectLocale, dgaFindSelectedOption, dgaIsFieldVisible, dgaIsRequiredWhen, dgaResolveLabel, dgaSetControlValidators, emptyLookupAdapter, noopCaptchaAdapter, provideDgaDynamicForm, resolveFormLabel };
-export type { DgaCaptchaAdapter, DgaDynamicFieldHostContext, DgaDynamicFieldRenderer, DgaDynamicFormConfig, DgaDynamicFormPayloadTransformer, DgaFormField, DgaFormFieldColumns, DgaFormFieldOption, DgaFormFieldType, DgaFormI18nAdapter, DgaFormLabel, DgaFormLocale, DgaFormStep, DgaFormToastAdapter, DgaHttpAdapterSecurityOptions, DgaHttpMethod, DgaInputRestriction, DgaLookupAdapter, DgaLookupRequest, DgaSubmitAdapter, DgaSubmitRequest, DgaToastVariant, DgaWizardConfig, ProvideDgaDynamicFormOptions };
+export { DGA_CAPTCHA_ADAPTER, DGA_DATE_RANGE_PAIRS, DGA_DYNAMIC_FORM_FIELD_REGISTRY, DGA_FORM_I18N_ADAPTER, DGA_FORM_TOAST_ADAPTER, DGA_HTTP_SECURITY, DGA_LOOKUP_ADAPTER, DGA_SUBMIT_ADAPTER, DgaDynamicForm, DgaDynamicFormField, DgaDynamicFormFieldRegistry, DgaDynamicFormService, createDgaToastAdapter, createHttpLookupAdapter, createHttpSubmitAdapter, defaultFormI18nAdapter, dgaApplyCrossFieldValidators, dgaAssertSafeHttpUrl, dgaBuildFormGroup, dgaBuildValidators, dgaCollectFields, dgaCreateControl, dgaDefaultValueForField, dgaDetectLocale, dgaFindSelectedOption, dgaIsFieldVisible, dgaIsRequiredWhen, dgaPasswordMatchValidator, dgaResolveLabel, dgaSaudiMobileValidator, dgaSetControlValidators, emptyLookupAdapter, noopCaptchaAdapter, provideDgaDynamicForm, resolveFormLabel };
+export type { DgaCaptchaAdapter, DgaDynamicFieldHostContext, DgaDynamicFieldRenderer, DgaDynamicFormConfig, DgaDynamicFormPayloadTransformer, DgaExistingAttachment, DgaFormField, DgaFormFieldColumns, DgaFormFieldOption, DgaFormFieldType, DgaFormI18nAdapter, DgaFormLabel, DgaFormLocale, DgaFormStep, DgaFormToastAdapter, DgaHttpAdapterSecurityOptions, DgaHttpMethod, DgaHttpSecurityOptions, DgaInputRestriction, DgaLookupAdapter, DgaLookupRequest, DgaStagedFileRef, DgaSubmitAdapter, DgaSubmitRequest, DgaToastVariant, DgaWizardConfig, ProvideDgaDynamicFormOptions };