Modal

Modal en Storybook

Uso

Descripción general

Los modales centran la atención del usuario en una tarea con una ventana que se encuentra en la parte superior de la página. Presentan información crítica, que puede o no requerir la entrada del usuario, antes de continuar con el flujo de trabajo.

Por diseño, los modales interrumpen el flujo de trabajo del usuario. Los modales deshabilitan el área de contenido principal y evitan que los usuarios regresen a su flujo de trabajo anterior hasta que completen la tarea del modal o la desestimen.

Los modales se usan principalmente para anotar errores (propósito original), pero se pueden usar para alertas, confirmaciones y requisitos personalizados.

Para obtener una guía detallada sobre cuándo utilizar este componente modal, examine el siguiente árbol de decisiones del componente de la interfaz de usuario.

Cuándo se debe utilizar

• Para solicitar información o decisiones esenciales que impidan que el usuario continúe con un proceso o tarea.
• Para proporcionar información urgente, errores críticos o advertencias importantes que requieran atención y aceptación inmediatas por parte del usuario.
• Para confirmar acciones significativas del usuario, especialmente aquellas con consecuencias importantes (por ejemplo, eliminar datos).

Cuándo no se debe utilizar

• Para mensajes que no sean críticos, actualizaciones de estado o información que no requiera la acción inmediata del usuario o la interrupción del flujo de trabajo.
• Para interrumpir tareas de usuario fluidas o de alto riesgo (como un proceso de pago o una entrada de datos compleja) a menos que sea absolutamente necesario para evitar un error crítico.
• Si la decisión o tarea dentro del modal requiere que los usuarios accedan a otra información en la página o en cualquier otro lugar de la aplicación.

Formato

Anatomía

Los modales tienen un encabezado, un cuerpo y un pie de página.

1. Encabezado: El encabezado contiene el título de la ventana modal y comunica su propósito.
2. Cuerpo: Contiene el texto complementario que se necesita para que los usuarios completen la tarea del modal. Los modales también pueden incluir otros componentes dentro del cuerpo.
3. Botones: Las principales acciones que el usuario necesita para completar o cancelar la tarea del modal.
4. Ícono de cierre: Cierra el cuadro de diálogo sin enviar ningún dato.
5. Superposición: Cubre el contenido de la página principal y lo deja inactivo hasta que la tarea del modal se completa o se desestima.

Errores

Los mensajes de error deben seguir las directrices de mensajes de error. Para obtener más información, consulte lo siguiente:

• Mecanismos de validación y mensajería
• Redacción de mensajes efectivos

Contenido

Pautas generales de redacción

• En todos los aspectos del diseño de las interfaces de productos de Guidewire, utilice mayúsculas como se usan en las oraciones. No use mayúsculas en todas las palabras.
• Use verbos en tiempo presente y voz activa en la mayoría de las situaciones.
• Use contracciones comunes para darle al texto un tono más natural e informal (pauta correspondiente al inglés).
• Use un lenguaje sencillo. Evite la jerga innecesaria y el lenguaje complejo.
• Las palabras y las oraciones deben ser breves.

Encabezado

• Los encabezados deben contener una pregunta única y clara o comunicar un mensaje único y conciso. Si el modal es informativo o educativo y no requiere decisión, el título puede ser una afirmación.
• Evite usar “¿Está seguro?” como título del modal. Es vago y es posible que los usuarios no sepan lo que realmente se está preguntando. En lugar de eso, pregunte directamente a los usuarios lo que desea que respondan mediante la acción específica, por ejemplo, “¿Enviar pago?”.

Cuerpo

• El texto del cuerpo debe aclarar las consecuencias y explicar las opciones en términos simples.
• Asegúrese de que el modal tenga toda la información que se necesite para una sola decisión.
• Evite incluir información que no esté relacionada con la decisión o descripciones complicadas de situaciones raras.
• Para los modales informativos, use el tono correcto que coincida con la naturaleza del mensaje. Por ejemplo, cuando se trata de evitar un error, el texto de UX debe ser claro y directo.

