@cahyo-dimas/freeday 2.0.0 → 2.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.
Files changed (41) hide show
  1. package/CHANGELOG.md +155 -0
  2. package/COMPONENTS.md +298 -2
  3. package/README.id.md +1 -1
  4. package/README.md +1 -1
  5. package/adapters/blazor/FdyAutocomplete.razor +4 -1
  6. package/adapters/blazor/FdyAutocomplete.razor.cs +26 -0
  7. package/adapters/blazor/FdyCascade.razor +6 -1
  8. package/adapters/blazor/FdyCascade.razor.cs +24 -0
  9. package/adapters/blazor/FdyCombo.razor +1 -0
  10. package/adapters/blazor/FdyCombo.razor.cs +13 -0
  11. package/adapters/blazor/FdyDatepicker.razor +15 -1
  12. package/adapters/blazor/FdyDatepicker.razor.cs +46 -0
  13. package/adapters/core/cfl-value.d.ts +11 -0
  14. package/adapters/core/cfl-value.js +31 -0
  15. package/adapters/react/components/FdyDrawer.tsx +3 -1
  16. package/adapters/react/components/FdyModal.tsx +3 -1
  17. package/adapters/react/index.d.ts +3 -0
  18. package/adapters/react/index.js +1 -0
  19. package/adapters/vue/components/FdyDrawer.vue +4 -1
  20. package/adapters/vue/components/FdyModal.vue +4 -1
  21. package/adapters/vue/index.d.ts +3 -0
  22. package/adapters/vue/index.js +1 -0
  23. package/dist/freeday-autocomplete.js +17 -1
  24. package/dist/freeday-carousel.js +5 -4
  25. package/dist/freeday-cascade.js +58 -7
  26. package/dist/freeday-cfl.js +5 -4
  27. package/dist/freeday-chart.js +33 -3
  28. package/dist/freeday-datepicker.js +109 -17
  29. package/dist/freeday-form.js +5 -4
  30. package/dist/freeday-mask.js +5 -4
  31. package/dist/freeday-select.js +18 -1
  32. package/dist/freeday-stepper.js +5 -4
  33. package/dist/freeday-table.js +9 -6
  34. package/dist/freeday-timepicker.js +19 -1
  35. package/dist/freeday-toast.js +5 -4
  36. package/dist/freeday-upload.js +5 -4
  37. package/dist/freeday.js +298 -64
  38. package/docs/agent-onboarding.md +9 -6
  39. package/docs/getting-started.md +15 -6
  40. package/docs/integrations.md +2 -2
  41. package/package.json +2 -2
package/docs/agent-onboarding.md CHANGED
@@ -20,21 +20,21 @@ the **root of the consuming project**:
20
20
 
21
21
  All UI in this project is built from Freeday: a **token-driven CSS kit** (`fdy-*` classes on plain
22
22
  markup) with **typed components for Vue, React and Blazor** layered on top. Most of the kit is
23
- markup + classes; ten interactive components also ship a typed wrapper, and in those three stacks
23
+ markup + classes; eleven interactive components also ship a typed wrapper, and in those three stacks
24
24
  the wrapper is the correct way to use them.
25
25
 
26
26
  **0. First decide which entry point this project uses. This is not an optimisation. Get it wrong
27
27
  and the code looks correct and fails later.**
28
28
 
29
- | This project's stack | Import the ten components from | Binding |
29
+ | This project's stack | Import the eleven components from | Binding |
30
30
  |---|---|---|
31
31
  | Vue 3 | `@cahyo-dimas/freeday/vue` | `v-model` |
32
32
  | React 18/19 | `@cahyo-dimas/freeday/react` | `value` + `onChange` |
33
33
  | Blazor (net8.0) | `@using Freeday.Blazor` (RCL) | `@bind-Value` |
34
34
  | Static HTML, Svelte, server-rendered templates… | no wrapper: raw markup + the enhancer script | `fdy-*` DOM events |
