# Composants de console de design Trois composants existent pour documenter un système de design. La console de design de Sovrium est construite avec eux, et votre application peut bâtir la sienne de la même façon. Ils lisent votre `design` plutôt que de le répéter, et c'est tout l'intérêt. Une page qui écrit sa propre copie d'un bouton montre à quoi ce bouton ressemblait le jour où il a été tapé. Un specimen dessine celui que votre application rend maintenant. Les jetons de design eux-mêmes sont dessinés par des types de kit ordinaires : `swatch` peint un jeton de couleur et trace un jeton d'accélération, `badge` avec `variant: contrast` note une paire pour sa lisibilité, et `card` avec `variant: scoped` marque une frontière de design sur une page qui montre deux systèmes à la fois. ## `specimen` Dessine un composant à côté du littéral de configuration qui l'a produit. Les deux sont projetés depuis la même déclaration : l'extrait ne peut donc pas cesser de correspondre à ce qui est au-dessus. | Propriété | Description | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `component` | Le littéral de composant à dessiner. | | `subject` | Le type dont le moteur dessine son propre specimen de catalogue — l'alternative à écrire le composant en entier. | | `showSnippet` | Affiche le littéral de configuration à côté du dessin, projeté depuis la même déclaration. | | `showProvenance` | Affiche, par partie, quelle couche a contribué chaque classe — la recette de Sovrium, votre bloc `design.components`, ou le plancher d'accessibilité verrouillé. | | `viewport` | La fenêtre (`width`, en pixels CSS) dans laquelle le specimen est re-rendu, dans un document à lui. | | `annotations` | Légendes nommant les parties du composant dessiné, sous la forme `[{ part, label }]`. | `subject` accepte `type`, `component`, `variant`, `size` et `state`. `annotations` emploie les mêmes noms de parties que le bloc `components` d'un `design`. ```yaml components: - type: specimen showSnippet: true showProvenance: true annotations: - { part: root, label: The button itself } component: type: button label: Save changes ``` ### Nommer un sujet plutôt que de l'écrire `component` porte un littéral, et c'est ce qui rend l'extrait honnête — mais cela veut dire aussi qu'une déclaration dessine un type. Une route de kit par type exigerait une page par type. Un specimen peut donc plutôt **nommer** son sujet, et Sovrium dessine son propre specimen de catalogue pour ce type, avec les propriétés illustratives dont chaque type a besoin pour être le specimen de quelque chose. Rendu nu, un `select` est une boîte vide ; c'est dans le catalogue que vit cette connaissance. ```yaml pages: - path: /kit/:type components: - type: specimen subject: { type: $param.type } showSnippet: true ``` `subject.type` est soit un nom de type catalogué (`button`), soit `$param.` désignant un segment du chemin de la page hôte. Un littéral est vérifié à la lecture de la configuration : une faute de frappe, ou un type qu'un specimen ne peut jamais dessiner, est nommé au démarrage. Un `$param` est un segment d'URL plutôt qu'un fait de configuration : un segment ne désignant rien de dessinable répond donc **404** — une URL mal tapée qui afficherait silencieusement une page ferait passer un lien mort pour vivant, et un cadre vide laisserait croire à un lecteur que le type n'a pas de specimen plutôt que pas d'existence. `component` et `subject` s'excluent mutuellement, et exactement l'un des deux est requis. Tous deux répondent à « qu'est-ce qui est dessiné », et il n'y a pas d'ordre de priorité défendable entre eux : un specimen déclarant les deux en montrerait un et jetterait l'autre en silence, avec l'extrait projeté depuis lui. Un specimen refuse de dessiner un composant qui rend un contrôle de soumission — `form` — à quelque profondeur que ce soit, et refuse de s'imbriquer dans un autre specimen. Le premier refus est une règle de sûreté : un cadre d'aperçu ne porte aucun chemin d'écriture. Le second est une borne : chaque niveau projette son extrait depuis le niveau inférieur, et l'imbrication n'aurait donc pas de fin. Les deux sont refusés à la lecture de la configuration, pour que l'échec nomme sa raison au lieu de ne rien dessiner en silence. ## `field-specimen` Dessine le contrôle qu'obtient un **type de champ** de table : un type de colonne, rendu comme le contrôle de formulaire que votre formulaire d'enregistrement affichera réellement pour lui. Là où `specimen` documente la moitié « composants » d'un système de design, celui-ci en documente la moitié « données ». | Propriété | Description | | ------------- | -------------------------------------------------------------------------------------------------------------------------- | | `fieldType` | Le type de champ de table dont il faut dessiner le contrôle. Requis. | | `name` | L'attribut `name` que porte le contrôle dessiné. Par défaut, le type de champ avec les tirets remplacés par des soulignés. | | `label` | Libellé visible sur le contrôle. Par défaut, le nom humanisé du contrôle. | | `placeholder` | Texte indicatif dans le contrôle. | | `description` | Texte d'aide sous le contrôle. | | `value` | Une valeur illustrative dans le contrôle. Vide par défaut. | | `options` | Valeurs d'options pour un type de champ à choix. Absent, dessine le contrôle vide. | | `compact` | Supprime la légende de surface propre au contrôle. Ne supprime jamais le marqueur de fidélité différée. | `fieldType` accepte un nom de type de champ catalogué, `$param.` désignant un segment de chemin, ou `$record.` désignant une colonne de la ligne depuis laquelle le specimen est déployé. ```yaml components: - type: field-specimen fieldType: single-select label: Status options: [Draft, Sent, Paid] ``` ### Il documente une surface, et dit laquelle Un type de champ est dessiné sur plus d'une surface, et ces surfaces diffèrent légitimement. Un specimen ne peut donc pas prétendre montrer _le_ rendu d'un type de champ. Il montre le contrôle d'une surface nommée, et porte une légende disant laquelle. `compact` supprime cette légende pour une page qui dessine tous les types à la fois, où la même phrase a sa place une fois au-dessus du groupe plutôt que des dizaines de fois à l'intérieur. Là où une surface n'a pas encore de contrôle exact, le specimen se signale comme **différé** plutôt que de dessiner une approximation et de vous laisser y croire. `compact` ne supprime jamais ce marqueur : masquer une légende est un choix de mise en page, masquer un avertissement de fidélité n'en est pas un. ### Il héberge un contrôle, et n'offre aucun moyen de le soumettre Le contrôle dessiné est un vrai contrôle : le même que celui qu'affiche votre formulaire d'enregistrement, pas un sosie construit à côté — c'est ce qui empêche la page de dériver loin du formulaire. Il est hébergé directement, sans `form` autour et sans affordance de soumission, pour que quiconque peut lire la page ne puisse pas devenir par accident l'éditeur de quoi que ce soit. Il n'y a ni propriété `surface` ni `fullWidth`. La première vous demanderait d'épeler une constante — il y a une surface aujourd'hui, et la propriété apparaîtra le jour où il y en aura une seconde. La seconde est de la mise en page, et la mise en page appartient au conteneur dans lequel vous placez le specimen, pas à un fait concernant le type de champ. ## `preview` Dessine une option d'un type, réglée sur la valeur que vous nommez — pour qu'un réglage puisse être vu plutôt que décrit. | Propriété | Description | | ----------- | --------------------------------------------------------------------------------------------------------- | | `subject` | Le type, l'option et la valeur que dessine l'aperçu : `type`, `option` et `value`. Les trois sont requis. | | `caption` | Une ligne sous le dessin disant ce que fait cette valeur. Texte ordinaire : `$record.` y résout. | | `showValue` | Imprime `option: valeur` au-dessus du dessin. Vrai par défaut. | `subject.type` est un nom de type catalogué, ou `$param.`, ou `$record.`. `subject.option` est un chemin dans la grammaire pointée que publie le point d'entrée des options de type de composant, avec `[]` pour un niveau de tableau. `subject.value` est une chaîne, un nombre ou un booléen ; une chaîne est convertie selon la nature propre de l'option, si bien qu'un gabarit de ligne portant `$record.value` dessine la même chose qu'un littéral `2`. ```yaml components: - type: preview subject: { type: table, option: pagination.position, value: both } caption: 'Pagers above and below, for a grid taller than the viewport.' - type: preview subject: { type: table, option: striped, value: true } showValue: false ``` ### Il dessine une valeur, pas une variante `specimen` dessine un composant dans un état — une variante, une taille, une apparence au repos ou au survol —, et ses champs d'axe sont réellement optionnels, parce qu'un type a une variante par défaut et une taille par défaut. Un aperçu dessine une **option** à une **valeur**, et aucune option n'a d'« option par défaut » : voilà pourquoi les trois parties de `subject` sont requises plutôt qu'optionnelles. Une valeur structurée est délibérément exclue. Une option dont la valeur est un objet n'est pas de celles qu'un lecteur apprend d'une seule image, et en admettre une rendrait la légende impossible à écrire. La chaîne vide, à l'inverse, est délibérément **admise** : la valeur intéressante d'une vraie option est parfois `''` — un `placeholder` vide, un `emptyText` vide —, et une image de cela est exactement ce dont un lecteur a besoin. ### La légende est écrite, pas générée La `description` d'un schéma dit ce qu'une option _est_. Ce dont un lecteur a besoin à côté de l'image, c'est de ce que _cette valeur_ lui fait, et c'est une phrase que seul un auteur peut écrire. Omettez `caption` là où l'effet est évident ; la console de Sovrium en écrit une par ligne, ce qui donne une idée honnête de la fréquence à laquelle il ne l'est pas. `showValue` est actif par défaut, et la console le **désactive** parce que chacune de ses lignes de configuration imprime déjà le chemin de l'option dans sa colonne de gauche. Une application qui dessine un aperçu isolé sur sa propre page le laisse actif. ## Pages connexes - [Système de design](/fr/docs/design) — le bloc `design` que ces trois composants lisent. - [Composants spécialisés](/fr/docs/specialty-components) — les autres types de la même section. - [Présentation des types de champs](/fr/docs/field-types-overview) — les types dont `field-specimen` dessine les contrôles.