@cahyo-dimas/freeday 1.21.0 → 1.23.0

package/CHANGELOG.md

@@ -3,6 +3,112 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.23.0] — 2026-08-13
+Consumption round 6 (`improvement-notes/006`). The reporter filed two of the three as **their own**
+bugs rather than the kit's — and they were right about the code, but in both cases the kit had a way
+to make the mistake impossible and had not taken it. Those are the two most valuable findings here.
+### Fixed
+- **`initAll(ctx)` now enhances `ctx` itself, not just its descendants.** `querySelectorAll` never
+  matches its own root, so a framework ref placed **on** the widget — `<div ref="menu" data-fdy-menu>`,
+  which is the ordinary shape when a component's root element *is* the widget — meant the one element
+  that needed enhancing was the only one that could not be found. It failed with **no error, no
+  warning, and a UI that looked finished**: the markup rendered and simply never opened. Measured
+  before the fix: `data-fdy-menu-ready` stayed `null` and `aria-expanded` stayed `"false"` while
+  `initAll` was present and callable the whole time; `initAll(parent)` worked. One `matches()` line
+  per selector, in **all 21 enhancers** (`drawer` and `cfl` needed their inline trigger callbacks
+  hoisted first). Init was already idempotent via each widget's `-ready` flag, so a root that is also
+  matched by the descendant query costs nothing. `useFreeday` (Vue/React) and `FreedayBlazor.initAll`
+  delegate to these, so they inherit the fix with no change of their own.
+- **The stepper connector no longer draws through the markers when `__btn` is omitted.** The lift now
+  lives on `.fdy-step__marker` — the part that must always exist — instead of only on
+  `.fdy-step__btn`. The connector is `position:absolute; z-index:0`, and a positioned box paints
+  *after* in-flow inline content in the same stacking context, so a marker that was merely inline got
+  painted over: not for lack of a z-index, but for lack of being positioned at all. An
+  indicator-only stepper (no navigation, so no button) is a reasonable thing to write and it produced
+  a visible defect in shipped UI. Measured: hit-testing the marker's centre returned the connector's
+  own `.fdy-step` before, the marker after. `__btn` keeps its z-index for the navigable case.
+### Added
+- **`.fdy-avatar--xs`** (1.5rem, `--text-xs`) — an avatar inside a control had nothing to reach for:
+  `.fdy-btn--sm` is `calc(var(--control-h) - var(--space-2))` = **2rem**, exactly `--avatar--sm`'s
+  size, so the monogram filled a small button edge to edge and the ghost border crossed the circle
+  (measured: trigger 32px tall, avatar 32×32). 1.5rem inside 2rem leaves the ~4px the kit's other
+  controls give their icons. The report suggested `--text-2xs`; that token does not exist — `--text-xs`
+  is the smallest the kit has, and inventing a type step for one avatar size is not worth it.
+### Added — guards
+- **`browser/root-init.mjs`** — mounts a widget *after* load, initialises it through its own root, and
+  drives a **real click** to prove it opens; repeated for a second enhancer so the fix reads as the
+  shared pattern rather than a one-off. Mutation-checked on both. Being marked `-ready` is explicitly
+  not accepted as passing: an early version of this check reported success against markup the enhancer
+  had actually bailed on.
+### Docs
+- `COMPONENTS.md`: `initAll(root)` documents that the root may be the widget itself; the stepper
+  section states that `__btn` is **optional** and shows the read-only indicator markup (the parts list
+  never said which parts were optional); avatar gains its size table with the in-control guidance.
+- Both `useFreeday` docstrings now show the ref-on-the-widget shape alongside the wrapping one.
+
+## [1.22.0] — 2026-08-12
+Two bodies of work. **(a)** three more findings from consumption round 5 — the report grew §5-§7
+after 1.21.0 was cut; **(b)** a **routing** failure found in the same adopted project, which had been
+built on raw markup + enhancers inside a framework that has typed wrappers because nothing in the
+package ever told it otherwise. (b) was prepared as 1.21.1 and folded in here rather than shipped as
+a separate patch minutes earlier.
+### Added — from consumption round 5 (§5, §6)
+- **`.fdy-nav--horizontal`** — the same navigation links laid out as a **row**, for a top-nav
+  application that puts its primary nav in `.fdy-appbar` / `.fdy-app__topbar` and has no sidebar.
+  Deliberately a modifier, not a new block: the item, its states and `aria-current="page"` are
+  unchanged. On `.fdy-appbar--primary` the links go on-colour automatically (full on-colour ink in
+  every state; the current page is carried by the background wash plus the semibold weight the base
+  rule already applies, so no dimmed variant trades away the bar's guaranteed contrast).
+  Reported as "there is no horizontal navigation component": `.fdy-nav` was the sidebar's vertical
+  menu and `.fdy-appbar` had `__brand`/`__spacer`/`__actions` but nothing to put *links* in — so a
+  top-nav app had a component for the bar and none for what the bar is mostly made of.
+- **`.fdy-tabs__tab` also honours `aria-current="page"`**, so the tab *look* legitimately serves
+  **routed** sub-navigation (`/settings/profile` · `/settings/billing`) built from real links. A link
+  cannot be `aria-selected` — that is invalid ARIA on an anchor — so the app that borrowed the class
+  had to restate the active style for a second attribute. Keep `role="tab"` + `freeday-tabs.js` for
+  **in-page** tabs, where the roving-tabindex / one-panel-per-tab contract is real.
+- **Pressed state for toggle buttons** — `aria-pressed="true"` now styles: soft primary fill + strong
+  ink on `--ghost`/`--text`, an inverted-gradient sunken look on the solid button, and the same
+  treatment in the danger hue. No new class or markup contract, since `aria-pressed` is already the
+  correct attribute — and it is what turns `.fdy-btn-group` from a joined row into a **complete**
+  segmented control. Previously "which one am I on" was left to each app to hand-tint, which is a
+  colour decision the kit should own.
+  *Found while building it:* one shared `.fdy-btn[aria-pressed="true"]` rule **cannot** work. A
+  gradient is a background-**image**, so the `background` shorthand resets `background-color` to
+  transparent — at equal specificity the later rule won and the ghost segment lost its fill entirely.
+  Each fill variant now defines its own pressed look. The CSS read correctly in the file; only a real
+  engine showed it, which is why the new guard lives in `browser/`.
+### Fixed — from consumption round 5 (§7)
+- **Hard rule 1 in `COMPONENTS.md` now records its one exception.** The rule says a modifier is
+  always written beside its block class, but `.fdy-input-group__addon--icon` is standalone by design
+  — adding the base `__addon` gives a search glyph the grey fill and divider of a `Rp` / `%` prefix.
+  An agent following the rule literally produced the wrong control; one following the CSS comment
+  broke the stated rule. The exception is now written down, and it is the only one.
+### Fixed — the package now routes by stack
+- **The paste-block in `docs/agent-onboarding.md` never mentioned the adapters.** That block is the
+  only text that lands in a consuming project's agent instructions, so it is the only text an agent
+  re-reads on every task — and it opened with "a CSS kit + enhancers, **not a component framework**",
+  which actively steers a Vue/React project away from the typed components. It now opens with a
+  **step 0 routing table** (Vue → `/vue` · React → `/react` · Blazor → RCL · everything else → raw
+  markup), names the ten wrapped components, and states the failure mode: the raw path renders
+  correctly the first time and then silently stops hydrating.
+- **`COMPONENTS.md` flags the wrapper at each of the ten sections**, so the choice is visible at the
+  point of use rather than only on an onboarding page read once — with each component's *real*
+  binding (`v-model` / `value`+`onChange` / `@bind-Value` for the six value-bound ones; `open`+`close`
+  for modal and drawer; data props for chart; `columns`+`rows`+events for table). Hard rule 7 states
+  it up front.
+- **Both READMEs lead with the routing table**, above the first import block. Previously the first
+  runnable snippet was the vanilla one and the adapter table sat ~130 lines below it.
+- **`docs/getting-started.md`** core concept 2 ("the enhancer is the source of truth") is now scoped
+  to the raw path, and notes that Vue/React re-implement the ten natively while Blazor wraps the
+  enhancer over interop.
+### Notes
+- Root cause was structural, not editorial: at **v1.18.0** `docs/getting-started.md` — the only
+  per-stack router the kit had — was **not in `files`**, so `npm i` delivered a README whose
+  "Starting a project? per stack" link pointed at a path that does not exist inside `node_modules`.
+  `adapters/` *was* shipped, so the wrappers sat in the install, unused, with nothing pointing at
+  them. v1.20.0 started shipping the docs; this release makes them route.
+
 ## [1.21.0] — 2026-08-12
 Fifth round of real-app consumption feedback, written while that app adopted 1.20.0. Two findings —
 and a **withdrawal**: the reporter retracted 1.20's rejected §A themselves after isolating the real
@@ -57,6 +163,11 @@ reproduce here, so the rejection stands and the withdrawal is recorded rather th
   hidden labels in a wide table, asserting the page cannot scroll horizontally *and* that the scroller
   still scrolls. A static test cannot see this failure; only a layout engine can. Both guards
   mutation-checked — reverting any single `position:relative` fails them.
+- **`browser/state.mjs`** — pressed toggles and nav orientation in a real engine: the pressed ghost
+  segment must keep a flat background-colour (the mutation that reproduces the shorthand bug fails
+  it), the solid toggle must read as inset, `--horizontal` must actually be a row with the current
+  link marked, on-colour nav ink must stay on-colour in both states, and a routed tab must take its
+  underline from `aria-current`. Mutation-checked against all three fixes.
 - **`browser/theme.mjs`** — subtree theming end-to-end: a `.fdy-title-page` and a `.fdy-card` inside
   `<section data-theme="dark">` take the dark tokens, a nested light island goes back, and
   `data-theme` on `<html>` still themes everything. `test/build.test.mjs` guards the selector shape

package/COMPONENTS.md

@@ -15,6 +15,10 @@ live docs.
 1. **Prefix is `fdy-`, pattern is compact BEM**: block `fdy-card`, element `fdy-card__title`,
    modifier `fdy-card--elevated`. A modifier is **always** written alongside its block class:
    `class="fdy-btn fdy-btn--ghost"`, never `fdy-btn--ghost` alone.
+   **One documented exception:** `.fdy-input-group__addon--icon` is **standalone** — it is a
+   borderless leading glyph, and adding the base `.fdy-input-group__addon` would give it the grey
+   fill and divider of a `Rp` / `%` prefix, which is not what a search icon is. Written
+   `class="fdy-input-group__addon--icon"`, alone. It is the only one; everywhere else the rule holds.
 2. **Never invent a class.** If it is not in this file, it does not exist. Freeday has no
    `fdy-grid`, no `fdy-flex`, no `fdy-mt-4`, no `fdy-primary`.
 3. **Never write a raw hex or px value** in app CSS. Use the tokens — `var(--color-primary)`,
@@ -30,6 +34,14 @@ 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, ten components have a typed wrapper — use it.** `FdyCombo` ·
+   `FdyDatepicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` · `FdyCfl` · `FdyChart` ·
+   `FdyTable` · `FdyModal` · `FdyDrawer`, 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 — the enhancer initialises once and the first render is correct — then
+   breaks quietly: later-rendered DOM is never hydrated and the widget's state sits in the DOM
+   instead of your framework's. Everything else is the same markup everywhere; hydrate the other
+   interactive components with `useFreeday` (Vue/React) or `FreedayBlazor.initAll` (Blazor).
 
 ### Containment — why the kit's containers are `position:relative`
 
@@ -53,7 +65,9 @@ Two consequences for you:
 ## Enhancers — hook, script, global, events
 
 Every enhancer is zero-dependency, auto-initialises once on `DOMContentLoaded`, and is idempotent:
-re-hydrate SPA-rendered DOM with `window.Freeday<X>.initAll(root)`. Events are bubbling
+re-hydrate SPA-rendered DOM with `window.Freeday<X>.initAll(root)`. **`root` may be the widget
+itself or an ancestor of it** — both work, so a framework ref placed directly on the enhanced
+element is fine. Events are bubbling
 `CustomEvent`s; the payload is in `event.detail`.
 
 | Markup hook | Script | Global | Emits |
@@ -227,6 +241,10 @@ rest of the app is not.
 - Modifiers: `--ghost` `--danger` `--text` `--icon` (square, icon-only) `--sm` `--lg`
 - Parts: `.fdy-btn__icon` (wraps the `<svg>`) · `.fdy-btn-group` (segmented row, `role="group"` +
   `aria-label`)
+- **Toggle / segmented:** `aria-pressed="true"` gives a real pressed state (soft primary fill on
+  `--ghost`/`--text`, an inset-sunk gradient on the solid button). No extra class — `aria-pressed`
+  is already the right attribute, and it is what turns `.fdy-btn-group` from a joined row into a
+  complete segmented control.
 - A11y: `--icon` **requires** `aria-label`. Use `<button type="button">` unless it submits.
 
 ```html
@@ -312,6 +330,8 @@ Native inputs, styled. `.fdy-check` · `.fdy-radio` · `.fdy-switch` on the wrap
 ```
 
 ## 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).
+
 Fully styleable dropdown, APG combobox+listbox. Needs `freeday-select.js`.
 
 - `.fdy-combo` (+`--error`, `--no-icon`) · `__button` `__value` (+`--placeholder`) `__listbox`
@@ -334,6 +354,8 @@ Fully styleable dropdown, APG combobox+listbox. Needs `freeday-select.js`.
 ```
 
 ## Autocomplete — `.fdy-autocomplete`
+> **Typed wrapper: `<FdyAutocomplete>`** — 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).
+
 Editable combobox that filters as you type. Needs `freeday-autocomplete.js`.
 
 - `.fdy-autocomplete` · `__listbox` `__option` `__empty`
@@ -341,6 +363,8 @@ Editable combobox that filters as you type. Needs `freeday-autocomplete.js`.
   `aria-controls` → the listbox `id`, `autocomplete="off"`.
 
 ## Cascade select — `.fdy-cascade`
+> **Typed wrapper: `<FdyCascade>`** — 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).
+
 Hierarchical drill-down. The data model is a **nested `<ul>`** inside the wrapper: an `<li>` with a
 child `<ul>` is a branch, one without is a leaf. Needs `freeday-cascade.js`.
 
@@ -360,6 +384,8 @@ 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).
+
 A read-only field backed by master data: the button opens a searchable dialog, the picked row fills
 the field. The value is always **chosen, never typed**. Needs `freeday-cfl.js`.
 
@@ -410,6 +436,8 @@ the field. The value is always **chosen, never typed**. Needs `freeday-cfl.js`.
 ```
 
 ## Date picker — `data-fdy-datepicker`
+> **Typed wrapper: `<FdyDatepicker>`** — 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).
+
 Input-styled trigger + calendar popover. Needs `freeday-datepicker.js`. **Author an empty `<div>`**
 — the enhancer builds everything.
 
