Modal

Modal dans Storybook

Utilisation

Présentation

Les fenêtres modales attirent l'attention de l'utilisateur sur une tâche à partir d'une fenêtre située en haut de la page. Elles présentent des informations essentielles, qui peuvent ou non nécessiter une saisie de la part de l'utilisateur avant que le workflow ne se poursuive.

De par leur conception, les fenêtres modales interrompent le flux de travail d'un utilisateur. Elles désactivent la zone de contenu principale et empêchent les utilisateurs de revenir à leur workflow antérieur tant qu'ils n'ont pas effectué la tâche indiquée dans la fenêtre modale ou qu'ils ne l'ont pas annulée.

Les fenêtres modales sont principalement utilisées pour signaler des erreurs (objectif initial), mais elles peuvent également servir à transmettre des alertes, des confirmations et des exigences personnalisées.

Pour savoir quand utiliser le composant modal, consultez l'arbre de décision des composants de l'interface utilisateur suivant :

Quand l'utiliser

• Pour demander des entrées ou des décisions essentielles qui empêchent l’utilisateur de poursuivre un processus ou une tâche.
• Pour fournir des informations urgentes, des erreurs critiques ou des avertissements importants qui nécessitent une attention et un accusé de réception immédiats de la part de l’utilisateur.
• Pour confirmer les actions importantes de l’utilisateur, en particulier celles qui ont des conséquences importantes (par exemple, la suppression de données).

Quand ne pas l'utiliser

• Pour les messages non critiques, les mises à jour de statut ou les informations qui ne nécessitent pas d’action immédiate de la part de l’utilisateur ni d’interruption du workflow.
• Pour interrompre des tâches utilisateur fluides ou à enjeux élevés (comme un processus de paiement ou une saisie de données complexe), sauf si cela est absolument nécessaire pour éviter une erreur critique.
• Si la décision ou la tâche contenue dans la fenêtre modale nécessite que les utilisateurs accèdent à d’autres informations sur la page ou ailleurs dans l’application.

Formatage

Structure

Les fenêtres modales comprennent un en-tête, un corps et un pied de page.

1. En-tête : l'en-tête contient le titre de la fenêtre modale et communique son objectif.
2. Corps : contient le texte nécessaire aux utilisateurs pour effectuer la tâche indiquée dans la fenêtre modale. Les fenêtres modales peuvent également comporter d'autres composants dans le corps.
3. Boutons : il s'agit des principales actions dont l'utilisateur a besoin pour effectuer la tâche indiquée dans la fenêtre modale ou l'annuler.
4. Icône de fermeture : ferme la boîte de dialogue sans soumettre de données.
5. Superposition : recouvre le contenu de la page principale et le rend inactif tant que la tâche de la fenêtre modale n'est pas terminée ou annulée.

Erreurs

Les messages d'erreur doivent respecter les directives en vigueur dans ce domaine. Pour en savoir plus, reportez-vous aux éléments suivants :

• Mécanismes de validation et de messagerie
• Rédaction de messages efficaces

Contenu

Directives générales relatives à la rédaction

• Mettez une majuscule en début de phrase pour tous les aspects relatifs à la conception des interfaces de produit Guidewire. Ne mettez pas la 1re lettre du 1er mot du titre en majuscule.
• Utilisez des verbes au présent et la forme active dans la plupart des cas.
• Utilisez des contractions courantes pour donner à votre texte un ton plus naturel et informel.
• Utilisez un langage simple. Évitez tout jargon inutile et les formulations complexes.
• Utilisez des termes et des phrases concis.

En-tête

• Les en-têtes doivent poser une seule question claire ou communiquer un seul message concis. Si la fenêtre modale a été conçue à titre d'information ou à des fins pédagogiques et qu'aucune décision n'est requise, le titre peut se présenter sous la forme d'une déclaration.
• Évitez d'utiliser « Êtes-vous sûr » comme titre d'une fenêtre modale. Ce texte est vague et les utilisateurs pourraient ne pas savoir ce que vous demandez vraiment. Posez plutôt aux utilisateurs la question à laquelle vous voulez qu'ils répondent à l'aide de l'action spécifique, par exemple « Envoyer un paiement ? ».

Corps

• Le corps du texte doit préciser clairement les conséquences éventuelles et expliquer les options disponibles en termes simples.
• Assurez-vous que la fenêtre modale contient toutes les informations nécessaires pour une prise de décision unique.
• Évitez d'inclure des informations qui n'ont aucun rapport avec la décision ou des descriptions compliquées de situations rares.
• Pour les fenêtres modales qui apparaissent à titre d'information, utilisez le ton approprié en fonction de la nature du message. Par exemple, lorsque vous cherchez à empêcher l'apparition d'une erreur, le texte UX doit être clair et direct.

