🚨 Breaking release! We hebben een nieuw component erbij: het logo! Je kunt nu door middel van dit component gemakkelijk een smal logo in de header plaatsen. Om te laten zien hoe dat werkt hebben we het header component in Storybook ook aangepast. De wijzigingen in het logo maken dit een breaking change.

Logo​

In de oude situatie gaf je één of twee statische afbeeldingen door aan het header component. Een afbeelding voor het logo (een afbeelding van het beeldmerk en het woordmerk) en een afbeelding met daarin de applicatienaam.

In het component laden we nu alleen het beeldmerk als afbeelding in (als inline SVG), en komen het woordmerk, de 'ribbon' en de applicatienaam terug als tekst. Dit maakt het gebruik van het logo flexibeler en toegankelijker, en bovendien konden we het bepaald gewenst responsive gedrag meegeven.

Vanaf nu kun je op deze manier het logo tonen in je applicatie:

<dso-logo label="Regels op de kaart" ribbon="beta"></dso-logo>

De applicatienaam geven we mee als label op het dso-logo component. Dit label is optioneel.

Het 'beta' blokje dat in deze fase op het logo staat kan worden ingezet door het logo component het attribuut ribbon mee te geven met de gewenste tekst. Zo kunnen we het logo straks ook gebruiken om visueel te communiceren dat we bijvoorbeeld op de pre- of acceptatie omgeving zijn. Ook dit attribuut is optioneel.

Afgesproken is om voor voornoemde gebruik steeds de prefix van de omgeving te gebruiken:

Opgelet: de header verandert ook​

Om het logo in het header component te plaatsen en goed te laten zien, is ook het header component aangepast. Er is nu geen sub-logo slot meer.

❌
<dso-header>
  <div slot="logo">
    <img alt="Omgevingsloket" src="LOGO" />
  </div>
  <img slot="sub-logo" alt="Regels op de kaart" src="LABEL" />
</dso-header>

✅
<dso-header>
  <div slot="logo">
    <dso-logo label="Regels op de kaart" ribbon="beta"></dso-logo>
  </div>
</dso-header>

Responsive gedrag​

Het nieuwe logo component wordt zo breed als nodig, maar als er niet genoeg ruimte is krimpt het vanzelf.

Op beeldschermen waar er genoeg ruimte is om het hoofdmenu volledig te tonen, ziet de bezoeker het beeldmerk, de tekst 'Omgevingsloket' met een beta ribbon, en de applicatienaam. In dit geval de tekst 'Maatregelen op maat'.

Als het scherm minder breed is, bijvoorbeeld bij tablets, verdwijnt de tekst Omgevingsloket en wordt alleen de applicatienaam Maatregelen op maat getoond. Deze tekst lijnt uit met een knop waarmee het menu kan worden geopend.

Op kleine telefoons waar de applicatienaam niet op één regel past, wordt de tekst vanzelf verdeeld over twee regels. De tekst blijft verticaal gecentreerd uitgelijnd ten opzichte van het logo.

Viewer Grid​

In #2161 hebben we ondersteuning voor de VDK layout gemaakt. Tegelijkertijd hebben we het component stateless gemaakt, in lijn met onze visie op stateful vs. stateless components.

Dit betekent dat afnemers van het Viewer Grid met de VRK layout ook werk moeten verzetten.

Stateless​

Voorheen was de breedte van het linkerpaneel onderdeel van de interne state. Nu moet de afnemer dit bijhouden. Hetzelfde geldt voor de "responsive tab view".

Hierdoor is de property initialMainSize komen te vervallen.

Interfaces​

API​

Bovenstaande opmerkingen komen enigszins in onderstaande markup voorschriften samen. Dit is exclusief de nieuwe functionaliteit die is ontwikkeld voor VDK.

❌
<dso-viewer-grid
  [initialMainSize]="'medium'"
  (dsoMainSizeChange)="$event.detail.stage === 'end' && resizeMap()"
></dso-viewer-grid>

✅
<dso-viewer-grid
  [mainSize]="mainSize"
  (dsoMainSizeChange)="mainSize = $event.detail.nextSize"
  [activeTab]="activeTab"
  (dsoActiveTabSwitch)="activeTab = $event.detail.tab"
  (dsoMainSizeChangeAnimationEnd)="resizeMap()"
></dso-viewer-grid>

Date Picker​

In #2226 zijn de maatwerk routines in Date Picker vervangen door de browser native <input type="date">. Dit gaat alleen over de implementatie van het Web Component. Dit betekent iets minder invloed maar veel betere toegankelijkheid.

Properties​

De volgende properties zijn komen te vervallen:

Interfaces hernoemd​

De interfaces van de Date Picker waren onterecht geprefixed met Dso.

In deze breaking release zijn de API's van Banner, Tooltip en Ozon Content aangepast.

Banner​

In deze breaking release hebben we de legacy CSS selector voor Banner verwijderd. Deze is sinds v22.0.0 deprecated.

Het migratiepad is gebruik maken van de namespaced CSS selector: dso-banner.

❌
<div class="banner"></div>

✅
<div class="dso-banner"></div>

Tooltip​

Zoals in 58.0.0 aangekondigd, is de HTML/CSS implementatie van Tooltip verwijderd. Zie de blogpost van versie 58.0.0 voor de onderbouwing.

Het migratiepad omvat het gebruik van het Web Component.

Migratie naar Web Component​

❌
<div class="tooltip fade in top|right|bottom|left" aria-hidden="true">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">LABEL</div>
</div>

✅
<dso-tooltip position="POSITION" descriptive>
  LABEL
</dso-tooltip>

Ozon Content​

Een deel van de functionaliteit van dit component is verhuisd naar Document Component.

Concreet betekent dit:

• De property deleted bestaat niet meer.
• De property interactive bestaat niet meer.
• Het event dsoClick met bijbehorend event model OzonContentClick bestaat niet meer.
• Het model OzonContentAnchorClick van het event dsoAnchorClick is hernoemd naar OzonContentAnchorClickEvent
• De slots prefix en suffix zijn verwijderd.

Er is geen uitgestippeld migratiepad. Hoogstwaarschijnlijk wil je als high-level afnemer gebruik maken van Document Component. Ozon Content kan gezien worden als een "Low Level component".

Een spiksplinternieuwe Modal is de oorzaak van deze breaking release! Daarnaast zijn er wat kleine (maar breaking) changes voor het Viewer Grid.

Verder hebben we van het Tooltip component de HTML/CSS implementatie deprecated. In sprint 27.6 verwijderen we de code. Tot die tijd werkt het component ongewijzigd.

Modal​

Modal heeft het HTML5 element dialog geadopteerd en ondersteunt nu ook een fullscreen modus.

HTML/CSS component .dso-modal​

Het root element waar de class .dso-modal is vanaf nu een dialog. Voor afnemers van het HTML/CSS component moet het dialog nog worden geactiveerd met HTMLDialogElement.showModal().

Fullscreen​

De modifier class .dso-fullscreen zorgt voor volledige scherm weergave:

<dialog class="dso-modal dso-fullscreen"></dialog>

Web Component <dso-modal>​

Fullscreen​

Het attribute [fullscreen] zorgt voor volledige scherm weergave:

<dso-modal fullscreen></dso-modal>

Return Focus (returnFocus)​

Het HTML5 element dialog heeft ingebouwde functionaliteit die dit vervangt. Zo wordt bij het sluiten van een dialog de focus teruggezet naar het element wat focus had bij het openen van dialog.

Het migratiepad geeft geen alternatieve oplossing. Het nieuwe inzicht is dat we die overlaten aan de user agent. Dit betekent dat de afnemer het gebruik van returnFocus moet verwijderen.

Initial Focus (initialFocus)​

Dit wordt nu met het autofocus attribuut geregeld. Zet dit attribuut op het interactieve element in de Modal. Als er geen autofocus attribuut is, zet dialog de focus standaard op het eerste focusable element binnen de dialog.

❌
<dso-modal initial-focus="#mijn-knop">
  <button type="button" class="dso-primary" id="mijn-knop">
    <span>Klik!</span>
  </button>
</dso-modal>

✅
<dso-modal>
  <button type="button" class="dso-primary" autofocus>
    <span>Klik!</span>
  </button>
</dso-modal>

Modal Factories​

De ModalController voor Angular en de ModalRef voor React zijn met dialog niet meer nodig en dus verwijderd.

Migratiepad: Maak direct <dso-dialog> of <DsoDialog> waar nodig. De nieuwe top-layer zorgt ervoor dat je zelfs meerdere Modals tegelijkertijd kan openen.

Viewer Grid​

Bij een functionele uitbreiding kwamen er bij de events wat inconsistenties naar voren.

(De *CustomEvent modellen zijn aliassen voor CustomEvent met een typed .target element.)

export interface ViewerGridCloseOverlayEvent {
  originalEvent: MouseEvent | Event;
}

export interface ViewerGridFilterpanelCancelEvent {
  originalEvent: MouseEvent | Event;
}

export interface ViewerGridFilterpanelApplyEvent {
  originalEvent: MouseEvent | Event;
}

