@arsedizioni/ars-utils 22.5.17 → 22.5.18

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

@@ -1,3 +1,4 @@
+import * as _angular_forms_signals from '@angular/forms/signals';
 import * as _angular_core from '@angular/core';
 import { DestroyRef, ChangeDetectorRef } from '@angular/core';
 import { ScrollDispatcher } from '@angular/cdk/scrolling';
@@ -315,12 +316,6 @@ declare class ClipperSearchResultManager extends ClipperDocumentManager {
     protected snapshot: ClipperSearchResult | undefined;
     protected readonly filterBusy: _angular_core.WritableSignal<boolean>;
     protected filterParams: ClipperSearchParams;
-    /**
-     * Parameters that produced the result set currently on screen, frozen at the moment the query
-     * was issued. Pagination and sorting page over this copy so that filter pane edits which have
-     * not been applied yet cannot leak into a page change.
-     */
-    protected activeParams: ClipperSearchParams | undefined;
     protected readonly filterPaneHasBackdrop: _angular_core.WritableSignal<boolean>;
     protected readonly filterPaneClosed: _angular_core.WritableSignal<boolean>;
     protected readonly filterPane2HasBackdrop: _angular_core.WritableSignal<boolean>;
@@ -464,32 +459,6 @@ declare class ClipperSearchResultManager extends ClipperDocumentManager {
      * @param queryChunks - Pipe-separated highlight chunks (e.g. "|1|2|3...").
      */
     openDocument(documentId?: string, query?: string, queryChunks?: string): void;
-    /**
-     * Freezes the parameters that produced the result set currently on screen. Paging and
-     * re-sorting must run against this copy, never against `filterParams`, which is bound to the
-     * filter pane and may hold edits the user has not applied yet.
-     * @param params - The parameters actually sent to the server for the current result set.
-     */
-    protected setActiveParams(params: ClipperSearchParams): void;
-    /**
-     * Returns a working copy of the parameters that produced the result set currently on screen.
-     * @returns A clone of the active parameters, or `undefined` when no search has run yet.
-     */
-    protected getActiveParams(): ClipperSearchParams | undefined;
-    /**
-     * Builds the parameters needed to load a different page of the result set currently on screen.
-     * @param pageIndex - The zero-based index of the requested page.
-     * @returns A clone of the active parameters with the paging offset moved to `pageIndex`, or
-     *          `undefined` when no search has run yet.
-     */
-    protected getPageParams(pageIndex: number): ClipperSearchParams | undefined;
-    /**
-     * Revives the date properties of a set of search parameters read back from storage, where JSON
-     * serialisation has turned them into strings.
-     * @param params - The deserialised parameters, or `undefined` when the stored state predates them.
-     * @returns The same instance with its date properties converted back to `Date`, or `undefined`.
-     */
-    protected reviveParamsDates(params?: ClipperSearchParams): ClipperSearchParams | undefined;
     /**
      * Serialises the current component state (paginator, facets, filter params, scroll, sort, data)
      * to the given storage under the given key, enabling later restoration.
@@ -503,11 +472,57 @@ declare class ClipperSearchResultManager extends ClipperDocumentManager {
      * @param id - The storage key to read from.
      * @param storage - The Web Storage instance to use. Defaults to `sessionStorage`.
      */
+    /**
+     * Hook invoked just before the component state is serialised by save().
+     * Subclasses that keep a separate form model can commit it to filterParams here.
+     */
+    protected onStateSaving(): void;
+    /**
+     * Hook invoked after restore() has fully re-hydrated filterParams.
+     * Subclasses that keep a separate form model can rebuild it from filterParams here.
+     */
+    protected onStateRestored(): void;
     restore(id: string, storage?: Storage): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ClipperSearchResultManager, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ClipperSearchResultManager, "ng-component", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Shape of the browser filter-pane form model. Text fields use '' when empty,
+ * numeric/select/date fields use null, list fields use null — never undefined,
+ * because signal forms only create child fields for defined values.
+ */
+interface BrowserFilterModel {
+    modules: NameValueItem<ClipperModule>[] | null;
+    tags: NameValueItem<string>[] | null;
+    topics: NameValueItem<string>[] | null;
+    sectors: NameValueItem<string>[] | null;
+    authors: NameValueItem<string>[] | null;
+    channels: NameValueItem<any>[] | null;
+    number: string;
+    year: number | null;
+    from: Date | null;
+    to: Date | null;
+    text: string;
+    titleOnly: boolean;
+    showNotAbrogatedDocumentsOnly: boolean;
+    showCommentedDocumentsOnly: boolean;
+    showUnreadDocumentsOnly: boolean;
+    sourceNumber: string;
+    sourceYear: number | null;
+    sourceFrom: Date | null;
+    sourceTo: Date | null;
+    source: string | null;
+    author: string | null;
+    type: string | null;
+    changedNumber: string;
+    changedYear: number | null;
+    changedTitle: string;
+    modifierNumber: string;
+    modifierYear: number | null;
+    modifierTitle: string;
+    changeReason: number | null;
+}
 declare class ClipperBrowserComponent extends ClipperSearchResultManager {
     readonly filterByNumber: _angular_core.Signal<MatInput>;
     readonly filterByText: _angular_core.Signal<MatInput>;
@@ -599,9 +614,46 @@ declare class ClipperBrowserComponent extends ClipperSearchResultManager {
      * Falls back to all modules when `selectableModules` is empty or null.
      */
     protected readonly filteredModules: _angular_core.Signal<NameValueItem<ClipperModule>[]>;
-    protected interval: DateInterval;
-    protected sourceInterval: DateInterval;
     protected user: ClipperUserInfo | undefined;
+    /**
+     * Model backing the filter-pane signal form. This is the single source of truth
+     * for every filter value bound in the template; `filterParams` only carries the
+     * assembled query DTO (see syncParams/loadFilter). Empty values are '' / null /
+     * false / null-array — never undefined, so every child field exists.
+     */
+    protected readonly filterModel: _angular_core.WritableSignal<BrowserFilterModel>;
+    /**
+     * Signal form for the filter pane. The four year fields accept values from 1750
+     * (previously the native min attribute on the inputs).
+     */
+    protected readonly filterForm: _angular_forms_signals.FieldTree<BrowserFilterModel, string | number, "writable">;
+    /** Root signal form for the sort-mode button selector. */
+    protected readonly sortForm: _angular_forms_signals.FieldTree<NameValueItem<ClipperSort>, string | number, "writable">;
+    /** Debounced stream of keyup events on the interval inputs (shorthand typing support). */
+    private readonly intervalKeyup;
+    /**
+     * Applies a partial update to the filter model.
+     * @param patch - The fields to change.
+     */
+    private patchFilter;
+    /**
+     * Blocks the space key on the interval inputs; it is reserved as the
+     * "copy the other bound" shortcut handled by onIntervalKeyup.
+     * @param event - The keydown event from a start or end date input.
+     */
+    protected onIntervalKeydown(event: KeyboardEvent): void;
+    /**
+     * Forwards keyup events of the interval inputs to the debounced shorthand parser.
+     * @param event  - The keyup event from a start or end date input.
+     * @param source - `true` when the event comes from the source-publication range.
+     * @param end    - `true` when the event comes from an end-date input.
+     */
+    protected onIntervalKeyup(event: KeyboardEvent, source: boolean, end: boolean): void;
+    /**
+     * Clears one of the two publication ranges.
+     * @param source - `true` to clear the source-publication range.
+     */
+    protected clearInterval(source?: boolean): void;
     private _viewReady;
     constructor();
     /**
@@ -670,8 +722,29 @@ declare class ClipperBrowserComponent extends ClipperSearchResultManager {
      */
     protected clearFilter(): void;
     /**
-   * Load selected filter
-   */
+     * Copies the filter model into `filterParams`, normalizing empty values back
+     * to the undefined-based convention of ClipperSearchParams.
+     */
+    private syncParams;
+    /**
+     * Commits the form model to filterParams before the component state is serialised.
+     */
+    protected onStateSaving(): void;
+    /**
+     * Rebuilds the form model from filterParams after a state restore.
+     * The publication intervals are intentionally not rebuilt from fromDate/toDate,
+     * matching the historical behavior where the range inputs were not restored.
+     */
+    protected onStateRestored(): void;
+    /**
+     * Builds a DateInterval for the publication range of the current model.
+     * @param source - When true, uses the source-publication range instead.
+     * @returns The interval, with raw (non-normalized) bounds.
+     */
+    private modelInterval;
+    /**
+     * Load selected filter
+     */
     private loadFilter;
     /**
     * Apply current filter params
@@ -1258,11 +1331,16 @@ interface SearchFreeTextQueryParams {
 declare class ClipperSearchFreeTextQueryBuilderComponent {
     readonly done: _angular_core.OutputEmitterRef<SearchFreeTextQueryParams>;
     private readonly dialogService;
-    protected queryAnd: string;
-    protected queryOr: string;
-    protected queryNot: string;
-    protected queryPhrase: string;
-    protected queryStart: string;
+    /** Model backing the signal form: one entry per query operator field. */
+    private readonly model;
+    /** Signal form for the query fields; every field is capped at 200 characters. */
+    protected readonly form: _angular_forms_signals.FieldTree<{
+        queryPhrase: string;
+        queryAnd: string;
+        queryOr: string;
+        queryStart: string;
+        queryNot: string;
+    }, string | number, "writable">;
     /**
      * Resets all query fields to empty strings.
      */

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

@@ -2,6 +2,7 @@ import * as _angular_core from '@angular/core';
 import { OnDestroy } from '@angular/core';
 import { ControlValueAccessor, NgControl } from '@angular/forms';
 import { NameValueItem, INode } from '@arsedizioni/ars-utils/core';
+import * as _angular_forms_signals from '@angular/forms/signals';
 
 declare class ButtonSelectorComponent implements OnDestroy, ControlValueAccessor {
     ngControl: NgControl;
@@ -196,10 +197,18 @@ declare class ChipsSelectorComponent implements OnDestroy, ControlValueAccessor
     private propagateTouched;
     private readonly renderer;
     private readonly cdr;
-    /** Currently selected items (may contain multiple entries when `multiple` is `true`). */
-    protected selection: NameValueItem<any>[];
+    /**
+     * Currently selected items. Kept loosely typed on purpose: in multi-select mode the
+     * bound controls write an array, while in single-select mode mat-select / the chip
+     * listbox write a single item; `getSelection()` normalizes both shapes.
+     */
+    protected readonly selection: _angular_core.WritableSignal<any>;
     /** The single selected item — used in `button` collapsed-display mode. */
-    protected singleSelection?: NameValueItem<any>;
+    protected readonly singleSelection: _angular_core.WritableSignal<NameValueItem<any>>;
+    /** Root signal form bound to the internal mat-select / chip listbox. */
+    protected readonly selectionForm: _angular_forms_signals.FieldTree<any, string | number, "writable">;
+    /** Root signal form bound to the internal button-selector in `button` collapsed mode. */
+    protected readonly singleForm: _angular_forms_signals.FieldTree<NameValueItem<any>, string | number, "writable">;
     constructor(ngControl: NgControl);
     ngOnDestroy(): void;
     /**
@@ -214,7 +223,8 @@ declare class ChipsSelectorComponent implements OnDestroy, ControlValueAccessor
      */
     private getSelection;
     /**
-     * Schedules a value update after a short delay, giving the template time to sync `ngModel`.
+     * Schedules a value update after a short delay, coalescing rapid selection changes
+     * before the value is propagated to the outer form.
      */
     updateValue(): void;
     /**
@@ -319,6 +329,8 @@ declare class TreePickerComponent {
     private _isSelectableNode;
     /** Current filter text. */
     protected readonly filterText: _angular_core.WritableSignal<string>;
+    /** Root signal form bound to the filter text input. */
+    protected readonly filterForm: _angular_forms_signals.FieldTree<string, string | number, "writable">;
     /** Nodes matching the current filter text, in nodeMap iteration order. */
     protected readonly filteredItems: _angular_core.WritableSignal<INode[]>;
     /** Index of the currently highlighted filtered node (-1 = none). */

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

@@ -1,3 +1,4 @@
+import * as _angular_forms_signals from '@angular/forms/signals';
 import * as _angular_core from '@angular/core';
 import { OnDestroy, DoCheck, ElementRef } from '@angular/core';
 import { ControlValueAccessor, NgControl } from '@angular/forms';
@@ -34,10 +35,12 @@ declare class FileInputComponent implements OnDestroy, DoCheck, MatFormFieldCont
     private setValue;
     get value(): FileInfo;
     get size(): any;
-    private _required;
+    /** Backing signal so the internal form schema reacts to `required` changes. */
+    private readonly _required;
     get required(): boolean;
     set required(value: boolean);
-    private _disabled;
+    /** Backing signal so the internal form schema reacts to `disabled` changes. */
+    private readonly _disabled;
     get disabled(): boolean;
     set disabled(value: boolean);
     get placeholder(): string;
@@ -60,6 +63,16 @@ declare class FileInputComponent implements OnDestroy, DoCheck, MatFormFieldCont
     readonly changed: _angular_core.OutputEmitterRef<FileInfo>;
     readonly download: _angular_core.OutputEmitterRef<void>;
     readonly preview: _angular_core.OutputEmitterRef<void>;
+    /** Model backing the internal display form: the (readonly) file-name text. */
+    private readonly nameModel;
+    /**
+     * Internal signal form for the file-name input. It reproduces the previous
+     * template-driven validators: `required` follows the `required` input and the
+     * size rule mirrors FileSizeValidatorDirective (empty name is left to `required`).
+     */
+    protected readonly nameForm: _angular_forms_signals.FieldTree<{
+        name: string;
+    }, string | number, "writable">;
     private propagateChange;
     private propagateTouched;
     constructor(ngControl: NgControl);

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

@@ -1,3 +1,4 @@
+import * as _angular_forms_signals from '@angular/forms/signals';
 import * as _angular_core from '@angular/core';
 
 /** Constants identifying each filter group slot and text filter channels. */
@@ -90,10 +91,18 @@ declare class FilterBarComponent {
     readonly text3Length: _angular_core.InputSignal<string>;
     readonly showTextSearchButton: _angular_core.InputSignal<boolean>;
     readonly appearance: _angular_core.InputSignal<"fill" | "outline">;
-    /** Two-way bindable text filter values. */
+    /**
+     * Text filter values. Empty is represented as '' (never undefined) because the
+     * signals back the [formField] bindings; it is normalized to undefined when
+     * committed to the CurrentFilter.
+     */
     protected readonly text: _angular_core.WritableSignal<string>;
     protected readonly text2: _angular_core.WritableSignal<string>;
     protected readonly text3: _angular_core.WritableSignal<string>;
+    /** Signal forms for the three text inputs (max 100 characters each). */
+    protected readonly textForm: _angular_forms_signals.FieldTree<string, string | number, "writable">;
+    protected readonly text2Form: _angular_forms_signals.FieldTree<string, string | number, "writable">;
+    protected readonly text3Form: _angular_forms_signals.FieldTree<string, string | number, "writable">;
     /** Filter group for slot 1, derived reactively from the `filters` input. */
     protected readonly flt1: _angular_core.Signal<FilterGroup>;
     /** Filter group for slot 2, derived reactively from the `filters` input. */

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

@@ -1,3 +1,4 @@
+import * as _angular_forms_signals from '@angular/forms/signals';
 import * as _angular_core from '@angular/core';
 import { MatPaginator, PageEvent } from '@angular/material/paginator';
 import { ScreenService, SelectableModel } from '@arsedizioni/ars-utils/core';
@@ -12,6 +13,10 @@ declare class SupportNotificationsBrowserComponent {
     private readonly destroyRef;
     protected selection: SelectableModel<SupportNotificationInfo, number>;
     protected searchParams: SupportNotificationsSearchParams;
+    /** Current free-text search value, bound to the search input. */
+    protected readonly searchText: _angular_core.WritableSignal<string>;
+    /** Signal form for the search box (max 200 characters). */
+    protected readonly searchForm: _angular_forms_signals.FieldTree<string, string | number, "writable">;
     protected total: _angular_core.WritableSignal<number>;
     protected items: _angular_core.WritableSignal<SupportNotificationInfo[]>;
     constructor();

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

@@ -2,6 +2,7 @@ import { RawEditorOptions, TinyMCE, Editor } from 'tinymce';
 import * as _angular_core from '@angular/core';
 import { OnInit, OnDestroy } from '@angular/core';
 import { ControlValueAccessor } from '@angular/forms';
+import * as _angular_forms_signals from '@angular/forms/signals';
 
 /**
  * The editor profiles the applications ask for, ready to be handed to
@@ -258,8 +259,13 @@ declare class TinyMceEditorComponent {
     protected readonly dialogData: _angular_core.WritableSignal<TinyMceEditorDialogData>;
     /** Whether the editor is in read-only mode. */
     protected readonly disabled: _angular_core.WritableSignal<boolean>;
-    /** Current editor content, kept as a plain field for [(ngModel)] two-way binding. */
-    protected text: string;
+    /** Current editor content. */
+    protected readonly text: _angular_core.WritableSignal<string>;
+    /**
+     * Signal form bound to the editor textarea. The disabled state is pushed to the
+     * TinymceEditorDirective through the ControlValueAccessor interop.
+     */
+    protected readonly textForm: _angular_forms_signals.FieldTree<string, string | number, "writable">;
     /** The profile handed to the editor directive, merged over its defaults. */
     protected tinymceConfig: RawEditorOptions;
     constructor();