# Componentcontracten — Vrules 2.3

Een component is pas af wanneer inhoud, bediening, alle relevante toestanden en herstel zijn beschreven. Gebruik native HTML waar mogelijk; maak geen ARIA-grid van een gewone tabel.

| Component | Anatomie en gedrag | Randgevallen en acceptatie |
| --- | --- | --- |
| App-shell | Project/organisatie, hoofdnavigatie, actieve route, h1, taakactie. Routes zijn links; lokale weergavewissels zijn knoppen. | Geen decoratieve accentlijn of inset-schaduw voor de actieve route. Gebruik neutrale vlakvulling, tekstgewicht en aria-current of aria-pressed waar van toepassing. Geen bovenkop die alleen de actieve route herhaalt. Geen dubbele actieve routes. Organisatiewissel benoemt scope en bewaakt onopgeslagen werk. Mobiel blijft dezelfde taak bereikbaar. |
| Zoek- en filterbalk | Zichtbaar label, zoekveld, relevante filters, resultaataantal, wisactie. | Nul resultaten verschilt van een lege database. Filters blijven bij terugkeer behouden. Kies URL-query voor deelbare filters; geen privézoektekst in publieke URL’s. |
| Gegevenstabel | Caption, echte th/td, scope, eenheden in kop, benoemde rijacties. Sorteerknop met aria-sort op th. | Null ≠ 0; geen klikbare hele rij zonder aparte link/knop. Sorteer numeriek/datumgetrouw. Paginering of virtualisatie alleen waar aantallen het vragen; aangekondigd bereik en behouden selectie. |
| Bulkselectie | Checkbox per rij en ‘selecteer deze pagina’, aantal geselecteerd, expliciete actie. | Selectie buiten filter of pagina moet benoemd worden. Geen stilzwijgende selectie van alle records. Bulkmutatie kent serverrechten en gedeeltelijke fouten. |
| Bord | Gelabelde fasen, aantal, compacte objectkaart, eigenaar en relevante deadline. | Verplaatsen kan via toetsenbordbesturing/selectie, niet uitsluitend slepen. Server controleert overgang. Op telefoon fasen onder elkaar. |
| Formulier | Permanent label, uitleg vóór invoer waar nodig, veldfout via aria-describedby, aria-invalid. | Toon fouten na submit of zinvol veldmoment, behoud alle invoer, focus eerste fout. Gebruik foutoverzicht bij veel fouten. Opslaan = pas succes na bevestigde opslag. Voorkom dubbel verzenden. |
| Detailpaneel / modal | Titel, sluitknop, logische volgorde, inhoud, taakacties. Native dialog met showModal in referentie. | Focus naar zinvol begin, binnen modal, Escape sluit via conceptbewaking, focus terug naar opener. Achtergrond inert. Bij onopgeslagen invoer: doorgaan met bewerken of expliciet verwerpen. |
| Tabs / stappen | Tabs alleen voor panelen binnen één object, volgens APG met pijltjestoetsen. Stappen tonen huidige stap en totaal. | Geen tabs gebruiken als onvolledige imitatie van routing. Vorige stap bewaart antwoorden. Verplichte invoer voorkomt onbedoeld overslaan. |
| Status en melding | Kort label + verklaring + mogelijke vervolgactie. Inline bij het betrokken object. | Kleur is aanvullend. role=status voor niet-dringende feedback, role=alert voor urgente fouten. Geen hele werkruimte als live region. Toast nooit enige plek van belangrijke foutinformatie. |
| Voortgang | Benoemde progress/max-waarden, tekst ‘3 van 8’, volgende stap. | Onderscheid gelezen, afgerond, getoetst en geslaagd. Onbekende duur geen schijnnauwkeurige percentagebalk. |
| Vergelijking | 2–4 gekozen objecten, dezelfde criteria/eenheden/bronkwaliteit, verwijder per object. | Vijfde selectie geeft verklaring. Selectie verandert geen boekingsstatus. Mobiel scrollregio met blijvende attribuutnamen of gestapelde vergelijkbare blokken. |
| Kaart/lijst | Werkelijke coördinaten, legenda, equivalent bereikbare lijst, geselecteerd object gedeeld. | Geen coördinaten? Geen gefingeerde pin. Verberg adres/reisdata volgens privacyregels. Map-provider en attributie blijven zichtbaar. |
| Kalender / tijdlijn | Datum, tijdzone, eigenaar/gebeurtenis en bron. Dag/maandnav heeft duidelijke namen. | Exacte deadlines niet alleen ‘morgen’. Zomertijd/grensgevallen testen. Datumvelden mogen native zijn; bereik heeft begin/eindvalidatie. |
| Grafiek / KPI | Naam, eenheid, periode, schaal, legenda, vergelijking en datatabel. | Nulbasis bij balken tenzij duidelijk gemotiveerd; ontbrekende waarden niet interpoleren zonder uitleg. Teken/patroon naast kleur. Geen ‘groei’ uit onvergelijkbare metingen. |
| Leerroutine / quiz | Eén vraag of beperkte taak, permanente antwoordlabels, expliciete controle, inhoudelijke feedback. | Geen schaamtecopy. Herproberen en hervatten volgens productregels. Timer waar mogelijk verstelbaar. Leraar-/leerlingrechten worden technisch geborgd. |
| Score-invoer / ranglijst | Deelnemerslabels, niet-negatieve gehele scores, opslagstatus, deadline/slot. | Invoer 0–0 is geldig; ontbrekend niet 0–0. Vergrendeling op servertijd. Gelijke punten volgens vastgelegde tie-break, nooit willekeurige rang suggereren. |
| Import / bronbewijs | Bestandsvereisten, inspectie, mapping, voorvertoning, rijgebonden fouten, bevestiging. | Onbekend formaat verandert geen records. Formules/tekst blijven data; AI-extractie blijft voorstel tot review. Toon herkomst en bewerkingsgeschiedenis. |

