@mrcaktuz/sds-react 0.0.0-stage → 0.1.1

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
@@ -1,3 +1,439 @@
1
- # Temporary Holding Version
1
+ # @mrcaktuz/sds-react
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Synerglass Design System — React components, styled on import.
4
+ Usable in a React project (Vite, Next.js) and in a **Vaadin Flow** application through React adapters (see [Usage in Vaadin](#usage-in-vaadin)).
5
+
6
+ > **Vaadin platform for this release: `25.3.5`**
7
+ > In a Vaadin application, set `<vaadin.version>25.3.5</vaadin.version>` in the `pom.xml` (see [Versions](#versions)).
8
+ > Built and tested with `@vaadin/react-components` `25.3.5`, the npm version pinned by this platform.
9
+ > Peer dependency `~25.3.5`: later `25.3.x` patches are accepted.
10
+
11
+ ## Installation
12
+
13
+ ```bash
14
+ npm i @mrcaktuz/sds-react
15
+ ```
16
+
17
+ Peer dependencies, provided by the host project:
18
+
19
+ | Package | Version | Needed for |
20
+ | -------------------------- | --------- | ------------------------------------------------------------------------------ |
21
+ | `react`, `react-dom` | `^19` | Every component |
22
+ | `@vaadin/react-components` | `~25.3.5` | The `/grid` entry only. In a Vaadin app, the version comes from the `pom.xml` |
23
+
24
+ npm (v7+) and pnpm install peer dependencies automatically; Yarn needs them added by hand.
25
+
26
+ **Outside of Vaadin** (Vite, Next.js), pin every `@vaadin/*` package to the same version with `overrides` (npm, pnpm) or `resolutions` (Yarn).
27
+ The Vaadin packages depend on each other with `~` ranges: without overrides, some resolve to a newer patch and two versions end up in the page.
28
+ A Vaadin application does not need this: Flow already pins them from the platform version.
29
+
30
+ ## Entries
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** |
36
+
37
+ The Vaadin-based components register custom elements as soon as they are imported, which crashes in Node.js.
38
+ That is why they live in a separate entry: importing the main entry never loads Vaadin.
39
+
40
+ ## Styles
41
+
42
+ - **Importing a component is enough**: its CSS (`@mrcaktuz/sds-styles`) is imported by the component itself and loaded by the host bundler (Vite in Vaadin). No stylesheet to import by hand.
43
+ - The CSS is global (no Shadow DOM): it applies to the components rendered by a Vaadin `ReactAdapterElement`.
44
+ - Colors come from the SDS tokens (`--sds-c-*`), in light and dark.
45
+
46
+ ### Light / dark theme
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 |
54
+
55
+ `theme` is the attribute of the Vaadin Lumo theme: **when the Vaadin application switches to dark, the DS components follow**.
56
+
57
+ ```java
58
+ // Force dark
59
+ UI.getCurrent().getElement().executeJs("document.documentElement.setAttribute('theme', 'dark')");
60
+ // Back to the OS preference
61
+ UI.getCurrent().getElement().executeJs("document.documentElement.removeAttribute('theme')");
62
+ ```
63
+
64
+ The components only follow the theme: the application still manages its own background and texts.
65
+
66
+ ## Components
67
+
68
+ ### SDSButton
69
+
70
+ ```tsx
71
+ import { SDSButton } from '@mrcaktuz/sds-react';
72
+
73
+ <SDSButton onClick={save}>Save</SDSButton>
74
+ <SDSButton variant="outline" color="brand">Cancel</SDSButton>
75
+ <SDSButton variant="ghost" color="danger" icon={<TrashIcon />} iconOnly aria-label="Delete" />
76
+ ```
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`… |
87
+
88
+ Combinations outside of the design system are rejected at compile time.
89
+
90
+ ### SDSInput
91
+
92
+ ```tsx
93
+ import { SDSInput } from '@mrcaktuz/sds-react';
94
+
95
+ <SDSInput
96
+ label="E-mail"
97
+ type="email"
98
+ value="jean.dupont@synerglass.com"
99
+ onBlur={(value) => validate(value)}
100
+ />
101
+ <SDSInput label="E-mail" status="error" message="Invalid address" />
102
+ ```
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 |
115
+
116
+ - The callbacks receive the value first: no need to read `event.target.value`.
117
+ - **No validation inside the component**: the host sets `status` and `message`.
118
+ - Prefer `onBlur` to `onChange` to limit server round trips.
119
+
120
+ ### SDSPagination
121
+
122
+ ```tsx
123
+ import { SDSPagination } from '@mrcaktuz/sds-react';
124
+
125
+ <SDSPagination page={page} pageSize={15} totalItems={total} onPageChange={setPage} />
126
+ ```
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"` | |
138
+
139
+ ### SDSGrid (`/grid` entry)
140
+
141
+ The official Vaadin Grid, themed with the SDS tokens. Same API as the Vaadin `Grid` and columns.
142
+
143
+ ```tsx
144
+ import { SDSGrid, SDSGridColumn, SDSGridSortColumn } from '@mrcaktuz/sds-react/grid';
145
+
146
+ <SDSGrid items={users} stripes>
147
+ <SDSGridSortColumn path="name" header="Name" />
148
+ <SDSGridColumn path="email" header="E-mail" />
149
+ </SDSGrid>
150
+ ```
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`… |
158
+
159
+ Columns: `SDSGridColumn`, `SDSGridSortColumn`, `SDSGridFilterColumn`, `SDSGridSelectionColumn` (the Vaadin columns).
160
+ The SDS theme is scoped to the `sds-grid` class: native Vaadin grids on the same screen keep their own style.
161
+
162
+ ## Usage in Vaadin
163
+
164
+ Vaadin Flow (24.4+) integrates React components with a `ReactAdapterElement` (TypeScript, in `src/main/frontend/`) and a `ReactAdapterComponent` (Java).
165
+ The DS publishes the React components; **the adapters and Java classes are written in the Vaadin project**.
166
+
167
+ ### Versions
168
+
169
+ **The DS decides the Vaadin version**: each release of this package states the Vaadin platform it requires.
170
+ In a Vaadin application, the `pom.xml` sets the version of every `@vaadin/*` npm package: if it differs, the application version wins and the grid theme may break silently.
171
+
172
+ Two version numbers, not to be mixed up:
173
+
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` |
178
+
179
+ The web components get their own patches on npm before a platform release includes them
180
+ (e.g. `@vaadin/react-components` `25.3.6` exists on npm, the `25.3.6` platform does not yet).
181
+ The DS always targets a **released platform** and the npm versions it pins
182
+ (see `versions.json` in [vaadin/platform](https://github.com/vaadin/platform), at the platform tag).
183
+
184
+ On each DS release, update both in **the same pull request**:
185
+
186
+ ```xml
187
+ <vaadin.version>25.3.5</vaadin.version> <!-- must match the DS release notes -->
188
+ ```
189
+
190
+ ```java
191
+ public final class SdsVersion {
192
+ 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
194
+ }
195
+ ```
196
+
197
+ ### Rules
198
+
199
+ - **Import everything from this package**, never `@vaadin/*` directly, and the grid from the `/grid` entry.
200
+ - **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.
204
+
205
+ How the React props map to Vaadin:
206
+
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(...)` |
212
+
213
+ ### SDSInput
214
+
215
+ | Tag | States | Events |
216
+ | --------------- | ----------------------------------------------------------------------- | ----------------------------------- |
217
+ | `synerds-input` | `inputId`, `value`, `label`, `placeholder`, `type`, `status`, `message` | `synerds-blur` (detail: the value) |
218
+
219
+ `src/main/frontend/synerds-input.tsx`:
220
+
221
+ ```tsx
222
+ import type { ReactElement } from 'react';
223
+ import { ReactAdapterElement, type RenderHooks } from 'Frontend/generated/flow/ReactAdapter';
224
+ import { SDSInput, type SDSInputStatus, type SDSInputType } from '@mrcaktuz/sds-react';
225
+
226
+ class SynerDsInputElement extends ReactAdapterElement {
227
+ protected override render(hooks: RenderHooks): ReactElement | null {
228
+ const [inputId] = hooks.useState<string>('inputId');
229
+ const [value, setValue] = hooks.useState<string>('value');
230
+ const [label] = hooks.useState<string>('label');
231
+ const [placeholder] = hooks.useState<string>('placeholder');
232
+ const [type] = hooks.useState<SDSInputType>('type');
233
+ const [status] = hooks.useState<SDSInputStatus>('status');
234
+ const [message] = hooks.useState<string>('message');
235
+ const dispatchBlur = hooks.useCustomEvent<string>('synerds-blur');
236
+
237
+ return (
238
+ <SDSInput
239
+ id={inputId}
240
+ label={label}
241
+ placeholder={placeholder}
242
+ type={type}
243
+ status={status}
244
+ message={message}
245
+ value={value}
246
+ onChange={(v) => setValue(v)}
247
+ onBlur={(v) => dispatchBlur(v)}
248
+ />
249
+ );
250
+ }
251
+ }
252
+
253
+ customElements.define('synerds-input', SynerDsInputElement);
254
+ ```
255
+
256
+ `SynerDsInput.java`:
257
+
258
+ ```java
259
+ @Tag("synerds-input")
260
+ @NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
261
+ @JsModule("./synerds-input.tsx")
262
+ public class SynerDsInput extends ReactAdapterComponent {
263
+
264
+ public SynerDsInput(String label) {
265
+ setLabel(label);
266
+ }
267
+
268
+ public void setInputId(String id) { setState("inputId", id); } // id of the <input> (not setId of the component)
269
+ public void setLabel(String label) { setState("label", label); }
270
+ public void setPlaceholder(String placeholder) { setState("placeholder", placeholder); }
271
+ public void setType(String type) { setState("type", type); } // "text", "email", "password"...
272
+
273
+ public String getValue() { return getState("value", String.class); }
274
+ public void setValue(String value) { setState("value", value); }
275
+
276
+ public void setError(String message) { setState("status", "error"); setState("message", message); }
277
+ public void setSuccess(String message) { setState("status", "success"); setState("message", message); }
278
+ public void clearStatus() { setState("status", "default"); setState("message", null); }
279
+
280
+ /** On each keystroke (the value is synchronized automatically) */
281
+ public void addValueChangeListener(Consumer<String> listener) {
282
+ addStateChangeListener("value", String.class, listener);
283
+ }
284
+
285
+ /** When the field loses focus */
286
+ public void addBlurListener(Consumer<String> listener) {
287
+ getElement().addEventListener("synerds-blur", e -> listener.accept(e.getEventData().getString("event.detail")))
288
+ .addEventData("event.detail");
289
+ }
290
+ }
291
+ ```
292
+
293
+ ### SDSButton
294
+
295
+ | Tag | States | Events |
296
+ | ---------------- | --------------------------------------- | --------------- |
297
+ | `synerds-button` | `text`, `variant`, `color`, `disabled` | `synerds-click` |
298
+
299
+ `src/main/frontend/synerds-button.tsx`:
300
+
301
+ ```tsx
302
+ import type { ReactElement } from 'react';
303
+ import { ReactAdapterElement, type RenderHooks } from 'Frontend/generated/flow/ReactAdapter';
304
+ import { SDSButton, type SDSButtonProps } from '@mrcaktuz/sds-react';
305
+
306
+ class SynerDsButtonElement extends ReactAdapterElement {
307
+ protected override render(hooks: RenderHooks): ReactElement | null {
308
+ const [text] = hooks.useState<string>('text');
309
+ const [variant] = hooks.useState<string>('variant');
310
+ const [color] = hooks.useState<string>('color');
311
+ const [disabled] = hooks.useState<boolean>('disabled');
312
+ const dispatchClick = hooks.useCustomEvent<void>('synerds-click');
313
+
314
+ // variant/color come from Java as strings: the allowed pairs are listed in the SDSButton table
315
+ const appearance = { variant: variant ?? 'primary', color: color ?? 'brand' } as SDSButtonProps;
316
+
317
+ return (
318
+ <SDSButton {...appearance} disabled={disabled} onClick={() => dispatchClick()}>
319
+ {text}
320
+ </SDSButton>
321
+ );
322
+ }
323
+ }
324
+
325
+ customElements.define('synerds-button', SynerDsButtonElement);
326
+ ```
327
+
328
+ `SynerDsButton.java`:
329
+
330
+ ```java
331
+ @Tag("synerds-button")
332
+ @NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
333
+ @JsModule("./synerds-button.tsx")
334
+ public class SynerDsButton extends ReactAdapterComponent {
335
+
336
+ public SynerDsButton(String text) {
337
+ setText(text);
338
+ }
339
+
340
+ public void setText(String text) { setState("text", text); }
341
+ /** variant: "primary", "outline", "ghost"; color: "brand", "gray", "success", "warning", "danger" */
342
+ public void setAppearance(String variant, String color) {
343
+ setState("variant", variant);
344
+ setState("color", color);
345
+ }
346
+ public void setDisabled(boolean disabled) { setState("disabled", disabled); }
347
+
348
+ public void addClickListener(Runnable listener) {
349
+ getElement().addEventListener("synerds-click", e -> listener.run());
350
+ }
351
+ }
352
+ ```
353
+
354
+ ### SDSGrid
355
+
356
+ | Tag | States | Events |
357
+ | -------------- | ---------------------------------------------------- | ------ |
358
+ | `synerds-grid` | `columns` (`{ path, header }[]`), `items` (objects) | — |
359
+
360
+ `src/main/frontend/synerds-grid.tsx`:
361
+
362
+ ```tsx
363
+ import type { ReactElement } from 'react';
364
+ import { ReactAdapterElement, type RenderHooks } from 'Frontend/generated/flow/ReactAdapter';
365
+ import { SDSGrid, SDSGridColumn } from '@mrcaktuz/sds-react/grid';
366
+
367
+ type Column = { path: string; header: string };
368
+
369
+ class SynerDsGridElement extends ReactAdapterElement {
370
+ protected override render(hooks: RenderHooks): ReactElement | null {
371
+ const [columns] = hooks.useState<Column[]>('columns');
372
+ const [items] = hooks.useState<object[]>('items');
373
+
374
+ return (
375
+ <SDSGrid items={items ?? []} allRowsVisible>
376
+ {(columns ?? []).map((c) => (
377
+ <SDSGridColumn key={c.path} path={c.path} header={c.header} />
378
+ ))}
379
+ </SDSGrid>
380
+ );
381
+ }
382
+ }
383
+
384
+ customElements.define('synerds-grid', SynerDsGridElement);
385
+ ```
386
+
387
+ `SynerDsGrid.java`:
388
+
389
+ ```java
390
+ @Tag("synerds-grid")
391
+ @NpmPackage(value = SdsVersion.PACKAGE, version = SdsVersion.VERSION)
392
+ @JsModule("./synerds-grid.tsx")
393
+ public class SynerDsGrid<T> extends ReactAdapterComponent {
394
+ public record Column(String path, String header) {}
395
+
396
+ public void setColumns(List<Column> columns) { setState("columns", columns); }
397
+ public void setItems(List<T> items) { setState("items", items); }
398
+ }
399
+ ```
400
+
401
+ ### In a view
402
+
403
+ ```java
404
+ SynerDsInput email = new SynerDsInput("E-mail");
405
+ email.setType("email");
406
+ email.addBlurListener(value -> {
407
+ if (value.contains("@")) email.setSuccess("Valid address");
408
+ else email.setError("Invalid address");
409
+ });
410
+
411
+ SynerDsButton save = new SynerDsButton("Save");
412
+ save.addClickListener(() -> Notification.show("Saved"));
413
+
414
+ SynerDsGrid<Person> grid = new SynerDsGrid<>();
415
+ grid.setColumns(List.of(new SynerDsGrid.Column("name", "Name"), new SynerDsGrid.Column("email", "E-mail")));
416
+ grid.setItems(personService.findPage(0, 15));
417
+
418
+ add(email, save, grid);
419
+ ```
420
+
421
+ ### Checks after an upgrade
422
+
423
+ - Only one version of `@vaadin/grid` in the `node_modules` of the Vaadin project, and only one loaded in the page.
424
+ - A native Java `Grid` on the same screen keeps its original style.
425
+ - The dark theme works with the Vaadin theme actually used by the application.
426
+
427
+ ## Usage in Next.js
428
+
429
+ The main entry is safe with server-side rendering. The `/grid` components must be loaded in the browser only:
430
+
431
+ ```tsx
432
+ 'use client';
433
+ import dynamic from 'next/dynamic';
434
+
435
+ const UsersTable = dynamic(() => import('./UsersTable'), {
436
+ ssr: false,
437
+ loading: () => <div style={{ minHeight: 480 }} aria-busy="true" />, // reserve space to avoid layout shift
438
+ });
439
+ ```