35
35
 
36
- The ten: **FdyCombo · FdyDatepicker · FdyDateRange · FdyAutocomplete · FdyCascade · FdyCfl ·
37
- FdyChart · FdyTable · FdyModal · FdyDrawer**. In Vue/React/Blazor, **never hand-write the raw
36
+ The eleven: **FdyCombo · FdyDatepicker · FdyDateRange · FdyAutocomplete · FdyCascade · FdyCfl ·
37
+ FdyChart · FdyTable · FdyModal · FdyDrawer · FdyAppShell**. In Vue/React/Blazor, **never hand-write the raw
38
38
  markup + enhancer for these eleven.** The raw path *appears* to work: the enhancer auto-initialises
39
39
  once on `DOMContentLoaded` and the first render is correct. Then it fails quietly: DOM your framework
40
40
  renders later is never hydrated, and the widget's state lives in the DOM instead of in your
@@ -75,6 +75,9 @@ wrapper, use the raw markup and hydrate it:
75
75
  components **without** a typed wrapper. For the eleven in step 0, use the wrapper instead.
76
76
  8. Freeday owns components + tokens, **not layout**. Grids/stacks/one-off gaps come from our own
77
77
  layout layer. Build its theme on `var(--space-N)` so both systems stay in step.
78
+ 9. The enhancers render their own English UI strings (pager, filter dialog, validation). Never
79
+ hand-translate one by rewriting the enhancer's nodes — set `data-fdy-text-<key>` on the
80
+ component root, and `<html lang>` for date names. Keys are in COMPONENTS.md.
78
81
  ```
79
82
 
80
83
  Adjust the paths if the package lives somewhere else (a workspace, a vendored copy, `wwwroot/` for
@@ -85,7 +88,7 @@ Blazor). Then verify the agent can actually read those files. An agent that can'
85
88
 
86
89
  | File | What it answers |
87
90
  |---|---|
88
- | `COMPONENTS.md` | The complete class surface: what exists, its modifiers, minimal markup, a11y. |
91
+ | `COMPONENTS.md` | The complete class surface: what exists, its modifiers, minimal markup, a11y. Also the typed wrappers' props — one `### Props — <FdyX>` table each, and the `FdyTableColumn` fields. |
89
92
  | `USAGE.md` | The doctrine: which token/role/shadow/emphasis to use when. |
90
93
  | `docs/getting-started.md` | Install + import + theme, per stack (Static HTML · Vue · React · Blazor). |
91
94
  | `docs/integrations.md` | How to bridge third-party libraries (validation, charts, dates, i18n…). |
@@ -95,7 +98,7 @@ Blazor). Then verify the agent can actually read those files. An agent that can'
95
98
  | `dist/` | Built CSS + enhancers. **`freeday.bundle.css` = tokens + components** (what `@cahyo-dimas/freeday/css` resolves to); `freeday.css` is components **only**, `freeday.tokens.css` tokens only, so linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
96
99
  | `src/components/*.css` | The authoritative source for every class, when a doc is ambiguous. |
97
100
  | `tokens/tokens.json` | Every token in W3C DTCG format, machine-readable. |
98
- | `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 10 components each. |
101
+ | `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 11 components each (plus `FdyTableFooter`). |
99
102
 
100
103
  The live docs (with an interactive playground) are at
101
104
  <https://cahyo-dimas.github.io/freeday-ui-kit/>, and the repo (including three complete example
package/docs/getting-started.md CHANGED
@@ -23,7 +23,7 @@ Freeday = **CSS** (semantic tokens + `fdy-*` classes) + **zero-dependency JS enh
23
23
  table: [`integrations.md` §Event & API contract](integrations.md).
24
24
  **On Vue, React or Blazor this is not the path to take for eleven of the components.** `FdyCombo`,
25
25
  `FdyDatepicker`, `FdyDateRange`, `FdyAutocomplete`, `FdyCascade`, `FdyCfl`, `FdyChart`,
