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.

16.2.0 → 17.0.0

Yleistä

• Päivitä react- ja react-dom-kirjastot vähintään versioon 19.2.3.
• Päivitä sass-kirjasto vähintään versioon 1.95.0, jos värityökalut ovat käytössä.
• Päivitä TypeScript vähintään versioon 5.9.3 (ei pakollinen, mutta suositeltu).
• Päivitä TypeScriptin moduleResolution(Avautuu uuteen välilehteen)-asetus: node16, nodenext tai bundler (suositus).

Selaintuki

• Lisää sovellukseen compat-import, jos sovelluksessa on käytössä Modal, DatePickerV2, DateRangePickerV2 tai Sidebar-komponentit ja selaintuen tulee kattaa Safari < 14.1 / iOS < 14.5.

CSS-tyylit ja muuttujat

• Korvaa scss design-muuttujien polku: dist/tokens/tokens → tokens/base/scss
• Korvaa seuraavat Kela-väripaletit (jos design-muuttujia on käytetty sovelluksessa):
  • warning-yellow → kela-warning-yellow
  • success-green → kela-success-green
  • warning-red → kela-danger-red
  • dark-orange → korvaavaa palettia ei ole
  • dark-red → korvaavaa palettia ei ole
  • dark-purple → kela-purple
  • dark-turquoise → kela-turquoise
  • bright-blue → korvaavaa palettia ei ole
  • bright-lime → korvaavaa palettia ei ole
• Korvaa seuraavat Kanta-väripaletit (jos design-muuttujia on käytetty sovelluksessa):
  • kanta-warning-red → kanta-danger-red
• Korvaa seuraavat design-muuttujat (jos design-muuttujia on käytetty sovelluksessa):
  • color-black-100 → color-black
  • color-black-90 → color-black-soft
• Poista viittaukset seuraaviin tiedostoihin legacy-variables-kanta.min.css ja legacy-variables-kela.min.css ja korvaa poistuneet muuttujat teemamuuttujilla.
• Lisää sovellukseen poistuvat teemamuuttujat css/themes/legacy-polusta, jos version 16.x.x CSS-teemamuuttujia on käytetty sovelluksessa räätälöidyn ulkoasun toteuttamiseen.
  • Kela: css/themes/legacy/kela.min.css ja css/themes/legacy/kela-dark.min.css
  • Kanta: css/themes/legacy/kanta.min.css ja css/themes/legacy/kanta-dark.min.css
  • Sijoita CSS-tiedostot ennen muita tyylejä, jotta uudet osittain samannimiset muuttujat yliajavat vanhemmat.
• Korvaa MainBar-komponentin tyylitiedoston nimi: mainbar.css → main-bar.css (jos tyylitiedostot on importoitu yksitellen).

Komponentit

• Poista id-attribuutit ModalHeader- ja ModalContent-komponenteilta.
  • Tarvittaessa id:n voi antaa Modal-komponentille, jolloin alikomponenttien id:t muodostuvat kaavalla [id]-header ja [id]-body.
• Korvaa Modal-komponentin toggle-prop, onClose-propilla.
• Korvaa Sidebar-komponentin toggle-prop, onClose-propilla.
• Korvaa Table-komponentti ja sen alikomponentit vastaavilla TableV2-komponenteilla.
  • Komponenttien ja proppien nimet ovat osittain muuttuneet rakenteen pysyessä pääasiassa samana.
• Korvaa ListGroup-komponentti vastaavankaltaisella toteutuksella. Katso alta ListGroup-komponentin korvaaminen.
• Muutos Dropdown-komponentissa saattaa vaatia testeihin päivityksen, koska valikko sulkeutuu viiveellä:
  • Esimerkki: await waitFor(() => { expect(screen.queryByRole("list")).not.toBeInTheDocument(); });
• Korvaa Button, MainBarAction ja TitleBarAction -komponenttien caret-prop käyttämään arvoja up ja down ja poista caretUp-prop.
• Muuta DescriptionListItem-komponenttien sisältöelementti takaisin div-elementiksi, jos lista pitää sisällään block-elementtejä.
  • Joko <DescriptionList itemContentAs="div"> tai <DescriptionListItem contentAs="div">.
  • Vaihtoehtoisesti DescriptionListItem:n sisällön voi pyrkiä muuttamaan inline-elementeiksi validin HTML-rakenteen säilyttämiseksi.

ListGroup-komponentin korvaaminen

Esimerkki, joka käyttää LinkBox-komponenttia koko alueen kokoisen linkin luomiseen.

<List unstyled className="kds-m-0">
  <ListItem className="kds-mb-0 kds--mt-px">
    <LinkBox className="kds-focus-ring-inset" href="#" appearance="outline" textColor="dark">
      Linkki 1
    </LinkBox>
  </ListItem>
  <ListItem className="kds-mb-0 kds--mt-px">
    <LinkBox className="kds-focus-ring-inset" href="#" appearance="outline" textColor="dark">
      Linkki 2
    </LinkBox>
  </ListItem>
</List>

Esimerkki, joka käyttää LinkWithInfo-komponenttia ja apuluokkia reunaviivojen tekemiseen.

<List unstyled className="kds-m-0">
  <ListItem className="kds-m-0 kds--mt-px kds-border kds-border-solid kds-border-default">
    <LinkWithInfo href="#" className="kds-p-4 sm:kds-px-6 kds-w-full" infoText="Linkin lisätieto">
      Linkki 1
    </LinkWithInfo>
  </ListItem>
  <ListItem className="kds-m-0 kds--mt-px kds-border kds-border-solid kds-border-default">
    <LinkWithInfo href="#" className="kds-p-4 sm:kds-px-6 kds-w-full" infoText="Linkin lisätieto">
      Linkki 2
    </LinkWithInfo>
  </ListItem>
</List>

Valmistautuminen import-polkujen muutokseen

15.3.0 → 16.0.0

Yleistä

• Päivitä react- ja react-dom-kirjastot vähintään 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.