@cahyo-dimas/freeday 1.21.0 → 1.22.0

package/CHANGELOG.md

@@ -3,6 +3,69 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [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 +120,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`
 
@@ -227,6 +239,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 +328,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 +352,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 +361,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 +382,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 +434,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 +443,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
@@ -517,6 +544,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 +585,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 +693,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 +738,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 +757,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`.

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.22.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.22.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.22.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.22.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/dist/freeday.bundle.css

@@ -473,6 +473,15 @@ a { color: var(--color-primary); }
 .fdy-app__brand-title{display:block;font-family:var(--font-display);font-weight:var(--weight-bold);font-size:var(--text-lg);color:var(--color-text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
 .fdy-app__brand-subtitle{display:block;font-size:var(--text-xs);font-weight:var(--weight-regular);color:var(--color-text-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
 .fdy-nav{flex:1;min-height:0;overflow-y:auto;overscroll-behavior:contain;display:flex;flex-direction:column;gap:2px;padding:var(--space-3) var(--space-3) var(--space-6);}
+/* Horizontal variant — the SAME nav links laid out as a row, for a top-nav application (one that
+ * puts its primary navigation in `.fdy-appbar` / `.fdy-app__topbar` and has no sidebar). Deliberately
+ * a modifier and not a new block: the item, its states and `aria-current="page"` are unchanged. That
+ * is the point — a navigation link is a link marked `aria-current`, never `aria-selected` (invalid
+ * ARIA on an anchor) and never a tab role, so borrowing `.fdy-tabs` for routes half-adopts a contract
+ * (roving tabindex, a panel per tab) that route links do not honour. position:relative because the
+ * row scrolls; see base.css on why a scroller must be a containing block. */
+.fdy-nav--horizontal{position:relative;flex:0 1 auto;flex-direction:row;align-items:center;gap:var(--space-1);padding:0;min-height:0;overflow-x:auto;}
+.fdy-nav--horizontal .fdy-nav__item{white-space:nowrap;}
 .fdy-nav__item{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-2) var(--space-3);border-radius:var(--radius-md);font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text-muted);text-decoration:none;cursor:pointer;transition:background var(--dur-fast) var(--ease-standard),color var(--dur-fast) var(--ease-standard);}
 .fdy-nav__item:hover{background:var(--color-surface-2);color:var(--color-text);}
 /* Active indicator stays in the primary ramp so it never clashes with a re-themed accent. */
@@ -548,9 +557,18 @@ a { color: var(--color-primary); }
 .fdy-appbar__brand svg{display:block;width:1.5rem;height:1.5rem;}
 .fdy-appbar__spacer{flex:1;}
 .fdy-appbar__actions{display:inline-flex;align-items:center;gap:var(--space-1);}
+/* Primary navigation inside the bar: `<nav class="fdy-nav fdy-nav--horizontal">` with
+   `.fdy-nav__item` links (see app-shell.css). The bar ships no link class of its own — a nav link
+   is the same component whether the nav is a sidebar column or a top row. */
 /* Controls on a coloured app bar go on-colour (icons stay legible, hover is a light wash) */
 .fdy-appbar--primary .fdy-btn--ghost{background:transparent;border-color:transparent;color:var(--color-on-primary);box-shadow:none;}
 .fdy-appbar--primary .fdy-btn--ghost:hover{background:color-mix(in srgb,var(--color-on-primary) 16%,transparent);color:var(--color-on-primary);transform:none;}
+/* Nav links on a coloured bar: full on-colour ink in every state (a dimmed variant would trade away
+   the contrast the bar's own token pair guarantees). The current page is carried by the background
+   wash plus the semibold weight the base rule already applies — and by `aria-current` itself. */
+.fdy-appbar--primary .fdy-nav__item{color:var(--color-on-primary);}
+.fdy-appbar--primary .fdy-nav__item:hover{background:color-mix(in srgb,var(--color-on-primary) 16%,transparent);color:var(--color-on-primary);}
+.fdy-appbar--primary .fdy-nav__item[aria-current="page"]{background:color-mix(in srgb,var(--color-on-primary) 24%,transparent);color:var(--color-on-primary);}
 
 /* Freeday — Autocomplete (text input + filtered suggestion listbox, APG editable combobox).
  * Enhanced by freeday-autocomplete.js. */
@@ -653,6 +671,14 @@ a { color: var(--color-primary); }
 .fdy-btn:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-primary) 60%,transparent),inset 0 1px 0 rgba(255,255,255,.26);}
 .fdy-btn:active{transform:translateY(1px);box-shadow:0 1px 4px -1px color-mix(in srgb,var(--color-primary) 46%,transparent);}
 .fdy-btn:disabled{opacity:.5;cursor:not-allowed;transform:none;box-shadow:none;}