Boutons

• Le texte du bouton principal doit énoncer une action non équivoque qui répond à la question posée dans l'en-tête.
• Assurez-vous que la question et l'action utilisent les mêmes termes. Évitez d'utiliser un langage incohérent. Par exemple, si vous demandez « Supprimer le portefeuille ? » dans l’en-tête, le bouton d’appel à l’action principal (CTA) doit également indiquer « Supprimer ».
• Les actions principales se trouvent à droite, les actions d'annulation ou secondaires à gauche.
• Pour les fenêtres modales qui exigent une décision, utilisez des termes qui décrivent l'action littérale plutôt qu'une formulation vague comme Oui, OK ou Bien sûr.
• Gardez « OK » pour les situations telles que les fenêtres modales de confirmation, dans lesquelles vous demandez simplement à l'utilisateur de prendre acte des informations présentées.

Cette fenêtre modale pose clairement des questions sur l’action spécifique, informe l’utilisateur d’une conséquence potentielle clé et propose des boutons orientés vers l’action sans ambiguïté.

Cette fenêtre modale pose une question vague, omet de mentionner les conséquences importantes et propose des options de bouton « Oui/Non » peu claires.

Comportements

États

Lors du déclenchement d'une fenêtre modale, certains éléments, tels que les boutons, ont un état actif, focus et survol.

• Focus : fournit un commentaire indiquant que l'élément est mis en évidence à l'aide du clavier ou de la souris.
• Actif : fournit un commentaire indiquant que l'utilisateur clique ou appuie sur l'élément.
• Survol : indique que l'utilisateur a positionné le curseur de la souris sur l'élément (version pour ordinateur de bureau uniquement).

Lors de la fermeture de la fenêtre modale, l'utilisateur revient au contenu de la page en cours et à son workflow précédent.

Interactions

Souris

Lorsque l'utilisateur clique sur l'icône de fermeture en haut à droite, il ferme la fenêtre modale sans soumettre ses données.

S'il clique sur le bouton d'action principale, la tâche est effectuée et la fenêtre modale disparaît.

L'action secondaire permet à l'utilisateur de faire marche arrière et de ne prendre aucune mesure. Le fait de cliquer sur le bouton secondaire ferme la fenêtre modale et l'utilisateur revient à son contexte précédent.

Clavier

Lorsque la fenêtre modale est déclenchée, la séquence de tabulation et le focus clavier sont limités à l'espace de la fenêtre. La fenêtre principale est inerte et ne peut faire l'objet d'aucune interaction tant que la fenêtre modale n'est pas annulée.

Lecteur d'écran

Les composants de la fenêtre modale incluent un élément WAI-ARIA de type role="dialog" et aria-modal="true" pour indiquer aux technologies d'assistance que la fenêtre en dessous est actuellement inerte. L'ordre du focus, les noms accessibles et les relations programmatiques dépendent du contenu individuel de chaque fenêtre modale. L'élément avec ARIA role="dialog" comprend à la fois une référence aria-labelledby et une référence aria-describedby, qui renvoient toutes les deux respectivement au titre principal de la fenêtre modale et à son contenu.

Accessibilité

Ce composant a été validé pour répondre aux directives d’accessibilité WCAG 2.2 AA dans sa configuration de base par défaut. Il s’agit notamment de s’assurer que :

• Le rapport de contraste des éléments textuels par rapport à leur arrière-plan est supérieur à 4.5:1.
• Le contenu non textuel qui doit transmettre le sens (comme les icônes et les indicateurs de focus) a un rapport de contraste d’au moins 3:1 avec ses couleurs adjacentes.
• Cet élément peut être utilisé à l’aide d’un clavier et d’une souris.
• Le contenu est accessible à l’aide de lecteurs d’écran, tels que JAWS et VoiceOver.

La conformité de l’accessibilité dépend en définitive de la façon dont ce composant est implémenté et personnalisé. Les modifications apportées par l’auteur du contenu peuvent affecter l’accessibilité. Pour en savoir plus sur notre modèle de responsabilité partagée, consultez notre Déclaration d’accessibilité Jutro complète.

Reportez-vous aux bonnes pratiques de création conformément à la spécification WAI-ARIA pour les fenêtres modales et pensez à vérifier les points suivants dans votre application :

• Au moment du déclenchement de la fenêtre modale, le focus clavier est placé sur le premier élément accessible dans cette fenêtre.
• Lors de sa fermeture, le focus clavier est de nouveau placé sur le composant à l'origine du déclenchement de la fenêtre modale.
• Le focus ne doit pas se déplacer en dehors de la fenêtre modale tant que celle-ci reste ouverte.

