@quadrel-enterprise-ui/framework 20.20.1 → 20.21.1

package/index.d.ts

@@ -5855,9 +5855,11 @@ declare class QdNotificationsSnackbarComponent {
 type ValidatorFnWithProps = {
     (control: AbstractControl): ValidationErrors | null;
     maxLength?: number;
+    qdRevalidates?: string;
 };
 declare class QdFormControl<T> extends UntypedFormControl implements AbstractControl {
     private maxLength?;
+    private revalidationPartners;
     private validatorList;
     constructor(formState?: T, validatorOrOpts?: ValidatorFnWithProps | ValidatorFnWithProps[] | FormControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null);
     private getValidatorList;
@@ -5868,6 +5870,7 @@ declare class QdFormControl<T> extends UntypedFormControl implements AbstractCon
     clearValidators(): void;
     hasMaxLength(): boolean;
     getMaxLengthOrUndefined(): number | undefined;
+    getRevalidationPartners(): string[];
 }
 
 /**
@@ -7912,7 +7915,35 @@ declare class QdRadioButtonsComponent implements OnInit, OnChanges, OnDestroy, C
     static ɵcmp: i0.ɵɵComponentDeclaration<QdRadioButtonsComponent, "qd-radio-buttons", never, { "value": { "alias": "value"; "required": false; }; "config": { "alias": "config"; "required": false; }; "formControlName": { "alias": "formControlName"; "required": false; }; "testId": { "alias": "data-test-id"; "required": false; }; }, { "valueChange": "valueChange"; "clickHint": "clickHint"; "clickReadonly": "clickReadonly"; "clickViewonly": "clickViewonly"; }, never, never, false, never>;
 }
 
+/**
+ * `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.
+ */
 declare class QdFormGroup extends UntypedFormGroup {
+    private revalidationSubscription;
+    constructor(controls: {
+        [key: string]: AbstractControl;
+    }, validatorOrOpts?: ValidatorFn | ValidatorFn[] | AbstractControlOptions | null, asyncValidator?: AsyncValidatorFn | AsyncValidatorFn[] | null);
+    addControl(name: string, control: AbstractControl, options?: {
+        emitEvent?: boolean;
+    }): void;
+    setControl(name: string, control: AbstractControl, options?: {
+        emitEvent?: boolean;
+    }): void;
+    removeControl(name: string, options?: {
+        emitEvent?: boolean;
+    }): void;
+    private rewireCrossFieldRevalidation;
+    private wireCrossFieldRevalidation;
 }
 
 declare class QdFormBuilder extends UntypedFormBuilder {
@@ -8123,29 +8154,71 @@ declare class QdFilterFormItemsComponent implements OnInit {
     static ɵcmp: i0.ɵɵComponentDeclaration<QdFilterFormItemsComponent, "qd-filter-form-items", never, { "inputFilterValue": { "alias": "inputFilterValue"; "required": false; }; "testId": { "alias": "data-test-id"; "required": false; }; }, { "filterValueChange": "filterValueChange"; }, never, never, false, never>;
 }
 
+/**
+ * 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)])
+ * });
+ * ```
+ */
 declare 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: number, errorKey?: string): ValidatorFn;
     /**
-     * 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: number, errorKey?: string): ValidatorFn;
     /**
-     * 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
@@ -8156,7 +8229,12 @@ declare class QdValidators {
     static required(errorKey?: string): ValidatorFn;
     private static isEmptyInputValue;
     /**
-     * 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
@@ -8166,7 +8244,14 @@ declare class QdValidators {
      */
     static email(errorKey?: string): ValidatorFn;
     /**
-     * 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
@@ -8176,7 +8261,15 @@ declare class QdValidators {
      */
     static minLength(minLength: number, errorKey?: string): ValidatorFn;
     /**
-     * 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
@@ -8186,7 +8279,13 @@ declare class QdValidators {
      */
     static maxLength(maxLength: number, errorKey?: string): ValidatorFn;
     /**
-     * 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
@@ -8197,37 +8296,102 @@ declare class QdValidators {
      */
     static pattern(pattern: string | RegExp, errorKey?: string): ValidatorFn;
     /**
-     * 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'));
      * ```
      */
     static date(errorKey?: string): ValidatorFn;
     /**
-     * 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: QdDisabledDates[], errorKey?: string): ValidatorFn;
     private static isDateDisabled;
     /**
-     * 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: string, position: 'start' | 'end', errorKey?: string): ValidatorFn;
+    private static isValidDate;
+    /**
+     * 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: QdDisabledTimes[], errorKey?: string): ValidatorFn;
     /**
-     * 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
@@ -8237,7 +8401,15 @@ declare class QdValidators {
      */
     static fileSize(maxMb: number, errorKey?: string): ValidatorFn;
     /**
-     * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quadrel-enterprise-ui/framework",
-  "version": "20.20.1",
+  "version": "20.21.1",
   "exports": {
     "./jest-preset": "./jest-preset.js",
     "./package.json": {

package/src/assets/i18n/de.json

@@ -99,6 +99,7 @@
   "i18n.qd.form.error.pattern": "Entspricht nicht dem Muster",
   "i18n.qd.form.error.date": "Eingabe entspricht nicht DD.MM.JJJJ",
   "i18n.qd.form.error.disabledDates": "Datum ausserhalb des erlaubten Bereichs",
+  "i18n.qd.form.error.dateRange": "Das Datum liegt ausserhalb des gültigen Bereichs.",
   "i18n.qd.form.error.startDateNotAfterEndDate": "Das Startdatum darf nicht hinter dem Enddatum liegen.",
   "i18n.qd.form.error.endDateNotBeforeStartDate": "Das Enddatum darf nicht vor dem Startdatum liegen.",
   "i18n.qd.form.error.disabledTimes": "Zeit ausserhalb des erlaubten Bereichs",

package/src/assets/i18n/en.json

@@ -101,6 +101,7 @@
   "i18n.qd.form.error.pattern": "Does not match pattern",
   "i18n.qd.form.error.date": "Input does not correspond to DD.MM.YYYY",
   "i18n.qd.form.error.disabledDates": "Date outside the permitted range",
+  "i18n.qd.form.error.dateRange": "The date is outside the valid range.",
   "i18n.qd.form.error.startDateNotAfterEndDate": "The start date cannot be later than the end date.",
   "i18n.qd.form.error.endDateNotBeforeStartDate": "The end date cannot be earlier than the start date.",
   "i18n.qd.form.error.disabledTimes": "Time outside the permitted range",

package/src/assets/i18n/fr.json

@@ -101,6 +101,7 @@
   "i18n.qd.form.error.pattern": "Ne correspond pas au schéma",
   "i18n.qd.form.error.date": "La saisie ne correspond pas à JJ.MM.AAAA",
   "i18n.qd.form.error.disabledDates": "Date en dehors de la plage autorisée",
+  "i18n.qd.form.error.dateRange": "La date est en dehors de la plage valide.",
   "i18n.qd.form.error.startDateNotAfterEndDate": "La date de début ne peut pas être postérieure à la date de fin.",
   "i18n.qd.form.error.endDateNotBeforeStartDate": "La date de fin ne peut pas être antérieure à la date de début.",
   "i18n.qd.form.error.disabledTimes": "Temps en dehors de la plage autorisée",

package/src/assets/i18n/it.json

@@ -101,6 +101,7 @@
   "i18n.qd.form.error.pattern": "Non corrisponde allo schema",
   "i18n.qd.form.error.date": "L'input non corrisponde a GG.MM.AAAA",
   "i18n.qd.form.error.disabledDates": "Data fuori dall'intervallo consentito",
+  "i18n.qd.form.error.dateRange": "La data è al di fuori dell'intervallo valido.",
   "i18n.qd.form.error.startDateNotAfterEndDate": "La data di inizio non può essere successiva alla data di fine.",
   "i18n.qd.form.error.endDateNotBeforeStartDate": "La data di fine non può essere anteriore alla data di inizio.",
   "i18n.qd.form.error.disabledTimes": "Tempo fuori dall'intervallo consentito",