+/* Pressed / toggle. `aria-pressed` is already the right attribute for a toggle button, so this adds
+   no class and no new markup contract — and it is what makes .fdy-btn-group a complete segmented
+   control: the group joins the borders, this says which segment you are on. Each fill variant
+   defines its OWN pressed look below; a single shared rule cannot work, because a gradient is a
+   background-IMAGE and would blank the ghost variant's background-color. Solid: invert the gradient
+   and sink the shadow inward, so a held button reads as depressed, not merely primary-coloured. */
+.fdy-btn[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 12%,var(--color-primary)),var(--color-primary));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 22%,transparent);}
+.fdy-btn[aria-pressed="true"]:hover{transform:none;box-shadow:inset 0 2px 6px color-mix(in srgb,#000 22%,transparent);}
 
 .fdy-btn--ghost{background:var(--color-surface);color:var(--color-primary-strong);border-color:var(--color-border-strong);box-shadow:var(--shadow-1);}
 .fdy-btn--ghost:hover{transform:none;background:var(--color-primary-soft);border-color:var(--color-primary-border);box-shadow:var(--shadow-1);}
@@ -661,6 +687,7 @@ a { color: var(--color-primary); }
 .fdy-btn--danger{background:linear-gradient(180deg,var(--color-danger-btn),color-mix(in srgb,#000 12%,var(--color-danger-btn)));color:var(--color-on-danger);box-shadow:0 2px 9px -1px color-mix(in srgb,var(--color-danger-btn) 46%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-danger-btn) 54%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:active{transform:translateY(1px);}
+.fdy-btn--danger[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 14%,var(--color-danger-btn)),var(--color-danger-btn));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 24%,transparent);}
 
 .fdy-btn--sm{height:calc(var(--control-h) - var(--space-2));padding:0 var(--space-3);font-size:var(--text-xs);border-radius:var(--radius-sm);}
 .fdy-btn--lg{height:calc(var(--control-h) + var(--space-2));padding:0 var(--space-6);font-size:var(--text-base);border-radius:var(--radius-lg);}
@@ -673,6 +700,11 @@ a { color: var(--color-primary); }
 .fdy-btn--text{background:none;color:var(--color-primary-strong);border-color:transparent;box-shadow:none;}
 .fdy-btn--text:hover{transform:none;background:var(--color-primary-soft);box-shadow:none;}
 .fdy-btn--text:active{transform:translateY(1px);box-shadow:none;}
+/* Ghost/text pressed: the kit's selected-surface pair (soft fill + strong ink) — the same pairing
+   .fdy-nav__item uses for the current page, and one the AA contrast gate already covers. This is
+   the realistic segmented control: a row of --ghost buttons with exactly one aria-pressed. */
+.fdy-btn--ghost[aria-pressed="true"],.fdy-btn--text[aria-pressed="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);border-color:var(--color-primary-border);box-shadow:none;}
+.fdy-btn--ghost[aria-pressed="true"]:hover,.fdy-btn--text[aria-pressed="true"]:hover{background:var(--color-primary-soft);transform:none;box-shadow:none;}
 
 /* Icon-only — square; combine with --ghost/--text/--sm/--lg. Requires aria-label. */
 .fdy-btn--icon{width:var(--control-h);padding:0;}
@@ -1518,7 +1550,13 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-tabs__tab:hover{color:var(--color-text);}
 .fdy-tabs__tab:disabled,.fdy-tabs__tab[aria-disabled="true"]{opacity:.5;cursor:not-allowed;color:var(--color-text-muted);}
 .fdy-tabs__tab:disabled:hover,.fdy-tabs__tab[aria-disabled="true"]:hover{color:var(--color-text-muted);}
-.fdy-tabs__tab[aria-selected="true"]{color:var(--color-primary-strong);border-bottom-color:var(--color-primary);}
+/* `aria-current="page"` is honoured alongside `aria-selected="true"` so the tab look can be used for
+   ROUTE-driven sub-navigation (/settings/profile · /settings/billing), where the tabs are real links.
+   A link cannot be `aria-selected` — that is invalid ARIA on an anchor; `aria-current` is the only
+   correct marker, and it is what a router sets. Use `.fdy-tabs` + `freeday-tabs.js` (roving tabindex,
+   a panel per tab) for in-page tabs; use these classes on plain links for routed ones, and
+   `.fdy-nav--horizontal` for an application's PRIMARY navigation. */
+.fdy-tabs__tab[aria-selected="true"],.fdy-tabs__tab[aria-current="page"]{color:var(--color-primary-strong);border-bottom-color:var(--color-primary);}
 .fdy-tabs__tab:focus-visible{outline:none;border-radius:var(--radius-sm);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
 .fdy-tabs__panel{padding:var(--space-5) 0;}
 .fdy-tabs__panel[hidden]{display:none;}

package/dist/freeday.css

@@ -103,6 +103,15 @@ a { color: var(--color-primary); }
 .fdy-app__brand-title{display:block;font-family:var(--font-display);font-weight:var(--weight-bold);font-size:var(--text-lg);color:var(--color-text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
 .fdy-app__brand-subtitle{display:block;font-size:var(--text-xs);font-weight:var(--weight-regular);color:var(--color-text-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
 .fdy-nav{flex:1;min-height:0;overflow-y:auto;overscroll-behavior:contain;display:flex;flex-direction:column;gap:2px;padding:var(--space-3) var(--space-3) var(--space-6);}
+/* Horizontal variant — the SAME nav links laid out as a row, for a top-nav application (one that
+ * puts its primary navigation in `.fdy-appbar` / `.fdy-app__topbar` and has no sidebar). Deliberately
+ * a modifier and not a new block: the item, its states and `aria-current="page"` are unchanged. That
+ * is the point — a navigation link is a link marked `aria-current`, never `aria-selected` (invalid
+ * ARIA on an anchor) and never a tab role, so borrowing `.fdy-tabs` for routes half-adopts a contract
+ * (roving tabindex, a panel per tab) that route links do not honour. position:relative because the
+ * row scrolls; see base.css on why a scroller must be a containing block. */
+.fdy-nav--horizontal{position:relative;flex:0 1 auto;flex-direction:row;align-items:center;gap:var(--space-1);padding:0;min-height:0;overflow-x:auto;}
+.fdy-nav--horizontal .fdy-nav__item{white-space:nowrap;}
 .fdy-nav__item{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-2) var(--space-3);border-radius:var(--radius-md);font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text-muted);text-decoration:none;cursor:pointer;transition:background var(--dur-fast) var(--ease-standard),color var(--dur-fast) var(--ease-standard);}
 .fdy-nav__item:hover{background:var(--color-surface-2);color:var(--color-text);}
 /* Active indicator stays in the primary ramp so it never clashes with a re-themed accent. */
@@ -178,9 +187,18 @@ a { color: var(--color-primary); }
 .fdy-appbar__brand svg{display:block;width:1.5rem;height:1.5rem;}
 .fdy-appbar__spacer{flex:1;}
 .fdy-appbar__actions{display:inline-flex;align-items:center;gap:var(--space-1);}
+/* Primary navigation inside the bar: `<nav class="fdy-nav fdy-nav--horizontal">` with
+   `.fdy-nav__item` links (see app-shell.css). The bar ships no link class of its own — a nav link
+   is the same component whether the nav is a sidebar column or a top row. */
 /* Controls on a coloured app bar go on-colour (icons stay legible, hover is a light wash) */
 .fdy-appbar--primary .fdy-btn--ghost{background:transparent;border-color:transparent;color:var(--color-on-primary);box-shadow:none;}
 .fdy-appbar--primary .fdy-btn--ghost:hover{background:color-mix(in srgb,var(--color-on-primary) 16%,transparent);color:var(--color-on-primary);transform:none;}
+/* Nav links on a coloured bar: full on-colour ink in every state (a dimmed variant would trade away
+   the contrast the bar's own token pair guarantees). The current page is carried by the background
+   wash plus the semibold weight the base rule already applies — and by `aria-current` itself. */
+.fdy-appbar--primary .fdy-nav__item{color:var(--color-on-primary);}
+.fdy-appbar--primary .fdy-nav__item:hover{background:color-mix(in srgb,var(--color-on-primary) 16%,transparent);color:var(--color-on-primary);}
+.fdy-appbar--primary .fdy-nav__item[aria-current="page"]{background:color-mix(in srgb,var(--color-on-primary) 24%,transparent);color:var(--color-on-primary);}
 
 /* Freeday — Autocomplete (text input + filtered suggestion listbox, APG editable combobox).
  * Enhanced by freeday-autocomplete.js. */
@@ -283,6 +301,14 @@ a { color: var(--color-primary); }
 .fdy-btn:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-primary) 60%,transparent),inset 0 1px 0 rgba(255,255,255,.26);}
 .fdy-btn:active{transform:translateY(1px);box-shadow:0 1px 4px -1px color-mix(in srgb,var(--color-primary) 46%,transparent);}
 .fdy-btn:disabled{opacity:.5;cursor:not-allowed;transform:none;box-shadow:none;}
+/* Pressed / toggle. `aria-pressed` is already the right attribute for a toggle button, so this adds
+   no class and no new markup contract — and it is what makes .fdy-btn-group a complete segmented
+   control: the group joins the borders, this says which segment you are on. Each fill variant
+   defines its OWN pressed look below; a single shared rule cannot work, because a gradient is a
+   background-IMAGE and would blank the ghost variant's background-color. Solid: invert the gradient
+   and sink the shadow inward, so a held button reads as depressed, not merely primary-coloured. */
+.fdy-btn[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 12%,var(--color-primary)),var(--color-primary));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 22%,transparent);}
+.fdy-btn[aria-pressed="true"]:hover{transform:none;box-shadow:inset 0 2px 6px color-mix(in srgb,#000 22%,transparent);}
 
 .fdy-btn--ghost{background:var(--color-surface);color:var(--color-primary-strong);border-color:var(--color-border-strong);box-shadow:var(--shadow-1);}
 .fdy-btn--ghost:hover{transform:none;background:var(--color-primary-soft);border-color:var(--color-primary-border);box-shadow:var(--shadow-1);}
@@ -291,6 +317,7 @@ a { color: var(--color-primary); }
 .fdy-btn--danger{background:linear-gradient(180deg,var(--color-danger-btn),color-mix(in srgb,#000 12%,var(--color-danger-btn)));color:var(--color-on-danger);box-shadow:0 2px 9px -1px color-mix(in srgb,var(--color-danger-btn) 46%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-danger-btn) 54%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:active{transform:translateY(1px);}
+.fdy-btn--danger[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 14%,var(--color-danger-btn)),var(--color-danger-btn));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 24%,transparent);}
 
 .fdy-btn--sm{height:calc(var(--control-h) - var(--space-2));padding:0 var(--space-3);font-size:var(--text-xs);border-radius:var(--radius-sm);}
 .fdy-btn--lg{height:calc(var(--control-h) + var(--space-2));padding:0 var(--space-6);font-size:var(--text-base);border-radius:var(--radius-lg);}
@@ -303,6 +330,11 @@ a { color: var(--color-primary); }
 .fdy-btn--text{background:none;color:var(--color-primary-strong);border-color:transparent;box-shadow:none;}
 .fdy-btn--text:hover{transform:none;background:var(--color-primary-soft);box-shadow:none;}
 .fdy-btn--text:active{transform:translateY(1px);box-shadow:none;}
+/* Ghost/text pressed: the kit's selected-surface pair (soft fill + strong ink) — the same pairing
+   .fdy-nav__item uses for the current page, and one the AA contrast gate already covers. This is
+   the realistic segmented control: a row of --ghost buttons with exactly one aria-pressed. */
+.fdy-btn--ghost[aria-pressed="true"],.fdy-btn--text[aria-pressed="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);border-color:var(--color-primary-border);box-shadow:none;}
+.fdy-btn--ghost[aria-pressed="true"]:hover,.fdy-btn--text[aria-pressed="true"]:hover{background:var(--color-primary-soft);transform:none;box-shadow:none;}
 
 /* Icon-only — square; combine with --ghost/--text/--sm/--lg. Requires aria-label. */
 .fdy-btn--icon{width:var(--control-h);padding:0;}
@@ -1148,7 +1180,13 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-tabs__tab:hover{color:var(--color-text);}
 .fdy-tabs__tab:disabled,.fdy-tabs__tab[aria-disabled="true"]{opacity:.5;cursor:not-allowed;color:var(--color-text-muted);}
 .fdy-tabs__tab:disabled:hover,.fdy-tabs__tab[aria-disabled="true"]:hover{color:var(--color-text-muted);}
-.fdy-tabs__tab[aria-selected="true"]{color:var(--color-primary-strong);border-bottom-color:var(--color-primary);}
+/* `aria-current="page"` is honoured alongside `aria-selected="true"` so the tab look can be used for
+   ROUTE-driven sub-navigation (/settings/profile · /settings/billing), where the tabs are real links.
+   A link cannot be `aria-selected` — that is invalid ARIA on an anchor; `aria-current` is the only
+   correct marker, and it is what a router sets. Use `.fdy-tabs` + `freeday-tabs.js` (roving tabindex,
+   a panel per tab) for in-page tabs; use these classes on plain links for routed ones, and
+   `.fdy-nav--horizontal` for an application's PRIMARY navigation. */
+.fdy-tabs__tab[aria-selected="true"],.fdy-tabs__tab[aria-current="page"]{color:var(--color-primary-strong);border-bottom-color:var(--color-primary);}
 .fdy-tabs__tab:focus-visible{outline:none;border-radius:var(--radius-sm);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
 .fdy-tabs__panel{padding:var(--space-5) 0;}
 .fdy-tabs__panel[hidden]{display:none;}

package/docs/agent-onboarding.md

@@ -18,8 +18,38 @@ the **root of the consuming project**:
 ```markdown
 ## UI: Freeday design system (@cahyo-dimas/freeday)
 
-All UI in this project is built from Freeday. It is a **token-driven CSS kit + zero-dependency JS
-enhancers**, not a component framework — components are plain markup with `fdy-*` classes.
+All UI in this project is built from Freeday: a **token-driven CSS kit** (`fdy-*` classes on plain
+markup) with **typed components for Vue, React and Blazor** layered on top. Most of the kit is
+markup + classes; ten interactive components also ship a typed wrapper, and in those three stacks
+the wrapper is the correct way to use them.
+
+**0. First decide which entry point this project uses. This is not an optimisation — get it wrong
+and the code looks correct and fails later.**
+
+| This project's stack | Import the ten components from | Binding |
+|---|---|---|
+| Vue 3 | `@cahyo-dimas/freeday/vue` | `v-model` |
+| React 18/19 | `@cahyo-dimas/freeday/react` | `value` + `onChange` |
+| Blazor (net8.0) | `@using Freeday.Blazor` (RCL) | `@bind-Value` |
+| Static HTML, Svelte, server-rendered templates… | no wrapper — raw markup + the enhancer script | `fdy-*` DOM events |
+
+The ten: **FdyCombo · FdyDatepicker · FdyDateRange · FdyAutocomplete · FdyCascade · FdyCfl ·
+FdyChart · FdyTable · FdyModal · FdyDrawer**. In Vue/React/Blazor, **never hand-write the raw
+markup + enhancer for these ten.** The raw path *appears* to work — the enhancer auto-initialises
+once on `DOMContentLoaded` and the first render is correct — then fails quietly: DOM your framework
+renders later is never hydrated, and the widget's state lives in the DOM instead of in your
+framework's state.
+
+Everything else is the same in every stack: plain `fdy-*` markup (button, card, badge, alert,
+table markup, layout…). For the *other* interactive components (chips, stepper, input mask, file
+upload, tree, tabs, menu, rating, slider, form validation, carousel, timepicker) there is no
+wrapper — use the raw markup and hydrate it:
+
+- **Vue / React** — `useFreeday(rootRef)` from the same import path, plus `import '@cahyo-dimas/freeday'`
+  once at app entry to register the enhancers. (The ten typed components do **not** need this: they
+  are native Vue/React implementations of the same markup, not wrappers over the enhancer.)
+- **Blazor** — `FreedayBlazor.initAll` interop. (Here the typed components *are* thin wrappers over
+  the enhancers, so the enhancer script is always required.)
 
 **Before writing or editing any markup/CSS, read these (they ship inside the package):**
 - `node_modules/@cahyo-dimas/freeday/COMPONENTS.md` — every class that exists, with minimal markup
@@ -40,8 +70,9 @@ enhancers**, not a component framework — components are plain markup with `fdy
 5. Assemble from the frame down: `.fdy-app` → `.fdy-page` → `.fdy-page-section` → components.
 6. Form errors: `aria-invalid="true"` + `aria-describedby` → a `.fdy-help.fdy-help--error`.
    Icon-only buttons need `aria-label`. Status is never colour-only.
-7. Interactive components need their enhancer script loaded (see the table in COMPONENTS.md);
-   in an SPA, re-hydrate dynamic DOM (`useFreeday` in Vue/React does this).
+7. Interactive components need their enhancer script loaded (see the table in COMPONENTS.md); in an
+   SPA, re-hydrate dynamic DOM with `useFreeday` / `FreedayBlazor.initAll`. This applies to the
+   components **without** a typed wrapper — for the ten in step 0, use the wrapper instead.
 8. Freeday owns components + tokens, **not layout**. Grids/stacks/one-off gaps come from our own
    layout layer — build its theme on `var(--space-N)` so both systems stay in step.
 ```

package/docs/getting-started.md

@@ -17,10 +17,15 @@ Freeday = **CSS** (semantic tokens + `fdy-*` classes) + **zero-dependency JS enh
 1. **Static vs interactive.** Static components (button, card, badge, plain input, layout) need
    only the **`fdy-*` classes** — no JS. Interactive components (select/combo, cascade, date/time
    picker, table, dropzone, form validation, input mask, chip) need the **JS enhancers**.
-2. **The enhancer is the source of truth.** You don't re-implement components; the enhancer owns
-   the widget's DOM. You **listen for `fdy-*` events** (all bubbling `CustomEvent`s, data in
-   `event.detail`) → store them in your framework state. Event/API contract table:
-   [`integrations.md` §Event & API contract](integrations.md).
+2. **The enhancer is the source of truth — *on the raw path*.** You don't re-implement components;
+   the enhancer owns the widget's DOM. You **listen for `fdy-*` events** (all bubbling
+   `CustomEvent`s, data in `event.detail`) → store them in your framework state. Event/API contract
+   table: [`integrations.md` §Event & API contract](integrations.md).
+   **On Vue, React or Blazor this is not the path to take for ten of the components** — `FdyCombo`,
+   `FdyDatepicker`, `FdyDateRange`, `FdyAutocomplete`, `FdyCascade`, `FdyCfl`, `FdyChart`,
+   `FdyTable`, `FdyModal`, `FdyDrawer` ship typed wrappers that own the state properly (Vue and
+   React re-implement the interaction natively; Blazor wraps the enhancer over interop). Use them;
+   the raw path is for the components without a wrapper, and for stacks without an adapter.
 3. **Hydrate dynamic DOM.** Enhancers auto-init once on `DOMContentLoaded`. DOM an SPA renders
    **after** that must be re-hydrated: `window.Freeday<X>.initAll(el)` (idempotent, safe to repeat).
    Each framework's adapter wraps this — you don't call it manually.
@@ -179,7 +184,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.21.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^1.22.0"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -71,7 +71,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs",
+    "test:browser": "node --test browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit"

package/src/components/app-shell.css

@@ -24,6 +24,15 @@
 .fdy-app__brand-title{display:block;font-family:var(--font-display);font-weight:var(--weight-bold);font-size:var(--text-lg);color:var(--color-text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
 .fdy-app__brand-subtitle{display:block;font-size:var(--text-xs);font-weight:var(--weight-regular);color:var(--color-text-muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
 .fdy-nav{flex:1;min-height:0;overflow-y:auto;overscroll-behavior:contain;display:flex;flex-direction:column;gap:2px;padding:var(--space-3) var(--space-3) var(--space-6);}
+/* Horizontal variant — the SAME nav links laid out as a row, for a top-nav application (one that
+ * puts its primary navigation in `.fdy-appbar` / `.fdy-app__topbar` and has no sidebar). Deliberately
+ * a modifier and not a new block: the item, its states and `aria-current="page"` are unchanged. That
+ * is the point — a navigation link is a link marked `aria-current`, never `aria-selected` (invalid
+ * ARIA on an anchor) and never a tab role, so borrowing `.fdy-tabs` for routes half-adopts a contract
+ * (roving tabindex, a panel per tab) that route links do not honour. position:relative because the
+ * row scrolls; see base.css on why a scroller must be a containing block. */
+.fdy-nav--horizontal{position:relative;flex:0 1 auto;flex-direction:row;align-items:center;gap:var(--space-1);padding:0;min-height:0;overflow-x:auto;}
+.fdy-nav--horizontal .fdy-nav__item{white-space:nowrap;}
 .fdy-nav__item{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-2) var(--space-3);border-radius:var(--radius-md);font-size:var(--text-sm);font-weight:var(--weight-medium);color:var(--color-text-muted);text-decoration:none;cursor:pointer;transition:background var(--dur-fast) var(--ease-standard),color var(--dur-fast) var(--ease-standard);}
 .fdy-nav__item:hover{background:var(--color-surface-2);color:var(--color-text);}
 /* Active indicator stays in the primary ramp so it never clashes with a re-themed accent. */

package/src/components/appbar.css

@@ -10,6 +10,15 @@
 .fdy-appbar__brand svg{display:block;width:1.5rem;height:1.5rem;}
 .fdy-appbar__spacer{flex:1;}
 .fdy-appbar__actions{display:inline-flex;align-items:center;gap:var(--space-1);}
+/* Primary navigation inside the bar: `<nav class="fdy-nav fdy-nav--horizontal">` with
+   `.fdy-nav__item` links (see app-shell.css). The bar ships no link class of its own — a nav link
+   is the same component whether the nav is a sidebar column or a top row. */
 /* Controls on a coloured app bar go on-colour (icons stay legible, hover is a light wash) */
 .fdy-appbar--primary .fdy-btn--ghost{background:transparent;border-color:transparent;color:var(--color-on-primary);box-shadow:none;}
 .fdy-appbar--primary .fdy-btn--ghost:hover{background:color-mix(in srgb,var(--color-on-primary) 16%,transparent);color:var(--color-on-primary);transform:none;}
+/* Nav links on a coloured bar: full on-colour ink in every state (a dimmed variant would trade away
+   the contrast the bar's own token pair guarantees). The current page is carried by the background
+   wash plus the semibold weight the base rule already applies — and by `aria-current` itself. */
+.fdy-appbar--primary .fdy-nav__item{color:var(--color-on-primary);}
+.fdy-appbar--primary .fdy-nav__item:hover{background:color-mix(in srgb,var(--color-on-primary) 16%,transparent);color:var(--color-on-primary);}
+.fdy-appbar--primary .fdy-nav__item[aria-current="page"]{background:color-mix(in srgb,var(--color-on-primary) 24%,transparent);color:var(--color-on-primary);}

package/src/components/button.css

@@ -10,6 +10,14 @@
 .fdy-btn:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-primary) 60%,transparent),inset 0 1px 0 rgba(255,255,255,.26);}
 .fdy-btn:active{transform:translateY(1px);box-shadow:0 1px 4px -1px color-mix(in srgb,var(--color-primary) 46%,transparent);}
 .fdy-btn:disabled{opacity:.5;cursor:not-allowed;transform:none;box-shadow:none;}
+/* Pressed / toggle. `aria-pressed` is already the right attribute for a toggle button, so this adds
+   no class and no new markup contract — and it is what makes .fdy-btn-group a complete segmented
+   control: the group joins the borders, this says which segment you are on. Each fill variant
+   defines its OWN pressed look below; a single shared rule cannot work, because a gradient is a
+   background-IMAGE and would blank the ghost variant's background-color. Solid: invert the gradient
+   and sink the shadow inward, so a held button reads as depressed, not merely primary-coloured. */
+.fdy-btn[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 12%,var(--color-primary)),var(--color-primary));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 22%,transparent);}
+.fdy-btn[aria-pressed="true"]:hover{transform:none;box-shadow:inset 0 2px 6px color-mix(in srgb,#000 22%,transparent);}
 
 .fdy-btn--ghost{background:var(--color-surface);color:var(--color-primary-strong);border-color:var(--color-border-strong);box-shadow:var(--shadow-1);}
 .fdy-btn--ghost:hover{transform:none;background:var(--color-primary-soft);border-color:var(--color-primary-border);box-shadow:var(--shadow-1);}
@@ -18,6 +26,7 @@
 .fdy-btn--danger{background:linear-gradient(180deg,var(--color-danger-btn),color-mix(in srgb,#000 12%,var(--color-danger-btn)));color:var(--color-on-danger);box-shadow:0 2px 9px -1px color-mix(in srgb,var(--color-danger-btn) 46%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:hover{transform:translateY(-1px);box-shadow:0 6px 18px -2px color-mix(in srgb,var(--color-danger-btn) 54%,transparent),inset 0 1px 0 rgba(255,255,255,.22);}
 .fdy-btn--danger:active{transform:translateY(1px);}
+.fdy-btn--danger[aria-pressed="true"]{background:linear-gradient(180deg,color-mix(in srgb,#000 14%,var(--color-danger-btn)),var(--color-danger-btn));box-shadow:inset 0 2px 6px color-mix(in srgb,#000 24%,transparent);}
 
 .fdy-btn--sm{height:calc(var(--control-h) - var(--space-2));padding:0 var(--space-3);font-size:var(--text-xs);border-radius:var(--radius-sm);}
 .fdy-btn--lg{height:calc(var(--control-h) + var(--space-2));padding:0 var(--space-6);font-size:var(--text-base);border-radius:var(--radius-lg);}
@@ -30,6 +39,11 @@
 .fdy-btn--text{background:none;color:var(--color-primary-strong);border-color:transparent;box-shadow:none;}
 .fdy-btn--text:hover{transform:none;background:var(--color-primary-soft);box-shadow:none;}
 .fdy-btn--text:active{transform:translateY(1px);box-shadow:none;}
+/* Ghost/text pressed: the kit's selected-surface pair (soft fill + strong ink) — the same pairing
+   .fdy-nav__item uses for the current page, and one the AA contrast gate already covers. This is
+   the realistic segmented control: a row of --ghost buttons with exactly one aria-pressed. */
+.fdy-btn--ghost[aria-pressed="true"],.fdy-btn--text[aria-pressed="true"]{background:var(--color-primary-soft);color:var(--color-primary-strong);border-color:var(--color-primary-border);box-shadow:none;}
+.fdy-btn--ghost[aria-pressed="true"]:hover,.fdy-btn--text[aria-pressed="true"]:hover{background:var(--color-primary-soft);transform:none;box-shadow:none;}
 
 /* Icon-only — square; combine with --ghost/--text/--sm/--lg. Requires aria-label. */
 .fdy-btn--icon{width:var(--control-h);padding:0;}

package/src/components/tabs.css

@@ -5,7 +5,13 @@
 .fdy-tabs__tab:hover{color:var(--color-text);}
 .fdy-tabs__tab:disabled,.fdy-tabs__tab[aria-disabled="true"]{opacity:.5;cursor:not-allowed;color:var(--color-text-muted);}
 .fdy-tabs__tab:disabled:hover,.fdy-tabs__tab[aria-disabled="true"]:hover{color:var(--color-text-muted);}
-.fdy-tabs__tab[aria-selected="true"]{color:var(--color-primary-strong);border-bottom-color:var(--color-primary);}
+/* `aria-current="page"` is honoured alongside `aria-selected="true"` so the tab look can be used for
+   ROUTE-driven sub-navigation (/settings/profile · /settings/billing), where the tabs are real links.
+   A link cannot be `aria-selected` — that is invalid ARIA on an anchor; `aria-current` is the only
+   correct marker, and it is what a router sets. Use `.fdy-tabs` + `freeday-tabs.js` (roving tabindex,
+   a panel per tab) for in-page tabs; use these classes on plain links for routed ones, and
+   `.fdy-nav--horizontal` for an application's PRIMARY navigation. */
+.fdy-tabs__tab[aria-selected="true"],.fdy-tabs__tab[aria-current="page"]{color:var(--color-primary-strong);border-bottom-color:var(--color-primary);}
 .fdy-tabs__tab:focus-visible{outline:none;border-radius:var(--radius-sm);box-shadow:0 0 0 3px color-mix(in srgb,var(--color-primary) 26%,transparent);}
 .fdy-tabs__panel{padding:var(--space-5) 0;}
 .fdy-tabs__panel[hidden]{display:none;}