@quadrel-enterprise-ui/framework 20.21.0 → 20.21.1

package/fesm2022/quadrel-enterprise-ui-framework.mjs

@@ -8468,6 +8468,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImpo
 // @ts-strict-ignore
 class QdFormControl extends UntypedFormControl {
     maxLength;
+    revalidationPartners = [];
     validatorList;
     constructor(formState, validatorOrOpts, asyncValidator) {
         super(formState, validatorOrOpts, asyncValidator);
@@ -8482,12 +8483,15 @@ class QdFormControl extends UntypedFormControl {
     }
     setPropsFromValidatorList() {
         let maxLength;
+        const revalidationPartners = [];
         this.validatorList.forEach((validatorFn) => {
-            if (validatorFn.maxLength) {
+            if (validatorFn.maxLength)
                 maxLength = validatorFn.maxLength;
-            }
+            if (validatorFn.qdRevalidates)
+                revalidationPartners.push(validatorFn.qdRevalidates);
         });
         this.maxLength = maxLength;
+        this.revalidationPartners = revalidationPartners;
     }
     setValidators(validators) {
         this.validatorList = this.getValidatorList(validators);
@@ -8520,6 +8524,9 @@ class QdFormControl extends UntypedFormControl {
     getMaxLengthOrUndefined() {
         return this.maxLength;
     }
+    getRevalidationPartners() {
+        return this.revalidationPartners;
+    }
 }
 function isOptionsObj$1(validatorOrOpts) {
     return validatorOrOpts != null && !Array.isArray(validatorOrOpts) && typeof validatorOrOpts === 'object';
@@ -12387,6 +12394,8 @@ class QdDatepickerComponent {
         const current = this.config?.disabledDates;
         if (current === this._boundDisabledDates)
             return;
+        if (!this.control)
+            return;
         this._boundDisabledDates = current;
         this.validateDisabledDates();
     }
@@ -12394,6 +12403,8 @@ class QdDatepickerComponent {
         const current = this.config?.timePicker?.disabledTimes;
         if (current === this._boundDisabledTimes)
             return;
+        if (!this.control)
+            return;
         this._boundDisabledTimes = current;
         this.validateDisabledTimes();
     }
@@ -13524,14 +13535,40 @@ const validatorsDroppedWithOptsWarning = 'Quadrel Framework | QdForms - QdFormCo
 function hasUnit(control) {
     return control.value?.value != null && control.value?.unit != null;
 }
+/**
+ * Ready-to-use validators for Quadrel Reactive Forms.
+ *
+ * Use them like Angular's built-in `Validators`, but every validator returns a **translatable
+ * error key** instead of a fixed message, and most accept a custom `errorKey` as the last
+ * argument.
+ *
+ * Empty values pass for most validators — combine with `required()` when a value is mandatory.
+ * The amount-aware validators (`min`, `max`, `minLength`, `maxLength`, `pattern`) also accept
+ * `{ value, unit }` objects and validate the inner `value`.
+ *
+ * #### **Usage**
+ * ```ts
+ * form = new QdFormGroup({
+ *   email: new QdFormControl(null, [QdValidators.required(), QdValidators.email()]),
+ *   age: new QdFormControl(null, [QdValidators.required(), QdValidators.min(18)])
+ * });
+ * ```
+ */
 class QdValidators {
     /**
-     * Validates that the value of the form field is at least the specified minimum.
+     * Validates that a numeric value is greater than or equal to a minimum.
+     *
+     * Empty values (`null`/`undefined`) pass — combine with `required` when a value is mandatory.
+     * Also accepts amount objects of the shape `{ value, unit }`; in that case the inner `value`
+     * is validated.
+     *
+     * @param min - The smallest allowed value (inclusive).
+     * @param errorKey - Translation key returned when the value is below the minimum.
      *
      * #### **Usage**
      * ```ts
-     * new QdFormControl('', QdValidators.min(3));
-     * new QdFormControl('', QdValidators.min(3, 'custom-error'));
+     * new QdFormControl(null, QdValidators.min(3));
+     * new QdFormControl(null, QdValidators.min(3, 'custom-error'));
      * ```
      */
     static min(min, errorKey = 'i18n.qd.form.error.min') {
@@ -13543,12 +13580,19 @@ class QdValidators {
         return validFn;
     }
     /**
-     * Validates that the value of the form field does not exceed the specified maximum.
+     * Validates that a numeric value is less than or equal to a maximum.
+     *
+     * Empty values (`null`/`undefined`) pass — combine with `required` when a value is mandatory.
+     * Also accepts amount objects of the shape `{ value, unit }`; in that case the inner `value`
+     * is validated.
+     *
+     * @param max - The largest allowed value (inclusive).
+     * @param errorKey - Translation key returned when the value exceeds the maximum.
      *
      * #### **Usage**
      * ```ts
-     * new QdFormControl('', QdValidators.max(10));
-     * new QdFormControl('', QdValidators.max(10, 'custom-error'));
+     * new QdFormControl(null, QdValidators.max(10));
+     * new QdFormControl(null, QdValidators.max(10, 'custom-error'));
      * ```
      */
     static max(max, errorKey = 'i18n.qd.form.error.max') {
@@ -13560,7 +13604,16 @@ class QdValidators {
         return validFn;
     }
     /**
-     * Ensures that the form field is not empty.
+     * Validates that the field holds a non-empty value.
+     *
+     * Quadrel form components additionally render a required asterisk (`*`) on the field label
+     * whenever this validator is present, so users see at a glance that the field is mandatory.
+     *
+     * Empty means: `null`, `undefined`, an empty string, an empty array, or an object whose
+     * leaf values are all empty (checked recursively — useful for amount objects such as
+     * `{ value, unit }`).
+     *
+     * @param errorKey - Translation key returned when the field is empty.
      *
      * #### **Usage**
      * ```ts
@@ -13583,7 +13636,12 @@ class QdValidators {
         return value == null || (typeof value === 'string' && value.length === 0);
     }
     /**
-     * Validates that the form field contains a valid email address.
+     * Validates that the field contains a single, well-formed email address.
+     *
+     * Empty values pass — combine with `required` when an address is mandatory. The whole value
+     * must be the address; surrounding text makes it invalid.
+     *
+     * @param errorKey - Translation key returned when the address is malformed.
      *
      * #### **Usage**
      * ```ts
@@ -13598,7 +13656,14 @@ class QdValidators {
         return validFn;
     }
     /**
-     * Ensures that the form field contains at least the specified number of characters.
+     * Validates that a text value is at least a given number of characters long.
+     *
+     * Empty values (`null`/`undefined`/`''`) pass — combine with `required` when input is
+     * mandatory. Also accepts amount objects of the shape `{ value, unit }`; in that case the
+     * inner `value` is measured.
+     *
+     * @param minLength - The minimum number of characters (inclusive).
+     * @param errorKey - Translation key returned when the value is too short.
      *
      * #### **Usage**
      * ```ts
@@ -13615,7 +13680,15 @@ class QdValidators {
         return validFn;
     }
     /**
-     * Ensures that the form field contains no more than the specified number of characters.
+     * Validates that a text value is no longer than a given number of characters.
+     *
+     * Empty values pass — combine with `required` when input is mandatory. Also accepts amount
+     * objects of the shape `{ value, unit }`; in that case the inner `value` is measured. The
+     * configured limit is exposed as `.maxLength` on the returned validator, which `qd-textarea`
+     * reads to show a live character counter (`current / max`).
+     *
+     * @param maxLength - The maximum number of characters (inclusive).
+     * @param errorKey - Translation key returned when the value is too long.
      *
      * #### **Usage**
      * ```ts
@@ -13633,7 +13706,13 @@ class QdValidators {
         return validFn;
     }
     /**
-     * Ensures that the form field matches a given regular expression pattern.
+     * Validates that a text value matches a regular expression.
+     *
+     * Empty values pass — combine with `required` when input is mandatory. Also accepts amount
+     * objects of the shape `{ value, unit }`; in that case the inner `value` is matched.
+     *
+     * @param pattern - The pattern to match, as a `RegExp` or a string regular expression.
+     * @param errorKey - Translation key returned when the value does not match.
      *
      * #### **Usage**
      * ```ts
@@ -13651,11 +13730,17 @@ class QdValidators {
         return validFn;
     }
     /**
-     * Ensures that the form field contains a valid date.
+     * Validates that the value is a real, parseable `Date` object.
+     *
+     * Empty values pass — combine with `required` when a date is mandatory. Strings (including
+     * `'Invalid Date'`), numbers and plain objects are rejected. The error carries the locale
+     * date format (`DD.MM.YYYY`) as a `params.format` hint for the message.
+     *
+     * @param errorKey - Translation key returned when the value is not a valid date.
      *
      * #### **Usage**
      * ```ts
-     * new QdFormControl('', QdValidators.date());
+     * new QdFormControl(null, QdValidators.date());
      * new QdFormControl(new Date(), QdValidators.date());
      * new QdFormControl(new Date(), QdValidators.date('date-error'));
      * ```
@@ -13666,24 +13751,29 @@ class QdValidators {
                 return null;
             const localizedFormat = moment().format('DD.MM.YYYY');
             const formattedErrorKey = { date: { key: errorKey, params: { format: localizedFormat } } };
-            if (value === 'Invalid Date')
-                return formattedErrorKey;
-            if (!(value instanceof Date) || isNaN(value.getTime()))
-                return formattedErrorKey;
-            return null;
+            return this.isValidDate(value) ? null : formattedErrorKey;
         };
     }
     /**
-     * Ensures that the selected date is not within a range of disabled dates.
+     * Validates that a date does not fall inside any of the given disabled ranges.
+     *
+     * Each range may set `from`, `to`, or both; an open end reaches into the far past/future.
+     * Boundaries are **exclusive** — a date exactly on `from` or `to` is still allowed; only
+     * dates strictly between them are rejected. Comparison is day-granular. Empty or invalid
+     * values pass.
+     *
+     * @param disabledDates - Ranges to block, e.g. `[{ from, to }]`.
+     * @param errorKey - Translation key returned when the date lies inside a range.
      *
      * #### **Usage**
      * ```ts
-     * new QdFormControl('', QdValidators.disabledDates([{ from: new Date('2025-01-01') }]));
+     * new QdFormControl(null, QdValidators.disabledDates([{ from: new Date('2025-01-01') }]));
+     * new QdFormControl(null, QdValidators.disabledDates([{ from: new Date('2025-01-01'), to: new Date('2025-01-31') }]));
      * ```
      */
     static disabledDates(disabledDates, errorKey = 'i18n.qd.form.error.disabledDates') {
         const validFn = (control) => {
-            if (!control.value || isNaN(control.value?.getTime?.()))
+            if (!this.isValidDate(control.value))
                 return null;
             const date = moment(control.value.getTime());
             return this.isDateDisabled(disabledDates, date) ? { disabledDates: errorKey } : null;
@@ -13702,16 +13792,74 @@ class QdValidators {
         });
     }
     /**
-     * Ensures that the selected time is not within a range of disabled times.
+     * Validates that a date stays on the correct side of a sibling "range partner" control.
+     *
+     * Put it on both ends of a from/to pair, each pointing at the other. A `'start'` control is
+     * invalid when its date is after the partner; an `'end'` control is invalid when its date is
+     * before the partner. Comparison is day-granular, so equal days are valid.
+     *
+     * The partner value is read live on every run, so the limit is never cached — it stays
+     * correct across form rebuilds, saves and config changes. Empty or invalid own/partner
+     * values, and a missing partner control, all pass.
+     *
+     * Inside a `QdFormGroup` the partner is re-validated automatically when this control changes
+     * (and vice versa), so a stale error never lingers — no manual `updateValueAndValidity` needed.
+     * The validator declares this dependency via `qdRevalidates`, which the group reads.
+     *
+     * The auto-revalidation only applies when both controls are `QdFormControl`s inside a
+     * `QdFormGroup`, and only for validators present at construction or set via the group's
+     * `add`/`set`/`removeControl`. On a native `FormGroup`/`FormControl`, or when the validator is
+     * added later via `control.addValidators(...)`, re-validate the partner manually with
+     * `partner.updateValueAndValidity({ emitEvent: false })` whenever this control changes.
+     *
+     * @param partnerControlName - Name of the sibling control holding the other end of the range.
+     * @param position - `'start'` for the from-control, `'end'` for the to-control.
+     * @param errorKey - Translation key returned when the order is violated.
+     *
+     * #### **Usage**
+     * ```ts
+     * new QdFormGroup({
+     *   from: new QdFormControl(null, QdValidators.dateRange('to', 'start')),
+     *   to: new QdFormControl(null, QdValidators.dateRange('from', 'end'))
+     * });
+     * ```
+     */
+    static dateRange(partnerControlName, position, errorKey = 'i18n.qd.form.error.dateRange') {
+        const validFn = (control) => {
+            const ownValue = control.value;
+            const partnerValue = control.parent?.get(partnerControlName)?.value;
+            if (!this.isValidDate(ownValue) || !this.isValidDate(partnerValue))
+                return null;
+            const own = moment(ownValue);
+            const partner = moment(partnerValue);
+            const isInvalid = position === 'start' ? own.isAfter(partner, 'day') : own.isBefore(partner, 'day');
+            return isInvalid ? { dateRange: errorKey } : null;
+        };
+        validFn.qdRevalidates = partnerControlName;
+        return validFn;
+    }
+    static isValidDate(value) {
+        return value instanceof Date && !isNaN(value.getTime());
+    }
+    /**
+     * Validates that the time of a date value does not fall inside any disabled time range.
+     *
+     * Each range may set `from`, `to`, or both, as `HH:mm` strings. Boundaries are **exclusive** —
+     * a time exactly on `from` or `to` is allowed; only times strictly between them are rejected.
+     * Only the time-of-day is considered, not the date. Empty or invalid values pass.
+     *
+     * @param disabledTimes - Ranges to block, e.g. `[{ from: '12:00', to: '13:00' }]`.
+     * @param errorKey - Translation key returned when the time lies inside a range.
      *
      * #### **Usage**
      * ```ts
-     * new QdFormControl('', QdValidators.disabledTimes([{ from: '15:00' }]));
+     * new QdFormControl(null, QdValidators.disabledTimes([{ from: '15:00' }]));
+     * new QdFormControl(null, QdValidators.disabledTimes([{ from: '12:00', to: '13:00' }]));
      * ```
      */
     static disabledTimes(disabledTimes, errorKey = 'i18n.qd.form.error.disabledTimes') {
         const validFn = (control) => {
-            if (!control.value || isNaN(control.value?.getTime?.()))
+            if (!this.isValidDate(control.value))
                 return null;
             const time = moment(control.value).format('HH:mm');
             return TimePickerService.isTimeDisabled(time, disabledTimes) ? { disabledTimes: errorKey } : null;
@@ -13719,7 +13867,14 @@ class QdValidators {
         return validFn;
     }
     /**
-     * Ensures that the selected file does not exceed the given maximum size in megabytes.
+     * Validates that a selected file does not exceed a maximum size.
+     *
+     * Operates on a `File` value (e.g. from a file input). Non-file values — including `null` —
+     * pass, so combine with `required` when a file is mandatory. The error carries `params.maxMb`
+     * for the message.
+     *
+     * @param maxMb - The maximum allowed size in megabytes.
+     * @param errorKey - Translation key returned when the file is too large.
      *
      * #### **Usage**
      * ```ts
@@ -13737,7 +13892,15 @@ class QdValidators {
         };
     }
     /**
-     * Validates that the file type or file extension matches one of the accepted types.
+     * Validates that a selected file matches one of the accepted types.
+     *
+     * Each accepted entry is either a MIME type (`'application/pdf'`), a MIME wildcard
+     * (`'image/*'`), or a file extension (`'.pdf'`); matching is case-insensitive. Non-file
+     * values — including `null` — pass, so combine with `required` when a file is mandatory. The
+     * error carries `params.accepted` for the message.
+     *
+     * @param accepted - Allowed MIME types, MIME wildcards or extensions.
+     * @param errorKey - Translation key returned when the file type is not accepted.
      *
      * #### **Usage**
      * ```ts
@@ -15176,7 +15339,59 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.18", ngImpo
                 args: ['class.qd-radio-buttons-error']
             }] } });
 
+/**
+ * `UntypedFormGroup` that wires cross-field re-validation automatically.
+ *
+ * A validator can declare a sibling dependency via `qdRevalidates` (see `QdValidators.dateRange`).
+ * The group then subscribes to that partner's `valueChanges` and re-validates the dependent control,
+ * so a stale error never lingers when the partner value changes — without the consumer calling
+ * `updateValueAndValidity`. The subscriptions are group-internal (sibling to sibling) and are torn
+ * down and rebuilt whenever a control is added, replaced or removed.
+ *
+ * Re-wiring is triggered by control mutations (`add`/`set`/`removeControl`), not by validator
+ * mutations on an existing control: calling `control.addValidators(...)` after construction updates
+ * the control's partners but does not re-wire the group until the next control mutation.
+ */
 class QdFormGroup extends UntypedFormGroup {
+    revalidationSubscription = new Subscription();
+    constructor(controls, validatorOrOpts, asyncValidator) {
+        super(controls, validatorOrOpts, asyncValidator);
+        this.wireCrossFieldRevalidation();
+    }
+    addControl(name, control, options) {
+        super.addControl(name, control, options);
+        this.rewireCrossFieldRevalidation();
+    }
+    setControl(name, control, options) {
+        super.setControl(name, control, options);
+        this.rewireCrossFieldRevalidation();
+    }
+    removeControl(name, options) {
+        super.removeControl(name, options);
+        this.rewireCrossFieldRevalidation();
+    }
+    rewireCrossFieldRevalidation() {
+        this.revalidationSubscription.unsubscribe();
+        this.revalidationSubscription = new Subscription();
+        this.wireCrossFieldRevalidation();
+    }
+    wireCrossFieldRevalidation() {
+        Object.keys(this.controls).forEach(name => {
+            const control = this.controls[name];
+            if (!(control instanceof QdFormControl))
+                return;
+            const partnerNames = control.getRevalidationPartners();
+            if (!partnerNames.length)
+                return;
+            partnerNames.forEach(partnerName => {
+                const partner = this.get(partnerName);
+                if (!partner)
+                    return;
+                this.revalidationSubscription.add(partner.valueChanges.subscribe(() => control.updateValueAndValidity({ emitEvent: false })));
+            });
+            control.updateValueAndValidity({ emitEvent: false });
+        });
+    }
 }
 
 class QdFormBuilder extends UntypedFormBuilder {