Tabellenzustände

Tabellenzustände in Storybook

Verwendung

Feedback-Zustände sind ein wichtiger Bestandteil der Benutzerfreundlichkeit der Tabellenkomponente. Sie geben ein klares visuelles Feedback, wenn in der Tabelle keine Datenzeilen angezeigt werden können, und verwandeln eine ggf. verwirrende Leere in eine hilfreiche und informative Nachricht. Diese Zustände kommunizieren den aktuellen Status der Daten, z. B. „Wird geladen“, „Leer“ oder „Fehler“, und geben dem Benutzer Hinweise zum weiteren Vorgehen. Diese Dokumentation behandelt die primären Zustände der Tabellenkomponente.

Formatierung

Aufbau

Obwohl der genaue Inhalt variiert, teilen sich alle Zustände innerhalb der Tabelle einen gemeinsamen Satz von Elementen, die im Hauptteil der Tabelle anstelle der Datenzeilen angezeigt werden.

1. Bild oder Symbol: Ein visueller Hinweis, der Benutzern hilft, die Art des Zustands schnell zu erkennen.
2. Titel: Eine prägnante Überschrift, die die Hauptbotschaft des Zustands vermittelt.
3. Beschreibung: Text, der zusätzlichen Kontext liefert und erklärt, warum der Zustand angezeigt wird, und der den Benutzer zu den nächsten Schritten führt.
4. Aktion: Eine Schaltfläche oder ein Link, über den der Benutzer direkt zum Handeln aufgefordert wird.

Nicht alle diese Elemente sind für jeden Zustand erforderlich. Die konkrete Kombination hängt vom Kontext ab. Ausführliche Richtlinien zu den einzelnen Zuständen finden Sie im Abschnitt über Verschiedene Zustände.

Inhalt

Allgemeine Richtlinien fürs Schreiben

• Verwenden Sie die Großschreibung des ersten Worts und von Substantiven für alle Aspekte der Gestaltung von Guidewire-Produktschnittstellen. Schreiben Sie nicht alles groß.
• Verwenden Sie in den meisten Situationen Verben im Präsens und im Aktiv.
• Verwenden Sie gebräuchliche Abkürzungen, um Ihrem Text einen natürlichen und informellen Ton zu verleihen.
• Verwenden Sie eine einfache Sprache. Vermeiden Sie unnötigen Jargon und komplexe Sprache.
• Halten Sie Wörter und Sätze kurz.

Verschiedene Zustände

Zustand „Wird geladen“

Der Zustand „Wird geladen“ informiert den Benutzer darüber, dass gerade Daten abgerufen werden. Er besteht aus einem sich drehenden Symbol und einer Textbeschriftung. Die Botschaft muss einfach und direkt sein. Verwenden Sie den Standardtext „Daten werden geladen...“, der den Benutzer eindeutig darüber informiert, dass das System funktioniert. Dies ist ein temporärer Zustand, der keine für den Benutzer interaktiven Elemente wie Schaltflächen oder Links anbietet.

Leerzustand

