Implémentation de `agtc-table`

---

Contexte

agtc-table est le composant le plus utilisé du site généré : 692 occurrences de token-row/token-table (tables de tokens : token CSS → référence → valeur → intention), plus les tables de comparaison et les tables DOs/DON'Ts. La gap-analysis du 2026-06-03 l'a identifié comme premier composant à construire à partir des besoins réels du site.

Constat à la création : le HTML d'origine du site n'a ni scope sur les <th> ni <caption> — un trou d'accessibilité que ce composant comble.

La table est en lecture seule : les tables documentaires n'ont pas besoin d'édition, de tri ni de pagination. On évite la conception spéculative tout en gardant la porte ouverte.

---

Décisions

Décision 1 — Architecture « mix » : composant piloté par données + classe light DOM

Deux formes consommant les mêmes tokens component.table.* :

1. <agtc-table> (Lit, shadow DOM) — piloté par .columns/.rows. Pour les apps, les contextes JS et Storybook. Cohérent avec les autres composants (shadow DOM + static styles). 2. .agtc-table (classe CSS) — appliquée à un <table> réel écrit à la main. Pour le site statique, qui doit rester résilient : afficher une table ne doit pas dépendre de JS.

Pourquoi pas un seul mécanisme ?

• Tout-shadow-DOM piloté par données rendrait le site JS-dépendant pour afficher ses tables —

régression de résilience (le site est aujourd'hui du HTML statique pur).

• Le *slotting* d'un <table> complet dans un shadow DOM ne permet pas de styler th/td

(::slotted n'atteint pas les descendants). La classe light DOM contourne cette limite et gère le contenu riche des cellules (ex. <code>), que l'API par données (texte échappé) ne couvre pas.

Décision 2 — Lecture seule ; tri/filtre/pagination hors périmètre, mais API extensible

La v1 n'implémente ni tri, ni filtrage, ni pagination (T10). Besoin réel du site = tables statiques. Mais l'utilisateur a confirmé un besoin futur : l'API columns/rows est choisie précisément pour les accueillir sans rupture (futur column.sortable, événement @sort, slot de barre d'outils). Aucune propriété morte n'est livrée en v1 pour éviter une API trompeuse.

Décision 3 — Tokens table dans component.json, structure default.* + paddings

Les couleurs et le rayon vivent sous table.default.* ; les paddings (horizontal, vertical compact/confortable) sont au niveau table.*. Cette séparation permet de changer la densité sans toucher aux couleurs. Conforme aux trois niveaux (ADR-001) : tous les tokens pointent vers des tokens sémantiques (background.subtle, border.default, background.hover…), aucune valeur brute.

Décision 4 — Accessibilité par défaut : scope, <caption>, alignement numérique

<th scope="col"> systématique ; <caption> recommandé (avertissement console si absent), masquable visuellement via caption-hidden ; colonnes numériques alignées à droite (align="end") pour le scan vertical. Comble les trous du HTML d'origine.

Décision 5 — Séparateurs par défaut, zébrage en option (T4)

Décision utilisateur : séparateurs de lignes par défaut (sobre, adapté aux tables de tokens denses), zébrage disponible via l'attribut striped.

Décision 6 — Densité compact par défaut (T9)

Les tables de tokens sont denses ; compact est le défaut, comfortable disponible via density.

---

Périmètre v1