@cahyo-dimas/freeday 3.1.0 → 3.3.0

package/CHANGELOG.md

@@ -9,6 +9,157 @@ 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.3.0] - 2026-08-28
+
+**Tiga kemampuan yang sebenarnya sudah ada di kit ini, dan tak satu pun bisa diminta.** `#054` dan
+`#055` datang dari tiga app berbeda dan bermuara pada satu bentuk kegagalan yang sama: kemampuannya
+ada — di jalur mentah, di satu container, di satu varian — tapi **kosakata untuk memintanya tidak**.
+Itu jenis gap yang paling mahal, karena tak terlihat seperti gap: yang membacanya menyimpulkan kit
+tak bisa, lalu membangun ulang. Satu di antaranya membuat dua console menulis 23 override yang sama,
+satu lagi membuat sebuah panel menyimpan dialog 420 baris di sebelah komponen yang melakukan hal itu
+persis, dan yang ketiga bertahan empat bulan hanya karena satu kalimat dokumentasi salah.
+
+### Added
+- **`FdyCfl` bisa dibuka oleh sesuatu yang bukan field-nya sendiri** (`#054`, dari
+  `IDU_AI_DOC_SAPB1_ADDON_DESKTOP_APP`). Enhancer punya `[data-fdy-cfl-open]` — *"opens the dialog
+  with no bound field"* — sejak ia terbit, dan COMPONENTS.md mendaftarnya. Ketiga wrapper typed
+  adalah **field plus dialog** dengan `openDialog` terkunci di dalam: tak ada ref, tak ada prop, tak
+  ada pintu. Jadi jalur mentah bisa melakukan hal yang jalur typed tidak — satu-satunya asimetri yang
+  dilarang klaim paritas kit ini. Panel 420px yang melaporkannya memicu picker dari **chip 12px**,
+  dua per baris dokumen; ia tak bisa membelanjakan satu readonly input 22rem per pemicu, jadi ia
+  menyimpan `CflGridDialog.vue` 420 baris. Sekarang: prop **`dialogOnly`** merender dialog tanpa
+  field, dan **`open()`/`close()`** terjangkau — Vue lewat `defineExpose`, React lewat
+  `FdyCflHandle` di `ref`, Blazor lewat `OpenAsync()`/`CloseAsync()` yang kini `public`. Host-nya
+  `display:contents` (`.fdy-cfl__host`), jadi ia **tak menghasilkan box sama sekali**: div berukuran
+  nol pun tetap jadi flex item atau sel grid di tempat pemicunya diletakkan, dan itu persis yang
+  akan merusak barisan chip. Blazor tak butuh host — ia memang sudah merender field dan dialog
+  sebagai sibling. `disabled`/`readonly` tetap menolak membuka, karena tanpa field tak ada tombol
+  disabled yang menahan klik: penjaganya harus ada di `open()` sendiri, dan itu yang diuji.
+- **`.fdy-field--full` melepas cap 22rem di mana pun field itu berada** (`#055` §1, dari
+  `IDU_AI_DOC_SAPB1_CLIENT` **dan** `IDU_AI_DOC_SAAS` — dua consumer independen yang meraih override
+  yang sama adalah buktinya, jumlahnya adalah argumennya). Kit sudah mengirim idenya:
+  `.fdy-form-grid > .fdy-field { max-width: none }`. Tapi setiap form nyata adalah **flex column**,
+  bukan grid itu — `.fdy-form-grid` adalah `repeat(auto-fit,minmax(14rem,1fr))`, yang memasangkan
+  field berdua begitu ada ruang. Benar untuk header dokumen, salah untuk settings pane, kartu login,
+  atau dialog 420px. Dan di luar grid, modifier-nya bukan sekadar "tak melepas cap": **ia tak
+  melakukan apa-apa**, satu-satunya rule-nya ber-scope grid. Jadi form kolom tunggal tak punya cara
+  mengatakan maksudnya, dan keduanya mengatakannya di container — 23 blok. Kit ini pun menulisnya
+  **empat kali di halaman referensinya sendiri** sebagai `style="max-width:none"`; keempatnya kini
+  `fdy-field--full`. Di dalam grid tak ada yang berubah (rule grid sudah mengatakannya), dan
+  `grid-column` tetap urusan grid.
+- **`--fdy-app-sidebar-w`** (default `15.5rem`) di `.fdy-app__sidebar`. Kedua console meng-override
+  `width`-nya ke `16.5rem` — yaitu meng-override rule yang juga menganimasikan collapse.
+
+### Fixed
+- **Shell bisa memuat anak yang menggulung** (`#055` §2). `.fdy-app__content` punya `min-width:0`
+  dan **tidak** `min-height:0`. Di flex column, sumbu **block**-lah yang menjebak overflow: automatic
+  minimum size sebuah flex item adalah kontennya, jadi consumer yang memaku shell ke viewport lalu
+  menggulung `.fdy-app__main` mendorong shell-nya terbuka, bukan menggulung. Topbar cerita yang sama
+  satu baris di bawah: flex item tanpa `flex`, jadi topbar yang kontennya membungkus melewati
+  `min-height` bisa terperas. Kedua console menulis kedua rule itu sendiri-sendiri, di `app.css`,
+  sebelum layar kelima mereka. Keduanya kini di kit; tak ada layout yang hari ini benar yang berubah.
+- **Kotak pencarian `.fdy-cfl__search` tak lagi ter-cap 22rem.** Empat berkas menulis ini sebagai
+  `style="max-width:none"` — kedua adapter typed dan kedua contoh docs — yaitu kosakata yang hilang
+  dari `#055` §1, satu class di sebelahnya. Sekarang satu rule, nol inline style.
+
+### Docs
+- **`.fdy-nav--flat` akhirnya dijelaskan sebagai dirinya sendiri** (`#055` §3, dan ini temuan yang
+  lebih berharga daripada item aslinya). Catatan itu meminta "bentuk resmi untuk nav grup statis".
+  Bentuk itu **sudah ada sejak 1.1.0** dan melakukan persis tiga hal yang kedua console tulis
+  tangan: caret hilang, `cursor:default`, pemisah antar-grup hilang — plus dukungan markup
+  non-`<details>`, yang persis kasus `<p class="fdy-nav__grouplabel">` mereka. Yang menyembunyikannya
+  adalah satu kalimat di COMPONENTS.md: *"`--flat` drops the surface"*, yang **tidak benar** —
+  `.fdy-nav` tak mengecat surface apa pun untuk dibuang. Deskripsi yang akurat hanya hidup di entri
+  CHANGELOG 1.1.0. Dua consumer membaca satu kalimat yang salah, menyimpulkan varian itu bukan
+  untuk mereka, lalu membangun ulang sesuatu yang sudah mereka punya, selama empat bulan.
+  **Pelajarannya bukan tentang nav:** deskripsi varian yang salah lebih mahal daripada varian yang
+  hilang, karena yang hilang menghasilkan laporan dan yang salah menghasilkan pekerjaan diam-diam.
+- `COMPONENTS.md`: `.fdy-field--full` kini dijelaskan sebagai pelepas cap (bukan hanya span kolom),
+  plus paragraf "single-column form is not a grid"; tabel props `<FdyCfl>` dapat `dialogOnly` dan
+  satu bagian tentang membuka picker lewat ref; `--fdy-app-sidebar-w` didaftar di App shell.
+
+### Guarded
+- **Empat gerbang baru, semuanya diverifikasi dengan mutasi.** `test/css.test.mjs`: `--full` melepas
+  cap **dan** berada setelah `.fdy-field` (spesifisitas sama, jadi urutan sumber adalah seluruh
+  mekanismenya); shell punya kedua `min-*` dan topbar punya `flex:none`. `test/docs.test.mjs`:
+  paritas `#054` di tiga stack **plus** hook `[data-fdy-cfl-open]` di enhancer — kalau hook itu
+  hilang, gerbangnya membandingkan dengan ketiadaan. `browser/cfl-dialog-only.mjs`: 4 test Chrome
+  nyata (Vue + React), dibuka lewat **klik sungguhan** pada chip milik app, bukan dengan memanggil
+  method — plus satu asersi yang mengukur **akibat** dan bukan CSS: fixture-nya flex row bergap 8px
+  dengan komponen di antara dua chip, jadi host yang punya box terbaca sebagai 16px. Asersi itu juga
+  yang menangkap kesalahan pertama penulisnya: hitungan `.fdy-input-group` yang naif menghitung
+  **kotak pencarian di dalam dialog**, bukan field.
+
+## [3.2.0] - 2026-08-28
+
+**Dua cacat yang tak bisa di-screenshot, dan satu komponen yang akhirnya muat di panel 420px.**
+Ketiganya datang dari layar sungguhan. Yang menyatukannya: tak satu pun terlihat di DOM atau di
+stylesheet — yang satu hanya bergerak, yang satu hanya terbaca, yang satu hanya muat atau tidak.
+
+### Fixed
+- **Strip tab tak lagi menggulung vertikal, dan garis aktifnya kini benar-benar 2px** (`#052`, dari
+  `IDU_AI_DOC_SAPB1_CLIENT`). Dilaporkan pengguna yang bisa merasakannya tapi tak bisa memotretnya:
+  *"panel tab ini menggulung vertikal, susah di-screenshot."* Memang begitu — **1px**.
+  `overflow-x:auto` tak bisa meminta satu sumbu saja (CSS Overflow §3: sumbu lain yang `visible`
+  ikut jadi `auto`), jadi 1px yang digantungkan `margin-bottom:-1px` milik tab — yang ada justru
+  untuk mengangkat underline 2px-nya ke atas garis strip — berubah jadi scrollport sungguhan yang
+  memakan gestur trackpad. Yang tak dilaporkan siapa pun, dan hanya piksel yang bisa membedakannya:
+  scroll container **memotong** keturunannya di padding box, jadi separuh bawah underline itu ikut
+  terpotong. Underline aktif terkirim **1px** selama negative margin itu ada — CSS-nya bilang 2px,
+  DOM-nya bilang 2px, layarnya bilang 1. Garis strip kini `box-shadow` inset (dicat di kotaknya,
+  bukan di konten yang menggulung), dan tab tak lagi menggantung. **Bagi konsumen yang menyembunyikan
+  garis itu:** `border-bottom:0` tak lagi menjangkaunya, pakai `box-shadow:none`. Sapuan ke seluruh
+  scroller lain (`.fdy-table-scroll`, `.fdy-nav--horizontal`, `.fdy-carousel__viewport`) bersih —
+  `.fdy-tabs__list` satu-satunya.
+- **`--color-text-subtle` gelap naik ke `slate-450`** (`#053` §2, dari
+  `IDU_AI_DOC_SAPB1_ADDON_DESKTOP_APP`). 4.02:1 di `--color-surface` gelap, di bawah AA, dan yang
+  memakainya bukan cuma app: **placeholder kit sendiri** (`.fdy-datepicker__value--placeholder` dan
+  sebelas `.fdy-cal__day.is-outside` dalam satu kalender). Yang menarik, tokennya tak melanggar
+  kontraknya — gerbang kontras memang menguji tier ini di **3:1 sebagai non-teks**; yang salah
+  adalah kit memakai tier dekoratif untuk teks yang berutang AA. Sekarang **4.88:1** di
+  `--color-surface`, yaitu permukaan yang dicat setiap `.fdy-input`, jadi placeholder lolos di tempat
+  placeholder benar-benar duduk. Light tak disentuh (sudah 4.69). **AA di ketiga permukaan gelap
+  sengaja tidak dikejar**: mencapainya butuh nada sejengkal dari `slate-400`, yang *adalah*
+  `--color-text-muted`, dan subtle yang sama dengan muted bukan tier lagi.
+
+### Added
+- **`FdyCfl` punya layout sempit, tanpa satu pun prop baru** (`#053` §1). Di bawah **30rem**,
+  barisnya menata diri sebagai list item: kolom pertama jadi judul, sisanya satu baris detail di
+  bawahnya, `<thead>` dilepas. **Container query, bukan media query** — dialog bukan viewport, dan
+  komponen yang sama adalah tabel di halaman desktop sekaligus daftar di dalam panel 420px yang
+  ditambatkan di SAP Business One. Kontrak datanya tak berubah: `columns` sudah menyebut kolom mana
+  yang identitas. Keempat stack dapat sekaligus, karena yang bekerja CSS.
+- **`size="cfl"` di `FdyModal`** (`#053` §4), Vue · React · Blazor. `.fdy-modal--cfl` (46rem) sudah
+  ada di CSS sejak lama tapi tak terjangkau dari adapter mana pun; `FdyCfl` memasang kelasnya
+  sendiri, jadi celah ini hanya muncul bagi yang membangun dialog sendiri selebar itu. **Bukan
+  breaking** meski union publiknya melebar: kebijakan 2.1.0 menyasar tipe di posisi *keluaran*
+  (handler yang menerima nilai lebih lebar); ini masukan, dan pemanggil yang mengirim nilai lama
+  tetap valid.
+
+### Added: guards
+- `browser/tabs-strip.mjs` — nol overflow vertikal, underline 2px terbaca dari **piksel** yang
+  benar-benar dicat, dan gulir horizontal yang tetap hidup. Diverifikasi mutasi: dengan aturan 3.1.0
+  dikembalikan, 2 dari 3 merah.
+- `browser/cfl-narrow.mjs` — menjalankan `FdyCfl.vue` sungguhan di viewport **420px**, lebar
+  konsumen yang melaporkannya, karena container query menanyakan lebar *dialog* dan hanya dialog
+  sungguhan yang punya lebar.
+- `test/contrast.test.mjs` dapat pasangan baru khusus placeholder, terpisah dari tier dekoratifnya,
+  jadi kedua paruh keputusan itu dijaga: gagal di 4.02 kalau tokennya dikembalikan, dan tetap 3:1
+  untuk chevron/separator.
+
+### Docs
+- `COMPONENTS.md`: kontrak override garis strip tab, layout sempit `FdyCfl`, dan `size="cfl"`.
+- `USAGE.md`: `.fdy-text-subtle` akhirnya masuk tabel peran teks — tabel itu berhenti di "muted",
+  padahal kelasnya publik — beserta kontrak kontrasnya di kedua tema.
+
+### Tidak diperbaiki, dan alasannya
+- **`--color-text-muted` 3.94:1 di `--color-surface-raised`** (`#053` §3) **tidak reproduksi.** Di
+  `soft`, `--color-surface-raised` *identik* dengan `--color-surface` (7.28:1); di `glass`,
+  komposit terburuknya 6.70:1; dan muted tak pernah turun di bawah **5.46:1** di mana pun dalam ramp
+  gelap. Angka 3.94 itu sendiri nyata: ia persis `slate-400` di atas `slate-700`, yaitu
+  `--color-border-strong` — token border yang tak dipakai komponen mana pun sebagai latar. Item ini
+  dibiarkan **open** dengan pertanyaan balik ke pelapor, bukan ditutup sebagai withdrawn.
+
 ## [3.1.0] - 2026-08-27
 
 **Dua cacat lebar yang dilaporkan dari layar sungguhan, dan keduanya tak kelihatan di DOM.** Markup-nya

