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

package/crud-table/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/crud-table/lib/components/form-builder/types/schema.types.d.ts

@@ -0,0 +1,304 @@
+/**
+ * @module ng-ui-system/form-builder
+ * Tipi per lo schema del form, sezioni e configurazione.
+ */
+import { UiFormFieldDescriptor } from './field.types';
+import { UiFieldCondition } from './condition.types';
+import { UiIconName } from '../../../core/types';
+/**
+ * Configurazione di validazione per un singolo step del wizard.
+ */
+export interface UiWizardStepValidation {
+    /** Se lo step richiede validazione prima di procedere. @default true */
+    required?: boolean;
+    /** Campi specifici da validare in questo step (se omesso, tutti i campi dello step). */
+    validateFields?: string[];
+    /**
+     * Se `false`, nella navigazione wizard i campi `type: 'custom'` non concorrono
+     * alla validità dello step (e i loro errori non bloccano il passaggio).
+     * @default true
+     */
+    validateCustomComponents?: boolean;
+}
+/**
+ * Funzione di validazione custom per uno step del wizard.
+ * Viene invocata prima della navigazione allo step successivo.
+ *
+ * @param formData - Dati correnti del form completo.
+ * @param currentStep - Indice dello step corrente (0-based).
+ * @param isValid - Risultato della validazione standard del form.
+ * @returns `true` per permettere la navigazione, `false` per bloccarla.
+ */
+export type UiWizardValidationFn = (formData: Record<string, any>, currentStep: number, isValid: boolean) => Promise<boolean> | boolean;
+/**
+ * Configurazione wizard per una sezione del form.
+ */
+export interface UiWizardStepConfig {
+    /** Numero dello step (1-based per UI, convertito a 0-based internamente). */
+    stepNumber: number;
+    /** Titolo personalizzato per lo step. */
+    stepTitle?: string;
+    /** Descrizione dello step. */
+    stepDescription?: string;
+    /** Configurazione di validazione per questo step. */
+    validation?: UiWizardStepValidation;
+    /** Permette di saltare questo step senza validazione. */
+    allowSkip?: boolean;
+    /** Nome del metodo di validazione custom (deve essere registrato nel wizard). */
+    customValidationFn?: string;
+    /** Metadati aggiuntivi per lo step. */
+    metadata?: Record<string, any>;
+}
+/**
+ * Configurazione per sezioni ripetibili (dynamic repeater).
+ * Permette di aggiungere/rimuovere/duplicare N istanze di un blocco
+ * di campi, con il modello reattivo gestito tramite FormArray.
+ *
+ * @example
+ * ```typescript
+ * const section: UiFormSection = {
+ *   id: 'obiettivi',
+ *   title: 'Obiettivi formativi',
+ *   repeatable: {
+ *     min: 1,
+ *     max: 10,
+ *     addLabel: 'Aggiungi obiettivo',
+ *     addIcon: 'plus',
+ *     instanceTitle: 'Obiettivo {index}',
+ *   },
+ *   fields: [ ... ],
+ * };
+ * ```
+ */
+export interface UiRepeatableConfig {
+    /**
+     * Numero minimo di istanze obbligatorie.
+     * Se `min > 0`, alla creazione del form vengono pre-create almeno `min` istanze
+     * (vuote o da `initialData[sectionId]`). Se omesso, vale `1`.
+     * Con `min: 0` non si aggiungono righe oltre a quelle già presenti in `initialData`.
+     */
+    min?: number;
+    /** Numero massimo di istanze (undefined = illimitato). */
+    max?: number;
+    /** Label per il pulsante "Aggiungi". @default '+ Aggiungi' */
+    addLabel?: string;
+    /** Icona Lucide per il pulsante "Aggiungi". @default 'plus' */
+    addIcon?: UiIconName;
+    /** Template per il titolo di ogni istanza. `{index}` viene sostituito con l'indice 1-based. */
+    instanceTitle?: string;
+    /** Se richiedere conferma prima della rimozione. @default false */
+    confirmRemove?: boolean;
+    /** Messaggio di conferma rimozione. @default 'Sei sicuro di voler rimuovere questa sezione?' */
+    confirmMessage?: string;
+}
+/**
+ * Sezione del form che raggruppa campi correlati.
+ * Supporta collapsibilita (accordion), condizioni di visibilita,
+ * configurazione wizard opzionale e ripetibilita dinamica.
+ *
+ * @example
+ * ```typescript
+ * const section: UiFormSection = {
+ *   id: 'anagrafica',
+ *   title: 'Dati anagrafici',
+ *   description: 'Informazioni personali del candidato',
+ *   collapsible: true,
+ *   fields: [ ... ],
+ * };
+ * ```
+ */
+export interface UiFormSection {
+    /** ID univoco della sezione. */
+    id: string;
+    /** Titolo della sezione. */
+    title?: string;
+    /** Descrizione della sezione. */
+    description?: string;
+    /** Icona Lucide opzionale per la sezione (visibile in modalità collapsible). @see https://lucide.dev/icons */
+    icon?: UiIconName;
+    /** Campi contenuti nella sezione. */
+    fields: UiFormFieldDescriptor[];
+    /** Condizioni per la visibilita della sezione. */
+    conditions?: UiFieldCondition[];
+    /** Se la sezione e collassabile (accordion). */
+    collapsible?: boolean;
+    /** Se la sezione e inizialmente collassata. @default false */
+    collapsed?: boolean;
+    /** Classi CSS aggiuntive per la sezione. */
+    cssClasses?: string[];
+    /**
+     * Configurazione wizard per questa sezione.
+     * Più sezioni possono condividere lo stesso `wizardStep.stepNumber`: formano un unico
+     * passo del wizard (es. più blocchi `collapsible` nello stesso step). Titolo, descrizione
+     * e validazione del passo si intendono dalla **prima** sezione del gruppo in ordine di schema.
+     * Le chiavi dei campi devono restare univoche tra tutte le sezioni dello stesso schema wizard.
+     */
+    wizardStep?: UiWizardStepConfig;
+    /** Configurazione per sezione ripetibile. Se definito, la sezione diventa un dynamic repeater. */
+    repeatable?: UiRepeatableConfig;
+}
+/**
+ * Configurazione globale del form builder.
+ */
+export interface UiFormBuilderConfig {
+    /** Layout del form. @default 'grid' */
+    layout?: 'vertical' | 'horizontal' | 'grid';
+    /** Numero di colonne nel grid. @default 12 */
+    columns?: number;
+    /** Mostra i pulsanti di azione (submit/reset). @default true */
+    showButtons?: boolean;
+    /** Nasconde solo l'area pulsanti del footer (`ui-button-area`), non il summary errori. */
+    hideFooter?: boolean;
+    /**
+     * Nasconde del tutto il blocco `ui-form-error-summary`.
+     * Se assente/falsy il summary è visibile anche senza errori (stato ok prevedibile).
+     */
+    hideErrorSummary?: boolean;
+    /** Messaggio nel summary quando il form non ha errori (stato ok). */
+    errorSummaryValidMessage?: string;
+    /** Label personalizzate per i pulsanti. */
+    buttonLabels?: {
+        submit?: string;
+        reset?: string;
+        cancel?: string;
+    };
+    /** Classi CSS globali sul container del form. */
+    cssClasses?: string[];
+}
+/**
+ * Configurazione per la modalita wizard del form.
+ * Usata dal componente `UiFormWizardComponent`.
+ *
+ * @example
+ * ```typescript
+ * const wizardConfig: UiWizardConfig = {
+ *   showProgress: true,
+ *   progressStyle: 'steps',
+ *   allowBackNavigation: true,
+ *   buttonLabels: { submit: 'Salva e prosegui', previous: 'Indietro', finish: 'Completa' },
+ * };
+ * ```
+ */
+export interface UiWizardConfig {
+    /** ID per sincronizzazione wireless tra istanze. */
+    wizardId?: string;
+    /** Nasconde l'header interno del wizard per consentire un header esterno. */
+    wirelessHeading?: boolean;
+    /** Mostra la barra di progresso. @default true */
+    showProgress?: boolean;
+    /** Stile della barra di progresso. @default 'steps' */
+    progressStyle?: 'linear' | 'steps';
+    /** Permette navigazione all'indietro. @default true */
+    allowBackNavigation?: boolean;
+    /** Permette navigazione in avanti senza validazione. @default false */
+    allowForwardNavigation?: boolean;
+    /** Salva automaticamente i dati ad ogni cambio step. */
+    autoSave?: boolean;
+    /** Callback per il salvataggio dei dati dello step. */
+    onStepSave?: (stepData: Record<string, any>, stepNumber: number) => Promise<void> | void;
+    /** Mostra pulsanti di navigazione (precedente/successivo). @default true */
+    showNavigationButtons?: boolean;
+    /** Posizione dei pulsanti di navigazione. @default 'bottom' */
+    navigationPosition?: 'top' | 'bottom' | 'both';
+    /**
+     * Consente di saltare a uno step già completato cliccando bullet o titolo step
+     * quando `progressStyle` è `'steps'`. @default true
+     */
+    allowStepIndicatorNavigation?: boolean;
+    /** Label personalizzate per i pulsanti del wizard. */
+    buttonLabels?: {
+        previous?: string;
+        /** Label pulsante avanti; se assente si usa `submit`. */
+        next?: string;
+        /**
+         * Alias di convenienza (come `submit` sul form builder) per il pulsante «avanti» / salva e prosegui.
+         * Usato solo se `next` non è valorizzato.
+         */
+        submit?: string;
+        finish?: string;
+        save?: string;
+    };
+}
+/**
+ * Stato corrente del wizard, esposto dal `WizardSyncService`.
+ */
+export interface UiWizardState {
+    /** Step corrente (0-based). */
+    currentStep: number;
+    /** Numero totale di step. */
+    totalSteps: number;
+    /** Indici degli step completati. */
+    completedSteps: Set<number>;
+    /** Indici degli step visitati. */
+    visitedSteps: Set<number>;
+    /** Se il form nello step corrente e valido. */
+    isValid: boolean;
+    /** Errori per step. */
+    stepErrors: Record<number, string[]>;
+}
+/**
+ * Schema completo del form.
+ *
+ * Rappresenta la configurazione dichiarativa dell'intero form:
+ * sezioni, campi, validazioni, condizioni e impostazioni globali.
+ *
+ * @example
+ * ```typescript
+ * export const myForm: UiFormSchema = {
+ *   id: 'user-registration',
+ *   title: 'Registrazione utente',
+ *   sections: [
+ *     { id: 'personal', title: 'Dati personali', fields: [...] },
+ *     { id: 'address', title: 'Indirizzo', fields: [...], collapsible: true },
+ *   ],
+ *   config: { columns: 12, showButtons: true },
+ * };
+ * ```
+ */
+export interface UiFormSchema {
+    /** ID univoco del form. */
+    id: string;
+    /** Titolo del form. */
+    title?: string;
+    /** Descrizione del form. */
+    description?: string;
+    /** Sezioni del form. */
+    sections: UiFormSection[];
+    /** Configurazione globale. */
+    config?: UiFormBuilderConfig;
+}
+/**
+ * Dati del form come mappa chiave-valore.
+ */
+export type UiFormData = Record<string, any>;
+/**
+ * Evento emesso dai campi custom.
+ */
+export interface UiFormCustomEvent {
+    /** Chiave del campo che ha emesso l'evento. */
+    field: string;
+    /** Nome dell'evento. */
+    event: string;
+    /** Dati associati all'evento. */
+    data: any;
+}
+/**
+ * Evento emesso al cambio step del wizard.
+ */
+export interface UiWizardStepChangeEvent {
+    /** Indice dello step di partenza. */
+    from: number;
+    /** Indice dello step di destinazione. */
+    to: number;
+    /** Direzione della navigazione. */
+    direction: 'next' | 'previous';
+}
+/**
+ * Evento emesso al completamento di uno step.
+ */
+export interface UiWizardStepCompleteEvent {
+    /** Indice dello step completato. */
+    step: number;
+    /** Dati del form al momento del completamento. */
+    data: Record<string, any>;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * @module ng-ui-system/form-builder
+ * Tipi per i componenti di selezione territoriale (location e location-table).
+ */
+/**
+ * Configurazione per un sotto-campo del componente location.
+ * Permette di controllare visibilita, obbligatorieta e layout.
+ */
+export interface UiLocationFieldConfig {
+    /** Mostra il campo. @default true per nazione/provincia/comune, false per campi opzionali */
+    show?: boolean;
+    /** Rende il campo obbligatorio. */
+    required?: boolean;
+    /** Numero di colonne nella griglia (1-12). */
+    columns?: number;
+}
+/**
+ * Configurazione completa per il componente `UiSpecificaTerritorialeComponent`.
+ *
+ * Permette di personalizzare ogni aspetto della selezione geografica:
+ * campi visibili, obbligatorieta, layout e labels.
+ *
+ * @example
+ * ```typescript
+ * // Configurazione base: solo nazione, provincia, comune
+ * const config: UiLocationConfig = {
+ *   nazione: { required: true },
+ *   provincia: { required: true },
+ *   comune: { required: true },
+ * };
+ *
+ * // Con campi aggiuntivi
+ * const configEsteso: UiLocationConfig = {
+ *   italyByDefault: true,
+ *   cap: { show: true, required: true, columns: 4 },
+ *   indirizzo: { show: true, required: true, columns: 8 },
+ *   mail: { show: true, columns: 6 },
+ *   pec: { show: true, columns: 6 },
+ *   telefono: { show: true, columns: 6 },
+ * };
+ * ```
+ */
+export interface UiLocationConfig {
+    /** Configurazione campo nazione. Required default: true. */
+    nazione?: {
+        required?: boolean;
+    };
+    /** Configurazione campo provincia. Required default: true. */
+    provincia?: {
+        required?: boolean;
+    };
+    /** Configurazione campo comune. Required default: true. */
+    comune?: {
+        required?: boolean;
+    };
+    /** Configurazione campo comune estero. Required default: true. */
+    comuneEstero?: {
+        required?: boolean;
+    };
+    /** Configurazione campo CAP. Show default: false. */
+    cap?: UiLocationFieldConfig;
+    /** Configurazione campo indirizzo. Show default: false. */
+    indirizzo?: UiLocationFieldConfig;
+    /** Configurazione campo email. Show default: false. */
+    mail?: UiLocationFieldConfig;
+    /** Configurazione campo PEC. Show default: false. */
+    pec?: UiLocationFieldConfig;
+    /** Configurazione campo telefono. Show default: false. */
+    telefono?: UiLocationFieldConfig;
+    /** Pre-imposta l'Italia come nazione e nasconde la select. */
+    italyByDefault?: boolean;
+    /** Labels personalizzate per i campi. */
+    labels?: UiLocationLabels;
+}
+/**
+ * Labels personalizzabili per i campi del componente location.
+ */
+export interface UiLocationLabels {
+    nazione?: string;
+    provincia?: string;
+    comune?: string;
+    cap?: string;
+    indirizzo?: string;
+    comuneEstero?: string;
+    mail?: string;
+    pec?: string;
+    telefono?: string;
+}
+/**
+ * Valore emesso dal componente location.
+ * Contiene gli ID dei dati geografici selezionati e i campi testuali.
+ */
+export interface UiLocationValue {
+    /** Codice nazione (es. `'ITA'`). */
+    nazioneId?: string;
+    /** Codice provincia (es. `'015'`). */
+    provinciaId?: string;
+    /** Codice comune (es. `'015146'`). */
+    comuneId?: string;
+    /** Codice di avviamento postale. */
+    cap?: string;
+    /** Indirizzo completo (via, numero civico). */
+    indirizzo?: string;
+    /** Nome del comune per nazioni estere (testo libero). */
+    comuneEstero?: string;
+    /** Indirizzo email. */
+    mail?: string;
+    /** Indirizzo PEC. */
+    pec?: string;
+    /** Numero di telefono. */
+    telefono?: string;
+}
+/**
+ * Configurazione per il componente `UiTableTerritorialeComponent`.
+ *
+ * Gestisce una tabella di righe territoriali con CRUD inline.
+ *
+ * @example
+ * ```typescript
+ * const tableConfig: UiLocationTableConfig = {
+ *   tableLabel: 'Sedi operative',
+ *   emptyPrompt: 'Nessuna sede aggiunta',
+ *   emptyCtaLabel: 'Aggiungi sede',
+ *   requiredMessage: 'Inserire almeno una sede',
+ *   subFieldConfig: {
+ *     italyByDefault: true,
+ *     cap: { show: true, required: true },
+ *     indirizzo: { show: true, required: true },
+ *   },
+ * };
+ * ```
+ */
+export interface UiLocationTableConfig {
+    /** Label della tabella. @default 'Tabella territoriale' */
+    tableLabel?: string;
+    /** Label del pulsante di aggiunta. @default 'Aggiungi un luogo' */
+    emptyCtaLabel?: string;
+    /** Testo mostrato quando la tabella e vuota. */
+    emptyPrompt?: string;
+    /** Messaggio di errore quando la tabella e richiesta ma vuota. */
+    requiredMessage?: string;
+    /** Configurazione per il sotto-form (specifica territoriale). */
+    subFieldConfig?: UiLocationConfig;
+}
+/**
+ * Riga della tabella territoriale.
+ * Contiene dati completi della location (oggetti risolti dal servizio).
+ */
+export interface UiLocationRow {
+    /** Nazione (oggetto completo). */
+    stato: any;
+    /** Provincia (solo per Italia). */
+    provincia?: any;
+    /** Comune italiano (oggetto completo). */
+    comuni?: any;
+    /** Comuni esteri (array di nomi). */
+    comuniEsteri?: string[];
+    /** Codice di avviamento postale. */
+    cap?: string;
+    /** Indirizzo completo. */
+    indirizzo?: string;
+    /** Indirizzo email. */
+    mail?: string;
+    /** PEC. */
+    pec?: string;
+    /** Numero di telefono. */
+    telefono?: string;
+    /** ID univoco per il tracciamento della riga. */
+    refId?: string;
+}