In deze release zijn twee nieuwe features aan het Logo component toegevoegd, die op zich niet breaking zijn, maar toch een toelichting behoeven.

Logo​

Voorheen kon een afnemer van het Logo component een anchor om het Logo component plaatsen om zo routering binnen de afnemende applicatie te faciliteren.

Markup voor deze situatie ziet er ongeveer zo uit:

<a href="/">
  <dso-logo label="Regels op de kaart"></dso-logo>
</a>

In deze release is het Logo component uitgebreid met 2 nieuwe properties: logoUrl en labelUrl.

logoUrl​

Indien de afnemer aan het Logo component de property logoUrl meegeeft, dan zal het Logo component een anchor met href zetten rondom het beeldmerk en het woordmerk. Wanneer een gebruiker deze link aanklikt dan zal het Logo component het custom event dsoLogoClick uitsturen.

labelUrl​

Indien de afnemer aan het Logo component de property labelUrl meegeeft, dan zal het Logo component een anchor met href zetten rondom het label. Voorwaarde is dan ook dat de property label is gezet. De property labelUrl zonder property label zal door het Logo component worden genegereerd. Wanneer een gebruiker deze link aanklikt dan zal het Logo component het custom event dsoLabelClick uitsturen.

De markup voor deze nieuwe mogelijkheden van het Logo component ziet er zo uit:

<dso-logo logo-url="/" label="Regels op de kaart" label-url="regels-op-de-kaart"></dso-logo>

Bekijk de nieuwe mogelijkheden in de storybook van het Logo component: https://storybook.dso-toolkit.nl/master/?path=/story/core-logo--with-logourl-and-label-and-labelurl

In deze release is een bug in de Modal opgelost waardoor in sommige gevallen de modal in een viewport onder 768px breedte verdween.

Modal​

De CSS-code die een deel van de markup op display: none zette, is verwijderd, en de HTML body detecteert nu automatisch of een modal is geopend:

Oud:

body.dso-modal-open {
  @media screen and (min-width: media-query-breakpoints.$screen-sm-min) {
    overflow: hidden;
  }

  @media screen and (max-width: media-query-breakpoints.$screen-xs-max) {
    .container,
    dso-banner,
    .dso-banner {
      display: none;
    }
  }
}

Nieuw:

body:has(dialog[open]),
body:has(dso-modal.hydrated) {
  // block scrolling of the body when a dialog is open
  overflow: hidden;
}

Het is bij de html/css-versie van de Modal dus niet meer nodig om de class dso-modal-open te zetten; de :has()-pseudoclass, sinds kort breed ondersteund, zorgt automatisch dat het scrollgedrag 'achter' de modal wordt uitgezet.

In deze release is een regressie bug in de Date Picker opgelost die in v60.0.0 is geintroduceerd.

Date Picker​

Het change event dsoDateChange van <dso-date-picker> moet de value als dd-mm-jjjj emitten. In versie v60.0.0 is dit per abuis jjjj-mm-dd geworden. In #2391 is dit opgelost en is de output format weer dd-mm-jjjj.

Tegelijkertijd hebben we #2380 Date Picker: Bij handmatige invoer van datum buiten min/max, geen event met error opgelost. Dit betekent dat event.error weer klopt. Met de komst van <input type="date"> in het Web Component is dit ook een erg beperkte API gebleven. Daarom hebben we de API uitgebreid met het validatieobject van de browser validity: ValidityState.

export interface DatePickerChangeEvent {
  component: "dso-date-picker";
  originalEvent: Event;
  value: string;
  valueAsDate: Date | undefined;
  error?: "required" | "min-range" | "max-range" | "invalid";

  // Nieuw
  validity: ValidityState;
}

Selectable​

Het SelectableChangeEvent was voorheen een alias voor Event. Dit was verwarrend en we hebben dit gelijkgetrokken met de overige events:

// ❌ Oud
interface SelectableChangeEvent extends Event {}

// ✅ Nieuw
export interface SelectableChangeEvent {
  originalEvent: Event;
  checked: boolean;
}

Voor het één-op-één migratiepad geldt dat het vorige DsoSelectableCustomEvent<SelectableChangeEvent>.detail object nu op DsoSelectableCustomEvent<SelectableChangeEvent>.detail.originalEvent staat:

event.detail === event.detail.originalEvent;

Voor de afnemers die de checked state willen weten kunnen ook gebruik maken van DsoSelectableCustomEvent<SelectableChangeEvent>.detail.checked:

event.detail.target.checked === event.detail.checked;

🚨 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.