États de la table

États de la table dans Storybook

Utilisation

Les états de retour sont une partie importante de l’expérience utilisateur du composant Table. Ils fournissent un retour visuel clair lorsque la table ne peut pas afficher de lignes de données, transformant ainsi un espace vide potentiellement déroutant en un message utile et informatif. Ces états communiquent le statut actuel des données, par exemple chargement, vide ou erreur, et guident l’utilisateur quant à la marche à suivre. Cette documentation couvre les principaux états du composant Table.

Formatage

Structure

Bien que le contenu spécifique varie, tous les états de la table partagent un ensemble commun d’éléments, présentés dans le corps de la table à la place des lignes de données.

1. Image ou icône : repère visuel qui aide les utilisateurs à comprendre rapidement la nature de l’état.
2. Titre : titre concis qui communique le message principal de l’état.
3. Description : corps du texte qui fournit un contexte supplémentaire, explique pourquoi l’état est affiché et guide l’utilisateur vers les étapes suivantes.
4. Action : bouton ou lien qui fournit à l’utilisateur un moyen direct d’effectuer une action.

Tous ces éléments ne sont pas requis pour tous les états ; la combinaison spécifique dépend du contexte. Reportez-vous à la section Variantes des états pour obtenir des instructions détaillées sur chaque état.

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.

Variantes des états

État de chargement

L’état de chargement informe l’utilisateur que des données sont en cours de récupération. Il se compose d’une icône de chargement et d’une étiquette de texte. Le message doit être simple et direct. Utilisez le texte standard « Chargement des données… » pour informer clairement l’utilisateur que le système fonctionne. Il s’agit d’un état temporaire qui n’inclut aucun élément interactif pour l’utilisateur tel que des boutons ou des liens.

État vide

L’état vide indique à l’utilisateur pourquoi il n’y a aucune donnée à afficher. Le contenu et les actions doivent être adaptés au scénario spécifique. Pour obtenir des conseils plus complets, reportez-vous au modèle d’état vide.

• Utilisation initiale : cet état apparaît lorsqu’un utilisateur rencontre une entité pour la première fois et qu’il n’a pas encore ajouté de données. Dans le message, expliquez la valeur de la fonctionnalité et utilisez l’action principale pour guider l’utilisateur vers l’ajout de son premier élément (par exemple, avec un bouton Ajouter un sinistre).
• Aucun résultat de recherche : cet état apparaît après que la recherche ou le filtrage d’un utilisateur ne renvoie aucun résultat correspondant. Le message doit informer l’utilisateur que la recherche est terminée mais qu’elle n’a rien trouvé. Il est vivement recommandé d’utiliser un bouton d’action pour indiquer à l’utilisateur une marche à suivre claire. Un bon exemple d’action logique consiste à afficher un bouton Effacer les filtres, mais uniquement lorsque l’état vide est la conséquence de l'utilisation de filtres actifs.
• Après suppression ou exécution : cet état apparaît après qu’un utilisateur a terminé avec succès une tâche, comme la suppression de toutes les notifications. Il sert de confirmation et ne nécessite souvent pas de bouton d’action.

État d'erreur

L’état d’erreur informe l’utilisateur que les données n’ont pas pu être affichées en raison d’un problème. Le message doit expliquer clairement le problème dans un langage simple et fournir un chemin direct vers une résolution. Par exemple, pour une panne de système ou de réseau, l’état inclut une icône d’avertissement, le titre « Impossible de récupérer les données », une description expliquant le problème et un bouton Recharger la page comme action de récupération.

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.

Lorsque vous utilisez ce composant dans votre application, respectez les meilleures pratiques suivantes :

• Annoncer les changements d’état. Lorsqu’un état s’affiche, son contenu doit être annoncé par les lecteurs d’écran. Cela nécessite généralement l’utilisation de régions actives ARIA pour s’assurer que les utilisateurs de technologies d’assistance sont informés du changement.
• Définir le rôle des illustrations. Si un état inclut un texte d'accompagnement qui explique la situation, l’illustration ou l’icône doit être traitée comme un élément décoratif et masquée pour les lecteurs d’écran. Si l’illustration est le seul moyen de transmettre le sens de l’état, elle doit comporter un texte alternatif descriptif.