26
- `FdyTable`, `FdyModal`, `FdyDrawer` ship typed wrappers that own the state properly (Vue and
26
+ `FdyTable`, `FdyModal`, `FdyDrawer`, `FdyAppShell` ship typed wrappers that own the state properly (Vue and
27
27
  React re-implement the interaction natively; Blazor wraps the enhancer over interop). Use them;
28
28
  the raw path is for the components without a wrapper, and for stacks without an adapter.
29
29
  3. **Hydrate dynamic DOM.** Enhancers auto-init once on `DOMContentLoaded`. DOM an SPA renders
@@ -65,6 +65,13 @@ Freeday = **CSS** (semantic tokens + `fdy-*` classes) + **zero-dependency JS enh
65
65
  `.fdy-page-section`, `.fdy-toolbar`, `.fdy-stats`/`.fdy-stat`) and the type roles (`.fdy-title-page`
66
66
  / `-section` / `-card`), not by re-using `.fdy-card__title` for everything. **Which token/role/shadow
67
67
  to use when lives in [`USAGE.md`](../USAGE.md)**. Read it once; it's what makes screens cohere.
68
+ 9. **The enhancers' UI strings are English, and replaceable per element.** Pager labels, column
69
+ filter dialogs, upload and validation messages come from the enhancer, not from your markup.
70
+ Override any of them with **`data-fdy-text-<key>`** on the component's root — key list and the
71
+ `{n}`/`{from}`/`{total}` placeholders are in [`COMPONENTS.md`](../COMPONENTS.md) §Data table.
72
+ Dates need no attribute: the pickers format through `Intl` from the page's `<html lang>`, so
73
+ `lang="id"` gives Indonesian month and weekday names. **Coming from 1.x**, where those defaults
74
+ were Indonesian: 2.0.0 flipped them to English, and this attribute is the whole migration.
68
75
 
69
76
  ---
70
77
 
@@ -184,7 +191,7 @@ live docs also have a copy button per component.
184
191
  ```bash
185
192
  npm i @cahyo-dimas/freeday
186
193
  ```
187
- Lands in `package.json` as `"@cahyo-dimas/freeday": "^2.0.0"` (public npm package). `dist/` is
194
+ Lands in `package.json` as `"@cahyo-dimas/freeday": "^2.2.0"` (public npm package). `dist/` is
188
195
  committed and published → no build step; `npm ci` runs without auth.
189
196
 
190
197
  ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)