## Toestanden, voor ieder asynchroon werkgebied

- **Laden:** benoem wat laadt; aria-busy op het betrokken gebied. Skeletons alleen met stabiele geometrie. Geen verzonnen nulwaarden tijdens laden.
- **Leeg:** leg uit wat hier verschijnt en geef een passende eerste actie.
- **Geen zoekresultaten:** behoud zoekterm/filters; bied wissen aan.
- **Opslaan:** duidelijke voortgang, dubbele submit voorkomen, invoer bewaren.
- **Opgeslagen:** bevestiging met juiste scope en waar relevant tijdstip.
- **Fout:** feitelijke oorzaak voor zover bekend, bewaarde invoer, herstelactie. Geen blinde automatische herhaling van mutaties.
- **Offline / verouderd:** laatste succesvolle synchronisatie, welke handelingen beschikbaar zijn; geen offline-opslag beloven zonder implementatie.
- **Conflict:** toon lokale en nieuwe serverversie of bied opnieuw laden met conceptbehoud; nooit stil overschrijven.
- **Geen toegang / alleen lezen:** uitleg en legitieme vervolgroute; geen gevoelige inhoud lekken. Verbergen van knoppen vervangt geen serverautorisatie.
- **Uitgeschakeld:** reden nabij besturing, geen onleesbare tekst. Read-only blijft leesbaar/selecteerbaar en is geen foutstatus.

## Referentie versus productie

De werkplaats implementeert native dialog/focus, conceptbewaking, validatie, zoeken, statusfilter, tabel/bord, sorteren, vergelijking, voortgang, quizfeedback en scorevergrendeling als lokale voorbeelden. Navigatie wisselt zes demonstraties. Herladen reset de voorbeelden. Native confirm voor verwerpen is een functionele referentie; een product mag een gelijkwaardig toegankelijk bevestigingsvenster gebruiken. Conflict en offline zijn zichtbaar gekozen simulaties; koppel in productie echte foutcodes en retry-semantiek.

Niet als complete code geleverd: backendautorisatie, datagridvirtualisatie, bulkmutaties, kaartprovider, bestandsimport, betalings- of boekingsflow. Gebruik het contract en de bestaande projectimplementatie; presenteer documentatie niet als geteste productiefunctionaliteit.
