Descripción emergente

Descripción emergente en Storybook

Uso

Descripción general

Las descripciones emergentes proporcionan una forma discreta de responder preguntas sobre la interfaz de usuario o agregar un poco de información o instrucciones a una interfaz. Ofrecen ayuda en el lugar necesario y ayuda contextual, y pueden informar el valor de las características. La descripción emergente aparece cuando los usuarios hacen clic, pasan el cursor por encima o llevan el foco a un elemento.

Cuándo se debe utilizar

• Para aclarar el propósito de las acciones o íconos usando un texto breve e informativo.
• Para mostrar el texto completo de los mensajes o strings que se hayan truncado.
• Para proporcionar ayuda contextual y evitar abandono del sitio en lugares complejos.

Do

Proporcione descripciones emergentes para íconos sin rótulo.

Cuándo no se debe utilizar

• Las descripciones emergentes no son apropiadas para transmitir información o instrucciones que sean fundamentales para completar una tarea.
• Deben utilizarse estratégicamente. Resista la tentación de saturar la interfaz de usuario con descripciones emergentes que no respondan a una necesidad evidente del usuario.

Do

Utilice descripciones emergentes para proporcionar información adicional, como por qué aparece un campo.

Don't

No incluya información esencial en descripciones emergentes.

Formato

Anatomía

1. Información básica sobre herramientas

2. Información sobre herramientas del ícono

Información sobre herramientas de definición

Las descripciones emergentes tienen un fondo oscuro con texto blanco superpuesto que muestra claramente la información. Un signo de intercalación debe indicar de dónde proviene la descripción emergente.

Las descripciones emergentes constan de tres variantes que satisfacen diferentes necesidades de diseño:

1. Descripción emergente básica: Se utiliza para obtener información general. El texto es descriptivo y está relacionado con el campo. También puede incluir elementos interactivos, como botones o enlaces.
2. Descripción emergente de ícono: Ayuda a aclarar el nombre del botón de ícono interactivo y describe su función.
3. Descripción emergente de definición: Define una parte predefinida de texto.

Alineación y ubicación

• Coloque las descripciones emergentes de modo que no bloqueen el contenido relacionado.
• Cuando haya varios elementos cerca, use un signo de intercalación para indicar de dónde proviene la descripción emergente.

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 siempre que fuera posible.
• 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.

Redacción de descripciones emergentes

• ** Sea conciso.** Las descripciones emergentes deben ser lo más cortas y sencillas posible.
  • Limite el texto de la descripción emergente a un máximo de 2 líneas y tenga cuidado de que, al traducir, el texto no exceda las 2 líneas.
  • Las descripciones emergentes que describen la función de un botón de acción o pestaña de solo ícono solo deben contener 1 o 2 palabras.
• El cuerpo del texto debe incluir información que sea significativa para los usuarios para la tarea en cuestión.
• Incluya un punto al final de las oraciones completas. Si la descripción emergente es una frase corta, no use punto.
• No trunque el texto en una descripción emergente.

Do

El contenido extenso hace que este elemento pierda sentido, así que sea breve.

Don't

No utilice grandes bloques de texto en la descripción emergente.

Comportamientos

Información sobre herramientas con un enlace

• Las descripciones emergentes se muestran al pasar el cursor sobre ellas y cuando tienen el foco. Seguirán apareciendo mientras el usuario pase el cursor sobre el elemento.
• Aunque la descripción emergente puede incluir enlaces y botones, es mejor no ocultar el contenido interactivo en esta.

Accesibilidad

El componente descripción emergente de Jutro muestra información complementaria adicional al hacer clic, pasar el cursor encima o recibir el foco. Si bien hay tres opciones para activar una descripción emergente, desde el punto de vista de la accesibilidad, recomendamos usar el clic o el foco. Esto se debe al hecho de que solo permitir que se muestre una descripción emergente al pasar el cursor significa que la información que contiene no estará disponible para los usuarios que solo usan teclado y lectores de pantalla.

• Interacción con el lector de pantalla: El componente descripción emergente tiene el rol WAI-ARIA de 'tooltip' y hereda el atributo aria-live automáticamente. Por tanto, los lectores de pantalla narrarán el contenido dentro de la descripción emergente.
• Interacción con el teclado: La descripción emergente se hace visible cuando está configurada para que se muestre en foco. También se hace visible cuando está configurada para que se muestre al hacer clic, ya que el evento de teclado está vinculado mediante programación al evento de clic.

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.

Asegúrese de revisar y seguir las pautas aquí y también en las Prácticas de creación de descripciones emergentes de WAI-ARIA.

