@mrcaktuz/sds-react 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +591 -105
- package/dist/grid.cjs +282 -15632
- package/dist/grid.d.cts +43 -28
- package/dist/grid.d.ts +43 -28
- package/dist/grid.js +297 -15618
- package/dist/index.d.cts +4 -4
- package/dist/index.d.ts +4 -4
- package/package.json +7 -11
package/README.md
CHANGED
|
@@ -3,9 +3,10 @@
|
|
|
3
3
|
Synerglass Design System — React components, styled on import.
|
|
4
4
|
Usable in a React project (Vite, Next.js) and in a **Vaadin Flow** application through React adapters (see [Usage in Vaadin](#usage-in-vaadin)).
|
|
5
5
|
|
|
6
|
-
> **Vaadin
|
|
7
|
-
>
|
|
8
|
-
>
|
|
6
|
+
> **Vaadin platform for this release: `25.3.5`**
|
|
7
|
+
> In a Vaadin application, set `<vaadin.version>25.3.5</vaadin.version>` in the `pom.xml` (see [Versions](#versions)).
|
|
8
|
+
> Built and tested with `@vaadin/react-components` `25.3.5`, the npm version pinned by this platform.
|
|
9
|
+
> Peer dependency `~25.3.5`: later `25.3.x` patches are accepted.
|
|
9
10
|
|
|
10
11
|
## Installation
|
|
11
12
|
|
|
@@ -15,19 +16,23 @@ npm i @mrcaktuz/sds-react
|
|
|
15
16
|
|
|
16
17
|
Peer dependencies, provided by the host project:
|
|
17
18
|
|
|
18
|
-
| Package | Version | Needed for
|
|
19
|
-
| -------------------------- | --------- |
|
|
20
|
-
| `react`, `react-dom` | `^19` | Every component
|
|
21
|
-
| `@vaadin/react-components` | `~25.3.
|
|
19
|
+
| Package | Version | Needed for |
|
|
20
|
+
| -------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
21
|
+
| `react`, `react-dom` | `^19` | Every component |
|
|
22
|
+
| `@vaadin/react-components` | `~25.3.5` | The `/grid` entry only. In a Vaadin app, the version comes from the `pom.xml` |
|
|
22
23
|
|
|
23
24
|
npm (v7+) and pnpm install peer dependencies automatically; Yarn needs them added by hand.
|
|
24
25
|
|
|
26
|
+
**Outside of Vaadin** (Vite, Next.js), pin every `@vaadin/*` package to the same version with `overrides` (npm, pnpm) or `resolutions` (Yarn).
|
|
27
|
+
The Vaadin packages depend on each other with `~` ranges: without overrides, some resolve to a newer patch and two versions end up in the page.
|
|
28
|
+
A Vaadin application does not need this: Flow already pins them from the platform version.
|
|
29
|
+
|
|
25
30
|
## Entries
|
|
26
31
|
|
|
27
|
-
| Import
|
|
28
|
-
|
|
|
29
|
-
| `@mrcaktuz/sds-react`
|
|
30
|
-
| `@mrcaktuz/sds-react/grid`
|
|
32
|
+
| Import | Components | Server-side rendering |
|
|
33
|
+
| -------------------------- | ---------------------------------------- | --------------------- |
|
|
34
|
+
| `@mrcaktuz/sds-react` | `SDSButton`, `SDSInput`, `SDSPagination` | Safe |
|
|
35
|
+
| `@mrcaktuz/sds-react/grid` | `SDSGrid` and its columns (Vaadin based) | **Browser only** |
|
|
31
36
|
|
|
32
37
|
The Vaadin-based components register custom elements as soon as they are imported, which crashes in Node.js.
|
|
33
38
|
That is why they live in a separate entry: importing the main entry never loads Vaadin.
|
|
@@ -40,12 +45,12 @@ That is why they live in a separate entry: importing the main entry never loads
|
|
|
40
45
|
|
|
41
46
|
### Light / dark theme
|
|
42
47
|
|
|
43
|
-
| `<html>` tag
|
|
44
|
-
|
|
|
45
|
-
| no attribute
|
|
46
|
-
| `theme="dark"` or `data-theme="dark"`
|
|
47
|
-
| `theme="light"` or `data-theme="light"`
|
|
48
|
-
| `theme="dark compact"` (several values)
|
|
48
|
+
| `<html>` tag | Theme |
|
|
49
|
+
| --------------------------------------- | ---------------------- |
|
|
50
|
+
| no attribute | OS preference |
|
|
51
|
+
| `theme="dark"` or `data-theme="dark"` | dark, whatever the OS |
|
|
52
|
+
| `theme="light"` or `data-theme="light"` | light, whatever the OS |
|
|
53
|
+
| `theme="dark compact"` (several values) | dark |
|
|
49
54
|
|
|
50
55
|
`theme` is the attribute of the Vaadin Lumo theme: **when the Vaadin application switches to dark, the DS components follow**.
|
|
51
56
|
|
|
@@ -70,15 +75,15 @@ import { SDSButton } from '@mrcaktuz/sds-react';
|
|
|
70
75
|
<SDSButton variant="ghost" color="danger" icon={<TrashIcon />} iconOnly aria-label="Delete" />
|
|
71
76
|
```
|
|
72
77
|
|
|
73
|
-
| Prop | Type
|
|
74
|
-
| -------------- |
|
|
75
|
-
| `variant` | `"primary"` \| `"outline"` \| `"ghost"`
|
|
76
|
-
| `color` | `"brand"` \| `"gray"` \| `"success"` \| `"warning"` \| `"danger"` | `"brand"`
|
|
77
|
-
| `small` | `boolean`
|
|
78
|
-
| `icon` | `ReactNode`
|
|
79
|
-
| `iconPosition` | `"left"` \| `"right"`
|
|
80
|
-
| `iconOnly` | `boolean`
|
|
81
|
-
| other props | `<button>` attributes
|
|
78
|
+
| Prop | Type | Default | Description |
|
|
79
|
+
| -------------- | ----------------------------------------------------------------- | ----------- | ------------------------------------- |
|
|
80
|
+
| `variant` | `"primary"` \| `"outline"` \| `"ghost"` | `"primary"` | Visual variant |
|
|
81
|
+
| `color` | `"brand"` \| `"gray"` \| `"success"` \| `"warning"` \| `"danger"` | `"brand"` | Required with a non-default `variant` |
|
|
82
|
+
| `small` | `boolean` | `false` | Smaller padding |
|
|
83
|
+
| `icon` | `ReactNode` | — | SVG icon |
|
|
84
|
+
| `iconPosition` | `"left"` \| `"right"` | `"left"` | |
|
|
85
|
+
| `iconOnly` | `boolean` | `false` | Hides the text: set `aria-label` |
|
|
86
|
+
| other props | `<button>` attributes | — | `onClick`, `disabled`, `type`… |
|
|
82
87
|
|
|
83
88
|
Combinations outside of the design system are rejected at compile time.
|
|
84
89
|
|
|
@@ -96,17 +101,17 @@ import { SDSInput } from '@mrcaktuz/sds-react';
|
|
|
96
101
|
<SDSInput label="E-mail" status="error" message="Invalid address" />
|
|
97
102
|
```
|
|
98
103
|
|
|
99
|
-
| Prop | Type
|
|
100
|
-
| ------------- |
|
|
101
|
-
| `id` | `string`
|
|
102
|
-
| `type` | `"text"` \| `"email"` \| `"password"` \| `"number"` \| `"tel"` \| `"url"` \| `"search"` \| `"date"` | `"text"`
|
|
103
|
-
| `label` | `string`
|
|
104
|
-
| `placeholder` | `string`
|
|
105
|
-
| `value` | `string`
|
|
106
|
-
| `status` | `"default"` \| `"error"` \| `"success"`
|
|
107
|
-
| `message` | `string`
|
|
108
|
-
| `onChange` | `(value: string, event) => void`
|
|
109
|
-
| `onBlur` | `(value: string, event) => void`
|
|
104
|
+
| Prop | Type | Default | Description |
|
|
105
|
+
| ------------- | --------------------------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------- |
|
|
106
|
+
| `id` | `string` | generated | HTML id of the `<input>`, also links the label |
|
|
107
|
+
| `type` | `"text"` \| `"email"` \| `"password"` \| `"number"` \| `"tel"` \| `"url"` \| `"search"` \| `"date"` | `"text"` | |
|
|
108
|
+
| `label` | `string` | — | Not displayed when missing |
|
|
109
|
+
| `placeholder` | `string` | — | |
|
|
110
|
+
| `value` | `string` | `""` | Fills the field; every new value replaces its content |
|
|
111
|
+
| `status` | `"default"` \| `"error"` \| `"success"` | `"default"` | Border, icon and message colors |
|
|
112
|
+
| `message` | `string` | — | Shown only with the `error` and `success` statuses |
|
|
113
|
+
| `onChange` | `(value: string, event) => void` | — | On each keystroke |
|
|
114
|
+
| `onBlur` | `(value: string, event) => void` | — | When the field loses focus |
|
|
110
115
|
|
|
111
116
|
- The callbacks receive the value first: no need to read `event.target.value`.
|
|
112
117
|
- **No validation inside the component**: the host sets `status` and `message`.
|
|
@@ -120,16 +125,16 @@ import { SDSPagination } from '@mrcaktuz/sds-react';
|
|
|
120
125
|
<SDSPagination page={page} pageSize={15} totalItems={total} onPageChange={setPage} />
|
|
121
126
|
```
|
|
122
127
|
|
|
123
|
-
| Prop | Type
|
|
124
|
-
| ------------------ |
|
|
125
|
-
| `page` | `number`
|
|
126
|
-
| `pageSize` | `number`
|
|
127
|
-
| `totalItems` | `number`
|
|
128
|
-
| `onPageChange` | `(page: number) => void`
|
|
129
|
-
| `onPageSizeChange` | `(pageSize: number) => void`
|
|
130
|
-
| `showRowsPerPage` | `boolean`
|
|
131
|
-
| `pageSizeOptions` | `number[]`
|
|
132
|
-
| `resultsSummary` | `(from, to, total) => string`
|
|
128
|
+
| Prop | Type | Default | Description |
|
|
129
|
+
| ------------------ | ----------------------------- | ---------------- | --------------------------- |
|
|
130
|
+
| `page` | `number` | — | Current page, starting at 1 |
|
|
131
|
+
| `pageSize` | `number` | — | |
|
|
132
|
+
| `totalItems` | `number` | — | |
|
|
133
|
+
| `onPageChange` | `(page: number) => void` | — | |
|
|
134
|
+
| `onPageSizeChange` | `(pageSize: number) => void` | — | |
|
|
135
|
+
| `showRowsPerPage` | `boolean` | `true` | "Rows per page" selector |
|
|
136
|
+
| `pageSizeOptions` | `number[]` | `[15, 30, 50]` | |
|
|
137
|
+
| `resultsSummary` | `(from, to, total) => string` | `"1–15 sur 100"` | |
|
|
133
138
|
|
|
134
139
|
### SDSGrid (`/grid` entry)
|
|
135
140
|
|
|
@@ -144,36 +149,104 @@ import { SDSGrid, SDSGridColumn, SDSGridSortColumn } from '@mrcaktuz/sds-react/g
|
|
|
144
149
|
</SDSGrid>
|
|
145
150
|
```
|
|
146
151
|
|
|
147
|
-
| Prop
|
|
148
|
-
|
|
|
149
|
-
| `stripes`
|
|
150
|
-
| `columnBorders`
|
|
151
|
-
| `noBorder`
|
|
152
|
-
|
|
|
152
|
+
| Prop | Type | Default | Description |
|
|
153
|
+
| ----------------------- | --------------------------------- | ------- | ---------------------------------------------- |
|
|
154
|
+
| `stripes` | `boolean` | `false` | Background on every other row |
|
|
155
|
+
| `columnBorders` | `boolean` | `false` | Vertical borders between columns |
|
|
156
|
+
| `noBorder` | `boolean` | `false` | No outer border nor radius |
|
|
157
|
+
| `editOnClick` | `boolean` | `false` | Editable cells start editing on a single click |
|
|
158
|
+
| `onItemPropertyChanged` | `({ item, path, value }) => void` | — | An editable cell was changed |
|
|
159
|
+
| other props | Vaadin `GridProps` | — | `items`, `dataProvider`, `allRowsVisible`… |
|
|
153
160
|
|
|
154
161
|
Columns: `SDSGridColumn`, `SDSGridSortColumn`, `SDSGridFilterColumn`, `SDSGridSelectionColumn` (the Vaadin columns).
|
|
162
|
+
Header parts `SDSGridSorter` and `SDSGridFilter` (the Vaadin ones), for a column both sortable and filterable:
|
|
163
|
+
|
|
164
|
+
```tsx
|
|
165
|
+
const NameHeader = () => (
|
|
166
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sds-sp-4)' }}>
|
|
167
|
+
<SDSGridSorter path="name">Name</SDSGridSorter>
|
|
168
|
+
<SDSGridFilter path="name" />
|
|
169
|
+
</div>
|
|
170
|
+
);
|
|
171
|
+
|
|
172
|
+
<SDSGridColumn path="name" headerRenderer={NameHeader} />
|
|
173
|
+
```
|
|
174
|
+
|
|
155
175
|
The SDS theme is scoped to the `sds-grid` class: native Vaadin grids on the same screen keep their own style.
|
|
156
176
|
|
|
177
|
+
#### Inline editing
|
|
178
|
+
|
|
179
|
+
The cells can be edited in the grid, like the commercial Vaadin Grid Pro, on the free Vaadin Grid.
|
|
180
|
+
`SDSGridColumn`, `SDSGridSortColumn` and `SDSGridFilterColumn` take three more props:
|
|
181
|
+
|
|
182
|
+
```tsx
|
|
183
|
+
<SDSGrid<User> items={users} onItemPropertyChanged={({ item, path, value }) => save(item)}>
|
|
184
|
+
<SDSGridSortColumn path="name" header="Name" editable />
|
|
185
|
+
<SDSGridColumn path="email" header="E-mail" editable={(user) => user.role !== 'Admin'} />
|
|
186
|
+
<SDSGridColumn path="role" header="Role" editable editorType="select" editorOptions={roles} />
|
|
187
|
+
<SDSGridColumn path="active" header="Active" editable editorType="checkbox" />
|
|
188
|
+
</SDSGrid>
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
| Prop | Type | Default | Description |
|
|
192
|
+
| --------------- | ---------------------------------------------- | -------- | -------------------------------------------------------------------- |
|
|
193
|
+
| `editable` | `boolean \| (item) => boolean` | `false` | The cells can be edited; a function decides row by row. Needs `path` |
|
|
194
|
+
| `editorType` | `'text' \| 'number' \| 'checkbox' \| 'select'` | `'text'` | Editor shown in the cell |
|
|
195
|
+
| `editorOptions` | `(string \| { label, value })[]` | — | Choices of the `select` editor |
|
|
196
|
+
|
|
197
|
+
- **Start**: double-click, Enter or F2 on a focused cell (single click with `editOnClick`).
|
|
198
|
+
- **Save**: Enter, Tab, leaving the cell, or a choice in the select editor. **Cancel**: Escape.
|
|
199
|
+
- Like Grid Pro, the new value is written on the item (`item[path] = value`), then `onItemPropertyChanged` is
|
|
200
|
+
called (only when the value changed): save it there.
|
|
201
|
+
- A `renderer` on an editable column is used when the cell is not being edited.
|
|
202
|
+
- **`checkbox` columns** always show a box, with no edit mode: a click on the box (or Enter / F2 on the cell)
|
|
203
|
+
toggles the value and calls `onItemPropertyChanged` at once. On the rows where the cell is not editable
|
|
204
|
+
(or without `editable`), the box is read-only. A `renderer` is ignored.
|
|
205
|
+
|
|
206
|
+
#### Row selection
|
|
207
|
+
|
|
208
|
+
`SDSGridSelectionColumn` (the Vaadin one) adds a box per row, plus a "select all" box in the header with `items`
|
|
209
|
+
(not with a `dataProvider`). It does not change the items: read the selection with `onSelectedItemsChanged`.
|
|
210
|
+
|
|
211
|
+
```tsx
|
|
212
|
+
<SDSGrid<User> items={users} onSelectedItemsChanged={(event) => setSelected(event.detail.value)}>
|
|
213
|
+
<SDSGridSelectionColumn />
|
|
214
|
+
<SDSGridColumn path="name" header="Name" />
|
|
215
|
+
</SDSGrid>
|
|
216
|
+
```
|
|
217
|
+
|
|
157
218
|
## Usage in Vaadin
|
|
158
219
|
|
|
159
|
-
Vaadin Flow (
|
|
220
|
+
Vaadin Flow (25+, the examples use the Jackson 3 API of Vaadin 25) integrates React components with a `ReactAdapterElement` (TypeScript, in `src/main/frontend/`) and a `ReactAdapterComponent` (Java).
|
|
160
221
|
The DS publishes the React components; **the adapters and Java classes are written in the Vaadin project**.
|
|
161
222
|
|
|
162
223
|
### Versions
|
|
163
224
|
|
|
164
|
-
**The DS decides the Vaadin version**: each release of this package states the Vaadin
|
|
165
|
-
In a Vaadin application, the `pom.xml` sets the version of every `@vaadin/*` package: if it differs, the application version wins and the grid theme may break silently.
|
|
225
|
+
**The DS decides the Vaadin version**: each release of this package states the Vaadin platform it requires.
|
|
226
|
+
In a Vaadin application, the `pom.xml` sets the version of every `@vaadin/*` npm package: if it differs, the application version wins and the grid theme may break silently.
|
|
227
|
+
|
|
228
|
+
Two version numbers, not to be mixed up:
|
|
229
|
+
|
|
230
|
+
| Number | Where | For this release |
|
|
231
|
+
| ---------------------------------------------------- | --------------------------------- | ---------------- |
|
|
232
|
+
| **Vaadin platform** (Maven `com.vaadin:vaadin-bom`) | `vaadin.version` in the `pom.xml` | `25.3.5` |
|
|
233
|
+
| **Web components** (npm `@vaadin/react-components`…) | Peer dependency of this package | `25.3.5` |
|
|
234
|
+
|
|
235
|
+
The web components get their own patches on npm before a platform release includes them
|
|
236
|
+
(e.g. `@vaadin/react-components` `25.3.6` exists on npm, the `25.3.6` platform does not yet).
|
|
237
|
+
The DS always targets a **released platform** and the npm versions it pins
|
|
238
|
+
(see `versions.json` in [vaadin/platform](https://github.com/vaadin/platform), at the platform tag).
|
|
166
239
|
|
|
167
240
|
On each DS release, update both in **the same pull request**:
|
|
168
241
|
|
|
169
242
|
```xml
|
|
170
|
-
<vaadin.version>25.3.
|
|
243
|
+
<vaadin.version>25.3.5</vaadin.version> <!-- must match the DS release notes -->
|
|
171
244
|
```
|
|
172
245
|
|
|
173
246
|
```java
|
|
174
247
|
public final class SdsVersion {
|
|
175
248
|
public static final String PACKAGE = "@mrcaktuz/sds-react";
|
|
176
|
-
public static final String VERSION = "0.
|
|
249
|
+
public static final String VERSION = "0.2.0"; // the only line to change on each DS release
|
|
177
250
|
}
|
|
178
251
|
```
|
|
179
252
|
|
|
@@ -181,25 +254,26 @@ public final class SdsVersion {
|
|
|
181
254
|
|
|
182
255
|
- **Import everything from this package**, never `@vaadin/*` directly, and the grid from the `/grid` entry.
|
|
183
256
|
- **State and event names must be identical in TypeScript and Java**: a typo fails silently. The tables below are the contract.
|
|
184
|
-
- **Data goes through JSON**: `setState` values must be serializable (records, simple beans). One page at a time, not thousands of rows.
|
|
185
|
-
- **
|
|
186
|
-
-
|
|
257
|
+
- **Data goes through JSON**: `setState` values must be serializable (records, simple beans). One page at a time, not thousands of rows.
|
|
258
|
+
- **Java components in grid cells** only through component columns (`Column.component(...)`, see SDSGrid).
|
|
259
|
+
- **Free Vaadin components only** (no Grid Pro, Charts…). Inline cell editing is provided by `SDSGrid`.
|
|
260
|
+
- Custom element tags and events use the `sds-` prefix.
|
|
187
261
|
|
|
188
262
|
How the React props map to Vaadin:
|
|
189
263
|
|
|
190
|
-
| React prop
|
|
191
|
-
|
|
|
192
|
-
| Data (`label`, `value`, `status`, `items`…)
|
|
193
|
-
| Input (`onChange` of `SDSInput`)
|
|
194
|
-
| Actions (`onBlur`, `onClick`)
|
|
264
|
+
| React prop | Vaadin side |
|
|
265
|
+
| ------------------------------------------- | -------------------------------------------------------------- |
|
|
266
|
+
| Data (`label`, `value`, `status`, `items`…) | Synchronized state: `setState(...)` / `getState(...)` |
|
|
267
|
+
| Input (`onChange` of `SDSInput`) | `value` state updated → `addStateChangeListener("value", ...)` |
|
|
268
|
+
| Actions (`onBlur`, `onClick`) | Custom event → `getElement().addEventListener(...)` |
|
|
195
269
|
|
|
196
270
|
### SDSInput
|
|
197
271
|
|
|
198
|
-
| Tag
|
|
199
|
-
|
|
|
200
|
-
| `
|
|
272
|
+
| Tag | States | Events |
|
|
273
|
+
| ----------- | ----------------------------------------------------------------------- | ------------------------------ |
|
|
274
|
+
| `sds-input` | `inputId`, `value`, `label`, `placeholder`, `type`, `status`, `message` | `sds-blur` (detail: the value) |
|
|
201
275
|
|
|
202
|
-
`src/main/frontend/
|
|
276
|
+
`src/main/frontend/sds-input.tsx`:
|
|
203
277
|
|
|
204
278
|
```tsx
|
|
205
279
|
import type { ReactElement } from 'react';
|
|
@@ -215,7 +289,7 @@ class SynerDsInputElement extends ReactAdapterElement {
|
|
|
215
289
|
const [type] = hooks.useState<SDSInputType>('type');
|
|
216
290
|
const [status] = hooks.useState<SDSInputStatus>('status');
|
|
217
291
|
const [message] = hooks.useState<string>('message');
|
|
218
|
-
const dispatchBlur = hooks.useCustomEvent<string>('
|
|
292
|
+
const dispatchBlur = hooks.useCustomEvent<string>('sds-blur');
|
|
219
293
|
|
|
220
294
|
return (
|
|
221
295
|
<SDSInput
|
|
@@ -233,15 +307,22 @@ class SynerDsInputElement extends ReactAdapterElement {
|
|
|
233
307
|
}
|
|
234
308
|
}
|
|
235
309
|
|
|
236
|
-
customElements.define('
|
|
310
|
+
customElements.define('sds-input', SynerDsInputElement);
|
|
237
311
|
```
|
|
238
312
|
|
|
239
313
|
`SynerDsInput.java`:
|
|
240
314
|
|
|
241
315
|
```java
|
|
242
|
-
|
|
316
|
+
import java.util.function.Consumer;
|
|
317
|
+
|
|
318
|
+
import com.vaadin.flow.component.Tag;
|
|
319
|
+
import com.vaadin.flow.component.dependency.JsModule;
|
|
320
|
+
import com.vaadin.flow.component.dependency.NpmPackage;
|
|
321
|
+
import com.vaadin.flow.component.react.ReactAdapterComponent;
|
|
322
|
+
|
|
323
|
+
@Tag("sds-input")
|
|
243
324
|
@NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
|
|
244
|
-
@JsModule("./
|
|
325
|
+
@JsModule("./sds-input.tsx")
|
|
245
326
|
public class SynerDsInput extends ReactAdapterComponent {
|
|
246
327
|
|
|
247
328
|
public SynerDsInput(String label) {
|
|
@@ -267,7 +348,7 @@ public class SynerDsInput extends ReactAdapterComponent {
|
|
|
267
348
|
|
|
268
349
|
/** When the field loses focus */
|
|
269
350
|
public void addBlurListener(Consumer<String> listener) {
|
|
270
|
-
getElement().addEventListener("
|
|
351
|
+
getElement().addEventListener("sds-blur", e -> listener.accept(e.getEventData().get("event.detail").asString()))
|
|
271
352
|
.addEventData("event.detail");
|
|
272
353
|
}
|
|
273
354
|
}
|
|
@@ -275,11 +356,11 @@ public class SynerDsInput extends ReactAdapterComponent {
|
|
|
275
356
|
|
|
276
357
|
### SDSButton
|
|
277
358
|
|
|
278
|
-
| Tag
|
|
279
|
-
|
|
|
280
|
-
| `
|
|
359
|
+
| Tag | States | Events |
|
|
360
|
+
| ------------ | -------------------------------------- | ----------- |
|
|
361
|
+
| `sds-button` | `text`, `variant`, `color`, `disabled` | `sds-click` |
|
|
281
362
|
|
|
282
|
-
`src/main/frontend/
|
|
363
|
+
`src/main/frontend/sds-button.tsx`:
|
|
283
364
|
|
|
284
365
|
```tsx
|
|
285
366
|
import type { ReactElement } from 'react';
|
|
@@ -292,7 +373,7 @@ class SynerDsButtonElement extends ReactAdapterElement {
|
|
|
292
373
|
const [variant] = hooks.useState<string>('variant');
|
|
293
374
|
const [color] = hooks.useState<string>('color');
|
|
294
375
|
const [disabled] = hooks.useState<boolean>('disabled');
|
|
295
|
-
const dispatchClick = hooks.useCustomEvent<void>('
|
|
376
|
+
const dispatchClick = hooks.useCustomEvent<void>('sds-click');
|
|
296
377
|
|
|
297
378
|
// variant/color come from Java as strings: the allowed pairs are listed in the SDSButton table
|
|
298
379
|
const appearance = { variant: variant ?? 'primary', color: color ?? 'brand' } as SDSButtonProps;
|
|
@@ -305,15 +386,20 @@ class SynerDsButtonElement extends ReactAdapterElement {
|
|
|
305
386
|
}
|
|
306
387
|
}
|
|
307
388
|
|
|
308
|
-
customElements.define('
|
|
389
|
+
customElements.define('sds-button', SynerDsButtonElement);
|
|
309
390
|
```
|
|
310
391
|
|
|
311
392
|
`SynerDsButton.java`:
|
|
312
393
|
|
|
313
394
|
```java
|
|
314
|
-
|
|
395
|
+
import com.vaadin.flow.component.Tag;
|
|
396
|
+
import com.vaadin.flow.component.dependency.JsModule;
|
|
397
|
+
import com.vaadin.flow.component.dependency.NpmPackage;
|
|
398
|
+
import com.vaadin.flow.component.react.ReactAdapterComponent;
|
|
399
|
+
|
|
400
|
+
@Tag("sds-button")
|
|
315
401
|
@NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
|
|
316
|
-
@JsModule("./
|
|
402
|
+
@JsModule("./sds-button.tsx")
|
|
317
403
|
public class SynerDsButton extends ReactAdapterComponent {
|
|
318
404
|
|
|
319
405
|
public SynerDsButton(String text) {
|
|
@@ -329,61 +415,461 @@ public class SynerDsButton extends ReactAdapterComponent {
|
|
|
329
415
|
public void setDisabled(boolean disabled) { setState("disabled", disabled); }
|
|
330
416
|
|
|
331
417
|
public void addClickListener(Runnable listener) {
|
|
332
|
-
getElement().addEventListener("
|
|
418
|
+
getElement().addEventListener("sds-click", e -> listener.run());
|
|
333
419
|
}
|
|
334
420
|
}
|
|
335
421
|
```
|
|
336
422
|
|
|
337
423
|
### SDSGrid
|
|
338
424
|
|
|
339
|
-
| Tag
|
|
340
|
-
|
|
|
341
|
-
| `
|
|
425
|
+
| Tag | States | Events |
|
|
426
|
+
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
|
|
427
|
+
| `sds-grid` | `columns` (see below), `items` (objects), `editable` (boolean), `editOnClick` (boolean), `selectable` (boolean), `selectedRows` (indexes in `items`, also set by the browser) | `sds-item-changed` (detail: `{ item, path, value }`) |
|
|
428
|
+
|
|
429
|
+
`columns` entries:
|
|
342
430
|
|
|
343
|
-
|
|
431
|
+
| Field | Type | Description |
|
|
432
|
+
| --------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
433
|
+
| `path` | string | Property of the item shown in the column (JSON name, `address.city` for a nested property) |
|
|
434
|
+
| `header` | string | Column title |
|
|
435
|
+
| `readOnly` | boolean | The column is never editable, even in an editable grid |
|
|
436
|
+
| `readOnlyWhen` | string \| null | Name of a boolean property of the item: when `true`, the cell of this row is read-only |
|
|
437
|
+
| `editorType` | `text` \| `number` \| `checkbox` \| `select` \| null | Editor shown in the cell (`text` when null) |
|
|
438
|
+
| `editorOptions` | `{ label, value }[]` \| null | Choices of the `select` editor |
|
|
439
|
+
| `sortable` | boolean | Sort indicator in the header |
|
|
440
|
+
| `filterable` | boolean | Text field in the header that filters the rows |
|
|
441
|
+
| `component` | boolean | The cells hold Java components (`path` is then the key of the column, not a property) |
|
|
442
|
+
|
|
443
|
+
Content elements (Java components): `sds-cell-<row>-<path>`, `<row>` being the index of the item in `items`.
|
|
444
|
+
|
|
445
|
+
`src/main/frontend/sds-grid.tsx`:
|
|
344
446
|
|
|
345
447
|
```tsx
|
|
346
|
-
import type
|
|
448
|
+
import { type ReactElement, createContext, useContext, useLayoutEffect, useMemo, useRef } from 'react';
|
|
347
449
|
import { ReactAdapterElement, type RenderHooks } from 'Frontend/generated/flow/ReactAdapter';
|
|
348
|
-
import {
|
|
450
|
+
import {
|
|
451
|
+
SDSGrid,
|
|
452
|
+
SDSGridColumn,
|
|
453
|
+
SDSGridFilter,
|
|
454
|
+
SDSGridFilterColumn,
|
|
455
|
+
SDSGridSelectionColumn,
|
|
456
|
+
SDSGridSortColumn,
|
|
457
|
+
SDSGridSorter,
|
|
458
|
+
type SDSGridEditorOption,
|
|
459
|
+
type SDSGridEditorType,
|
|
460
|
+
} from '@mrcaktuz/sds-react/grid';
|
|
461
|
+
|
|
462
|
+
type Item = Record<string, unknown>;
|
|
463
|
+
type Column = {
|
|
464
|
+
path: string;
|
|
465
|
+
header: string;
|
|
466
|
+
readOnly?: boolean | null;
|
|
467
|
+
readOnlyWhen?: string | null;
|
|
468
|
+
editorType?: SDSGridEditorType | null;
|
|
469
|
+
editorOptions?: SDSGridEditorOption[] | null;
|
|
470
|
+
sortable?: boolean | null;
|
|
471
|
+
filterable?: boolean | null;
|
|
472
|
+
component?: boolean | null;
|
|
473
|
+
};
|
|
474
|
+
type ItemChange = { item: Item; path: string; value: unknown };
|
|
475
|
+
|
|
476
|
+
// Content element holding the Java components of a cell (same name in SynerDsGrid.java)
|
|
477
|
+
const cellName = (row: number, path: string) => `sds-cell-${row}-${path}`;
|
|
478
|
+
|
|
479
|
+
// Index of each item in the list sent by Java (unchanged when the grid sorts or filters)
|
|
480
|
+
const RowIndex = createContext(new Map<Item, number>());
|
|
481
|
+
|
|
482
|
+
// Flow binds a content element once, to its DOM node: the containers stay mounted in a hidden
|
|
483
|
+
// stash, and a cell borrows its container while the cell is displayed
|
|
484
|
+
function Slot({ name, useContent }: { name: string; useContent: RenderHooks['useContent'] }) {
|
|
485
|
+
return <span data-sds-slot={name}>{useContent(name)}</span>;
|
|
486
|
+
}
|
|
349
487
|
|
|
350
|
-
|
|
488
|
+
function ComponentCell({ item, original }: { item: Item; original: { path?: string | null } }) {
|
|
489
|
+
const row = useContext(RowIndex).get(item);
|
|
490
|
+
const name = row === undefined ? null : cellName(row, original.path ?? '');
|
|
491
|
+
const cell = useRef<HTMLSpanElement>(null);
|
|
492
|
+
|
|
493
|
+
useLayoutEffect(() => {
|
|
494
|
+
const element = cell.current;
|
|
495
|
+
const host = element?.closest('sds-grid');
|
|
496
|
+
const container = name && host?.querySelector(`flow-content-container[name="${name}"]`);
|
|
497
|
+
if (!element || !container) return;
|
|
498
|
+
element.append(container);
|
|
499
|
+
return () => {
|
|
500
|
+
// Back to the stash, unless another cell took it in the meantime
|
|
501
|
+
if (container.parentNode === element)
|
|
502
|
+
host?.querySelector(`[data-sds-slot="${name}"]`)?.append(container);
|
|
503
|
+
};
|
|
504
|
+
}, [name]);
|
|
505
|
+
|
|
506
|
+
return <span ref={cell} />;
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
// Header of a column both sortable and filterable
|
|
510
|
+
function SortFilterHeader({ original }: { original: { path?: string | null; header?: string | null } }) {
|
|
511
|
+
const path = original.path ?? undefined;
|
|
512
|
+
return (
|
|
513
|
+
<div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--sds-sp-4)' }}>
|
|
514
|
+
<SDSGridSorter path={path}>{original.header}</SDSGridSorter>
|
|
515
|
+
<SDSGridFilter path={path} />
|
|
516
|
+
</div>
|
|
517
|
+
);
|
|
518
|
+
}
|
|
351
519
|
|
|
352
520
|
class SynerDsGridElement extends ReactAdapterElement {
|
|
353
521
|
protected override render(hooks: RenderHooks): ReactElement | null {
|
|
354
522
|
const [columns] = hooks.useState<Column[]>('columns');
|
|
355
|
-
const [items] = hooks.useState<
|
|
523
|
+
const [items] = hooks.useState<Item[]>('items');
|
|
524
|
+
const [editable] = hooks.useState<boolean>('editable');
|
|
525
|
+
const [editOnClick] = hooks.useState<boolean>('editOnClick');
|
|
526
|
+
const [selectable] = hooks.useState<boolean>('selectable');
|
|
527
|
+
const [selectedRows, setSelectedRows] = hooks.useState<number[]>('selectedRows', []);
|
|
528
|
+
const dispatchItemChanged = hooks.useCustomEvent<ItemChange>('sds-item-changed');
|
|
529
|
+
|
|
530
|
+
const rowIndex = useMemo(() => new Map((items ?? []).map((item, row) => [item, row])), [items]);
|
|
531
|
+
const selectedItems = useMemo(
|
|
532
|
+
() => (selectedRows ?? []).map((row) => items?.[row]).filter((item) => item !== undefined),
|
|
533
|
+
[selectedRows, items]
|
|
534
|
+
);
|
|
535
|
+
const onSelectionChanged = (selection: Item[]) => {
|
|
536
|
+
const rows = selection
|
|
537
|
+
.map((item) => rowIndex.get(item))
|
|
538
|
+
.filter((row) => row !== undefined)
|
|
539
|
+
.sort((a, b) => a - b);
|
|
540
|
+
// The grid also fires when Java sets the selection: only send real changes
|
|
541
|
+
if (rows.join() !== (selectedRows ?? []).join()) setSelectedRows(rows);
|
|
542
|
+
};
|
|
543
|
+
// Containers are never removed: Flow would not bind a container mounted again
|
|
544
|
+
const slots = useRef(new Set<string>()).current;
|
|
545
|
+
for (const c of columns ?? []) {
|
|
546
|
+
if (c.component) (items ?? []).forEach((_, row) => slots.add(cellName(row, c.path)));
|
|
547
|
+
}
|
|
356
548
|
|
|
357
549
|
return (
|
|
358
|
-
<
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
550
|
+
<RowIndex.Provider value={rowIndex}>
|
|
551
|
+
<div hidden>
|
|
552
|
+
{[...slots].map((name) => (
|
|
553
|
+
<Slot key={name} name={name} useContent={hooks.useContent} />
|
|
554
|
+
))}
|
|
555
|
+
</div>
|
|
556
|
+
<SDSGrid<Item>
|
|
557
|
+
items={items ?? []}
|
|
558
|
+
allRowsVisible
|
|
559
|
+
editOnClick={editOnClick ?? false}
|
|
560
|
+
onItemPropertyChanged={(change) => dispatchItemChanged(change)}
|
|
561
|
+
selectedItems={selectedItems}
|
|
562
|
+
onSelectedItemsChanged={(event) => onSelectionChanged(event.detail.value)}
|
|
563
|
+
>
|
|
564
|
+
{selectable && <SDSGridSelectionColumn />}
|
|
565
|
+
{(columns ?? []).map((c) => {
|
|
566
|
+
if (c.component) {
|
|
567
|
+
return <SDSGridColumn<Item> key={c.path} header={c.header} renderer={ComponentCell} />;
|
|
568
|
+
}
|
|
569
|
+
const props = {
|
|
570
|
+
path: c.path,
|
|
571
|
+
header: c.header,
|
|
572
|
+
editable:
|
|
573
|
+
editable && !c.readOnly
|
|
574
|
+
? (item: Item) => !(c.readOnlyWhen && item[c.readOnlyWhen])
|
|
575
|
+
: false,
|
|
576
|
+
// Java sends null for the unset fields: the SDS defaults only apply to undefined
|
|
577
|
+
editorType: c.editorType ?? undefined,
|
|
578
|
+
editorOptions: c.editorOptions ?? undefined,
|
|
579
|
+
};
|
|
580
|
+
if (c.sortable && c.filterable) {
|
|
581
|
+
return <SDSGridColumn<Item> key={c.path} {...props} headerRenderer={SortFilterHeader} />;
|
|
582
|
+
}
|
|
583
|
+
if (c.sortable) return <SDSGridSortColumn<Item> key={c.path} {...props} />;
|
|
584
|
+
if (c.filterable) return <SDSGridFilterColumn<Item> key={c.path} {...props} />;
|
|
585
|
+
return <SDSGridColumn<Item> key={c.path} {...props} />;
|
|
586
|
+
})}
|
|
587
|
+
</SDSGrid>
|
|
588
|
+
</RowIndex.Provider>
|
|
363
589
|
);
|
|
364
590
|
}
|
|
365
591
|
}
|
|
366
592
|
|
|
367
|
-
customElements.define('
|
|
593
|
+
customElements.define('sds-grid', SynerDsGridElement);
|
|
368
594
|
```
|
|
369
595
|
|
|
370
596
|
`SynerDsGrid.java`:
|
|
371
597
|
|
|
372
598
|
```java
|
|
373
|
-
|
|
599
|
+
import java.util.ArrayList;
|
|
600
|
+
import java.util.Arrays;
|
|
601
|
+
import java.util.List;
|
|
602
|
+
|
|
603
|
+
import com.fasterxml.jackson.annotation.JsonIgnore; // Jackson 3 keeps the annotations in this package
|
|
604
|
+
import com.fasterxml.jackson.annotation.JsonProperty;
|
|
605
|
+
import com.vaadin.flow.component.Component;
|
|
606
|
+
import com.vaadin.flow.component.Tag;
|
|
607
|
+
import com.vaadin.flow.component.dependency.JsModule;
|
|
608
|
+
import com.vaadin.flow.component.dependency.NpmPackage;
|
|
609
|
+
import com.vaadin.flow.component.react.ReactAdapterComponent;
|
|
610
|
+
import com.vaadin.flow.dom.Element;
|
|
611
|
+
import com.vaadin.flow.function.SerializableConsumer;
|
|
612
|
+
import com.vaadin.flow.function.SerializableFunction;
|
|
613
|
+
import com.vaadin.flow.shared.Registration;
|
|
614
|
+
import tools.jackson.databind.JsonNode; // Vaadin 25: Jackson 3
|
|
615
|
+
|
|
616
|
+
@Tag("sds-grid")
|
|
374
617
|
@NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
|
|
375
|
-
@JsModule("./
|
|
618
|
+
@JsModule("./sds-grid.tsx")
|
|
376
619
|
public class SynerDsGrid<T> extends ReactAdapterComponent {
|
|
377
|
-
public record Column(String path, String header) {}
|
|
378
620
|
|
|
379
|
-
|
|
380
|
-
public
|
|
621
|
+
/** A column: editable when the grid is editable, unless created with {@link #readOnly} or {@link #component}. */
|
|
622
|
+
public record Column(String path, String header, boolean readOnly, String readOnlyWhen,
|
|
623
|
+
String editorType, List<Option> editorOptions, boolean sortable, boolean filterable,
|
|
624
|
+
@JsonIgnore SerializableFunction<?, ? extends Component> renderer) {
|
|
625
|
+
|
|
626
|
+
public static Column text(String path, String header) { return of(path, header, "text", null); }
|
|
627
|
+
public static Column number(String path, String header) { return of(path, header, "number", null); }
|
|
628
|
+
public static Column checkbox(String path, String header) { return of(path, header, "checkbox", null); }
|
|
629
|
+
public static Column select(String path, String header, List<Option> options) {
|
|
630
|
+
return of(path, header, "select", options);
|
|
631
|
+
}
|
|
632
|
+
/** Never editable */
|
|
633
|
+
public static Column readOnly(String path, String header) {
|
|
634
|
+
return new Column(path, header, true, null, null, null, false, false, null);
|
|
635
|
+
}
|
|
636
|
+
/** Boolean property shown as read-only boxes, even in an editable grid */
|
|
637
|
+
public static Column readOnlyCheckbox(String path, String header) {
|
|
638
|
+
return new Column(path, header, true, null, "checkbox", null, false, false, null);
|
|
639
|
+
}
|
|
640
|
+
/**
|
|
641
|
+
* Cells holding Java components, built by {@code renderer} for each row (button, badge, layout…).
|
|
642
|
+
* {@code key}: unique name of the column (not a property of the item). Never editable, sortable nor filterable.
|
|
643
|
+
*/
|
|
644
|
+
public static <T> Column component(String key, String header,
|
|
645
|
+
SerializableFunction<T, ? extends Component> renderer) {
|
|
646
|
+
return new Column(key, header, true, null, null, null, false, false, renderer);
|
|
647
|
+
}
|
|
648
|
+
|
|
649
|
+
private static Column of(String path, String header, String editorType, List<Option> options) {
|
|
650
|
+
return new Column(path, header, false, null, editorType, options, false, false, null);
|
|
651
|
+
}
|
|
652
|
+
|
|
653
|
+
/** Same column, read-only on the rows where the boolean property {@code property} of the item is true */
|
|
654
|
+
public Column readOnlyWhen(String property) {
|
|
655
|
+
return new Column(path, header, readOnly, property, editorType, editorOptions, sortable, filterable, renderer);
|
|
656
|
+
}
|
|
657
|
+
/** Same column, sorted by a click on its header (ascending, descending, none) */
|
|
658
|
+
public Column sortable() {
|
|
659
|
+
return new Column(path, header, readOnly, readOnlyWhen, editorType, editorOptions, true, filterable, renderer);
|
|
660
|
+
}
|
|
661
|
+
/** Same column, with a text field in its header that filters the rows (contains, case-insensitive) */
|
|
662
|
+
public Column filterable() {
|
|
663
|
+
return new Column(path, header, readOnly, readOnlyWhen, editorType, editorOptions, sortable, true, renderer);
|
|
664
|
+
}
|
|
665
|
+
|
|
666
|
+
/** Sent to the browser instead of the renderer */
|
|
667
|
+
@JsonProperty("component")
|
|
668
|
+
public boolean isComponent() { return renderer != null; }
|
|
669
|
+
}
|
|
670
|
+
|
|
671
|
+
/** A choice of a select column: {@code value} is stored in the item, {@code label} is displayed */
|
|
672
|
+
public record Option(String label, String value) {
|
|
673
|
+
public static List<Option> of(String... values) {
|
|
674
|
+
return Arrays.stream(values).map(v -> new Option(v, v)).toList();
|
|
675
|
+
}
|
|
676
|
+
}
|
|
677
|
+
|
|
678
|
+
/** A validated cell edit: {@code item} already holds the new value */
|
|
679
|
+
public record ItemChange<T>(T item, String path, JsonNode value) {}
|
|
680
|
+
|
|
681
|
+
private final Class<T> itemType;
|
|
682
|
+
private List<Column> columns = List.of();
|
|
683
|
+
private List<T> items = List.of();
|
|
684
|
+
private final List<Element> filledCells = new ArrayList<>();
|
|
685
|
+
|
|
686
|
+
public SynerDsGrid(Class<T> itemType) { this.itemType = itemType; }
|
|
687
|
+
|
|
688
|
+
public void setColumns(List<Column> columns) {
|
|
689
|
+
this.columns = columns;
|
|
690
|
+
setState("columns", columns);
|
|
691
|
+
renderComponents();
|
|
692
|
+
}
|
|
693
|
+
|
|
694
|
+
/** Replaces the rows and clears the selection */
|
|
695
|
+
public void setItems(List<T> items) {
|
|
696
|
+
this.items = items;
|
|
697
|
+
setState("items", items);
|
|
698
|
+
setState("selectedRows", new int[0]);
|
|
699
|
+
renderComponents();
|
|
700
|
+
}
|
|
701
|
+
|
|
702
|
+
/** Turns inline editing on or off for the whole grid (off by default) */
|
|
703
|
+
public void setEditable(boolean editable) { setState("editable", editable); }
|
|
704
|
+
/** Editing starts on a single click instead of a double-click */
|
|
705
|
+
public void setEditOnClick(boolean editOnClick) { setState("editOnClick", editOnClick); }
|
|
706
|
+
|
|
707
|
+
/** Adds a first column of boxes to select rows, with a "select all" box in its header (off by default) */
|
|
708
|
+
public void setSelectable(boolean selectable) { setState("selectable", selectable); }
|
|
709
|
+
/** Selected rows (objects of the list given to {@link #setItems}), in the order of that list */
|
|
710
|
+
public List<T> getSelectedItems() { return toItems(getState("selectedRows", int[].class)); }
|
|
711
|
+
public void deselectAll() { setState("selectedRows", new int[0]); }
|
|
712
|
+
|
|
713
|
+
/** Called each time the user changes the selection */
|
|
714
|
+
public Registration addSelectionListener(SerializableConsumer<List<T>> listener) {
|
|
715
|
+
return addStateChangeListener("selectedRows", int[].class, rows -> listener.accept(toItems(rows)));
|
|
716
|
+
}
|
|
717
|
+
|
|
718
|
+
private List<T> toItems(int[] rows) {
|
|
719
|
+
if (rows == null) return List.of();
|
|
720
|
+
return Arrays.stream(rows).filter(row -> row < items.size()).mapToObj(items::get).toList();
|
|
721
|
+
}
|
|
722
|
+
|
|
723
|
+
/** Called each time a cell edit is validated with a new value */
|
|
724
|
+
public Registration addItemChangeListener(SerializableConsumer<ItemChange<T>> listener) {
|
|
725
|
+
return getElement().addEventListener("sds-item-changed", e -> {
|
|
726
|
+
JsonNode change = e.getEventData().get("event.detail");
|
|
727
|
+
listener.accept(new ItemChange<>(
|
|
728
|
+
readFromJson(change.get("item"), itemType),
|
|
729
|
+
change.get("path").asString(),
|
|
730
|
+
change.get("value")));
|
|
731
|
+
}).addEventData("event.detail");
|
|
732
|
+
}
|
|
733
|
+
|
|
734
|
+
/** Builds the components of the component columns, one per row, in place of the previous ones */
|
|
735
|
+
@SuppressWarnings("unchecked")
|
|
736
|
+
private void renderComponents() {
|
|
737
|
+
filledCells.forEach(Element::removeAllChildren);
|
|
738
|
+
filledCells.clear();
|
|
739
|
+
for (Column column : columns) {
|
|
740
|
+
if (column.renderer() == null) continue;
|
|
741
|
+
var renderer = (SerializableFunction<T, ? extends Component>) column.renderer();
|
|
742
|
+
for (int row = 0; row < items.size(); row++) {
|
|
743
|
+
Element cell = getContentElement("sds-cell-" + row + "-" + column.path()); // name used in sds-grid.tsx
|
|
744
|
+
cell.appendChild(renderer.apply(items.get(row)).getElement());
|
|
745
|
+
filledCells.add(cell);
|
|
746
|
+
}
|
|
747
|
+
}
|
|
748
|
+
}
|
|
381
749
|
}
|
|
382
750
|
```
|
|
383
751
|
|
|
752
|
+
#### Inline editing in Vaadin
|
|
753
|
+
|
|
754
|
+
1. **Editable grid or not**: `grid.setEditable(true)`. Without it (default), the grid is read-only, whatever the columns.
|
|
755
|
+
2. **Non-editable cells**:
|
|
756
|
+
- a whole column: `Column.readOnly("id", "ID")`,
|
|
757
|
+
- some rows only: `.readOnlyWhen("admin")` on the column. `admin` is a boolean property of the item, sent in the JSON
|
|
758
|
+
(field / getter of `T`, or record component). When it is `true`, the cell of that row is read-only.
|
|
759
|
+
To lock a whole row, put the same `readOnlyWhen` on every column.
|
|
760
|
+
3. **Get the new value**: `grid.addItemChangeListener(change -> ...)`, called once per validated edit, only when the value changed.
|
|
761
|
+
- `change.item()`: the row as a `T`, **with the new value already applied**: save it as is.
|
|
762
|
+
- `change.path()`: the edited property (the `path` of the column).
|
|
763
|
+
- `change.value()`: the new value as JSON (`asString()`, `asInt()`, `asBoolean()`…), when only that field is needed.
|
|
764
|
+
|
|
765
|
+
```java
|
|
766
|
+
SynerDsGrid<Person> grid = new SynerDsGrid<>(Person.class);
|
|
767
|
+
grid.setEditable(true);
|
|
768
|
+
grid.setColumns(List.of(
|
|
769
|
+
Column.readOnly("id", "ID"),
|
|
770
|
+
Column.text("name", "Name"),
|
|
771
|
+
Column.text("email", "E-mail").readOnlyWhen("admin"), // admins' e-mails are locked
|
|
772
|
+
Column.select("role", "Role", Option.of("Admin", "User", "Guest")),
|
|
773
|
+
Column.checkbox("active", "Active")));
|
|
774
|
+
grid.setItems(personService.findPage(0, 15));
|
|
775
|
+
|
|
776
|
+
grid.addItemChangeListener(change -> {
|
|
777
|
+
try {
|
|
778
|
+
personService.save(change.item());
|
|
779
|
+
} catch (ValidationException ex) {
|
|
780
|
+
Notification.show(ex.getMessage());
|
|
781
|
+
grid.setItems(personService.findPage(0, 15)); // back to the stored values
|
|
782
|
+
}
|
|
783
|
+
});
|
|
784
|
+
```
|
|
785
|
+
|
|
786
|
+
How it works for the user:
|
|
787
|
+
|
|
788
|
+
| Action | Result |
|
|
789
|
+
| ---------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
790
|
+
| Double-click a cell, or Enter / F2 on a focused cell | The editor opens in the cell (single click with `setEditOnClick(true)`) |
|
|
791
|
+
| Enter, Tab, click elsewhere | Validated: `addItemChangeListener` is called |
|
|
792
|
+
| Choice in a `select` | Validated at once |
|
|
793
|
+
| Click on a `checkbox` box, or Enter / F2 on its cell | Toggled and validated at once (no edit mode) |
|
|
794
|
+
| Escape | Cancelled: the previous value comes back, no event |
|
|
795
|
+
|
|
796
|
+
Good to know:
|
|
797
|
+
|
|
798
|
+
- **The browser shows the new value right away**, before Java answers. Java's `List<T>` is **not** updated:
|
|
799
|
+
the listener receives a new `T` built from the JSON of the row.
|
|
800
|
+
- **Validation is done in Java**: the cell has no error state. To refuse a value, show a message and call
|
|
801
|
+
`setItems(...)` again with the stored data: the cell shows the previous value.
|
|
802
|
+
- `setItems(...)` replaces all the rows and loses an edit in progress: avoid refreshing the grid while the user edits.
|
|
803
|
+
- `path` and `readOnlyWhen` use the JSON names of the properties of `T` (Jackson rules).
|
|
804
|
+
- Checkbox columns always show boxes: read-only boxes when the grid is not editable, on `readOnlyWhen` rows, and with
|
|
805
|
+
`Column.readOnlyCheckbox(...)`.
|
|
806
|
+
- Not available yet: Tab to the next cell, starting an edit by typing, custom editors (date, combo box…).
|
|
807
|
+
|
|
808
|
+
#### Row selection in Vaadin
|
|
809
|
+
|
|
810
|
+
```java
|
|
811
|
+
grid.setSelectable(true);
|
|
812
|
+
grid.addSelectionListener(selected -> deleteButton.setDisabled(selected.isEmpty()));
|
|
813
|
+
|
|
814
|
+
deleteButton.addClickListener(() -> {
|
|
815
|
+
personService.delete(grid.getSelectedItems());
|
|
816
|
+
grid.setItems(personService.findPage(0, 15)); // also clears the selection
|
|
817
|
+
});
|
|
818
|
+
```
|
|
819
|
+
|
|
820
|
+
- A first column of boxes, with a "select all" box in its header (selects the rows of the current page).
|
|
821
|
+
- Independent from the data and from inline editing: selecting a row does not change the items.
|
|
822
|
+
- `getSelectedItems()` returns the objects given to `setItems(...)` (not updated by inline edits).
|
|
823
|
+
- `setItems(...)` and `deselectAll()` clear the selection.
|
|
824
|
+
|
|
825
|
+
#### Sorting and filtering in Vaadin
|
|
826
|
+
|
|
827
|
+
```java
|
|
828
|
+
grid.setColumns(List.of(
|
|
829
|
+
Column.text("name", "Name").sortable().filterable(),
|
|
830
|
+
Column.text("email", "E-mail").filterable(),
|
|
831
|
+
Column.readOnly("createdAt", "Created").sortable()));
|
|
832
|
+
```
|
|
833
|
+
|
|
834
|
+
- Done in the browser, on the rows sent by `setItems(...)` (the current page): Java is not called.
|
|
835
|
+
- **Sort**: a click on the header cycles ascending, descending, none. One sorted column at a time.
|
|
836
|
+
- **Filter**: keeps the rows whose value contains the text typed, case-insensitive.
|
|
837
|
+
- A column can be sortable, filterable, editable and `readOnlyWhen` at the same time.
|
|
838
|
+
- The sort compares the JSON values: send dates as ISO strings (`2026-11-19`) or numbers to keep them in order.
|
|
839
|
+
|
|
840
|
+
#### Components in cells
|
|
841
|
+
|
|
842
|
+
`Column.component(key, header, renderer)`: `renderer` builds a Java component for each row, with any content
|
|
843
|
+
(DS components, Vaadin components, layouts…). Its listeners work as usual.
|
|
844
|
+
|
|
845
|
+
```java
|
|
846
|
+
grid.setColumns(List.of(
|
|
847
|
+
Column.text("name", "Name"),
|
|
848
|
+
Column.component("actions", "Actions", (Person person) -> {
|
|
849
|
+
SynerDsButton edit = new SynerDsButton("Edit");
|
|
850
|
+
edit.setAppearance("ghost", "gray");
|
|
851
|
+
edit.addClickListener(() -> openEditor(person));
|
|
852
|
+
return edit;
|
|
853
|
+
})));
|
|
854
|
+
grid.setItems(personService.findPage(0, 15));
|
|
855
|
+
```
|
|
856
|
+
|
|
857
|
+
- Give the type of the lambda parameter (`(Person person) -> …`): Java cannot infer it from `List<Column>`.
|
|
858
|
+
- The components are built again on each `setItems(...)` or `setColumns(...)`, never on an inline edit:
|
|
859
|
+
if they show a value of the row, call `setItems(...)` after saving.
|
|
860
|
+
- One component per row and per column, all kept on the server: fine for a page of rows, not for thousands.
|
|
861
|
+
- `key` must be unique among the columns. The column is never editable, sortable nor filterable.
|
|
862
|
+
- How it works: each cell is a Flow content element (`getContentElement`, Vaadin 24.5+) named
|
|
863
|
+
`sds-cell-<row>-<key>`, bound once to a container that `sds-grid.tsx` keeps in a hidden stash and moves into the
|
|
864
|
+
cell while it is displayed. Both files must use the same names.
|
|
865
|
+
|
|
384
866
|
### In a view
|
|
385
867
|
|
|
386
868
|
```java
|
|
869
|
+
import java.util.List;
|
|
870
|
+
|
|
871
|
+
import com.vaadin.flow.component.notification.Notification;
|
|
872
|
+
|
|
387
873
|
SynerDsInput email = new SynerDsInput("E-mail");
|
|
388
874
|
email.setType("email");
|
|
389
875
|
email.addBlurListener(value -> {
|
|
@@ -394,8 +880,8 @@ email.addBlurListener(value -> {
|
|
|
394
880
|
SynerDsButton save = new SynerDsButton("Save");
|
|
395
881
|
save.addClickListener(() -> Notification.show("Saved"));
|
|
396
882
|
|
|
397
|
-
SynerDsGrid<Person> grid = new SynerDsGrid<>();
|
|
398
|
-
grid.setColumns(List.of(
|
|
883
|
+
SynerDsGrid<Person> grid = new SynerDsGrid<>(Person.class);
|
|
884
|
+
grid.setColumns(List.of(Column.readOnly("name", "Name"), Column.readOnly("email", "E-mail")));
|
|
399
885
|
grid.setItems(personService.findPage(0, 15));
|
|
400
886
|
|
|
401
887
|
add(email, save, grid);
|