@@ -300,10 +307,11 @@ export function Panel() {
300
307
  value from `event.detail` in state/ref; don't set the DOM `value` back. `StrictMode` mounts twice in
301
308
  dev; `useFreeday` is idempotent, so it's safe.
302
309
 
303
- ### 5. Alternative: typed controlled components (`FdyCombo` · `FdyDatepicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart`)
310
+ ### 5. Alternative: typed controlled components
304
311
  For fields you'd normally write as a native `<select>`/`<input type="date">`,
305
312
  `@cahyo-dimas/freeday/react` also exports typed **controlled** components with plain `value`/`onChange`,
306
- no manual event bubbling (parity with the Vue `v-model` components above):
313
+ no manual event bubbling — the same eleven listed in §Core concepts #2, at parity with the Vue
314
+ `v-model` components above:
307
315
  ```tsx
308
316
  import { FdyCombo } from '@cahyo-dimas/freeday/react';
309
317
  import type { FdyComboOption } from '@cahyo-dimas/freeday/react';
@@ -436,11 +444,12 @@ kit's CSS/enhancers), then bind:
436
444
  <FdyChart Type="donut" Values="_byCity" Labels="_cityLabels" AriaLabel="Revenue by city" />
437
445
  <FdyDrawer @bind-Open="_drawerOpen" Title="Detail" Side="right">…</FdyDrawer>
438
446
  ```
439
- Ten components at parity with the Vue/React adapters: **`FdyModal`** · **`FdyDrawer`** (`@bind-Open`,
447
+ Eleven components at parity with the Vue/React adapters: **`FdyModal`** · **`FdyDrawer`** (`@bind-Open`,
440
448
  `Title`, `Size`/`Side`, `Dismissible`) · **`FdyCombo<TValue>`** · **`FdyDatepicker`** ·
441
449
  **`FdyAutocomplete`** · **`FdyCascade`** · **`FdyDateRange`** (`@bind-From`/`@bind-To`) ·
442
450
  **`FdyCfl<TRow>`** (async `LoadPage`) · **`FdyChart`** · **`FdyTable<TRow>`** (client sort/filter/page,
443
- or controlled `Sort`/`Filters`/`Page` for a server-paged table; `RowActivatable`, `RowDetail`). Each
451
+ or controlled `Sort`/`Filters`/`Page` for a server-paged table; `RowActivatable`, `RowDetail`) ·
452
+ **`FdyAppShell`** (`@bind-NavOpen`). Each
444
453
  `select`-type control also takes `Disabled`/`Readonly`/`Invalid`. The RCL targets **net8.0** and is
445
454
  consumed as source (`<ProjectReference>`); `.NET bin/obj` never ships in the npm tarball.
446
455
 
package/docs/integrations.md CHANGED
@@ -154,7 +154,7 @@ function Panel(): JSX.Element {
154
154
  ```
155
155
  > **Controlled alternative (parity with Vue's `v-model`):** `@cahyo-dimas/freeday/react` also exports
156
156
  > the typed components `FdyCombo` / `FdyDatepicker` / `FdyDateRange` / `FdyAutocomplete` /
157
- > `FdyCascade` / `FdyCfl` / `FdyChart` / `FdyTable` / `FdyModal` / `FdyDrawer`, with plain
157
+ > `FdyCascade` / `FdyCfl` / `FdyChart` / `FdyTable` / `FdyModal` / `FdyDrawer` / `FdyAppShell`, with plain
158
158
  > `value`/`onChange` (props in, events out), no `data-fdy-*` + manual event listener:
159
159
  > ```tsx
160
160
  > import { FdyCombo } from '@cahyo-dimas/freeday/react';
@@ -200,7 +200,7 @@ document.addEventListener('fdy-form-invalid', (e) =>
200
200
  > **Native components (parity with Vue's `v-model` / React's `value`/`onChange`):** the
201
201
  > **`Freeday.Blazor`** RCL (net8.0, `adapters/blazor/`) ships the typed components `FdyCombo<TValue>` /
202
202
  > `FdyDatepicker` / `FdyDateRange` / `FdyAutocomplete` / `FdyCascade` / `FdyCfl<TRow>` / `FdyChart` /
203
- > `FdyTable<TRow>` / `FdyModal` / `FdyDrawer` with `@bind`, no `@ref` / manual `initAll` / `[JSInvokable]`:
203
+ > `FdyTable<TRow>` / `FdyModal` / `FdyDrawer` / `FdyAppShell` with `@bind`, no `@ref` / manual `initAll` / `[JSInvokable]`:
204
204
  > ```razor
205
205
  > @using Freeday.Blazor
206
206
  > <FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl-status" />
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@cahyo-dimas/freeday",
3
- "version": "2.0.0",
3
+ "version": "2.2.0",
4
4
  "description": "Freeday: token-driven, framework-agnostic UI KIT (design source-of-truth).",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -92,7 +92,7 @@
92
92
  "scripts": {
93
93
  "build": "node tokens/build.mjs",
94
94
  "test": "node --test",
95
- "test:browser": "node --test --test-concurrency=3 browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/cfl-multi.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs",
95
+ "test:browser": "node --test --test-concurrency=3 browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/cfl-multi.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/picker-states.mjs",
96
96
  "prepack": "node tokens/build.mjs",
97
97
  "version": "node tokens/build.mjs && git add dist",
98
98
  "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit",