# Guida di migrazione tmw-picker 1.0.x → 1.1.0

> **Versioning**: la major version del pacchetto segue la major di Angular
> (schema Angular-aligned, come `@angular/material`). La serie `1.x` è per
> **Angular 15**; la `2.x` sarà la release su **Angular 17**. Per questo questa
> riscrittura resta nella serie `1.x` (1.1.0) pur introducendo breaking changes.

La 1.1.0 è una riscrittura che rende la libreria idiomatica, accessibile e
pronta per l'upgrade ad Angular moderno. Introduce **breaking changes** rispetto
alla 1.0.x: questa guida elenca cosa cambia e come adeguare il codice.

## In sintesi

| Area | 1.0.x | 1.1.0 |
|------|-------|-------|
| Moduli | `TmwPickerModule` (NgModule) | Componenti **standalone** (niente modulo) |
| Libreria date | moment.js | **Luxon** |
| Calendario | `@angular-material-components/datetime-picker` | `@angular/material` nativo |
| I/O nei form | `[formGroupInput]` + `[formControlNameInput]` | **`ControlValueAccessor`** standard |
| I/O diretto | `[(ngModelInput)]` / `(ngModelInputChange)` | `[(ngModel)]` standard / `(dateChange)` |
| Token di formato | sintassi moment (`DD/MM/YYYY`) | sintassi **Luxon** (`dd/MM/yyyy`) |
| Timezone | `forSaveLocalOnDB` (inversione GMT) | `forSaveLocalOnDB` (riscritto) + `[timeZone]` IANA |
| Highlight | `[highLightedAriaFormat]` | rimosso (gestito da `dateClass`) |

## 1. Import: da NgModule a standalone

Non esiste più `TmwPickerModule`. Importa i componenti dove servono.

```diff
- import { TmwPickerModule } from 'tmw-picker';
-
- @NgModule({
-   imports: [TmwPickerModule],
- })
+ import { TmwDateTimePickerComponent, TmwPickerComponent, TmwDateRangePickerComponent } from 'tmw-picker';
+
+ @NgModule({
+   imports: [TmwDateTimePickerComponent, TmwPickerComponent, TmwDateRangePickerComponent],
+ })
```

In un componente standalone, aggiungili direttamente agli `imports` del componente.

## 2. Integrazione con i form: ControlValueAccessor

Il componente ora implementa `ControlValueAccessor` + `Validator`: si usa come
qualunque control nativo.

**Reactive Forms**
```diff
- <tmw-datetimepicker
-   [formGroupInput]="form"
-   [formControlNameInput]="'data'"
-   (ngModelInputChange)="onChange($event)">
- </tmw-datetimepicker>
+ <!-- dentro un [formGroup]="form" -->
+ <tmw-datetimepicker
+   formControlName="data"
+   (dateChange)="onChange($event)">
+ </tmw-datetimepicker>
```

**Template-driven**
```diff
- <tmw-datetimepicker [(ngModelInput)]="data"></tmw-datetimepicker>
+ <tmw-datetimepicker [(ngModel)]="data"></tmw-datetimepicker>
```

Vantaggi gratuiti: `required`/`min`/`max` producono errori di form standard,
`dirty`/`touched`/`disabled` funzionano nativamente.

### Input/Output rimossi

| Rimosso | Sostituto |
|---------|-----------|
| `[formGroupInput]` | `formControlName` / `[formControl]` |
| `[formControlNameInput]` | `formControlName` |
| `[(ngModelInput)]` | `[(ngModel)]` |
| `(ngModelInputChange)` | `(dateChange)` (oppure il valore del form control) |
| `[highLightedAriaFormat]` | — (non più necessario) |

## 3. Token di formato: moment → Luxon

`inputFormat` e `outputFormat` usano ora i token di
[Luxon](https://moment.github.io/luxon/#/formatting?id=table-of-tokens),
diversi da moment in alcuni casi chiave:

| Significato | moment (1.0.x) | Luxon (1.1.0) |
|-------------|----------------|---------------|
| Giorno (2 cifre) | `DD` | `dd` |
| Anno (4 cifre) | `YYYY` | `yyyy` |
| Mese (2 cifre) | `MM` | `MM` (invariato) |
| Ora 24h | `HH` | `HH` (invariato) |

```diff
- [inputFormat]="'DD/MM/YYYY'"  [outputFormat]="'YYYY-MM-DD'"
+ [inputFormat]="'dd/MM/yyyy'"  [outputFormat]="'yyyy-MM-dd'"
```

> `timeType = MOMENT` ora emette un oggetto **Luxon `DateTime`** invece di un
> `moment`. L'enum mantiene il nome `MOMENT` per compatibilità.

## 4. Timezone

`forSaveLocalOnDB` continua a funzionare (riscritto con Luxon, stesso effetto:
i campi UTC del valore emesso coincidono con l'orario mostrato). In più:

```html
<!-- interpreta l'orario di calendario nel fuso IANA indicato -->
<tmw-datetimepicker [timeZone]="'Europe/Rome'" ...></tmw-datetimepicker>
```

`timeZone` ha precedenza su `forSaveLocalOnDB`.

## 5. Nuovo: selettore di intervallo

```html
<tmw-daterangepicker
  formControlName="periodo"
  [timeType]="timeType.DATE"
  [outputFormat]="'yyyy-MM-dd'">
</tmw-daterangepicker>
```

Il valore è un oggetto `{ start, end }` (tipo dei membri secondo `timeType`).

## 6. Dipendenze

```diff
- npm i moment @angular-material-components/datetime-picker @angular-material-components/moment-adapter
+ npm i luxon
```

> Nota storica: le primissime versioni della 1.1.0 si appoggiavano ad
> Angular Material nativo (da qui il nome interno di alcuni file/commenti).
> Dalla 1.2.13 la libreria non ha più alcuna dipendenza da `@angular/material`
> o `@angular/cdk` — il calendario, i dialog e il selettore di intervallo sono
> tutti componenti nativi Luxon-based. Se il tuo progetto installava
> `@angular/material`/`@angular/material-luxon-adapter` solo per `tmw-picker`,
> puoi rimuoverli.