@@ -417,6 +445,7 @@ Input-styled trigger + calendar popover. Needs `freeday-datepicker.js`. **Author
   `__panel`; calendar internals `.fdy-cal__head` `__nav` `__title` `__grid` `__dow` `__day`
 - 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.
+  **Typed wrapper: `<FdyDateRange>`** (Vue/React/Blazor) — use it in those stacks.
 - Attributes: `data-value="YYYY-MM-DD"`, `data-placeholder`, `data-label`, `data-fdy-no-icon`
 
 ```html
@@ -499,6 +528,18 @@ Linear multi-step flow: marker → check, one panel at a time, back/next. Needs
 
 # Data
 
+**`__btn` is optional.** For a **read-only indicator** put `__marker` + `__label` straight in the
+`<li>`; for a **navigable** stepper wrap them in `<button class="fdy-step__btn">` (add `disabled`
+for a step that is not reachable yet). Both render identically — the marker carries its own lift
+over the connector line, so omitting `__btn` cannot make the connector draw through the numbers.
+
+```html
+<ol class="fdy-stepper">
+  <li class="fdy-step is-complete"><span class="fdy-step__marker">1</span><span class="fdy-step__label">Email</span></li>
+  <li class="fdy-step is-active"><span class="fdy-step__marker">2</span><span class="fdy-step__label">Verify</span></li>
+</ol>
+```
+
 ## Table — `.fdy-table`
 Semantic static table. Wrap in `.fdy-table-wrap` (bordered surface) or `.fdy-table-scroll`
 (horizontal scroll). Always a `<caption>` (use `.fdy-visually-hidden` if it shouldn't show) and
@@ -517,6 +558,8 @@ Semantic static table. Wrap in `.fdy-table-wrap` (bordered surface) or `.fdy-tab
 ```
 
 ## Data table — `.fdy-datatable`
+> **Typed wrapper: `<FdyTable>`** — controlled: `columns` + `rows`, with sort/filter/page events (`update:pageIndex` · `onPageIndexChange` · `PageIndexChanged`) and `process` for driving a card list off the same processed set. The markup below is the raw enhancer path.
+
 The interactive table: global search, sort, per-column filters, row selection + bulk bar,
 pagination. Needs `freeday-table.js`. Wrap the whole thing in `.fdy-datatable` + `data-fdy-table`
 (`data-page-size="N"`).
@@ -556,6 +599,8 @@ Empty / error placeholder for a data area. `--danger` for failures. Parts: `__ic
 replaces.
 
 ## 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.
+
 Pure SVG/CSS, no dependency, re-colours with the theme. Needs `freeday-chart.js`; call
 `FreedayChart.update(el)` after changing data (or use `FdyChart` in Vue/React/Blazor).
 
@@ -662,18 +707,43 @@ Size-matched placeholders so nothing shifts when data lands: `--title` `--text`
 
 # Navigation
 
-## Nav (sidebar menu) — `.fdy-nav`
-Vertical navigation, used by the app shell. Items are `<a class="fdy-nav__item">` with
+## 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>`:
 
 - `.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
+- **`--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
+  links go on-colour automatically.
+
+```html
+<header class="fdy-appbar">
+  <a class="fdy-appbar__brand" href="/">Acme</a>
+  <nav class="fdy-nav fdy-nav--horizontal" aria-label="Main">
+    <a class="fdy-nav__item" href="/invoices" aria-current="page">Invoices</a>
+    <a class="fdy-nav__item" href="/customers">Customers</a>
+  </nav>
+  <span class="fdy-appbar__spacer"></span>
+  <div class="fdy-appbar__actions"><!-- buttons --></div>
+</header>
+```
+
+> **Which one for navigation?** A nav link is a link marked `aria-current="page"` — never
+> `aria-selected` (invalid ARIA on an anchor) and never `role="tab"`. Use `.fdy-nav--horizontal`
+> for an application's **primary** navigation. For **routed sub-navigation** that should look like
+> tabs (`/settings/profile` · `/settings/billing`), put `.fdy-tabs__list` / `.fdy-tabs__tab` on
+> plain `<a>`s — those classes honour `aria-current="page"` too — and do **not** add the tab roles
+> or `freeday-tabs.js`, which promise a keyboard contract routes do not have.
 
 ## App bar — `.fdy-appbar`
 Standalone top bar (distinct from the shell's `.fdy-app__topbar`). Modifiers `--sticky`
 `--elevated` `--dense` `--primary` (on-colour controls). Parts `__brand` `__spacer` `__actions`.
+It ships **no link class of its own** — put `<nav class="fdy-nav fdy-nav--horizontal">` in it
+for primary navigation (see Nav above).
 
 ## Breadcrumb — `.fdy-breadcrumb`
 `<nav class="fdy-breadcrumb" aria-label="Breadcrumb">` → `<ol class="fdy-breadcrumb__list">` with
@@ -682,6 +752,8 @@ Standalone top bar (distinct from the shell's `.fdy-app__topbar`). Modifiers `--
 
 ## 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"`**,
+so the same look serves routed sub-navigation built from plain links — see the note under Nav.
 
 ```html
 <div class="fdy-tabs" data-fdy-tabs>
@@ -699,12 +771,16 @@ APG tabs: ←/→, Home/End, roving tabindex. Needs `freeday-tabs.js`.
 # Overlays
 
 ## Modal — `.fdy-modal`
+> **Typed wrapper: `<FdyModal>`** — Vue (`:open` + `@close`) · React (`open` + `onClose`) · Blazor (`@bind-Open`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
+
 Native `<dialog>`: focus trap, Esc and backdrop come from the browser. Sizes `--sm` `--md` `--lg`
 `--wide`; `--cfl` for the choose-from-list dialog. Parts `__header` `__title` `__body` `__footer`
 `__close`. The body scrolls; the footer never clips. `aria-labelledby` → the title's `id`;
 `data-close` on any button that should close it.
 
 ## Drawer — `.fdy-drawer`
+> **Typed wrapper: `<FdyDrawer>`** — Vue (`:open` + `@close`) · React (`open` + `onClose`) · Blazor (`@bind-Open`). In those stacks use the wrapper; the markup below is for stacks without an adapter (and is what the wrapper renders).
+
 Temporary side panel on native `<dialog>` — left by default, `--right` to flip. Parts `__header`
 `__title` `__body` `__footer` `__close`. Open it from any
 `<button data-fdy-drawer="<dialog id>">`. Needs `freeday-drawer.js`.
@@ -751,6 +827,10 @@ 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.
 
+Sizes: `--xs` 1.5rem · *(base)* 2.5rem · `--sm` 2rem · `--lg` 3.5rem. Use **`--xs` inside a control**
+— `.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.
+
 ## Chip — `.fdy-chip`
 Three roles inside a `.fdy-chips` row:
 

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-v1.21.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.21.0)
+[![Release](https://img.shields.io/badge/release-v1.23.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.23.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`.
@@ -31,6 +31,28 @@ npm test                # tes transformasi build + kontras WCAG (node:test)
 
 ## Pakai di project
 
+### Pertama: pintu masuk mana yang kamu pakai?
+
+Sebagian besar Freeday itu markup + kelas `fdy-*` dan sama di mana pun. **Sepuluh komponen
+interaktif juga punya wrapper typed** — di stack berikut, pakai wrapper-nya, bukan markup mentah +
+enhancer:
+
+| Stack-mu | Impor kesepuluhnya dari | Binding |
+|---|---|---|
+| **Vue 3** | `@cahyo-dimas/freeday/vue` | `v-model` |
+| **React 18/19** | `@cahyo-dimas/freeday/react` | `value` + `onChange` |
+| **Blazor (net8.0)** | RCL `Freeday.Blazor` | `@bind-Value` |
+| HTML statis · Svelte · template server-rendered | *(tanpa wrapper)* markup mentah + enhancer, di bawah | event `fdy-*` |
+
+Kesepuluhnya: `FdyCombo` · `FdyDatepicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` ·
+`FdyCfl` · `FdyChart` · `FdyTable` · `FdyModal` · `FdyDrawer`. Menulis markup mentah untuk
+kesepuluh ini di dalam Vue/React/Blazor *kelihatan* baik-baik saja — render pertama benar — lalu
+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
+yang terakhir, hydrate dengan `useFreeday` (Vue/React) atau `FreedayBlazor.initAll` (Blazor).
+Panduan lengkap per stack: [`docs/getting-started.md`](docs/getting-started.md).
+
 **Sebagai paket (project dengan bundler — Vue/React/Blazor/Vite):**
 ```bash
 npm i @cahyo-dimas/freeday

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-v1.21.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.21.0)
+[![Release](https://img.shields.io/badge/release-v1.23.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.23.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`.
@@ -31,6 +31,27 @@ npm test                # build-transform tests + WCAG contrast (node:test)
 
 ## Use in a project
 
+### First: which entry point is yours?
+
+Most of Freeday is markup + `fdy-*` classes and is identical everywhere. **Ten interactive
+components also ship a typed wrapper** — in these stacks, use the wrapper, not raw markup + enhancer:
+
+| Your stack | Import the ten from | Binding |
+|---|---|---|
+| **Vue 3** | `@cahyo-dimas/freeday/vue` | `v-model` |
+| **React 18/19** | `@cahyo-dimas/freeday/react` | `value` + `onChange` |
+| **Blazor (net8.0)** | `Freeday.Blazor` RCL | `@bind-Value` |
+| Static HTML · Svelte · server-rendered templates | *(no wrapper)* raw markup + enhancers, below | `fdy-*` events |
+
+The ten: `FdyCombo` · `FdyDatepicker` · `FdyDateRange` · `FdyAutocomplete` · `FdyCascade` ·
+`FdyCfl` · `FdyChart` · `FdyTable` · `FdyModal` · `FdyDrawer`. Hand-writing the raw markup for
+these inside Vue/React/Blazor *looks* fine — the first render is correct — and then breaks quietly:
+DOM the framework renders later is never hydrated, and the widget's state ends up in the DOM instead
+of your framework's. Everything else (button, card, badge, alert, table markup, layout, and the
+interactive components with no wrapper) is the same plain markup in every stack — hydrate the latter
+with `useFreeday` (Vue/React) or `FreedayBlazor.initAll` (Blazor). Full walkthrough per stack:
+[`docs/getting-started.md`](docs/getting-started.md).
+
 **As a package (projects with a bundler — Vue/React/Blazor/Vite):**
 ```bash
 npm i @cahyo-dimas/freeday

package/USAGE.md

@@ -115,6 +115,27 @@ container, a single `<section>`. An app whose two list screens are dense and who
 are not should scope it per screen rather than densifying everything. Set it at one level per screen,
 never per component.
 
+## 6b. Navigation: one component, two orientations — and never a tab role
+
+A navigation link is an `<a class="fdy-nav__item">` marked **`aria-current="page"`**. That does not
+change with the layout:
+
+- **Sidebar app** — `.fdy-nav` inside `.fdy-app__sidebar` (the default).
+- **Top-nav app** — `.fdy-nav.fdy-nav--horizontal` inside `.fdy-appbar` or `.fdy-app__topbar`, with
+  no sidebar. Same items, same states; on `.fdy-appbar--primary` the links go on-colour for you.
+- **Routed sub-navigation that should look like tabs** (`/settings/profile` · `/settings/billing`) —
+  put `.fdy-tabs__list` / `.fdy-tabs__tab` on plain `<a>`s. Those classes honour `aria-current="page"`
+  as well as `aria-selected="true"` precisely for this. Do **not** add `role="tab"`/`role="tablist"`
+  or `freeday-tabs.js`: those promise a roving-tabindex, arrow-key, one-panel-per-tab contract that
+  route links do not honour, and `aria-selected` is invalid ARIA on an anchor in the first place.
+
+Reserve the full `.fdy-tabs` component (with its roles and its enhancer) for **in-page** tabs, where
+nothing navigates.
+
+**Toggles:** a button that is on/off carries `aria-pressed`, and the kit styles it — soft primary
+fill on `--ghost`/`--text`, a sunken gradient on the solid button. A `.fdy-btn-group` of `--ghost`
+buttons with exactly one `aria-pressed="true"` **is** the segmented control; don't hand-tint it.
+
 ## 7. Assemble the page from the frame down
 
 1. **Shell:** every application starts inside **`.fdy-app`** — a flex row of `__sidebar` (with

package/adapters/react/useFreeday.js

@@ -9,6 +9,11 @@
  *   useFreeday(root);            // scopes init to this component's subtree
  *   // <div ref={root}> ...[data-fdy-*] markup... </div>
  *
+ * The ref may also sit ON the widget itself — <div ref={root} data-fdy-menu> — which is what you
+ * write when the component's root element IS the widget. initAll() matches its own root as
+ * well as descendants, so both shapes work. (Before 1.23.0 only the wrapping shape did, and
+ * the other failed silently: querySelectorAll never matches its root.)
+ *
  * Events are native bubbling CustomEvents — add listeners on the root (they
  * bubble) and read event.detail. See index.d.ts for the detail types.
  */

package/adapters/vue/useFreeday.js

@@ -10,6 +10,11 @@
  *   useFreeday(root);            // scopes init to this component's subtree
  *   // <div ref="root"> ...[data-fdy-*] markup... </div>
  *
+ * The ref may also sit ON the widget itself — <div ref="root" data-fdy-menu> — which is what you
+ * write when the component's root element IS the widget. initAll() matches its own root as
+ * well as descendants, so both shapes work. (Before 1.23.0 only the wrapping shape did, and
+ * the other failed silently: querySelectorAll never matches its root.)
+ *
  * Events come straight through as native bubbling CustomEvents — bind them with
  * plain v-on (e.g. @fdy-cascade-change) and read event.detail. See index.d.ts
  * for the detail types.

package/dist/freeday-autocomplete.js

@@ -122,7 +122,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-autocomplete]')) initAutocomplete(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-carousel.js

@@ -98,7 +98,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-carousel]'), initCarousel);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-carousel]')) initCarousel(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-carousel]'), initCarousel);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-cascade.js

@@ -243,7 +243,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-cascade]'), initCascade);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-cascade]')) initCascade(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-cascade]'), initCascade);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-cfl.js

@@ -179,28 +179,33 @@
     };
   }
 
-  function initTriggers(context) {
-    var ctx = context || document;
+  function bindGroup(group) {
+    if (group.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
+    if (!dialog) return;
+    initDialog(dialog);
+    var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
+    if (!opener) return;
+    group.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), function (group) {
-      if (group.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
-      if (!dialog) return;
-      initDialog(dialog);
-      var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
-      if (!opener) return;
-      group.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
-    });
+  function bindOpener(opener) {
+    if (opener.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
+    if (!dialog) return;
+    initDialog(dialog);
+    opener.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), function (opener) {
-      if (opener.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
-      if (!dialog) return;
-      initDialog(dialog);
-      opener.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
-    });
+  function initTriggers(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-cfl]')) bindGroup(ctx);
+    if (ctx.matches && ctx.matches('[data-fdy-cfl-open]')) bindOpener(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), bindGroup);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), bindOpener);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-chart.js

@@ -416,7 +416,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-chart]'), initChart);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chart]')) initChart(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chart]'), initChart);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-chip.js

@@ -69,6 +69,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chips]')) initGroup(root);
+    if (root.matches && root.matches('.fdy-chip__remove')) initRemove(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chips]'), initGroup);
     Array.prototype.forEach.call(root.querySelectorAll('.fdy-chip__remove'), initRemove);
   }

package/dist/freeday-datepicker.js

@@ -306,9 +306,12 @@
   }
 
   function initAll(context) {
-    var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-daterange]'), initRange);
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-datepicker]'), initPicker);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-daterange]')) initRange(root);
+    if (root.matches && root.matches('[data-fdy-datepicker]')) initPicker(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-daterange]'), initRange);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datepicker]'), initPicker);
   }
 
   if (document.readyState === 'loading') {

package/dist/freeday-datetime.js

@@ -70,7 +70,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-datetimepicker]')) initDatetime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
   }
 
   if (document.readyState === 'loading') {