Skip to content

Commit 5453a44

Browse files
deleoniodeleonio
authored
Added Table-Stateful & Table-Stateless (#250)
The A11y and PO reviews will only take place after all other DoD steps have been completed by the Developer: - [x] Maturation completed and documented - [x] Meaningful pull request title for the release notes - [x] Pull request is linked to an issue - [x] All changes relate to the issue - [x] No TODOs or commented out code in the final commit - [x] Tests to protect this code implemented (if applicable) - [x] Manual test performed successfully (if applicable) - [x] Documentation or migration has been updated (if applicable)
2 parents 879c612 + bb3c62d commit 5453a44

File tree

7 files changed

+298
-51
lines changed

7 files changed

+298
-51
lines changed

‎docs/30-components/popover.mdx

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ tags:
77
- Spezifikation
88
---
99

10-
import Readme from '../../readmes/popover/readme.md';
11-
1210
# Popover
1311

1412
<kol-badge _label="untested"></kol-badge> Diese neue Komponente wird als ungetestet markiert, da der vollständige Barrierefreiheitstest noch aussteht. Der vollständige Test kann bei neuen Komponenten und Funktionalitäten auch erst nach einem abgeschlossenen Release erfolgen.
@@ -17,5 +15,3 @@ Die **Popover**-Komponente stellt eine Möglichkeit dar zusätzliche Inhalte in
1715
Das Triggerelement ist immer das im HTML vorangehende Element (previousSibling).
1816

1917
<kol-alert _type="info" _variant="card">Die **Popover**-Komponente wird innerhalb von KoliBri verwendet und ist nicht dafür vorgesehen in der Anwendungsentwicklung verwendet zu werden.</kol-alert>
20-
21-
<Readme />

‎docs/30-components/span.mdx

Lines changed: 0 additions & 32 deletions
This file was deleted.

‎docs/30-components/table-stateful.mdx

Lines changed: 204 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,204 @@
1+
---
2+
title: TableStateful
3+
description: Beschreibung, Spezifikation und Beispiele für die TableStateful-Komponente.
4+
tags:
5+
- Table
6+
- Beschreibung
7+
- Spezifikation
8+
- Beispiele
9+
---
10+
11+
import Readme from '../../readmes/table-stateful/readme.md';
12+
import { LiveEditorCompact } from '@site/src/components/LiveEditorCompact';
13+
import { ExampleLink } from '@site/src/components/ExampleLink';
14+
15+
Synonyme: Data Table, Details List, Data Grid
16+
17+
Die **TableStateful**-Komponente dient primär der übersichtlichen Darstellung von Datenmengen. Dabei ist sie so ausgelegt, dass sie alle von den Daten abhängige Werte automatisch ermittelt und die Tabelle entsprechend darstellt. Hierzu gehören beispielsweise die optionalen Funktionalitäten Spaltensortierung oder Pagination.
18+
19+
<kol-indented-text _summary="Backend-seitige Pagination">
20+
Bei sehr großen Datenmengen ist auch eine manuelle Nutzung der TableStateless-Komponente möglich. Das bedeutet, dass die Tabelle seitenweise "manuell" befüllt wird. Hierzu kann einfach anstatt der Table-Pagination eine "eigene" Pagination unter der Tabelle mittels der Pagination-Komponente verwendet werden. Eine mögliche Sortierung muss ebenfalls über die `onSort`-Events selber implementiert werden. Siehe [KolTableStateless](./table-stateless).
21+
</kol-indented-text>
22+
23+
## Konstruktion
24+
25+
Die Table-Komponente ist so konstruiert, dass nicht der gesamte Tabellenaufbau im Markup selbst beschrieben werden muss. Wie genau die Tabelle Markup-spezifisch aufgebaut werden muss, um barrierefrei zu sein, übernimmt die Komponente selbst.
26+
27+
Dadurch, dass die Table-Komponente das valide und barrierefreie Markup dynamisch zusammenbaut, kann die komplexe Auszeichnung für die assistive Systeme dem/der Entwickler:in abgenommen werden.
28+
29+
### Funktionalitäten
30+
31+
Die Table-Komponente unterstützt folgende Funktionalitäten:
32+
33+
- Tabellenbeschreibung durch ein **`label`**-Attribut.
34+
- Mehrzeilige Spaltenüberschriften in horizontaler oder vertikaler Richtung.
35+
- Sortierfunktion für entweder horizontale und vertikale Ausrichtung.
36+
- Unterschiedliche Render-Funktion für die Zellen.
37+
- Pagination für die Tabelle.
38+
39+
Die Table-Komponente unterstützt folgende Funktionalitäten **nicht**:
40+
41+
- Das Filtern der Tabelle ist aktuell nicht innerhalb der Tabelle vorgesehen.
42+
- Das Auswählen von Zeilen ist aktuell in der Tabelle nicht vorgesehen.
43+
44+
> Beides könnte jedoch mittels der Render-Funktion umgesetzt werden.
45+
46+
### Pagination
47+
48+
Über das Attribut **`_pagination`** kann optional eine Vielzahl zusätzlicher Properties zur Steuerung der Pagination übergeben werden. Die genaue Beschreibung der Optionen ist auf der Seite <kol-link _href="../pagination" _label="/docs/components/pagination" _label="Pagination"></kol-link> zu finden.
49+
50+
#### KoliBriTableHeaders
51+
52+
```ts
53+
{
54+
horizontal: [
55+
[
56+
{
57+
label: string,
58+
key?: string,
59+
colsSpan?: number,
60+
rowSpan?: number,
61+
useTdInsteadOfTh?: boolean,
62+
render?: (data) => string,
63+
sort?: (data) => data,
64+
},
65+
…
66+
],
67+
…
68+
],
69+
vertical: [
70+
[
71+
{
72+
label: string,
73+
key?: string,
74+
colsSpan?: number,
75+
rowSpan?: number,
76+
useTdInsteadOfTh?: boolean,
77+
render?: (data) => string,
78+
sort?: (data) => data,
79+
},
80+
…
81+
],
82+
…
83+
],
84+
};
85+
```
86+
87+
### Code
88+
89+
```html
90+
<kol-table-stateful
91+
_label="Tabellenbeschreibung"
92+
_headers='{"horizontal": [[{"label":"Montag","key":"montag"}]]}'
93+
_pagination='[{"page":2}]'
94+
></kol-table-stateful>
95+
```
96+
97+
### Beispiel
98+
99+
<kol-table-stateful _label="Nur Vertikal Header, Daten Vertikal, Pagination" _headers='{"horizontal":[[{"label":"Montag","key":"montag"}]]}' _data='[{"montag":"Zelle1"},{"montag":"Zelle2"}]' _pagination='{"page":2}'></kol-table-stateful>
100+
101+
### Footer
102+
103+
Durch die Verwendung des **`_dataFoot_`**-Attribut können zusammenfassende Informationen oder zusätzliche Details am Ende der Tabelle angezeigt werden. Die Informationen sind hierbei an die Spaltendefinitionen gebunden.
104+
105+
### Beispiel
106+
107+
<kol-table-stateful _label="Nur Vertikal Header, Daten Vertikal, Pagination, DataFoot" _headers='{"horizontal":[[{"label":"Montag","key":"montag"}]]}' _data='[{"montag":"Zelle1"},{"montag":"Zelle2"}]' _dataFoot='[{"montag":"Ruhetag"}]' _pagination='{"page":2}'></kol-table-stateful>
108+
109+
## Verwendung
110+
111+
### Sortierung
112+
113+
- Zu jedem Header kann man eine Sortierfunktion definieren.
114+
- Es ist exakt eine oder keine Sortierfunktion aktiviert.
115+
- **Multi-Sort-Funktionalität**: Wenn die Multi-Sort-Option (`_allowMultiSort`) aktiviert ist, kann der Benutzer mehrere Spalten gleichzeitig sortieren. Standardmäßig ist diese Funktion deaktiviert, und nur eine Spalte kann auf einmal sortiert werden. Die Sortierung wechselt zwischen aufsteigend, absteigend und ohne Sortierung. Wenn Multi-Sort deaktiviert ist, wird die Sortierung der vorherigen Spalte aufgehoben, sobald eine neue Spalte sortiert wird.
116+
- Aktuell wird nicht unterstützt, dass bei zweidimensionalen Headern, die Header der jeweils anderen Header-Seite mit sortiert werden. Bei der Anforderung der Sortierung empfehlen wir die Verwendung nur einer Header-Dimension (entweder horizontal oder vertikal).
117+
118+
### Render Funktion
119+
120+
Render-Funktionen werden als Teil der Tabellen-Header definiert. Siehe Abschnitt "KoliBriTableHeaders". Gibt es sowohl horizontale als auch vertikale Header, muss die Render-Funktion für die _horizontalen_ Header definiert werden. Gibt es nur vertikale Header, können die Render-Funktionen dort definiert werden.
121+
122+
Die `render` Funktion kann auf verschiedene Arten wie folgt verwendet werden.
123+
Alle Methoden sind auch in diesem Beispiel demonstriert: [render-cell.tsx](https://github.com/public-ui/kolibri/blob/23ebb42d1ce3c8d1e4c74a5c7972842d5e4203fe/packages/samples/react/src/components/table/render-cell.tsx#L34)
124+
125+
1. String Rückgabewert:
126+
127+
```tsx
128+
{
129+
render: (_el, cell) => `Index: ${cell.label}`,
130+
}
131+
```
132+
133+
2. Node mit textContent füllen
134+
135+
```tsx
136+
{
137+
render: (el, cell) => {
138+
el.textContent = `Index: ${cell.label}`;
139+
},
140+
}
141+
```
142+
143+
3. Node mit innerHTML füllen - ⚠️ Hierbei unbedingt darauf achten, Werte zu sanitizen, um XXS vermeiden.
144+
145+
```tsx
146+
{
147+
render: (el, cell) => {
148+
el.innerHTML = `<strong>${cell.label}</strong>`;
149+
},
150+
}
151+
```
152+
153+
4. React render-function verwenden
154+
155+
```tsx
156+
import { createReactRenderElement } from '@public-ui/react';
157+
{
158+
render: (el) => {
159+
getRoot(createReactRenderElement(el)).render(
160+
<div>
161+
<KolInputText _label="Input" />
162+
<KolButton _label="Save" />
163+
</div>,
164+
);
165+
},
166+
}
167+
```
168+
169+
<!--### Best practices
170+
171+
### Anwendungsfälle-->
172+
173+
## Barrierefreiheit
174+
175+
Bei der Table-Komponente werden zahlreiche Attribut-Definitionen dem Tabellen-Markup hinzugefügt, um die Screenreader bestmöglich zu unterstützen.
176+
177+
Aktuell werden folgende Attribute von der Komponente verwaltet: `role`, `scope` und `aria-\*`.
178+
179+
Das heißt beispielsweise, dass bei den Spaltenüberschriften automatisch entweder die Rolle `colheader` oder `rowheader` gesetzt wird. Darüber hinaus wird der Scope entweder auf `col`/`colgroup` oder `row`/`rowgroup` gesetzt. Ähnlich dieser Automatismen werden auch die `aria-\*`-Attribute je nach Relevanz gesetzt.
180+
181+
Warum die Tabelle einen **Tabindex** hat, wird auf der folgenden Webseite beschrieben: <kol-link _href="" _label=""></kol-link>https://dequeuniversity.com/rules/axe/3.5/scrollable-region-focusable
182+
183+
## Links und Referenzen
184+
185+
- <kol-link _href="https://www.w3.org/WAI/tutorials/tables/" _target="_blank"></kol-link>
186+
- <kol-link _href="https://www.barrierefreies-webdesign.de/knowhow/datentabellen/scope.html" _target="_blank"></kol-link>
187+
- <kol-link _href="https://developer.mozilla.org/de/docs/Web/Accessibility/ARIA/ARIA_Live_Regions" _target="_blank"></kol-link>
188+
- <kol-link _href="https://tollwerk.de/projekte/tipps-techniken-inklusiv-barrierefrei/aria-live-regionen" _target="_blank"></kol-link>
189+
- <kol-link _href="https://www.barrierefreies-webdesign.de/knowhow/live-regions/attribute.html" _target="_blank"></kol-link>
190+
- <kol-link _href="https://www.digitala11y.com/aria-sort-properties/" _target="_blank"></kol-link>
191+
- <kol-link _href="https://dequeuniversity.com/library/aria/table-sortable" _target="_blank"></kol-link>
192+
- <kol-link _href="https://www.maxability.co.in/2016/06/07/aria-sort-property/" _target="_blank"></kol-link>
193+
- <kol-link _href="https://developer.mozilla.org/en-US/docs/Web/API/Element/ariaSort" _target="_blank"></kol-link>
194+
- <kol-link _href="https://tollwerk.de/projekte/tipps-techniken-inklusiv-barrierefrei/aria-live-regionen" _target="_blank"></kol-link>
195+
- <kol-link _href="https://stackoverflow.com/questions/1312236/" _target="_blank"></kol-link>
196+
- <kol-link _href="https://dequeuniversity.com/rules/axe/3.5/scrollable-region-focusable" _target="_blank"></kol-link>
197+
198+
<Readme />
199+
200+
<ExampleLink component="table-stateful" />
201+
202+
## Live-Editor
203+
204+
<LiveEditorCompact component="table-stateful" />

‎docs/30-components/table-stateless.mdx

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: TableStateless
3+
description: Beschreibung, Spezifikation und Beispiele für die TableStateless-Komponente.
4+
tags:
5+
- Table
6+
- Beschreibung
7+
- Spezifikation
8+
- Beispiele
9+
---
10+
11+
import Readme from '../../readmes/table-stateless/readme.md';
12+
import { LiveEditorCompact } from '@site/src/components/LiveEditorCompact';
13+
import { ExampleLink } from '@site/src/components/ExampleLink';
14+
15+
Synonyme: Data Table, Details List, Data Grid
16+
17+
Die **TableStateless**-Komponente ist für die reine Darstellung der KoliBri-Tabelle verantwortlich. Für eine Tabellen-Komponente, die Sortierung und Paginierung mit den zur Verfügung gestellten Daten automatisch übernehmen kann, siehe [KolTableStateful](./table-stateful).
18+
19+
TableStateless bietet sich insbesondere bei größeren Datenmengen an, wenn es nicht praktikabel ist, die komplette Datenmenge zur Filterung und Sortierung in den Browser auszuliefern.
20+
21+
## Selektion
22+
23+
Über die `_selection`-Property kann der "Selection-Modus" der Komponente aktiviert und gesteuert werden. Ist `_selection` definiert, erhält jede Zeile eine Checkbox, über die sich die Zeile aus- oder abwählen lässt.
24+
25+
```ts
26+
const data = [
27+
{ id: '1001', name: 'Marianne Musterfrau' },
28+
{ id: '1002', name: 'Max Mustermann' },
29+
];
30+
const selection: KoliBriTableSelection = {
31+
/* label: Funktion, welche für jede Zeile ausgerufen wird, und ein Label für die Checkbox zurückgibt. */
32+
label: (row: KoliBriTableDataType) => `Selection for ${row.name}`,
33+
34+
/* selectedKeys: Array von Strings, das die Key-Properties der gewählten Zeilen beinhaltet */
35+
selectedKeys: ['1002'],
36+
37+
/* keyPropertyName: Eigenschaft, auf die sich `selectedKeys` bezieht. Default-Wert: `id` */
38+
keyPropertyName: 'id',
39+
};
40+
```
41+
42+
## Beispiel
43+
44+
```jsx
45+
<KolTableStateless
46+
_label="Table for demonstration purposes"
47+
_headerCells={{
48+
horizontal: [
49+
[
50+
{ key: 'value', label: 'Value', sortDirection: 'ASC' },
51+
],
52+
],
53+
}}
54+
_data={DATA}
55+
_selection={{
56+
label: (row: KoliBriTableDataType) => `Selection for ${row.name}`,
57+
selectedKeys: ['1002'],
58+
keyPropertyName: 'id',
59+
}}
60+
_on={{
61+
/**
62+
* @param {MouseEvent} _
63+
* @param {SortEventPayload} payload
64+
* @param {string} payload.key
65+
* @param {KoliBriSortDirection} payload.currentSortDirection
66+
*/
67+
onSort: (_: MouseEvent, payload: SortEventPayload) => {
68+
/* Perform sort, update `DATA` and headers `sortDirection` */
69+
},
70+
71+
/**
72+
* @param {Event} _
73+
* @param {string[]} selection - Array of selected keys
74+
*/
75+
onSelectionChange: (_: Event, selection: string[]) => {
76+
/* Update selection.selectedKeys state */
77+
}
78+
}}
79+
/>
80+
```
81+
82+
<Readme />
83+
84+
<ExampleLink component="table-stateless" />
85+
86+
## Live-Editor
87+
88+
<LiveEditorCompact component="table-stateless" />

‎docs/30-components/table.mdx

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Table
2+
title: Table (Deprecated)
33
description: Beschreibung, Spezifikation und Beispiele für die Table-Komponente.
44
tags:
55
- Table
@@ -8,16 +8,13 @@ tags:
88
- Beispiele
99
---
1010

11-
import Readme from '../../readmes/popover/readme.md';
1211
import { LiveEditorCompact } from '@site/src/components/LiveEditorCompact';
1312
import { ExampleLink } from '@site/src/components/ExampleLink';
1413

15-
# Table
16-
1714
Synonyme: Data Table, Details List, Data Grid
1815

1916
<kol-alert _type="warning" _variant="card">
20-
<kol-badge _color="#fb4509" _label="Deprecated"></kol-badge>KolTable ist veraltet, bitte stattdessen <kol-link _label="KolTableStateful" _href="https://github.com/public-ui/kolibri/blob/develop/packages/components/src/components/table-stateful/readme.md"></kol-link> verwenden, die API und Funktionalität sind identisch.
17+
<kol-badge _color="#fb4509" _label="Deprecated"></kol-badge> KolTable ist veraltet, bitte stattdessen <kol-link _label="KolTableStateful" _href="table-stateful"></kol-link> verwenden, die API und Funktionalität sind identisch.
2118
</kol-alert>
2219

2320
Die **Table**-Komponente dient primär der übersichtlichen Darstellung von Datenmengen. Dabei ist sie so ausgelegt, dass sie alle von den Daten abhängige Werte automatisch ermittelt und die Tabelle entsprechend darstellt. Hierzu gehören beispielsweise die optionalen Funktionalitäten Spaltensortierung oder Pagination.
@@ -51,7 +48,7 @@ Die Table-Komponente unterstützt folgende Funktionalitäten **nicht**:
5148
5249
### Pagination
5350

54-
Über das Attribut **`_pagination`** kann optional eine Vielzahl zusätzlicher Properties zur Steuerung der Pagination übergeben werden. Die genaue Beschreibung der Optionen ist auf der Seite <kol-link _href="../components/pagination" _label="/docs/components/pagination" _label="Pagination"></kol-link> zu finden.
51+
Über das Attribut **`_pagination`** kann optional eine Vielzahl zusätzlicher Properties zur Steuerung der Pagination übergeben werden. Die genaue Beschreibung der Optionen ist auf der Seite <kol-link _href="pagination" _label="/docs/components/pagination" _label="Pagination"></kol-link> zu finden.
5552

5653
#### KoliBriTableHeaders
5754

@@ -189,8 +186,6 @@ Warum die Tabelle einen **Tabindex** hat, wird auf der folgenden Webseite beschr
189186
- <kol-link _href="https://stackoverflow.com/questions/1312236/" _target="_blank"></kol-link>
190187
- <kol-link _href="https://dequeuniversity.com/rules/axe/3.5/scrollable-region-focusable" _target="_blank"></kol-link>
191188

192-
<Readme />
193-
194189
<ExampleLink component="table" />
195190

196191
## Live-Editor

‎docs/30-components/tooltip.mdx

Lines changed: 0 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,6 @@ tags:
77
- Spezifikation
88
---
99

10-
import Readme from '../../readmes/tooltip/readme.md';
11-
1210
# Tooltip
1311

1412
Synonyme: Inline Dialog, Popover
@@ -43,5 +41,3 @@ Um die Breite eines Tooltips zu konfigurieren, kann auf dem umgebenden Container
4341
## Links und Referenzen
4442

4543
- <kol-link _href="https://tollwerk.de/projekte/tipps-techniken-inklusiv-barrierefrei/titel-tooltips-toggletips" _target="_blank"></kol-link>
46-
47-
<Readme />

0 commit comments

Comments
 (0)