@cahyo-dimas/freeday 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -9,6 +9,133 @@ 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.6.0] - 2026-10-22
+
+**Tiga belas hal yang dibangun ulang sebuah app back-office karena kit belum punya.** App-nya tidak
+memakai Freeday (Vue + PrimeVue), jadi yang diangkat adalah polanya, bukan komponennya: setiap
+kandidat dibandingkan dengan kit, dan hanya yang generik dan benar-benar belum ada yang masuk
+(`#059`–`#071`). Satu di antaranya cacat yang kit punya juga: submit yang ditolak memfokus field
+yang tak terlihat. Satu lagi mengubah tampilan setiap tabel, jadi dikirim sebagai opt-in dan
+dijadwalkan jadi default di 4.0 (NEXT-UP #16). Tidak ada tipe publik yang menyempit dan tidak ada
+tampilan yang berubah tanpa diminta, jadi ini rilis minor.
+
+### Added
+- **`Freeday.confirm()`** (`#060`). Pertanyaan ya/tidak sebelum aksi yang tak bisa diulang, tanpa
+  merakit dialog sendiri. Mengembalikan `Promise<boolean>`: `true` saat accept, `false` saat reject,
+  Escape atau klik backdrop. `details[]` tampil sebagai daftar di bawah pesan, untuk konfirmasi yang
+  harus menyebut temuannya. Fokus awal di tombol reject, teks dipasang sebagai teks (bukan HTML), dan
+  kedua tombol punya hook `data-fdy-confirm-accept` / `-reject` untuk test. Tipe ada di
+  `freeday.d.ts`; Blazor memanggilnya lewat `JS.InvokeAsync<bool>`.
+- **`[data-fdy-search]`** (`#061`, menjawab NEXT-UP #10). `.fdy-input-group` yang mencari saat
+  pengetik berhenti sejenak (`data-fdy-search-delay`, default 400 ms), langsung saat Enter, dan
+  punya tombol clear. Ketiga jalur berakhir di satu event `fdy-search {term}`. Clear menulis lewat
+  setter native dan memicu `input` native, jadi `v-model`, `onChange` React dan `@bind` Blazor ikut.
+- **`[data-fdy-copy]`** (`#062`). Tombol yang menyalin nilainya sendiri lalu memberi toast. Tanpa
+  Clipboard API (http) pembaca diberi tahu untuk menyalin manual. Listener-nya didelegasikan di
+  `document`, jadi tombol yang dirender belakangan tak perlu hidrasi.
+- Ketiganya dijaga `browser/confirm-search-copy.mjs` (7 spec), dan tiap spec diverifikasi dengan
+  mutasi: delapan mutasi pada kode baru, delapan merah.
+- **`settled` pada date range** (`#063`). Vue `@settled`, React `onSettled`, Blazor `Settled`,
+  jalur mentah `fdy-daterange-settled`. Terpancar hanya saat kedua ujung terisi atau keduanya
+  kosong. Sebelumnya setiap stack memancarkan per ujung, jadi list yang reload saat berubah memuat
+  data dengan tanggal awal saja lalu memuat lagi saat tanggal akhir dipilih. `change` dan `v-model`
+  tidak berubah. Dijaga `browser/daterange-settled.mjs` (4 spec) + `FdyDateRangeTests` (2 bUnit),
+  lima mutasi, lima merah.
+- **`.fdy-dl--grid`** (`#066`). Grid fakta: label di atas nilai, kolom sebanyak yang muat di lebar
+  list itu SENDIRI, maksimal tiga. Diukur dari elemen, bukan jendela, jadi markup yang sama tiga
+  kolom di area utama dan satu kolom di rail sempit tanpa modifier. Semua `.fdy-dl dd` kini
+  `overflow-wrap:anywhere`, jadi email atau nomor panjang tidak lagi tercetak di atas kolom sebelah.
+- **`.fdy-card__head` + `__action`** (`#070`). Header kartu: tanda, judul yang di-truncate, dan
+  satu aksi di kanan, dengan garis selebar kartu. Tandanya `.fdy-avatar --sm --square --tone-N`.
+- **`.fdy-avatar--square`** untuk tanda yang bukan orang (logo perusahaan, chip ikon kartu).
+- **Hint state switch** (`#068`). Dua baris `[data-fdy-when="on|off"]` di satu `.fdy-help`; kit
+  menampilkan yang cocok dengan state sekarang, tanpa JS. `aria-describedby` menunjuk ke
+  pembungkusnya, jadi pembaca layar hanya mendengar baris yang tampil (diverifikasi lewat deskripsi
+  aksesibel yang dihitung Chrome).
+- **`.fdy-state--compact`** (`#069`) untuk state di dalam kartu kecil.
+- **Empty state `FdyTable` tahu kenapa ia kosong** (`#069`). Slot Vue `empty` dan fungsi React
+  `empty` menerima `{ filtered, clearFilters }`; Blazor punya `EmptyTemplate`
+  (`RenderFragment<FdyTableEmptyContext>`). "Tidak ada yang cocok" bisa menawarkan Clear, "belum
+  ada data" menawarkan Create.
+- **`.fdy-page__columns`** (`#065`, menutup "Form master-detail / 2 kolom" yang ditunda di
+  NEXT-UP). Rail `__lead` / `__aside` di samping `__main`; lebar dipilih dari rail mana yang ada
+  (8/4, 3/9, 3/6/3). Saat menumpuk, rail ringkasan didahulukan. Mulai `md` rail sticky dan
+  scroll sendiri, jadi total dan status tetap terlihat dan rail yang lebih tinggi dari layar tidak
+  menggantung. Diadaptasi dari layout yang di app asalnya menahan seluruh halaman; di kit shell-nya
+  tetap scroll halaman, jadi tidak ada consumer yang dipaksa mengubah layout-nya. Dijaga
+  `browser/page-columns.mjs` (5 spec, 6 mutasi, 6 merah).
+- **`.fdy-table--hover-actionable`** (`#064`), prop `hoverActionable` / `HoverActionable` di ketiga
+  adapter. Hanya baris yang melakukan sesuatu (`rowActivatable`) yang ber-hover (baris terpilih tetap berwarna terpilih);
+  baris inert kembali ke warna istirahatnya sendiri, termasuk stripe, dan sel beku tetap opak.
+  Opt-in di 3.x supaya tidak ada tabel yang berubah; direncanakan jadi default di 4.0. Hover dasar
+  kini membaca `--_fdy-row-hover` (privat), tampilannya tidak berubah. Dijaga
+  `browser/table-hover.mjs` (4 spec, 5 mutasi, 5 merah) + `FdyTableHoverTests` (2 bUnit).
+- **Docs: breadcrumb** (`#071 §8`). `aria-current="page"` hanya untuk crumb yang memang halaman ini;
+  trail yang berhenti di induknya (form record yang crumb terakhirnya list) membiarkan crumb itu
+  tetap link.
+- **Docs: Record actions** (`#067`). Urutan tetap untuk aksi form di `.fdy-page__actions`:
+  Find | New, maksimal dua aksi inline, sisanya di menu More dengan urutan deklarasi yang sama dan
+  warna danger yang tetap terbawa, Save terakhir dan satu-satunya tombol solid.
+- Dijaga `browser/display-parts.mjs` (4), `browser/table-empty.mjs` (2) dan `FdyTableEmptyTests`
+  (2 bUnit). Setiap perilaku baru diverifikasi dengan mutasi (13 mutasi, 13 merah).
+### Fixed
+- **Date range jalur mentah: ujung yang dihapus kini diumumkan.** Tanggal awal yang melewati
+  tanggal akhir mengosongkan tanggal akhir tanpa event apa pun, jadi `To` di Blazor (yang hanya
+  mendengar pilihan) tetap memegang tanggal yang sudah tidak ada. Pengosongan itu sekarang
+  memancarkan `fdy-datepicker-change` dengan `value: ''`.
+- **Submit yang ditolak kini memperlihatkan field yang ditolaknya** (`#059`). `freeday-form.js`
+  memanggil `focus()` pada kontrol invalid pertama dan berhenti di situ. Kalau kontrol itu tidak
+  dirender (di dalam `<details>` tertutup, di tab yang tak dipilih, di panel stepper yang sudah
+  dilewati), `focus()` tidak melakukan apa pun dan tidak melapor apa pun: field memerah di tempat
+  yang tak terlihat, dan tombol Save terbaca mati. Sekarang penghalangnya dibuka dulu lewat kontrol
+  milik komponennya sendiri, supaya state komponen itu tetap cocok dengan yang tampil: `<details>`
+  di-`open`, tab-nya diklik, tombol step-nya diklik. Step yang **belum dicapai** sengaja tidak
+  dilompati, karena itu sama dengan melewati guard `fdy-step-before-change`. Dijaga
+  `browser/form-reveal.mjs` (5 spec); empat di antaranya merah sebelum perbaikan.
+
+## [3.5.0] - 2026-09-15
+
+**Sebuah angka yang hanya bisa ditemukan dengan membaca stylesheet kit.** `#058` (dari
+`IDU_AI_DOC_SAPB1_CLIENT` dan `IDU_AI_DOC_SAAS`, satu sapuan atas dua konsol) datang dari audit yang
+hasilnya nyaris bersih: tipografi, spasi dan warna tak menyisakan satu pun nilai mentah. Yang tersisa
+cuma media query — dan di situlah dua hal yang sama-sama berakar pada satu kenyataan CSS: `@media`
+tak bisa membaca custom property.
+
+Akibatnya angka breakpoint kit hanya hidup sebagai literal, app mengetik ulang literal itu, dan
+literal yang diketik ulang hanyut. Dua konsol itu menuliskan satu lebar yang sama dengan tiga cara
+(`640px`, `40rem`, `45rem`) untuk satu maksud yang sama.
+
+### Added
+- **`@cahyo-dimas/freeday/media`** — berkas `@custom-media` (`dist/freeday.media.css`), jawaban
+  sisi-CSS untuk apa yang selama ini hanya dijawab `tokens/breakpoints.mjs` di sisi JS. App menulis
+  `@media (--fdy-below-sm)` atau `@media (--fdy-filterbar-stacked)`, bukan literal yang diketik
+  ulang, dan karenanya tak bisa hanyut.
+  Isinya `--fdy-below-*` / `--fdy-from-*` untuk ramp (`sm`·`md`·`lg`·`xl`), plus `--fdy-nav-drawer`,
+  `--fdy-nav-static` dan `--fdy-filterbar-stacked` untuk dua lebar yang bukan anak tangga ramp.
+  **Opt-in, dan tak mengubah apa pun bagi yang tidak memakainya:** `@custom-media` adalah transform
+  PostCSS (`postcss-custom-media`, sudah termasuk di `postcss-preset-env`), jadi app ber-Vite
+  mendapatkannya cuma-cuma dan app tanpa PostCSS tetap menulis literal seperti kemarin. Berkas ini
+  **tidak** ikut `freeday.css` maupun `freeday.bundle.css` — at-rule waktu-build tak punya urusan di
+  stylesheet yang dimuat tiap app — dan tak membawa satu rule pun, jadi meng-import-nya tak berbiaya
+  saat runtime.
+  Di-**generate** dari objek yang sama yang diekspor sisi JS, jadi kedua paruh skala itu tak mungkin
+  berbeda pendapat; yang menjaganya agar tetap sama dengan CSS yang dideskripsikannya adalah dua tes
+  baru di `test/docs.test.mjs`, diverifikasi dengan mutasi.
+- **`breakpoints.filterbar` (640)** — lebar tempat `.fdy-filterbar` menumpuk fieldnya jadi selebar
+  penuh, kini bernama, bukan cuma tertulis di `filterbar.css:45`.
+
+### Changed
+- **640 tetap 640, tapi berhenti jadi angka siluman.** Ia bukan anak tangga ramp (`sm` = 600) dan
+  sengaja tidak dipindahkan: 640 adalah lebar telepon-lanskap yang nyata, dan menggesernya akan
+  me-reflow setiap filter bar di setiap app. Yang salah bukan angkanya, melainkan bahwa satu-satunya
+  cara menemukannya adalah membaca stylesheet kit lalu mempercayai sumber di atas dokumentasi.
+  Menyelaraskan rule app ke `sm` — hal yang wajar dilakukan dari dokumentasi saja — merusak
+  600–640px: fieldnya sudah ditumpuk kit sementara app masih membatasi lebar field `--w-grow`-nya,
+  sehingga field itu terlihat lebih sempit dari tetangganya di tumpukan.
+  Header `breakpoints.css`, komentar `filterbar.css`, `COMPONENTS.md` dan kedua README kini menyebut
+  `nav` **dan** `filterbar` sebagai dua lebar yang bukan ramp, lengkap dengan pita px yang rusak
+  kalau dibulatkan ke anak tangga terdekat.
+
 ## [3.4.0] - 2026-09-07
 
 **Tiga hal yang hanya terlihat setelah sebuah app bertemu telepon sungguhan.** `#057` (dari

package/COMPONENTS.md

@@ -77,7 +77,7 @@ element is fine. Events are bubbling
 | `data-fdy-autocomplete` | `freeday-autocomplete.js` | `FreedayAutocomplete` | `fdy-autocomplete-select` |
 | `data-fdy-cascade` | `freeday-cascade.js` | `FreedayCascade` | `fdy-cascade-change` |
 | `data-fdy-cfl` | `freeday-cfl.js` | `FreedayCfl` | `fdy-cfl-select` |
-| `data-fdy-datepicker`, `data-fdy-daterange` | `freeday-datepicker.js` | `FreedayDatepicker` | `fdy-datepicker-change` |
+| `data-fdy-datepicker`, `data-fdy-daterange` | `freeday-datepicker.js` | `FreedayDatepicker` | `fdy-datepicker-change`, `fdy-daterange-settled` |
 | `data-fdy-timepicker` | `freeday-timepicker.js` | `FreedayTimepicker` | `fdy-time-select` |
 | `data-fdy-datetimepicker` | `freeday-datetime.js` | `FreedayDatetime` | `fdy-datetime-change` |
 | `data-fdy-table` | `freeday-table.js` | `FreedayTable` | `fdy-table-change` |
@@ -93,9 +93,12 @@ element is fine. Events are bubbling
 | `data-fdy-rating` | `freeday-rating.js` | `FreedayRating` | — (native `change`) |
 | `data-fdy-slider` | `freeday-slider.js` | `FreedaySlider` | — (native `input`) |
 | `data-fdy-number` | `freeday-number.js` | `FreedayNumber` | — (native `input`, `change`) |
+| `data-fdy-search` | `freeday-search.js` | `FreedaySearch` | `fdy-search` (+ native `input` on clear) |
+| `data-fdy-copy="value"` (delegated, no hydration) | `freeday-copy.js` | `FreedayCopy` | `fdy-copy` |
 | `data-fdy-drawer="id"` | `freeday-drawer.js` | `FreedayDrawer` | — |
 | `data-fdy-chart="type"` | `freeday-chart.js` | `FreedayChart` | — (`.update(el)` to repaint) |
 | — (imperative) | `freeday-toast.js` | `Freeday.toast()` / `Freeday.dismiss()` | — |
+| — (imperative, returns `Promise<boolean>`) | `freeday-confirm.js` | `Freeday.confirm()` | — |
 | — (stamps `<html data-breakpoint>`) | `freeday-breakpoint.js` | `FreedayBreakpoint` | `fdy-breakpoint-change` |
 | — (internal positioning) | `freeday-popover.js` | `FreedayPopover` | — |
 
@@ -289,6 +292,78 @@ carry the doctrine in markup.
 </div>
 ```
 
+### Document columns — `.fdy-page__columns`
+
+A record or form page with side rails: `__lead` on the left for the record's identity (avatar,
+number, status), `__main` for the sections, `__aside` on the right for the summary (totals, what
+happens next). The column widths follow which rails are **present**, so no screen picks them:
+
+| Children | From `md` | From `lg` |
+|---|---|---|
+| `__main` | one column | one column |
+| `__main` + `__aside` | 8 / 4 | 8 / 4 |
+| `__lead` + `__main` | 3 / 9 | 3 / 9 |
+| `__lead` + `__main` + `__aside` | rails stacked on the left, main on the right | 3 / 6 / 3 |
+
+- Below `md` everything stacks, and **the summary rail comes first**. Last, it would sit under
+  every section, and the button in it with it.
+- From `md` each rail is **sticky and scrolls on its own**: the total and the status stay in view
+  while `__main` scrolls with the page, and a rail taller than the screen scrolls inside itself
+  instead of hanging its end off the bottom. The exception is both rails sharing the left column
+  (between `md` and `lg`): two sticky rails in one column would slide over each other, so there they
+  scroll with the page.
+- Inside `.fdy-app` the rails stick below the topbar. Set `--fdy-page-sticky-top` on the columns or
+  an ancestor if your header is taller.
+- A rail's box starts `--space-1` early on every side, room for a focus ring that a scrolling box
+  would otherwise clip. Its content still lines up with `__main`.
+- Put `.fdy-dl--grid` in a rail as is: it measures the rail, not the window, so it stays one column.
+
+```html
+<div class="fdy-page__columns">
+  <aside class="fdy-page__lead" aria-label="Record">…</aside>
+  <div class="fdy-page__main">…sections…</div>
+  <aside class="fdy-page__aside" aria-label="Summary">…</aside>
+</div>
+```
+
+### Record actions — a form's `.fdy-page__actions`
+
+A document or master form carries more than one button: its own actions (Print, Send, Cancel
+document, Copy from…) and Save. Without a rule the row grows with every module, reflows at tablet
+width and pushes Save off the end, and two screens with the same actions order them differently.
+The kit's rule, in this fixed order:
+
+1. **Find | New** as one `.fdy-btn-group`, ghost. Hide New on the create screen itself: a button
+   that navigates to the screen you are on appears to do nothing.
+2. **At most two** of the form's own actions inline, ghost, in the order they are declared.
+3. **More**: an `.fdy-menu` holding every other action, in the **same declared order**. A
+   destructive item keeps `.fdy-menu__item--danger`: an action that loses its colour on the way
+   into a menu is one the reader no longer recognises. Keep each action's test hook the same
+   whether it is inline or in the menu.
+4. **Save**, last, the **only** solid button on the row. Never green: green says something already
+   succeeded.
+
+```html
+<div class="fdy-page__actions">
+  <div class="fdy-btn-group" role="group" aria-label="Records">
+    <a class="fdy-btn fdy-btn--ghost" href="/orders">Find</a>
+    <a class="fdy-btn fdy-btn--ghost" href="/orders/new">New</a>
+  </div>
+  <button class="fdy-btn fdy-btn--ghost" type="button">Print</button>
+  <button class="fdy-btn fdy-btn--ghost" type="button">Send</button>
+  <div class="fdy-menu-wrap" data-fdy-menu>
+    <button class="fdy-btn fdy-btn--ghost" type="button" aria-haspopup="menu" aria-expanded="false">More</button>
+    <ul class="fdy-menu fdy-menu--end" role="menu" hidden>
+      <li role="none"><button class="fdy-menu__item" role="menuitem">Copy from quotation</button></li>
+      <li role="none"><button class="fdy-menu__item fdy-menu__item--danger" role="menuitem">Cancel document</button></li>
+    </ul>
+  </div>
+  <button class="fdy-btn" type="submit" form="order-form">Save</button>
+</div>
+```
+
+Ask before a destructive action with `Freeday.confirm({ tone: 'danger', … })`.
+
 ## Type roles & text
 One role per level of hierarchy. Never re-use a card title for a page title.
 
@@ -313,10 +388,33 @@ Responsive display: `.fdy-hide-below-sm|md|lg` · `.fdy-hide-above-sm|md|lg`.
 Breakpoints (min-width): `sm` 600 · `md` 960 · `lg` 1280 · `xl` 1920, importable as
 `import { breakpoints } from '@cahyo-dimas/freeday/breakpoints'`.
 
-**`breakpoints.nav` (721) is separate and is the one the shell uses.** `.fdy-app` switches the
-sidebar from off-canvas drawer to static column at 721px, *not* at `md`. Any `matchMedia` guard or
-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).
+**Two widths in that object are not ramp steps**, and each is the one to use when your rule has to
+fire with a kit rule. Aligning either to the nearest ramp step leaves a band of broken widths, in
+which the kit has already switched and your app has not:
+
+| | px | Governs | Aligning to the ramp instead breaks |
+|---|---|---|---|
+| `breakpoints.nav` | 721 | `.fdy-app` switches the sidebar from off-canvas drawer to static column — and `.fdy-app__main`'s padding step and `.fdy-bottomnav` ride the same width | 721–959px, if you use `md`: sidebar already static while your script still treats it as an overlay |
+| `breakpoints.filterbar` | 640 | `.fdy-filterbar` stacks every field full-width | 600–640px, if you use `sm`: fields already stacked while your rule still caps the `--w-grow` one, so it sits visibly narrower than the fields under it |
+
+**In CSS, import the breakpoints instead of retyping them.** `@media` cannot read a custom property,
+so there is no `--breakpoint-*` token and never will be; `@cahyo-dimas/freeday/media` answers it the
+only way CSS can, as a `@custom-media` sheet:
+
+```css
+@import '@cahyo-dimas/freeday/media';           /* once, above the rules that use it */
+
+@media (--fdy-filterbar-stacked) { .page-filters > .fdy-field--w-grow { max-width: none } }
+@media (--fdy-nav-drawer)        { .page-banner { padding-inline: var(--space-5) } }
+```
+
+Declared: `--fdy-below-sm|md|lg|xl` and `--fdy-from-sm|md|lg|xl` (the ramp, matching the utilities
+above), plus `--fdy-nav-drawer` / `--fdy-nav-static` and `--fdy-filterbar-stacked` for the two
+widths in the table. It is **opt-in**: `@custom-media` is a PostCSS transform
+(`postcss-custom-media`, included in `postcss-preset-env`), so an app that runs PostCSS — anything on
+Vite already does — gets it, and an app that does not keeps writing literals exactly as before. The
+sheet carries no rules, so importing it costs nothing at runtime, and it is deliberately not part of
+`freeday.css` or `freeday.bundle.css`.
 
 **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
@@ -490,7 +588,7 @@ cannot guarantee.
 
 | Type | What the UA still draws | What to do |
 |---|---|---|
-| `search` | WebKit's clear (×) button, in OS colours | **Left alone on purpose** — it is the only way to empty the field. Want it themed? Drop the type back to `text` and add a `.fdy-input-group__btn` that clears. |
+| `search` | WebKit's clear (×) button, in OS colours | **Left alone on purpose** — it is the only way to empty the field. Want it themed, and want clearing to search again? Use [`data-fdy-search`](#search-box--data-fdy-search), which is `type="text"` with a clear button of its own. |
 | `date` `time` `datetime-local` | the picker indicator glyph, and the whole native picker | Use `.fdy-datepicker` / `.fdy-timepicker` / `.fdy-datetimepicker` instead — the kit ships its own. |
 
 `number` used to be a third: the UA spin buttons are unthemeable, so `.fdy-input[type="number"]`
@@ -534,6 +632,31 @@ the shared border, focus ring and error promotion. Needs `freeday-number.js`.
   `aria-label`, so pointer and browse-mode users still get a named control.
 - `type="button"` is required. Inside a `<form>`, a bare `<button>` submits it.
 
+## Search box — `[data-fdy-search]`
+The search box above a list: it searches when the reader pauses typing, at once on Enter, and has a
+clear button that brings every row back. **Not a new block.** It is an `.fdy-input-group`, like the
+number field. Needs `freeday-search.js`.
+
+```html
+<div class="fdy-input-group" data-fdy-search>
+  <span class="fdy-input-group__addon fdy-input-group__addon--icon"><!-- search svg --></span>
+  <input class="fdy-input" type="text" aria-label="Search orders">
+  <button type="button" class="fdy-input-group__btn" data-fdy-search-clear aria-label="Clear search">&times;</button>
+</div>
+```
+
+- **One event for all three paths.** The group emits bubbling `fdy-search` with `detail.term`
+  (trimmed) after the pause, on Enter, and on clear. `""` means "show everything again". Listen to
+  that and nothing else.
+- The pause is `data-fdy-search-delay` in ms on the group, default `400`. A new keystroke restarts
+  it; Enter and clear send at once and cancel what was pending.
+- `type="text"`, not `search`: WebKit's own × is unthemed, and emptying a field with it never
+  searched again on a list that only listened for Enter.
+- The clear button is yours, and so is its `aria-label`. The enhancer hides it while the box is
+  empty. Clearing writes through the native value setter and fires a native `input`, so `v-model`,
+  a React `onChange` and Blazor `@bind` see the empty value, then puts focus back in the box.
+- Enter is `preventDefault`ed, so a search box inside a `<form>` does not submit it.
+
 ## Checkbox · radio · switch
 Native inputs, styled. `.fdy-check` · `.fdy-radio` · `.fdy-switch` on the wrapping `<label>`;
 `.fdy-checkbox` on a bare `<input type="checkbox">` used inside tables/trees.
@@ -543,6 +666,23 @@ Native inputs, styled. `.fdy-check` · `.fdy-radio` · `.fdy-switch` on the wrap
 <label class="fdy-switch"><input type="checkbox"> Enable notifications</label>
 ```
 
+**A state hint** says what the switch's **current** state means, for a label that does not explain
+"on" by itself ("Approval" on a notification rule). Two lines in one `.fdy-help`, and the kit
+shows the one that matches. Point `aria-describedby` at the **wrapper**, not at the two lines: a
+hidden child of a referenced element is skipped, so a screen reader hears only the line on screen,
+while each line referenced directly would be read even when hidden. Zero JS; works for
+`.fdy-check` too. Needs a `.fdy-field` around both.
+
+```html
+<div class="fdy-field">
+  <label class="fdy-switch"><input type="checkbox" aria-describedby="appr-hint"> Approval</label>
+  <div class="fdy-help" id="appr-hint">
+    <span data-fdy-when="on">Each change waits for a supervisor.</span>
+    <span data-fdy-when="off">Changes apply at once; nobody reviews them.</span>
+  </div>
+</div>
+```
+
 ## Select / combobox — `.fdy-combo`
 > **Typed wrapper: `<FdyCombo>`**. Vue (`v-model`) · React (`value`/`onChange`) · Blazor (`@bind-Value`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
 
@@ -834,7 +974,8 @@ page's `<html lang>`), `clearable` and `clearLabel` (this path builds no clear b
 | Prop | Type | What it does |
 |---|---|---|
 | `modelValue` · `value` | `DateRangeValue` = `{ start, end }`, each `string \| null` | Both ends at once, so the pair can never be half-applied. |
-| `onChange` | `(value: DateRangeValue) => void` | React. Vue emits `update:modelValue` and `change`. |
+| `onChange` | `(value: DateRangeValue) => void` | React. Vue emits `update:modelValue` and `change`. Fires on **each** end, which is right for a binding and wrong for a reload. |
+| `onSettled?` | `(value: DateRangeValue) => void` | React. Vue emits `settled`, Blazor `Settled` (`SettledRange(From, To)`), the raw path `fdy-daterange-settled` `{ from, to }` on the group. Fires only when **both ends are chosen or both are empty**, so a list that reloads on it never filters on half a range. |
 | `min?` · `max?` | `string` | ISO bounds for both ends. The end can never precede the start. |
 | `locale?` | `string` | As on the single picker. |
 | `startPlaceholder?` · `endPlaceholder?` | `string` | One per field. |
@@ -851,7 +992,9 @@ The enhancer builds everything.
   `__panel`; calendar internals `.fdy-cal__head` `__nav` `__title` `__grid` (+`--months` `--years`)
   `__dow` `__day` `__month` `__year`
 - Range: wrap two pickers in `.fdy-daterange` + `data-fdy-daterange` (`role="group"`), children
-  get `data-role="from"` / `"to"`; separator `.fdy-daterange__sep`. The end can't precede the start.
+  get `data-role="from"` / `"to"`; separator `.fdy-daterange__sep`. The end can't precede the start:
+  a start picked past the end clears the end, and that clear fires `fdy-datepicker-change` with
+  `value: ''` like a pick. Reload on `fdy-daterange-settled`, not on each change.
   **Typed wrapper: `<FdyDateRange>`** (Vue/React/Blazor). Use it in those stacks.
 **Getting to a distant date.** The title is a **button**, and it drills up one level each press:
 day grid → 12-cell month grid (`.fdy-cal__grid--months` of `.fdy-cal__month`) → 12-cell year grid
@@ -959,6 +1102,13 @@ blur/input. Needs `freeday-form.js`.
 - Per-control messages: `data-fdy-msg-required`, `-type`, `-minlength`, `-min`, `-mismatch`, …
 - Cross-field: `data-fdy-match="#otherFieldId"`
 - Emits `fdy-form-valid` / `fdy-form-invalid`.
+- **A refused field is revealed before it is focused**, because `focus()` on a control that is not
+  rendered does nothing. A closed `<details>` around it (accordion, tree, nav group) is opened, an
+  unselected tab is selected by clicking it, and a `.fdy-step-panel` left behind is returned to by
+  clicking its step. A step **not yet reached** is never jumped to, since that would skip its
+  `fdy-step-before-change` guard: put the submit where every refusable field is already reachable,
+  or mark the step `is-error` from `fdy-form-invalid`. Anything else hiding the field (your own
+  `hidden`, a closed drawer) stays as you left it.
 
 ## Password & mask
 `data-fdy-password` on `<input type="password">` adds a reveal toggle (reusing the input-group
@@ -1057,6 +1207,15 @@ hover and selection are ordered so the later state always wins. Override the col
 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.
 
+**`--hover-actionable`** keeps the hover tint for rows that do something
+(`.fdy-table__row--activatable`) and gives every other row none. A selected row keeps its selected
+colour either way. A tinted row
+with no click handler promises a target that is not there: people click it, nothing happens, and
+the button they needed was elsewhere in the row. Striping is what keeps the eye on a line; hover
+says "target". An inert row hovers back to its own resting colour, stripe included, and a frozen
+cell to its opaque surface. Opt-in in 3.x so no existing table changes; planned as the default
+for 4.0.
+
 ```html
 <div class="fdy-table-wrap">
   <table class="fdy-table">
@@ -1164,12 +1323,13 @@ provide the state prop for a concern and you own that concern instead. React nam
 | `pageSizes?` · `onPageSizeChange?` | `readonly number[]` · `(size) => void` | Offer a rows-per-page control. Server mode reports the pick through the page event (read its `size`); client mode applies it itself and reports it too, so it works with nothing wired. |
 | `pager?` | `boolean` | Default true. Turn it off to withhold the table's own footer when the screen renders one. |
 | `loading?` | `boolean` | Show the in-table loading state. |
-| `emptyText?` · `empty?` | `string` · `ReactNode` | The empty state as text, or as markup (React `empty`, Vue's `empty` slot). |
+| `emptyText?` · `empty?` | `string` · `ReactNode \| (ctx) => ReactNode` | The empty state as text, or as markup (React `empty`, Vue's `empty` slot). As a React function or through the Vue slot's props it receives `{ filtered, clearFilters }`: whether an active column filter is what emptied the table, and how to clear every filter (through `onFiltersChange` / `update:filters` when they are controlled). "No rows match" wants a Clear button, "nothing here yet" a Create one. |
 | `ariaLabel?` | `string` | Names the table for assistive tech. |
 | `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`). |
+| `hoverActionable?` | `boolean` | Hover only the rows that do something (`rowActivatable`), `.fdy-table--hover-actionable`. A tint on a row with no handler promises a target that is not there. Inert rows keep their resting colour, stripe included. Off by default so existing tables do not change; planned as the default for 4.0. |
 | `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`. |
@@ -1181,7 +1341,8 @@ provide the state prop for a concern and you own that concern instead. React nam
 
 Blazor matches this surface (`LoadingText` and `EmptyContent` in place of `emptyText`/`empty`,
 `Toolbar` and `RowDetail` as `RenderFragment`s) and is the one adapter that also exposes
-`FiltersChanged`.
+`FiltersChanged`. Its filter-aware empty state is `EmptyTemplate`, a
+`RenderFragment<FdyTableEmptyContext>` (`Filtered`, `ClearFilters`) that wins over `EmptyContent`.
 
 **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
@@ -1309,6 +1470,11 @@ Empty / error placeholder for a data area. `--danger` for failures. Parts: `__ic
 (`aria-hidden="true"`) `__title` `__text` `__actions`. Put it inside the card or table area it
 replaces.
 
+`--compact` is the same state inside a small card or dashboard widget: icon and text on one line,
+`__actions` pushed to the end, no `__title`. Give a failed load its own `--compact --danger` line
+rather than rendering zero: a widget that shows 0 for a request that failed reads as "nothing to
+do", the opposite of what happened.
+
 ## Charts — `data-fdy-chart`
 > **Typed wrapper: `<FdyChart>`**. data props in all three (`type` + `values` / `series`); it repaints on data change, so `FreedayChart.update(el)` is only for the raw path below.
 
@@ -1410,12 +1576,55 @@ responsive `.fdy-datatable` should become below `md`, rather than a stack of `.f
 
 ## Description list — `.fdy-dl`
 Key–value detail view: `<dl class="fdy-dl">` with `<dt>`/`<dd>` pairs. `--rows` for a row-per-pair
-layout.
+layout. Every `dd` wraps a long unbreakable value (an email, an order code, a 13-digit phone) inside
+its column instead of printing over the next one.
+
+**`--grid` is the facts panel:** caption above value, each pair wrapped in a `<div>` (valid inside
+`<dl>`), in as many columns as the list's **own** width holds, never more than three. It is sized
+by the element, not the window, so the same markup is three columns in a wide main column and one
+column in a narrow side rail, with no modifier. `--fdy-dl-col-min` (default `14rem`) is the
+narrowest a column may get.
+
+```html
+<dl class="fdy-dl fdy-dl--grid">
+  <div><dt>Customer</dt><dd>PT Sumber Makmur</dd></div>
+  <div><dt>Email</dt><dd>procurement@sumbermakmur.co.id</dd></div>
+  <div><dt>Phone</dt><dd class="fdy-mono">0812345678901</dd></div>
+</dl>
+```
+
+A fact is not a field: use this for read-only values, `.fdy-form-grid` only where something can be
+typed.
 
 ---
 
 # Feedback
 
+## Copy a value — `[data-fdy-copy]`
+A button that copies a value the reader takes somewhere else: an external document number, an
+event ID. Needs `freeday-copy.js`; uses `Freeday.toast()` for its feedback.
+
+```html
+<dd>
+  <span class="fdy-mono">INV-2026-00042</span>
+  <button type="button" class="fdy-btn fdy-btn--ghost fdy-btn--icon fdy-btn--sm"
+          data-fdy-copy="INV-2026-00042" aria-label="Copy invoice number"><!-- copy svg --></button>
+</dd>
+```
+
+- **The value is the attribute.** Write it from the same variable as the visible text; a table row
+  needs no ids to find its own cell. An empty value copies nothing, so render the button only when
+  there is something to copy.
+- One delegated listener on the document: a button rendered later needs no hydration.
+- The toast says `Copied.` on success. Without a Clipboard API (plain `http`, an old browser) or
+  when the write is refused, a sticky danger toast tells the reader to copy by hand. A copy that
+  silently does nothing is the one outcome it never produces. Override both strings per button
+  with `data-fdy-text-copied` / `data-fdy-text-failed`.
+- Emits bubbling `fdy-copy` with `detail.value` and `detail.ok`.
+- Name the button for its value (`Copy invoice number`); an icon alone has no name.
+- Inside a clickable table row the click still reaches the row's handler. Stop it there if copying
+  should not also open the row.
+
 ## Alert — `.fdy-alert`
 Inline message. Modifiers `--info` `--success` `--warning` `--danger`. Parts `__icon` `__body`
 `__title` `__text` `__close`. The danger variant takes `role="alert"`.
@@ -1453,6 +1662,35 @@ something is in the top layer too. Where the Popover API is unavailable (before
 Safari 17 / Firefox 125) the region falls back to a fixed block at `z-index: 200`, which cannot
 clear an open modal, the message is still announced to a screen reader.
 
+## Confirm — `Freeday.confirm()`
+A yes/no question before an action that cannot be taken back. Imperative, like the toast. Needs
+`freeday-confirm.js`; renders a `.fdy-modal--sm`.
+
+```js
+const yes = await Freeday.confirm({
+  title: 'Delete order?',
+  message: 'Order SO-1042 will be deleted permanently.',
+  details: ['2 payments are deleted with it'],   // optional, shown as a list
+  acceptText: 'Delete order', rejectText: 'Keep', // name the action
+  tone: 'danger',                                 // 'primary' (default) | 'danger'
+})
+```
+
+- Resolves `true` on accept, `false` on reject, **Escape, or a click on the backdrop**. One dialog
+  gives one answer.
+- `details` is for a confirm that has to name its findings. Five findings folded into `message`
+  read as one long sentence.
+- Focus starts on the reject button, so an Enter that was meant for the page behind cannot
+  confirm. Focus returns to the opener when it closes, and the dialog leaves the DOM.
+- Text is set as text, never parsed as HTML, so a record name can go into `message` as is.
+- The buttons carry `data-fdy-confirm-accept` / `data-fdy-confirm-reject`. A test needs them: an
+  accept labelled "Delete" shares its accessible name with every row's own Delete button.
+- Defaults are `Confirm` / `Cancel`; pass `acceptText` / `rejectText` instead of relying on them.
+- Vue and React call it as is. Blazor awaits it through interop:
+  `await JS.InvokeAsync<bool>("Freeday.confirm", new { title = "Delete order?", tone = "danger" })`.
+- An "unsaved changes" guard is three lines on top of it, in your router's leave hook:
+  `return isDirty() ? Freeday.confirm({ … }) : true`.
+
 ## Tooltip — `.fdy-tooltip`
 Hover/focus only, never the sole carrier of information. Wrap in `.fdy-tooltip-wrap`; the trigger
 gets `aria-describedby` → the `.fdy-tooltip[role="tooltip"]` `id`.
@@ -1587,6 +1825,12 @@ for primary navigation (see Nav above).
 `.fdy-breadcrumb__item` (last one `aria-current="page"`, no link), `.fdy-breadcrumb__link`, and
 `.fdy-breadcrumb__sep` marked `aria-hidden="true"`.
 
+`aria-current="page"` belongs to the crumb that **is** this page, not to whichever crumb is last. A
+trail that stops at the parent (a record form whose last crumb is its list) keeps that crumb a
+link with no `aria-current`; otherwise the reader is told they are on the list while looking at a
+record. A crumb for a menu group that has no page of its own is plain text in the item, not a link
+to nowhere.
+
 ## Tabs — `.fdy-tabs`
 APG tabs: ←/→, Home/End, roving tabindex. Needs `freeday-tabs.js`.
 `.fdy-tabs__tab` marks its active state from **`aria-selected="true"` or `aria-current="page"`**,
@@ -1713,7 +1957,7 @@ is `role="group" aria-roledescription="slide"`.
 # Display
 
 ## Card — `.fdy-card`
-Parts `__body` `__title` `__desc` `__footer`. Modifiers:
+Parts `__head` `__body` `__title` `__desc` `__action` `__footer`. Modifiers:
 
 - `--elevated` raises it (use sparingly; most surfaces are flat)
 - `--interactive` gives cursor + hover-lift to a card that *has* a click handler. **Presentational
@@ -1730,6 +1974,26 @@ Parts `__body` `__title` `__desc` `__footer`. Modifiers:
 - The card is `position:relative`, so a badge or ribbon you absolutely position inside it anchors
   to the card. That is also what keeps hidden labels inside it from escaping. See *Containment*.
 
+**Header band: `__head`.** A mark, the title and the card's way out on one row, with a rule under
+it from edge to edge. The action sits beside the title so it is in the same place on every card;
+under the content it moved each time the content grew. The title truncates rather than wrapping
+under the action. The mark is an `.fdy-avatar --sm --square --tone-N`, so its tints are the ones
+the contrast gate already covers; pick the tone for what the card is **about** and keep it fixed.
+
+```html
+<article class="fdy-card">
+  <header class="fdy-card__head">
+    <span class="fdy-avatar fdy-avatar--sm fdy-avatar--square fdy-avatar--tone-3" aria-hidden="true"><!-- icon --></span>
+    <h3 class="fdy-card__title">Due today</h3>
+    <div class="fdy-card__action"><a class="fdy-btn fdy-btn--text fdy-btn--sm" href="/queue">View all</a></div>
+  </header>
+  <div class="fdy-card__body">…</div>
+</article>
+```
+
+A collapsible section whose band is a `<button>` cannot hold the action inside it (a button in a
+button is invalid and is read as one control): put `__action` beside the button, not in it.
+
 ### One card, one primary action, one escape hatch
 
 A card with **two** actions cannot be `--button`: interactive content nested in a `<button>` is
@@ -1790,6 +2054,8 @@ Initials or image. Sizes `--sm` / default / `--lg`; `.fdy-avatar-group` stacks t
 group). `--tone-1`…`--tone-8` are decorative tints (WCAG AA in both themes) to distinguish
 same-initial avatars. Hash the index off the **full** name, not the initials.
 
+`--square` for a mark that is not a person: a company logo, a card's icon chip.
+
 Sizes: `--xs` 1.5rem · *(base)* 2.5rem · `--sm` 2rem · `--lg` 3.5rem. Use **`--xs` inside a control**
 because `.fdy-btn--sm` is itself 2rem tall, so an `--sm` avatar fills a small button edge to edge and the
 ghost border cuts across the circle.

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-v3.4.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.4.0)
+[![Release](https://img.shields.io/badge/release-v3.6.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.6.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`.
@@ -60,7 +60,7 @@ npm i @cahyo-dimas/freeday
 ```js
 import '@cahyo-dimas/freeday/css';   // token + komponen (satu file)
 import '@cahyo-dimas/freeday';       // semua enhancer JS (auto-init [data-fdy-*])
-// granular bila perlu: '@cahyo-dimas/freeday/tokens' · '@cahyo-dimas/freeday/css/components' · '@cahyo-dimas/freeday/enhancers/<nama>'
+// granular bila perlu: '@cahyo-dimas/freeday/tokens' · '@cahyo-dimas/freeday/css/components' · '@cahyo-dimas/freeday/enhancers/<nama>' · '@cahyo-dimas/freeday/media' (breakpoint @custom-media)
 ```
 Set tema di root app: `<html data-theme="light" data-density="comfortable">`. `dist/` di-commit &
 ter-publish → install tanpa build step; minify diserahkan ke bundler konsumen. Karena terbit di
@@ -153,9 +153,13 @@ container-nya, bukan scroll sendiri.
   menyusut/melebar saat `data-density` berubah.
 - (roadmap) `data-style` untuk varian visual lain.
 - Skala breakpoint (`sm`/`md`/`lg`/`xl` = 600/960/1280/1920px, sama dengan utilitas
-  `src/components/breakpoints.css`) juga tersedia di JS: `import { breakpoints } from
-  '@cahyo-dimas/freeday/breakpoints'`. Pakai itu untuk menyamakan `matchMedia`/`@media` app-mu
-  dengan skala Freeday.
+  `src/components/breakpoints.css`) tersedia untuk app-mu dalam dua bahasa: `import { breakpoints }
+  from '@cahyo-dimas/freeday/breakpoints'` untuk JS (`matchMedia`, varian utility), dan `@import
+  '@cahyo-dimas/freeday/media'` untuk CSS, yang mendeklarasikan tiap lebar sebagai `@custom-media`
+  sehingga sebuah rule ditulis `@media (--fdy-below-sm)`, bukan literal yang diketik ulang (butuh
+  PostCSS; opt-in). Objeknya juga membawa dua lebar yang **bukan** anak tangga ramp dan tak boleh
+  dibulatkan ke salah satunya: `nav` (721, saklar drawer↔sidebar milik shell) dan `filterbar` (640,
+  tempat `.fdy-filterbar` menumpuk). Lihat [`COMPONENTS.md`](COMPONENTS.md) untuk apa yang diaturnya.
 
 ## Integrasi framework (SPA)
 > **Peta library lengkap:** [`docs/integrations.md`](docs/integrations.md). Tiap area