CodeBlock
À quoi il sert
CodeBlock affiche du code coloré au build, défilable au clavier, avec un bouton de copie.
Quand l’utiliser
- Montrer une commande, une configuration ou un extrait de code à lire ou à copier.
- Afficher un nom de fichier au-dessus de l’extrait, avec filename.
Quand ne pas l’utiliser
- Pour un mot de code dans une phrase : utiliser l’élément code seul.
- Pour une comparaison avant-après : utiliser Diff.
- Pour une langue hors liste : le texte s’affiche sans couleur, il faut le savoir.
Exemples
import { defineConfig } from 'astro/config';
export default defineConfig({ site: 'https://design.paulperigault.dev' });npm run verifytexte brut, sans langue<CodeBlock
code={source}
lang="ts"
filename="astro.config.ts"
label="Configuration Astro"
copyLabel="Copier le code"
copiedLabel="Code copié"
/>Accessibilité
Clavier
- Le bloc de code reçoit le focus (tabindex="0") : les flèches le font défiler (WCAG 2.1.1).
- Le bouton de copie s’active avec Entrée ou Espace, comme tout bouton natif.
Lecteur d’écran
- Avec label ou filename, le bloc est une région nommée (role="region", aria-label).
- Le message de copie est écrit dans un role="status" vide au départ, annoncé sans déplacer le focus (WCAG 4.1.3).
Garanti par le composant
- Les couleurs de jetons ont un contraste d’au moins 4,5:1 sur le fond, dans les deux thèmes (WCAG 1.4.3, test automatisé).
- La coloration ne porte aucun sens à elle seule : le code reste lisible en noir et blanc (WCAG 1.4.1).
- Le bouton de copie fait au moins --pp-size-target-min et affiche son libellé (WCAG 2.5.8, 2.5.3).
- Sans JavaScript, le code et la coloration restent ; le bouton reste masqué, car il ne peut pas fonctionner.
- En forced-colors: active, les jetons prennent la couleur CanvasText.
À la charge de l’intégrateur
- Fournir copyLabel et copiedLabel dans la langue du site.
- Nommer chaque bloc avec label ou filename s’il y en a plusieurs sur la page.
- Autoriser le script du composant dans la CSP (script-src 'self') : il est servi en fichier externe.
- Non vérifié : la restitution par lecteur d’écran des régions nommées et de l’annonce de copie.
Propriétés
| Propriété | Type | Défaut | Description |
|---|---|---|---|
| code (obligatoire) | string | — | Code à afficher, tel quel (le saut de ligne final est retiré). |
| lang | string | — | Langue : ts, js, json, shellscript, astro, css, html ou yaml. Autre valeur : texte sans couleur. |
| label | string | — | Nom accessible du bloc. À défaut, `filename` sert de nom ; sans les deux, le bloc n'est pas nommé. |
| copyLabel (obligatoire) | string | — | Libellé visible du bouton de copie (par exemple « Copier »). |
| copiedLabel (obligatoire) | string | — | Message annoncé après la copie (par exemple « Copié »). |
| filename | string | — | Nom de fichier affiché au-dessus du code. |
Jetons utilisés
--pp-color-accent--pp-color-control--pp-color-fg--pp-color-focus--pp-color-line--pp-color-muted--pp-color-status-degraded--pp-color-status-passed--pp-color-surface--pp-font-family-mono--pp-font-line-height-body--pp-font-size--1--pp-radius-control--pp-radius-surface--pp-size-focus-offset--pp-size-focus-width--pp-size-rule--pp-size-target-min--pp-space-2xs--pp-space-s--pp-space-xs
Preuves et décisions
- WCAG 1.4.3 Contraste minimum
- WCAG 2.1.1 Clavier
- WCAG 4.1.3 Messages d’état
- APG : motif Button
- Tests : packages/astro/test/CodeBlock.test.ts