@mrcaktuz/sds-react 0.1.1 → 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 +571 -102
- package/dist/grid.cjs +282 -15627
- package/dist/grid.d.cts +43 -28
- package/dist/grid.d.ts +43 -28
- package/dist/grid.js +297 -15613
- package/dist/index.d.cts +4 -4
- package/dist/index.d.ts +4 -4
- package/package.json +5 -9
package/README.md
CHANGED
|
@@ -16,9 +16,9 @@ npm i @mrcaktuz/sds-react
|
|
|
16
16
|
|
|
17
17
|
Peer dependencies, provided by the host project:
|
|
18
18
|
|
|
19
|
-
| Package | Version | Needed for
|
|
20
|
-
| -------------------------- | --------- |
|
|
21
|
-
| `react`, `react-dom` | `^19` | Every component
|
|
19
|
+
| Package | Version | Needed for |
|
|
20
|
+
| -------------------------- | --------- | ----------------------------------------------------------------------------- |
|
|
21
|
+
| `react`, `react-dom` | `^19` | Every component |
|
|
22
22
|
| `@vaadin/react-components` | `~25.3.5` | The `/grid` entry only. In a Vaadin app, the version comes from the `pom.xml` |
|
|
23
23
|
|
|
24
24
|
npm (v7+) and pnpm install peer dependencies automatically; Yarn needs them added by hand.
|
|
@@ -29,10 +29,10 @@ A Vaadin application does not need this: Flow already pins them from the platfor
|
|
|
29
29
|
|
|
30
30
|
## Entries
|
|
31
31
|
|
|
32
|
-
| Import
|
|
33
|
-
|
|
|
34
|
-
| `@mrcaktuz/sds-react`
|
|
35
|
-
| `@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** |
|
|
36
36
|
|
|
37
37
|
The Vaadin-based components register custom elements as soon as they are imported, which crashes in Node.js.
|
|
38
38
|
That is why they live in a separate entry: importing the main entry never loads Vaadin.
|
|
@@ -45,12 +45,12 @@ That is why they live in a separate entry: importing the main entry never loads
|
|
|
45
45
|
|
|
46
46
|
### Light / dark theme
|
|
47
47
|
|
|
48
|
-
| `<html>` tag
|
|
49
|
-
|
|
|
50
|
-
| no attribute
|
|
51
|
-
| `theme="dark"` or `data-theme="dark"`
|
|
52
|
-
| `theme="light"` or `data-theme="light"`
|
|
53
|
-
| `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 |
|
|
54
54
|
|
|
55
55
|
`theme` is the attribute of the Vaadin Lumo theme: **when the Vaadin application switches to dark, the DS components follow**.
|
|
56
56
|
|
|
@@ -75,15 +75,15 @@ import { SDSButton } from '@mrcaktuz/sds-react';
|
|
|
75
75
|
<SDSButton variant="ghost" color="danger" icon={<TrashIcon />} iconOnly aria-label="Delete" />
|
|
76
76
|
```
|
|
77
77
|
|
|
78
|
-
| Prop | Type
|
|
79
|
-
| -------------- |
|
|
80
|
-
| `variant` | `"primary"` \| `"outline"` \| `"ghost"`
|
|
81
|
-
| `color` | `"brand"` \| `"gray"` \| `"success"` \| `"warning"` \| `"danger"` | `"brand"`
|
|
82
|
-
| `small` | `boolean`
|
|
83
|
-
| `icon` | `ReactNode`
|
|
84
|
-
| `iconPosition` | `"left"` \| `"right"`
|
|
85
|
-
| `iconOnly` | `boolean`
|
|
86
|
-
| 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`… |
|
|
87
87
|
|
|
88
88
|
Combinations outside of the design system are rejected at compile time.
|
|
89
89
|
|
|
@@ -101,17 +101,17 @@ import { SDSInput } from '@mrcaktuz/sds-react';
|
|
|
101
101
|
<SDSInput label="E-mail" status="error" message="Invalid address" />
|
|
102
102
|
```
|
|
103
103
|
|
|
104
|
-
| Prop | Type
|
|
105
|
-
| ------------- |
|
|
106
|
-
| `id` | `string`
|
|
107
|
-
| `type` | `"text"` \| `"email"` \| `"password"` \| `"number"` \| `"tel"` \| `"url"` \| `"search"` \| `"date"` | `"text"`
|
|
108
|
-
| `label` | `string`
|
|
109
|
-
| `placeholder` | `string`
|
|
110
|
-
| `value` | `string`
|
|
111
|
-
| `status` | `"default"` \| `"error"` \| `"success"`
|
|
112
|
-
| `message` | `string`
|
|
113
|
-
| `onChange` | `(value: string, event) => void`
|
|
114
|
-
| `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 |
|
|
115
115
|
|
|
116
116
|
- The callbacks receive the value first: no need to read `event.target.value`.
|
|
117
117
|
- **No validation inside the component**: the host sets `status` and `message`.
|
|
@@ -125,16 +125,16 @@ import { SDSPagination } from '@mrcaktuz/sds-react';
|
|
|
125
125
|
<SDSPagination page={page} pageSize={15} totalItems={total} onPageChange={setPage} />
|
|
126
126
|
```
|
|
127
127
|
|
|
128
|
-
| Prop | Type
|
|
129
|
-
| ------------------ |
|
|
130
|
-
| `page` | `number`
|
|
131
|
-
| `pageSize` | `number`
|
|
132
|
-
| `totalItems` | `number`
|
|
133
|
-
| `onPageChange` | `(page: number) => void`
|
|
134
|
-
| `onPageSizeChange` | `(pageSize: number) => void`
|
|
135
|
-
| `showRowsPerPage` | `boolean`
|
|
136
|
-
| `pageSizeOptions` | `number[]`
|
|
137
|
-
| `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"` | |
|
|
138
138
|
|
|
139
139
|
### SDSGrid (`/grid` entry)
|
|
140
140
|
|
|
@@ -149,19 +149,75 @@ import { SDSGrid, SDSGridColumn, SDSGridSortColumn } from '@mrcaktuz/sds-react/g
|
|
|
149
149
|
</SDSGrid>
|
|
150
150
|
```
|
|
151
151
|
|
|
152
|
-
| Prop
|
|
153
|
-
|
|
|
154
|
-
| `stripes`
|
|
155
|
-
| `columnBorders`
|
|
156
|
-
| `noBorder`
|
|
157
|
-
|
|
|
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`… |
|
|
158
160
|
|
|
159
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
|
+
|
|
160
175
|
The SDS theme is scoped to the `sds-grid` class: native Vaadin grids on the same screen keep their own style.
|
|
161
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
|
+
|
|
162
218
|
## Usage in Vaadin
|
|
163
219
|
|
|
164
|
-
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).
|
|
165
221
|
The DS publishes the React components; **the adapters and Java classes are written in the Vaadin project**.
|
|
166
222
|
|
|
167
223
|
### Versions
|
|
@@ -171,10 +227,10 @@ In a Vaadin application, the `pom.xml` sets the version of every `@vaadin/*` npm
|
|
|
171
227
|
|
|
172
228
|
Two version numbers, not to be mixed up:
|
|
173
229
|
|
|
174
|
-
| Number
|
|
175
|
-
|
|
|
176
|
-
| **Vaadin platform** (Maven `com.vaadin:vaadin-bom`)
|
|
177
|
-
| **Web components** (npm `@vaadin/react-components`…)
|
|
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` |
|
|
178
234
|
|
|
179
235
|
The web components get their own patches on npm before a platform release includes them
|
|
180
236
|
(e.g. `@vaadin/react-components` `25.3.6` exists on npm, the `25.3.6` platform does not yet).
|
|
@@ -190,7 +246,7 @@ On each DS release, update both in **the same pull request**:
|
|
|
190
246
|
```java
|
|
191
247
|
public final class SdsVersion {
|
|
192
248
|
public static final String PACKAGE = "@mrcaktuz/sds-react";
|
|
193
|
-
public static final String VERSION = "0.
|
|
249
|
+
public static final String VERSION = "0.2.0"; // the only line to change on each DS release
|
|
194
250
|
}
|
|
195
251
|
```
|
|
196
252
|
|
|
@@ -198,25 +254,26 @@ public final class SdsVersion {
|
|
|
198
254
|
|
|
199
255
|
- **Import everything from this package**, never `@vaadin/*` directly, and the grid from the `/grid` entry.
|
|
200
256
|
- **State and event names must be identical in TypeScript and Java**: a typo fails silently. The tables below are the contract.
|
|
201
|
-
- **Data goes through JSON**: `setState` values must be serializable (records, simple beans). One page at a time, not thousands of rows.
|
|
202
|
-
- **
|
|
203
|
-
-
|
|
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.
|
|
204
261
|
|
|
205
262
|
How the React props map to Vaadin:
|
|
206
263
|
|
|
207
|
-
| React prop
|
|
208
|
-
|
|
|
209
|
-
| Data (`label`, `value`, `status`, `items`…)
|
|
210
|
-
| Input (`onChange` of `SDSInput`)
|
|
211
|
-
| 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(...)` |
|
|
212
269
|
|
|
213
270
|
### SDSInput
|
|
214
271
|
|
|
215
|
-
| Tag
|
|
216
|
-
|
|
|
217
|
-
| `
|
|
272
|
+
| Tag | States | Events |
|
|
273
|
+
| ----------- | ----------------------------------------------------------------------- | ------------------------------ |
|
|
274
|
+
| `sds-input` | `inputId`, `value`, `label`, `placeholder`, `type`, `status`, `message` | `sds-blur` (detail: the value) |
|
|
218
275
|
|
|
219
|
-
`src/main/frontend/
|
|
276
|
+
`src/main/frontend/sds-input.tsx`:
|
|
220
277
|
|
|
221
278
|
```tsx
|
|
222
279
|
import type { ReactElement } from 'react';
|
|
@@ -232,7 +289,7 @@ class SynerDsInputElement extends ReactAdapterElement {
|
|
|
232
289
|
const [type] = hooks.useState<SDSInputType>('type');
|
|
233
290
|
const [status] = hooks.useState<SDSInputStatus>('status');
|
|
234
291
|
const [message] = hooks.useState<string>('message');
|
|
235
|
-
const dispatchBlur = hooks.useCustomEvent<string>('
|
|
292
|
+
const dispatchBlur = hooks.useCustomEvent<string>('sds-blur');
|
|
236
293
|
|
|
237
294
|
return (
|
|
238
295
|
<SDSInput
|
|
@@ -250,15 +307,22 @@ class SynerDsInputElement extends ReactAdapterElement {
|
|
|
250
307
|
}
|
|
251
308
|
}
|
|
252
309
|
|
|
253
|
-
customElements.define('
|
|
310
|
+
customElements.define('sds-input', SynerDsInputElement);
|
|
254
311
|
```
|
|
255
312
|
|
|
256
313
|
`SynerDsInput.java`:
|
|
257
314
|
|
|
258
315
|
```java
|
|
259
|
-
|
|
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")
|
|
260
324
|
@NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
|
|
261
|
-
@JsModule("./
|
|
325
|
+
@JsModule("./sds-input.tsx")
|
|
262
326
|
public class SynerDsInput extends ReactAdapterComponent {
|
|
263
327
|
|
|
264
328
|
public SynerDsInput(String label) {
|
|
@@ -284,7 +348,7 @@ public class SynerDsInput extends ReactAdapterComponent {
|
|
|
284
348
|
|
|
285
349
|
/** When the field loses focus */
|
|
286
350
|
public void addBlurListener(Consumer<String> listener) {
|
|
287
|
-
getElement().addEventListener("
|
|
351
|
+
getElement().addEventListener("sds-blur", e -> listener.accept(e.getEventData().get("event.detail").asString()))
|
|
288
352
|
.addEventData("event.detail");
|
|
289
353
|
}
|
|
290
354
|
}
|
|
@@ -292,11 +356,11 @@ public class SynerDsInput extends ReactAdapterComponent {
|
|
|
292
356
|
|
|
293
357
|
### SDSButton
|
|
294
358
|
|
|
295
|
-
| Tag
|
|
296
|
-
|
|
|
297
|
-
| `
|
|
359
|
+
| Tag | States | Events |
|
|
360
|
+
| ------------ | -------------------------------------- | ----------- |
|
|
361
|
+
| `sds-button` | `text`, `variant`, `color`, `disabled` | `sds-click` |
|
|
298
362
|
|
|
299
|
-
`src/main/frontend/
|
|
363
|
+
`src/main/frontend/sds-button.tsx`:
|
|
300
364
|
|
|
301
365
|
```tsx
|
|
302
366
|
import type { ReactElement } from 'react';
|
|
@@ -309,7 +373,7 @@ class SynerDsButtonElement extends ReactAdapterElement {
|
|
|
309
373
|
const [variant] = hooks.useState<string>('variant');
|
|
310
374
|
const [color] = hooks.useState<string>('color');
|
|
311
375
|
const [disabled] = hooks.useState<boolean>('disabled');
|
|
312
|
-
const dispatchClick = hooks.useCustomEvent<void>('
|
|
376
|
+
const dispatchClick = hooks.useCustomEvent<void>('sds-click');
|
|
313
377
|
|
|
314
378
|
// variant/color come from Java as strings: the allowed pairs are listed in the SDSButton table
|
|
315
379
|
const appearance = { variant: variant ?? 'primary', color: color ?? 'brand' } as SDSButtonProps;
|
|
@@ -322,15 +386,20 @@ class SynerDsButtonElement extends ReactAdapterElement {
|
|
|
322
386
|
}
|
|
323
387
|
}
|
|
324
388
|
|
|
325
|
-
customElements.define('
|
|
389
|
+
customElements.define('sds-button', SynerDsButtonElement);
|
|
326
390
|
```
|
|
327
391
|
|
|
328
392
|
`SynerDsButton.java`:
|
|
329
393
|
|
|
330
394
|
```java
|
|
331
|
-
|
|
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")
|
|
332
401
|
@NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
|
|
333
|
-
@JsModule("./
|
|
402
|
+
@JsModule("./sds-button.tsx")
|
|
334
403
|
public class SynerDsButton extends ReactAdapterComponent {
|
|
335
404
|
|
|
336
405
|
public SynerDsButton(String text) {
|
|
@@ -346,61 +415,461 @@ public class SynerDsButton extends ReactAdapterComponent {
|
|
|
346
415
|
public void setDisabled(boolean disabled) { setState("disabled", disabled); }
|
|
347
416
|
|
|
348
417
|
public void addClickListener(Runnable listener) {
|
|
349
|
-
getElement().addEventListener("
|
|
418
|
+
getElement().addEventListener("sds-click", e -> listener.run());
|
|
350
419
|
}
|
|
351
420
|
}
|
|
352
421
|
```
|
|
353
422
|
|
|
354
423
|
### SDSGrid
|
|
355
424
|
|
|
356
|
-
| Tag
|
|
357
|
-
|
|
|
358
|
-
| `
|
|
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:
|
|
359
430
|
|
|
360
|
-
|
|
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`:
|
|
361
446
|
|
|
362
447
|
```tsx
|
|
363
|
-
import type
|
|
448
|
+
import { type ReactElement, createContext, useContext, useLayoutEffect, useMemo, useRef } from 'react';
|
|
364
449
|
import { ReactAdapterElement, type RenderHooks } from 'Frontend/generated/flow/ReactAdapter';
|
|
365
|
-
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
|
+
}
|
|
366
487
|
|
|
367
|
-
|
|
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
|
+
}
|
|
368
519
|
|
|
369
520
|
class SynerDsGridElement extends ReactAdapterElement {
|
|
370
521
|
protected override render(hooks: RenderHooks): ReactElement | null {
|
|
371
522
|
const [columns] = hooks.useState<Column[]>('columns');
|
|
372
|
-
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
|
+
}
|
|
373
548
|
|
|
374
549
|
return (
|
|
375
|
-
<
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
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>
|
|
380
589
|
);
|
|
381
590
|
}
|
|
382
591
|
}
|
|
383
592
|
|
|
384
|
-
customElements.define('
|
|
593
|
+
customElements.define('sds-grid', SynerDsGridElement);
|
|
385
594
|
```
|
|
386
595
|
|
|
387
596
|
`SynerDsGrid.java`:
|
|
388
597
|
|
|
389
598
|
```java
|
|
390
|
-
|
|
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")
|
|
391
617
|
@NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
|
|
392
|
-
@JsModule("./
|
|
618
|
+
@JsModule("./sds-grid.tsx")
|
|
393
619
|
public class SynerDsGrid<T> extends ReactAdapterComponent {
|
|
394
|
-
public record Column(String path, String header) {}
|
|
395
620
|
|
|
396
|
-
|
|
397
|
-
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
|
+
}
|
|
398
749
|
}
|
|
399
750
|
```
|
|
400
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
|
+
|
|
401
866
|
### In a view
|
|
402
867
|
|
|
403
868
|
```java
|
|
869
|
+
import java.util.List;
|
|
870
|
+
|
|
871
|
+
import com.vaadin.flow.component.notification.Notification;
|
|
872
|
+
|
|
404
873
|
SynerDsInput email = new SynerDsInput("E-mail");
|
|
405
874
|
email.setType("email");
|
|
406
875
|
email.addBlurListener(value -> {
|
|
@@ -411,8 +880,8 @@ email.addBlurListener(value -> {
|
|
|
411
880
|
SynerDsButton save = new SynerDsButton("Save");
|
|
412
881
|
save.addClickListener(() -> Notification.show("Saved"));
|
|
413
882
|
|
|
414
|
-
SynerDsGrid<Person> grid = new SynerDsGrid<>();
|
|
415
|
-
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")));
|
|
416
885
|
grid.setItems(personService.findPage(0, 15));
|
|
417
886
|
|
|
418
887
|
add(email, save, grid);
|