@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 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 | 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** |
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 | 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 |
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 | 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`… |
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 | 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 |
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 | 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"` | |
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 | 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
- | other props | Vaadin `GridProps` | — | `items`, `dataProvider`, `allRowsVisible`… |
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 (24.4+) integrates React components with a `ReactAdapterElement` (TypeScript, in `src/main/frontend/`) and a `ReactAdapterComponent` (Java).
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 | Where | For this release |
175
- | ------------------------------------------------------- | ----------------------------------------- | ---------------- |
176
- | **Vaadin platform** (Maven `com.vaadin:vaadin-bom`) | `vaadin.version` in the `pom.xml` | `25.3.5` |
177
- | **Web components** (npm `@vaadin/react-components`…) | Peer dependency of this package | `25.3.5` |
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.1.1"; // the only line to change on each DS release
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. No Java component inside a grid cell.
202
- - **Free Vaadin components only** (no Grid Pro, Charts…).
203
- - Custom element tags use the `synerds-` prefix: `sds-*` tags are already used by the DS.
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 | Vaadin side |
208
- | ---------------------------------------------- | ------------------------------------------------------------------- |
209
- | Data (`label`, `value`, `status`, `items`…) | Synchronized state: `setState(...)` / `getState(...)` |
210
- | Input (`onChange` of `SDSInput`) | `value` state updated → `addStateChangeListener("value", ...)` |
211
- | Actions (`onBlur`, `onClick`) | Custom event → `getElement().addEventListener(...)` |
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 | States | Events |
216
- | --------------- | ----------------------------------------------------------------------- | ----------------------------------- |
217
- | `synerds-input` | `inputId`, `value`, `label`, `placeholder`, `type`, `status`, `message` | `synerds-blur` (detail: the value) |
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/synerds-input.tsx`:
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>('synerds-blur');
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('synerds-input', SynerDsInputElement);
310
+ customElements.define('sds-input', SynerDsInputElement);
254
311
  ```
255
312
 
256
313
  `SynerDsInput.java`:
257
314
 
258
315
  ```java
259
- @Tag("synerds-input")
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("./synerds-input.tsx")
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("synerds-blur", e -> listener.accept(e.getEventData().getString("event.detail")))
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 | States | Events |
296
- | ---------------- | --------------------------------------- | --------------- |
297
- | `synerds-button` | `text`, `variant`, `color`, `disabled` | `synerds-click` |
359
+ | Tag | States | Events |
360
+ | ------------ | -------------------------------------- | ----------- |
361
+ | `sds-button` | `text`, `variant`, `color`, `disabled` | `sds-click` |
298
362
 
299
- `src/main/frontend/synerds-button.tsx`:
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>('synerds-click');
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('synerds-button', SynerDsButtonElement);
389
+ customElements.define('sds-button', SynerDsButtonElement);
326
390
  ```
327
391
 
328
392
  `SynerDsButton.java`:
329
393
 
330
394
  ```java
331
- @Tag("synerds-button")
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("./synerds-button.tsx")
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("synerds-click", e -> listener.run());
418
+ getElement().addEventListener("sds-click", e -> listener.run());
350
419
  }
351
420
  }
352
421
  ```
353
422
 
354
423
  ### SDSGrid
355
424
 
356
- | Tag | States | Events |
357
- | -------------- | ---------------------------------------------------- | ------ |
358
- | `synerds-grid` | `columns` (`{ path, header }[]`), `items` (objects) | — |
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
- `src/main/frontend/synerds-grid.tsx`:
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 { ReactElement } from 'react';
448
+ import { type ReactElement, createContext, useContext, useLayoutEffect, useMemo, useRef } from 'react';
364
449
  import { ReactAdapterElement, type RenderHooks } from 'Frontend/generated/flow/ReactAdapter';
365
- import { SDSGrid, SDSGridColumn } from '@mrcaktuz/sds-react/grid';
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
- type Column = { path: string; header: string };
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<object[]>('items');
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
- <SDSGrid items={items ?? []} allRowsVisible>
376
- {(columns ?? []).map((c) => (
377
- <SDSGridColumn key={c.path} path={c.path} header={c.header} />
378
- ))}
379
- </SDSGrid>
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('synerds-grid', SynerDsGridElement);
593
+ customElements.define('sds-grid', SynerDsGridElement);
385
594
  ```
386
595
 
387
596
  `SynerDsGrid.java`:
388
597
 
389
598
  ```java
390
- @Tag("synerds-grid")
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("./synerds-grid.tsx")
618
+ @JsModule("./sds-grid.tsx")
393
619
  public class SynerDsGrid<T> extends ReactAdapterComponent {
394
- public record Column(String path, String header) {}
395
620
 
396
- public void setColumns(List<Column> columns) { setState("columns", columns); }
397
- public void setItems(List<T> items) { setState("items", items); }
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(new SynerDsGrid.Column("name", "Name"), new SynerDsGrid.Column("email", "E-mail")));
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);