• Cuando se desestime o cierre la descripción emergente, asegúrese de mantener el foco en el elemento que la invocó.
• Compruebe los umbrales de contraste de color entre el texto y su fondo si se aplican colores personalizados al elemento.

Note: Algunas configuraciones del componente descripción emergente no cumplen con la accesibilidad.

• El activador 'Mouseenter' solo está disponible para usuarios de mouse. Si se llega al componente mediante el tabulador y, a continuación, se intenta activarlo, no se muestra la descripción emergente. Esto significa que la descripción emergente es inaccesible para los usuarios que dependen del uso del teclado.
• Si establece 'Hide On Click' en false, no se cumpliría el requisito de WCAG 2.1 “Contenido al pasar el cursor o en foco” porque no es posible eliminar la descripción emergente. La descripción emergente puede ocultar el contenido que un usuario necesita leer.

Código

Hay dos componentes diferentes que implementan las especificaciones de “descripción emergente”. Mientras que el componente Tooltip es capaz de admitir todas las situaciones, el componente TooltipIcon solo se tiene en cuenta cuando la descripción emergente está asociada a un ícono. Consulte la sección Ejemplos para ver casos de uso.

Descripción emergente

import React from 'react';
import { Tooltip, Button } from '@jutro/components';

export const BasicTooltip = () => {
  return (
    <Tooltip content="This is a tooltip">
      <Button label="Move the cursor here" />
    </Tooltip>
  );
};

TooltipIcon

import { TooltipIcon } from '@jutro/components';
import React from 'react';

export const TooltipIconBasic = () => {
  return <TooltipIcon text="This is a tooltip" />;
};

Instrucción de importación

import { Tooltip, TooltipIcon } from '@jutro/components';

Contrato del componente descripción emergente

Asegúrese de comprender la superficie de la API de componentes del sistema de diseño, así como sus implicaciones, ventajas y desventajas. Obtenga más información en nuestra introducción a la API de componentes.

Propiedades

Propiedades de la descripción emergente

Warning: Cualquier propiedad de Tooltip no incluida en la siguiente lista se considera un detalle de implementación interna y no está sujeta a la política de cambios sin interrupciones.

content

Tipo

any

Descripción

Allows to specify content of the Tooltip message.

delay

Tipo

number | [number, number]

Descripción

Delay in ms between the trigger or closure event and the tooltip appearing or disappearing.

Valor predeterminado

[0, 20]

duration

Tipo

number | [number, number]

Descripción

Duration of the CSS transition animation in ms. Using the tuple type [number, number] allows setting the show and hide durations separately.

Valor predeterminado

[300, 300]

flipBehavior

Tipo

'right' | 'bottom' | 'top' | 'left'[]

Descripción

Determines the order of flipping, i.e., which placements to prefer if a certain placement cannot be used.

Valor predeterminado

['right', 'bottom', 'top', 'left', 'right']

followCursor

Tipo

boolean

Descripción

If set to true, the tooltip follows the user's mouse cursor.

hideOnClick

Tipo

true | false | 'toggle'

Descripción

If set to true, the tooltip disappears if a mousedown event is fired outside of it. If set to false, it is not possible to close the tooltip. If 'toggle' option is used, the tooltip will be closed when clicking on the element again. In all cases, trigger property needs to be set to 'click'.

Valor predeterminado

true

placement

Tipo

'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'auto' | 'auto-start' | 'auto-end'

Descripción

Positions of the tooltip relative to its reference element: top, right, left, bottom.

Valor predeterminado

right

showOnInit

Tipo

boolean

Descripción

Displays the tooltip when the page is loaded.

sticky

Tipo

boolean | 'reference' | 'popper'

Descripción

Ensures the tooltip stays stuck to its reference element if it moves around or changes size.

Valor predeterminado

true

trigger

Tipo

string

Descripción

The events (each separated by a space) which cause the tooltip to appear.

Valor predeterminado

'mouseenter focus'

animationobsoleto

Tipo

string

Descripción

The type of the transition animation. Only 'fade' is accepted as value.

Valor predeterminado

'fade'

idobsoleto

Tipo

string

Descripción

Unique identifier for the component.

Contrato del componente TooltipIcon

Propiedades de TooltipIcon

Note: Es necesario que exista un ícono con el mismo nombre que el que se pasó en la propiedad icon, pero con el sufijo '-outlined', para establecer un ícono específico. Si no existe, el ícono predeterminado se mostrará siempre.

className

Tipo

string

Descripción

CSS class name for this component.

disabled

Tipo

boolean

Descripción

If true, trigger icon is disabled.

flipBehavior

Tipo

