Skip to content

Commit 350112e

Browse files
Lukas742Lukas742
committed
docs(AnalyticalTable): add JSDoc comments, enhance story
1 parent d440b59 commit 350112e

File tree

5 files changed

+187
-6
lines changed

5 files changed

+187
-6
lines changed

‎packages/main/src/components/AnalyticalTable/AnalyticalTable.stories.mdx

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -194,6 +194,8 @@ import { DocsCommonProps } from '@shared/stories/DocsCommonProps';
194194
| `disableGroupBy` | `boolean` | Disable groupBy for this column |
195195
| `defaultCanSort` | `boolean` | If set to true, this column will be sortable, regardless if it has a valid `accessor` |
196196
| `disableSortBy` | `boolean` | Disable sorting for this column |
197+
| `sortDescFirst` | `boolean` | If set to `true`, the first sort direction for this column will be descending instead of ascending. |
198+
| `sortInverted` | `boolean` | If set to `true`, the underlying sorting direction will be inverted, but the UI will not. |
197199
| `sortType` | `string OR ((rowA, rowB, columnId: string, descending: boolean) => any)` | String or custom sort function.<br />Supported String Values: <ul><li>`basic`</li><li>`datetime`</li><li>`alphanumeric`</li></ul> |
198200
| `disableResizing` | `boolean` | Disable resizing for this column |
199201
| `hAlign` | `TextAlign` | Horizontal align of the cell |

‎packages/main/src/components/AnalyticalTable/index.tsx

