@cahyo-dimas/freeday 3.10.0 → 3.12.0

package/CHANGELOG.md

@@ -9,6 +9,111 @@ 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.12.0] - 2026-10-27
+
+**Sebuah form kini dapat menuntut kontrol kit terisi.** `data-fdy-validate` mewirekan Constraint
+Validation **native**: `isCandidate` menuntut `willValidate` dan menolak `type === 'button'`, dan
+pemicu kontrol kit memang `<button>`. Jadi `form.elements` tak pernah menawarkannya, `required` di
+atasnya tak berarti apa pun, dan form tak bisa menuntut combo, datepicker, monthpicker, timepicker
+atau cascade diisi.
+
+Ini yang menahan audit 3.11.0 di 3 dari 7 pemilih. Empat `<input type="time">` di formulir shift
+keamanan-cluster tetap native **hanya** karena menukarnya ke `FdyTimepicker` akan memperbaiki
+penampilannya dan diam-diam membuang penegakan wajib-isinya.
+
+Koreksi atas catatan rilis sebelumnya, yang layak dibawa: ia menulis "tiga belas wrapper bertipe
+merender `<button>`". Salah. Hanya **lima** yang berpemicu tombol; `FdyAutocomplete` dan `FdyCfl`
+merender `<input>` asli, dan tujuh sisanya bukan kontrol bernilai. Angka yang dibesarkan membuat
+perbaikan ini terdengar jauh lebih mahal daripada yang ternyata.
+
+### Added
+- **`data-fdy-required` pada akar kontrol** (`#096`), dan prop `required` / `Required` di
+  `FdyCombo`, `FdyDatepicker`, `FdyMonthpicker`, `FdyTimepicker` dan `FdyCascade` di ketiga stack.
+  Submit ditolak, pesannya dilukis di slot `.fdy-field` yang sudah ada, dan fokusnya ke pemicu.
+  Aturannya **tidak menyebut satu pun nama komponen**: nilainya dibaca dari `data-value`, elemen
+  yang menerima `aria-invalid` dan fokus ditemukan lewat `aria-haspopup` yang sudah dipasang setiap
+  pemicu, dan re-validasinya memakai `MutationObserver` pada atribut itu — supaya enhancer tak
+  perlu mengenal lima nama event (`fdy-change`, `fdy-datepicker-change`, `fdy-time-select`,
+  `fdy-cascade-change`).
+- **Kontrol yang ditolak diurut menurut urutan DOM** (`#096`). Mengumpulkan kontrol native lebih
+  dulu lalu akar kit akan memfokuskan field KEDUA sementara yang pertama juga merah, dan pembaca
+  yang dikirim melewati field merah pertamanya belajar hal yang salah.
+
+### Changed
+- **`data-value` di akar kontrol kini cermin hidup, bukan seed.** Di jalur mentah, datepicker,
+  timepicker dan cascade hanya MEMBACANYA saat init; `freeday-select.js` sudah menulisnya kembali
+  sejak lama, jadi ini membuat keluarganya sepakat alih-alih memperkenalkan atribut kedua. Aditif:
+  tak ada yang membaca atribut itu sesudah init, sebab sebelum ini nilainya basi. Cerminnya
+  dipasang di `updateDisplay()`, satu titik sempit yang dilalui pick, clear, pilih-bulan dan
+  setRange, bukan di tiap tempat event dikirim.
+
+### Fixed
+- **`FdyDatepicker`, `FdyMonthpicker` dan `FdyCascade` tak pernah mencerminkan nilainya ke akar**
+  di adapter Vue dan React (`#096`), padahal `FdyCombo` dan `FdyTimepicker` melakukannya. Tanpa itu
+  aturan di atas mustahil, dan atributnya juga pegangan yang dapat dibaca uji atau aturan CSS
+  keadaan-kosong.
+
+### Catatan
+- `FdyAutocomplete` dan `FdyCfl` **di luar** aturan ini: keduanya merender `<input>` asli, jadi
+  `required` native yang cocok. Belum ada prop yang mengeksposnya, dan atribut tak dikenal jatuh ke
+  AKAR wrapper bukan ke input di dalamnya, jadi hari ini keduanya tak bisa dijadikan wajib di stack
+  mana pun. Dicatat terbuka di `NEXT-UP.md` alih-alih ditutup separuh: mengalirkannya lewat jalur
+  kit akan memberi satu field dua sumber kebenaran.
+- Penimpaan pesan per-kontrol (`data-fdy-msg-required` di akar) bekerja di mana atribut mencapai
+  akar: jalur mentah, dan Vue, yang meneruskan atribut tak dikenal. React dan Blazor tidak, jadi
+  jalur yang terbaca sama di semua stack adalah `data-fdy-text-required` di elemen `<form>`.
+
+## [3.11.0] - 2026-10-26
+
+**Audit kontrol native di seluruh layar sebuah aplikasi konsumen, bukan di satu layar yang
+mengeluh.** Pemiliknya melaporkan tampilan HP aslinya tak cocok dengan peramban di lebar yang sama,
+dan dugaan pertama -- termasuk dugaan saya -- adalah CSS. Pengukuran menyangkalnya: dengan
+stylesheet aplikasi yang sebenarnya, pada 375x667, Chromium dan WebKit menata `date`, `time`,
+`number`, `search` dan `text` **identik**, 293x44 keenamnya, selisih satu piksel pada `y` yang
+cuma pembulatan. Jadi yang berbeda bukan tata letaknya, melainkan **widget native-nya**: `date` dan
+`time` digambar sistem operasi, sehingga iOS memberi roda gulir, Android piringan jam dan desktop
+sebuah stepper, masing-masing dengan lebar dan format nilainya sendiri, dan tak ada CSS yang
+menjangkaunya. Itu sebabnya satu HP dan satu peramban di lebar yang sama bisa tidak sepakat soal
+layar yang selebihnya sama.
+
+Kit sudah mengatakan ini di tabelnya sendiri ("Use `.fdy-datepicker` / `.fdy-timepicker` /
+`.fdy-datetimepicker` instead") dan sudah mengirim CSS plus enhancer-nya. Yang belum ada adalah
+wrapper bertipe untuk timepicker, jadi aplikasi Vue/React/Blazor harus merakit sendiri
+plumbing custom-event-nya -- dan merakit sendiri adalah yang membuat empat `<input type="time">`
+bertahan di satu formulir shift.
+
+Catatan kejujuran: perbedaan iOS itu **tidak** direproduksi di sini. WebKit desktop bukan Mobile
+Safari, dan penampilan kontrol native memang bersifat platform; buktinya adalah tangkapan layar
+perangkat nyata plus fakta terukur bahwa tata letak per lebar sudah identik. Yang dapat diuji
+lokal, dan kini diuji, adalah perilaku penggantinya.
+
+### Added
+- **`FdyTimepicker`** (`#094`), wrapper bertipe di **ketiga** stack, menjadikannya tiga belas.
+  Vue dan React mengimplementasikan listbox-nya secara native sebab ia kontrol form -- alasan yang
+  sama dengan `FdyCombo`, dan alasan yang `FdyChart` nyatakan dari sisi sebaliknya: enhancer yang
+  menguasai DOM berkelahi dengan render framework dan tak menyisakan `v-model`. Blazor
+  menjembatani enhancer lewat seed, seperti `FdyDatepicker`. Sorotannya **dijepit, bukan
+  berputar**: pada daftar 48 opsi, ArrowUp di `00:00` yang melompat ke `23:30` terbaca sebagai
+  kerusakan. Sorotan juga digulirkan ke dalam pandangan, sebab panelnya `max-height:15rem` dan
+  sorotan yang tak terlihat bukan sorotan.
+- **`data-id` dan `data-describedby` pada seed timepicker** (`#094`). Keduanya tak terbaca
+  sebelumnya, jadi host yang menampilkan teks galat tak punya cara menautkannya. Pemicunya
+  `<button>`, yang **bukan** elemen labelable, sehingga `<label for>` memang tak akan pernah
+  mengaktifkannya -- itu didokumentasikan sekarang, bukan dibiarkan jadi kejutan.
+- **`FreedayTimepicker.setState(root, { disabled, readonly, invalid })`** (`#094`), bentuknya sama
+  dengan `FreedayDatepicker.setState`. Tanpa ini, host yang merender seed-nya sekali lalu tidak
+  pernah lagi (Blazor, `ShouldRender => false`) memiliki tiga parameter keadaan yang tak ada yang
+  membacanya setelah render pertama.
+
+### Fixed
+- **`FdyDateRange` membuang kedelapan prop label navigasi kalender** (`#095`), di ketiga stack.
+  `FdyDatepicker` menerimanya sejak 2.1.1; rentangnya tidak meneruskannya, sehingga rentang tanggal
+  adalah **satu-satunya** kontrol tanggal di kit yang navigasinya tak bisa dinamai dalam bahasa
+  halamannya sendiri -- aplikasi berbahasa Indonesia mendapat "Previous month" tepat di tempat yang
+  tak dapat ia jangkau. Diteruskan apa adanya ke kedua pemilih. Prop datar `xxxLabel`, bukan objek
+  `labels`, sebab bentuk itulah yang sudah dipakai setiap komponen lain di kit. Blazor menambah
+  `BackToMonthsLabel`, karena seed yang kedua pemilihnya dibangun dari situ punya tombol itu.
+
 ## [3.10.0] - 2026-10-26
 
 **Lima rilis dalam satu hari, empat di antaranya menambal satu kelas yang sama, dan pemiliknya

package/COMPONENTS.md

@@ -34,8 +34,9 @@ live docs.
    invalid state does not belong to the control itself.
 6. **Interactive components need their enhancer script.** Static ones (button, card, badge, table,
    alert, breadcrumb, timeline, accordion, tree-without-cascade…) are CSS-only.
-7. **On Vue, React or Blazor, twelve components have a typed wrapper. Use it.** `FdyCombo` ·
-   `FdyDatepicker` · `FdyMonthpicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` · `FdyCfl` ·
+7. **On Vue, React or Blazor, thirteen components have a typed wrapper. Use it.** `FdyCombo` ·
+   `FdyDatepicker` · `FdyMonthpicker` · `FdyDateRange` · `FdyTimepicker` · `FdyAutocomplete` ·
+   `FdyCascade` · `FdyCfl` ·
    `FdyChart` · `FdyTable` · `FdyModal` · `FdyDrawer` · `FdyAppShell`, from `@cahyo-dimas/freeday/vue`, `/react`, or the
    `Freeday.Blazor` RCL. Each is flagged at its own section below. Hand-writing their raw markup in
    those stacks *looks* right at first, because the enhancer initialises once and the first render is
@@ -708,6 +709,7 @@ while each line referenced directly would be read even when hidden. Zero JS; wor
 | `ariaLabelledby?` | `string` | Id of the element that labels the combobox. |
 | `placeholder?` | `string` | Shown when no option matches the current value. |
 | `disabled?` | `boolean` | Greyed and out of the tab order, the native `disabled` semantics. |
+| `required?` | `boolean` | Lets a [`data-fdy-validate`](#form-validation--data-fdy-validate) form demand this control be filled. Renders `data-fdy-required` on the root. Needed because the trigger is a `<button>`, whose `willValidate` is false, so a plain `required` on it has never meant anything. Blazor: `Required`. |
 | `readonly?` | `boolean` | Locked/view mode: keeps focus and tab order and shows its value, but cannot be opened or changed. Unlike `disabled` it is not greyed. |
 | `invalid?` | `boolean` | Sets `aria-invalid`; pair it with `describedby` pointing at the error text. |
 | `describedby?` | `string` | Id of the help or error text (`aria-describedby`). |
@@ -785,6 +787,7 @@ Editable combobox that filters as you type. Needs `freeday-autocomplete.js`.
 | `placeholder?` | `string` | |
 | `id?` · `ariaLabelledby?` · `describedby?` | `string` | Trigger id; the element that labels it; the help/error text it points at. |
 | `disabled?` · `readonly?` · `invalid?` | `boolean` | As on `<FdyCombo>`. |
+| `required?` | `boolean` | Lets a [`data-fdy-validate`](#form-validation--data-fdy-validate) form demand this control be filled. Renders `data-fdy-required` on the root. Needed because the trigger is a `<button>`, whose `willValidate` is false, so a plain `required` on it has never meant anything. Blazor: `Required`. |
 
 Raw path: `data-disabled` / `data-readonly` / `data-invalid`, `data-id`, `data-describedby`, and
 `FreedayCascade.setState(root, { disabled, readonly, invalid })` for a host that rendered once.
@@ -961,6 +964,7 @@ a new class.
 | `placeholder?` | `string` | |
 | `id?` · `ariaLabelledby?` · `describedby?` | `string` | Trigger id; the element that labels it; the help/error text it points at. |
 | `disabled?` · `readonly?` · `invalid?` | `boolean` | `readonly` keeps focus and tab order and shows its date, but it cannot be opened, cleared or changed. |
+| `required?` | `boolean` | Lets a [`data-fdy-validate`](#form-validation--data-fdy-validate) form demand this control be filled. Renders `data-fdy-required` on the root. Needed because the trigger is a `<button>`, whose `willValidate` is false, so a plain `required` on it has never meant anything. Blazor: `Required`. |
 | `clearable?` | `boolean` | Show a × in the trigger once a date is set, so an optional date can be unset. Sends `''`. Off by default. |
 | `clearLabel?` | `string` | Accessible name for that ×. Default `Clear date`. |
 | `prevMonthLabel?` · `nextMonthLabel?` | `string` | The month arrows. Defaults `Previous month` / `Next month`. |
@@ -995,6 +999,7 @@ page's `<html lang>`), `clearable` and `clearLabel` (this path builds no clear b
 | `placeholder?` | `string` | Shown while nothing is picked. Default `Select month`. |
 | `id?` · `ariaLabelledby?` · `describedby?` | `string` | Trigger id; the element that labels it; the help/error text it points at. |
 | `disabled?` · `readonly?` · `invalid?` | `boolean` | `readonly` keeps focus and tab order and shows its month, but it cannot be opened, cleared or changed. |
+| `required?` | `boolean` | Lets a [`data-fdy-validate`](#form-validation--data-fdy-validate) form demand this control be filled. Renders `data-fdy-required` on the root. Needed because the trigger is a `<button>`, whose `willValidate` is false, so a plain `required` on it has never meant anything. Blazor: `Required`. |
 | `clearable?` | `boolean` | Show a × in the trigger once a month is set, so an optional month can be unset. Sends `''`. Off by default. |
 | `clearLabel?` | `string` | Accessible name for that ×. Default `Clear month`. |
 | `prevYearLabel?` · `nextYearLabel?` | `string` | The arrows beside the month grid, which step a year. Defaults `Previous year` / `Next year`. |
@@ -1020,6 +1025,7 @@ grid's own title.
 | `startPlaceholder?` · `endPlaceholder?` | `string` | One per field. |
 | `ariaLabel?` · `ariaLabelledby?` · `describedby?` | `string` | Names the group (`role="group"`), or points at the text that does. |
 | `disabled?` · `readonly?` · `invalid?` | `boolean` | Applied to both pickers together. |
+| `prevMonthLabel?` · `nextMonthLabel?` · `prevYearLabel?` · `nextYearLabel?` · `prevYearsLabel?` · `nextYearsLabel?` · `chooseMonthLabel?` · `chooseYearLabel?` | `string` | Forwarded verbatim to **both** pickers. Until 3.11.0 this was the one picker in the kit whose calendar nav could not be named in the page's own language: the single picker took these, the range dropped them. Blazor adds `BackToMonthsLabel`, since the raw seed both pickers are built from has that button. |
 
 Blazor splits the value into two scalars, `From` / `FromChanged` and `To` / `ToChanged`, because a
 C# binding cannot express one object bound in two places, and it adds `Separator`.
@@ -1106,10 +1112,53 @@ it has always been, down to the `YYYY-MM-DD` it reports.
 ```
 
 ## Time picker — `data-fdy-timepicker`
-24-hour `HH:MM` listbox. `data-step` (minutes, default 30), `data-min`, `data-max`. Needs
+> **Typed wrapper: `<FdyTimepicker>`**. 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).
+
+24-hour `HH:MM` listbox. **Author an empty `<div>`** — the enhancer builds everything. Needs
 `freeday-timepicker.js`. Classes: `.fdy-timepicker` (+`--error`) · `__trigger` `__value`
 (+`--placeholder`) `__icon` `__panel` `__opt`.
 
+Seed attributes: `data-step` (minutes, default 30), `data-min` (default `00:00`), `data-max`
+(default `23:59`), `data-value`, `data-label`, `data-placeholder` (default `--:--`), `data-id`,
+`data-describedby`, `data-disabled`, `data-readonly`, `data-invalid`. Emits a bubbling
+`fdy-time-select` (`detail {value}`). `FreedayTimepicker.setState(root, { disabled, readonly,
+invalid })` changes the three states afterwards, which is what a host that renders its seed once
+and never again (Blazor) needs.
+
+**Use this instead of `<input type="time">`**, and not for theming alone: the native picker is
+drawn by the *operating system*, so iOS shows a scroll wheel, Android a clock dial and desktop a
+stepper, each with its own width and value format, and no CSS reaches any of them. A phone and a
+browser at the same width therefore disagree about a screen that is otherwise identical.
+
+```html
+<div data-fdy-timepicker data-step="15" data-min="06:00" data-max="22:00"
+     data-value="07:00" data-label="Jam mulai"></div>
+```
+
+### Props — `<FdyTimepicker>`
+
+| Prop | Type | What it does |
+|---|---|---|
+| `modelValue` · `value` | `string \| null` | `HH:MM`, 24-hour. `''`/`null` for empty. A loose `H:MM` is normalised for matching. Blazor: `Value` / `@bind-Value`. |
+| `onChange` | `(value: string) => void` | React. Vue emits `update:modelValue` and `change`, Blazor `ValueChanged`. |
+| `step?` | `number` | Minutes between options. Default 30. |
+| `min?` · `max?` | `string` | `HH:MM` bounds, inclusive. Default `00:00` to `23:59`. |
+| `placeholder?` | `string` | Shown when there is no value. Default `--:--`. |
+| `ariaLabel?` · `ariaLabelledby?` · `describedby?` | `string` | Names the trigger, or points at the text that does. Blazor: `Label` / `Describedby`. |
+| `id?` | `string` | Id for the trigger. It is a `<button>`, which is **not** a labelable element, so a `<label for>` will not activate it — name it with `ariaLabel`/`ariaLabelledby`. |
+| `disabled?` · `readonly?` · `invalid?` | `boolean` | `readonly` keeps tab order and shows the time but will not open. |
+| `required?` | `boolean` | Lets a [`data-fdy-validate`](#form-validation--data-fdy-validate) form demand this control be filled. Renders `data-fdy-required` on the root. Needed because the trigger is a `<button>`, whose `willValidate` is false, so a plain `required` on it has never meant anything. Blazor: `Required`. |
+
+Keyboard: `ArrowDown`/`ArrowUp` move one option, `Home`/`End` jump to the ends, `Enter`/`Space`
+pick, `Escape` closes. The highlight is **clamped, not cyclic** — `ArrowUp` at `00:00` stays there,
+because wrapping to `23:30` reads as a glitch in a list this long — and it is scrolled into view,
+since the panel is `max-height:15rem` and a highlight nobody can see is no highlight.
+
+**Deliberate difference between the two paths.** The wrappers keep focus on the **trigger** with
+`aria-activedescendant` on it, which is what `FdyCombo`, `FdyDatepicker` and `FdyAutocomplete` do;
+the raw enhancer moves focus **into the panel**. Both are valid APG listbox patterns, and the Vue
+and React adapters follow their own family rather than the enhancer.
+
 ## Datetime picker — `data-fdy-datetimepicker`
 A **composition** of the two above, not a monolith: nest one datepicker and one timepicker inside
 the wrapper. `freeday-datetime.js` joins them and emits one `fdy-datetime-change` with
@@ -1179,6 +1228,26 @@ 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 kit control can be required too** — `data-fdy-required` on its root. Combo, datepicker,
+  monthpicker, timepicker and cascade build a `<button>` trigger, and a button's `willValidate` is
+  false, so `form.elements` never offered one and `required` on it meant nothing. The enhancer now
+  collects these roots alongside the native controls: empty `data-value` refuses the submit, the
+  message lands in the same `.fdy-field` slot, and the focus goes to the trigger. It names no
+  component — the value is read from `data-value` and the trigger is found by `aria-haspopup`. In
+  the typed stacks pass `required` / `Required` instead of writing the attribute.
+  **`FdyAutocomplete` and `FdyCfl` are outside this rule**: they render a real `<input>`, so the
+  native `required` is the mechanism that fits them — but no prop exposes it yet, and an unknown
+  attribute falls through to a wrapper's ROOT rather than to the input inside it, so today an app
+  cannot require either one. Tracked in `NEXT-UP.md`; the rule above deliberately does not cover
+  them, because painting a native input through the kit path would give it two sources of truth.
+  Re-validation watches the attribute with a `MutationObserver`, so no control has to announce
+  itself. The message override is per-control (`data-fdy-msg-required` on the root) wherever
+  attributes reach the root — the raw path, and Vue, where an unknown attribute falls through. In
+  React and Blazor they do not, so use the form-level `data-fdy-text-required`, which reads the
+  same in every stack.
+- **`data-value` on a control's root is the live value**, not just the seed it used to be on the
+  datepicker, timepicker and cascade (the combo always kept it current). That is what makes the
+  rule above possible, and it is also the handle a test or a CSS empty-state rule can read.
 - **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

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.10.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.10.0)
+[![Release](https://img.shields.io/badge/release-v3.12.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.12.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`.
@@ -44,9 +44,9 @@ enhancer:
 | **Blazor (net8.0)** | RCL `Freeday.Blazor` | `@bind-Value` |
 | HTML statis · Svelte · template server-rendered | *(tanpa wrapper)* markup mentah + enhancer, di bawah | event `fdy-*` |
 
-Kedua belasnya: `FdyCombo` · `FdyDatepicker` · `FdyMonthpicker` · `FdyDateRange` ·
-`FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart` · `FdyTable` · `FdyModal` · `FdyDrawer` ·
-`FdyAppShell`. Menulis markup mentah untuk kedua belas ini di dalam Vue/React/Blazor *kelihatan* baik-baik saja pada mulanya, karena render
+Ketiga belasnya: `FdyCombo` · `FdyDatepicker` · `FdyMonthpicker` · `FdyDateRange` ·
+`FdyTimepicker` · `FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart` · `FdyTable` · `FdyModal` · `FdyDrawer` ·
+`FdyAppShell`. Menulis markup mentah untuk ketiga belas ini di dalam Vue/React/Blazor *kelihatan* baik-baik saja pada mulanya, karena render
 pertamanya memang benar. Setelah itu ia rusak diam-diam: DOM yang di-render framework belakangan tak pernah ter-hydrate, dan state widget
 berakhir di DOM alih-alih di state framework-mu. Selebihnya (button, card, badge, alert, markup
 tabel, layout, dan komponen interaktif yang tak punya wrapper) sama persis di semua stack. Untuk

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-v3.10.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.10.0)
+[![Release](https://img.shields.io/badge/release-v3.12.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.12.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`.
@@ -44,8 +44,8 @@ enhancer:
 | **Blazor (net8.0)** | `Freeday.Blazor` RCL | `@bind-Value` |
 | Static HTML · Svelte · server-rendered templates | *(no wrapper)* raw markup + enhancers, below | `fdy-*` events |
 
-The twelve: `FdyCombo` · `FdyDatepicker` · `FdyMonthpicker` · `FdyDateRange` · `FdyAutocomplete` ·
-`FdyCascade` · `FdyCfl` · `FdyChart` · `FdyTable` · `FdyModal` · `FdyDrawer` · `FdyAppShell`.
+The thirteen: `FdyCombo` · `FdyDatepicker` · `FdyMonthpicker` · `FdyDateRange` · `FdyTimepicker` ·
+`FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart` · `FdyTable` · `FdyModal` · `FdyDrawer` · `FdyAppShell`.
 Hand-writing the raw
 markup for these inside Vue/React/Blazor *looks* fine at first, because the first render is correct.
 Then it breaks quietly:

package/adapters/blazor/FdyCascade.razor

@@ -16,7 +16,8 @@
      data-describedby="@Describedby"
      data-disabled="@(Disabled ? "true" : null)"
      data-readonly="@(Readonly ? "true" : null)"
-     data-invalid="@(Invalid ? "true" : null)">
+     data-invalid="@(Invalid ? "true" : null)"
+     data-fdy-required="@(Required ? "" : null)">
     <ul>
         @foreach (FdyCascadeNode node in Nodes)
         {

package/adapters/blazor/FdyCascade.razor.cs

@@ -46,6 +46,13 @@ public partial class FdyCascade
     /// <summary>Marks the field invalid (<c>aria-invalid</c> + the error styling).</summary>
     [Parameter] public bool Invalid { get; set; }
 
+    /// <summary>Let a <c>data-fdy-validate</c> form demand this control be filled. Renders
+    /// <c>data-fdy-required</c> on the root, and <c>freeday-form.js</c> refuses the submit, paints
+    /// the message in the field and focuses the trigger. Needed because the trigger is a
+    /// <c>&lt;button&gt;</c>: <c>willValidate</c> is false, so a plain <c>required</c> on it has
+    /// never meant anything. Override the message with <c>data-fdy-msg-required</c> on the root.</summary>
+    [Parameter] public bool Required { get; set; }
+
     protected override bool ShouldRender() => !Hydrated;
 
     /* Pushed, not re-rendered: the seed's <ul> is consumed and removed by the enhancer, so this

package/adapters/blazor/FdyCombo.razor

@@ -6,7 +6,8 @@
    markup the freeday-select.js enhancer expects; the enhancer owns the open/keyboard/focus
    behaviour and emits fdy-change, which flows back to @bind-Value. An externally-changed Value
    is pushed onto the enhancer silently (no event echo). *@
-<div @ref="Root" class="@RootClass" data-fdy-combo data-value="@SelectedKey">
+<div @ref="Root" class="@RootClass" data-fdy-combo data-value="@SelectedKey"
+     data-fdy-required="@(Required ? "" : null)">
     <button id="@ButtonId" type="button" class="fdy-combo__button" role="combobox"
             aria-haspopup="listbox" aria-expanded="false"
             aria-labelledby="@AriaLabelledby"

package/adapters/blazor/FdyCombo.razor.cs

@@ -29,6 +29,13 @@ public partial class FdyCombo<TValue>
 
     [Parameter] public bool Invalid { get; set; }
 
+    /// <summary>Let a <c>data-fdy-validate</c> form demand this control be filled. Renders
+    /// <c>data-fdy-required</c> on the root, and <c>freeday-form.js</c> refuses the submit, paints
+    /// the message in the field and focuses the trigger. Needed because the trigger is a
+    /// <c>&lt;button&gt;</c>: <c>willValidate</c> is false, so a plain <c>required</c> on it has
+    /// never meant anything. Override the message with <c>data-fdy-msg-required</c> on the root.</summary>
+    [Parameter] public bool Required { get; set; }
+
     /// <summary>Id of the help or error text the combobox describes itself with. Vue and React
     /// have always had this one; Blazor was the odd stack out.</summary>
     [Parameter] public string? Describedby { get; set; }

package/adapters/blazor/FdyDateRange.razor

@@ -8,9 +8,27 @@
 <div @ref="Root">
     <div data-fdy-daterange role="group" aria-label="@AriaLabel">
         <div data-fdy-datepicker data-role="from"
-             data-value="@From" data-placeholder="@FromPlaceholder" data-min="@Min" data-max="@Max"></div>
+             data-value="@From" data-placeholder="@FromPlaceholder" data-min="@Min" data-max="@Max"
+             data-fdy-text-prev-month="@PrevMonthLabel"
+             data-fdy-text-next-month="@NextMonthLabel"
+             data-fdy-text-prev-year="@PrevYearLabel"
+             data-fdy-text-next-year="@NextYearLabel"
+             data-fdy-text-prev-years="@PrevYearsLabel"
+             data-fdy-text-next-years="@NextYearsLabel"
+             data-fdy-text-choose-month="@ChooseMonthLabel"
+             data-fdy-text-choose-year="@ChooseYearLabel"
+             data-fdy-text-back-to-months="@BackToMonthsLabel"></div>
         <span class="fdy-daterange__sep">@Separator</span>
         <div data-fdy-datepicker data-role="to"
-             data-value="@To" data-placeholder="@ToPlaceholder" data-min="@Min" data-max="@Max"></div>
+             data-value="@To" data-placeholder="@ToPlaceholder" data-min="@Min" data-max="@Max"
+             data-fdy-text-prev-month="@PrevMonthLabel"
+             data-fdy-text-next-month="@NextMonthLabel"
+             data-fdy-text-prev-year="@PrevYearLabel"
+             data-fdy-text-next-year="@NextYearLabel"
+             data-fdy-text-prev-years="@PrevYearsLabel"
+             data-fdy-text-next-years="@NextYearsLabel"
+             data-fdy-text-choose-month="@ChooseMonthLabel"
+             data-fdy-text-choose-year="@ChooseYearLabel"
+             data-fdy-text-back-to-months="@BackToMonthsLabel"></div>
     </div>
 </div>

package/adapters/blazor/FdyDateRange.razor.cs

@@ -23,6 +23,26 @@ public partial class FdyDateRange
     [Parameter] public string? Max { get; set; }
     [Parameter] public string Separator { get; set; } = "–";
 
+    /* The calendars' own navigation labels, forwarded verbatim to BOTH pickers. Month and weekday
+       NAMES follow the page's `lang` through Intl and need nothing here; these are the buttons
+       around them. Until now the range was the one picker in the kit whose nav could not be named
+       in the page's own language -- FdyDatepicker took these, FdyDateRange dropped them, so an
+       Indonesian app got "Previous month" on the only date control it could not reach. Raised
+       from keamanan-cluster (#095). */
+    [Parameter] public string? PrevMonthLabel { get; set; }
+    [Parameter] public string? NextMonthLabel { get; set; }
+    [Parameter] public string? PrevYearLabel { get; set; }
+    [Parameter] public string? NextYearLabel { get; set; }
+    [Parameter] public string? PrevYearsLabel { get; set; }
+    [Parameter] public string? NextYearsLabel { get; set; }
+    [Parameter] public string? ChooseMonthLabel { get; set; }
+    [Parameter] public string? ChooseYearLabel { get; set; }
+
+    /// <summary>The year grid's title, back to months. Blazor only, because the raw seed both
+    /// pickers are built from supports it and <see cref="FdyDatepicker"/> already exposes it;
+    /// the Vue and React adapters build no such button.</summary>
+    [Parameter] public string? BackToMonthsLabel { get; set; }
+
     private int _token;
 
     // initAll(Root) links the daterange (descendant) and inits both child pickers.

package/adapters/blazor/FdyDatepicker.razor

@@ -18,6 +18,7 @@
      data-disabled="@(Disabled ? "true" : null)"
      data-readonly="@(Readonly ? "true" : null)"
      data-invalid="@(Invalid ? "true" : null)"
+     data-fdy-required="@(Required ? "" : null)"
      data-fdy-text-prev-month="@PrevMonthLabel"
      data-fdy-text-next-month="@NextMonthLabel"
      data-fdy-text-prev-year="@PrevYearLabel"

package/adapters/blazor/FdyDatepicker.razor.cs

@@ -54,6 +54,13 @@ public partial class FdyDatepicker
     /// <summary>Marks the field invalid (<c>aria-invalid</c> + the error styling).</summary>
     [Parameter] public bool Invalid { get; set; }
 
+    /// <summary>Let a <c>data-fdy-validate</c> form demand this control be filled. Renders
+    /// <c>data-fdy-required</c> on the root, and <c>freeday-form.js</c> refuses the submit, paints
+    /// the message in the field and focuses the trigger. Needed because the trigger is a
+    /// <c>&lt;button&gt;</c>: <c>willValidate</c> is false, so a plain <c>required</c> on it has
+    /// never meant anything. Override the message with <c>data-fdy-msg-required</c> on the root.</summary>
+    [Parameter] public bool Required { get; set; }
+
     /* The calendar's own navigation labels. Month and weekday NAMES follow the page's `lang`
        through Intl and need nothing here; these are the buttons around them, which until 2.1.1
        were literals inside the enhancer that no host could reach. Leave one null and the

package/adapters/blazor/FdyMonthpicker.razor

@@ -21,6 +21,7 @@
      data-disabled="@(Disabled ? "true" : null)"
      data-readonly="@(Readonly ? "true" : null)"
      data-invalid="@(Invalid ? "true" : null)"
+     data-fdy-required="@(Required ? "" : null)"
      data-fdy-text-prev-year="@PrevYearLabel"
      data-fdy-text-next-year="@NextYearLabel"
      data-fdy-text-prev-years="@PrevYearsLabel"

package/adapters/blazor/FdyMonthpicker.razor.cs

@@ -57,6 +57,13 @@ public partial class FdyMonthpicker
     /// <summary>Marks the field invalid (<c>aria-invalid</c> + the error styling).</summary>
     [Parameter] public bool Invalid { get; set; }
 
+    /// <summary>Let a <c>data-fdy-validate</c> form demand this control be filled. Renders
+    /// <c>data-fdy-required</c> on the root, and <c>freeday-form.js</c> refuses the submit, paints
+    /// the message in the field and focuses the trigger. Needed because the trigger is a
+    /// <c>&lt;button&gt;</c>: <c>willValidate</c> is false, so a plain <c>required</c> on it has
+    /// never meant anything. Override the message with <c>data-fdy-msg-required</c> on the root.</summary>
+    [Parameter] public bool Required { get; set; }
+
     /* The calendar's navigation labels, and only the ones this picker shows. Month NAMES follow the
        page's `lang` through Intl and need nothing here. The day grid's own arrows are absent along
        with the day grid, so there is no PrevMonthLabel to pass: the arrows beside a month grid step

package/adapters/blazor/FdyTimepicker.razor

@@ -0,0 +1,24 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyTimepicker>
+
+@* Seed-based wrapper over freeday-timepicker.js: the enhancer builds the input-styled trigger
+   + time listbox from this empty div and emits fdy-time-select. The enhancer owns that DOM, so
+   the seed renders once (ShouldRender => false) and the picked time is read back through
+   @bind-Value. Value is "HH:MM" (24-hour) or "".
+
+   This is what replaces <input type="time">, and not for theming alone: the native picker is
+   drawn by the OPERATING SYSTEM, so iOS shows a scroll wheel, Android a clock dial and desktop a
+   stepper, each with its own width and value format, and no CSS reaches any of them (#094). *@
+<div @ref="Root" data-fdy-timepicker
+     data-value="@Value"
+     data-label="@Label"
+     data-placeholder="@Placeholder"
+     data-step="@StepAttribute"
+     data-min="@Min"
+     data-max="@Max"
+     data-id="@Id"
+     data-describedby="@Describedby"
+     data-disabled="@(Disabled ? "true" : null)"
+     data-readonly="@(Readonly ? "true" : null)"
+     data-invalid="@(Invalid ? "true" : null)"
+     data-fdy-required="@(Required ? "" : null)"></div>

package/adapters/blazor/FdyTimepicker.razor.cs

@@ -0,0 +1,86 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyTimepicker
+{
+    /// <summary>Selected time as <c>HH:MM</c> (24-hour), or "" when unset. Two-way bindable
+    /// via <c>@bind-Value</c>.</summary>
+    [Parameter] public string? Value { get; set; }
+    [Parameter] public EventCallback<string?> ValueChanged { get; set; }
+
+    /// <summary>Accessible label for the trigger.</summary>
+    [Parameter] public string? Label { get; set; }
+
+    /// <summary>Shown when there is no value. The enhancer's own default is <c>--:--</c>.</summary>
+    [Parameter] public string? Placeholder { get; set; }
+
+    /// <summary>Minutes between options. The enhancer's own default is 30.</summary>
+    [Parameter] public int? Step { get; set; }
+
+    /* null, not "30", for the default: an attribute the enhancer does not need is one no reader
+       of the seed has to interpret, and the enhancer already falls back to 30. */
+    private string? StepAttribute => Step is null ? null : Step.Value.ToString();
+
+    /// <summary>Earliest selectable time (<c>HH:MM</c>). Default <c>00:00</c>.</summary>
+    [Parameter] public string? Min { get; set; }
+
+    /// <summary>Latest selectable time (<c>HH:MM</c>). Default <c>23:59</c>.</summary>
+    [Parameter] public string? Max { get; set; }
+
+    /// <summary>Id for the trigger the enhancer builds, so <c>aria-describedby</c> targets and
+    /// other references can point at it. Note the trigger is a <c>&lt;button&gt;</c>, which is not
+    /// a labelable element, so a <c>&lt;label for&gt;</c> will not activate it — use
+    /// <see cref="Label"/>.</summary>
+    [Parameter] public string? Id { get; set; }
+
+    /// <summary>Id of the help or error text the trigger describes itself with.</summary>
+    [Parameter] public string? Describedby { get; set; }
+
+    /// <summary>Greyed and out of the tab order.</summary>
+    [Parameter] public bool Disabled { get; set; }
+
+    /// <summary>Locked/view mode: focusable and showing its time, but the list will not open.
+    /// Unlike <see cref="Disabled"/> it keeps tab order and is not greyed.</summary>
+    [Parameter] public bool Readonly { get; set; }
+
+    /// <summary>Marks the field invalid (<c>aria-invalid</c> + the error styling).</summary>
+    [Parameter] public bool Invalid { get; set; }
+
+    /// <summary>Let a <c>data-fdy-validate</c> form demand this control be filled. Renders
+    /// <c>data-fdy-required</c> on the root, and <c>freeday-form.js</c> refuses the submit, paints
+    /// the message in the field and focuses the trigger. Needed because the trigger is a
+    /// <c>&lt;button&gt;</c>: <c>willValidate</c> is false, so a plain <c>required</c> on it has
+    /// never meant anything. Override the message with <c>data-fdy-msg-required</c> on the root.</summary>
+    [Parameter] public bool Required { get; set; }
+
+    // The enhancer owns this control's DOM; init it directly (initAll would skip Root itself).
+    protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayTimepicker.init", Root);
+
+    protected override async ValueTask OnHydratedAsync()
+        => await SubscribeAsync("fdy-time-select", nameof(OnSelect));
+
+    // The enhancer owns the built trigger + listbox; never let Blazor re-render the seed.
+    protected override bool ShouldRender() => !Hydrated;
+
+    /* Which is exactly why the three states are pushed rather than re-rendered: the seed above is
+       written once, so a page that disables this field later would otherwise be ignored. */
+    protected override async Task OnParametersSetAsync()
+    {
+        if (!Hydrated) return;
+        await JS.InvokeVoidAsync("FreedayTimepicker.setState", Root,
+            new { disabled = Disabled, @readonly = Readonly, invalid = Invalid });
+    }
+
+    /// <summary>Invoked by the bridge when the reader picks a time (enhancer's fdy-time-select).</summary>
+    [JSInvokable]
+    public async Task OnSelect(SelectDetail detail)
+    {
+        Value = detail.Value;
+        await ValueChanged.InvokeAsync(detail.Value);
+    }
+
+    /// <summary>The detail shape of the enhancer's <c>fdy-time-select</c> event.</summary>
+    public sealed record SelectDetail(string Value);
+}

package/adapters/react/components/FdyCascade.tsx

@@ -33,6 +33,14 @@ export interface FdyCascadeProps {
   disabled?: boolean;
   /** Locked/view mode: stays focusable and shows its value, but can't be opened or changed. Unlike `disabled`, it keeps tab order and isn't greyed. */
   readonly?: boolean;
+  /**
+   * Let a `data-fdy-validate` form demand this control be filled. It renders `data-fdy-required`
+   * on the root, and `freeday-form.js` refuses the submit, paints the message in the field and
+   * focuses the trigger. Needed because the trigger is a `<button>`: `willValidate` is false, so
+   * a plain `required` on it has never meant anything (#096). Override the message per control
+   * with `data-fdy-msg-required` on the root.
+   */
+  required?: boolean;
   invalid?: boolean;
   describedby?: string;
 }
@@ -168,7 +176,8 @@ export function FdyCascade(props: FdyCascadeProps): JSX.Element {
   }, [active, open, stack]);
 
   return (
-    <div ref={rootRef} className={isInvalid ? 'fdy-cascade fdy-cascade--error' : 'fdy-cascade'}>
+    <div ref={rootRef} className={isInvalid ? 'fdy-cascade fdy-cascade--error' : 'fdy-cascade'}
+         data-value={props.value} data-fdy-required={props.required === true ? '' : undefined}>
       <button
         ref={triggerRef}
         id={triggerId}

package/adapters/react/components/FdyCombo.tsx

@@ -17,6 +17,14 @@ export interface FdyComboProps<T extends string> {
   disabled?: boolean;
   /** Locked/view mode: stays focusable and shows its value, but can't be opened or changed. Unlike `disabled`, it keeps tab order and isn't greyed. */
   readonly?: boolean;
+  /**
+   * Let a `data-fdy-validate` form demand this control be filled. It renders `data-fdy-required`
+   * on the root, and `freeday-form.js` refuses the submit, paints the message in the field and
+   * focuses the trigger. Needed because the trigger is a `<button>`: `willValidate` is false, so
+   * a plain `required` on it has never meant anything (#096). Override the message per control
+   * with `data-fdy-msg-required` on the root.
+   */
+  required?: boolean;
   invalid?: boolean;
   describedby?: string;
 }
@@ -128,6 +136,7 @@ export function FdyCombo<T extends string>(props: FdyComboProps<T>): JSX.Element
       ref={rootRef}
       className={isInvalid ? 'fdy-combo fdy-combo--error' : 'fdy-combo'}
       data-value={props.value}
+      data-fdy-required={props.required === true ? '' : undefined}
       onKeyDown={onKeyDown}
       onBlur={onFocusout}
     >