'right' | 'bottom' | 'top' | 'left'[]

Descripción

Determines the order of flipping, i.e., which placements to prefer if a certain placement cannot be used.

Valor predeterminado

['right', 'bottom', 'top', 'left', 'right']

href

Tipo

string

Descripción

URL to be opened when user clicks on link text. It requires link property to be set also.

icon

Tipo

string | Icon

Descripción

An Icon component to render on the component. The value must be an Icon component or the icon's name. For example, CheckIcon or 'gw-check'.

Valor predeterminado

'gw-help'

link

Tipo

string

Descripción

Text of link to be rendered inside tooltip. It requires that href property is also set.

messageProps

Tipo

{ showTooltip: intlMessageShape }

Descripción

Allows changing the aria-label of a trigger icon.

placement

Tipo

placementOptions

Descripción

Positions of the tooltip relative to its reference element (icon).

renderContent

Tipo

() => JSX.Element

Descripción

Allows rendering a custom tooltip.

showOnInit

Tipo

boolean

Descripción

Displays the tooltip when the page is loaded.

text

Tipo

string

Descripción

Text to be displayed in the tooltip.

title

Tipo

string

Descripción

Title to be displayed in the tooltip.

trigger

Tipo

string

Descripción

The events (each separated by a space) which cause the tooltip to appear.

fieldLabelIdobsoleto

Tipo

string

Descripción

Information from Field Component to link tooltip with related field. This property is not to be used out of the context of the @legacy input components.

idobsoleto

Tipo

string

Descripción

Unique identifier for the component.

labelPositionobsoleto

Tipo

top|left

Descripción

Information from Field Component to the Tooltip Icon about the position of the label. This property is not to be used out of the context of the @legacy input components.

linkClassobsoleto

Tipo

boolean

Descripción

Set specific class name to the link element of the tooltip.

showInlineLabelobsoleto

Tipo

boolean

Descripción

Information from Field Component. If set to true, the label is displayed inline. This property is not to be used out of the context of the @legacy input components.

textClassobsoleto

Tipo

boolean

Descripción

Set specific class name to the text element of the tooltip.

titleClassobsoleto

Tipo

boolean

Descripción

Set specific class name to the title element of the tooltip.

Solución de problemas

Problema conocido: el componente secundario requiere un forwardRef

Si Tooltip no funciona, es posible que se trate de un problema conocido: el componente secundario necesita un forwardRef para que la descripción emergente funcione.

La solución temporal para los componentes que no tienen forwardRef es encapsularlos en un <span>.

import { Badge, Tooltip } from '@jutro/components';
import React from 'react';

export const TooltipNoRef = () => {
  return (
    <Tooltip
      content="This badge does not have a forward ref but it really needs a tooltip"
      showOnInit
    >
      <span>
        <Badge
          value={7}
          type="primary"
        />
      </span>
    </Tooltip>
  );
};

Problema conocido: aria-expanded="true"

Si coloca un elemento que no puede recibir el foco dentro de un Tooltip, el elemento recibirá el rótulo aria-expanded="true". Este es incorrecto para HTML. Para evitar este problema, asegúrese de colocar solo elementos que puedan recibir el foco dentro de Tooltip.

Ejemplos

Consulte la sección Uso para obtener más información sobre cómo y cuándo utilizar los componentes Tooltip y TooltipIcon.

Descripción emergente básica

Descripción emergente básica agregada a un componente Button. La descripción emergente se muestra cuando se posiciona el cursor sobre el botón.

import React from 'react';
import { Tooltip, Button } from '@jutro/components';

export const BasicTooltip = () => {
  return (
    <Tooltip content="This is a tooltip">
      <Button label="Move the cursor here" />
    </Tooltip>
  );
};

Uso de diferentes desencadenantes y posiciones

Puede activar la descripción emergente al hacer clic, llevar el foco o el cursor sobre el elemento. La descripción emergente se muestra en un lugar diferente según la propiedad placement.

import { Button, Tooltip } from '@jutro/components';
import React from 'react';

export const TooltipPlacementAndTriggers = () => {
  return (
    <>
      <Tooltip
        content="Tooltip displayed on the left"
        placement="left"
        trigger="click"
      >
        <Button
          label="Click trigger"
          style={{ margin: '0 1rem 0 0' }}
        />
      </Tooltip>
      <Tooltip
        content="Tooltip displayed on the top"
        placement="top"
        trigger="click focus"
      >
        <Button
          label="Focus trigger"
          style={{ margin: '0 1rem 0 0' }}
        />
      </Tooltip>
      <Tooltip
        content="Tooltip displayed on the right"
        placement="right"
        trigger="mouseenter"
      >
        <Button label="Mouse enter trigger" />
      </Tooltip>
    </>
  );
};