Code

if (loading) {
  return <TableLoader />;
}

if (!hasData) {
  return (
    <TableEmptyState
      mainMessageVariant="heading-3"
      mainMessageTag="h3"
      mainMessageContent="Nothing to display"
      detailedMessageContent={
        <>
          Unable to load data.
          <br />
          Click below to try again.
        </>
      }
      actions={[
        {
          label: 'Reload',
          variant: 'tertiary',
          onClick: simulateAsyncFetch(addData, {
            setLoading,
          }),
        },
      ]}
    />
  );
}

Consultez la section Exemples pour obtenir des exemples de code complets illustrant diverses implémentations d'états de table.

Instruction d'importation

import { TableEmptyState, TableLoader } from '@jutro/components';

Cahier des charges du composant

Assurez-vous de comprendre la surface de l'API des composants du système de conception, ainsi que les implications et les compromis. Pour en savoir plus, reportez-vous à notre introduction à l'API des composants.

TableEmptyState

Le composant TableEmptyState définit l’état vide de la table. Il est utilisé dans le composant TableBody lorsqu’il n’y a aucune donnée à afficher. Le composant centre automatiquement le contenu dans le corps de la table et calcule sa hauteur en fonction du contenu de la table précédemment affiché afin d’éviter tout décalage visuel brusque entre les états.

Propriétés

actions

Type

ButtonProps[]

Description

A list of action buttons displayed below the messages, allowing users to perform specific tasks. You can add multiple action buttons and define them using the button component properties.

detailedMessageContent

Type

React.ReactNode

Description

Additional message content displayed below the main message. Useful for providing context, instructions, or extra details.

icon

Type

React.ReactElement

Description

The icon displayed above the main message. Accepts any React element, for example an Icon component, or SVG file.

Valeur par défaut

ErrorOutlineIcon

mainMessageContent

Type

React.ReactNode

Description

The content of the main message displayed when the table is empty.

mainMessageTag

Type

AllowedElementType

Description

The HTML element used by the Typography component to render the main message that you can use for semantic customization. See tag options to review possible values.

mainMessageVariant

Type

Variant

Description

The style variant of the Typography component applied to the main message. See variant options to review possible values.

Valeur par défaut

heading-3

TableLoader

Le composant TableLoader définit l’état de chargement de la table. Il est utilisé dans le composant TableBody pendant les opérations de récupération de données ou tout traitement asynchrone nécessitant un retour de l’utilisateur. Le composant centre automatiquement le contenu dans le corps de la table et calcule sa hauteur en fonction du contenu de la table précédemment affiché afin d’éviter tout décalage visuel brusque entre les états.

Propriétés

icon

Type

React.ReactElement

Description

The icon displayed during data loading. Accepts any React element, for example an Icon component, or SVG file.

Valeur par défaut

SpinnerIcon

label

Type

IntlMessageShape

Description

The content of the label displayed during data loading. Accepts an internationalized message shape for localization purposes.

Valeur par défaut

Loading data

Comportements personnalisés

Mise à l’échelle de la hauteur en fonction du contexte

Les composants TableEmptyState et TableLoader incluent une mise à l’échelle de la hauteur sensible au contexte pour empêcher le scintillement et le décalage de l’interface utilisateur gênants. Lorsque ces composants sont affichés, ils calculent leur hauteur en fonction du contenu de la table précédemment affiché. Cela garantit que les chargeurs et les états vides occupent le même espace vertical que l’ensemble de données précédent, ce qui permet d’obtenir une interface plus fluide sans changements brusques de mise en page.

Exemples de scénarios

• Chargement des données : un tableau affichant 50 lignes avec une hauteur de 1 000 px conserve cette hauteur de 1 000 px lorsque le chargeur apparaît pendant une opération asynchrone, ce qui empêche le contenu sous le tableau de se déplacer.
• Recherche sans résultats : une fois que le filtrage n'a renvoyé aucun résultat correspondant, l’état vide utilise la hauteur précédemment occupée par l’ensemble de données filtré, tout en maintenant la stabilité de la disposition.
• Données minimales : un tableau affichant deux lignes d’une hauteur de 100 px se développe à un minimum de 400 px lorsqu’un état apparaît, ce qui garantit un espace suffisant pour le contenu de l’état.

Personnalisation de la hauteur minimale

La hauteur calculée est déterminée automatiquement et ne peut pas être personnalisée. Toutefois, vous pouvez remplacer le paramètre min-height (par défaut, il est défini sur 400 px) qui s’applique lorsque le contenu de la table précédente est minimal, en définissant les jetons de conception correspondants :

• jds.table.content.empty pour TableEmptyState
• jds.table.content.loading pour TableLoader

Crochets

Aucun crochet n'est disponible pour table states.

Clés de traduction

TableEmptyState

Clé	Valeur par défaut	Utilisée pour
jutro-components.Table.TableEmptyState.mainMessage	Nothing to display	Message principal affiché lorsque la table est vide. Peut être remplacé par la propriété mainMessageContent.
jutro-components.Table.TableEmptyState.detailedMessage	-	Contenu de message supplémentaire affiché sous le message principal. Utile pour fournir un contexte, des instructions ou des détails supplémentaires. Peut être remplacé par la propriété detailedMessageContent.

TableLoader

Clé	Valeur par défaut	Utilisée pour
jutro-components.Table.TableLoader.label	Loading data	Étiquette affichée pendant le chargement des données. Peut être remplacé par la propriété label.

Portes de sortie

Pour en savoir plus, reportez-vous à notre documentation sur les portes de sortie.

Exemples

Le composant de table fournit une fonctionnalité d’états de table en utilisant uniquement des composants Jutro. Pour les cas d’utilisation avancés ou les intégrations existantes, vous pouvez éventuellement exploiter des bibliothèques externes telles que TanStack Table pour gérer certaines parties de la logique de gestion des données.

Vous pouvez passer en revue deux types d’exemples de code pour les états de table qui montrent l’utilisation des composants Jutro uniquement et l’utilisation de TanStack Table pour une partie de la logique de gestion des données. Les exemples contiennent tous les fichiers dont vous avez besoin pour les examiner dans votre environnement, comme des fonctions simulant l’extraction asynchrone de données. Chaque exemple dispose d’un ensemble de fichiers différent.

Consultez la section Utilisation pour découvrir comment concevoir correctement une table et connaître les différentes options de configuration que nous proposons.

Implémentation de l’état vide

Pour implémenter un état vide dans votre table, utilisez le composant TableEmptyState dans l'élément TableBody lorsque votre série de données est vide ou lorsqu’une vérification conditionnelle détermine qu’aucun contenu ne doit être affiché.

Le composant TableEmptyState fournit une icône ErrorOutlineIcon et une étiquette Nothing to display par défaut. Elles peuvent être modifiées à l’aide des propriétés facultatives mainMessageContent et icon. Il accepte également des propriétés facultatives telles que detailedMessageContent pour un contexte supplémentaire et actions pour des éléments interactifs.

Utilisez les propriétés mainMessageVariant et mainMessageTag pour contrôler la structure et le style des titres.

Configurez les boutons d’action via la série actions, où chaque objet d’action requiert une propriété label et accepte toutes les propriétés de bouton facultatives, telles que le gestionnaire d’événements 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>
  );
}

EmptyStateTanstack.tsx

import React, { useId, useState } from 'react';
import {
  flexRender,
  getCoreRowModel,
  Table as TableType,
  useReactTable,
} from '@tanstack/react-table';

import {
  BodyCell,
  BodyRow,
  Button,
  HeaderCell,
  HeaderRow,
  Table,
  TableBody,
  TableEmptyState,
  TableHeader,
  Typography,
} from '@jutro/components';
import type { TableEmptyStateProps, TableProps } from '@jutro/components';
import type { ColumnDef, RowData } from '@tanstack/react-table';

type TableMockData = {
  product: {
    name: string;
  };
  insured: string;
  premium: {
    currency: string;
    amount: number;
  };
};

const mockRowData: TableMockData = {
  product: {
    name: 'Go Commercial Auto',
  },
  insured: 'Marshall Reagan',
  premium: {
    currency: 'USD',
    amount: 1236.39,
  },
};

/** Tanstack Table module augmentation to extend ColumnMeta interface with alignment and aria-label properties. */
declare module '@tanstack/react-table' {
  interface ColumnMeta<TData extends RowData, TValue> {
    align?: 'left' | 'right' | 'center';
    ariaLabel?: string;
  }
}

/** Column configuration for the table with Product, Insured, and Premium columns. */
export const columns: ColumnDef<TableMockData, any>[] = [
  {
    id: 'product',
    header: () => (
      <Typography
        variant="heading-5"
        tag="span"
      >
        Product
      </Typography>
    ),
    cell: (props) => <Typography>{props.getValue()}</Typography>,
    accessorFn: (row) => row.product.name,
    meta: {
      ariaLabel: 'Product',
    },
  },
  {
    id: 'insured',
    header: () => (
      <Typography
        variant="heading-5"
        tag="span"
      >
        Insured
      </Typography>
    ),
    cell: (props) => <Typography>{props.getValue()}</Typography>,
    accessorKey: 'insured',
    meta: {
      ariaLabel: 'Insured',
    },
  },
  {
    id: 'premium',
    header: () => (
      <Typography
        variant="heading-5"
        tag="span"
      >
        Premium
      </Typography>
    ),
    cell: (props) => <Typography>{props.getValue()}</Typography>,
    accessorFn: (row) =>
      `${row.premium.currency} ${row.premium.amount?.toFixed(2)}`,
    meta: {
      align: 'right',
      ariaLabel: 'Premium',
    },
  },
];

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 mockData: TableMockData[] = [];

const TableBodyChildren: React.FC<{
  table: TableType<TableMockData>;
  data: TableMockData[];
  setTableData: React.Dispatch<React.SetStateAction<TableMockData[]>>;
  args: TableProps & TableEmptyStateProps;
}> = ({ table, data, setTableData, args }) => {
  if (!data.length) {
    return (
      <TableEmptyState
        mainMessageVariant={args.mainMessageVariant}
        mainMessageTag={args.mainMessageTag}
        mainMessageContent={args.mainMessageContent}
        detailedMessageContent={
          args?.detailedMessageContent || (
            <>
              No records found.
              <br />
              Click <strong>Add a new entry</strong> to create a new entry.
            </>
          )
        }
        actions={
          args?.actions || [
            {
              label: 'Add a new entry',
              variant: 'tertiary',
              onClick: () => {
                setTableData([mockRowData]);
              },
            },
          ]
        }
      />
    );
  }

  return (
    <React.Fragment>
      {table?.getRowModel()?.rows.map((row, rowIndex) => (
        <BodyRow key={row.id}>
          {row.getVisibleCells().map((cell, columnIndex) => (
            <BodyCell
              key={cell.id}
              rowIndex={rowIndex}
              columnIndex={columnIndex}
              align={cell.column.columnDef.meta?.align}
            >
              {flexRender(cell.column.columnDef.cell, cell.getContext())}
            </BodyCell>
          ))}
        </BodyRow>
      ))}
    </React.Fragment>
  );
};

export function EmptyStateTanstackStory(
  args: TableProps & TableEmptyStateProps
): React.ReactElement {
  const tableId = useId();

  const [tableData, setTableData] = useState(mockData);

  const table = useReactTable<TableMockData>({
    getCoreRowModel: getCoreRowModel(),
    data: tableData,
    columns,
  });

  return (
    <div>
      <TableTitle tableId={tableId}>
        {tableData.length > 0 && (
          <div>
            <Button
              label="Clear data"
              onClick={() => setTableData([])}
            />
          </div>
        )}
      </TableTitle>
      <Table
        aria-labelledby={tableId}
        className={args.className}
        noStripedRows={args.noStripedRows}
      >
        <TableHeader>
          {table.getHeaderGroups().map((headerGroup) => (
            <HeaderRow key={headerGroup.id}>
              {headerGroup.headers.map((header, columnIndex) => (
                <HeaderCell
                  key={header.id}
                  columnIndex={columnIndex}
                  align={header.column.columnDef.meta?.align}
                >
                  {flexRender(
                    header.column.columnDef.header,
                    header.getContext()
                  )}
                </HeaderCell>
              ))}
            </HeaderRow>
          ))}
        </TableHeader>
        <TableBody>
          <TableBodyChildren
            table={table}
            data={tableData}
            setTableData={setTableData}
            args={args}
          />
        </TableBody>
      </Table>
    </div>
  );
}

Implémentation de l’état de chargement

Pour implémenter un état de chargement dans votre table, utilisez le composant TableLoader dans TableBody pendant les opérations de récupération de données ou tout traitement asynchrone nécessitant un retour de l’utilisateur.

Le composant TableLoader offre une expérience de chargement standardisée avec une icône de double flèche et l’étiquette par défaut « Chargement des données ». Vous pouvez modifier l’icône et le libellé à l’aide des propriétés disponibles. Le composant centre automatiquement le contenu dans le corps de la table.

Implémentez des états de chargement en affichant le composant TableLoader de manière conditionnelle en fonction de l’état de récupération de vos données. Utilisez des indicateurs booléens comme loading ou isLoading dans le cadre de votre gestion des états pour contrôler l’affichage de l’état de chargement. L’état de chargement consiste à remplacer le contenu normal de la table pendant les opérations sur les données et à passer automatiquement à la table remplie, à un état vide ou à un état d’erreur approprié une fois l’opération terminée.

Accessibilité

Définissez aria-busy="true" au niveau du composant Table pendant les opérations de chargement pour informer les technologies d’assistance que le contenu est en cours de mise à jour.

Utilisez aria-live="polite" au niveau du composant Table pour créer une région active qui annonce automatiquement les changements d’état aux utilisateurs de lecteurs d’écran, ce qui leur permet de recevoir des commentaires en temps opportun lorsque le contenu passe d'un état à un autre (chargement, vide et rempli) sans interrompre le focus ni le flux de lecture actuel.

Implémentation des composants

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

Gestion des données

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

Implémentation des composants

LoadingStateTanstack.tsx

import React, { useId, useState } from 'react';
import {
  flexRender,
  getCoreRowModel,
  Table as TableType,
  useReactTable,
} from '@tanstack/react-table';

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

type TableMockData = {
  product: {
    name: string;
  };
  insured: string;
  premium: {
    currency: string;
    amount: number;
  };
};

const mockRowData: TableMockData[] = [
  {
    product: {
      name: 'Go Commercial Auto',
    },
    insured: 'Marshall Reagan',
    premium: {
      currency: 'USD',
      amount: 1236.39,
    },
  },
  {
    product: {
      name: "Go Worker's Compensation",
    },
    insured: 'April Kub',
    premium: {
      currency: 'USD',
      amount: 173.99,
    },
  },
  {
    product: {
      name: 'USA Personal Auto',
    },
    insured: 'Abel Rippin',
    premium: {
      currency: 'USD',
      amount: 1228.69,
    },
  },
  {
    product: {
      name: 'Go Commercial Auto',
    },
    insured: 'John Smith',
    premium: {
      currency: 'USD',
      amount: 892.45,
    },
  },
];

/** Tanstack Table module augmentation to extend ColumnMeta interface with alignment and aria-label properties. */
declare module '@tanstack/react-table' {
  interface ColumnMeta<TData extends RowData, TValue> {
    align?: 'left' | 'right' | 'center';
    ariaLabel?: string;
  }
}