package/COMPONENTS.md

@@ -142,6 +142,8 @@ 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`
+- Sidebar width: `--fdy-app-sidebar-w` on `.fdy-app` (default `15.5rem`). Set it rather than
+  overriding `width` on `.fdy-app__sidebar`, whose value also feeds the collapse transition.
 - 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)
@@ -422,15 +424,22 @@ WAI-ARIA APG menu-button. Keyboard ↑/↓/Home/End/Esc handled by the enhancer.
 The field wrapper owns the vertical rhythm; `<label class="fdy-field">` when it wraps a single
 native control, otherwise a `<div>` + explicitly associated label.
 
-- `.fdy-field` (+ `--full` inside `.fdy-form-grid`; widths `--w-sm` `--w-lg` `--w-xl` `--w-2xl`
-  `--w-grow` inside `.fdy-filterbar`)
+- `.fdy-field` (+ `--full`, which releases the width cap **wherever the field is**, and inside
+  `.fdy-form-grid` also spans the row; widths `--w-sm` `--w-lg` `--w-xl` `--w-2xl` `--w-grow`
+  inside `.fdy-filterbar`)
 - **The field owns the width; the control in it follows.** `.fdy-field` caps at `22rem` so a lone
-  field does not run the width of the page. `.fdy-form-grid` and `.fdy-filterbar` lift that cap, and
-  so does any width you state yourself — and in every one of those cases the control (`.fdy-input`,
+  field does not run the width of the page. `.fdy-form-grid` and `.fdy-filterbar` lift that cap,
+  `.fdy-field--full` lifts it on one field anywhere, and so does any width you state yourself — and in every one of those cases the control (`.fdy-input`,
   `.fdy-input-group`, `.fdy-combo`, `.fdy-autocomplete`, `.fdy-cascade`, and the pickers) spans the
   field. So **size the field, never the control**: styling the control instead leaves the field
   wider than what is in it, and that dead space is invisible in the DOM — it reads on screen as a
   gap you did not write.
+- **A single-column form is not a grid.** `.fdy-form-grid` pairs fields up the moment there is room,
+  which is right for a document header and wrong for a settings pane, a login card, or a dialog at
+  420px. Those are a plain flex column, and the way one says *"these fields fill me"* is
+  `.fdy-field--full` on the fields — **not** a `max-width` override on the container. Both of this
+  kit's own consoles wrote that override, once per form, before this modifier reached outside the
+  grid.
 - `.fdy-label` (+`--required`) · `.fdy-input` (+`--error`) · `.fdy-textarea` · `.fdy-help` (+`--error`)
 
 **Grouped controls are a `<fieldset>`, not a new block.** Put `.fdy-field` on the fieldset and
@@ -640,6 +649,15 @@ child `<ul>` is a branch, one without is a leaf. Needs `freeday-cascade.js`.
 ## Choose-from-list (CFL) — `data-fdy-cfl`
 > **Typed wrapper: `<FdyCfl>`**. 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).
 
+> **Narrow: the results stack, and there is no prop for it** (`#053`). Under a `.fdy-cfl__results`
+> narrower than **30rem** — a docked add-on panel, a phone — the rows lay out as list items instead
+> of table cells: the first column becomes the title, the remaining columns become one detail line
+> under it, and `<thead>` is dropped. It is a **container** query, so what decides is the dialog's
+> width and not the viewport's; the same component is a table on a desktop page and a list inside a
+> 420px panel, with no flag to pass and nothing to keep in sync. Your data contract does not change:
+> `columns`, `display` and `rowKey` already say which column is the identity. If a screen genuinely
+> needs columns at that width, override the `@container` block — do not widen the dialog.
+
 ### Props — `<FdyCfl>`
 
 Four of these are required and carry the whole component: `fetchPage`, `columns`, `display`,