Lines changed: 95 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -66,13 +66,17 @@ interface DivWithCustomScrollProp extends HTMLDivElement {
6666

6767
export interface TableProps extends Omit<CommonProps, 'title'> {
6868
/**
69-
* Please look at the [AnalyticalTableColumnDefinition interface](#column-properties) for a full list of options.
69+
* Defines the columns array where you can define the configuration for each column.<br />
70+
* __Note:__ Please look at the [AnalyticalTableColumnDefinition interface](#column-properties) for a full list of options.
7071
*/
7172
columns: AnalyticalTableColumnDefinition[];
73+
/**
74+
* The data array that you want to display on the table.
75+
*/
7276
data: Record<any, any>[];
73-
7477
/**
75-
* Component or text of title section of the Table (if not set it will be hidden)
78+
* Component or text rendered in the title section of the `AnalyticalTable`.
79+
* __Note:__ If not set, it will be hidden.
7680
*/
7781
title?: ReactText | ReactNode;
7882
/**
@@ -81,12 +85,32 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
8185
extension?: ReactNode;
8286

8387
// appearance
84-
88+
/**
89+
* The minimum number of rows that are displayed. If the data contains less entries than `minRows`, it will be filled with empty rows.
90+
*/
8591
minRows?: number;
92+
/**
93+
* The number of rows visible without going into overflow.
94+
* __Note:__ If the data contains more entries than the `visibleRow` count, a vertical scrollbar is rendered and the table goes into overflow.
95+
*/
8696
visibleRows?: number;
97+
/**
98+
* Indicates whether a loading indicator should be shown.
99+
* __Note:__ If the data array is not empty and loading is set to `true` a `Loader` will be displayed underneath the header, otherwise a loading placeholder will be shown.
100+
* You can use your own placeholder by passing it to the `LoadingComponent` prop.
101+
*/
87102
loading?: boolean;
103+
/**
104+
* Defines the text shown if the data array is empty. If not set "No data" will be displayed.
105+
*/
88106
noDataText?: string;
107+
/**
108+
* Defines the height of the rows and header.
109+
*/
89110
rowHeight?: number;
111+
/**
112+
* Defines whether the table should display rows with alternating row colors.
113+
*/
90114
alternateRowColor?: boolean;
91115
/**
92116
* Flag whether the table should add an extra column for displaying row highlights, based on the `highlightField` prop.
@@ -103,11 +127,35 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
103127
highlightField?: string | ((row: Record<any, any>) => ValueState);
104128

105129
// features
130+
/**
131+
* Defines whether columns are filterable.
132+
*/
106133
filterable?: boolean;
134+
/**
135+
* Defines whether columns are sortable.
136+
*/
107137
sortable?: boolean;
138+
/**
139+
* Defines whether columns are groupable.
140+
*/
108141
groupable?: boolean;
142+
/**
143+
* Group table rows by adding the column's `accessor` or `id` to the array.
144+
*/
109145
groupBy?: string[];
146+
/**
147+
* Defines the selection behavior of the table. <br />
148+
* __"Row":__ A selection column is rendered along with the normal columns. The whole row is selectable.
149+
* __"RowOnly":__ No selection column is rendered along with the normal columns. The whole row is selectable.
150+
* __"RowSelector":__ The row is only selectable by clicking on the corresponding field in the selection column.
151+
*/
110152
selectionBehavior?: TableSelectionBehavior;
153+
/**
154+
* Defines the `SelectionMode` of the table.<br />
155+
* __"None":__ The rows are not selectable.
156+
* __"SingleSelect":__ You can select only one row at once. Clicking on another row will unselect the previously selected row.
157+
* __"MultiSelect":__ You can select multiple rows.
158+
*/
111159
selectionMode?: TableSelectionMode;
112160
/**
113161
* Defines the column growing behaviour. Possible Values:
@@ -118,27 +166,64 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
118166
*
119167
*/
120168
scaleWidthMode?: TableScaleWidthMode;
169+
/**
170+
* Defines the columns order by their `accessor` or `id`.
171+
*/
121172
columnOrder?: string[];
173+
/**
174+
* Defines whether infinite scroll is active.
175+
*/
122176
infiniteScroll?: boolean;
177+
/**
178+
* Defines the infinite scroll threshold. When the threshold is reached, the `onLoadMore` event is fired.
179+
*/
123180
infiniteScrollThreshold?: number;
124181

125182
// events
183+
/**
184+
* Fired when the sorting of the rows changes.
185+
*/
126186
onSort?: (e: CustomEvent<{ column: unknown; sortDirection: string }>) => void;
187+
/**
188+
* Fired when the grouping of the rows changes.
189+
*/
127190
onGroup?: (e: CustomEvent<{ column: unknown; groupedColumns: string[] }>) => void;
191+
/**
192+
* Fired when a row is selected or unselected.
193+
*/
128194
onRowSelected?: (e?: CustomEvent<{ allRowsSelected?: boolean; row?: unknown; isSelected?: boolean }>) => any;
195+
/**
196+
* Fired when a row is expanded or collapsed
197+
*/
129198
onRowExpandChange?: (e?: CustomEvent<{ row: unknown; column: unknown }>) => any;
199+
/**
200+
* Fired when the columns order is changed.
201+
*/
130202
onColumnsReordered?: (e?: CustomEvent<{ columnsNewOrder: string[]; column: unknown }>) => void;
203+
/**
204+
* Fired when the `infiniteScrollThreshold` is reached.
205+
*/
131206
onLoadMore?: (e?: { detail: { rowCount: number } }) => void;
132207
/**
133208
* Additional options which will be passed to [react-table´s useTable hook](https://react-table.tanstack.com/docs/api/useTable#table-options)
134209
*/
135210
reactTableOptions?: Record<string, unknown>;
211+
/**
212+
* You can use this prob to add custom hooks to the table.
213+
*/
136214
tableHooks?: PluginHook<any>[];
215+
/**
216+
* Defines the key for nested rows. <br />
217+
* Default: "children"
218+
*/
137219
subRowsKey?: string;
138220
/**
139221
* The key must consist of a valid `rowId` like `{ 2: true }` or `{ '0.2.0': true }` for nested rows.
140222
*/
141223
selectedRowIds?: { [key: string]: boolean };
224+
/**
225+
* Defines whether the table should act as tree-table.
226+
*/
142227
isTreeTable?: boolean;
143228
/**
144229
* The amount of columns to load both behind and ahead of the current window range.
@@ -150,7 +235,13 @@ export interface TableProps extends Omit<CommonProps, 'title'> {
150235
overscanCount?: number;
151236

152237
// default components
238+
/**
239+
* Component that will be rendered when the table is not loading and has no data.
240+
*/
153241
NoDataComponent?: ComponentType<any>;
242+
/**
243+
* Component that will be rendered when the table is loading and has no data.
244+
*/
154245
LoadingComponent?: ComponentType<any>;
155246
}
156247

‎packages/main/src/enums/TableSelectionBehavior.ts

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
export enum TableSelectionBehavior {
2+
/**
3+
* A selection column is rendered along with the normal columns. The whole row is selectable.
4+
*/
25
ROW = 'Row',
6+
/**
7+
* No selection column is rendered along with the normal columns. The whole row is selectable.
8+
*/
39
ROW_ONLY = 'RowOnly',
10+
/**
11+
* The row is only selectable by clicking on the corresponding field in the selection column.
12+
*/
413
ROW_SELECTOR = 'RowSelector'
514
}

‎packages/main/src/enums/TableSelectionMode.ts

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,14 @@
11
export enum TableSelectionMode {
2+
/**
3+
* The rows are not selectable.
4+
*/
25
NONE = 'None',
6+
/**
7+
* Only a single row is selectable. Clicking on another row will unselect the previously selected row.
8+
*/
39
SINGLE_SELECT = 'SingleSelect',
10+
/**
11+
* Multiple rows are selectable.
12+
*/
413
MULTI_SELECT = 'MultiSelect'
514
}

‎packages/main/src/interfaces/AnalyticalTableColumnDefinition.ts

Lines changed: 72 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,43 +4,113 @@ import { ComponentType } from 'react';
44

55
export interface AnalyticalTableColumnDefinition {
66
// base properties
7+
/**
8+
* This `string`/`function` is used to build the data model for your column. <br />
9+
* __Note__: You can also specify deeply nested values with accessors like `info.hobby` or even `address[0].street
10+
*/
711
accessor: string | ((row: any, rowIndex: number) => any);
812
/**
9-
* Required if accessor is a function
13+
* Defines the unique ID for the column. It is used by reference in things like sorting, grouping, filtering etc.
14+
* __Note__: Required if `accessor` is a function, otherwise `accessor` will overwrite the id.
1015
*/
1116
id?: string;
12-
17+
/**
18+
* Can either be string or a React component that will be rendered as column header
19+
*/
1320
Header?: string | ComponentType<any>;
21+
/**
22+
* Tooltip for the column header. If not set, the display text will be the same as the Header if it is a `string`.
23+
*/
1424
headerTooltip?: string;
25+
/**
26+
* Custom cell renderer. If set, the table will call that component for every cell and pass all required information as props, e.g. the cell value as `props.cell.value`
27+
*/
1528
Cell?: string | ComponentType<any>;
29+
/**
30+
* Cell width, if not set the table will distribute all columns without a width evenly.
31+
*/
1632
width?: number;
33+
/**
34+
* Minimum width of the column, e.g. used for resizing.
35+
*/
1736
minWidth?: number;
37+
/**
38+
* Maximum with of the column, e.g. used for resizing.
39+
*/
1840
maxWidth?: number;
1941

2042
// useFilters
43+
/**
44+
* Filter Component to be rendered in the Header.
45+
*/
2146
Filter?: string | ComponentType<any>;
47+
/**
48+
* Disable filters for this column.
49+
*/
2250
disableFilters?: boolean;
51+
/**
52+
* If set to true, this column will be filterable, regardless if it has a valid `accessor`.
53+
*/
2354
defaultCanFilter?: boolean;
55+
/**
56+
* Either a string or a filter function.<br />Supported String Values: <ul><li>`text`</li><li>`exactText`</li><li>`exactTextCase`</li><li>`equals`</li></ul>
57+
*/
2458
filter?: string | Function;
2559

2660
// useGroupBy
61+
/**
62+
* Component to render for aggregated cells.
63+
*/
2764
Aggregated?: string | ComponentType<any>;
65+
/**
66+
* Aggregation function or string.<br />Supported String Values: <ul><li>`min`</li><li>`max`</li><li>`median`</li><li>`count`</li></ul>
67+
*/
2868
aggregate?: string | ((leafValues, aggregatedValues) => any);
69+
/**
70+
* When attempting to group/aggregate non primitive cell values (eg. arrays of items) you will likely need to resolve a stable primitive value like a number or string to use in normal row aggregations. This property can be used to aggregate or simply access the value to be used in aggregations eg. count-ing the unique number of items in a cell's array value before sum-ing that count across the table.
71+
*/
2972
aggregateValue?: string | ((values, row, column) => any);
73+
/**
74+
* Disable groupBy for this column.
75+
*/
3076
disableGroupBy?: boolean;
3177

3278
// useSortBy
79+
/**
80+
* If set to true, this column will be sortable, regardless if it has a valid `accessor`.
81+
*/
3382
defaultCanSort?: boolean;
83+
/**
84+
* Disable sorting for this column.
85+
*/
3486
disableSortBy?: boolean;
87+
/**
88+
* If set to `true`, the first sort direction for this column will be descending instead of ascending.
89+
*/
3590
sortDescFirst?: boolean;
91+
/**
92+
* If set to `true`, the underlying sorting direction will be inverted, but the UI will not.
93+
*/
3694
sortInverted?: boolean;
95+
/**
96+
* String or custom sort function.<br />Supported String Values: <ul><li>`basic`</li><li>`datetime`</li><li>`alphanumeric`</li></ul>
97+
*/
3798
sortType?: string | ((rowA, rowB, columnId: string, descending: boolean) => any);
3899

39100
// useResizeColumns
101+
/**
102+
* Disable resizing for this column.
103+
*/
40104
disableResizing?: boolean;
41105

42106
// ui5 web components react properties
107+
/**
108+
* Horizontal alignment of the cell.
109+
*/
43110
hAlign?: TextAlign;
111+
/**
112+
* Vertical alignment of the cell.
113+
*/
44114
vAlign?: VerticalAlign;
45115

46116
[key: string]: any;

0 commit comments

Comments
 (0)