Champ de texte

Il y a deux couches ici. input() et textarea() sont les contrôles nus ; textField() et textareaField() en enveloppent un dans un libellé, un texte d’aide et un message d’erreur, et les relient avec for et aria-describedby. Prenez les seconds, sauf si vous construisez la mise en page vous-même.

Champ de base

Nom

textField({ label: 'Nom', name: 'name', placeholder: 'Ada Lovelace' })

Texte d’aide

Le texte d’aide est relié par aria-describedby : un lecteur d’écran le lit comme faisant partie du champ, et non comme du texte détaché après lui.

E-mail

Nous ne l’utilisons que pour signaler les builds en échec.

textField({
  label: 'E-mail',
  name: 'email',
  type: 'email',
  help: 'Nous ne l’utilisons que pour signaler les builds en échec.',
})

Obligatoire et erreur

Un error marque le champ invalide, colore la bordure, pose aria-invalid et fait pointer aria-describedby vers le message — une prop, les quatre effets.

Projet

Site

Ce n’est pas une URL.

stack({ gap: 'lg' },
  textField({ label: 'Projet', name: 'project', required: true, value: '' }),
  textField({
    label: 'Site',
    name: 'site',
    error: 'Ce n’est pas une URL.',
    value: 'sitelo point dev',
  }),
)

Tailles

Petit

Moyen

Grand

stack({ gap: 'md' },
  textField({ label: 'Petit', name: 'small', size: 'sm', placeholder: 'sm' }),
  textField({ label: 'Moyen', name: 'medium', size: 'md', placeholder: 'md' }),
  textField({ label: 'Grand', name: 'large', size: 'lg', placeholder: 'lg' }),
)

Ornements

Un préfixe ou un suffixe accolé au contrôle lui-même, pour les unités et les fragments fixes d’une valeur.

Site

https://

Délai de build

secondes

stack({ gap: 'md' },
  textField({ label: 'Site', name: 'url', startAdornment: 'https://', placeholder: 'example.com' }),
  textField({ label: 'Délai de build', name: 'timeout', endAdornment: 'secondes', value: '30' }),
)

Désactivé et en lecture seule

Désactivé

Lecture seule

stack({ gap: 'md' },
  textField({ label: 'Désactivé', name: 'disabled', value: 'Non modifiable', disabled: true }),
  textField({ label: 'Lecture seule', name: 'readonly', value: 'dist/', readonly: true }),
)

Multiligne

textareaField() est le même champ autour d’un <textarea>. Sa valeur est le contenu de l’élément plutôt qu’un attribut, ce dont le composant se charge pour vous.

Description

Affichée dans les résultats de recherche et les cartes sociales.

textareaField({
  label: 'Description',
  name: 'description',
  rows: 4,
  help: 'Affichée dans les résultats de recherche et les cartes sociales.',
  value: 'Génération de sites statiques sans configuration, propulsée par Vite.',
})

Dans un formulaire

Nom

E-mail

Message

card(
  cardBody(
    stack({ gap: 'md' },
      textField({ label: 'Nom', name: 'contact-name', required: true }),
      textField({ label: 'E-mail', name: 'contact-email', type: 'email', required: true }),
      textareaField({ label: 'Message', name: 'message', rows: 3 }),
    ),
  ),
  cardFooter({ divided: true, style: 'justify-content: flex-end' },
    button({ variant: 'ghost', color: 'neutral' }, 'Annuler'),
    button({ type: 'submit' }, 'Envoyer'),
  ),
)

Le construire soi-même

field() est l’enveloppe seule — elle accepte n’importe quel contrôle en enfant, ce qui permet de poser deux saisies sur une rangée, ou un contrôle que cette bibliothèque n’a pas, sous le même traitement de libellé et d’erreur.

Un libellé ne peut pas nommer deux contrôles : chaque saisie a donc besoin ici de son propre nom accessible. C’est le rôle des aria-label : le libellé visible nomme la paire, et chaque saisie dit de quelle extrémité elle est.

Plage de dates

Les deux extrémités sont incluses.

field({ label: 'Plage de dates', help: 'Les deux extrémités sont incluses.' },
  stack({ direction: 'row', gap: 'sm' },
    input({ type: 'date', name: 'from', 'aria-label': 'Du' }),
    input({ type: 'date', name: 'to', 'aria-label': 'Au' }),
  ),
)

Props

textField et textareaField

Prop	Type	Défaut	Description
`label`	`Child`	—	Le libellé du champ. Sert aussi à dériver l’id du contrôle en l’absence de name.
`name`	`string`	—	Nom du champ ; l’id en découle.
`help`	`Child`	—	Indication sous le contrôle, reliée par aria-describedby.
`error`	`Child \| false`	—	Message d’erreur. Pose aussi aria-invalid sur le contrôle.
`required`	`boolean`	`false`	Marque le libellé et le contrôle.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Hauteur du contrôle et taille du texte.
`type`	`string`	`'text'`	N’importe quel type d’input. textField uniquement.
`startAdornment`	`Child`	—	Préfixe accolé au contrôle. textField uniquement.
`endAdornment`	`Child`	—	Suffixe accolé au contrôle. textField uniquement.
`value`	`string \| number`	—	Valeur initiale.
`fieldClass`	`string`	—	Classe pour l’enveloppe plutôt que pour le contrôle.

Les ids découlent de name — ou de label en l’absence de name — plutôt que d’un compteur : la même page produit donc le même HTML à chaque build. Passez id pour le remplacer.

field

Prop	Type	Défaut	Description
`label`	`Child`	—	Le texte du libellé.
`help`	`Child`	—	Indication sous le contrôle.
`error`	`Child \| false`	—	Message d’erreur ; ajoute aussi l’état invalide à l’enveloppe.
`required`	`boolean`	`false`	Ajoute le marqueur d’obligation au libellé.
`for`	`string`	—	Id du contrôle désigné.