/** Column configuration for the table with Product, Insured, and Premium columns. */
export const columns: ColumnDef<TableMockData, any>[] = [
  {
    id: 'product',
    header: () => (
      <Typography
        variant="heading-5"
        tag="span"
      >
        Product
      </Typography>
    ),
    cell: (props) => <Typography>{props.getValue()}</Typography>,
    accessorFn: (row) => row.product.name,
    meta: {
      ariaLabel: 'Product',
    },
  },
  {
    id: 'insured',
    header: () => (
      <Typography
        variant="heading-5"
        tag="span"
      >
        Insured
      </Typography>
    ),
    cell: (props) => <Typography>{props.getValue()}</Typography>,
    accessorKey: 'insured',
    meta: {
      ariaLabel: 'Insured',
    },
  },
  {
    id: 'premium',
    header: () => (
      <Typography
        variant="heading-5"
        tag="span"
      >
        Premium
      </Typography>
    ),
    cell: (props) => <Typography>{props.getValue()}</Typography>,
    accessorFn: (row) =>
      `${row.premium.currency} ${row.premium.amount?.toFixed(2)}`,
    meta: {
      align: 'right',
      ariaLabel: 'Premium',
    },
  },
];

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<{
  table: TableType<TableMockData>;
  data: TableMockData[];
  setTableData: React.Dispatch<React.SetStateAction<TableMockData[]>>;
  args: TableEmptyStateProps;
  loading: boolean;
  setLoading: React.Dispatch<React.SetStateAction<boolean>>;
}> = ({ table, data, setTableData, args, loading, setLoading }) => {
  {
  }
  if (loading) {
    return <TableLoader />;
  }
  {
  }
  const reloadData = () => {
    setTableData(mockRowData);
  };

  if (!data.length) {
    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(reloadData, {
              setLoading,
            }),
          },
        ]}
      />
    );
  }

  return (
    <React.Fragment>
      {table?.getRowModel()?.rows.map((row, rowIndex) => (
        <BodyRow key={row.id}>
          {row.getVisibleCells().map((cell, columnIndex) => (
            <BodyCell
              key={cell.id}
              rowIndex={rowIndex}
              columnIndex={columnIndex}
              align={cell.column.columnDef.meta?.align}
            >
              {flexRender(cell.column.columnDef.cell, cell.getContext())}
            </BodyCell>
          ))}
        </BodyRow>
      ))}
    </React.Fragment>
  );
};

export function LoadingStateTanstackStory(
  args: TableProps & TableEmptyStateProps
): React.ReactElement {
  const tableId = useId();

  const [tableData, setTableData] = useState<TableMockData[]>([]);
  const [loading, setLoading] = useState(false);

  const table = useReactTable<TableMockData>({
    getCoreRowModel: getCoreRowModel(),
    data: tableData,
    columns,
  });

  return (
    <div>
      <TableTitle tableId={tableId}>
        {tableData.length > 0 && (
          <div>
            <Button
              label="Clear data"
              onClick={() => setTableData([])}
            />
          </div>
        )}
      </TableTitle>
      <Table
        aria-labelledby={tableId}
        className={args.className}
        noStripedRows={args.noStripedRows}
        aria-busy={loading ? 'true' : 'false'}
        aria-live="polite"
      >
        <TableHeader>
          {table.getHeaderGroups().map((headerGroup) => (
            <HeaderRow key={headerGroup.id}>
              {headerGroup.headers.map((header, columnIndex) => (
                <HeaderCell
                  key={header.id}
                  columnIndex={columnIndex}
                  align={header.column.columnDef.meta?.align}
                >
                  {flexRender(
                    header.column.columnDef.header,
                    header.getContext()
                  )}
                </HeaderCell>
              ))}
            </HeaderRow>
          ))}
        </TableHeader>
        <TableBody>
          <TableBodyChildren
            table={table}
            data={tableData}
            setTableData={setTableData}
            args={args}
            loading={loading}
            setLoading={setLoading}
          />
        </TableBody>
      </Table>
    </div>
  );
}

Gestion des données

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

Journal des modifications

10.13.0

Les composants TableEmptyState et TableLoader qui gèrent les états « vide » et « chargement » de la table ont été mis à jour avec une mise à l’échelle contextuelle de la hauteur. Cette mise à jour empêche le scintillement et le décalage gênants de l’interface utilisateur en veillant à ce que les états « chargement » et « vides » occupent le même espace vertical que l’ensemble de données précédent, ce qui permet d’obtenir une interface plus fluide.

10.12.0

Les composants suivants ont été introduits :

• @jutro/components/TableEmptyState
• @jutro/components/TableLoader