Alcune versioni di albe-web-components introducono dei breaking changes ad alcuni componenti.
Quando si passa da una versione major a un'altra, è bene fare attenzione a questi cambiamenti e implementare gli adattamenti necessari per evitare bug o problemi di UI.
Ogni volta che viene implementato un breaking change su un componente, la sua vecchia versione viene mantenuta attiva sotto la cartella deprecated per qualche mese (di solito 2) e il componente viene rinominato con il suffisso -deprecated (es. z-button --> z-button-deprecated). Quando invece un componente legacy viene deprecato, il suffisso viene omesso ma il componente viene comunque spostato nella cartella deprecated e rimosso dopo qualche mese.
Indice delle breaking changes divise per numero di versione in cui sono state introdotte.
La versione attuale del componente è stata mantenuta con il nuovo nome z-book-card-deprecated.
La nuova versione è disponibile in due varianti, landscape e portrait, che sono i valori da passare alla prop variant.
Le prop ribbon, ribbonIcon, ribbonInteractive, borderless sono state eliminate.
La prop operaTitleTag cambia nome in operaTitleHtmlTag.
Sono state aggiunte le prop edi, annotated, teacherVersion per gestire i tag: accettano un oggetto di questo tipo
{
status: "active"|"disabled";
interactive: boolean;
}
Dove status definisce lo stile del tag, mentre interactive gestisce il click dell'utente.
È stata aggiunta la prop adoption che gestisce il badge dei libri adottati.
Le nuove prop catalogUrl e ebookUrl gestiscono rispettivamente i link al catalogo Zanichelli e al libro digitale.
I seguenti token dei link hanno subito modifiche:
color-link-primarydiventacolor-text-link-bluecolor-hover-linkdiventacolor-text-link-blue-hovercolor-active-linkdiventacolor-text-link-blue-activecolor-visited-linkdiventacolor-text-link-blue-visitedcolor-pressed-linkdiventacolor-text-link-blue-pressedcolor-inverse-linkecolor-inverse-hover/active/pressed/visited-linkdiventanocolor-text-link-inverse
I seguenti token dei link sono stati aggiunti:
color-text-link-red:red500color-text-link-red-hover:red800color-text-link-red-active:red800color-text-link-red-visited:red800color-text-link-red-pressed:red400color-text-link-default:gray900
Le seguenti classi css sono state state aggiunte:
z-link-bluecon i rispettivi token per gli stati di hover/active/focus/visitedz-link-redcon i rispettivi token per gli stati di hover/active/focus/visited
Il token color-text-link-default rappresenta il colore di default per i link in ogni loro stato
Il tema di default ha subito le seguenti modifiche:
surface05passa dagray800agray900surface04passa dagray600agray700surface03passa dagray200agray300surface02passa dagray50agray100(per mantenere la situazione attuale, si può usare il tokenbackground)- i token
active-surfaceeselected-surfacesono stati eliminati (sostituirli consurface03) - inoltre vengono modificati i seguenti token secondary (sostituire
secondary02esecondary03consecondary01):secondary01:red500secondary02:red25secondary03:red50active-secondary:red400pressed-secondary:red400hover-secondary:red800
Il token --color-input-field01 cambia nome in --color-form-background, mentre il colore rimane invariato.
Il token --color-input-field02 è stato rimosso.
Il componente ZAppHeader e i suoi sottocomponenti ZMenu e ZMenuSection sono stati rivisitati con modifiche breaking. Le modifiche da attenzionare sono:
ZAppHeader:- rimosso lo slot
subtitle: non è più previsto un sottotilo ma solo iltop-subtitle - rimossa la prop
hero: non è più prevista la variante con immagine di sfondo - rimossa la prop
overlay: non più necessaria senza l'immagine di sfondo - rimossa la prop
flow: il flusso del contenuto è gestito dal componente e non è più previsto il menu a destra - rimosse le CSS properties relative alla tipografia (
--app-header-typography-1-size,--app-header-typography-1-lineheight,--app-header-typography-1-tracking,--app-header-title-font-size,--app-header-title-lineheight,--app-header-title-letter-spacing...): le dimensioni del testo sono gestite dal componente - rimossa la CSS property
--app-header-height - rimossa la CSS property
--app-header-drawer-trigger-size
- rimosso lo slot
ZMenuSection: lo slotitemha cambiato nome insectionper distinguerlo più facilmente da quello diZMenu
L'aggiornamento di Stencil alla versione 4 nella libreria rimuove i polyfills (v2.10.0) pertanto è necessario aggiornare le applicazioni che fanno uso del metodo applyPolyfills.
Il metodo, in precedenza usato in questo modo
applyPolyfills().then(() => {
defineCustomElements(window);
});non dovrà più essere invocato, quindi il codice precedente diventerà
defineCustomElements(window);Questa versione non introduce problemi a livello di compilazione del codice, ma a livello di layout.
Il padding laterale dell'header della modale è stato infatti fissato a 16px indipendentemente dal breakpoint. Prima della modifica invece era 32px/24px/8px. Questo influirà sui layout dei prodotti che usano il componente, in quanto il contenuto è uno slot e le spaziature vengono impostate dal prodotto; dovranno quindi essere eventualmente rivisti gli allineamenti laterali del contenuto.
La versione 1.0.0 del pacchetto @zanichelli/albe-design-tokens ha cambiato la denominazione e il valore di alcuni token, di conseguenza le applicazioni che usano la versione >= 14 di questo repo, devono sostituire i vecchi token con i nuovi equivalenti.
Di seguito la lista dei tokens da modificare:
text01da modificare indefault-texttext02ha cambiato valore da gray800 a gray100, verificare se in alcuni puntitext02è da sostituire context01text04da modificare intext-inversedisabled02ha cambiato valore da gray700 a gray100, verificare se in alcuni puntidisabled02è da sostituire condisabled03icon01da modificare inprimary01-iconicon02da modificare indefault-iconicon03da modificare ininverse-icon
Il componente deprecato è stato eliminato definitivamente dalla libreria
Rimosso i componenti deprecati ZTable e i suoi componenti figli. Nel dettaglio sono stati rimossi:
- z-table
- z-table-body
- z-table-cell
- z-table-empty-box
- z-table-expanded-row
- z-table-footer
- z-table-head
- z-table-header
- z-table-header-row
- z-table-row
- z-table-sticky-footer
Il componente deprecato è stato eliminato definitivamente dalla libreria
Il componente deprecato è stato eliminato definitivamente dalla libreria
Il componente deprecato è stato eliminato definitivamente dalla libreria
A seguito della rimozione del componente ZContextualMenu la prop isContextualMenu (optional) e tutte le logiche legate a essa sono state rimosse perchè non più necessarie
Aggiunto testPathIgnorePatterns al file stencil.config.ts perchè ignori le cartelle /dist e /storybook dai test
La versione 0.2.29 del pacchetto @zanichelli/albe-design-tokens non ha più i token (classi e custom prop CSS) classificati come legacy, di conseguenza le applicazioni che usano la versione >= 12 di questo repo, devono sostituire i vecchi token con i nuovi equivalenti.
Per trovare facilmente i vecchi token nel codice di un applicativo, è possibile fare una ricerca con regex dall'IDE di sviluppo (es. VSCode) usando la seguente regex:
t-weight-lt|t-weight-rg|t-weight-sb|t-align-center|t-color-light|caption-01|helper-text-01|body-short-01|body-short-02|body-long-01|body-long-02|heading-01|heading-02|heading-03|heading-04|heading-05|expressive-heading-04|expressive-heading-05|expressive-paragraph-01|quotation-01|quotation-02|display-01|display-02|display-03|display-04|--dashboard-font|--basex1|--basex2|--basex3|--basex4|--basex5|--basex6|--basex7|--basex8|--half-x1|--half-x3|--half-x5|--half-x7|--half-x9|--half-x11|--half-x13|--half-x14|--myz-blue|--myz-blue-dark|--myz-blue-light|--myz-blue-lighter|--myz-red|--myz-red-dark|--myz-red-light|--accent|--accent-dark|--accent-light|--accent-lighter|--bg-grey-050|--bg-grey-200|--bg-grey-700|--bg-grey-800|--bg-grey-900|--bg-white|--bg-neutral-100|--bg-neutral-150|--bg-neutral-200|--bg-neutral-300|--bg-neutral-400|--bg-neutral-500|--bg-neutral-600|--bg-neutral-700|--bg-neutral-800|--status-error-red|--status-error-red-dark|--status-error-red-light|--status-error-red-lighter|--status-warning-yellow|--status-warning-yellow-dark|--status-warning-yellow-light|--status-warning-yellow-lighter|--status-success-green|--status-success-green-dark|--status-success-green-light|--status-success-green-lighter|--text-grey-800|--text-grey-700|--text-grey-200|--text-grey-050|--text-white|--border-base|--radius-base|--border-radius-base|--border-radius-min|--border-radius-maxL'uso dei sottocomponenti di ZNavigationTabs creava dei problemi di accessibilità a causa della struttura HTML generata. I componenti in questione wrappano dei tag <button> e <a>, con role=tab, aggiungendo stili e qualche comportamento. La corretta implementazione del Tabs Pattern richiede che le tab siano elementi posizionati direttamente dentro quello con il role=tablist e quel wrapping lo impediva.
Il comportamento implementato nei sottocomponenti è ora gestito dal componente principale.
Sostituire tutti gli z-navigation-tab con dei <button> e i z-navigation-tab-link con degli <a>. Ricordarsi di aggiungere l'attributo aria-controls quando necessario.
Il componente deprecato è stato eliminato a favore delle relative classi css su design-tokens
Il componente deprecato è stato eliminato a favore delle relative classi css .body-* su design-tokens
Il componente deprecato è stato eliminato a favore delle relative classi css .heading-* su design-tokens
Il componente z-table è stato rifattorizzato per migliorarne l'accessibilità e la flessibilità dopo il passaggio da snowflake a componente ufficiale della libreria.
Tutti i sottocomponenti sono stati deprecati in favore di un numero ridotto di sottocomponenti e nomi più in linea con gli elementi nativi (z-thead, z-tbody, z-tfoot, z-tr, z-th, z-td).
Fare riferimento alla documentazione su Storybook per capire come utilizzarli e vedere gli esempi con tutte le funzionalità.
Per continuare a usare la vecchia tabella, modificare z-table in z-table-deprecated e implementare le modifiche descritte nei paragrafi relativi a Rimozione del valore none dell'enum SortDirection e Rimozione dell'enum Size.
Il valore none è stato rimosso dall'enum SortDirection in quanto non più necessario. Per continuare a usare i vecchi componenti che usavano questo enum, sostituire l'uso dell'enum passando il valore come stringa "none" alla prop sortDirection.
L'enum Size è stato rimosso poiché usato solo da componenti deprecati. Per continuare a usare i vecchi componenti che usavano questo enum, sostituire l'uso dell'enum passando i valori come stringa alla prop padding.
Il componente è stato rifattorizzato per migliorare l'accessibilità, mantenendo gli stili pregressi e l'intera area della card come cliccabile.
La property permane soltanto per gestire gli stili della card.
Lo slot title va usato come slot principale al quale passare un tag interattivo come un'àncora o un bottone, in caso di necessità di avere una card cliccabile.
La prop showshadow è stata rinominata in showShadow per essere in linea con il code style del DS. Le app dovranno usare quindi showShadow o show-shadow come attributo HTML.
Il componente è stato rifattorizzato per gestire l'aspect ratio dell'immagine slottata. Questa può essere configurata tramite la prop CSS --cover-hero-aspect-ratio. Di default la prop non ha nessun valore e se non viene impostata, il componente usa l'aspect ratio intrinseco dell'immagine.
Con l'introduzione della gestione dell'aspect ratio, questa prop è diventata inutile
Con l'introduzione della gestione dell'aspect ratio, questa prop è diventata inutile
Le regole di coding style configurate impongono l'uso dell'UPPER_CASE per i membri degli enum e il camelCase per le property dei types, quindi l'applicazione di queste regole di naming convention risultano breaking per chi usa gli enum e i types importandoli da questo repository.
Lista degli Enum e tipi interessati:
LicenseTypeCardCardVariantNavigationTabsOrientationNavigationTabsSizeButtonVariantButtonTypeButtonSizeInputTypeInputStatusPopoverPositionThemeVariantDividerSizeDividerOrientationSortDirectionAvatarSizeListSizeSizeExpandableListStyleExpandableListButtonAlignLabelPositionListDividerTypeNotificationTypeAlertTypeDeviceToastNotificationToastNotificationTransitionToastNotificationPositionZTableRowExpandedTypeZAriaAlertModeTransitionDirectionOffCanvasVariantZFileUploadTypeZChipTypeZSectionTitleDividerPositionZDatePickerModeZDatePickerPositionZRangePickerModeInfoRevealPosition
Per via delle regole di coding style, la prop descr_slot_name diventa descrSlotName.
Per via delle regole di Stylelint, alcune classi CSS hanno cambiato nome (da camelCase a kebab-case). Non dovrebbe avere un impatto nei prodotti MA se, per via di situazioni molto particolari, è stato necessario intervenire sullo stile dei componenti, usando dei selettori per classi, allora sarà neccessario andarli a modificare.
Di seguito l'elenco dei componenti interessati e delle classi modificate:
| Component | Classes |
|---|---|
z-input |
.hasClearIcon .hasIcon .iconButton .iconsWrapper .inputIcon .inputLabel .resetIcon .showHidePasswordIcon .textareaWrapper .textWrapper |
z-input-deprecated |
.hasClearIcon .hasIcon .iconsWrapper .input_error .input_success .input_warning .resetIcon .showHidePasswordIcon .textareaWrapper |
z-input / z-input-deprecated |
La classe .showHidePasswordIcon è stata modificata in .toggle-password-icon per chiarezza |
z-input-deprecated (checkbox) |
.checkboxLabel .checkboxWrapper .radioLabel .radioWrapper |
z-select |
.noResults .selectWrapper .ulScrollWrapper |
z-chip |
.iconSx |
z-file-upload |
.modalWrapper |
z-table-empty-box |
.has2Cta |
z-button |
- |
z-toggle-switch |
- |
z-date-picker |
- |
z-range-picker |
- |
z-footer |
- |
z-combobox |
- |
z-input-message |
- |
z-list-element |
- |
z-toast-notification-list |
- |
z-modal-login |
- |
z-navigation-tab-link |
- |
z-navigation-tab |
- |
z-navigation-tabs |
- |
z-menu-dropdown |
- |
z-cookiebar |
- |
z-toast-notification |
- |
z-card |
- |
z-offcanvas |
- |
z-pagination |
- |
z-popover |
- |
z-section-title |
- |
z-table |
- |
z-table-cell |
- |
z-table-header |
- |
z-button-deprecated |
- |
z-popover-deprecated |
- |
z-myz-card-alert |
- |
z-myz-card-dictionary |
- |
z-myz-card-footer |
- |
z-myz-card-header |
- |
z-myz-card-list |
- |
z-myz-card |
- |
z-myz-card-alert |
- |
z-myz-list |
- |
topbar |
- |
z-alert |
- |
z-otp |
- |
z-slideshow |
- |
utils |
- |
Sono state cambiate classi CSS anche in altri componenti che non sono inclusi nell'elenco: quei componenti hanno l'opzione
shadow: true, quindi di sicuro non è stato possibile usare le classi CSS per modificarne lo stile dai prodotti.
Lo ZPopover è strutturalmente cambiato: il contenuto è completamente slottato, l'elemento che funge da "trigger" per l'apertura va aggiunto fuori dal componente. La proprietà "bindTo" permette di specificare l'elemento (con referenza o stringa selettore) rispetto a cui il popover deve essere posizionato, e generalmente rappresenta l'elemento "trigger" stesso.
Le nuove "posizioni" utilizzabili sono cambiate e sono disponibili nell'enum "PopoverPosition".
Le proprietà legate allo stile (backgroundColor, borderRadius, ecc.) sono scomparse in favore di variabili CSS.
Anche le shadow sono settate tramite variabile CSS --z-popover-shadow-filter, di tipo "filter".
La proprietà type ora si chiama position. Per avere il tooltip in versione "dark" c'è una nuova proprietà dark da settare a true.
Lo ZInputMessage adesso è gestito solo dalla prop message. Per rimuovere l'ingombro del messaggio basta settare un valore falsy. Il comportamento di default rimane invariato (ingombro visibile).
Il type "select" esisteva solo per una questione di retrocompatibilità, adesso se si vuole una select basta usare il componente ZSelect. Di conseguenza sono state rimosse le prop items e multiple che servivano solo per la select.
Il timeout prima che venga fatto un emit dell'evento inputChange non è più configurabile e rimane fisso a 300ms. Per adattare basta semplicemente non passare più il valore a typingtimeout.
La prop labelafter è stata rimossa e sostituita da labelPosition. Quest'ultima non è di tipo boolean ma di tipo LabelPosition e accetta uno dei due valori dell'enum LabelPosition (LabelPosition.right, LabelPosition.left o una stringa tra "right" e "left").
I metodi pubblici setValue() e getValue() sono stati rimossi. Per leggere o scrivere programmaticamente il valore della input, usare la prop value.
Esempi:
zInput.value = "testo della input";const inputValue = zInput.value;<z-input value="valore di default"></z-input>La situazione è analoga a quella della ZInput.
Rimossa la prop multiple e tutta la gestione con le chip. È possibile utilizzare il componente ZCombobox per ottenere lo stesso risultato.
Come conseguenza della rimozione della prop multiple, adesso con la ZSelect è possibile selezionare un solo elemento, quindi non ci sono più items ma un solo item.
La prop square è stata rimossa e la forma quadrata del button, quando contiene solo l'icona, viene gestita automaticamente tramite CSS.
Questo slot veniva usato in casi rari in cui serviva sostituire il button, interno allo ZButton con un altro elemento ma facendolo comunque apparire esteticamente come uno ZButton. Dato che il principale utilizzo era una sostituzione con un a, la mancanza dello slot "element" viene sopperita dalla nuova prop href, che, quando valorizzata con un url, crea un <a> anziché un <button>.
Il valore dark-bg assegnabile alla prop variant è stato rimosso. Per cambiare i colori dello ZButton quando si trova su un background scuro/colorato, è possibile fare un ovveride da CSS dei token colore usati internamente.
Es.
.container-dark z-button {
--color-primary01: var(--gray600);
--color-hover-primary: var(--gray700);
--color-pressed-primary: var(--gray500);
--color-disabled01: var(--gray700);
--color-disabled02: var(--gray500);
}Usare la prop size con valore small
Il componente ZPaginationBar è stato deprecato in favore del nuovo componente ZPagination. Di conseguenza anche il relativo componente interno ZPaginationPage è stato deprecato.
Il componente ZStatusTag è stato deprecato in favore del nuovo componente generico ZTag. Per evidenziare graficamente uno "status", settare da prodotto i colori di testo e sfondo, usando le apposite CSS custom prop --z-tag-text-color e --z-tag-bg.
Il componente ZButtonFilter è stato deprecato. Al suo posto usare il componente ZChip in versione "interactive"; quest'ultima si ottiene valorizzando la prop interactiveIcon con il name di una z-icon.
Il componente ZChip è stato completamente rifattorizzato. La vecchia versione è stata trasferita nella cartella dei deprecated e rinominata a ZChipDeprecated. Per passare dalla vecchia alla nuova versione, consultare la documentazione del componente.