@gnggln/ng-ui-system 1.0.0-alpha.2 → 1.0.0-alpha.21

package/crud-table/lib/components/form-builder/sub-components/specifica-territoriale/specifica-territoriale.component.d.ts

@@ -0,0 +1,145 @@
+import { OnInit, OnDestroy, ChangeDetectorRef, Injector } from '@angular/core';
+import { ControlValueAccessor, FormBuilder, FormGroup, AbstractControl, ValidationErrors, Validator, NgControl } from '@angular/forms';
+import { UiLocationService, UiNazione, UiProvincia, UiComune } from '../../services/location.service';
+import { UiLocationConfig, UiLocationValue } from '../../types/territoriale.types';
+import * as i0 from "@angular/core";
+/**
+ * Interfaccia interna per i CAP nel componente.
+ */
+interface UiCapOption {
+    /** ID del CAP. */
+    id: string;
+    /** Codice CAP visualizzato. */
+    codice: string;
+    /** ID del comune associato. */
+    comuneId: string;
+}
+/**
+ * Componente standalone per la selezione di dati geografici italiani o esteri.
+ *
+ * Supporta due modalita:
+ * - **Italia**: selezione a cascata nazione -> provincia -> comune -> CAP
+ * - **Estero**: selezione nazione + campo testo libero per il comune
+ *
+ * Campi opzionali configurabili: indirizzo, mail, PEC, telefono.
+ *
+ * Implementa `ControlValueAccessor` e `Validator` per l'integrazione
+ * diretta con Angular Reactive Forms.
+ *
+ * Utilizza dati da JSON statici tramite `UiLocationService`
+ * (nessuna dipendenza al backend).
+ *
+ * @selector ui-specifica-territoriale
+ *
+ * @example
+ * ```html
+ * <ui-specifica-territoriale
+ *   [formControl]="myControl"
+ *   [config]="{ italyByDefault: true, cap: { show: true } }"
+ * />
+ * ```
+ */
+export declare class UiSpecificaTerritorialeComponent implements ControlValueAccessor, Validator, OnInit, OnDestroy {
+    private readonly fb;
+    private readonly injector;
+    private readonly cdr;
+    private readonly locationService;
+    /** Configurazione del componente. */
+    config: UiLocationConfig;
+    /** Stato disabilitato globale. */
+    disabled: boolean;
+    private readonly EMAIL_PATTERN;
+    private readonly PEC_PATTERN;
+    private readonly PHONE_PATTERN;
+    form: FormGroup;
+    isItalian: boolean;
+    isForeign: boolean;
+    ngControl: NgControl;
+    /** Elenco nazioni disponibili. */
+    nazioni: UiNazione[];
+    /** Elenco province disponibili. */
+    province: UiProvincia[];
+    /** Comuni filtrati per la provincia selezionata. */
+    filteredComuni: UiComune[];
+    /** CAP filtrati per il comune selezionato. */
+    filteredCaps: UiCapOption[];
+    /** Promise di inizializzazione (utile per test e table-territoriale). */
+    initializationPromise: Promise<void> | null;
+    private readonly destroy$;
+    private onChange;
+    private onTouched;
+    private onValidatorChange;
+    private subscriptionsInitialized;
+    private pendingWriteValue;
+    private isInitializing;
+    private tipologicheLoaded;
+    constructor(fb: FormBuilder, injector: Injector, cdr: ChangeDetectorRef, locationService: UiLocationService);
+    ngOnInit(): void;
+    ngOnDestroy(): void;
+    writeValue(value: UiLocationValue | null): void;
+    registerOnChange(fn: (value: UiLocationValue) => void): void;
+    registerOnTouched(fn: () => void): void;
+    registerOnValidatorChange(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    validate(_control: AbstractControl): ValidationErrors | null;
+    /** Marca tutti i controlli interni come touched. */
+    markAsTouched(): void;
+    /** Verifica se mostrare gli errori per un campo interno. */
+    shouldShowFieldErrors(fieldKey: string): boolean;
+    /** Errori di un campo interno come array di messaggi. */
+    getFieldErrors(fieldKey: string): string[];
+    /** Handler blur per propagare il touched. */
+    onBlur(): void;
+    /** Resetta lo stato del componente. */
+    resetComponentState(): void;
+    /** Labels personalizzabili con valori di default. */
+    get labels(): {
+        nazione: string;
+        provincia: string;
+        comune: string;
+        cap: string;
+        indirizzo: string;
+        comuneEstero: string;
+        mail: string;
+        pec: string;
+        telefono: string;
+    };
+    get hasValidationErrors(): boolean;
+    get validationErrors(): string[];
+    get showCAP(): boolean;
+    get showIndirizzo(): boolean;
+    get showMail(): boolean;
+    get showPEC(): boolean;
+    get showTelefono(): boolean;
+    get capColumns(): number;
+    get indirizzoColumns(): number;
+    get mailColumns(): number;
+    get pecColumns(): number;
+    get telefonoColumns(): number;
+    get isItalyByDefault(): boolean;
+    get isCapDisabled(): boolean;
+    get isNazioneDisabled(): boolean;
+    get isRequired(): boolean;
+    private initializeComponent;
+    private initializeForm;
+    private setupNgControl;
+    private loadLocationData;
+    private processWriteValue;
+    private handleItalyByDefaultValue;
+    private setupFormSubscriptions;
+    private handleTerritorialChanges;
+    private updateNationalityState;
+    private updateTerritorialData;
+    private updateFilteredComuni;
+    private updateFilteredCaps;
+    private updateComponentState;
+    private applyFieldsDisabledState;
+    private updateValidators;
+    private applyContactValidators;
+    private validateContactFields;
+    private applyInitialConfiguration;
+    private notifyValidationChange;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiSpecificaTerritorialeComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiSpecificaTerritorialeComponent, "ui-specifica-territoriale", never, { "config": { "alias": "config"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; }, {}, never, never, true, never>;
+}
+export {};

package/crud-table/lib/components/form-builder/sub-components/table-territoriale/table-territoriale.component.d.ts

@@ -0,0 +1,108 @@
+import { OnInit, OnDestroy, OnChanges, SimpleChanges, ChangeDetectorRef, Injector } from '@angular/core';
+import { ControlValueAccessor, Validator, AbstractControl, ValidationErrors, NgControl } from '@angular/forms';
+import { MatTableDataSource } from '@angular/material/table';
+import { UiSpecificaTerritorialeComponent } from '../specifica-territoriale/specifica-territoriale.component';
+import { UiLocationService } from '../../services/location.service';
+import { UiButtonDescriptor } from '../../../button/index';
+import { UiLocationTableConfig, UiLocationRow } from '../../types/territoriale.types';
+import * as i0 from "@angular/core";
+/**
+ * Componente standalone per la gestione tabellare di location multiple.
+ *
+ * Permette l'inserimento, la modifica e l'eliminazione di righe
+ * territoriali (italiane o estere) tramite una tabella Material
+ * con form inline basato su `UiSpecificaTerritorialeComponent`.
+ *
+ * Implementa `ControlValueAccessor` e `Validator` per l'integrazione
+ * con Angular Reactive Forms. Il valore e un array di `UiLocationRow`.
+ *
+ * @selector ui-table-territoriale
+ *
+ * @example
+ * ```html
+ * <ui-table-territoriale
+ *   [formControl]="sedeControl"
+ *   [config]="{
+ *     tableLabel: 'Sedi operative',
+ *     subFieldConfig: { italyByDefault: true, cap: { show: true } }
+ *   }"
+ * />
+ * ```
+ */
+export declare class UiTableTerritorialeComponent implements ControlValueAccessor, Validator, OnInit, OnDestroy, OnChanges {
+    private readonly cdr;
+    private readonly injector;
+    private readonly locationService;
+    /** Configurazione della tabella. */
+    config: UiLocationTableConfig;
+    /** Stato disabilitato globale. */
+    disabled: boolean;
+    /** Righe della tabella. */
+    rows: UiLocationRow[];
+    /** DataSource Material per la tabella. */
+    dataSource: MatTableDataSource<UiLocationRow, import("@angular/material/paginator").MatPaginator>;
+    /** Modalita editing attiva. */
+    editMode: boolean;
+    /** Modalita inserimento attiva. */
+    insertMode: boolean;
+    /** Riga in modifica. */
+    editingRow: UiLocationRow | null;
+    /** Indice della riga in modifica. */
+    editingIndex: number | null;
+    /** Colonne visualizzate nella tabella. */
+    displayedColumns: string[];
+    /** Configurazione delle colonne. */
+    columnConfig: Record<string, {
+        label: string;
+        show: boolean;
+    }>;
+    /** Pulsanti per il form di inserimento/modifica. */
+    formButtons: UiButtonDescriptor[];
+    /** Pulsante per aggiungere una nuova riga. */
+    addButton: UiButtonDescriptor[];
+    /** NgControl per accedere alla validazione del form parent. */
+    ngControl: NgControl | null;
+    specificaForm: UiSpecificaTerritorialeComponent;
+    private readonly destroy$;
+    private onChange;
+    private onTouched;
+    private onValidatorChange;
+    constructor(cdr: ChangeDetectorRef, injector: Injector, locationService: UiLocationService);
+    ngOnInit(): void;
+    ngOnChanges(changes: SimpleChanges): void;
+    ngOnDestroy(): void;
+    writeValue(value: UiLocationRow[] | null): void;
+    registerOnChange(fn: (value: UiLocationRow[]) => void): void;
+    registerOnTouched(fn: () => void): void;
+    setDisabledState(isDisabled: boolean): void;
+    validate(control: AbstractControl): ValidationErrors | null;
+    get isRequired(): boolean;
+    get hasValidationErrors(): boolean;
+    get validationErrors(): string[];
+    private initializeColumns;
+    /** Attiva la modalita inserimento. */
+    activateInsertMode(): void;
+    /** Attiva la modalita modifica per una riga. */
+    editRow(row: UiLocationRow, index: number): void;
+    /** Annulla l'operazione in corso (inserimento o modifica). */
+    cancelEdit(): void;
+    /** Rimuove una riga dalla tabella. */
+    removeRow(index: number): void;
+    /** Salva la riga corrente (nuova o in modifica). */
+    saveRow(): Promise<void>;
+    /** Marca il componente come touched. */
+    markAsTouched(): void;
+    /** Resetta lo stato del componente. */
+    resetComponentState(): void;
+    /** Funzione track by per la tabella. */
+    trackByFn(_index: number, item: UiLocationRow): string;
+    private mapRowToFormValue;
+    private mapFormValueToRow;
+    private propagateChange;
+    private generateUUID;
+    private calculateActions;
+    private calculateFormButtons;
+    private calculateAddButton;
+    static ɵfac: i0.ɵɵFactoryDeclaration<UiTableTerritorialeComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<UiTableTerritorialeComponent, "ui-table-territoriale", never, { "config": { "alias": "config"; "required": false; }; "disabled": { "alias": "disabled"; "required": false; }; }, {}, never, never, true, never>;
+}

package/crud-table/lib/components/form-builder/types/condition.types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * @module ng-ui-system/form-builder
+ * Tipi per il sistema di condizioni (visibilita, required, disable).
+ */
+/**
+ * Operatori di confronto supportati dal sistema di condizioni.
+ *
+ * | Operatore        | Descrizione                                |
+ * |------------------|--------------------------------------------|
+ * | `equals`         | Uguale a `value`                           |
+ * | `not_equals`     | Diverso da `value`                         |
+ * | `contains`       | La stringa contiene `value`                |
+ * | `not_contains`   | La stringa non contiene `value`            |
+ * | `greater_than`   | Maggiore di `value` (numerico)             |
+ * | `less_than`      | Minore di `value` (numerico)               |
+ * | `greater_equal`  | Maggiore o uguale a `value`                |
+ * | `less_equal`     | Minore o uguale a `value`                  |
+ * | `is_empty`       | Il campo e vuoto/null/undefined            |
+ * | `is_not_empty`   | Il campo ha un valore non vuoto            |
+ * | `in_array`       | Il valore e presente nell'array `value`    |
+ * | `not_in_array`   | Il valore non e presente nell'array `value`|
+ */
+export type UiConditionalOperator = 'equals' | 'not_equals' | 'contains' | 'not_contains' | 'greater_than' | 'less_than' | 'greater_equal' | 'less_equal' | 'is_empty' | 'is_not_empty' | 'in_array' | 'not_in_array';
+/**
+ * Condizione per il rendering condizionale dei campi.
+ *
+ * Piu condizioni possono essere combinate con logica AND/OR.
+ * Default: AND (tutte le condizioni devono essere vere).
+ *
+ * @example
+ * ```typescript
+ * // Campo visibile solo se 'tipo' == 'persona-fisica'
+ * conditions: [{ field: 'tipo', operator: 'equals', value: 'persona-fisica' }]
+ *
+ * // Combinazione AND/OR
+ * conditions: [
+ *   { field: 'stato', operator: 'equals', value: 'attivo', logic: 'AND' },
+ *   { field: 'ruolo', operator: 'in_array', value: ['admin', 'editor'] },
+ * ]
+ * ```
+ */
+export interface UiFieldCondition {
+    /** Chiave del campo da valutare. Supporta dot notation (es. `'address.city'`). */
+    field: string;
+    /** Operatore di confronto. */
+    operator: UiConditionalOperator;
+    /** Valore di confronto (opzionale per `is_empty`/`is_not_empty`). */
+    value?: any;
+    /** Logica di combinazione con le altre condizioni. @default 'AND' */
+    logic?: 'AND' | 'OR';
+}

package/crud-table/lib/components/form-builder/types/field.types.d.ts

@@ -0,0 +1,330 @@
+/**
+ * @module ng-ui-system/form-builder
+ * Tipi relativi ai campi del form builder.
+ */
+import type { FormControl, FormGroup } from '@angular/forms';
+import { Observable } from 'rxjs';
+import { UiIconName } from '../../../core/types';
+import type { UiLocationGeocodedFieldConfig } from './geocoded-location.types';
+export { UiIconName };
+/**
+ * Tipi di campo supportati dal form builder.
+ *
+ * | Tipo              | Descrizione                                       |
+ * |-------------------|---------------------------------------------------|
+ * | `text`            | Input testuale generico                           |
+ * | `email`           | Input email con validazione formato               |
+ * | `password`        | Input password con oscuramento                    |
+ * | `number`          | Input numerico (supporta currency directive)       |
+ * | `textarea`        | Area di testo multi-riga                          |
+ * | `select`          | Select singola (con autocomplete opzionale)        |
+ * | `multiselect`     | Select multipla con chips e autocomplete           |
+ * | `freemultiselect` | Multiselect a testo libero con chips               |
+ * | `checkbox`        | Checkbox (puo renderizzare come switch)            |
+ * | `switch`          | Toggle switch (mat-slide-toggle)                   |
+ * | `radio`           | Gruppo radio button (supporta icone)               |
+ * | `date`            | Date picker (supporta vista mese/anno)             |
+ * | `datetime`        | Date e time picker combinato                       |
+ * | `file`            | Upload file con drag & drop e preview              |
+ * | `divider`         | Separatore visuale (nessun valore nel form)        |
+ * | `flag`            | Campo nascosto per logica interna (sempre readonly)|
+ * | `custom`          | Extension point per componenti custom              |
+ * | `location`        | Selezione territorio (nazione/provincia/comune/CAP)|
+ * | `location-table`  | Tabella CRUD di location multiple                  |
+ * | `location-geocoded` | Indirizzo libero con autocomplete geocodificato   |
+ */
+export type UiFieldType = 'text' | 'email' | 'password' | 'number' | 'textarea' | 'select' | 'multiselect' | 'freemultiselect' | 'checkbox' | 'switch' | 'radio' | 'date' | 'datetime' | 'file' | 'divider' | 'flag' | 'custom' | 'location' | 'location-table' | 'location-geocoded';
+/**
+ * Singola opzione per campi select, radio, multiselect.
+ */
+export interface UiFieldOption {
+    /** Valore dell'opzione (chiave logica). */
+    value: any;
+    /** Etichetta visualizzata all'utente. */
+    label: string;
+    /** Disabilita l'opzione nella lista. */
+    disabled?: boolean;
+    /** Metadati aggiuntivi associati all'opzione. */
+    metadata?: Record<string, any>;
+    /** Icona Lucide da mostrare accanto alla label. */
+    icon?: UiIconName;
+    /** Tooltip al passaggio del mouse. */
+    tooltip?: string;
+}
+/**
+ * Generazione dinamica di opzioni.
+ * Supporta generatori predefiniti (es. range anni) o funzioni custom.
+ *
+ * @example
+ * ```typescript
+ * // Range anni dall'anno corrente a 5 anni fa
+ * dynamicOptions: { type: 'year-range', minYear: 2020, maxYear: 2026 }
+ *
+ * // Generatore custom
+ * dynamicOptions: { type: 'custom', generator: (formData) => [...] }
+ * ```
+ */
+export interface UiDynamicOptionsConfig {
+    /** Tipo di generazione. */
+    type: 'year-range' | 'custom';
+    /** Anno minimo (per `year-range`). */
+    minYear?: number;
+    /** Anno massimo (per `year-range`, default: anno corrente). */
+    maxYear?: number;
+    /** Funzione custom per generare le opzioni. */
+    generator?: (formData: Record<string, any>) => UiFieldOption[];
+}
+/**
+ * Filtraggio opzioni basato sul valore di un altro campo.
+ *
+ * @example
+ * ```typescript
+ * // Mostra solo anni >= dell'anno selezionato in 'anno-inizio'
+ * dependentOptions: {
+ *   dependsOn: 'anno-inizio',
+ *   filterType: 'greater_equal',
+ * }
+ * ```
+ */
+export interface UiDependentOptionsConfig {
+    /** Chiave del campo da cui dipendono le opzioni. */
+    dependsOn: string;
+    /** Tipo di filtro predefinito da applicare. */
+    filterType: 'greater_than' | 'greater_equal' | 'less_than' | 'less_equal' | 'equals' | 'not_equals' | 'custom';
+    /** Funzione custom per filtrare le opzioni. */
+    filterFn?: (option: UiFieldOption, dependentValue: any, formData: Record<string, any>) => boolean;
+    /** Messaggio mostrato se nessuna opzione disponibile dopo il filtro. */
+    noOptionsMessage?: string;
+    /** Se `true`, disabilita le opzioni filtrate invece di nasconderle. */
+    disableInsteadOfHide?: boolean;
+}
+/**
+ * Configurazione per tooltip con icona affiancata al campo.
+ */
+export interface UiIconTooltip {
+    /** Testo visualizzato nel tooltip. */
+    text: string;
+    /** Icona Lucide da mostrare. @default 'info' */
+    icon?: UiIconName;
+    /** Classe CSS aggiuntiva per il tooltip. */
+    tooltipClass?: string;
+}
+/**
+ * Dati di un singolo file gestito dal componente file input.
+ */
+export interface UiFileData {
+    /** Nome del file. */
+    filename: string;
+    /** Contenuto del file come byte array. */
+    content: Uint8Array;
+    /** Tipo MIME del file. */
+    mimeType: string;
+    /** Estensione del file (es. `pdf`, `jpg`). */
+    extension: string;
+    /** Dimensione del file in bytes. */
+    size: number;
+    /** Flag che indica se il file deve essere ancora caricato. */
+    needsUpload: boolean;
+    /** ID univoco per tracciamento interno. */
+    id?: string;
+    /** URL per l'anteprima (immagini/PDF). */
+    previewUrl?: string;
+    /** Timestamp di creazione/modifica. */
+    timestamp?: Date;
+    /** ID del file sul server (per file gia caricati). */
+    serverFileId?: number;
+    /** Path del file sul server (per file gia caricati). */
+    serverPath?: string;
+}
+/**
+ * Configurazione per il campo file input.
+ */
+export interface UiFileInputConfig {
+    /** Dimensione massima per singolo file in bytes. */
+    maxFileSize?: number;
+    /** Tipi MIME accettati (es. `['application/pdf', 'image/*']`). */
+    acceptedTypes?: string[];
+    /** Numero massimo di file caricabili. */
+    maxFiles?: number;
+    /** Abilita selezione multipla. */
+    multiple?: boolean;
+    /** Mostra anteprime per immagini e PDF. */
+    showPreview?: boolean;
+    /** Abilita drag & drop. @default true */
+    enableDragDrop?: boolean;
+    /** Testo placeholder quando nessun file e selezionato. */
+    placeholder?: string;
+    /** Testo mostrato nell'area drag & drop. */
+    dragDropText?: string;
+}
+/**
+ * Configurazione per componenti custom iniettati nel form.
+ * Permette di estendere il form builder con componenti applicativi.
+ *
+ * @example
+ * ```typescript
+ * customConfig: {
+ *   component: 'my-location-picker',
+ *   config: { showMap: true, zoom: 12 },
+ * }
+ * ```
+ */
+export interface UiCustomComponentConfig {
+    /** Selettore logico o nome del widget (documentazione / tooling). */
+    component: string;
+    /**
+     * Chiave per risolvere il template in `customFieldTemplates` sul form builder.
+     * Se assente si usa `component`, poi la chiave del campo (`field.key`).
+     */
+    templateKey?: string;
+    /** Input da passare al componente. */
+    inputs?: Record<string, any>;
+    /** Output da ascoltare dal componente. */
+    outputs?: Record<string, string>;
+    /** Configurazione specifica del componente. */
+    config?: Record<string, any>;
+}
+/**
+ * Contesto passato a `ngTemplateOutlet` per i campi `type: 'custom'`.
+ * Il componente proiettato dovrebbe collegare il valore tramite `control`
+ * (idealmente implementando `ControlValueAccessor` o `[formControl]`).
+ */
+export interface UiCustomFieldTemplateContext {
+    /** Stesso di `field` (valore implicito per `let-field` nel template). */
+    $implicit: UiFormFieldDescriptor;
+    /** Descrittore del campo. */
+    field: UiFormFieldDescriptor;
+    /** FormGroup del contesto (root o istanza repeatable). */
+    formGroup: FormGroup;
+    /** `FormControl` del campo (`formGroup.get(field.key)`). */
+    control: FormControl;
+    /** Configurazione da `customConfig.config`. */
+    config: Record<string, any>;
+    /**
+     * Prefisso per chiavi errore/scroll dei campi interni al CVA
+     * (es. `step9[0].sezioneRepertorioRegionale__`).
+     */
+    nestedErrorKeyPrefix?: string;
+    /** Notifica eventi applicativi (inoltrati come `customEvent` dal form builder). */
+    emitCustomEvent: (event: string, data?: any) => void;
+}
+/**
+ * Interfaccia legacy per integrazione imperativa (callback).
+ * Preferire `ControlValueAccessor` sul controllo del campo e il contesto
+ * `UiCustomFieldTemplateContext` tramite template outlet.
+ */
+export interface UiCustomFormComponent {
+    /** Valore corrente del componente. */
+    value: any;
+    /** Stato disabilitato. */
+    disabled: boolean;
+    /** Configurazione ricevuta dal descriptor. */
+    config: Record<string, any>;
+    /** Callback per notificare cambiamenti di valore. */
+    onChange: (value: any) => void;
+    /** Callback per emettere eventi custom. */
+    onEvent: (event: string, data: any) => void;
+}
+/**
+ * Descrittore completo di un campo del form.
+ *
+ * Definisce tipo, label, validazione, condizioni di visibilita,
+ * opzioni per select/radio e ogni altra configurazione necessaria
+ * per il rendering e la logica del campo.
+ *
+ * @example
+ * ```typescript
+ * const field: UiFormFieldDescriptor = {
+ *   key: 'email',
+ *   type: 'email',
+ *   label: 'Indirizzo email',
+ *   placeholder: 'nome@esempio.it',
+ *   required: true,
+ *   validation: [
+ *     { type: 'required', message: 'Campo obbligatorio' },
+ *     { type: 'email', message: 'Formato email non valido' },
+ *   ],
+ * };
+ * ```
+ */
+export interface UiFormFieldDescriptor {
+    /** Chiave univoca del campo nel FormGroup. */
+    key: string;
+    /** Tipo di campo da renderizzare. */
+    type: UiFieldType;
+    /** Etichetta visualizzata sopra/accanto al campo. */
+    label: string;
+    /** Testo placeholder. */
+    placeholder?: string;
+    /** Tooltip testuale per il campo. */
+    tooltip?: string;
+    /** Configurazione tooltip con icona. */
+    iconTooltip?: UiIconTooltip;
+    /** Valore di default. */
+    defaultValue?: any;
+    /** Se il campo e obbligatorio (shortcut per validazione `required`). */
+    required?: boolean;
+    /** Se il campo e disabilitato. */
+    disabled?: boolean;
+    /** Se il campo e in sola lettura. */
+    readonly?: boolean;
+    /** Regole di validazione. @see UiValidationRule */
+    validation?: import('./validation.types').UiValidationRule[];
+    /** Opzioni statiche o osservabili. */
+    options?: UiFieldOption[] | Observable<UiFieldOption[]>;
+    /** Nasconde l'opzione vuota iniziale nelle select. */
+    hideEmptyOption?: boolean;
+    /** Trasforma la select in autocomplete con ricerca. */
+    searchable?: boolean;
+    /** Mostra pulsante "Seleziona tutto" per multiselect. */
+    allowSelectAll?: boolean;
+    /**
+     * Con `searchable: true` su `select`/`text`, ogni `input` dell'autocomplete
+     * invoca la callback: il risultato sostituisce l'elenco opzioni mostrato.
+     */
+    asyncOptions?: (query: string) => Promise<UiFieldOption[]>;
+    /**
+     * Contratto per risolvere opzioni da id (es. prefill da API). Il Form Builder
+     * Angular attuale non invoca questa callback; l'app può comporre le opzioni
+     * in `options` o collegarla a logica custom.
+     */
+    recoverAsyncValues?: (ids: any[]) => Promise<UiFieldOption[]>;
+    /** Generazione dinamica di opzioni. */
+    dynamicOptions?: UiDynamicOptionsConfig;
+    /** Filtraggio opzioni dipendente da altro campo. */
+    dependentOptions?: UiDependentOptionsConfig;
+    /** Condizioni per la visibilita del campo. */
+    conditions?: import('./condition.types').UiFieldCondition[];
+    /** Condizioni per disabilitare il campo. */
+    disableConditions?: import('./condition.types').UiFieldCondition[];
+    /** Congela il valore quando il campo viene disabilitato da `disableConditions`. */
+    freezeValueOnDisable?: boolean;
+    /** Configurazione per componenti custom. */
+    customConfig?: UiCustomComponentConfig;
+    /** Configurazione per il campo file. */
+    fileConfig?: UiFileInputConfig;
+    /** Configurazione per il campo `location-geocoded` (Nominatim / proxy). */
+    locationGeocodedConfig?: UiLocationGeocodedFieldConfig;
+    /** Configurazione aspetto del campo. */
+    appearance?: {
+        /** Per checkbox: 'switch' rende il campo come mat-slide-toggle. */
+        style?: 'default' | 'switch';
+        /** Colore del componente. */
+        color?: 'primary' | 'accent' | 'warn';
+    };
+    /** Classi CSS aggiuntive sul wrapper del campo. */
+    cssClasses?: string[];
+    /** Attributi HTML aggiuntivi. */
+    attributes?: Record<string, any>;
+    /** Metadati arbitrari (chips protetti, configurazioni extra, etc.). */
+    metadata?: Record<string, any>;
+    /** Configurazione layout del campo nel grid. */
+    layout?: {
+        /** Numero di colonne che il campo occupa (default: dipende dal tipo). */
+        columns?: number;
+        /** Ordine nel grid. */
+        order?: number;
+        /** Override colonne per breakpoint (`{ md: 6, lg: 4 }`). */
+        breakpoints?: Record<string, number>;
+    };
+}