Estados de tabla

Uso

Los estados de retroalimentación son una parte importante de la experiencia de usuario del componente tabla. Proporcionan información visual clara cuando la tabla no puede mostrar filas de datos, lo que transforma un espacio vacío potencialmente confuso en un mensaje útil e informativo. Estos estados comunican el estado actual de los datos, como cargando, vacío o error, y guían al usuario sobre cómo proceder. Esta documentación aborda los estados principales del componente tabla.

Formato

Anatomía

Si bien el contenido específico varía, todos los estados dentro de la tabla comparten un conjunto común de elementos, que se presentan en el cuerpo de la tabla en lugar de las filas de datos.

Imagen o ícono: Indicación visual que ayuda a los usuarios a comprender rápidamente la naturaleza del estado.
Título: Encabezado conciso que comunica el mensaje principal del estado.
Descripción: Cuerpo del texto que proporciona contexto adicional, explica por qué se muestra el estado y guía al usuario sobre los próximos pasos.
Acción: Botón o enlace que proporciona una vía directa para que el usuario lleve a cabo una acción.

No todos estos elementos son necesarios para todos los estados; la combinación específica depende del contexto. Consulte la sección sobre Variaciones de estado para conocer pautas detalladas sobre cada estado.

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.

Variaciones de estado

Estado cargando

El estado cargando informa al usuario que los datos se están recuperando. Consta de un ícono indicador de carga y un rótulo de texto. El mensaje debe ser simple y directo. Utilice el texto estándar “Cargando datos...” para informar claramente al usuario de que el sistema está funcionando. Este es un estado temporal y no incluye ningún elemento interactivo con el usuario, como botones o enlaces.

Ícono indicador de carga con el texto “Cargando datos...” que indica un estado cargando.

Estado vacío

