Versiopäivitysohje

Yleistä

Ohjeeseen on koottu merkittävimmät suurten (major) versioiden päivityksiin liittyvät rikkovat muutokset. Lisätietoja julkaisukäytännöistä. Muita muutoksia voi tutkia versiohistoriasta.

15.3.0 → 16.0.0

Yleistä

• Päivitä react- ja react-dom-kirjastot versioon 19.1.0.

Ikonit, kuvakkeet ja logot

• Korvaa kuvitusikonien nimet ja import-lausekkeet alkamaan IconDeco-alkuisesti (esim. IconNetwork → IconDecoNetwork).
• Korvaa käyttöliittymäkuvakkeiden nimet ja import-lausekkeet alkamaan IconUi-alkuisesti (esim. IconLock → IconUiLock).
• Lisää aria-hidden={undefined} kuvitusikoneille, käyttöliittymäkuvakkeille ja logoille, jos niiden nimeäminen on toteutettu jotenkin muuten kuin aria-label-, aria-labelledby- tai aria-describedby-attribuuteilla.
• Poista Handelsbanken-logo käytöstä.

Komponentit

• Toteuta Multiselect-komponentin suodatustoiminnon aksentti- ja erikoismerkkien normalisointi filterItems-funktiolla, jos tarvitset normalisoinnille Unicode-merkkejä U+0300 – U+036F laajempaa tukea.
• Korvaa Chip-komponentin variant="outline" → appearance="outline".
• Muuta TimeInput-komponenttia seuraavasti:
  • Poista InputGroup-, InputLabel-, InputText-komponentit ja anna nimilappu, ohjetekstit ja virheilmoitukset suoraan komponentin propeille.
  • Muuta validointi ja tapahtumakäsittelijät yms. toiminnallisuudet vastaamaan normaalin input-kentän toimintaa.
• Korvaa TextInput-komponentin select- ja multiline-propit element-propilla.
• Lisää ButtonGroup-komponentin size-prop myös painikkeille ja poista sm- ja lg-arvot ButtonGroup-komponentilta.
• Korvaa poistunut ButtonToolbar-komponentti ButtonGroup-komponentilla (isToolbar-prop).
• Korvaa poistunut Combobox-komponentti ComboboxV2-komponentilla.
• Korvaa poistunut Media-komponentti Card-komponentilla tai CSS:n flex-tyyleillä.
• Korjaukset Modal-komponenttiin saattavat vaatia muutoksia testeihin, koska Modal avautuu ja sulkeutuu pienellä viiveellä.
  • Avaaminen: expect(await screen.findByRole("dialog")).toBeTruthy()
  • Sulkeminen: await waitFor(() => { expect(screen.queryByRole("dialog")).not.toBeInTheDocument(); });
• Poista autoSize-prop seuraavilta komponenteilta, jos se on käytössä:
  • ComboboxV2
  • DatePickerV2
  • DateRangePickerV2
  • Multiselect
  • TextInput

Hookit

• Muuta useThrottle- ja useDebounce-hookin käyttöä seuraavasti:
  • Korvaa const throttled = useThrottle(callback, 250); → const { throttled } = useThrottle(callback, 250);
  • Korvaa const debounced = useDebounce(callback, 250); → const { debounced } = useDebounce(callback, 250);
  • Poista cancel-funktio useEffectin cleanup:sta (kutsutaan nyt hookin toimesta automaattisesti).

14.5.0 → 15.0.0

CSS-tyylit ja muuttujat

• Korvaa käytöstä poistuneet dist/css/legacy/legacy-utils.min.css-tiedostosta tulleet Bootstrapin CSS-apuluokat nykyisillä CSS-apuluokilla tai muilla vastaavilla.
  • Tarvittaessa legacy-utils.min.css-tiedoston voi kopioida sovellukseen KDS:n vanhemmasta versiosta, jolloin muutoksia ei tarvita.
