@cahyo-dimas/freeday 1.18.0 → 1.20.0

package/docs/agent-onboarding.md

@@ -0,0 +1,151 @@
+# Freeday — AI agent onboarding
+
+For **a coding agent working in a project that consumes Freeday** (Claude Code, Codex, Cursor,
+Copilot…). No model has Freeday in its training data, so an agent that is merely told "use Freeday"
+will invent class names or silently fall back to Bootstrap/Tailwind conventions. This file is the
+fix: paste the block below into the consuming project's agent instruction file, once.
+
+> Working on **the kit itself**, not a consuming app? That's [`../CLAUDE.md`](../CLAUDE.md) — this
+> file is about *using* the published package.
+
+---
+
+## 1. Paste this into your project's agent instructions
+
+Into `CLAUDE.md` (Claude Code) / `AGENTS.md` (Codex, others) / `.github/copilot-instructions.md` at
+the **root of the consuming project**:
+
+```markdown
+## UI: Freeday design system (@cahyo-dimas/freeday)
+
+All UI in this project is built from Freeday. It is a **token-driven CSS kit + zero-dependency JS
+enhancers**, not a component framework — components are plain markup with `fdy-*` classes.
+
+**Before writing or editing any markup/CSS, read these (they ship inside the package):**
+- `node_modules/@cahyo-dimas/freeday/COMPONENTS.md` — every class that exists, with minimal markup
+  skeletons, enhancer hooks and the a11y contract per component. **The class list is closed:
+  if a class is not in that file, it does not exist — do not invent one.**
+- `node_modules/@cahyo-dimas/freeday/USAGE.md` — the doctrine: which token/role/shadow to use when.
+- `node_modules/@cahyo-dimas/freeday/docs/reference-screen.html` — one complete screen, assembled
+  the intended way. Copy this structure for a new screen.
+
+**Non-negotiables:**
+1. No raw hex or px in app CSS. Use tokens: `var(--color-primary)`, `var(--space-4)` (4px scale),
+   `var(--radius-md)`, `var(--shadow-1)`, `var(--dur-2)`.
+2. Components only touch semantic tokens (`--color-*`) — never the primitive ramp (`--azure-600`).
+3. `.fdy-btn` is already the primary action (there is no `--primary`). One per screen; everything
+   else is `--ghost` or `--text`.
+4. Three title roles only: `.fdy-title-page` (one `<h1>`) / `.fdy-title-section` / `.fdy-title-card`.
+   Never reuse a card title as a page title.
+5. Assemble from the frame down: `.fdy-app` → `.fdy-page` → `.fdy-page-section` → components.
+6. Form errors: `aria-invalid="true"` + `aria-describedby` → a `.fdy-help.fdy-help--error`.
+   Icon-only buttons need `aria-label`. Status is never colour-only.
+7. Interactive components need their enhancer script loaded (see the table in COMPONENTS.md);
+   in an SPA, re-hydrate dynamic DOM (`useFreeday` in Vue/React does this).
+8. Freeday owns components + tokens, **not layout**. Grids/stacks/one-off gaps come from our own
+   layout layer — build its theme on `var(--space-N)` so both systems stay in step.
+```
+
+Adjust the paths if the package lives somewhere else (a workspace, a vendored copy, `wwwroot/` for
+Blazor). Then verify the agent can actually read those files — an agent that can't open
+`node_modules` will keep guessing.
+
+## 2. What ships in the package
+
+| File | What it answers |
+|---|---|
+| `COMPONENTS.md` | The complete class surface — what exists, its modifiers, minimal markup, a11y. |
+| `USAGE.md` | The doctrine — which token/role/shadow/emphasis to use when. |
+| `docs/getting-started.md` | Install + import + theme, per stack (Static HTML · Vue · React · Blazor). |
+| `docs/integrations.md` | How to bridge third-party libraries (validation, charts, dates, i18n…). |
+| `docs/reference-screen.html` | A full screen assembled from the shell down. Open it in a browser. |
+| `docs/agent-onboarding.md` | This file. |
+| `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 — linking `freeday.css` alone leaves every `var(--…)` unresolved. Plus `freeday-*.js` and the `.d.ts` files. |
+| `src/components/*.css` | The authoritative source for every class, when a doc is ambiguous. |
+| `tokens/tokens.json` | Every token in W3C DTCG format — machine-readable. |
+| `adapters/vue` · `adapters/react` · `adapters/blazor` | Typed wrappers, 10 components each. |
+
+The live docs (with an interactive playground) are at
+<https://cahyo-dimas.github.io/freeday-ui-kit/>, and the repo — including three complete example
+apps under `examples/` (Vue, React, Blazor) that are **not** in the npm tarball — is at
+<https://github.com/cahyo-dimas/freeday-ui-kit>.
+
+## 3. Starting a new screen
+
+The order matters; skipping to components is what produces flat, identical-card screens.
+
+0. **Pick the screen shape first.** Which archetype is this — dashboard, master-detail, kanban,
+   wizard, POS…? The repo's
+   [`reference/README.md`](https://github.com/cahyo-dimas/freeday-ui-kit/blob/main/reference/README.md)
+   maps 15 archetypes to the exact primitives that compose each one, and says plainly which shapes
+   the kit has **no** component for (kanban columns, calendar month grid, chat bubbles, canvas) so
+   you build the frame instead of inventing a class. Not in the npm package — read it on GitHub.
+1. **Shell** — is `.fdy-app` already in place (usually once, in the app layout)? If not, copy it
+   from `docs/getting-started.md` §The app shell.
+2. **Theme** — `data-theme="light|dark"` + `data-density="comfortable|compact"` on `<html>`, set
+   once at the root. Use `compact` for table-heavy back-office screens.
+3. **Fonts** — the package ships **no** `@font-face`. Load Sora / IBM Plex Sans / JetBrains Mono
+   yourself, or override `--font-display`/`--font-body`/`--font-mono`. Skipping this reads as
+   "unfinished design", not "missing dependency".
+4. **Page frame** — `.fdy-page` + `.fdy-page__header` (eyebrow + `.fdy-title-page` + desc on the
+   left, **one** primary action on the right).
+5. **Sections** — one `.fdy-page-section` per region, each with a `.fdy-title-section`.
+6. **Components** — from `COMPONENTS.md`, inside the sections.
+7. **Verify** — the checklist in §5.
+
+## 4. Migrating an existing UI to Freeday
+
+Migration is a **class-and-structure swap**, not a rewrite. Keep the app's DOM semantics; replace
+the styling layer. Rough equivalents — always confirm the target class in `COMPONENTS.md`, and note
+that Freeday deliberately has **no** layout/spacing utilities, so grid/flex/margin classes stay with
+your own layout layer:
+
+| Coming from | Freeday |
+|---|---|
+| `btn btn-primary` / `MudButton Variant=Filled` | `fdy-btn` |
+| `btn btn-secondary` / `btn-outline-*` | `fdy-btn fdy-btn--ghost` |
+| `btn btn-danger` | `fdy-btn fdy-btn--danger` |
+| `btn btn-link` | `fdy-btn fdy-btn--text` |
+| `btn-sm` / `btn-lg` | `fdy-btn--sm` / `fdy-btn--lg` |
+| `form-control` / `MudTextField` | `fdy-field` + `fdy-label` + `fdy-input` |
+| `form-select` / `<select>` / `MudSelect` | `fdy-combo` + `data-fdy-combo` (+ `freeday-select.js`) |
+| `invalid-feedback` / `is-invalid` | `aria-invalid="true"` + `fdy-help fdy-help--error` |
+| `input-group` / `input-group-text` | `fdy-input-group` + `__addon` / `__btn` |
+| `form-check` / `form-switch` | `fdy-check` / `fdy-radio` / `fdy-switch` |
+| `card` / `card-body` / `card-title` | `fdy-card` / `__body` / `__title` |
+| `table table-striped` / `MudTable` | `fdy-table` in `fdy-table-wrap`; interactive → `fdy-datatable` |
+| `badge bg-success` / `MudChip` (status) | `fdy-badge fdy-badge--success` |
+| `alert alert-danger` | `fdy-alert fdy-alert--danger` + `role="alert"` |
+| `modal` / `MudDialog` | `<dialog class="fdy-modal">` (native — drop the JS backdrop plumbing) |
+| `offcanvas` / `MudDrawer` | `<dialog class="fdy-drawer">` + `data-fdy-drawer` |
+| `nav nav-tabs` | `fdy-tabs` + `data-fdy-tabs` |
+| `breadcrumb` / `pagination` | `fdy-breadcrumb` / `fdy-pagination` (same `<nav><ol>` structure) |
+| `spinner-border` / `progress` | `fdy-spinner` / `fdy-progress` + `__bar` |
+| `toast` container + JS | `Freeday.toast({…})` — imperative, no markup to author |
+| `text-muted` | `fdy-text-muted` |
+| `d-none` / `visually-hidden` | `fdy-hidden` / `fdy-visually-hidden` |
+| `container` / `row` / `col-*` / `mb-3` / `gap-2` | **stays yours** — Freeday ships no layout utilities |
+
+Order of work that avoids a half-migrated mess:
+
+1. Load Freeday's CSS and **turn off the old framework's reset/preflight** — `base.css` is the
+   reset now. Two resets fighting is the usual source of "everything looks slightly off".
+2. Shell + theme attributes first, so tokens resolve everywhere.
+3. Then screen by screen: page frame → sections → controls. Convert a whole screen at a time;
+   half-converted screens can't be reviewed visually.
+4. Delete the old framework's CSS only when no screen references it, then grep for leftover class
+   prefixes.
+5. Replace hand-rolled modal/drawer/dropdown JS with the native-`<dialog>` components and the
+   enhancers — that is usually where the most code disappears.
+
+## 5. Verification checklist (before claiming a screen is done)
+
+- Every `fdy-*` class used appears in `COMPONENTS.md`. Grep the diff for `fdy-` and check.
+- No raw hex/rgb/px in the diff's CSS. Grep for `#` and `px`.
+- Exactly one `.fdy-btn` without a variant modifier on the screen; one `.fdy-title-page`.
+- Toggle `data-theme="dark"` on `<html>` — nothing becomes unreadable, no hard-coded white/black.
+- Toggle `data-density="compact"` — the layout still holds.
+- Keyboard: Tab reaches every control, focus is always visible, Esc closes overlays.
+- Form errors carry `aria-invalid` + a linked message; icon-only buttons have `aria-label`.
+- The interactive components on the screen have their enhancer loaded, and SPA-rendered DOM is
+  re-hydrated.

package/docs/getting-started.md

@@ -0,0 +1,454 @@
+# Freeday — Getting Started (per stack)
+
+A step-by-step guide to adopting Freeday in **your new project**. Pick your stack:
+
+**[Static HTML](#static-html-no-build)** · **[Vue 3 (Vite)](#vue-3-vite)** · **[React (Vite)](#react-vite)** · **[Blazor (WASM)](#blazor-wasm)**
+
+> **Component reference** (each component's exact markup + ARIA): live docs →
+> <https://cahyo-dimas.github.io/freeday-ui-kit/> (open a component section, copy its markup).
+> **Ecosystem library map & how to bridge:** [`integrations.md`](integrations.md).
+
+---
+
+## Core concepts (read once, applies to every stack)
+
+Freeday = **CSS** (semantic tokens + `fdy-*` classes) + **zero-dependency JS enhancers** (optional).
+
+1. **Static vs interactive.** Static components (button, card, badge, plain input, layout) need
+   only the **`fdy-*` classes** — no JS. Interactive components (select/combo, cascade, date/time
+   picker, table, dropzone, form validation, input mask, chip) need the **JS enhancers**.
+2. **The enhancer is the source of truth.** You don't re-implement components; the enhancer owns
+   the widget's DOM. You **listen for `fdy-*` events** (all bubbling `CustomEvent`s, data in
+   `event.detail`) → store them in your framework state. Event/API contract table:
+   [`integrations.md` §Event & API contract](integrations.md).
+3. **Hydrate dynamic DOM.** Enhancers auto-init once on `DOMContentLoaded`. DOM an SPA renders
+   **after** that must be re-hydrated: `window.Freeday<X>.initAll(el)` (idempotent, safe to repeat).
+   Each framework's adapter wraps this — you don't call it manually.
+4. **Theme via `data-*` on `<html>`.** `data-theme="light|dark"` (all semantic tokens switch) +
+   `data-density="comfortable|compact"` (control height, for data-dense screens). Change at runtime:
+   `document.documentElement.dataset.theme = 'dark'`.
+5. **3-tier token rule.** Components only touch **Tier 2/3** (`var(--color-primary)`,
+   `var(--space-4)`, `var(--radius-md)`…). **Never** write raw hex/px.
+6. **Scope: components + tokens, deliberately *not* layout.** Freeday ships components and tokens;
+   the only layout helpers are `.fdy-hidden` / `.fdy-visually-hidden`. Stacks, grids, gaps and sizing
+   come from **your** layout layer — pair Freeday with a utility framework (Tailwind, UnoCSS…) run
+   **utilities-only, preflight OFF** (Freeday's `base.css` is your reset). Two consequences worth
+   knowing up front:
+   - **base.css is a *light* reset** — it does not strip `ul`/`ol`/`p` margins. With preflight off, a
+     semantic `<ul>` keeps native bullets + a 40px indent; add **`.fdy-list-reset`** (or use a Freeday
+     list component) on such lists.
+   - **The spacing scale is public.** `--space-0`…`--space-24`, `--radius-*`, `--dur-*` etc. are real
+     custom properties in `dist/freeday.tokens.css` — **define your utility theme in terms of them**
+     (`spacing: { 4: 'var(--space-4)' }`) so both systems stay in step. `data-density="compact"` steps
+     `--control-h` **and** the mid-range spacing scale (`--space-3`…`--space-6`), so Freeday components
+     densify — and if your utility theme is built on `var(--space-N)`, density reaches your utilities too.
+7. **Load the fonts — the package does not.** The type tokens *name* **Sora** (display), **IBM Plex
+   Sans** (body) and **JetBrains Mono** (data), but Freeday bundles no `@font-face` and no font files.
+   Load them yourself, or the kit renders in the system fallback — which reads as "unfinished design",
+   not "missing dependency". One line with [Fontsource](https://fontsource.org):
+   ```css
+   @import '@fontsource/sora/600.css'; @import '@fontsource/sora/700.css';
+   @import '@fontsource-variable/ibm-plex-sans'; @import '@fontsource/jetbrains-mono/500.css';
+   ```
+   (Or a `<link>` to your own self-hosted copies, or override `--font-display`/`--font-body`/`--font-mono`
+   to faces you already ship. If you keep a system-sans fallback, consider softening
+   `--tracking-tighter` on headings — it's tuned for Sora's proportions.)
+8. **Start from the shell, then compose.** Every application goes inside **`.fdy-app`** (see below);
+   inside it, assemble screens from the composition primitives — `.fdy-page`, `.fdy-page__header`,
+   `.fdy-page-section`, `.fdy-toolbar`, `.fdy-stats`/`.fdy-stat` — and the type roles (`.fdy-title-page`
+   / `-section` / `-card`), not by re-using `.fdy-card__title` for everything. **Which token/role/shadow
+   to use when lives in [`USAGE.md`](../USAGE.md)** — read it once; it's what makes screens cohere.
+
+---
+
+## The app shell (start here)
+
+Every Freeday application goes inside **`.fdy-app`** — the frame that holds a top bar, a sidebar, and
+the scrolling content. Don't hand-roll one from flexbox; the responsive sidebar + backdrop are built in.
+The nav toggle is one line: toggle `.fdy-app--nav-open` (mobile drawer) / `.fdy-app--nav-collapsed`
+(desktop) on the `.fdy-app` element from the `__navtoggle` button's click.
+
+The nesting is not free-form — `.fdy-app` is a flex **row** of `[sidebar | content]`, and `__content`
+is the column that holds the topbar and the main area (it gives the sticky topbar a tall containing
+block to travel in). The brand belongs in the **sidebar**, sized to match the topbar's height:
+
+```html
+<div class="fdy-app">
+  <a class="fdy-skip" href="#main">Skip to content</a>
+
+  <aside class="fdy-app__sidebar">
+    <a class="fdy-app__brand" href="/">
+      <span class="fdy-app__brand-mark"><!-- logo --></span>
+      <span class="fdy-app__brand-text">
+        <span class="fdy-app__brand-title">Acme</span>
+        <span class="fdy-app__brand-subtitle">Finance</span><!-- optional -->
+      </span>
+    </a>
+    <nav class="fdy-nav"><!-- .fdy-nav__item … --></nav>
+  </aside>
+
+  <div class="fdy-app__content">
+    <header class="fdy-app__topbar">
+      <button class="fdy-app__navtoggle" aria-label="Toggle navigation"><!-- hamburger svg --></button>
+      <h1 class="fdy-app__title">Invoices</h1><!-- auto-spacer: what follows goes right -->
+      <!-- topbar actions … -->
+    </header>
+    <main class="fdy-app__main" id="main">
+      <!-- YOUR SCREEN: a .fdy-page … (see USAGE.md) -->
+    </main>
+  </div>
+
+  <div class="fdy-app__backdrop"></div>
+</div>
+```
+
+`.fdy-app__main` already carries the page padding (`--space-8`, `--space-5` on mobile) — don't wrap
+your screen in another padded box. The toggle's two states split at **720px**: above it,
+`.fdy-app--nav-collapsed` collapses the sidebar to zero width; at or below it,
+`.fdy-app--nav-open` slides the sidebar in as an off-canvas drawer over the backdrop. A complete,
+working version of all of this — including the toggle script — is
+[`reference-screen.html`](reference-screen.html).
+
+Then compose the screen inside `__main` with `.fdy-page` / `.fdy-page__header` / `.fdy-page-section`
+/ `.fdy-stats` and the type roles. The live **App shell** + **Sidebar menu** demos in
+[`docs/index.html`](index.html) are copy-pasteable; **[`USAGE.md`](../USAGE.md)** says which role and
+token to use where.
+
+---
+
+## Static HTML (no build)
+
+Good for plain `.html` pages / templates — no bundler, no npm.
+
+### 1. Get the dist files into your project
+`dist/` is committed, so there's no build step. Easiest way — use npm once just to download, then
+copy the files (vendor them):
+```bash
+npm i @cahyo-dimas/freeday
+cp -r node_modules/@cahyo-dimas/freeday/dist ./assets/freeday   # copy into your project
+```
+(or `git clone` the repo and copy `dist/`, or download the files one by one). The minimum you need:
+`freeday.bundle.css` (tokens + components in one) and `freeday.js` (all enhancers).
+
+### 2. Set the theme on `<html>` + link the CSS
+```html
+<!doctype html>
+<html lang="en" data-theme="light" data-density="comfortable">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <link rel="stylesheet" href="assets/freeday/freeday.bundle.css">
+</head>
+```
+> Two-file alternative: `freeday.tokens.css` (tokens) + `freeday.css` (components).
+
+### 3. Load the enhancers before `</body>`
+```html
+  <script src="assets/freeday/freeday.js" defer></script>
+  <!-- or pick per-file: freeday-select.js, freeday-table.js, freeday-datepicker.js, … -->
+</body>
+```
+
+### 4. Use `fdy-*` classes + `data-fdy-*` hooks
+```html
+<button class="fdy-btn fdy-btn--primary" type="button">Save</button>
+
+<div data-fdy-datepicker></div>   <!-- enhancer auto-inits on DOMContentLoaded -->
+```
+Listen for events as needed; for DOM you add **dynamically** after load, re-hydrate:
+```html
+<script>
+  document.addEventListener('fdy-datepicker-change', (e) => console.log(e.detail.value));
+  // after inserting new markup dynamically:
+  // window.FreedayDatepicker.initAll(containerEl);
+</script>
+```
+
+### 5. Copy component markup
+From **[`COMPONENTS.md`](../COMPONENTS.md)** (every component's classes + minimal markup, shipped in
+the package) or **[`reference-screen.html`](reference-screen.html)** for a whole assembled screen. The
+live docs also have a copy button per component.
+
+---
+
+## Vue 3 (Vite)
+
+### 1. Install
+```bash
+npm i @cahyo-dimas/freeday
+```
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.20.0"` (public npm package). `dist/` is
+committed and published → no build step; `npm ci` runs without auth.
+
+### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)
+```ts
+import { createApp } from 'vue';
+import '@cahyo-dimas/freeday/css'; // tokens + components (single file)
+import '@cahyo-dimas/freeday';     // side-effect: registers every window.Freeday* enhancer
+import App from './App.vue';
+
+createApp(App).mount('#app');
+```
+
+### 3. Set the theme on the root (`index.html`)
+```html
+<html lang="en" data-theme="light" data-density="comfortable">
+```
+
+### 4. Use `fdy-*` + hydrate via `useFreeday`
+Call `useFreeday(root)` **once** per component; put `ref="root"` on the subtree container. `fdy-*`
+events are bubbling `CustomEvent`s → use native `v-on` (`@fdy-*`) and read `event.detail` (typed).
+```vue
+<script setup lang="ts">
+import { ref, reactive } from 'vue';
+import { useFreeday } from '@cahyo-dimas/freeday/vue';
+import type { FdyCascadeChangeDetail, FdyDatepickerChangeDetail } from '@cahyo-dimas/freeday/vue';
+
+const root = ref<HTMLElement | null>(null);
+useFreeday(root); // hydrate [data-fdy-*] in the subtree, on each mount + update (idempotent)
+
+const form = reactive({ category: '', dueDate: '' });
+const onCascade = (e: Event) => { form.category = (e as CustomEvent<FdyCascadeChangeDetail>).detail.value; };
+const onDate    = (e: Event) => { form.dueDate  = (e as CustomEvent<FdyDatepickerChangeDetail>).detail.value; };
+</script>
+
+<template>
+  <div ref="root">
+    <button class="fdy-btn fdy-btn--primary" type="button">Save</button>
+    <div data-fdy-cascade    @fdy-cascade-change="onCascade">…</div>
+    <div data-fdy-datepicker @fdy-datepicker-change="onDate">…</div>
+  </div>
+</template>
+```
+
+**Gotcha:** if TypeScript complains about `import '@cahyo-dimas/freeday/css'`, make sure `env.d.ts`
+has `/// <reference types="vite/client" />`. For **Nuxt/SSR**, enhancers are client-only — wrap them
+in `onMounted`/`<ClientOnly>`.
+
+Full working example: [`examples/vue-faktur/`](../examples/vue-faktur/).
+
+---
+
+## React (Vite)
+
+### 1. Install
+```bash
+npm i @cahyo-dimas/freeday
+```
+
+### 2. Import the CSS + enhancers **once** in your entry (`src/main.tsx`)
+```tsx
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import '@cahyo-dimas/freeday/css'; // tokens + components
+import '@cahyo-dimas/freeday';     // registers every window.Freeday* enhancer
+import { App } from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode><App /></StrictMode>,
+);
+```
+
+### 3. Set the theme on the root (`index.html`)
+```html
+<html lang="en" data-theme="light" data-density="comfortable">
+```
+
+### 4. Use `fdy-*` + hydrate via the `useFreeday` hook
+React has no native `on:fdy-*` handler → since the events **bubble**, attach one set of listeners on
+`root` via `useEffect` (clean up on unmount). Read `event.detail` (typed).
+```tsx
+import { useRef, useEffect } from 'react';
+import { useFreeday } from '@cahyo-dimas/freeday/react';
+import type { FdyCascadeChangeDetail, FdyDatepickerChangeDetail } from '@cahyo-dimas/freeday/react';
+
+export function Panel() {
+  const root = useRef<HTMLDivElement>(null);
+  useFreeday(root); // hydrate subtree on mount + every commit (idempotent)
+
+  useEffect(() => {
+    const el = root.current;
+    if (!el) return;
+    const onCascade = (e: Event) => { /* (e as CustomEvent<FdyCascadeChangeDetail>).detail.value */ };
+    const onDate    = (e: Event) => { /* (e as CustomEvent<FdyDatepickerChangeDetail>).detail.value */ };
+    el.addEventListener('fdy-cascade-change', onCascade);
+    el.addEventListener('fdy-datepicker-change', onDate);
+    return () => {
+      el.removeEventListener('fdy-cascade-change', onCascade);
+      el.removeEventListener('fdy-datepicker-change', onDate);
+    };
+  }, []);
+
+  return (
+    <div ref={root}>
+      <button className="fdy-btn fdy-btn--primary" type="button">Save</button>
+      <div data-fdy-cascade />
+      <div data-fdy-datepicker />
+    </div>
+  );
+}
+```
+
+**Gotcha:** because the enhancer owns the widget DOM, don't double-control it from React — store the
+value from `event.detail` in state/ref; don't set the DOM `value` back. `StrictMode` mounts twice in
+dev; `useFreeday` is idempotent, so it's safe.
+
+### 5. Alternative: typed controlled components (`FdyCombo` · `FdyDatepicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart`)
+For fields you'd normally write as a native `<select>`/`<input type="date">`,
+`@cahyo-dimas/freeday/react` also exports typed **controlled** components — plain `value`/`onChange`,
+no manual event bubbling (parity with the Vue `v-model` components above):
+```tsx
+import { FdyCombo } from '@cahyo-dimas/freeday/react';
+import type { FdyComboOption } from '@cahyo-dimas/freeday/react';
+
+type Status = 'draft' | 'sent' | 'paid';
+const options: ReadonlyArray<FdyComboOption<Status>> = [
+  { value: 'draft', label: 'Draft' },
+  { value: 'sent', label: 'Sent' },
+  { value: 'paid', label: 'Paid' },
+];
+
+function StatusField({ value, onChange }: { value: Status; onChange: (v: Status) => void }) {
+  return <FdyCombo<Status> value={value} options={options} onChange={onChange} ariaLabelledby="lbl-status" />;
+}
+```
+`FdyDatepicker`, `FdyCfl` (async choose-from-list), and `FdyChart` share the same shape (typed
+`value`/`onChange`, or `series`/`values` for `FdyChart`) — see [`integrations.md`](integrations.md)
+and `examples/react-faktur/src/App.tsx` for the full patterns. **Vite works with no extra config**
+(esbuild transpiles the `.tsx` source directly); **Next.js** consumers may need
+`transpilePackages: ['@cahyo-dimas/freeday']` in `next.config.js`.
+
+Full working example: [`examples/react-faktur/`](../examples/react-faktur/).
+
+---
+
+## Blazor (WASM)
+
+Blazor doesn't use npm — Freeday is served as **static files** in `wwwroot/`.
+
+> **Prefer the native components?** Jump to [§4 — the `Freeday.Blazor` RCL](#4-recommended-native-typed-components-freedayblazor-rcl):
+> typed `<FdyX>` with `@bind`, no manual JS interop. Steps 1–2 (assets + scripts) still apply; step 3
+> below (the raw enhancer + event bridge) is the underlying mechanism and the fallback for markup the
+> RCL doesn't cover.
+
+### 1. Place the assets in `wwwroot/freeday/`
+Copy 3 files into `wwwroot/freeday/`: `freeday.bundle.css`, `freeday.js` (from `dist/`), and
+`freeday-blazor.js` (from `adapters/blazor/`). Manually, **or** automatically via an MSBuild target
+(put the Freeday repo near your project and adjust the path) in `.csproj`:
+```xml
+<Target Name="CopyFreedayAssets" BeforeTargets="ResolveStaticWebAssetsInputs;Build">
+  <ItemGroup>
+    <_FreedaySrc Include="PATH\dist\freeday.bundle.css;PATH\dist\freeday.js;PATH\adapters\blazor\freeday-blazor.js" />
+  </ItemGroup>
+  <Copy SourceFiles="@(_FreedaySrc)" DestinationFolder="$(MSBuildProjectDirectory)\wwwroot\freeday" SkipUnchangedFiles="true" />
+</Target>
+```
+
+### 2. Set the theme + load the assets in `wwwroot/index.html`
+Load `freeday.js` then `freeday-blazor.js` **before** `blazor.webassembly.js`:
+```html
+<html lang="en" data-theme="light" data-density="comfortable">
+<head>
+  <link rel="stylesheet" href="freeday/freeday.bundle.css" />
+</head>
+<body>
+  <div id="app">Loading…</div>
+  <script src="freeday/freeday.js"></script>
+  <script src="freeday/freeday-blazor.js"></script>
+  <script src="_framework/blazor.webassembly.js"></script>
+</body>
+```
+> Use the global IIFE (`window.FreedayBlazor`), **not** an ES module — so it passes strict-MIME on static hosts.
+
+### 3. Hydrate + bridge events in code-behind (`.razor.cs`)
+In `OnAfterRenderAsync(firstRender)`: `initAll`, then `on(...)` per event → `[JSInvokable]` methods.
+Release them in `DisposeAsync`.
+```csharp
+public partial class Panel : ComponentBase, IAsyncDisposable
+{
+    [Inject] private IJSRuntime JS { get; set; } = default!;
+    private ElementReference _root;
+    private DotNetObjectReference<Panel>? _self;
+    private readonly List<int> _tokens = new();
+
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (!firstRender) return;
+        await JS.InvokeVoidAsync("FreedayBlazor.initAll", _root);   // hydrate the Blazor markup
+        _self = DotNetObjectReference.Create(this);
+        _tokens.Add(await JS.InvokeAsync<int>("FreedayBlazor.on", _root, "fdy-cascade-change", _self, nameof(OnCascade)));
+        _tokens.Add(await JS.InvokeAsync<int>("FreedayBlazor.on", _root, "fdy-datepicker-change", _self, nameof(OnDate)));
+    }
+
+    [JSInvokable] public void OnCascade(CascadeDetail d) { /* d.Value / d.Path */ StateHasChanged(); }
+    [JSInvokable] public void OnDate(ValueDetail d)      { /* d.Value */ StateHasChanged(); }
+
+    public async ValueTask DisposeAsync()
+    {
+        foreach (var t in _tokens)
+            try { await JS.InvokeVoidAsync("FreedayBlazor.off", t); } catch (JSDisconnectedException) { }
+        _self?.Dispose();
+    }
+
+    public sealed record CascadeDetail(string Value, string Path, string[] Labels);
+    public sealed record ValueDetail(string Value);
+}
+```
+```razor
+@* Panel.razor — @ref on the subtree container, fdy-* classes + data-fdy-* hooks in the markup *@
+<div @ref="_root">
+  <button class="fdy-btn fdy-btn--primary" type="button">Save</button>
+  <div data-fdy-cascade></div>
+  <div data-fdy-datepicker></div>
+</div>
+```
+Extras: `FreedayBlazor.toast(new { variant, title, message })` for toasts; `FreedayBlazor.toggleTheme()`
+to flip the theme. Event DTOs are deserialized case-insensitively by Blazor.
+
+### 4. Recommended: native typed components (`Freeday.Blazor` RCL)
+
+Instead of hand-writing `fdy-*` markup + the interop above, reference the **Razor Class Library** and
+use typed `<FdyX>` components with `@bind` — the Blazor equivalent of the Vue `v-model` / React
+`value`/`onChange` adapters. Place the Freeday repo near your solution and add a project reference:
+```xml
+<!-- YourApp.csproj -->
+<ProjectReference Include="PATH\adapters\blazor\Freeday.Blazor.csproj" />
+```
+```razor
+@* _Imports.razor *@
+@using Freeday.Blazor
+```
+Load `freeday.js` + `freeday-blazor.js` exactly as in step 2 (the components still hydrate over the
+kit's CSS/enhancers), then bind:
+```razor
+@* Invoice.razor — no @ref, no manual JS interop, no [JSInvokable] *@
+<FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl-status" />
+<FdyDatepicker @bind-Value="_dueDate" Label="Due date" />
+<FdyTable TRow="Invoice" Columns="_cols" Rows="_rows" RowKey="@(i => i.Code)"
+          PageSize="10" RowActivatable="true" RowActivate="OpenDetail" />
+<FdyChart Type="donut" Values="_byCity" Labels="_cityLabels" AriaLabel="Revenue by city" />
+<FdyDrawer @bind-Open="_drawerOpen" Title="Detail" Side="right">…</FdyDrawer>
+```
+Ten components at parity with the Vue/React adapters: **`FdyModal`** · **`FdyDrawer`** (`@bind-Open`,
+`Title`, `Size`/`Side`, `Dismissible`) · **`FdyCombo<TValue>`** · **`FdyDatepicker`** ·
+**`FdyAutocomplete`** · **`FdyCascade`** · **`FdyDateRange`** (`@bind-From`/`@bind-To`) ·
+**`FdyCfl<TRow>`** (async `LoadPage`) · **`FdyChart`** · **`FdyTable<TRow>`** (client sort/filter/page,
+or controlled `Sort`/`Filters`/`Page` for a server-paged table; `RowActivatable`, `RowDetail`). Each
+`select`-type control also takes `Disabled`/`Readonly`/`Invalid`. The RCL targets **net8.0** and is
+consumed as source (`<ProjectReference>`); `.NET bin/obj` never ships in the npm tarball.
+
+Full working example (all ten): [`examples/blazor-faktur/`](../examples/blazor-faktur/) —
+`Pages/ComponentsDemo.razor`.
+
+---
+
+## Verify (every stack)
+
+Run the project → check two things:
+1. **CSS connected** — buttons/cards are styled (not plain HTML).
+2. **Enhancers connected** — interactive components come alive (e.g. datepicker/combo open on
+   click), and `event.detail` reaches your state.
+
+If the visuals are plain → the CSS didn't load. If visuals are fine but widgets are dead → the
+enhancers aren't hydrated (make sure `import '@cahyo-dimas/freeday'` / `<script freeday.js>` is
+present, and the adapter/`initAll` is called for dynamic DOM).