Im Leerzustand wird der Benutzer darüber informiert, warum keine Daten zum Anzeigen vorhanden sind. Die Inhalte und Aktionen müssen auf das jeweilige Szenario zugeschnitten sein. Eine umfassendere Anleitung finden Sie unter ](./empty-state.mdx)Leerzustand-Muster[.

• Erstmalige Verwendung: Dieser Zustand tritt ein, wenn ein Benutzer zum ersten Mal auf eine Funktion stößt und noch keine Daten hinzugefügt hat. Erläutern Sie in der Meldung den Wert der Funktion und nutzen Sie die primäre Aktion, um den Benutzer zum Hinzufügen seines ersten Elements zu führen (z. B. mit der Schaltfläche Schadenfall hinzufügen).
• Keine Suchergebnisse: Dieser Status wird angezeigt, wenn die Suche oder Filterung eines Benutzers keine passenden Ergebnisse liefert. Die Meldung muss den Benutzer darüber informieren, dass die Suche abgeschlossen ist, aber nichts gefunden wurde. Eine Aktionsschaltfläche wird hier dringend empfohlen, um dem Benutzer einen klaren Weg zu weiteren Schritten anzubieten. Ein gutes Beispiel für eine logische Aktion ist die Anzeige der Schaltfläche Filter löschen, jedoch nur dann, wenn der Leerzustand auf aktive Filter zurückzuführen ist.
• Nach dem Löschen oder Abschließen: Dieser Zustand wird angezeigt, nachdem ein Benutzer eine Aufgabe erfolgreich abgeschlossen hat, z. B. das Löschen aller Benachrichtigungen. Er dient als Bestätigung und benötigt oft keine Aktionsschaltfläche.

Fehlerzustand

Der Fehlerzustand informiert den Benutzer, dass Daten aufgrund eines Problems nicht angezeigt werden können. Die Nachricht muss das Problem in einfacher Sprache klar erklären und einen direkten Weg zur Lösung aufzeigen. Bei einem System- oder Netzwerkausfall umfasst der Zustand beispielsweise ein Warnsymbol, den Titel „Daten können nicht abgerufen werden“, eine Beschreibung des Problems und die Schaltfläche Seite neu laden für die Wiederherstellungsaktion.

Barrierefreiheit

Diese Komponente wurde validiert, um die Richtlinien für Barrierefreiheit WCAG 2.2 AA in der Standardbasiskonfiguration zu erfüllen. Dazu wird u. a. Folgendes sichergestellt:

• Das Kontrastverhältnis von Textelementen zu ihrem Hintergrund liegt über 4,5:1.
• Nicht-textuelle Inhalte, die eine Bedeutung vermitteln sollen (z. B. Symbole und Fokusanzeigen), weisen ein Kontrastverhältnis von mindestens 3:1 zu den angrenzenden Farben auf.
• Das jeweilige Element kann sowohl über eine Tastatur als auch über eine Maus bedient werden.
• Der Zugriff auf die Inhalte erfolgt über Screenreader wie JAWS oder VoiceOver.

Die Konformität mit den Richtlinien für Barrierefreiheit hängt letztendlich davon ab, wie diese Komponente implementiert und angepasst wird. Vom Autor des Inhalts vorgenommene Änderungen können sich auf die Barrierefreiheit auswirken. Details zu unserem Modell der geteilten Verantwortung finden Sie in unserer Erklärung zur Barrierefreiheit von Jutro.

Beachten Sie bei Verwendung dieser Komponente in Ihrer Anwendung die folgenden Best Practices:

• Kündigen Sie Zustandsänderungen an. Wenn ein Zustand angezeigt wird, muss sein Inhalt über Screenreader angesagt werden. Dies erfordert in der Regel die Verwendung von ARIA-Live-Bereichen, um sicherzustellen, dass Benutzer von Hilfstechnologien über die Änderung informiert sind.
• Definieren Sie die Rolle von Illustrationen. Wenn ein Status unterstützenden Text enthält, der die Situation erklärt, muss die Illustration oder das Symbol als dekorativ behandelt und vor Screenreadern verborgen werden. Wenn die Illustration die einzige Möglichkeit ist, die Bedeutung des Zustands zu vermitteln, muss sie einen beschreibenden Alternativtext enthalten.

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,
          }),
        },
      ]}
    />
  );
}

Im Abschnitt Beispiele finden Sie vollständige Codebeispiele zur Demonstration verschiedener Implementierungen der Tabellenzustände.

Importanweisung

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

Komponentenvertrag

Vergewissern Sie sich, dass Sie die API-Oberfläche der Design System-Komponenten und die damit verbundenen Auswirkungen und Kompromisse verstehen. Erfahren Sie mehr in unserer Einführung zur Komponenten-API.

TableEmptyState

Die TableEmptyState-Komponente definiert den Leerzustand der Tabelle. Sie wird innerhalb der TableBody-Komponente verwendet, wenn keine Daten zum Anzeigen vorhanden sind. Die Komponente zentriert den Inhalt automatisch im Tabellenkörper und berechnet seine Höhe basierend auf dem zuvor angezeigten Tabelleninhalt, um abrupte visuelle Verschiebungen zwischen den Zuständen zu verhindern.

Eigenschaften

actions

Typ

ButtonProps[]

Beschreibung

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

Typ

React.ReactNode

Beschreibung

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

icon

Typ

React.ReactElement

Beschreibung

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

Standardwert

ErrorOutlineIcon

mainMessageContent

Typ

React.ReactNode

Beschreibung

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

mainMessageTag

Typ

AllowedElementType

Beschreibung

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

Typ

Variant

Beschreibung

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

Standardwert

heading-3

TableLoader

