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

package/form-builder/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>;
+    };
+}

package/form-builder/lib/components/form-builder/types/geocoded-location.types.d.ts

@@ -0,0 +1,116 @@
+/**
+ * @module ng-ui-system/form-builder
+ * Tipi per il campo `location-geocoded` (indirizzo con geocoding).
+ */
+/**
+ * Dettaglio minimo per una sede **italiana** (allineato a comune / provincia / regione).
+ * Popolato solo se {@link UiGeocodedLocationType.territory} è `'italian'`.
+ */
+export interface UiGeocodedItalianDetails {
+    /** Comune (o equivalente censuario). */
+    comune?: string;
+    /**
+     * Provincia: nome o sigla se restituita dal provider (es. da `county` Nominatim).
+     */
+    provincia?: string;
+    /** Regione. */
+    regione?: string;
+}
+/**
+ * Dettaglio minimo per una sede **estera** (struttura generica, indipendente dal paese).
+ * Popolato solo se {@link UiGeocodedLocationType.territory} è `'foreign'`.
+ */
+export interface UiGeocodedForeignDetails {
+    /** Località principale (città, town, ecc.). */
+    locality?: string;
+    /** Area amministrativa (stato federato, Land, contea, ecc.). */
+    adminArea?: string;
+    /** Codice paese ISO 3166-1 alpha-2 (ridondante con il campo radice se già presente). */
+    countryCode?: string;
+}
+/**
+ * Valore atomico restituito dal campo geocodificato.
+ * Struttura indipendente dal provider; la mappatura avviene nel servizio di ricerca.
+ *
+ * Usa {@link territory} e i blocchi `italian` / `foreign` per logiche diverse (es. validazione,
+ * persistenza); i campi piatti (`city`, `province`, …) restano per compatibilità e uso generico.
+ */
+export interface UiGeocodedLocationType {
+    /** Etichetta principale mostrata all'utente. */
+    label: string;
+    /** Latitudine WGS84. */
+    latitude: number;
+    /** Longitudine WGS84. */
+    longitude: number;
+    /** Indirizzo formattato completo. */
+    formattedAddress: string;
+    /**
+     * Ambito territoriale dedotto dal paese (ISO): Italia vs resto del mondo.
+     * Se il provider non fornisce `country_code`, si assume `'foreign'`.
+     */
+    territory: 'italian' | 'foreign';
+    /**
+     * Dettaglio strutturato per sedi italiane. Assente se `territory === 'foreign'`.
+     */
+    italian?: UiGeocodedItalianDetails;
+    /**
+     * Dettaglio strutturato per sedi non italiane. Assente se `territory === 'italian'`.
+     */
+    foreign?: UiGeocodedForeignDetails;
+    street?: string;
+    streetNumber?: string;
+    postalCode?: string;
+    city?: string;
+    municipality?: string;
+    province?: string;
+    region?: string;
+    country?: string;
+    countryCode?: string;
+    placeId?: string;
+    /** Affidabilità stimata del risultato (0–1), se disponibile dal provider. */
+    confidence?: number;
+    boundingBox?: {
+        north: number;
+        south: number;
+        east: number;
+        west: number;
+    };
+    source?: 'nominatim' | 'pelias' | 'mapbox' | 'google' | 'custom';
+    /** Payload grezzo del provider (debug / integrazioni avanzate). */
+    raw?: unknown;
+}
+/**
+ * Valore accettato da `ControlValueAccessor.writeValue` quando i dati persistiti
+ * possono non includere ancora `territory` (versioni precedenti del modello).
+ */
+export type UiGeocodedLocationInput = Omit<UiGeocodedLocationType, 'territory'> & {
+    territory?: 'italian' | 'foreign';
+};
+/**
+ * Configurazione del campo `location-geocoded` nello schema del form.
+ */
+export interface UiLocationGeocodedFieldConfig {
+    /**
+     * Base URL dell'endpoint di ricerca (senza slash finale).
+     * Per Nominatim: `https://nominatim.openstreetmap.org` oppure, in sviluppo,
+     * un proxy same-origin (es. `/nominatim`) per rispettare CORS e User-Agent.
+     * @default 'https://nominatim.openstreetmap.org'
+     */
+    nominatimBaseUrl?: string;
+    /** Numero minimo di caratteri prima di avviare la ricerca. @default 3 */
+    minChars?: number;
+    /** Debounce sulla digitazione in millisecondi. @default 200 */
+    debounceMs?: number;
+    /** Numero massimo di suggerimenti. @default 5 */
+    limit?: number;
+    /**
+     * Codice ISO paese per **limitare** i risultati (parametro Nominatim `countrycodes`).
+     * Se omesso, la ricerca è **mondiale** (nessun filtro paese).
+     */
+    biasCountry?: string;
+    /** Punto di riferimento per ordinare i risultati (`viewbox` Nominatim). */
+    biasProximity?: {
+        lat: number;
+        lng: number;
+    };
+}

package/form-builder/lib/components/form-builder/types/index.d.ts

@@ -0,0 +1,6 @@
+export { UiFieldType, UiFieldOption, UiDynamicOptionsConfig, UiDependentOptionsConfig, UiIconTooltip, UiFileData, UiFileInputConfig, UiCustomComponentConfig, UiCustomFieldTemplateContext, UiCustomFormComponent, UiFormFieldDescriptor, } from './field.types';
+export { UiCrossFieldOperator, UiCrossFieldConfig, UiDateKeyword, UiDateValidationConfig, UiValidationType, UiValidationRule, UiFormValidationState, UiFormErrorDetail, UI_FORM_NESTED_FIELD_ERRORS_KEY, } from './validation.types';
+export { UiConditionalOperator, UiFieldCondition, } from './condition.types';
+export { UiLocationFieldConfig, UiLocationConfig, UiLocationLabels, UiLocationValue, UiLocationTableConfig, UiLocationRow, } from './territoriale.types';
+export { UiGeocodedLocationType, UiGeocodedLocationInput, UiGeocodedItalianDetails, UiGeocodedForeignDetails, UiLocationGeocodedFieldConfig, } from './geocoded-location.types';
+export { UiRepeatableConfig, UiWizardStepValidation, UiWizardValidationFn, UiWizardStepConfig, UiFormSection, UiFormBuilderConfig, UiWizardConfig, UiWizardState, UiFormSchema, UiFormData, UiFormCustomEvent, UiWizardStepChangeEvent, UiWizardStepCompleteEvent, } from './schema.types';