@arsedizioni/ars-utils 22.5.46 → 22.5.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arsedizioni/ars-utils",
-  "version": "22.5.46",
+  "version": "22.5.48",
   "author": {
     "email": "software@arsedizioni.it",
     "name": "Fabio Buscaroli, Alberto Doria"

package/types/arsedizioni-ars-utils-core.validators.d.ts

@@ -257,8 +257,8 @@ declare class TimeValidatorDirective implements Validator {
  * nor an empty array. Apply `notEmpty` to a text input where non-blank content is required, or
  * to a multi-value control that must carry at least one entry.
  *
- * A value that is simply absent passes: saying "obbligatorio" is the job of `required`, or of
- * `requiredNotEmpty` when both rules belong on the same control.
+ * A value that is simply absent passes: saying "obbligatorio" is the job of `required`, which is
+ * declared next to this one when both rules belong on the same control.
  */
 declare class NotEmptyValidatorDirective implements Validator {
     /**
@@ -272,37 +272,6 @@ declare class NotEmptyValidatorDirective implements Validator {
     static ɵdir: i0.ɵɵDirectiveDeclaration<NotEmptyValidatorDirective, "[notEmpty]", never, {}, {}, never, never, true, never>;
 }
 
-/**
- * Directive that validates that a control carries actual content: present AND not blank.
- * Apply `requiredNotEmpty` where `required notEmpty` would otherwise be spelled out together.
- *
- * It raises the very errors those two rules raise — `required` when the value is missing, an
- * empty string or an empty array, `notEmpty` when a value is there but made of whitespace alone —
- * so existing error messages and `getFieldErrorMessage` keep working untouched, and the user
- * still reads "Obbligatorio" rather than the vaguer "Non può essere vuoto".
- *
- * IMPORTANT, on a Material field: this directive does NOT draw the asterisk. `MatInput` reads its
- * own `required` input first and falls back to `hasValidator(Validators.required)`, which no
- * directive-provided validator can satisfy — the validators of a template-driven control are
- * merged into one composed function before they get there. Keep writing `required` on the
- * control next to this one: the two produce the same `{ required: true }` key, so the errors
- * merge and nothing is reported twice.
- *
- * `aria-required` is set here so that assistive technology is told the truth even where the
- * `required` attribute is absent.
- */
-declare class RequiredNotEmptyValidatorDirective implements Validator {
-    /**
-     * Validates that the control value is present and carries content.
-     * @param control - The form control to validate.
-     * @returns `{ required: true }` when nothing was entered, `{ notEmpty: true }` when the value
-     *          is blank, `null` when the value is acceptable.
-     */
-    validate(control: AbstractControl): ValidationErrors | null;
-    static ɵfac: i0.ɵɵFactoryDeclaration<RequiredNotEmptyValidatorDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<RequiredNotEmptyValidatorDirective, "[requiredNotEmpty]", never, {}, {}, never, never, true, never>;
-}
-
 /**
  * Options shared by the ARS signal-form validators.
  *
@@ -370,12 +339,16 @@ declare function password<TPathKind extends PathKind = PathKind.Root>(path: Sche
  * The signal-form counterpart of `NotEmptyValidatorDirective`, sharing its predicate through
  * {@link isBlankValue}: a blank string and an empty array are errors, an absent value is not.
  * That last part is not an oversight — saying "obbligatorio" belongs to `required()`, and a field
- * that is merely blank would otherwise raise two errors that mean the same thing. Pair the two,
- * or reach for {@link requiredNotEmpty}, when a field must be both present and non-blank.
+ * that is merely blank would otherwise raise two errors that mean the same thing. Declare the two
+ * together when a field must be both present and non-blank.
  *
  * Replaces the `pattern(p.x, /\S/)` workaround: same rule, but the intent is in the name and the
  * error kind is `notEmpty` rather than `pattern`.
  *
+ * On a multi-value field this rule is the ONLY one that sees an empty selection: Angular's
+ * `required()` treats emptiness as `'' | false | null | undefined`, so an empty array walks past
+ * it. Give it a message of its own there, because the default one talks about whitespace.
+ *
  * @param path   - Path of the field to validate.
  * @param config - Optional message override.
  * @returns void
@@ -385,34 +358,6 @@ declare function password<TPathKind extends PathKind = PathKind.Root>(path: Sche
  * const f = form(this.model, p => { notEmpty(p.tags); });   // at least one tag
  */
 declare function notEmpty<TValue extends string | readonly unknown[] | undefined, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, config?: ArsValidatorConfig<TValue, TPathKind>): void;
-/**
- * Requires the value to be both present and made of something: the two rules a mandatory text
- * field almost always needs together, declared once.
- *
- * The signal-form counterpart of `RequiredNotEmptyValidatorDirective`. It raises the errors the
- * two rules raise on their own rather than a kind of its own — `required` when nothing was
- * entered, `notEmpty` when a value is there but blank — so the message stays as precise as it was
- * and nothing downstream needs to learn a new kind.
- *
- * The presence half is DELEGATED to Angular's own `required()` and is not reimplemented here.
- * That call does more than validate: it writes the `REQUIRED` metadata on the field, and that
- * metadata is the only thing the Material compatibility layer looks at when it answers
- * `hasValidator(Validators.required)` through `field().required()`. A plain `validate()` would
- * reject the empty value just the same and silently drop the asterisk from the label.
- *
- * The empty array is the one case handled here rather than there: Angular's emptiness check is
- * `value === '' || value === false || value == null`, so an empty array walks straight past
- * `required()`. It is reported with the `required` kind all the same, because for a multi-value
- * field "nothing selected" is exactly what the user needs to be told.
- *
- * @param path   - Path of the field to validate.
- * @param config - Optional message override, applied to whichever of the two errors is raised,
- *                 and `when` condition, honoured by both halves of the rule.
- * @returns void
- * @example
- * const f = form(this.model, p => { requiredNotEmpty(p.city); });
- */
-declare function requiredNotEmpty<TValue extends string | readonly unknown[] | undefined, TPathKind extends PathKind = PathKind.Root>(path: SchemaPath<TValue, SchemaPathRules.Supported, TPathKind>, config?: ArsValidatorConfig<TValue, TPathKind>): void;
 /**
  * Requires the value to differ from the value of another field of the same form.
  *
@@ -613,5 +558,5 @@ declare class SignalsUtils {
     }[], message?: string): string | undefined;
 }
 
-export { ARS_VALIDATOR_MESSAGES, EmailsValidatorDirective, EqualsValidatorDirective, FileSizeValidatorDirective, GuidValidatorDirective, MIN_VALID_YEAR, MaxTermsValidatorDirective, NotEmptyValidatorDirective, NotEqualValidatorDirective, NotFutureValidatorDirective, PasswordValidatorDirective, RequiredNotEmptyValidatorDirective, SignalsUtils, SqlDateValidatorDirective, TimeValidatorDirective, UrlValidatorDirective, ValidIfDirective, ValidatorDirective, date, dateRange, emails, equals, fileSize, guid, maxTerms, notEmpty, notEqual, notFuture, otp, password, requiredNotEmpty, sqlDate, time, url, validIf };
+export { ARS_VALIDATOR_MESSAGES, EmailsValidatorDirective, EqualsValidatorDirective, FileSizeValidatorDirective, GuidValidatorDirective, MIN_VALID_YEAR, MaxTermsValidatorDirective, NotEmptyValidatorDirective, NotEqualValidatorDirective, NotFutureValidatorDirective, PasswordValidatorDirective, SignalsUtils, SqlDateValidatorDirective, TimeValidatorDirective, UrlValidatorDirective, ValidIfDirective, ValidatorDirective, date, dateRange, emails, equals, fileSize, guid, maxTerms, notEmpty, notEqual, notFuture, otp, password, sqlDate, time, url, validIf };
 export type { ArsValidatorConfig };

package/types/arsedizioni-ars-utils-ui.d.ts

@@ -1,4 +1,4 @@
-import { Searchable, INode, DateInterval, SearchBag, NameValueItem } from '@arsedizioni/ars-utils/core';
+import { Searchable, INode, SearchBag, DateInterval, NameValueItem } from '@arsedizioni/ars-utils/core';
 import { MatFormFieldAppearance } from '@angular/material/form-field';
 import * as _angular_core from '@angular/core';
 import { TemplateRef, InjectionToken, Signal, ElementRef, Renderer2 } from '@angular/core';
@@ -111,6 +111,35 @@ interface SelectDialogData {
     searchLabel?: string;
     searchButtonLabel?: string;
 }
+/**
+ * Data of `ListDialogComponent`: the read-only sibling of {@link SelectDialogData}.
+ *
+ * It carries no `can*` flag on purpose — the dialog shows a searchable list and closes, so there
+ * is nothing to enable — and no `mustSelect` / `okCaption` either, because there is no
+ * confirmation step to gate.
+ */
+interface ListDialogData {
+    /** Dialog title, rendered as HTML. */
+    title: string;
+    /** Optional description shown under the title, rendered as HTML. */
+    description?: string;
+    /** Optional header shown above the list, rendered as HTML. Hidden while the list is empty. */
+    header?: string;
+    /** Items to display. */
+    items?: SelectableItem[];
+    /** Initial search text. */
+    filter?: string;
+    /** Message shown in place of the list when there is nothing to display. Rendered as HTML. */
+    emptyMessage?: string;
+    /** Caption of the close button, which is always available. Defaults to `Chiudi`. */
+    closeCaption?: string;
+    /** Label of the search field. Defaults to `Cerca...`. */
+    searchLabel?: string;
+    /** Appearance of the search field. Defaults to `outline`. */
+    appearance?: MatFormFieldAppearance;
+    /** Preferred dialog width, in pixels, for the caller that opens it. */
+    width?: number;
+}
 interface SelectTreeDialogData {
     title: string;
     description?: string;
@@ -910,4 +939,4 @@ declare class FlexLayoutModule {
 }
 
 export { ALIAS_FAMILIES, BS5_BREAKPOINTS, CANONICAL_ALIASES, FlexLayoutModule, FxClassDirective, FxFlexAlignDirective, FxFlexDirective, FxFlexFillDirective, FxFlexOffsetDirective, FxFlexOrderDirective, FxGridAreaDirective, FxGridColumnDirective, FxGridDirective, FxLayoutAlignDirective, FxLayoutDirective, FxLayoutGapDirective, FxLayoutWrapDirective, FxShowHideDirective, FxStyleDirective, IfBpDirective, ItemNode, LAYOUT_BREAKPOINTS, LAYOUT_VALUES, MediaObserver, NON_CANONICAL_PRIORITY, PromptDialogType, ResponsiveBaseDirective, SelectableItem, SelectableNode, UIService, applyVisibility, buildAlignStyles, buildFlexStyles, buildLayoutCSS, resolve, resolveAll, resolveFlexInput, resolveNonCanonical, resolveParentFlow, validateBasis, validateLayoutValue, validateWrapValue };
-export type { BpValues, BreakpointAlias, CanonicalKey, CredentialsDialogResult, DialogOption, DialogResult, ISelectableItem, ISendToDialog, NcValues, NonCanonicalKey, PromptDateDialogResult, PromptDialogData, PromptDialogResult, PromptOtpDialogResult, PromptTimeDialogData, RecoverPasswordDialogResult, ResetPasswordDialogResult, SelectDialogAppend, SelectDialogData, SelectDialogDelete, SelectDialogEdit, SelectDialogFilter, SelectDialogLookup, SelectDialogResult, SelectFile, SelectFileDialogData, SelectFileOption, SelectPictureFileDialogData, SelectTreeDialogData, SelectTreeDialogResult, SelectableFilter, SendToDialogResult, SendToPopulateData };
+export type { BpValues, BreakpointAlias, CanonicalKey, CredentialsDialogResult, DialogOption, DialogResult, ISelectableItem, ISendToDialog, ListDialogData, NcValues, NonCanonicalKey, PromptDateDialogResult, PromptDialogData, PromptDialogResult, PromptOtpDialogResult, PromptTimeDialogData, RecoverPasswordDialogResult, ResetPasswordDialogResult, SelectDialogAppend, SelectDialogData, SelectDialogDelete, SelectDialogEdit, SelectDialogFilter, SelectDialogLookup, SelectDialogResult, SelectFile, SelectFileDialogData, SelectFileOption, SelectPictureFileDialogData, SelectTreeDialogData, SelectTreeDialogResult, SelectableFilter, SendToDialogResult, SendToPopulateData };

package/types/arsedizioni-ars-utils-ui.dialogs.select.d.ts

@@ -1,16 +1,62 @@
 import * as _angular_forms_signals from '@angular/forms/signals';
 import * as _angular_core from '@angular/core';
 import { OnDestroy } from '@angular/core';
+import { SearchFilterMetadata } from '@arsedizioni/ars-utils/core';
+import { ListDialogData, SelectableItem, SelectDialogData, SelectDialogResult, SelectDialogEdit, SelectDialogAppend, SelectDialogDelete, SelectDialogLookup, SelectDialogFilter, SelectableFilter, ItemNode, SelectTreeDialogResult, SelectTreeDialogData, ISendToDialog, SendToDialogResult, SendToPopulateData } from '@arsedizioni/ars-utils/ui';
 import { MatCheckboxChange } from '@angular/material/checkbox';
 import { MatSelectionList, MatSelectionListChange } from '@angular/material/list';
 import { MatPaginator, PageEvent } from '@angular/material/paginator';
-import { SearchFilterMetadata } from '@arsedizioni/ars-utils/core';
-import { SelectDialogData, SelectDialogResult, SelectDialogEdit, SelectableItem, SelectDialogAppend, SelectDialogDelete, SelectDialogLookup, SelectDialogFilter, SelectableFilter, ItemNode, SelectTreeDialogResult, SelectTreeDialogData, ISendToDialog, SendToDialogResult, SendToPopulateData } from '@arsedizioni/ars-utils/ui';
 import * as rxjs from 'rxjs';
 import { MatTree } from '@angular/material/tree';
 import { MatFormFieldAppearance } from '@angular/material/form-field';
 import { SignalsUtils } from '@arsedizioni/ars-utils/core.validators';
 
+/**
+ * Read-only counterpart of `SelectDialogComponent`: it shows a list of items with a search box
+ * and nothing else.
+ *
+ * Deliberately not a selection: the list is a plain `mat-list`, not a `mat-selection-list`, so
+ * there is no selected state to read, no `done` payload and no Ok / Annulla pair — closing is the
+ * only way out and it is always available. It carries no add / edit / delete affordance either:
+ * a dialog that cannot change anything is the whole point, and a caller that needs commands wants
+ * `SelectDialogComponent` instead.
+ *
+ * Filtering is client-side, through the same `search` pipe the select dialog uses on its local
+ * items. There is no server-side lookup: paging a list nobody can act on would buy nothing.
+ */
+declare class ListDialogComponent {
+    private readonly cdr;
+    protected readonly dialogData: _angular_core.WritableSignal<ListDialogData>;
+    /** Items currently on screen. Seeded from the dialog data and replaceable through {@link setItems}. */
+    protected readonly items: _angular_core.WritableSignal<SelectableItem[]>;
+    /** Counters written by the `search` pipe while it filters, read back by the footer. */
+    protected filterMetadata: SearchFilterMetadata;
+    /** Current search text. */
+    protected readonly filterText: _angular_core.WritableSignal<string>;
+    /** Root signal form bound to the search input. */
+    protected readonly filterForm: _angular_forms_signals.FieldTree<string, string | number, "writable">;
+    /**
+     * Replaces the items on screen, for a caller that fills the list after opening the dialog or
+     * refreshes it while it is open.
+     * @param items - The new items to display; an empty array clears the list.
+     */
+    setItems(items: SelectableItem[]): void;
+    /**
+     * Sets the search text programmatically.
+     * @param text - The new search string to apply.
+     */
+    setFilter(text: string): void;
+    /**
+     * Returns the current search text.
+     * @returns The active search string.
+     */
+    getFilter(): string;
+    /** Clears the search text, restoring the whole list. */
+    protected clearFilter(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<ListDialogComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<ListDialogComponent, "ng-component", never, {}, {}, never, never, true, never>;
+}
+
 declare class SelectDialogComponent {
     readonly paginator: _angular_core.Signal<MatPaginator>;
     readonly selection: _angular_core.Signal<MatSelectionList>;
@@ -345,5 +391,5 @@ declare class SendToDialogComponent implements ISendToDialog {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SendToDialogComponent, "ng-component", never, {}, { "done": "done"; "populate": "populate"; }, never, never, true, never>;
 }
 
-export { SelectDialogComponent, SelectTreeDialogComponent, SendToDialogComponent, TreeDataSource };
+export { ListDialogComponent, SelectDialogComponent, SelectTreeDialogComponent, SendToDialogComponent, TreeDataSource };
 export type { SelectTreeDialogAppend, SendToDialogData };