• Korvaa tiedostoista dist/css/themes/kela.min.css tai dist/css/themes/kanta.min.css tulleet teemamuuttujat uusilla vastaavilla, jos niitä on käytetty sovelluksessa.
• Vanhat käytöstä poistuvat teemamuuttujat ovat saatavilla tiedostoista: dist/css/legacy/legacy-variables-kanta.min.css ja dist/css/legacy/legacy-variables-kela.min.css.

Useat komponentit

• Asenna TypeScript >= 5.7.2 (ei pakollinen, mutta suositeltu).
• Korvaa komponenttien util-prop className-propilla, jos se on käytössä apuluokkien välittämiseen.
• Korjaa interface → type tyypitysmuutoksen aiheuttamat virheet komponenttien exportoiduissa tyypityksissä, jos niitä on hyödynnetty tai laajennettu sovelluksessa.
• Korvaa käytöstä poistunut Page-komponentti:
  • Sivupohjat-suunnittelumallista löytyy esimerkkejä erilaisten sivupohjien toteutukseen.
  • SkipLink-komponentti löytyy erillisenä komponenttina.
  • Saavutettavuus-ohjeista löytyy esimerkki Page-komponentissa olleen kohdistuselementin toteuttamiseen.
• Korvaa Sidebar-komponentin navLinks-prop lapsielementeillä (children).
• Korvaa SidebarNavItem ja SidebarNavHeading Nav-komponenteilla.

MainBar, TitleBar ja DropdownToggle

• Vaihda MainBar ja MainBarContainer-komponenttien sticky-prop arvoon true, jos haluat pitää ne jatkossakin sisällön päällä kelluvina.
• Korvaa MainBarSearch-komponentti MainBarSearchV2-komponentilla.
• Korvaa MainBarAction-komponentin labelUtil-prop labelClassName-propilla.
• Korvaa TitleBarAction-komponentin labelUtil-prop labelClassName-propilla.
• Korvaa DropdownToggle-komponentin labelUtil-prop labelClassName-propilla, silloin kuin DropdownToggle käyttää kyseisiä komponentteja as-propilla.

ContentHighlight

• Korvaa ContentHighlight-komponentin poistunut type-prop seuraavasti:
  • type="info" → variant="primary" icon={<IconQuestionCircle />}
  • type="notice" → variant="danger" icon={<IconExclamationCircle />}
  • type="example" → variant="warning" icon={<IconBulb />}
• Ikoneina käytetään kuvitusikoneita deco-hakemistosta.

DatePicker ja DateRangePicker

• Korvaa käytöstä poistuneet DatePicker- ja DateRangePicker-komponentit DatePickerV2- ja DateRangePickerV2-komponenteilla.
• Muokkaa DatePickerV2- ja DateRangePickerV2-komponentteja seuraavasti:
  • Poista merkkijonomuotoisista value- ja defaultValue-oletusarvoista etunollat, esim. date-fns format(new Date(), "d.M.yyyy").
  • Aseta showLeadingZeros={true}, jos päivämäärien etunollat halutaan pitää käytössä.

Alert, Accordion, Collapse, Panel, useCollapse

• Muuta Panel-komponenttia seuraavasti:
  • Jos Panelia käytetään lomake-elementtien ryhmänä, lisää sille role="group".
  • Poista mahdolliset itse määritetyt as="section" ja aria-labelledby, jotka tulevat nyt oletuksena.
• Aseta AccordionToggle-komponentille headingAs-propilla sivun rakenteen mukainen otsikkotaso (h1-h6) ja muuta sen sisällä olevat elementit span-elementeiksi.
  • Jos AccordionToggle:n sisällä on käytetty otsikkoa, tulee se muuttaa malliin <Heading as="span" size={3}>, jolloin size määrittää visuaalisen koon ja as on aina span-elementti.