@@ -665,6 +683,31 @@ Four of these are required and carry the whole component: `fetchPage`, `columns`
 | `clearLabel?` | `string` | Accessible name for that button. Default `Clear selection`. |
 | `disabled?` · `readonly?` · `invalid?` | `boolean` | `readonly` keeps the picked value visible, focusable and copyable, but the dialog cannot be opened. |
 | `id?` · `ariaLabelledby?` · `describedby?` | `string` | Field id; the element that labels it; the help/error text it points at. |
+| `dialogOnly?` | `boolean` | Render the **dialog and no field**, for a caller whose trigger is already its own. See below. |
+
+**Opening it yourself.** The field is one way in, not the only one. A ref gives you `open()` and
+`close()` — Vue `defineExpose`, React a `FdyCflHandle` through `ref`, Blazor `OpenAsync()` /
+`CloseAsync()` on the `@ref` — and `dialogOnly` drops the field entirely so the picker can be
+triggered by a chip, a table cell, a menu item, or anything else that is not a 22rem readonly input.
+This is what the raw path has always had in `[data-fdy-cfl-open]`; before 3.3.0 the typed wrappers
+were a field *plus* a dialog with no door, and a screen that could not spend a field per trigger had
+to hand-roll the whole picker. With `dialogOnly` the component's host generates no box
+(`.fdy-cfl__host` is `display:contents`), so it can be rendered anywhere — Blazor renders only the
+`<dialog>` and needs no host. `placeholder`, `clearable`, `id` and the field's aria props have
+nothing to name in that mode and are ignored; `disabled` and `readonly` still refuse to open, so a
+programmatic `open()` cannot bypass them.
+
+```vue
+<script setup lang="ts">
+const picker = ref<InstanceType<typeof FdyCfl> | null>(null);
+</script>
+
+<template>
+  <button class="fdy-chip" type="button" @click="picker?.open()">Cost centre</button>
+  <FdyCfl ref="picker" dialog-only v-model="costCentre" :fetch-page="fetchPage"
+          :columns="columns" :display="d" :row-key="k" />
+</template>
+```
 
 Blazor carries the same surface in `PascalCase` with three differences: multi-select is a second
 pair (`Values` / `ValuesChanged`) rather than a widened single binding, the fetch delegate is