Duración de la manipulación

Establecer la propiedad duration determina cuánto tiempo se tarda en mostrar y ocultar la descripción emergente.

import { Button, Tooltip } from '@jutro/components';
import React from 'react';

export const TooltipDuration = () => {
  return (
    <>
      <Tooltip
        content="Hides in 2 seconds"
        duration={2000}
      >
        <Button
          label="Takes 2 seconds to be displayed"
          style={{ margin: '0 1rem 0 0' }}
        />
      </Tooltip>
      <Tooltip
        content="Hides immediately"
        duration={[500, 0]}
      >
        <Button label="Opens in 0.5 seconds" />
      </Tooltip>
    </>
  );
};

Opciones para ocultar al hacer clic

Es posible decidir cuándo se cierra la descripción emergente después de que se activa por un evento de clic:

• Cuando se haga un clic en otras partes de la pantalla.
• Cuando se vuelva a hacer clic en el componente.
• Nunca.

import { Button, Tooltip } from '@jutro/components';
import React from 'react';

export const TooltipHideOnClickOptions = () => {
  return (
    <div style={{ display: 'flex', gap: '1rem', flexWrap: 'wrap' }}>
      <Tooltip
        content="Click outside to close"
        placement="top"
        trigger="click"
      >
        <Button label="hideOnClick = true" />
      </Tooltip>
      <Tooltip
        content="Click again on the button to hide"
        placement="top"
        hideOnClick="toggle"
        trigger="click"
      >
        <Button label="hideOnClick = toggle" />
      </Tooltip>
      <Tooltip
        content="Cannot be closed"
        placement="top"
        hideOnClick={false}
        trigger="click"
      >
        <Button label="hideOnClick = false" />
      </Tooltip>
    </div>
  );
};

Cómo agregar una nueva línea en un mensaje de descripción emergente

Es posible tener varias líneas en una descripción emergente de 2 maneras diferentes.

Opción 1: interpolando el mensaje con un nuevo carácter de línea.

import { Button, Tooltip } from '@jutro/components';
import React from 'react';

export const TooltipNewlineInterpolate = () => {
  return (
    <Tooltip
      content={{
        defaultMessage: 'This is a tooltip {br} this is a new line',
        args: { br: <br /> },
      }}
      placement="top"
      trigger="click"
    >
      <Button label="Click to open" />
    </Tooltip>
  );
};

Opción 2: pasando un elemento JSX como contenido.

import { Button, Tooltip } from '@jutro/components';
import React from 'react';

export const TooltipNewlineJsx = () => {
  return (
    <Tooltip
      content={
        <p>
          This is a tooltip <br /> this is a new line
        </p>
      }
      placement="top"
      trigger="click"
    >
      <Button label="Click to open" />
    </Tooltip>
  );
};

Ícono con descripción emergente

Hay dos opciones para crear un ícono con descripción emergente:

• Usando del componente TooltipIcon.
• Usando del componente Tooltip en combinación con el componente Icon.

La primera opción es más específica, pero más limitada en cuanto al número de alternativas disponibles.

TooltipIcon

import { TooltipIcon } from '@jutro/components';
import React from 'react';

export const TooltipIconWithTooltipIcon = () => {
  return (
    <TooltipIcon
      href="https://docs.guidewire.com"
      link="Tooltip link"
      text="Tooltip text"
      title="This is a tooltip title"
    />
  );
};

Ícono y descripción emergente

import { Tooltip } from '@jutro/components';
import React from 'react';

import { Icon } from '@jutro/legacy/components';

export const TooltipWithIconWithAnIconAndATooltip = () => {
  return (
    <Tooltip
      content="This is a tooltip"
      trigger="click"
    >
      <Icon icon="gw-warning" />
    </Tooltip>
  );
};

Registro de cambios

10.9.0

Tipo de propiedad icon extendida

El tipo de la propiedad icon se ha extendido a string | React.ComponentType.

Valor predeterminado de icon modificado

El valor predeterminado de la propiedad icon se cambió de 'gw-help' a HelpIcon.

Elementos obsoletos

El paso de un string como valor a la propiedad icon ha quedado obsoleto.

10.4.0

Descripción emergente

Las siguientes propiedades han quedado obsoletas:

• id
• animation. Nota: Solo se acepta 'fade' como valor.

TooltipIcon

Las siguientes propiedades han quedado obsoletas:

• id
• labelPosition
• showInlineLabel
• fieldLabelId
• titleClass
• textClass
• linkClass