📝 Keywords en aliassen bepaald - uitbreiden met "Gerelateerde componenten"

[eslook]

TLDR

Tijdens Unordered List (#1051 (comment)) en Ordered List (#1052 (comment)) kwam ook uit zichzelf naar voren welke componenten volgens bronnen (en een beetje volgens de community) gerelateerd zijn aan de componenten. Dit is informatie waar we op dit moment niets mee doen, dat is zonde. Met kernteam is afgestemd dat we ze willen documenteren als onderdeel van deze stap.

(Mini context: we hebben al 'gerelateerde componenten' genoteerd in de backlog issue, en de discussion, maar die zijn vastgesteld tijdens de Help Wanted fase. Tijdens Candidate updaten we keywords en aliassen, en daar komen we dus ook meer over gerelateerde componenten tegen.)

User Story

Oplossingsrichting

Scope:

• Dit word in de documentatie repository gedocumenteerd, niet candidate repo; omdat de candidate repo de componenten op zichzelf moeten staan.
• Het idee is dat dit in de vorm van een json komt.
• Optioneel maken we het ook direct zichtbaar op de website, maar dat is niet de prioriteit van deze stap, het gaat vooral om de gewonnen informatie niet te verspillen.
  • Als we dat doen, houden we het huidige format "Gerelateerde componenten: Alert, Modal Dialog, Dialog." aan. We gaan niet direct de verbetering doen van "Gerelateerde componenten: Alert, Modal Dialog, Dialog." naar "Gebruik Alert wanneer x. Gebruik Modal Dialog wanneer y. Gebruik Dialog wanneer z.".

Actiepunten

• Voorstel over data opzet.
• Optioneel voorstel voor direct weergeven op de website.
• Afstemmen met kernteam
• Uitvoeren voor de resultaten van Unordered List en Ordered List.
• Losse issue maken voor overige componenten Opnemen gerelateerde componenten data op website voor alle componenten documentatie#3966
• Issue template updaten met stap adhv ervaring.

Acceptatiecriteria

• Gerelateerde componenten voor Unordered List en Ordered List zijn vastgelegd.
• De Gerelateerde componenten werkwijze en data is afgestemd met het kernteam.
• Follow-up issue voor andere componenten is aangemaakt.
• Issue template is bijgewerkt.

[eslook]

Case "gerelateerd aan"

Relaties:

• Alert is gerelateerd aan: Alert Dialog, Notification Banner, Note.
• Alert Dialog is gerelateerd aan: Alert, Modal Dialog, Dialog.
• Note is gerelateerd aan: Alert, Notification Banner.

Regels:

• Alert is gerelateerd aan Alert Dialog.
• Alert Dialog is gerelateerd aan Modal Dialog.
• Maar: Alert is niet gerelateerd aan Modal Dialog.
• Note is gerelateerd aan Alert.
• Alert is gerelateerd aan Alert Dialog.
• Maar: Note is niet gerelateerd aan Alert Dialog.

[eslook]

Eerste poging: duplicatie voorkomen

Initieel was het idee om relaties aan te geven maar wel duplicatie te voorkomen.

Afgewezen data format 1 (groepen)

{
  "relations": [
    ["Note", "Alert", "Notification Banner"],
    ["Alert", "Alert Dialog", "Notification Banner", "Note"],
    ["Alert Dialog", "Alert", "Modal Dialog", "Dialog"]
  ]
}

Probleem:

• Als we hieruit de relaties voor "Alert" zoeken, moeten we kiezen tussen: "de eerste array die je tegenkomt waar Alert in voorkomt" of "alle arrays waar Alert in voorkomt" en beide geven ongewenste resultaten.
• Daarnaast is het onduidelijk voor kernteam waar ze iets moeten toevoegen. Moeten ze een nieuwe array maken? Of een bestaande array aanpassen? En welke array dan?

Afgewezen data format 2 (edge list met arrays)

{
  "relations": [
    ["Alert", "Alert Dialog"],
    ["Alert", "Notification Banner"],
    ["Alert", "Note"],
    ["Alert Dialog", "Modal Dialog"],
    ["Alert Dialog", "Dialog"],
    ["Note", "Notification Banner"]
  ]
}

Voordeel:

• expliciete relaties
• geen impliciete verbanden

Probleem:

• minder leesbaar per component
• nog steeds onduidelijk voor kernteam waar en wanneer je iets moet toevoegen
• array impliceert 2 waarden, maar dwingt dat niet af, kan dus ook ander aantal bevatten

Verbetering: expliciete keys

{
  "relations": [
    {
      "from": "Alert",
      "to": "Alert Dialog"
    },
    {
      "from": "Alert",
      "to": "Notification Banner"
    },
    {
      "from": "Alert",
      "to": "Note"
    },
    {
      "from": "Alert Dialog",
      "to": "Modal Dialog"
    },
    {
      "from": "Alert Dialog",
      "to": "Dialog"
    },
    {
      "from": "Note",
      "to": "Notification Banner"
    }
  ]
}

Maar:

• dan ben je eigenlijk al bezig met config per component, echter op een onhandige manier, omdat je meerdere configs hebt per component
• de data word er niet leesbaarder op, en de lookup functie moet rekening houden met zowel de from als to

Conclusie

Pogingen om duplicatie te voorkomen leiden tot:

• impliciete logica die ongewenst is
• slechtere kernteam experience dat kan leiden tot fouten of inconsistenties

Dus dan kan je beter direct een config per component te schrijven, zoals hierop volgt.

[eslook]

Tweede poging: config per component

Data format 1 (basis)

{
  "relations": [
    {
      "name": "Alert",
      "items": ["Alert Dialog", "Notification Banner", "Note"]
    },
    {
      "name": "Alert Dialog",
      "items": ["Alert", "Modal Dialog", "Dialog"]
    },
    {
      "name": "Note",
      "items": ["Alert", "Notification Banner"]
    }
  ]
}

Voordelen:

• enkele config per component
• makkelijk aanpasbaar voor kernteam
• geen impliciete relaties

Verbetering: direct object ipv array

Nog duidelijker is

• om de json als map te gebruiken, zo is de lookup functie eenvoudiger en voorkom je fool-proof dubbele entries
• om de key items te hernoemen naar iets explicieter

{
  "Alert": {
    "related_to": ["Alert Dialog", "Notification Banner", "Note"]
  },
  "Alert Dialog": {
    "related_to": ["Alert", "Modal Dialog", "Dialog"]
  },
  "Note": {
    "related_to": ["Alert", "Notification Banner"]
  }
}

Voorbereiding op toekomstige cases

De huidige structuur maakt het ook makkelijk om in de toekomst optioneel uit te breiden, naar meerdere relatie types, zoals:
Voorbereid voor optioneel andere type groeperingen in de toekomst, zoals 'alles gerelateerd aan' of 'maakt gebruik van' of 'word gebruikt in' etc.

De reden dat we het hier over hebben, is omdat hier al eerder over gesproken is in het kernteam. Het is geen vereiste om er rekening mee te houden, maar met dit stukje laten we zien dat het dus wel mogelijk is.

Case "maakt gebruik van":

• Alert maakt gebruik van: Icon, Paragraph.
• Alert Dialog maakt gebruik van: Icon, Paragraph, Button, Actions.
• Form Field maakt gebruik van: Form Field Description, Form Field Error Message, Form Field Label, Form Field Label Suffix.

Case "word gebruikt in":

• Text Input word gebruikt in: Form Field.
• Form Field Description word gebruikt in: Form Field.
• Form Field Error Message word gebruikt in: Form Field.
• Form Field Label word gebruikt in: Form Field.
• Form Field Label Suffix word gebruikt in: Form Field.

Case "is gegroepeerd in":

• Modal Dialog, Alert Dialog, Dialog zijn allemaal gegroepeerd in: "Dialogs".
• Text Input, Number Input, Password Input, Date Input, File Input, Text Area zijn allemaal gegroepeerd in: "Form Controls".

Scope:

• We willen niet impliciete relates laten zien: we willen niet zeggen, Icon word gebruikt in [gigantische lijst]. De relaties zijn expliciet omdat we de community willen helpen met keuzes maken en overzicht vinden.

Voorgesteld data format 2 (definitief)

{
  "Alert": {
    "related_to": ["Alert Dialog", "Notification Banner", "Note"],
    "uses": ["Icon", "Paragraph", "Actions", "Button"],
    "used_in": [],
    "grouped_in": ["Dialogs"]
  },
  "Text Input": {
    "related_to": [],
    "uses": [],
    "used_in": ["Form Field"],
    "grouped_in": ["Form Controls"]
  }
}

Conclusie

Het voorgestelde format met config per component is:

• expliciet adhv relaties die we uit onderzoek hebben bevonden
• voorkomt impliciete relaties
• goed te begrijpen en onderhouden door kernteam
• optioneel uitbreidbaar in de toekomst

De relaties:

• helpen gebruikers bij het ontdekken van relevante components en begrijpen van structuur
• moeten expliciet en intentioneel blijven adhv wat kernteam heeft onderzocht. Geen automatische 'omdat Icon word gebruikt in a t/m z, laat a t/m z zien als gerelateerde componenten voor Icon'.

Duplicatie is toegestaan:

"Alert": { "related_to": ["Note"] },
"Note": { "related_to": ["Alert"] }

Dat is bewust want:

• voorkomt impliciete logica
• verhoogt leesbaarheid en aanpasbaarheid door kernteam

[eslook]

Dat geeft ons deze data, aan de hand van de pagina's die al een "Gerelateerde componenten: " blokje op de website hebben, plus de Ordered List en de Unordered List waaruit deze issue naar voren kwam:

{
  "Notification Banner": {
    "related_to": [
      "Alert",
      "Note"
    ]
  },
  "Note": {
    "related_to": [
      "Alert",
      "Notification Banner"
    ]
  },
  "Modal Dialog": {
    "related_to": [
      "Alert Dialog",
      "Drawer",
      "Dialog"
    ]
  },
  "Drawer": {
    "related_to": [
      "Modal Dialog",
      "Dialog"
    ]
  },
  "Dialog": {
    "related_to": [
      "Alert Dialog",
      "Drawer"
    ]
  },
  "Alert Dialog": {
    "related_to": [
      "Alert",
      "Modal Dialog",
      "Dialog"
    ]
  },
  "Alert": {
    "related_to": [
      "Alert Dialog",
      "Notification Banner",
      "Note"
    ]
  },
  "Unordered List": {
    "related_to": [
      "Ordered List",
      "Rich Text Content",
      "Link List",
      "Task List"
    ]
  },
  "Ordered List": {
    "related_to": [
      "Rich Text Content",
      "Unordered List"
    ]
  }
}

Suggestie is om deze op te slaan als relations.json in src/components/.

[eslook]

Suggestie indien gewenst direct toe te passen op de documentatie website

Indien we de JSON ook direct willen gebruiken en weergeven op de website, kan je de hardcoded code op bijvoorbeeld Alert Dialog:

// docs/componenten/alert-dialog/index.mdx

<p>
  Gerelateerde componenten: <a href="/alert/">Alert</a>, <a href="/modal-dialog/">Modal Dialog</a>,{" "}
  <a href="/dialog/">Dialog</a>.
</p>

vervangen met:

// docs/componenten/alert-dialog/index.mdx

import {
  Related,
} from "@site/src/components/ComponentPage";

<Related component={component} />

En dan de Related component exporteren vanuit de ComponentPage:

// src/components/ComponentPage.tsx

import relationMap from './relations.json';

export const Related = ({ component }: ComponentPageSectionProps) => {
  const relatedComponents = component && relationMap[component.title] ? relationMap[component.title].related_to : [];
  return (
    relatedComponents.length > 0 && (
      <Paragraph>
        Gerelateerde componenten:{' '}
        {relatedComponents.map((relatedComponent, index) => (
          <>
            <Link href={`/${relatedComponent.toLowerCase().replaceAll(' ', '-')}`}>{relatedComponent}</Link>
            {index < relatedComponents.length - 1 ? ', ' : '.'}
          </>
        ))}
      </Paragraph>
    )
  );
};

Hier kan nog besproken worden of we de slug willen doen middels:

• aanname dat het format altijd gebaseerd is op de naam van de component /${relatedComponent.toLowerCase().replaceAll(' ', '-')}
• uitgebreider: invullen in de JSON, maar mogelijk ie "Note": { "related_to": [ { "name": "Alert", "slug": "/alert" }] }
• nog uitgebreider: uit docusaurus de slug halen adhv de component naam
• iets anders

Beslissing: met Yolijn op donderdag 26 maart 2026 tijdens Refinement besproken dat huidige aanname werkwijze prima is. Ergens in de toekomst waarin we het uitbreiden ooit met andere dingen, kunnen we kijken naar slug of id.

[eslook]

Besproken op donderdag 26 maar tijdens Refinement met Yolijn.

• Data format OK? Ja:
  • We houden het nog simpeler, dus direct "Note": ["Alert"].
• Direct ook gebruiken om huidige hardcoded te vervangen? Ja:
  • Maar we plaatsen 'm direct onder Community
  • Huidige hardcode vervangen met Related component, en die data opnemen in relations.json
  • Direct de Unordered List en Ordered List related date in relations.json opnemen
  • Losse issue om alle componenten die al Help Wanted door zijn gegaan, om de related components daarvan in relations.json op te nemen

Draft PR in documentatie voor bovenstaande twee: nl-design-system/documentatie#3949.