Botones

• El texto del botón principal debe indicar una acción inequívoca que responda a la pregunta planteada en el encabezado.
• Asegúrese de que la pregunta y las acciones usen las mismas palabras. Evite el uso de lenguaje inconexo. Por ejemplo, si pregunta “¿Eliminar cartera?” en el encabezado, el botón de llamada a la acción (CTA) principal también debe decir “Eliminar”.
• Las acciones primarias van a la derecha, las acciones despectivas o secundarias a la izquierda.
• Para los modales que requieren una decisión, use palabras que describan la acción literal, en lugar de algo vago como Sí, OK o Claro.
• Reserve “OK” para situaciones como modales de reconocimiento, donde simplemente le pide al usuario que reconozca la información presentada.

Este modal contiene una pregunta clara sobre la acción específica, informa al usuario sobre una posible consecuencia clave y ofrece botones inequívocos orientados a la acción.

Este modal utiliza una pregunta vaga, no menciona consecuencias importantes y ofrece opciones de botón poco claras “Sí/No”.

Comportamientos

Estados

Cuando se activa un modal, ciertos elementos, como los botones, tienen un estado activo, de foco y con cursor encima.

• En foco: Proporciona retroalimentación que indica que el elemento está resaltado mediante el uso de un teclado o un mouse.
• Activo: Proporciona retroalimentación que indica que el usuario está haciendo clic o tocando el elemento.
• Con cursor encima: Proporciona retroalimentación que indica que el usuario ha colocado un cursor sobre el elemento (solo para computadoras de escritorio).

Cuando se cierra el modal, el usuario vuelve al contenido de la página y a su flujo de trabajo anterior.

Interacciones

Ratón

Al hacer clic en el ícono de cerrar en la esquina superior derecha, se cerrará el modal sin enviar los datos del usuario.

Al hacer clic en el botón de acción principal, se completa la tarea y se cierra el modal.

La acción secundaria ofrece una manera para que el usuario retroceda y no realice ninguna acción. Al hacer clic en el botón secundario, se cierra el modal y el usuario vuelve a su contexto anterior.

Teclado

Cuando se activa, la secuencia de tabulaciones se contiene y el foco del teclado queda atrapado dentro del modal. La ventana principal es inerte y no se puede interactuar con ella hasta que se desestime el modal.

Lector de pantalla

Los componentes modales incluyen un WAI-ARIA role="dialog" y aria-modal="true" para indicar a las tecnologías de asistencia que la ventana debajo está actualmente inerte. El orden del foco, los nombres accesibles y las relaciones programáticas dependen del contenido individual dentro de cada modal. El elemento con ARIA role="dialog" incluye tanto una referencia aria-labelledby como aria-describedby, que se refieren al título del modal y al contenido del modal principales, respectivamente.

Accesibilidad

Este componente de Jutro ha sido validado para cumplir con las pautas de accesibilidad de WCAG 2.2 AA en su configuración base predeterminada. Esto incluye garantizar que se cumpla lo siguiente:

• La relación de contraste de los elementos textuales con respecto a su fondo es superior a 4,5:1.
• El contenido no textual que debe transmitir significado (como íconos e indicadores de foco) tiene una relación de contraste de al menos 3:1 con sus colores adyacentes.
• El elemento se puede operar con teclado, así como con mouse.
• Se puede acceder al contenido mediante lectores de pantalla, como JAWS y VoiceOver.

El cumplimiento de los criterios de accesibilidad depende, en última instancia, de cómo se implementa y personaliza este componente. Los cambios realizados por el autor del contenido pueden afectar la accesibilidad. Para obtener más información sobre nuestro modelo de responsabilidad compartida, revise nuestra declaración completa sobre accesibilidad de Jutro.

Consulte las Prácticas de creación de WAI-ARIA para modales y, dentro de su aplicación, asegúrese de verificar lo siguiente:

• Al activarse, el foco del teclado se coloca en el primer elemento que pueda tener foco dentro del diálogo modal.
• Al descartar, el foco del teclado vuelve al mismo componente que activó el diálogo modal.
• El foco no debe moverse fuera del modal hasta que esté cerrado.

Código

Warning: Microfrontends

Si utiliza el componente modal en un microfrontend, utilice ModalNextContext. showModal no funciona en aplicaciones incrustadas debido a las limitaciones en torno al paso de elementos personalizados de React.

ModalNext renderiza los elementos secundarios a una superposición. Ofrece lo siguiente:

• Bloquea la interacción por debajo del modal.
• Deshabilita el desplazamiento mientras está abierto.
• Administra el foco de acuerdo con las prácticas recomendadas de accesibilidad (consulte accesibilidad).

Implementación básica

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 manera más sencilla de mostrar un modal es importar <ModalNext> y sus componentes secundarios y mostrarlo mediante el estado en el componente principal.

Para implementar la lógica de negocio, configure un controlador y páselo como onResolve. En el ejemplo anterior, activamos diferentes acciones con cada botón. Puede ejecutar varias operaciones en la función de devolución de llamada y cerrar el modal cuando haya terminado.

Observe que <ModalHeader> toma una devolución de llamada onClose que se ejecuta cuando el usuario hace clic en el botón X (cerrar).

Propiedades

ModalNext

Propiedad	Tipo	Descripción
contentLayout	{component: string, componentProps: object}, LayoutShape	Define la composición y disposición que se utilizará con una propiedad de 'componente' establecida en Flex o Grid y componentProperties para establecer propiedades para ese componente composición y disposición
isOpen	bool	Indicador opcional que indica si el Modal está actualmente abierto
onAfterOpen	func	Función de devolución de llamada que, si se proporciona, se llama cuando se ha abierto el cuadro de diálogo Modal y está visible para el usuario
onAfterClose	func	Función de devolución de llamada que, si se proporciona, se llama cuando el cuadro de diálogo Modal se ha cerrado y está oculto para el usuario
onRequestClose	func	Función de devolución de llamada que, si se proporciona, se llama cuando se solicita que se cierre el cuadro de diálogo Modal (ya sea haciendo clic en la superposición o presionando ESC)
closeTimeoutMS	number	Número que indica los milisegundos a esperar antes de cerrar el modal.
contentLabel	IntlMessageShape	Cadena que indica cómo se debe anunciar el contenedor de contenido a los lectores de pantalla
overlayClassName	string	La clase CSS opcional para la superposición del cuadro de diálogo Modal
className	string	La clase CSS opcional para el diálogo Modal
shouldFocusAfterRender	bool	Indicador opcional que indica si el Modal se enfocará automáticamente en sí mismo al abrir
shouldCloseOnOverlayClick	bool	Cuando es falso, no se cerrará el cuadro de diálogo cuando se haga clic en la superposición.
shouldCloseOnEsc	bool	Indicador opcional que muestra si está disponible la compatibilidad con el teclado para cerrar el modal (a través de la tecla ESC).
shouldReturnFocusAfterClose	bool	Indicador opcional que muestra si el modal debe restaurar el foco al elemento que tenía el foco antes de su visualización.
parentSelector	func	Función a la que se llamará para obtener el elemento principal al que se adjuntará el Modal.

El componente ModalNext es el componente base que debe envolver los siguientes componentes y determina algunos de los comportamientos generales del modal.

ModalHeader

Propiedad	Tipo	Descripción
contentLayout	{component: string, componentProps: object}, LayoutShape	Define la composición y disposición del contenido que se usará con una propiedad de 'componente' establecida en Flex o Grid y componentProps para establecer propiedades para ese componente composición y disposición
titleLayout	{component: string, componentProps: object}, LayoutShape	Define la composición y disposición del encabezado que se usará con una propiedad de 'componente' establecida en Flex o Grid y componentProps para establecer propiedades para ese componente composición y disposición
status	success, info, warning, error	El estado de este modal. Puede ser 'acción correcta', 'información', 'advertencia', 'error'. El valor predeterminado es sin estado.
icon	string	Consulte Ícono.
title	IntlMessageShape	Texto que se mostrará para el título
subtitle	IntlMessageShape	Texto que se mostrará para el subtítulo
onClose	func	La función a la que se llamará cuando se haga clic en el botón Cerrar. Si no configura esta función, el modal no tendrá un botón de cierre (x) en la esquina.