El estado vacío informa al usuario por qué no hay datos que mostrar. El contenido y las acciones deben adaptarse al caso específico. Para obtener instrucciones integrales, consulte el ](pathname://es/empty-state.mdx)patrón de estado vacío[.

Uso inicial: Este estado aparece cuando un usuario encuentra por primera vez una característica y aún no ha agregado ningún dato. En el mensaje, explique el valor de la característica y use la acción principal para guiar al usuario a agregar el primer elemento (por ejemplo, con un botón Agregar siniestro).
Sin resultados de búsqueda: Este estado aparece después de que la búsqueda o el filtrado del usuario no devuelven resultados coincidentes. El mensaje debe informar al usuario que la búsqueda ha finalizado, pero no se ha encontrado nada. Se recomienda enfáticamente un botón de acción para proporcionar un camino claro para el usuario. Un buen ejemplo de una acción basada en la lógica es mostrar un botón Borrar filtros, pero solo cuando el estado vacío sea el resultado de filtros activos.
Después de una eliminación o finalización: Este estado aparece después de que un usuario completa correctamente una tarea, como borrar todas las notificaciones. Sirve como confirmación y, a menudo, no requiere un botón de acción.

Una pantalla de estado vacío que muestra el título “No se encontraron resultados” y el botón “Borrar filtros”.

Estado de error

El estado de error informa al usuario que los datos no se pudieron mostrar debido a un problema. El mensaje debe explicar claramente el problema en un lenguaje sencillo y proporcionar una ruta directa hacia la resolución. Por ejemplo, si se trata de una falla del sistema o de la red, el estado incluye un ícono de advertencia, el título “No se pueden recuperar datos”, una descripción que explica el problema y el botón Volver a cargar la página como acción de recuperación.

Pantalla de estado de error que muestra un ícono de advertencia, el título “No se pueden recuperar datos” y un botón “Volver a cargar la página”.

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.

Cuando utilice este componente en su aplicación, respete estas prácticas recomendadas:

Anuncie los cambios de estado. Cuando aparece un estado, los lectores de pantalla deben anunciar su contenido. Por lo general, esto requiere el uso de regiones activas de ARIA para garantizar que los usuarios de las tecnologías de asistencia estén al tanto del cambio.
Defina la función de las ilustraciones. Si un estado incluye texto complementario que explica la situación, la ilustración o el ícono deben tratarse como decorativos y estar ocultos para los lectores de pantalla. Si la ilustración es el único medio para transmitir el significado del estado, debe tener un texto alternativo descriptivo.

Clave	Valor predeterminado	Se usa para
jutro-components.Table.TableEmptyState.mainMessage	`Nothing to display`	Mensaje principal que se muestra cuando la tabla está vacía. Se puede invalidar mediante la propiedad `mainMessageContent`.
jutro-components.Table.TableEmptyState.detailedMessage	-	Contenido del mensaje adicional que se muestra debajo del mensaje principal. Útil para proporcionar contexto, instrucciones o detalles adicionales. Se puede invalidar mediante la propiedad `detailedMessageContent`.

Clave	Valor predeterminado	Se usa para
jutro-components.Table.TableLoader.label	`Loading data`	Rótulo que se muestra durante la carga de datos. Se puede invalidar mediante la propiedad `label`.

Ejemplos

El componente tabla proporciona la funcionalidad de estados de tabla utilizando solo componentes de Jutro. Para casos de uso avanzados o integraciones existentes, puede aprovechar opcionalmente bibliotecas externas como TanStack Table para manejar partes de la lógica de administración de datos.

Puede revisar dos tipos de ejemplos de código para los estados de tablas que demuestran el uso de componentes de Jutro solamente y el uso de TanStack Table para parte de la lógica de administración de datos. Los ejemplos tienen todos los archivos necesarios para que los revise en su entorno, como funciones que simulan el recupero de datos asíncronos. Cada ejemplo tiene un conjunto diferente de archivos.

Consulte la sección Uso para obtener detalles sobre cómo diseñar una tabla correctamente y las diferentes opciones de configuración que ofrecemos.

Implementación de estado vacío

Para implementar un estado vacío en la tabla, utilice el componente TableEmptyState dentro de TableBody cuando la matriz de datos esté vacía o cuando una verificación condicional determine que no se debe mostrar ningún contenido.

El componente TableEmptyState proporciona un ícono ErrorOutlineIcon y un rótulo Nothing to display predeterminados. Estos se pueden modificar utilizando las propiedades opcionales mainMessageContent y icon. También acepta propiedades opcionales como detailedMessageContent para contexto adicional y actions para elementos interactivos.

Utilice las propiedades mainMessageVariant y mainMessageTag para controlar la jerarquía y el estilo del encabezado.

Configure los botones de acción en la matriz actions, donde cada objeto de acción requiere una propiedad label y acepta todas las propiedades de botón opcionales, como el gestor de eventos onClick.

EmptyState.tsx
import React, { useId, useState } from 'react';

import {
  BodyCell,
  BodyRow,
  Button,
  HeaderCell,
  HeaderRow,
  Table,
  TableBody,
  TableEmptyState,
  TableHeader,
  Typography,
} from '@jutro/components';
import type { TableProps } from '@jutro/components';

const mockRowData = {
  product: 'Go Commercial Auto',
  insured: 'Marshall Reagan',
  premium: 'USD 1,236.39',
};

export const TableTitleString = 'Policy list';

/** Component that renders a table title section with heading and subtitle. */
export const TableTitle: React.FC<{
  tableId: string;
  children?: React.ReactNode;
}> = ({ tableId, children }) => (
  <div>
    <div>
      <Typography
        variant="heading-2"
        id={tableId}
      >
        {TableTitleString}
      </Typography>
      <Typography role="doc-subtitle">
        Detailed record of individual policies
      </Typography>
    </div>
    {children}
  </div>
);

export function EmptyStateStory(args: TableProps): React.ReactElement {
  const tableId = useId();
  const [hasData, setHasData] = useState(false);

  return (
    <div>
      <TableTitle tableId={tableId}>
        {hasData && (
          <div>
            <Button
              label="Clear data"
              onClick={() => setHasData(false)}
            />
          </div>
        )}
      </TableTitle>
      <Table
        noStripedRows={args.noStripedRows}
        className={args.className}
        aria-labelledby={tableId}
      >
        <TableHeader>
          <HeaderRow>
            <HeaderCell columnIndex={0}>Product</HeaderCell>
            <HeaderCell columnIndex={1}>Insured</HeaderCell>
            <HeaderCell columnIndex={2}>Premium</HeaderCell>
          </HeaderRow>
        </TableHeader>
        <TableBody>
          {!hasData ? (
            <TableEmptyState
              mainMessageVariant="heading-3"
              mainMessageTag="h3"
              mainMessageContent="Nothing to display"
              detailedMessageContent={
                <>
                  No records found.
                  <br />
                  Click <strong>Add a new entry</strong> to create a new entry.
                </>
              }
              actions={[
                {
                  label: 'Add a new entry',
                  variant: 'tertiary',
                  onClick: () => {
                    setHasData(true);
                  },
                },
              ]}
            />
          ) : (
            <BodyRow>
              <BodyCell
                rowIndex={0}
                columnIndex={0}
              >
                {mockRowData.product}
              </BodyCell>
              <BodyCell
                rowIndex={0}
                columnIndex={1}
              >
                {mockRowData.insured}
              </BodyCell>
              <BodyCell
                rowIndex={0}
                columnIndex={2}
              >
                {mockRowData.premium}
              </BodyCell>
            </BodyRow>
          )}
        </TableBody>
      </Table>
    </div>
  );
}

Implementación de estado cargando

Para implementar un estado cargando en la tabla, utilice el componente TableLoader dentro de TableBody la durante las operaciones de recuperación de datos o cualquier procesamiento asincrónico que requiera la retroalimentación del usuario.

El componente TableLoader proporciona una experiencia de carga estandarizada con un ícono indicador de carga y el rótulo predeterminado “Cargando datos”. Puede modificar tanto el ícono como el rótulo utilizando las propiedades disponibles. El componente centra automáticamente el contenido dentro del cuerpo de la tabla.

Implemente los estados cargando mediante la renderización condicional del componente TableLoader en función de su estado de recuperación de datos. Utilice indicadores booleanos como loading o isLoading de la gestión de estados para controlar cuándo aparece el estado cargando. El estado cargando reemplaza el contenido normal de la tabla durante las operaciones de datos y pasa automáticamente a la tabla rellena, a un estado vacío o a un estado de error adecuado una vez finalizada la operación.

Accesibilidad

Establezca aria-busy="true" en el componente Table durante las operaciones de carga para informar a las tecnologías de asistencia que el contenido se está actualizando.

Utilice aria-live="polite" en el componente Table para crear una región activa que anuncie automáticamente los cambios de estado a los usuarios de lectores de pantalla, lo que garantiza que reciban información oportuna cuando el contenido pase a los estados cargando, vacío y rellenado sin interrumpir el foco o flujo de lectura actual.

Implementación de componentes

LoadingState.tsx
import React, { useId, useState } from 'react';

import {
  BodyCell,
  BodyRow,
  Button,
  HeaderCell,
  HeaderRow,
  Table,
  TableBody,
  TableEmptyState,
  TableHeader,
  Typography,
  TableLoader,
} from '@jutro/components';
import { simulateAsyncFetch } from './simulateAsyncFetch';
import type { TableProps, TableEmptyStateProps } from '@jutro/components';

const mockRowData = [
  {
    id: '11111',
    product: 'Go Commercial Auto',
    insured: 'Marshall Reagan',
    premium: 'USD 1,236.39',
  },
  {
    id: '80077',
    product: "Go Worker's Compensation",
    insured: 'April Kub',
    premium: 'USD 173.99',
  },
  {
    id: '64487',
    product: 'USA Personal Auto',
    insured: 'Abel Rippin',
    premium: 'USD 1,228.69',
  },
  {
    id: '12345',
    product: 'Go Commercial Auto',
    insured: 'John Smith',
    premium: 'USD 892.45',
  },
];

export const TableTitleString = 'Policy list';

/** Component that renders a table title section with heading and subtitle. */
export const TableTitle: React.FC<{
  tableId: string;
  children?: React.ReactNode;
}> = ({ tableId, children }) => (
  <div>
    <div>
      <Typography
        variant="heading-2"
        id={tableId}
      >
        {TableTitleString}
      </Typography>
      <Typography role="doc-subtitle">
        Detailed record of individual policies
      </Typography>
    </div>
    {children}
  </div>
);

const TableBodyChildren: React.FC<{
  hasData: boolean;
  setHasData: React.Dispatch<React.SetStateAction<boolean>>;
  loading: boolean;
  setLoading: React.Dispatch<React.SetStateAction<boolean>>;
  args: TableProps & TableEmptyStateProps;
}> = ({ hasData, setHasData, loading, setLoading, args }) => {
  const addData = () => {
    setHasData(true);
  };
  {
  }
  if (loading) {
    return <TableLoader />;
  }
  {
  }
  if (!hasData) {
    return (
      <TableEmptyState
        mainMessageVariant="heading-3"
        mainMessageTag="h3"
        mainMessageContent="Nothing to display"
        detailedMessageContent={
          <>
            Unable to load data.
            <br />
            Click <strong>Reload</strong> to reload the data.
          </>
        }
        actions={[
          {
            label: 'Reload',
            variant: 'tertiary',
            onClick: simulateAsyncFetch(addData, {
              setLoading,
            }),
          },
        ]}
      />
    );
  }

  return (
    <>
      {mockRowData.map((row, index) => (
        <BodyRow key={row.id}>
          <BodyCell
            rowIndex={index}
            columnIndex={0}
          >
            {row.product}
          </BodyCell>
          <BodyCell
            rowIndex={index}
            columnIndex={1}
          >
            {row.insured}
          </BodyCell>
          <BodyCell
            rowIndex={index}
            columnIndex={2}
          >
            {row.premium}
          </BodyCell>
        </BodyRow>
      ))}
    </>
  );
};

export function EmptyStateReloadStory(
  args: TableProps & TableEmptyStateProps
): React.ReactElement {
  const tableId = useId();
  const [hasData, setHasData] = useState(false);
  const [loading, setLoading] = useState(false);

  return (
    <div>
      <TableTitle tableId={tableId}>
        {hasData && (
          <div>
            <Button
              label="Clear data"
              onClick={() => setHasData(false)}
            />
          </div>
        )}
      </TableTitle>
      <Table
        noStripedRows={args.noStripedRows}
        className={args.className}
        aria-labelledby={tableId}
        aria-busy={loading ? 'true' : 'false'}
        aria-live="polite"
      >
        <TableHeader>
          <HeaderRow>
            <HeaderCell columnIndex={0}>Product</HeaderCell>
            <HeaderCell columnIndex={1}>Insured</HeaderCell>
            <HeaderCell columnIndex={2}>Premium</HeaderCell>
          </HeaderRow>
        </TableHeader>
        <TableBody>
          <TableBodyChildren
            hasData={hasData}
            setHasData={setHasData}
            loading={loading}
            setLoading={setLoading}
            args={args}
          />
        </TableBody>
      </Table>
    </div>
  );
}

Administración de los datos

simulateAsyncFetch.ts
const WAIT_TIME = 400;

type SimulateAsyncFetchOptions = {
    setLoading?: (value: boolean) => void;
    delay?: number;
};

export function simulateAsyncFetch<T extends unknown[], R>(
    callback: (...args: T) => R | Promise<R>,
    options?: SimulateAsyncFetchOptions
): (...args: T) => Promise<R> {
    let timer: number | null = null;

    return async (...args: T): Promise<R> => {
        options?.setLoading?.(true);

        try {
            return await callback(...args);
        } finally {
            if (timer) {
                clearTimeout(timer);
            }

            timer = window.setTimeout(
                () => options?.setLoading?.(false),
                options?.delay || WAIT_TIME
            );
        }
    };
}

Uso​

Formato​

Anatomía​

Contenido​

Pautas generales de redacción​

Variaciones de estado​

Estado cargando​

Estado vacío​

Estado de error​

Accesibilidad​

Código​

Instrucción de importación​

Contrato de componentes​

TableEmptyState​

Propiedades​

actions​

detailedMessageContent​

icon​

mainMessageContent​

mainMessageTag​

mainMessageVariant​

TableLoader​

Propiedades​

icon​

label​

Comportamientos personalizados​

Escalado de altura que tiene en cuenta el contexto​

Situaciones de ejemplo​

Personalización de la altura mínima​

Ganchos​

Claves de traducción​

TableEmptyState​

TableLoader​

Escotillas de escape​

Ejemplos​

Implementación de estado vacío​

Implementación de estado cargando​

Accesibilidad​

Implementación de componentes​

Administración de los datos​

Implementación de componentes​

Administración de los datos​

Registro de cambios​

10.13.0​

10.12.0​

Uso

Formato

Anatomía

Contenido

Pautas generales de redacción

Variaciones de estado

Estado cargando

Estado vacío

Estado de error

Accesibilidad

Código

Instrucción de importación

Contrato de componentes

TableEmptyState

Propiedades

`actions`

`detailedMessageContent`

`icon`

`mainMessageContent`

`mainMessageTag`

`mainMessageVariant`

TableLoader

Propiedades

`icon`

`label`

Comportamientos personalizados

Escalado de altura que tiene en cuenta el contexto

Situaciones de ejemplo

Personalización de la altura mínima

Ganchos

Claves de traducción

TableEmptyState

TableLoader

Escotillas de escape

Ejemplos

Implementación de estado vacío

Implementación de estado cargando

Accesibilidad

Implementación de componentes

Administración de los datos

Implementación de componentes

Administración de los datos

Registro de cambios

10.13.0

10.12.0