Dit betekent dat bij DsoCloseOverlay het originele event niet meer op DsoViewerGridCustomEvent.detail zit, maar op DsoViewerGridCustomEvent.detail.originalEvent. De andere twee changes zijn geen breaking changes per se, maar de naam van het model is gewijzigd.

Tooltip: HTML/CSS implementatie​

Een toegankelijke tooltip is heel veel werk. Bij de HTML/CSS implementatie is het voornamelijk documentatie. Na de zoveelste bevinding hebben we besloten het Tooltip component te deprecaten ten gunste van de Web Component implementatie.

Migratie naar Web Component​

❌
<div class="tooltip fade in top|right|bottom|left" aria-hidden="true">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">LABEL</div>
</div>

✅
<dso-tooltip position="POSITION" descriptive>
  LABEL
</dso-tooltip>

Dit is een breaking release vanwege de volgende issues:

• #1776 Button: Legacy Bootstrap selectors verwijderen

Button: Legacy Bootstrap selectors verwijderen​

Lang lang geleden... Was de toolkit bovenop Bootstrap gebouwd. Bootstrap heeft ons een hoop gebracht, maar heeft ons ook in de weg gezeten. Zo'n 4 jaar geleden zijn wij begonnen met loskomen van Bootstrap. Dat is aardig gelukt en met dit issue zijn we er bijna.

Impact​

Deze change heeft impact op de volgende componenten:

• Button: <button class="btn btn-primary">, <button class="btn btn-default">, <button class="btn btn-link">
• Button Group. Alleen HTML/CSS implementatie: <div class="dso-btn-group">.
• Alert. Alle implementaties: <div class="alert">, <dso-alert> en <DsoAlert>.

Button​

Met de "Legacy Bootstrap selectors" bedoelen we de volgende classes:

• btn
• btn-primary
• btn-default
• btn-link
• btn-sm

DSO Toolkit versie 25.0.0 van 2 juli 2021 bevatte issue #856 waarmee we bovenstaande classes hebben omgezet naar de UX en toolkit classes dso-tertiary, dso-secondary en dso-tertiary. Sinds 2 jaar ontmoedigen we het gebruik van de Bootstrap basis classes.

Zie de volgende tabel hoe de classes gemigreerd worden.

❌
<button type="button" class="btn btn-primary btn-sm btn-align">
  <span>Dit is een voorbeeld</span>
</button>

✅
<button type="button" class="dso-primary dso-small dso-align">
  <span>Dit is een voorbeeld</span>
</button>

Button Group​

Dit component had de root selector .dso-btn-group. Dat is nu .dso-button-group.

❌
<div class="dso-btn-group">
  <button></button>
  <button></button>
  <button></button>
</div>

✅
<div class="dso-button-group">
  <button></button>
  <button></button>
  <button></button>
</div>

Alert​

Het Alert component maakte alleen van de basis class btn gebruik. Deze class is vervangen door dso-alert-button:

Dit geldt voor alle implementaties!

❌
<div class="alert alert-success">
  <!-- of <dso-alert status="success"> of <DsoAlert status="success"> -->
  <div class="dso-rich-content">
    <p>Succes!</p>
    <button type="button" class="btn">
      <span>Button</span>
    </button>
  </div>
</div>

✅
<div class="alert alert-success">
  <div class="dso-rich-content">
    <p>Succes!</p>
    <button type="button" class="dso-alert-button">
      <!--                      👆 -->
      <span>Button</span>
    </button>
  </div>
</div>

De vorige breaking release is nog niet afgekoeld of er ligt alweer een nieuwe breaking release op de plank. Hoewel v55.0.0 alleen formeel een breaking release was (er ging niets stuk), zal dat voor afnemers van Accordion, Annotation Button, Annotation Output, Expandable en Expandable Heading wel het geval zijn.

Accordion​

Zoals in de vorige blogpost aangekondigd hebben wij onze visie op State en toolkitcomponenten herzien. De Web Component implementatie van Accordion is het eerste component wat we bijwerken naar deze nieuwe visie.

De HTML/CSS implementatie van Accordion heeft geen changes.

API changes​

• De property status is hernoemd naar statusExplanation. De werking is ongewijzigd.
• De property state is hernoemd naar status. De werking is ongewijzigd.

De events dsoToggleSection en dsoToggleSectionAnimationEnd zitten niet meer op Accordion maar zijn verhuisd naar de Accordion Section en zijn hernoemd naar dsoToggleClick en dsoAnimationEnd.

Met het verwijderen van interne state is de property allowMultipleOpen obsolete geraakt. Deze property is dus ook verwijderd.