El componente ModalHeader debe usarse para mostrar la parte superior del modal: la barra de color de estado, el ícono opcional a la izquierda del título y el título mismo.

ModalBody

Propiedad	Tipo	Descripción
id	string	Se utiliza para identificar el componente del cuerpo modal.
contentLayout	{component: string, componentProps: object}, LayoutShape	Define la composición y disposición que se utilizará con una propiedad de 'componente' establecida en Flex o Grid y la propiedad componentProps para establecer propiedades para ese componente composición y disposición.
autoFocus	bool	Hace que el foco se atraiga al cuerpo del modal en el montaje. El valor predeterminado es true.

El componente ModalBody es un componente simple que sirve para envolver el contenido del modal y debe colocarse después del ModalHeader

ModalFooter

Propiedad	Tipo	Descripción
contentLayout	{component: string, componentProps: object}, LayoutShape	Define la composición y disposición que se utilizará con una propiedad de 'componente' establecida en Flex o Grid (de lo contrario, se establecerá de forma predeterminada en un div) y componentProperties para establecer propiedades para ese componente composición y disposición

El componente ModalFooter es un componente simple que sirve para encapsular el contenido del modal y debe colocarse como el último componente encapsulado por ModalNext. Por lo general, encapsulará los botones dentro de este componente, pero esto no restringe sus posibilidades si otros componentes son necesarios para la implementación.

Ejemplo asíncrono

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 (proveedor de modal) es la única forma de crear un modal en un microfrontend.

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>;

Modales genéricos

Alerta

El modal de alerta es un modal genérico que mostrará un modal con un color de estado, un ícono opcional, un título, un mensaje y un botón de confirmación. Los resultados del modal de alerta también se pueden capturar (confirmar o cerrar (como un rechazo)).

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>
  );
};

Confirmación

El modal de confirmación es un modal genérico que mostrará un modal con un color de estado, un ícono opcional, un título, un mensaje y un botón para confirmar y cancelar. Los resultados del modal de confirmación también se pueden capturar (confirmar, cancelar o cerrar (como un rechazo)).

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>
  );
};

Modales personalizados

Los modales personalizados se pueden implementar con los componentes ModalNext, ModalHeader, ModalBody y ModalFooter y se muestran usando showModal desde ModalNextContext, similar al uso anterior para los modales genéricos.

Registro de cambios

10.10.1

Se agregaron tokens de diseño adicionales para este componente.

10.9.0

• Se introdujo una nueva característica de opción de participación que desactiva la publicación automática de eventos para el componente Modal. Puede habilitar esta función agregando JUTRO_DISABLE_AUTO_EVENTS_PUBLISHING=true al archivo .env en la raíz de su aplicación de Jutro. Cuando esta acción está habilitada, los componentes heredados ya no publican eventos de forma predeterminada. Para obtener más información sobre los eventos y cómo configurar nuevos, consulte la documentación sobre eventos.

Tipo de propiedad icon extendida

El tipo de la propiedad icon en los siguientes componentes se ha ampliado:

Componente	Propiedad	Tipo antiguo	Tipo nuevo
AlertModal	icon	string	string/React.ComponentType
ConfirmationModal	icon	string	string/React.ComponentType
ModalHeader	icon	string	string/React.ComponentType

Elementos obsoletos

El paso de un string como valor a la propiedad icon ha quedado obsoleto en los siguientes componentes:

Componente	Propiedad
AlertModal	icon
ConfirmationModal	icon
ModalHeader	icon