Code

Warning: Modules micro front-end

Si vous utilisez le composant modal dans un micro front-end, utilisez ModalNextContext. showModal ne fonctionne pas dans les applications intégrées en raison des limitations liées à la transmission d’éléments React personnalisés.

ModalNext affiche les éléments enfants devant une superposition. Il offre les avantages suivants :

• Bloque l'interaction sous la fenêtre modale
• Désactive le défilement pendant l'ouverture
• Gère le focus en fonction des meilleures pratiques d'accessibilité (voir Accessibilité)

Implémentation de base

import React, { useState } from 'react';
import {
  Button,
  ModalBody,
  ModalFooter,
  ModalHeader,
  ModalNext,
} from '@jutro/components';

const MyModal = ({ isOpen, onResolve }) =>
  isOpen ? (
    <ModalNext isOpen>
      <ModalHeader onClose={() => onResolve()} />
      <ModalBody>
        <p>You can put anything you want here!</p>
      </ModalBody>
      <ModalFooter>
        <Button onClick={() => onResolve('Cancel')}>Cancel</Button>
        <Button onClick={() => onResolve('OK')}>OK</Button>
        <Button onClick={() => onResolve('More')}>More options</Button>
      </ModalFooter>
    </ModalNext>
  ) : null;

export const MyComponent = () => {
  const [isOpen, setIsOpen] = useState(false);

  const handleOpen = () => setIsOpen(true);

  const handleModalResult = (result) => {
    switch (result) {
      case 'Cancel':
        alert('Cancelled');
        break;
      case 'OK':
        alert("So you're okay with this?");
        break;
      case 'More':
        alert('Your other options');
        break;

      default:
        alert('The default thing happened.');
        break;
    }
    setIsOpen(false);
  };

  const handleClose = () => {
    alert('Closed with the X button');
  };

  return (
    <div>
      <MyModal
        isOpen={isOpen}
        onResolve={handleModalResult}
      />
      <Button onClick={handleOpen}>Show Modal</Button>
    </div>
  );
};

La façon la plus simple d'afficher un modal consiste à importer <ModalNext> et ses composants enfants, et l'afficher à l'aide de l'état dans le composant parent.

Pour implémenter une logique métier, configurez un gestionnaire et transmettez-le en tant que onResolve. Dans l'exemple ci-dessus, nous déclenchons différentes actions à l'aide de chaque bouton. Vous pouvez exécuter plusieurs opérations dans la fonction de rappel et fermer la fenêtre modale lorsque vous êtes prêt.

Notez que <ModalHeader> prend un rappel onClose qui s'exécute lorsque l'utilisateur clique sur le bouton X (fermer).

Propriétés

ModalNext

Propriété	Type	Description
contentLayout	{component: string, componentProps: object}, LayoutShape	Définit la disposition à appliquer avec une propriété 'component' configurée sur Flex ou Grid et la propriété componentProperties afin de définir les propriétés de ce composant de mise en page.
isOpen	bool	Indicateur facultatif précisant si la fenêtre modale est actuellement ouverte
onAfterOpen	func	Fonction de rappel qui, si elle est mise à disposition, est appelée lorsque la fenêtre modale est ouverte et qu'elle est visible pour l'utilisateur
onAfterClose	func	Fonction de rappel qui, si elle est mise à disposition, est appelée lorsque la fenêtre modale est fermée et qu'elle est masquée pour l'utilisateur
onRequestClose	func	Fonction de rappel qui, si elle est mise à disposition, est appelée lorsque la fenêtre modale reçoit une demande de fermeture (soit au moyen d'un clic sur la superposition, soit par l'utilisation de la touche Échap)
closeTimeoutMS	number	Nombre indiquant les millisecondes à attendre avant la fermeture de la fenêtre modale
contentLabel	IntlMessageShape	Chaîne indiquant la façon dont le conteneur de contenu doit être annoncé aux lecteurs d'écran
overlayClassName	string	Classe CSS facultative pour la superposition de la boîte de dialogue modale
className	string	Classe CSS facultative pour la boîte de dialogue modale
shouldFocusAfterRender	bool	Indicateur facultatif précisant si le focus sera placé automatiquement au niveau de la fenêtre modale lors de son ouverture.
shouldCloseOnOverlayClick	bool	Si la valeur est définie sur « false », la boîte de dialogue ne se ferme pas lorsque l'utilisateur clique sur la superposition.
shouldCloseOnEsc	bool	Indicateur facultatif précisant si la fenêtre modale peut être fermée à partir du clavier (au moyen de la touche Échap)
shouldReturnFocusAfterClose	bool	Indicateur facultatif précisant si la fenêtre modale doit rétablir le focus sur l'élément sur lequel il était placé avant son affichage.
parentSelector	func	Fonction appelée pour identifier l'élément parent auquel la fenêtre modale sera associée.