Geen interne state​

De interne state van de Accordion is verwijderd. Dit betekent dat afnemers meer moeten aansluiten. Het voordeel is dat afnemers meer invloed op de Accordion hebben en dat de Accordion volledig opgaat in de state van de applicatie.

Helper functie scrollIntoView().​

Op het AccordionSectionAnimationEndEvent object staat een helperfunctie scrollIntoView(). De afnemer kan deze aanroepen om de Accordion Section in beeld te scrollen.

Annotation Button​

Dit component is stateless gemaakt. De afnemer moet zorg dragen voor state management. Bij het tonen van Annotation Output moet ook dit component open="true" krijgen.

<dso-annotation-button [...] open>[...]</dso-annotation-button>

Annotation Output​

Het event dsoToggle is hernoemd naar dsoClose. Daarnaast is dit component stateless gemaakt. Dit betekent dat de content van dit element pas toont als open="true" is gezet:

<dso-annotation-output [...] open>[...]</dso-annotation-output>

Expandable​

Het named slot "expandable-content" is omgezet naar een nameless slot:

❌
<dso-expandable>
  <div slot="expandable-content">
    [...]
  </div>
</div>

✅
<dso-expandable>
  <div>
    [...]
  </div>
</div>

Expandable Heading​

Dit component is komen te vervallen met de komst van Document Component.

Het is alweer een aantal releases geleden dat er een blogpost is geplaatst. Maar dat mag de pret voor deze release niet drukken.

Samenstelling team​

Thomas Rijsewijk (@tfrijsewijk) is sinds 15 mei Product Owner van de DSO Toolkit. Hans Grimm (@hansgrimm) is sinds 1 juni Front-End Developer en toegankelijkheidsexpert.

In de loop van dit jaar wordt het team nog met een developer versterkt.

Stateful vs. stateless components​

Sinds 3 jaar biedt de toolkit Web Components aan. Sommige componenten waren daarnaast ook voorzien van een interne state. Met name het afgelopen half jaar is duidelijk geworden dat de interne state conflicteert met de wensen van de afnemers.

Daarom gaan wij onze componenten stateless maken. Het gevolg is dat het koppelvlak groter wordt en dat afnemers meer zullen moeten programmeren. Daartegenover staat dat afnemers alle invloed hebben op de state van het component. Een groot voordeel daarvan is dat componenten hun state uit de URL kunnen krijgen en dat de state van de applicatie beter te delen is.

Dit is een breaking change en voor elk component dat is omgebouwd zal een breaking release worden uitgebracht.

De uitverkorenen om op korte termijn te worden aangepakt zijn:

• Accordion.
• Image Overlay.
• Viewer Grid.

Dit betekent niet dat toolkitcomponenten stateless moeten zijn. De grens zal liggen tussen de interne werking van een component (bv. de state van animaties) en presentatie (bv. de breedte van een paneel of hoeveel Accordion secties er open staan.) Waar de grens precies ligt zullen we in overleg met afnemers en de UX designers bepalen.

Uitgelicht​

In deze release hebben we 8 bugs gefixed. Daarnaast hebben we twee nieuwe features geintroduceerd en één breaking change doorgevoerd.

Voor alle wijzigingen verwijs ik je naar de CHANGELOG van deze release.

Modal (breaking change)​

In (#2092) hebben we de presentatie van het Modal verbeterd. Bij het na-testen kwamen nog twee kleine puntjes aan het licht. Deze worden in (#2223) opgelost.

Dit is een breaking change omdat de markup voorschriften van de HTML/CSS implementatie van Modal zijn gewijzigd. Het element <div class="dso-body"> moet door een Scrollable worden gewrapped:

<div class="dso-modal">
  <!-- [...] -->
  <div class="dso-dialog">
    <dso-scrollable>
      <div class="dso-body">
        <!-- Inhoud van Modal -->
      </div>
    </dso-scrollable>
  </div>
</div>

Voor het Web Component zijn er geen breaking changes. Daar krijg je de functionaliteit van Scrollable cadeau.

Voor afnemers die geen gebruik maakt van Web Componenten kan het <dso-scrollable> component achterwege worden gelaten. De Modal zal dan nog steeds werken maar zonder de schaduwrandjes die Scrollable levert.

Button Row​

Button Row heeft een nieuwe variant "emphasized" om knoppen uit te lichten.

• HTML/CSS implementatie: Onder de modifier class .dso-emphasized.
• Web Component: Onder het attribuut [emphasized] en de property HTMLDsoButtonRowElement.emphasized = true.

Map Controls​

De knop waarmee de Map Controls wordt getoond heeft op smalle viewport geen visueel label meer.

Lifecycle management​

We hebben een update naar Storybook 7 gedaan. Dit was niet geheel pijnloos. Wij maken geen gebruik van CSF. De komende periode gaan we onze stories omschrijven naar CSF zodat we ook naar Storybook 8 kunnen.

In deze breaking release is met name de CDN een punt van aandacht.

CDN​

De CDN heeft een andere layout gekregen. Toen we begonnen met de toolkit was er maar één package. Inmiddels zijn er veel meer packages. Vanaf deze release worden packages in een eigen directory naar de CDN gepubliceerd.

Dit betekent applicaties die dso-toolkit via de CDN gebruiken een andere URL moeten gebruiken.

• voorheen: https://cdn.dso-toolkit.nl/<versie>/<dso-toolkit artifacts>
• nu: https://cdn.dso-toolkit.nl/dso-toolkit/<versie>/<dso-toolkit artifacts>.

Zie de documentatie over de CDN voor meer informatie.

Incomplete release artifacts​

Sinds versie 48.0.0 zijn er incomplete releases naar de CDN gepubliceerd. De package layout van dso-toolkit is gewijzigd. Voorheen zat alles in /dist. Uitsluitend de bestanden in deze directory werden naar de CDN gepubliceerd. Icons, illustraties en fonts zijn verhuisd naar /assets en werden niet gepubliceerd naar de CDN. Fonts die vanuit dso.css worden aangeroepen werken dus niet.

Concreet betekent dit dat CDN gebruikers vanaf nu de volgende url voor dso.css kunnen gebruiken:

https://cdn.dso-toolkit.nl/dso-toolkit/<versie>/dist/dso.css

Waar <versie> een semver zonder prefix vanaf 50.0.0, of master is.

Minified CSS​

De toolkit levert dso.css nu ook geminified: dso.min.css. Daarnaast zijn beide stylesheets voorzien van sourcemaps vanaf de SCSS stylesheets.

Vertrek Thomas Rijsewijk​

Per 1 februari werk ik niet meer aan de toolkit en daarmee is deze release mijn laatste.

Ik ben trots op wat we bereikt hebben. Waar we 6 jaar geleden begonnen met een stijlgids zijn we inmiddels uitgegroeid tot een volwaardig open source Design System.

Simon Rijsewijk neemt mijn taken over. Ik weet zeker dat hij de toolkit naar een nog hover niveau weet te brengen.

Iedereen bedankt voor het vertrouwen en de prettige samenwerking, het was een mooie reis.

Modal​

In deze release is #1989 opgelost.

• Voor het HTML/CSS component zijn de markup voorschriften gewijzigd: Het element .dso-modal .dso-body moet een attribuut tabindex="0" krijgen.
• Voor het Web Component zijn geen wijzigingen voor afnemers.

In versie 49.0.0 werken de fonts niet, dit is gefixed in 49.0.1

Dit is de laatste (BREAKING) release van 2022.

Breaking changes​

De indeling van de NPM package dso-toolkit is aangepast.

• De stylesheet: dso-toolkit/dist/toolkit/styles/dso.css -> dso-toolkit/dist/dso.css
• De icon spritesheet: dso-toolkit/dist/toolkit/dso-icons.svg -> dso-toolkit/dist/dso-icons.svg
• De fonts: dso-toolkit/dist/toolkit/fonts -> dso-toolkit/assets/fonts

Er is geen formele definitie wat de publieke API van de toolkit is. Hier zijn we mee bezig in het kader #1882. We helpen je graag verder als je bij het updaten naar versie 49.0.0 vastloopt op de package layout.

Issue highlights​

• Feature: Accordion is uitgebreid met scroll into view (#1875).
• Fixed: dso-accordion props komen niet goed door bij initiele render van de React binding <DsoAccordion /> (#1930).

Angular​

Vanaf nu publiceren we Angular bindings in @dso-toolkit/angular. Dit deden we al een tijd voor React met @dso-toolkit/react. Zie de documentatie voor meer informatie: Angular bindings.

Storybook Composition​

Met de komst van Angular bindings was er ook noodzaak voor een extra Storybook. Samen met de HTML/CSS + Web Components en React bindings levert de DSO Toolkit 3 Storybooks. Tot de vorige release publiceerden we deze Storybooks los naar https://storybook.dso-toolkit.nl en https://react.storybook.nl. Vanaf nu publiceren we alle Storybooks als één Storybook naar https://storybook.dso-toolkit.nl.

Zie de link in de primaire navigatie om de Storybook voor de huidige versie te openen.

Tot volgend jaar!