@cahyo-dimas/freeday 2.2.0 → 3.0.0

package/CHANGELOG.md

@@ -9,6 +9,183 @@ benar. Perubahan seperti itu ditulis di bawah `### Changed: BREAKING (types)`
 lama → tipe baru, dan cara menyempitkannya — bukan di bawah `### Added`, betapapun aditifnya dari
 sisi kit.
 
+## [3.0.0] - 2026-08-26
+
+**Kenapa MAJOR padahal rilis ini seluruhnya aditif.** Tak ada satu pun perubahan di bawah yang
+mematahkan konsumen: prop-nya opsional, class-nya baru, dan `fdy-step-before-change` tanpa listener
+berperilaku persis seperti sebelumnya. Secara semver murni ini MINOR. Nomor mayor diambil sebagai
+keputusan pemilik untuk **membuka lini adopsi back-office** yang dispesifikasikan di
+[`docs/superpowers/specs/2026-08-26-back-office-adoption-design.md`](docs/superpowers/specs/2026-08-26-back-office-adoption-design.md):
+delapan item, empat di antaranya terkirim di sini, dan **paruh yang benar-benar breaking masih di
+depan** — sumbu `data-style` mengubah arti atribut yang sudah terdokumentasi, `FdyTableColumn`
+melebar untuk edit sel, `FdyAppShell` mendapat mode nav baru. Konsumen 2.x bisa naik ke 3.0.0 tanpa
+mengubah satu baris pun.
+
+### Added
+- **Row selection terkontrol di keempat stack** (`NEXT-UP.md` #3). Enhancer vanilla sudah punya
+  `.fdy-table-bulkbar` + kolom pilih sejak awal; adapter typed tidak, jadi tiap layar list yang
+  butuh aksi massal merakit kolom checkbox sendiri di samping tabel terkontrol. Kini `selectable` +
+  `selectedKeys` di Vue/React/Blazor, ber-key `rowKey` — identitas yang sudah dipakai
+  `expandedKeys`, karena sebuah key selamat dari re-fetch yang mengganti seluruh objek baris,
+  sedangkan identitas objek tidak. Select-all menyentuh **halaman yang terlihat**, bukan seluruh
+  hasil filter: checkbox header yang diam-diam memilih baris yang tak bisa dilihat pembaca adalah
+  cara bulk delete jadi bencana. Key dari halaman lain dipertahankan, jadi hitungan di bulk bar
+  bisa lebih besar dari jumlah baris di layar — didokumentasikan, karena kalau tidak terbaca
+  seperti bug.
+- **`.fdy-table--striped`** + prop `striped` di keempat adapter, plus token Tier-3
+  `--fdy-table-stripe`. Warnanya **setengah** langkah surface, bukan langkah penuh yang dipakai
+  hover: stripe dengan warna hover membuat hover tak terlihat di setiap baris genap. Kolom beku
+  ikut dicat ulang, karena sel beku membawa background opak sendiri.
+- **`Freeday.busy()` / `Freeday.idle()`** — overlay yang menghalangi layar selama operasi yang tak
+  boleh diinterupsi. Imperatif seperti `toast()`, dan alasannya lebih tajam: API komponen mengundang
+  dua instans, dan dua scrim dengan dua caption dari dua komponen yang sama-sama merasa memiliki
+  layar adalah kegagalan yang komponen ini cegah. Bukan dialog — tak ada yang ditanyakan dan tak ada
+  yang bisa ditutup, jadi interaksi dicabut dengan `inert`, bukan dengan focus trap. Jeda default
+  120 ms supaya operasi 80 ms tak mengedipkan scrim, dan `idle()` membatalkan tampilan yang masih
+  tertunda alih-alih menyembunyikannya setelah terlanjur terlihat.
+- **Token semantic `--color-scrim`**, sengaja identik di light dan dark: scrim menggelapkan apa pun
+  di belakangnya, jadi ia tak ikut membalik bersama palet.
+- **`.fdy-step__badge`** dan status `is-error` stepper yang **sudah ada di CSS tapi tak
+  terdokumentasi**, sehingga tak terjangkau siapa pun. Label kini ikut ke danger, dan badge memuat
+  jumlahnya — karena cincin merah bilang "ada sesuatu" dan tak mengatakan apa-apa kepada pembaca
+  yang tak bisa melihat merah. Badge adalah **saudara** marker, bukan anaknya: enhancer menulis
+  ulang `__marker.innerHTML` di tiap render.
+- **`fdy-step-before-change`**, event cancelable yang membuat Lanjut bisa ditolak. Event saja tak
+  cukup — validasi biasanya sejauh satu round-trip — jadi handler bisa `preventDefault()` **atau**
+  menitipkan promise ke `detail.waitFor`. Selama promise itu tertunda kedua tombol nav dinonaktifkan
+  dan header membawa `aria-busy`. Menjawab apa pun selain `false` meneruskan (handler yang lupa
+  `return` bukan penolakan), dan guard yang **melempar** tak meneruskan apa pun karena ia tak
+  memutuskan apa pun. Mundur tak pernah ditanya; lompat maju ke langkah yang sudah dicapai ditanya.
+  **Cara validitas diputuskan tetap milik aplikasi** — kit tak berpendapat soal library form, dan
+  event inilah batasnya.
+- **`FreedayBlazor.setIndeterminate`**, satu helper interop, karena `indeterminate` adalah properti
+  DOM tanpa atribut HTML: renderer Blazor tak bisa mengekspresikannya, dan halaman yang separuh
+  terpilih akan tampil polos "belum tercentang".
+- **Mode nav overlay di layar lebar** — `.fdy-app--nav-overlay`, dan `navMode` di keempat adapter
+  (Blazor: enum `FdyNavMode`). Nav mengambang di atas konten alih-alih menggesernya, yaitu pilihan
+  yang selama ini hanya bisa terjadi di layar sempit. **Modifier ini mengubah tata letak, bukan
+  perilaku**: backdrop, Escape, tutup-saat-link-diikuti, fokus masuk-dan-kembali, `inert`, dan Tab
+  trap semuanya jalur kode drawer yang sudah ada — shell kini bertanya pada sebuah class, bukan pada
+  media query, sehingga layar lebar tak lagi berarti "kolom". Konsekuensinya melintasi breakpoint
+  **tidak** menutup panel yang mengambang di kedua sisi. `FreedayAppShell.refresh(root)` ditambahkan
+  untuk jalur mentah yang mengubah class itu sendiri.
+
+- **Sumbu palet primary: `data-primary`, 18 pilihan.** `azure` (default) · `sky` `blue` `indigo`
+  `violet` `purple` `fuchsia` `pink` `rose` · `orange` `amber` `yellow` `lime` `green` `emerald`
+  `teal` `cyan` · `noir`. Dipasang di mana pun `data-theme` bisa, termasuk di wrapper untuk
+  me-rebrand satu region.
+
+  Yang di-redefinisi sebuah palet adalah **ramp alias delapan shade**, bukan token semantic-nya.
+  Pemetaan "shade mana yang jadi fill, mana hover, mana wash" ditulis **sekali** di `color.primary*`,
+  jadi palet yang salah memetakan salah satunya bukan bentuk yang bisa dihasilkan sistem ini — dan
+  `--color-primary`, `-hover`, `-active`, `-soft`, `-border`, `-strong` serta `--focus-ring`
+  semuanya ikut, di kedua tema, tanpa apa pun untuk disetel.
+
+  **Ke-18 dijaga gerbang kontras di kedua tema**: label di atas fill (AA 4.5), fill terhadap surface
+  dan cincin fokus (1.4.11, 3:1), dan `primary-strong` di atas wash-nya sendiri di atas ketiga
+  surface. 36 kombinasi, dan tiga hasilnya **dipaksa oleh pengukuran, bukan selera**: `yellow`
+  memakai fill lebih gelap di tema terang (di shade aslinya cuma 2.94:1 di atas putih, di bawah
+  ambang untuk sebuah fill UI) dan karena itu berlabel putih sementara semua palet hangat lain
+  berlabel gelap; `indigo` dan `violet` bergeser satu langkah lebih terang di tema gelap, karena di
+  shade tengahnya tak ada — putih maupun mendekati-hitam — yang mencapai 4.5:1. Ketiganya
+  didokumentasikan, karena tanpa penjelasan mereka terlihat seperti kekeliruan.
+
+  `noir` bukan hue: ia mengarahkan ramp alias ke ramp netral, jadi "primary" jadi mendekati hitam di
+  terang dan mendekati putih di gelap.
+
+- **Sumbu gaya visual: `data-style="soft | glass"`.** `soft` default dan tampilan kit selama ini;
+  `glass` memfrost **permukaan terangkat** — card, modal, drawer, menu, appbar, sidebar & topbar app
+  shell. Dipasang di mana pun `data-theme` bisa, dan `[data-style="soft"]` adalah **rule sungguhan**,
+  jadi satu region bisa keluar dari root yang kaca. Sumbu ini menyerap toggle glass yang selama ini
+  jadi fitur terpisah di app konsumen: satu sumbu dua nilai, bukan empat kombinasi yang dua di
+  antaranya tak punya definisi visual.
+
+  Yang difrost adalah `--color-surface-raised`, **bukan `--color-surface`**: token itu juga isian
+  input, chip, sel tabel dan **kolom beku**, dan kolom beku yang tembus pandang memperlihatkan baris
+  yang menggulung di bawahnya. Komponen tak membawa selector `[data-style]` sama sekali; mereka
+  membaca tiga knob yang no-op di `soft` — `--color-surface-raised`, `--surface-filter`,
+  `--surface-inset`.
+
+  **Seberapa tembus kaca boleh jadi ditentukan gerbang kontras, bukan selera.** Di bawah `.82`
+  (terang) / `.90` (gelap), tinta muted dan `primary-strong` berhenti lolos 4.5:1 begitu panel
+  dikomposit di atas latar sembarang. Gerbangnya sengaja diuji terhadap **dua ekstrem — di atas hitam
+  dan di atas putih** — bukan terhadap warna halaman kit sendiri: versi pertama memakai warna halaman,
+  dan panel empat kali lebih tembus pun lolos, jadi gerbangnya nyaris hampa. Konsekuensinya jujur:
+  kaca di sini **halus**, dan frost yang terlihat datang dari blur-nya, bukan dari alpha-nya.
+
+### Fixed
+- **`--color-surface-raised` tak ikut saat satu subtree di-gelapkan.** Custom property beralias
+  `var(--color-surface)` di-compute di tempat ia dideklarasikan, jadi tanpa nilai `$dark` sendiri ia
+  membeku pada permukaan terang dan sebuah `.fdy-card` di dalam panel `data-theme="dark"` tetap
+  mengecat terang. Ditangkap spec browser `theme.mjs` yang sudah ada, bukan oleh review.
+- **`resolveValue` melewatkan referensi token di dalam ekspresi.** Pola lamanya mengikat seluruh
+  string, jadi `{primary.600}` di dalam `color-mix(...)` lolos mentah ke stylesheet sebagai teks
+  literal. Ketahuan saat wash `-soft` gelap diturunkan dari alias alih-alih memaku warna azure.
+- **Gerbang kontras memipihkan alpha-nya sendiri.** Cabang `color-mix` mengembalikan `a: 1` apa pun
+  masukannya, jadi setiap wash `-soft` diuji seolah-olah opak — kekeliruan yang justru merupakan
+  hal yang pasangan `-soft` itu ada untuk menangkapnya, bersembunyi di dalam alatnya. Kini
+  premultiplied dan alpha-nya dibawa keluar.
+- **`--focus-ring` menunjuk ramp brand langsung**, jadi cincin fokus akan tetap biru di aplikasi
+  yang memilih palet hijau. Kini ikut alias primary.
+- **`CLAUDE.md` mengklaim `data-style` sudah ada.** Grep ke `src/`, `dist/` dan `tokens/`
+  mengembalikan nol: kit belum punya sumbu gaya sama sekali, dan `soft` adalah deskripsi tampilan,
+  bukan sebuah nilai. Spec `2026-07-21` §6 juga menyebut knob `--blur`/`--sat`/`--inset`
+  "dicadangkan, default no-op" — ketiganya tak pernah dibuat. Keduanya kini dikoreksi, karena klaim
+  palsu di dokumen menaikkan estimasi pekerjaan yang bergantung padanya.
+- **`.fdy-busy__panel` disamakan dengan doktrin elevasi** (`USAGE.md`): panel di atas scrim adalah
+  kerabat modal, jadi `--shadow-lift`, bukan `--shadow-3` yang dipakai benda melayang di atas
+  halaman.
+- **Backdrop app-shell menelan klik selama transisinya.** `visibility` adalah properti yang
+  di-transisi, jadi backdrop yang sedang menghilang tetap `visible` sepanjang durasinya dan terus
+  menangkap klik yang ditujukan ke topbar di bawahnya — dan masuk ke mode overlay lebih buruk lagi,
+  karena elemennya berpindah `display:none` → `display:block` dengan visibility beranimasi dari
+  `visible` bawaan, sehingga **sekadar mengganti mode memberi halaman ~200 ms klik mati**. Terukur:
+  `elementFromPoint` di atas tombol nav mengembalikan backdrop-nya. Kini `pointer-events:none`
+  selama tertutup, di jalur mobile maupun overlay. Spec app-shell yang lama sudah menyebut gejala
+  ini dan menyiasatinya dengan menunggu; ini menghapus sebabnya.
+- **Backdrop mobile berhenti memakai warna mentah** (`rgba(8,10,20,.45)`), nilai kasar terakhir yang
+  tersisa di stylesheet komponen. Kini `--color-scrim`, jadi ia menggelap persis seperti overlay lain.
+
+### Guarded
+- **Harness Blazor Server + prerender yang sungguhan** (`test/blazor-server/`, `npm run
+  test:blazor-server`) — host Blazor Server betulan, bukan double bUnit, digerakkan lewat CDP. bUnit
+  merender in-process dengan JS runtime tiruan, jadi setiap test Blazor selama ini **berangkat dari
+  dunia di mana interop sudah bekerja**; justru itu yang tak bisa menjawab `NEXT-UP` #2. **4/4
+  hijau**: prerender mengeluarkan markup penuh tanpa satu pun penanda hidrasi, enhancer hidrat begitu
+  circuit tersambung, `<dialog>` yang dibuka dari .NET benar-benar terbuka lalu tertutup Escape, dan
+  combo yang dipilih dengan mouse asli sampai ke binding .NET.
+
+  **Satu check sempat merah dan sempat dilaporkan sebagai cacat kit. Ia bukan cacat kit.** Enhancer
+  auto-init saat `DOMContentLoaded`, jadi mereka menstempel `data-fdy-*-ready` pada markup
+  **prerender yang sebentar lagi dibuang** Blazor ketika circuit tersambung. Test yang menunggu
+  penanda itu menunggu hal yang salah, dan klik-nya mendarat di node yang akan dilepas — persis
+  gejala "node dilepas, bukan fokus berpindah" yang terukur. Menunggu komponen benar-benar interaktif
+  membuatnya hijau, 3 dari 3 run. Pelajarannya tetap berlaku meski cacatnya tidak ada: **di bawah
+  prerendering, penanda hidrasi bisa benar tentang DOM yang tak punya masa depan.**
+- 4 test node baru (invariant urutan stripe + warnanya), 11 test Chrome baru (selection lintas
+  halaman & non-aktivasi baris, `inert` yang mendarat **dan dilepas**, operasi cepat yang tak
+  melukis apa pun, guard stepper yang menolak), 7 test bUnit baru. **Setiap invariant diverifikasi
+  dengan mutasi**, bukan hanya dijalankan sekali.
+- node 68 → 113 · browser 83 → 92 · bUnit 14 → 21 · **suite baru** blazor-server 4.
+
+### Fixed: the kit's own suite
+- **A coordinate click now reaches its target on a window that is not the author's.** CI went red
+  on a **docs-only** commit — five lines of `HANDOFF.md` — with three unrelated specs failing at
+  once: the stretched card target, the app shell's wide toggle, and the Vue combo's mouse select.
+  All three click at coordinates. The tree that failed differs from the tree that passed by nothing
+  a browser can see, so the cause was the runner's window, not the commit: a target below the fold
+  is clicked where nobody can see it, `elementFromPoint` there is `null`, the click reaches nothing,
+  and the run reports whatever assertion came three lines later. `clickCenter` scrolls the target
+  into view before measuring, and refuses an empty point with an error naming the viewport and the
+  element's rect. Demonstrated on the real failure mode: with the target pushed below a 420×240
+  window the point is provably empty, and the click lands anyway.
+- **`browser/harness-contract.mjs`** (2 tests) pins both halves, because a harness that quietly
+  stops clicking is the one bug the rest of the suite cannot report.
+- An earlier attempt at this also rejected *intercepted* clicks and was reverted: `.fdy-btn--stretch`
+  covers its card through an `::after` pseudo-element that `getBoundingClientRect` cannot see, so
+  the check fired on two tests that were asserting exactly that behaviour. A check with false
+  positives on a documented pattern is worse than no check.
+
 ## [2.2.0] - 2026-08-26
 ### Added
 - **The raw path can disable, lock and invalidate a picker** (`NEXT-UP.md` #12). `datepicker.css`

package/COMPONENTS.md

@@ -126,6 +126,7 @@ which is why React's list is longer while offering the same thing.
 |---|---|---|
 | `navOpen?` | `boolean` | Whether the nav is visible. Optional because the default is the **viewport's**, and a caller cannot state that in one initial value. Vue binds `v-model:navOpen`. |
 | `onNavOpenChange?` | `(open: boolean) => void` | React. Visibility changed: the toggle, Escape, the backdrop, or a followed nav item. Vue emits `update:navOpen`. |
+| `navMode?` | `'push' \| 'overlay'` | How a **visible** nav sits on a **wide** viewport: `push` (default) is the column that displaces the content, `overlay` floats it over the page with a backdrop. Below the nav breakpoint it is ignored — the nav is off-canvas there by definition, so there is nothing to choose. Blazor takes the enum `FdyNavMode`. |
 | `title?` | `string` (Vue) · `ReactNode` | Topbar title. |
 | `toggleLabel?` | `string` | Accessible name for the nav toggle button. |
 | `toggleIcon?` | `ReactNode` | React. Replaces the default hamburger; Vue uses the slot of that name. |
@@ -141,8 +142,18 @@ off-canvas drawer and backdrop are built in.
 
 - Parts: `__sidebar` `__brand` (`__brand-mark` `__brand-text` `__brand-title` `__brand-subtitle`)
   `__content` `__topbar` `__navtoggle` `__title` `__main` `__backdrop`
-- Modifiers: `--nav-open` (mobile drawer open, ≤720px) · `--nav-collapsed` (collapse to zero width,
-  ≥721px) · `--static` (embed the shell in a page instead of filling the viewport)
+- Modifiers: `--nav-open` (drawer open) · `--nav-collapsed` (collapse to zero width, ≥721px) ·
+  `--nav-overlay` (≥721px: float the nav over the content instead of displacing it) · `--static`
+  (embed the shell in a page instead of filling the viewport)
+
+**`--nav-overlay` is a layout choice, not a second behaviour.** With it the nav floats at *every*
+width, so the drawer's whole code path — backdrop, Escape, close-on-follow, focus into the panel and
+back, `inert` on the content, the Tab trap — is reused rather than re-implemented; only the
+positioning rules differ, and only above the breakpoint. It also changes which state class means
+"visible": `--nav-open` instead of the absence of `--nav-collapsed`, exactly as on a narrow screen.
+On the raw path, if you add or remove the class yourself, call
+**`FreedayAppShell.refresh(root)`** afterwards — the shell has to re-read the DOM, or `inert` and
+`aria-expanded` keep describing the arrangement you just left.
 - Also: `.fdy-skip`, the skip-to-content link, first child of the shell.
 - **Behaviour: `freeday-app-shell.js`.** Opt in with `data-fdy-app` on the root. The markup below
   is unchanged. It owns the toggle in both modes plus everything an overlay needs that hand-rolling
@@ -278,6 +289,57 @@ sidebar from off-canvas drawer to static column at 721px, *not* at `md`. Any `ma
 utility variant that has to agree with the shell must use `nav`; using `md` leaves 721–959px broken
 (sidebar already static while your script still treats it as an overlay).
 
+**Visual style: `data-style="soft | glass"`.** `soft` is the default and the look the kit has always
+had; `glass` frosts the **raised** surfaces — card, modal, drawer, menu, appbar, the app shell's
+sidebar and topbar. Set it wherever `data-theme` goes, and `[data-style="soft"]` is a real rule, so a
+region can opt back **out** of a glass root.
+
+```html
+<html data-style="glass">
+<section data-style="soft"><!-- this region stays flat --></section>
+```
+
+It frosts `--color-surface-raised`, **never `--color-surface`** — that token is also the fill of
+inputs, chips, table cells and frozen columns, and a translucent frozen column shows the rows
+scrolling underneath it. Components carry no `[data-style]` selector of their own; they read three
+knobs that are no-ops under `soft`: `--color-surface-raised`, `--surface-filter` (the
+`backdrop-filter` value) and `--surface-inset` (a hairline top edge, chained onto the panel's
+shadow). A component that cannot follow the axis through those is reporting a **missing token**, not
+asking for a rule.
+
+**How transparent glass may be is decided by the contrast gate, not by taste.** Below `.82` in light
+and `.90` in dark, muted text and `primary-strong` stop clearing 4.5:1 once the panel is composited
+over an arbitrary ground — measured, and asserted against the two extremes (over black and over
+white) rather than against the kit's own page colour, which is close enough to the panel's own
+lightness that a panel four times more transparent still passed. So glass here is a **subtle** frost:
+the effect people actually see comes from the blur, not from the alpha. Put a photo or a gradient
+behind a panel and the promise still holds; that is what "over any ground" buys.
+
+**Primary palette: `data-primary`.** 18 options — `azure` (the default, and what you get with no
+attribute) · `sky` `blue` `indigo` `violet` `purple` `fuchsia` `pink` `rose` · `orange` `amber`
+`yellow` `lime` `green` `emerald` `teal` `cyan` · `noir`. Set it anywhere `data-theme` works,
+including on a wrapper to re-brand one region:
+
+```html
+<html data-primary="emerald" data-theme="dark">
+```
+
+A palette redefines an eight-shade **alias ramp**, never the semantic tokens. Which shade is the
+fill, which is hover, which is the soft wash is stated once in the token source, so a palette cannot
+disagree with the others about what "primary" means — and `--color-primary`, `--color-primary-hover`,
+`--color-primary-soft`, `--color-primary-border`, `--color-primary-strong` and `--focus-ring` all
+follow, in both themes, with nothing to wire.
+
+**Every palette is contrast-gated, and two carry an exception the gate forced.** All 18 are asserted
+in both themes for the label on a primary fill (AA 4.5), the fill against the surface and the focus
+ring (1.4.11, 3:1), and `primary-strong` on its soft wash over all three surfaces. Three results
+worth knowing, because they look like mistakes otherwise: `yellow` uses a **darker** fill in light
+than the other palettes (at its natural shade it is 2.94:1 on white — below the floor for a UI
+fill), and takes a **white** label there while every other warm palette takes a dark one; `indigo`
+and `violet` shift one step lighter in dark, because at their mid shade neither white nor near-black
+reaches 4.5:1. `noir` is not a hue at all — it re-points the alias ramp at the neutral ramp, so
+"primary" becomes near-black in light and near-white in dark.
+
 Density: `data-density="compact"` works on `<html>` **or any wrapper**, because the selector is a bare
 `[data-density="compact"]` over inheriting custom properties, so one screen can be dense while the
 rest of the app is not. `data-density="comfortable"` is a real rule too, so the reverse also works:
@@ -853,11 +915,42 @@ variant is `role="img"` + `aria-label`; each interactive star needs a `.fdy-visu
 Linear multi-step flow: marker → check, one panel at a time, back/next. Needs
 `freeday-stepper.js`.
 
-- `.fdy-stepper` (`<ol>`) of `.fdy-step` (`is-active` / `is-complete` set by JS) ·
-  `.fdy-step__btn` `__marker` `__label`
+- `.fdy-stepper` (`<ol>`) of `.fdy-step` (`is-active` / `is-complete` set by JS, `is-error` set by
+  **you**) · `.fdy-step__btn` `__marker` `__badge` `__label`
 - `.fdy-step-panels` wrapping one `.fdy-step-panel` per step (`hidden` on the inactive ones)
 - `.fdy-step-nav` with `data-fdy-step-prev` / `data-fdy-step-next` buttons
 
+**A step with problems: `is-error` + `__badge`.** The marker turns danger and the label with it,
+but colour is never the carrier — put the count in `.fdy-step__badge` and name it in text, because
+a red ring says "something" and a reader who cannot see red is told nothing at all. The badge is a
+**sibling** of the marker, not a child: the enhancer rewrites the marker's contents on every render,
+so a badge inside it would vanish the first time the reader moved a step.
+
+```html
+<li class="fdy-step is-error">
+  <span class="fdy-step__marker">2</span>
+  <span class="fdy-step__badge" aria-hidden="true">3</span>
+  <span class="fdy-step__label">Lines <span class="fdy-visually-hidden">— 3 problems</span></span>
+</li>
+```
+
+**Leaving a step is refusable.** Next, and a forward jump to an already-reached step, both fire a
+cancelable `fdy-step-before-change` (`detail: { from, to, waitFor }`). Going *back* never asks —
+nothing is being committed.
+
+```js
+el.addEventListener('fdy-step-before-change', (e) => {
+  e.preventDefault();                    // refuse now, when the answer is already known
+  e.detail.waitFor = validate(e.detail.from);  // …or defer: a promise resolving false refuses
+});
+```
+
+The enhancer disables both nav buttons and sets `aria-busy` on the `.fdy-stepper` while a promise is
+outstanding, so a second click has nothing to aim at. Resolving to anything but `false` advances —
+a handler that forgets to return is not read as a rejection — and a guard that **throws** advances
+nothing, since it decided nothing. **How validity is decided stays with you**: the kit takes no
+opinion on form libraries, and this event is the line that keeps it that way.
+
 ---
 
 # Data
@@ -879,6 +972,12 @@ Semantic static table. Wrap in `.fdy-table-wrap` (bordered surface) or `.fdy-tab
 (horizontal scroll). Always a `<caption>` (use `.fdy-visually-hidden` if it shouldn't show) and
 `<th scope="col">`. Numeric cells get `.fdy-table__num` (right-aligned, tabular).
 
+**`--striped`** zebras the even body rows. The tint is deliberately *half* a surface step, not the
+full one hover uses, so hover still reads on a striped row instead of matching it — and stripe,
+hover and selection are ordered so the later state always wins. Override the colour through the
+Tier-3 token **`--fdy-table-stripe`** (set it on any ancestor; the rule reads it as a `var()`
+fallback, so your value wins without a specificity fight). Frozen columns stay striped.
+
 ```html
 <div class="fdy-table-wrap">
   <table class="fdy-table">
@@ -991,6 +1090,12 @@ provide the state prop for a concern and you own that concern instead. React nam
 | `rowActivatable?` · `onRowActivate?` | `boolean` · `(row) => void` | Rows become focusable and activate on click, Enter or Space. |
 | `rowClass?` | `(row: Row) => string \| undefined` | Per-row class hook, e.g. marking the selected row. |
 | `expandedKeys?` · `renderRowDetail?` | `ReadonlyArray<string \| number>` · `(row) => ReactNode` | Controlled expansion: these keys get a full-width detail row. Vue uses the `row-detail` slot. |
+| `striped?` | `boolean` | Zebra-stripe the body rows (`.fdy-table--striped`). |
+| `selectable?` | `boolean` | Render the checkbox column and the bulk bar. |
+| `selectedKeys?` · `onSelectedKeysChange?` | `ReadonlyArray<string \| number>` · `(keys) => void` | Controlled selection, as `rowKey` values — the same identity `expandedKeys` uses, because a key survives the re-fetch that replaces every row object. Omit `selectedKeys` and the column still works, keeping the selection internally. The callback fires in **both** modes, so a screen can watch the selection without owning it. Vue emits `update:selectedKeys`; Blazor binds `@bind-SelectedKeys`. |
+| `bulkActions?` | `ReactNode` | React. Content in the bulk bar beside the count; Vue uses the `bulk-actions` slot (scoped: `keys`, `clear`), Blazor `BulkContent`. |
+| `selectedText?` · `clearSelectionText?` | `string` | Bulk-bar copy. Defaults `{n} selected` (with `{n}` substituted) and `Clear`. |
+| `selectAllLabel?` · `selectRowLabel?` · `bulkLabel?` | `string` | Accessible names for the header checkbox, each row checkbox, and the bulk-bar region. Defaults `Select all rows on this page`, `Select row`, `Bulk actions`. |
 | `renderCell?` | `(column, row, value) => ReactNode` | React. Custom cell rendering; Vue uses the `cell` slot. |
 | `toolbar?` | `ReactNode` | React. Content above the table; Vue uses the `toolbar` slot. |
 | `onProcess?` | `(result: { rows, total }) => void` | React. The processed page after filter/sort/paginate, in **both** modes. Vue emits `process`, Blazor calls it `Process`. Render the same set elsewhere — a card list, a summary, a CSV export — without re-deriving the pipeline. |
@@ -999,6 +1104,14 @@ Blazor matches this surface (`LoadingText` and `EmptyContent` in place of `empty
 `Toolbar` and `RowDetail` as `RenderFragment`s) and is the one adapter that also exposes
 `FiltersChanged`.
 
+**Select-all ticks the current page, not the whole result set.** A header checkbox that silently
+selects rows the reader cannot see is how a bulk delete goes wrong, so it acts on the rows on
+screen — and it is `indeterminate` while only some of them are ticked. Keys picked on *other* pages
+are kept rather than dropped, so paging away and back does not lose them; the bulk bar's count is
+the true total across pages, which is why it can read higher than the rows in view. `Clear` empties
+the whole selection. A row checkbox stops its own click, so ticking a row in a `rowActivatable`
+table selects it instead of navigating away from it.
+
 The interactive table: global search, sort, per-column filters, row selection + bulk bar,
 pagination. Needs `freeday-table.js`. Wrap the whole thing in `.fdy-datatable` + `data-fdy-table`
 (`data-page-size="N"`).
@@ -1242,9 +1355,13 @@ Transient notification in a live region. Imperative only:
 ```js
 const node = Freeday.toast({ variant: 'success', title: 'Saved', message: 'INV-1042 saved.' })
 Freeday.toast({ variant: 'danger', title: 'Failed', message: '…', key: 'net-fail' }) // same key replaces
+Freeday.toast({ message: 'Still uploading…', timeout: 0 })   // 0 = stays until dismissed
 Freeday.dismiss('net-fail')  // or Freeday.dismiss(node)
 ```
-Every field is optional; it returns the toast element. Classes (rendered for you):
+Every field is optional; it returns the toast element. **`timeout`** is ms before it auto-dismisses,
+default `4000`, and `0` makes it stick — the enhancer has honoured it since it was written, but this
+line did not exist until 3.0.0, so every app that needed a sticky error toast hand-rolled one.
+Classes (rendered for you):
 `.fdy-toast-region`, `.fdy-toast` (+`--info` `--success` `--warning` `--danger`) · `__accent`
 `__body` `__title` `__text` `__close`.
 
@@ -1264,6 +1381,41 @@ gets `aria-describedby` → the `.fdy-tooltip[role="tooltip"]` `id`.
 duration. `role="progressbar"` with `aria-valuenow/min/max` (omit `valuenow` when indeterminate).
 `.fdy-spinner` (+`--sm` `--lg`) with `role="status"` + `aria-label`.
 
+## Busy overlay — `Freeday.busy()`
+Blocks the screen while an operation runs — a save that must not be double-submitted, a report the
+server is still building. Imperative only, and that is the design, not a shortcut:
+
+```js
+Freeday.busy({ caption: 'Posting invoice…' })   // returns the element
+Freeday.idle()                                  // releases it
+```
+
+- `caption?` — what is happening. Announced politely (`role="status"`). Omitted, it falls back to
+  the kit's default, overridable page-wide with `data-fdy-text-caption` on `<html>`.
+- `delay?` — ms before it appears, default `120`, `0` shows immediately. An operation that finishes
+  in 80ms should never flash a scrim; that reads as a glitch rather than as progress. `idle()`
+  cancels a still-pending show, so a fast operation leaves nothing behind.
+- `mark?` — an `Element` to use instead of the spinner. **Element only, never an HTML string** — a
+  string here would be an injection point in every app that passed user text through it. Brand marks
+  are yours; the kit ships the box and one spinner.
+
+Classes (rendered for you): `.fdy-busy` (+`.is-open`) · `__panel` `__mark` `__caption`.
+
+**One overlay, always.** A second `busy()` while one is up replaces the caption instead of stacking
+a second scrim. That is the whole reason there is no component API and no markup to hand-write: two
+of these on screen, with two captions, from two components that each thought they owned it, is the
+bug this prevents.
+
+**It is not a dialog.** Nothing asks a question and nothing can be dismissed, so there is no focus
+trap and no Escape. Interaction is removed with `inert` on every other child of `<body>` — and only
+on the ones the kit set it on, so an app's own `inert` is never cleared. Focus is parked on the panel
+and handed back to the element that had it once `idle()` runs, because by then that element's
+ancestor is inert and the browser would otherwise have dropped focus to `<body>`.
+
+**Above modals, and not by z-index.** Like the toast region it is a `popover`, so it enters the top
+layer over an open `<dialog>`. Where the Popover API is missing it falls back to a fixed layer at
+`z-index: 190`, which cannot clear an open modal — the same trade the toast region documents.
+
 ## Skeleton — `.fdy-skeleton`
 Size-matched placeholders so nothing shifts when data lands: `--title` `--text` `--circle`
 `--avatar` (+`--avatar-sm` `--avatar-lg`, exactly `.fdy-avatar`'s box).

package/README.id.md

@@ -5,7 +5,7 @@
 > **Lebih banyak _free day_ buat dev. UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v2.2.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v2.2.0)
+[![Release](https://img.shields.io/badge/release-v3.0.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.0.0)
 
 UI KIT yang token-driven & framework-agnostic. Satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs. The UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v2.2.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v2.2.0)
+[![Release](https://img.shields.io/badge/release-v3.0.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.0.0)
 
 A token-driven, framework-agnostic UI kit. One source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.

package/USAGE.md

@@ -65,7 +65,7 @@ Shadow is a signal, not decoration. There are two families, and the difference m
 | Raised | `--shadow-2` | `.fdy-tooltip`, `.fdy-appbar--elevated` |
 | Floating | `--shadow-3` | Things that float over the page: `.fdy-menu`, `.fdy-filter`, `.fdy-toast`, `.fdy-fab` |
 | Overlay | `--shadow-4` | `.fdy-drawer` |
-| **Lift** | `--shadow-lift` / `--shadow-lift-hover` | **`.fdy-card`** (and `--elevated` / `--interactive:hover`), `.fdy-modal` |
+| **Lift** | `--shadow-lift` / `--shadow-lift-hover` | **`.fdy-card`** (and `--elevated` / `--interactive:hover`), `.fdy-modal`, `.fdy-busy__panel` |
 
 **`.fdy-card` is a lifted surface, not a hairline one.** `--shadow-lift` is a real 34px lift, ~6×
 heavier than `--shadow-1`. That is the whole point of a card, and it is also why a *stack* of them

package/adapters/blazor/FdyAppShell.razor

@@ -6,7 +6,7 @@
    `data-fdy-app` and binds to it: the enhancer announces changes as a bubbling `fdy-app-nav` event
    and accepts them through FreedayAppShell.setVisible. That is the bridge's own doctrine: the
    enhancers stay the source of truth, and it keeps the focus trap from existing a third time. *@
-<div @ref="Root" class="fdy-app" data-fdy-app>
+<div @ref="Root" class="@ShellClass" data-fdy-app>
     @SkipContent
 
     <aside class="fdy-app__sidebar">

package/adapters/blazor/FdyAppShell.razor.cs

@@ -43,8 +43,20 @@ public partial class FdyAppShell
 
     [Parameter] public string ToggleLabel { get; set; } = "Toggle navigation";
 
+    /// <summary>
+    /// How a VISIBLE nav sits on a wide viewport: <see cref="FdyNavMode.Push"/> (default) makes it
+    /// a column that displaces the content, <see cref="FdyNavMode.Overlay"/> floats it over the page
+    /// with a backdrop. Below the nav breakpoint it is ignored — the nav is off-canvas there by
+    /// definition, so there is nothing to choose.
+    /// </summary>
+    [Parameter] public FdyNavMode NavMode { get; set; } = FdyNavMode.Push;
+
+    private string ShellClass =>
+        NavMode == FdyNavMode.Overlay ? "fdy-app fdy-app--nav-overlay" : "fdy-app";
+
     private int _navToken;
     private bool? _lastNavOpen;
+    private FdyNavMode _lastNavMode = FdyNavMode.Push;
 
     protected override async ValueTask HydrateAsync()
     {
@@ -77,6 +89,15 @@ public partial class FdyAppShell
             _lastNavOpen = wanted;
             await JS.InvokeVoidAsync("FreedayAppShell.setVisible", Root, wanted);
         }
+
+        // Switching the mode moves the answer to "is the nav visible?" from one state class to the
+        // other, so `inert` and `aria-expanded` describe the old arrangement until the shell re-reads
+        // the DOM. Blazor has rendered the new class by now; this tells the enhancer to look again.
+        if (_navToken != 0 && NavMode != _lastNavMode)
+        {
+            _lastNavMode = NavMode;
+            await JS.InvokeVoidAsync("FreedayAppShell.refresh", Root);
+        }
     }
 
     /// <summary>Invoked by the bridge when the shell's nav visibility changes for any reason,
@@ -112,3 +133,17 @@ public partial class FdyAppShell
 
     public sealed record NavDetail(bool Visible);
 }
+
+/// <summary>
+/// How a visible nav sits on a wide viewport. The JS adapters take the same idea as the string
+/// union <c>'push' | 'overlay'</c>; C# gets an enum, for the same reason the column filter type is
+/// one — a typo in a string reaches the renderer, a typo in an enum member does not compile.
+/// </summary>
+public enum FdyNavMode
+{
+    /// <summary>A column that displaces the content (the default, and what every 2.x shell did).</summary>
+    Push,
+
+    /// <summary>Floats over the page with a backdrop, the way it already behaves on a narrow one.</summary>
+    Overlay,
+}

package/adapters/blazor/FdyTable.razor

@@ -17,10 +17,34 @@
         </div>
     }
 
+    @if (Selectable)
+    {
+        <div class="fdy-table-bulkbar" hidden="@(SelectedCount == 0)" role="region" aria-label="@BulkLabel">
+            <span class="fdy-table-bulkbar__count" aria-live="polite">@SelectedLabel()</span>
+            <span class="fdy-table-bulkbar__spacer"></span>
+            <div class="fdy-table-bulkbar__actions">
+                @BulkContent
+                <button type="button" class="fdy-btn fdy-btn--ghost fdy-btn--sm" @onclick="ClearSelection">@ClearSelectionText</button>
+            </div>
+        </div>
+    }
+
     <div class="fdy-table-scroll">
-        <table class="fdy-table" aria-label="@AriaLabel">
+        <table class="fdy-table @(Striped ? "fdy-table--striped" : null)" aria-label="@AriaLabel">
             <thead>
                 <tr>
+                    @if (Selectable)
+                    {
+                        <th class="fdy-table__selcol" scope="col">
+                            <input type="checkbox"
+                                   class="fdy-checkbox"
+                                   data-fdy-select-all
+                                   @ref="_selectAllRef"
+                                   checked="@AllPageSelected"
+                                   aria-label="@SelectAllLabel"
+                                   @onchange="e => ToggleAllOnPage((bool)(e.Value ?? false))" />
+                        </th>
+                    }
                     @foreach (FdyTableColumn<TRow> col in Columns)
                     {
                         <th scope="col" style="@AlignStyle(col)" aria-sort="@AriaSortOf(col)">
@@ -47,12 +71,12 @@
             <tbody>
                 @if (Loading)
                 {
-                    <tr><td colspan="@Columns.Count" class="fdy-table__state" role="status">@LoadingText</td></tr>
+                    <tr><td colspan="@ColSpan" class="fdy-table__state" role="status">@LoadingText</td></tr>
                 }
                 else if (_displayRows.Count == 0)
                 {
                     <tr>
-                        <td colspan="@Columns.Count" class="fdy-table__state">
+                        <td colspan="@ColSpan" class="fdy-table__state">
                             @if (EmptyContent is not null)
                             {
                                 @EmptyContent
@@ -72,8 +96,24 @@
                         <tr class="@RowClasses(r)"
                             tabindex="@(RowActivatable ? 0 : (int?)null)"
                             aria-expanded="@ExpandedAttr(r)"
+                            aria-selected="@SelectedAttr(r)"
                             @onclick="() => OnRowClick(r)"
                             @onkeydown="e => OnRowKeydown(e, r)">
+                            @if (Selectable)
+                            {
+                                @* @onclick:stopPropagation: without it, ticking a checkbox in an
+                                   activatable row also raises RowActivate, so selecting a row
+                                   would navigate away from it. *@
+                                <td class="fdy-table__selcol">
+                                    <input type="checkbox"
+                                           class="fdy-checkbox"
+                                           data-fdy-row-select
+                                           checked="@IsSelected(r)"
+                                           aria-label="@SelectRowLabel"
+                                           @onclick:stopPropagation="true"
+                                           @onchange="e => ToggleRow(r, (bool)(e.Value ?? false))" />
+                                </td>
+                            }
                             @foreach (FdyTableColumn<TRow> col in Columns)
                             {
                                 <td class="@CellClass(col)" style="@AlignStyle(col)">
@@ -91,7 +131,7 @@
                         @if (RowDetail is not null && IsExpanded(r))
                         {
                             <tr class="fdy-table__detailrow">
-                                <td colspan="@Columns.Count">@RowDetail(r)</td>
+                                <td colspan="@ColSpan">@RowDetail(r)</td>
                             </tr>
                         }
                     }