ModalNext est le composant de base qui doit envelopper les composants ci-dessous et détermine certains des comportements globaux de la fenêtre modale.

ModalHeader

Propriété	Type	Description
contentLayout	{component: string, componentProps: object}, LayoutShape	Définit la disposition du contenu à appliquer avec une propriété 'component' configurée sur Flex ou Grid et la propriété componentProps afin de définir les propriétés de ce composant de mise en page.
titleLayout	{component: string, componentProps: object}, LayoutShape	Définit la disposition de l'en-tête à appliquer avec une propriété 'component' configurée sur Flex ou Grid et la propriété componentProps afin de définir les propriétés de ce composant de mise en page.
status	success, info, warning, error	Statut de cette fenêtre modale. Il peut s'agir des valeurs suivantes : 'succès', 'information', 'avertissement', 'erreur'. Aucun statut par défaut
icon	string	Voir Icône
title	IntlMessageShape	Texte à afficher pour le titre
subtitle	IntlMessageShape	Texte à afficher pour le sous-titre
onClose	func	Fonction à appeler lorsque le bouton Fermer est activé. Si vous ne définissez pas cette fonction, la fenêtre modale ne comportera pas de bouton Fermer (x) dans le coin.

Le composant ModalHeader doit être utilisé pour afficher la partie supérieure de la fenêtre modale, à savoir la barre de statut en couleur, l'icône facultative à gauche du titre et le titre lui-même.

ModalBody

Propriété	Type	Description
id	string	Utilisé pour identifier le composant du corps de la fenêtre modale.
contentLayout	{component: string, componentProps: object}, LayoutShape	Définit la mise en page à appliquer avec une propriété 'component' configurée sur Flex ou Grid et la propriété componentProps afin de définir les propriétés de ce composant de mise en page.
autoFocus	bool	Permet d'attirer l'attention sur le corps de la fenêtre modale lors de l'installation. La valeur par défaut est true.

Le composant ModalBody est un composant simple qui sert à envelopper le contenu de la fenêtre modale et qui doit être placé après l'élément ModalHeader

ModalFooter

Propriété	Type	Description
contentLayout	{component: string, componentProps: object}, LayoutShape	Définit la mise en page à appliquer avec une propriété 'component' configurée sur Flex ou Grid (sinon, un élément div est appliqué par défaut) et la propriété componentProperties afin de définir les propriétés de ce composant de mise en page

Le composant ModalFooter est un composant simple qui sert à envelopper le contenu du pied de page de la fenêtre modale et qui doit être placé en tant que dernier composant enveloppé par ModalNext. Vous pourrez généralement envelopper des boutons dans ce composant, mais vous ne devez pas vous sentir limité si d'autres composants sont nécessaires à l'implémentation.

Exemple asynchrone

const MyModal = ({ isOpen, onResolve }) =>
  isOpen ? (
    <ModalNext isOpen>
      <ModalHeader onClose={() => onResolve()} />
      <ModalBody>
        <p>You can put anything you want here!</p>
      </ModalBody>
      <ModalFooter>
        <Button onClick={() => onResolve('Cancel')}>Cancel</Button>
        <Button onClick={() => onResolve('Process request')}>
          Process request
        </Button>
      </ModalFooter>
    </ModalNext>
  ) : null;

export const MyComponent = () => {
  const [isOpen, setIsOpen] = useState(false);
  const [processing, setProcessing] = useState(false);

  const handleOpen = () => setIsOpen(true);

  const processRequest = async () => {
    return new Promise((resolve) => {
      setTimeout(() => {
        alert('Request successful');
        resolve();
      }, [3000]);
    });
  };

  const handleModalResult = async (result) => {
    if (result === 'Process request') {
      if (!processing) {
        setProcessing(true);
        await processRequest();
        setProcessing(false);
        setIsOpen(false);
      }
    } else {
      setIsOpen(false);
    }
  };

  return (
    <div>
      <MyModal
        isOpen={isOpen}
        onResolve={handleModalResult}
      />
      <Button onClick={handleOpen}>Show Modal</Button>
    </div>
  );
};

ModalNextContext

ModalNextContext (fournisseur de fenêtres modales) est le seul moyen de créer une fenêtre modale dans un micro front-end.

import React, { useContext } from 'react';
import { ModalNextContext } from '@jutro/components';

// . . . create the callback function
const { showAlert } = useContext(ModalNextContext);

const showSomething = (msg) => {
  showAlert({
    status: 'success',
    title: messages.genericSuccessMessage,
    message: msg,
  });
};

// . . . and eventually
<button onClick={() => showSomething('Surprise!')}>
  Click here to get a surprise
</button>;

Modaux génériques

Alerte

La fenêtre modale d'alerte est un élément générique qui affiche une fenêtre modale avec une couleur de statut, une icône facultative, un titre, un message et un bouton de confirmation. Les résultats de la fenêtre modale d'alerte peuvent également être enregistrés (confirmation ou fermeture (en guise de rejet)).

import React, { useState, useContext } from 'react';
import { ModalNextContext } from '@jutro/components';

const AlertModalExample = () => {
  const [result, setResult] = useState(null);
  const { showAlert } = useContext(ModalNextContext);

  async function triggerAlert() {
    const results = await showAlert({
      status: 'info' /* status - 'info', 'warning', 'error', or 'success' */,
      icon: 'gw-error-outline' /* icon - optional icon class name for the icon to display to the left of the title */,
      title:
        'Test Alert' /* title - string/IntlMessageShape for the title of the alert */,
      message:
        'Just testing an Alert!' /* message - string/IntlMessageShape for the message to display within the alert */,
      confirmButtonText:
        'OK' /* confirmButtonText - string/IntlMessageShape for the text to appear on the confirm button */,
    });
    setResult(`modal result was: ${results}`);
  }

  return (
    <div>
      <button onClick={triggerAlert}>Show Alert Modal</button>
      <div>{result}</div>
    </div>
  );
};

Confirmation

La fenêtre modale de confirmation est un élément générique qui affiche une fenêtre modale avec une couleur de statut, une icône facultative, un titre, un message, ainsi que des boutons de confirmation et d'annulation. Les résultats de la fenêtre modale de confirmation peuvent également être enregistrés (confirmation, annulation ou fermeture (en guise de rejet)).

import React, { useState, useContext } from 'react';
import { ModalNextContext } from '@jutro/components';

const ConfirmationModalExample = () => {
  const [result, setResult] = useState(null);
  const { showConfirm } = useContext(ModalNextContext);

  async function triggerConfirmation() {
    const results = await showConfirm({
      status: 'info' /* status - 'info', 'warning', 'error', or 'success' */,
      icon: 'gw-error-outline' /* icon - optional icon class name for the icon to display to the left of the title */,
      title:
        'Test Confirm Modal' /* title - string/IntlMessageShape for the title of the confirm modal */,
      message:
        'Just testing a Confirmation Modal!' /* message - string/IntlMessageShape for the message to display within the confirm modal */,
      confirmButtonText:
        'OK' /* confirmButtonText - string/IntlMessageShape for the text to appear on the confirm button */,
      cancelButtonText:
        'Cancel' /* cancelButtonText - string/IntlMessageShape for the text to appear on the cancel button */,
    });
    setResult(`modal result was: ${results}`);
  }

  return (
    <div>
      <button onClick={triggerConfirmation}>Show Confirmation Modal</button>
      <div>{result}</div>
    </div>
  );
};

Modaux personnalisés

Les modaux personnalisés peuvent être implémentés avec les composants ModalNext, ModalHeader, ModalBody et ModalFooter, et affichées au moyen de showModal à partir de ModalNextContext, comme pour les modaux génériques décrits ci-dessus.

Journal des modifications

10.10.1

Des jetons de conception supplémentaires ont été ajoutés pour ce composant.

10.9.0

• Une nouvelle fonctionnalité d'opt-in a été introduite pour désactiver la publication automatique des événements pour le composant Modal. Vous pouvez activer cette fonctionnalité en ajoutant JUTRO_DISABLE_AUTO_EVENTS_PUBLISHING=true au fichier .env dans la racine de votre application Jutro. Lorsque cette option est activée, les composants hérités ne publient plus d'événements par défaut. Pour en savoir plus sur les événements et sur la façon d'en créer de nouveaux, reportez-vous à la documentation relative aux événements.

Type de propriété icon étendu

Le type de la propriété icon dans les composants suivants a été étendu :

Composant	Propriété	Ancien type	Nouveau type
AlertModal	icon	string	string/React.ComponentType
ConfirmationModal	icon	string	string/React.ComponentType
ModalHeader	icon	string	string/React.ComponentType

Obsolescences

La transmission de string en tant que valeur à la propriété icon est désormais obsolète dans les composants suivants :

Composant	Propriété
AlertModal	icon
ConfirmationModal	icon
ModalHeader	icon