• Aseta laajennettavalle Alert-komponentille collapseTitleAs-propilla sivun rakenteen mukainen otsikkotaso (h1-h6).
• Aseta avattavalle Panel-komponentille headingAs-propilla sivun rakenteen mukainen otsikkotaso (h1-h6).
• Aseta Collapse- ja useCollapse-komponenteilla rakennetuille toteutuksille sivun rakenteen mukaiset otsikkotasot tarvittaessa.

Muut muutokset

• Päivitä tarvittaessa TextInput-komponenttia seuraavasti:
  • Korvaa ennakoivasti versiossa 16.0.0 poistuvat propit select ja multiline, element-propilla, jolle annetaan arvoksi input, textarea tai select.
  • Muuta proppien tyypitykset vastaamaan uutta mallia.
  • Esimerkiksi onChange-käsittelijän tulee nyt vastata renderöitävää elementtiä (element="textarea" → onChange={(e: React.ChangeEvent<HTMLTextAreaElement>) => setValue(e.target.value)}).
• Päivitä Footer-komponentin rakenne esimerkkien mukaiseksi ja poista seuraavat propit käytöstä: copyrightText, links ja isLegacy.
• Päivitä useSort-hookia:
  • Muuta parametrit objektiksi seuraavasti: useSort(data, locale, options) → useSort(data, { locale: "fi", options }).
  • Hookin vastaanottama ja palauttama data tyypittyy sille annetun datan mukaisesti, joten mahdolliset data as MyData[] konversiot voi poistaa.

Kuvakkeet ja ikonit

• Korvaa seuraavat ikonit:
  • IconLeftArrowCircle → IconArrowCircleLeft
  • IconRightArrowCircle → IconArrowCircleRight
  • IconLaptopClock → IconLaptopLock
• Korvaa käytöstä poistuneet kuvitusikonit (other-hakemisto) kuvitusikoneilla (deco-hakemisto) alla olevan taulukon mukaisesti.
• Korvaa käyttöliittymäkuvakkeiden size="xs" → size="relative" arvolla, jos xs-arvo muuttaa ikonin tai kuvakkeen kokoa.

Poistuvat kuvitusikonit

13.7.0 → 14.0.0

• Asenna TypeScript >= 5.3.3 (ei pakollinen, mutta suositeltu)
• Lisää Container-komponentille maxWidth="xl"-prop, jos haluat pitää elementin leveyden ennallaan.
• Lisää TitleBar-komponentille maxWidth="xl"-prop, jos haluat pitää elementin leveyden ennallaan.
• Lisää TitleBar-komponentille erikseen Kela- tai Kanta-logo, logo-proppia käyttäen.
• Poista Tabs-komponentilta flush-prop.
• Poista Dropdown-komponentilta useLegacyMenu-prop ja kääri dropdownin sisältö DropdownMenuGroup-komponenttiin, joka tekee ul-listan.
• Korvaa $breakpoint-xs, BREAKPOINT_XS, --kds-t-breakpoint-xs design-muuttujat, base-muuttujalla (xs = 428, base = 0), jos käytössä.
• Korvaa --kds-dropdown-z-index-teemamuuttuja --kds-z-dropdown-muuttujalla, jos käytössä.
• Korvaa Row-komponentin form-prop, gx={2}-propilla.
• Korvaa ButtonGroup-komponentin horizontal="xs" => horizontal, asettaaksesi painikkeet jokaisella näyttökoolla vierekkäin.
• Korvaa Accordion-komponentin borderless-prop, appearance="borderless"-propilla.
• Korvaa Tile-komponentin propit seuraavasti säilyttääksesi edellisen version ulkoasun:
  • variant="secondary" => variant="primary-medium"
  • variant="light" => variant="primary-light"
  • highlightValue => variant="danger-light"
• Korvaa Alert, Button, ButtonGroup, Modal, Spinner, Table ja Tabs-komponenttien small, medium, large ja xlarge propit size="sm|md|lg|xl"-propeilla.
• Tarkista lomakkeiden virheilmoitusten räätälöidyt toteutukset. Virheilmoitukset esitetään kenttien alapuolella.