@@ -911,7 +954,9 @@ button chrome). `data-fdy-mask="####-####"` formats while typing: `#` digit, `A`
 alphanumeric, anything else is a literal. Needs `freeday-mask.js`.
 
 ## Form grid — `.fdy-form-grid`
-Responsive two-column document header. Children are `.fdy-field`; `.fdy-field--full` spans both.
+Responsive two-column document header. Children are `.fdy-field`; `.fdy-field--full` spans both
+columns. For a form that must stay **one** column, do not reach for this grid — it pairs fields up
+as soon as the container is wide enough. Use a flex column and mark the fields `--full`.
 
 ## Filter bar — `.fdy-filterbar`
 A consistent filter row of `.fdy-field`s with a width rhythm (`--w-sm` · default · `--w-lg` ·
@@ -1451,11 +1496,17 @@ Size-matched placeholders so nothing shifts when data lands: `--title` `--text`
 ## Nav (menu) — `.fdy-nav`
 Navigation links, **vertical by default** (the app shell sidebar), horizontal with `--horizontal`. Items are `<a class="fdy-nav__item">` with
 `__icon` / `__label` / `__badge`; the current one gets `aria-current="page"`.
-`--flat` drops the surface. Nested groups are native `<details>`:
+Nested groups are native `<details>`:
 
 - `.fdy-nav__tree` + `<summary class="fdy-nav__item">` + `.fdy-nav__caret` → children in
   `.fdy-nav__sub`
 - `.fdy-nav__group` + `<summary class="fdy-nav__grouplabel">` → a collapsible section
+- **`--flat` on the `<nav>` is the static variant**: group labels that never collapse. It drops the
+  disclosure caret, returns the label to `cursor: default`, and removes the divider between groups,
+  so `.fdy-nav__grouplabel` can be a plain `<p>`/`<div>` heading ("OVERVIEW", "ADMINISTRATION")
+  outside any `<details>`. Reach for it instead of undoing those three rules per app — which is what
+  two consoles did for four months, because this line used to claim `--flat` "drops the surface",
+  and it never did: `.fdy-nav` paints no surface to drop.
 - **`--horizontal`** lays the same links out as a row, for a **top-nav application** (primary
   navigation in `.fdy-appbar` or `.fdy-app__topbar`, no sidebar). Same item, same states, same
   `aria-current="page"`; the row scrolls if it runs out of width. On `.fdy-appbar--primary` the
@@ -1496,6 +1547,16 @@ 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"`**,
 so the same look serves routed sub-navigation built from plain links. See the note under Nav.
 
+> **The strip's line is an inset `box-shadow`, not a `border-bottom`** (`#052`; through 3.1.0 it
+> was a border, so an app upgrading past that release changes the override with it). To
+> remove it — a strip inside a header that draws its own rule — override `box-shadow:none`;
+> `border-bottom:0` no longer reaches it. The swap is not cosmetic: `.fdy-tabs__list` scrolls
+> horizontally, a scroll container clips its descendants to the padding box, and the tab's
+> `margin-bottom:-1px` (which lifted its 2px underline onto that border) therefore pushed the
+> underline's lower half into the clip — the underline painted 1px, and the strip carried 1px of
+> vertical scroll that ate trackpad gestures. A shadow paints on the box, not on the scrolled
+> content, so the line needs no overhang to sit under. Guarded in `browser/tabs-strip.mjs`.
+
 ```html
 <div class="fdy-tabs" data-fdy-tabs>
   <div class="fdy-tabs__list" role="tablist" aria-label="Invoice detail">
@@ -1521,7 +1582,7 @@ so the same look serves routed sub-navigation built from plain links. See the no
 | `open` | `boolean` | Controlled: your state decides. The wrapper cancels the native `cancel` event so the DOM can never disagree with it. |
 | `title` | `string` (Vue) · `ReactNode` | Names the dialog through `aria-labelledby`. Vue also offers a `title` slot when the heading needs markup. |
 | `onClose` | `() => void` | React. Vue emits `close`. Fires from Escape, a backdrop click and the ×, all three of which exist only under `dismissible`. |
-| `size?` | `'sm' \| 'md' \| 'lg' \| 'wide'` | Dialog width. |
+| `size?` | `'sm' \| 'md' \| 'lg' \| 'wide' \| 'cfl'` | Dialog width. `cfl` is the 46rem choose-from-list width; `FdyCfl` applies it itself, so pass it only for a dialog you build at that width. |
 | `dismissible?` | `boolean` | Whether Escape, the backdrop and the × can close it. Off means the reader has to take a footer action, which is the point of a blocking confirm. |
 | `closeLabel?` | `string` | Accessible name for the × button. Default `Close`. |
 | `footer?` | `ReactNode` | React. Vue: the `footer` slot. |

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.1.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.1.0)
+[![Release](https://img.shields.io/badge/release-v3.3.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.3.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-v3.1.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.1.0)
+[![Release](https://img.shields.io/badge/release-v3.3.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v3.3.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

@@ -23,10 +23,20 @@ the single biggest cause of "flat grey mush". Pick the role, not the size:
 | Card / row title | `.fdy-title-card` (or `.fdy-card__title`) | A title inside a card or list row (`<h3>`). |
 | Body | *(default)* | Running text. |
 | Muted / caption | `.fdy-text-muted`, `.fdy-text-caption` | Secondary text, timestamps, help. |
+| Subtle | `.fdy-text-subtle` | The faintest ink. Placeholders and decoration — chevrons, separators, out-of-month days. **Read the contract below before using it for a sentence.** |
 
 Everything else is body. If you reach for a fourth title size, you probably need a section, not a
 font size.
 
+**`--color-text-subtle` is not a third body-text tier, and dark is where that bites.** It clears AA
+on `--color-surface` in both themes (light 4.69:1, dark 4.88:1) — which is what `.fdy-input` and
+`.fdy-textarea` paint, so a placeholder is safe. It clears AA on **nothing else**, in either theme:
+`--color-surface-3` reads 4.11:1 in light and 3.66:1 in dark. Nor will it ever: reaching 4.5 there
+needs a tone within a hair of `--color-text-muted`, and a subtle that equals muted is not a tier. So a small uppercase
+label, a card's second line, or anything a reader must actually read on a raised or tinted surface
+takes `--color-text-muted`. `test/contrast.test.mjs` holds both halves of that split, which is why
+the ramp cannot quietly drift into either mistake.
+
 
 ## Borders: two roles, two contrast contracts
 

package/adapters/blazor/FdyCfl.razor

@@ -7,27 +7,33 @@
    dialog are rendered and re-rendered by Blazor, rows come from an async LoadPage callback, and
    the <dialog> is opened/closed through the same freeday-blazor.js interop FdyModal uses. *@
 
-<div class="@FieldGroupClass">
-    <input class="fdy-input" type="text" readonly value="@DisplayValue"
-           placeholder="@Placeholder" aria-labelledby="@AriaLabelledby"
-           aria-invalid="@(Invalid ? "true" : null)" aria-readonly="@(Readonly ? "true" : null)" />
-    @if (Clearable && Value is not null && !Disabled && !Readonly)
-    {
-        <button class="fdy-input-group__btn" type="button" @onclick="ClearAsync" aria-label="@ClearLabel">
+@* The field is optional (#054): with DialogOnly the component renders the dialog alone, for a
+   caller whose trigger is already its own — a chip, a table cell, a menu item — and opens it
+   through @ref: `await picker.OpenAsync()`. The host generates no box. *@
+@if (!DialogOnly)
+{
+    <div class="@FieldGroupClass">
+        <input class="fdy-input" type="text" readonly value="@DisplayValue"
+               placeholder="@Placeholder" aria-labelledby="@AriaLabelledby"
+               aria-invalid="@(Invalid ? "true" : null)" aria-readonly="@(Readonly ? "true" : null)" />
+        @if (Clearable && Value is not null && !Disabled && !Readonly)
+        {
+            <button class="fdy-input-group__btn" type="button" @onclick="ClearAsync" aria-label="@ClearLabel">
+                <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+                     stroke-width="2" stroke-linecap="round" aria-hidden="true">
+                    <path d="M6 6l12 12M18 6L6 18"></path>
+                </svg>
+            </button>
+        }
+        <button class="fdy-input-group__btn" type="button" @onclick="OpenAsync"
+                disabled="@(Disabled || Readonly)" aria-label="@OpenLabel">
             <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
-                 stroke-width="2" stroke-linecap="round" aria-hidden="true">
-                <path d="M6 6l12 12M18 6L6 18"></path>
+                 stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+                <circle cx="11" cy="11" r="7"></circle><path d="m21 21-4.3-4.3"></path>
             </svg>
         </button>
-    }
-    <button class="fdy-input-group__btn" type="button" @onclick="OpenAsync"
-            disabled="@(Disabled || Readonly)" aria-label="@OpenLabel">
-        <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
-             stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
-            <circle cx="11" cy="11" r="7"></circle><path d="m21 21-4.3-4.3"></path>
-        </svg>
-    </button>
-</div>
+    </div>
+}
 
 <dialog @ref="Root" class="fdy-modal fdy-modal--cfl" aria-labelledby="@_titleId">
     <div class="fdy-modal__header">

package/adapters/blazor/FdyCfl.razor.cs

@@ -70,6 +70,13 @@ public partial class FdyCfl<TRow>
     /// <summary>Debounce (ms) between a keystroke and the search request.</summary>
     [Parameter] public int SearchDebounceMs { get; set; } = 250;
 
+    /// <summary>Render the dialog and NO field, for a caller whose trigger is already its own — a chip,
+    /// a table cell, a menu item — opened through <c>@ref</c>: <c>await picker.OpenAsync()</c>. The raw
+    /// path has had exactly this since the enhancer's <c>[data-fdy-cfl-open]</c>. <c>Placeholder</c>,
+    /// <c>Clearable</c> and the field's aria parameters have nothing to name here and are ignored;
+    /// <c>Disabled</c> and <c>Readonly</c> still refuse to open.</summary>
+    [Parameter] public bool DialogOnly { get; set; }
+
     private readonly string _titleId = $"fdy-cfl-{Guid.NewGuid():N}-title";
     private int _dialogToken;
     private bool _open;
@@ -93,7 +100,10 @@ public partial class FdyCfl<TRow>
     protected override async ValueTask HydrateAsync()
         => _dialogToken = await JS.InvokeAsync<int>("FreedayBlazor.dialogInit", Root, Self, nameof(OnDismiss), true);
 
-    private async Task OpenAsync()
+    /// <summary>Open the picker. Public because with <see cref="DialogOnly"/> there is no field to
+    /// open it, and because a caller with its own trigger is the case that made #054: it guards
+    /// exactly as the built trigger does, so this cannot bypass Disabled/Readonly.</summary>
+    public async Task OpenAsync()
     {
         if (Disabled || Readonly || _open) return;
         _open = true;
@@ -105,7 +115,8 @@ public partial class FdyCfl<TRow>
         await LoadAsync(reset: true);
     }
 
-    private async Task CloseAsync()
+    /// <summary>Close the picker without committing, the same path Esc and the footer button take.</summary>
+    public async Task CloseAsync()
     {
         if (!_open) return;
         _open = false;

package/adapters/blazor/FdyModal.razor.cs

@@ -19,7 +19,7 @@ public partial class FdyModal
     /// <summary>Optional footer (action buttons). Omitted entirely when null.</summary>
     [Parameter] public RenderFragment? FooterContent { get; set; }
 
-    /// <summary>Size modifier: <c>sm</c> | <c>md</c> | <c>lg</c> | <c>wide</c>.</summary>
+    /// <summary>Size modifier: <c>sm</c> | <c>md</c> | <c>lg</c> | <c>wide</c> | <c>cfl</c> (the 46rem choose-from-list width).</summary>
     [Parameter] public string? Size { get; set; }
 
     /// <summary>When true (default), Esc and a backdrop click dismiss the dialog and a close

package/adapters/react/components/FdyCfl.tsx

@@ -1,5 +1,5 @@
-import type { JSX } from 'react';
-import { useEffect, useId, useRef, useState } from 'react';
+import type { JSX, Ref } from 'react';
+import { forwardRef, useEffect, useId, useImperativeHandle, useRef, useState } from 'react';
 
 // React port of adapters/vue/components/FdyCfl.vue over freeday's `.fdy-cfl*` +
 // `.fdy-input-group` classes (see src/components/cfl.css, input-group.css). A controlled
@@ -71,9 +71,27 @@ export interface FdyCflProps<Row extends Record<string, unknown>> {
   describedby?: string;
   id?: string;
   ariaLabelledby?: string;
+  /** Render the dialog and NO field, for a caller whose trigger is already its own — a chip, a table
+   *  cell, a menu item — opened through the ref: `picker.current?.open()`. The raw path has had
+   *  exactly this since the enhancer's `[data-fdy-cfl-open]`; the typed wrappers were a field *plus*
+   *  a dialog with no way in, so a screen that could not spend a 22rem readonly input per trigger had
+   *  to hand-roll the picker (#054). The host generates no box, so it can sit anywhere.
+   *  `placeholder`, `clearable`, `id` and the field's aria props have nothing to name here and are
+   *  ignored; `disabled` and `readonly` still refuse to open. */
+  dialogOnly?: boolean;
 }
 
-export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<Row>): JSX.Element {
+/** What a `ref` on `<FdyCfl>` gives you. Both guard exactly as the trigger does, so a programmatic
+ *  open cannot bypass `disabled`/`readonly`. */
+export interface FdyCflHandle {
+  open: () => void;
+  close: () => void;
+}
+
+function FdyCflInner<Row extends Record<string, unknown>>(
+  props: FdyCflProps<Row>,
+  ref: Ref<FdyCflHandle>,
+): JSX.Element {
   const baseId: string = useId();
   const fieldId: string = props.id ?? `${baseId}-field`;
   const titleId: string = `${baseId}-title`;
@@ -301,6 +319,10 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
     dialogRef.current?.close();
   }
 
+  /* No dependency array on purpose: both close over state (the ticks to seed, whether the field is
+     disabled), so a handle frozen at first render would open a picker with last week's props. */
+  useImperativeHandle(ref, (): FdyCflHandle => ({ open: openDialog, close: closeDialog }));
+
   // Fires for every close path (button, Esc, commit); centralise cleanup here.
   function onClose(): void {
     reqIdRef.current++; // invalidate any in-flight fetch so it can't apply after close
@@ -330,46 +352,50 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
   }, []);
 
   return (
-    <div className="fdy-input-group">
-      <input
-        id={fieldId}
-        className="fdy-input"
-        type="text"
-        readOnly
-        value={displayValue}
-        placeholder={props.placeholder}
-        aria-labelledby={props.ariaLabelledby}
-        aria-invalid={isInvalid ? 'true' : undefined}
-        aria-describedby={props.describedby}
-        disabled={isDisabled}
-      />
-      {showClear ? (
-        <button
-          type="button"
-          className="fdy-input-group__btn"
-          aria-label={clearLabelText}
-          onClick={clearValue}
-        >
-          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true">
-            <path d="M6 6l12 12M18 6L6 18" />
-          </svg>
-        </button>
-      ) : null}
-      <button
-        ref={triggerRef}
-        type="button"
-        className="fdy-input-group__btn"
-        aria-haspopup="dialog"
-        aria-labelledby={props.ariaLabelledby}
-        aria-label={props.ariaLabelledby ? undefined : (props.openLabel ?? 'Open search')}
-        disabled={isDisabled || isReadonly}
-        onClick={openDialog}
-      >
-        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
-          <circle cx={11} cy={11} r={7}></circle>
-          <path d="m21 21-4.35-4.35"></path>
-        </svg>
-      </button>
+    <div className={props.dialogOnly === true ? 'fdy-cfl__host' : 'fdy-input-group'}>
+      {props.dialogOnly === true ? null : (
+        <>
+          <input
+            id={fieldId}
+            className="fdy-input"
+            type="text"
+            readOnly
+            value={displayValue}
+            placeholder={props.placeholder}
+            aria-labelledby={props.ariaLabelledby}
+            aria-invalid={isInvalid ? 'true' : undefined}
+            aria-describedby={props.describedby}
+            disabled={isDisabled}
+          />
+          {showClear ? (
+            <button
+              type="button"
+              className="fdy-input-group__btn"
+              aria-label={clearLabelText}
+              onClick={clearValue}
+            >
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden="true">
+                <path d="M6 6l12 12M18 6L6 18" />
+              </svg>
+            </button>
+          ) : null}
+          <button
+            ref={triggerRef}
+            type="button"
+            className="fdy-input-group__btn"
+            aria-haspopup="dialog"
+            aria-labelledby={props.ariaLabelledby}
+            aria-label={props.ariaLabelledby ? undefined : (props.openLabel ?? 'Open search')}
+            disabled={isDisabled || isReadonly}
+            onClick={openDialog}
+          >
+            <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
+              <circle cx={11} cy={11} r={7}></circle>
+              <path d="m21 21-4.35-4.35"></path>
+            </svg>
+          </button>
+        </>
+      )}
 
       <dialog ref={dialogRef} className="fdy-modal fdy-modal--cfl" aria-labelledby={titleId} onClose={onClose} onKeyDown={onKeydown}>
         <div className="fdy-modal__header">
@@ -379,7 +405,7 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
 
         <div className="fdy-modal__body">
           <div className="fdy-cfl__search">
-            <div className="fdy-input-group" style={{ maxWidth: 'none' }}>
+            <div className="fdy-input-group">
               <span className="fdy-input-group__addon fdy-input-group__addon--icon">
                 <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2} strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
                   <circle cx={11} cy={11} r={7}></circle>
@@ -478,3 +504,12 @@ export function FdyCfl<Row extends Record<string, unknown>>(props: FdyCflProps<R
     </div>
   );
 }
+
+/* `forwardRef` types its argument as a plain function, which erases `Row`: every consumer would get
+   `FdyCflProps<Record<string, unknown>>` and lose the row type the whole component exists to carry.
+   The cast restores the generic call signature, and it is the standard shape for a generic component
+   with a ref while `react` is `>=18` (React 19's ref-as-prop would not need it, and the peer range
+   still admits 18). */
+export const FdyCfl = forwardRef(FdyCflInner) as <Row extends Record<string, unknown>>(
+  props: FdyCflProps<Row> & { ref?: Ref<FdyCflHandle> },
+) => JSX.Element;

package/adapters/react/components/FdyModal.tsx

@@ -13,7 +13,8 @@ export interface FdyModalProps {
   open: boolean;
   title: ReactNode;
   onClose: () => void;
-  size?: 'sm' | 'md' | 'lg' | 'wide';
+  /* 'cfl' is the choose-from-list width (46rem); see the Vue wrapper for why it was missing. */
+  size?: 'sm' | 'md' | 'lg' | 'wide' | 'cfl';
   dismissible?: boolean;
   /** aria-label for the × button. Default 'Close'. */
   closeLabel?: string;

package/adapters/react/index.d.ts

@@ -33,7 +33,7 @@ export { FdyDatepicker, type FdyDatepickerProps } from './components/FdyDatepick
 export { FdyDateRange, type FdyDateRangeProps, type DateRangeValue } from './components/FdyDateRange';
 export { FdyAutocomplete, type FdyAutocompleteProps } from './components/FdyAutocomplete';
 export { FdyCascade, type FdyCascadeProps, type CascadeNode } from './components/FdyCascade';
-export { FdyCfl, type FdyCflProps, type CflColumn, type CflPage } from './components/FdyCfl';
+export { FdyCfl, type FdyCflProps, type FdyCflHandle, type CflColumn, type CflPage } from './components/FdyCfl';
 /** Narrow `FdyCfl`'s `Row | Row[] | null` to the `Row | null` a single-select can produce; throws
  *  on the array only a `multiple` field emits. */
 export { singleRow } from '../core/cfl-value';