Die TableLoader-Komponente definiert den Ladezustand der Tabelle. Er wird innerhalb der TableBody-Komponente bei Datenabrufvorgängen oder bei asynchronen Verarbeitungen verwendet, die Benutzerfeedback erfordern. Die Komponente zentriert den Inhalt automatisch im Tabellenkörper und berechnet seine Höhe basierend auf dem zuvor angezeigten Tabelleninhalt, um abrupte visuelle Verschiebungen zwischen den Zuständen zu verhindern.

Eigenschaften

icon

Typ

React.ReactElement

Beschreibung

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

Standardwert

SpinnerIcon

label

Typ

IntlMessageShape

Beschreibung

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

Standardwert

Loading data

Benutzerdefinierte Verhalten

Kontextabhängige Höhenskalierung

Die Komponenten TableEmptyState und TableLoader verfügen über eine kontextbezogene Höhenskalierung, um störendes Flackern und Verschieben der Benutzeroberfläche zu verhindern. Wenn diese Komponenten gerendert werden, berechnen sie ihre Höhe basierend auf dem zuvor angezeigten Tabelleninhalt. Dadurch wird sichergestellt, dass Loader und Leerzustände den gleichen vertikalen Platz wie im vorherigen Datensatz einnehmen, was zu einer flüssigeren Benutzeroberfläche ohne plötzliche Layoutverschiebungen führt.

Beispielszenario

• Laden von Daten: Eine Tabelle mit 50 Zeilen und einer Höhe von 1000 Pixel behält diese Höhe von 1000 Pixel bei, wenn während eines asynchronen Vorgangs der Loader angezeigt wird, wodurch verhindert wird, dass sich der Inhalt unterhalb der Tabelle verschiebt.
• Suche ohne Ergebnisse: Nachdem die Filterung keine passenden Ergebnisse geliefert hat, nimmt der Leerzustand die Höhe ein, die zuvor vom gefilterten Datensatz eingenommen wurde, wodurch die Stabilität des Layouts gewahrt bleibt.
• Minimale Daten: Eine Tabelle mit zwei Zeilen und einer Höhe von 100 Pixel wird bei Auftreten eines entsprechenden Zustands auf mindestens 400 Pixel erweitert, um ausreichend Platz für den Inhalt des Zustands zu gewährleisten.

Anpassen der Mindesthöhe

Die berechnete Höhe wird automatisch ermittelt und kann nicht angepasst werden. Sie können jedoch den Wert von min-height überschreiben (standardmäßig auf 400 Pixel festgelegt), der gilt, wenn der Inhalt der vorherigen Tabelle minimal ist. Setzen Sie dazu den entsprechenden Design-Token:

• jds.table.content.empty für TableEmptyState
• jds.table.content.loading für TableLoader

Hooks

Für table states sind keine Hooks verfügbar.

Übersetzungsschlüssel

TableEmptyState

Schlüssel	Standardwert	Verwendet für
jutro-components.Table.TableEmptyState.mainMessage	Nothing to display	Hauptmeldung, die angezeigt wird, wenn die Tabelle leer ist. Kann durch die mainMessageContent-Eigenschaft überschrieben werden.
jutro-components.Table.TableEmptyState.detailedMessage	-	Zusätzlicher Nachrichteninhalt, der unter der Hauptmeldung angezeigt wird. Nützlich für Kontext, Anweisungen oder zusätzliche Details. Kann durch die detailedMessageContent-Eigenschaft überschrieben werden.

TableLoader

Schlüssel	Standardwert	Verwendet für
jutro-components.Table.TableLoader.label	Loading data	Beschriftung, die beim Laden von Daten angezeigt wird. Kann durch die label-Eigenschaft überschrieben werden.

Escape Hatches

Weitere Informationen finden Sie in unserer Dokumentation über Escape Hatches.

Beispiele

Die Tabellenkomponente stellt die Funktion der Tabellenzustände mit Jutro-Komponenten bereit. Für erweiterte Anwendungsfälle oder bestehende Integrationen können Sie optional externe Bibliotheken wie TanStack Table nutzen, um bestimmte Teile der Datenmanagement-Logik zu realisieren.

Sie können sich zwei Arten von Codebeispielen für die Tabellenpaginierung ansehen. Sie veranschaulichen einerseits die Verwendung ausschließlich von Jutro-Komponenten und andererseits die Verwendung von TanStack Table für einen Teil der Datenmanagement-Logik. Die Beispiele enthalten alle Dateien, die Sie benötigen, um sie in Ihrer Umgebung zu begutachten, z. B. Funktionen, die das asynchrone Abrufen von Daten simulieren. Für jedes Beispiel wird ein anderer Satz von Dateien verwendet.

Im Abschnitt Verwendung finden Sie Informationen zum korrekten Design einer Tabelle und zu den verschiedenen von Guidewire bereitgestellten Konfigurationsoptionen.

Implementierung des Leerzustands

Um einen Leerzustand in Ihrer Tabelle zu implementieren, verwenden Sie die TableEmptyState-Komponente in TableBody, wenn Ihr Datenarray leer ist oder wenn durch eine logische Prüfung festlegt wird, dass kein Inhalt angezeigt werden soll.

Die TableEmptyState-Komponente enthält ein ErrorOutlineIcon-Standardsymbol und eine Nothing to display-Beschriftung. Diese können mit den optionalen Eigenschaften mainMessageContent und icon modifiziert werden. Es werden auch optionale Eigenschaften wie detailedMessageContent für zusätzlichen Kontext und actions für interaktive Elemente akzeptiert.

Verwenden Sie die Eigenschaften mainMessageVariant und mainMessageTag, um die Überschriftenhierarchie und das Styling zu steuern.

Konfigurieren Sie Aktionsschaltflächen über das actions-Array. Hierbei erfordert jedes Aktionsobjekt eine label-Eigenschaft und akzeptiert alle optionalen Schaltflächeneigenschaften, z. B. den Ereignishandler 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>
  );
}

Implementierung des Ladezustands

Um einen Ladezustand in Ihrer Tabelle zu implementieren, verwenden Sie die TableLoader-Komponente in TableBody während der Datenabrufvorgänge oder bei jeder asynchronen Verarbeitung, die Benutzerfeedback erfordert.

Die TableLoader-Komponente bietet eine standardisierte Ladeanzeige mit einem sich drehenden Symbol und der Standardbeschriftung „Daten werden geladen“. Sie können sowohl das Symbol als auch die Beschriftung mithilfe der verfügbaren Eigenschaften ändern. Die Komponente zentriert den Inhalt automatisch im Tabellenhauptteil.

Implementieren Sie Ladezustände, indem Sie die TableLoader-Komponente abhängig vom Abrufstatus der Daten (bedingt) rendern. Verwenden Sie boolesche Flags wie loading oder isLoading aus Ihrer Statusverwaltung, um zu steuern, wann der Ladezustand angezeigt wird. Der Ladezustand dient dazu, den normalen Tabelleninhalt bei Datenvorgängen zu ersetzen und nach Abschluss des Vorgangs automatisch entweder in die aufgefüllte Tabelle, in den Leerzustand oder in einen entsprechenden Fehlerzustand überzugehen.

Barrierefreiheit

Für den Ladevorgang muss die Table-Komponente mit aria-busy="true" konfiguriert sein, um Hilfstechnologien darüber zu informieren, dass der Inhalt gerade aktualisiert wird.

Verwenden Sie aria-live="polite" für die Table-Komponente, um einen Live-Bereich zu erstellen, der Benutzern von Screenreadern automatisch Statusänderungen ankündigt. Damit wird sichergestellt, dass sie eine zeitnahe Rückmeldung erhalten, wenn Tabelleninhalte zwischen den Zuständen „Wird geladen“, „Leer“ und „Gefüllt“ wechseln, ohne ihren aktuellen Fokus oder Lesefluss zu unterbrechen.

Implementierung von Komponenten

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

Datenmanagement

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

Implementierung von Komponenten

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

Datenmanagement

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

Änderungsprotokoll

10.13.0

Die Komponenten TableEmptyState und TableLoader, die den Leer- und Ladezustand der Tabelle verarbeiten, wurden mit kontextabhängiger Höhenskalierung aktualisiert. Dieses Update verhindert störendes Flackern und Verschieben der Benutzeroberfläche, indem es sicherstellt, dass Lade- und Leerzustände den gleichen vertikalen Platz einnehmen wie der vorherige Datensatz. Die Benutzeroberfläche wird dadurch nahtloser mit ruhigeren Übergängen.

10.12.0

Die folgenden Komponenten wurden eingeführt:

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