@cahyo-dimas/freeday 1.20.0 → 1.22.0

package/CHANGELOG.md

@@ -3,6 +3,139 @@
 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
+mechanism, which turned out to be a genuine kit bug hiding behind it. Both halves of that rejection
+reproduce here, so the rejection stands and the withdrawal is recorded rather than re-litigated.
+### Fixed
+- **Hidden labels could scroll the whole page.** `.fdy-visually-hidden` is `position:absolute`, and
+  `clip` hides *painting*, not *layout*. With no positioned ancestor its containing block is the
+  document, and `overflow` clips only what is contained inside the overflow box — so a hidden label in
+  a horizontally scrolling table (the kit's own recommended way to name an icon button) parks at its
+  static position and drags the document sideways. Measured in Chrome: **1351px** of phantom page
+  scroll from 11 spans in one table; `overflow-x:hidden` on the scroller, the shell, `body` and `html`
+  each changed it by **0px**; removing the spans took it to 0. Every clipping/scrolling container that
+  holds consumer markup now declares `position:relative` — `.fdy-table-scroll`, `.fdy-table-wrap`,
+  `.fdy-list`, `.fdy-card`, `.fdy-tabs__list`, `.fdy-carousel__viewport`, `.fdy-accordion` — each
+  measured to take its own case to 0 with the scroller still scrolling internally. The rest are
+  already inside something the kit positions (`<dialog>`, the sticky sidebar, a fixed popover) and are
+  listed with that reason in the new test.
+  **`.fdy-accordion` is the one to note:** it was contained only by its panel's reveal *animation*
+  (a transform makes a containing block), and that animation sits behind
+  `prefers-reduced-motion: no-preference` — so the bug was reachable **only** by readers who asked for
+  reduced motion. Measured with the animation off: 2906px → 0.
+  *Possible migration:* if you absolutely positioned something inside a card, list or table scroller
+  and relied on it escaping, it now anchors to that container. Anchoring is the reason for the change.
+- **`--button` rows and cards ignored `:disabled`.** `.fdy-list__row--button` adopts the UA button box
+  but not its disabled state, so a row disabled mid-flight kept its hover tint and pointer cursor — a
+  control answering the pointer while refusing input. `:disabled` and `[aria-disabled="true"]` now dim
+  it and withdraw hover, for `.fdy-list__row--button`, `.fdy-list__row--interactive`,
+  `.fdy-card--button` and `.fdy-card--interactive`. The report suggested `cursor:default`; the kit uses
+  `opacity:.5` + `cursor:not-allowed` on every other disabled control, and consistency wins.
+### Changed
+- **`data-theme` is no longer root-scoped** — the same move density made in 1.20.0, and for the same
+  reason. The two *explicit* selectors are now bare `[data-theme="dark"]` / `[data-theme="light"]`, so
+  a `<section data-theme="dark">` inverts that region and **every component inside it follows** —
+  card surfaces, inputs, and text roles like `.fdy-title-page` that set `color: var(--color-text)`
+  explicitly and therefore never saw a consumer's hand-rolled override. A dark brand panel beside a
+  light sign-in form is an ordinary layout; it should not cost a re-colouring pass. Setting the
+  attribute on `<html>` is unchanged, and a `[data-theme="light"]` island nested inside a dark region
+  wins in turn.
+  **The system default stays root-scoped, deliberately** — the report asked for "the two generated
+  selectors", but there are three. Un-rooting `@media (prefers-color-scheme: dark) { :root:not(...) }`
+  would make it match every element that does not itself carry `data-theme="light"`, including the
+  *children* of a light island, dragging them back to dark. Measured: with the un-rooted variant that
+  island renders light ink on a light surface; root-scoped, it stays correct.
+### Added — guards
+- **`test/css.test.mjs`** — the containment invariant, CI-gated: a rule that declares `overflow` must
+  also be positioned, or be listed with the ancestor that already contains it. Single-line truncation
+  (`text-overflow:ellipsis` on a label) is excluded by shape, not by name, so new truncating labels
+  don't accumulate in an allowlist. A new clipping container fails the test until someone decides
+  which case it is.
+- **`browser/layout.mjs`** — the same bug end-to-end in real Chrome (`npm run test:browser`): ten
+  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
+  (not root-scoped, media block still is, and the block order the cascade depends on); this guards the
+  behaviour that shape exists for. Mutation-checked: re-rooting the selectors fails it.
+### Notes
+- Not adopted from the report, deliberately: `.fdy-datatable`, `.fdy-modal__body`, `.fdy-drawer__body`
+  were listed as needing the same fix. Measured: they do not escape — `<dialog>` is `position:fixed`
+  and is already their containing block, and the datatable's own scrolling child now carries it. They
+  are in the test's allowlist with that reason instead of carrying a declaration that does nothing.
+
 ## [1.20.0] — 2026-08-12
 Two bodies of work in one release (1.19.0 was prepared but never committed, tagged or published, so
 it is folded in here rather than left as a phantom version):

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,33 @@ 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`
+
+`.fdy-visually-hidden` is `position:absolute`, and `clip` hides **painting**, not **layout**. An
+absolutely positioned box resolves against its nearest *positioned* ancestor, and `overflow` clips
+only what is contained that way — so in an unpositioned scroller, a hidden label parks at its static
+position (possibly thousands of px to the right) and drags the **whole document** sideways. It is
+invisible in the DOM and immune to `overflow-x: hidden` on every wrapper.
+
+Every kit container that clips or scrolls therefore declares `position: relative` —
+`.fdy-table-scroll`, `.fdy-table-wrap`, `.fdy-list`, `.fdy-card`, `.fdy-tabs__list`,
+`.fdy-carousel__viewport`, `.fdy-accordion` (the rest are already inside a positioned ancestor).
+Two consequences for you:
+
+- **Do the same in your own scrollers.** A container with `overflow` that holds arbitrary markup
+  needs `position: relative`, or the hidden labels *you* write will escape it.
+- **Diagnose it correctly.** `document.documentElement.scrollWidth` sees the escaped box;
+  `document.body.scrollWidth` does not. The honest check is `window.scrollTo(9999, 0)` then reading
+  `window.scrollX`.
 
 ## Enhancers — hook, script, global, events
 
@@ -208,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
@@ -293,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`
@@ -315,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`
@@ -322,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`.
 
@@ -341,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`.
 
@@ -391,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.
 
@@ -398,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
@@ -498,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"`).
@@ -537,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).
 
@@ -572,6 +622,10 @@ responsive `.fdy-datatable` should become below `md` — not a stack of `.fdy-ca
   control (render it as a real `<button>`/`<a>`; the UA box is reset without losing the list surface)
 - Row internals: `.fdy-list__main` (truncating stack) → `.fdy-list__title` + `.fdy-list__meta`, and
   `.fdy-list__aside` pinned right
+- **Disabled** — `disabled` on the `<button>` (or `aria-disabled="true"` when the row is an `<a>`/
+  `<div>`) dims the row and withdraws the hover tint and the pointer cursor, same as every other
+  control in the kit. Do not hand-roll it: an undimmed row that still lights up under the pointer
+  reads as clickable while it is refusing input.
 - Not `.fdy-list-reset` — that utility only strips UA bullets/indent from a semantic list.
 
 ```html
@@ -639,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
@@ -659,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>
@@ -676,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`.
@@ -709,6 +794,10 @@ Parts `__body` `__title` `__desc` `__footer`. Modifiers:
   the UA button box **without** losing the card surface/border
 - `.fdy-card--button` never replaces keyboard semantics — a clickable card must be a real
   `<button>` or `<a>`.
+- **Disabled** — `disabled` (or `aria-disabled="true"`) dims the card and withdraws the pointer
+  cursor and the `--interactive` hover-lift.
+- The card is `position:relative`, so a badge or ribbon you absolutely position inside it anchors
+  to the card. That is also what keeps hidden labels inside it from escaping — see *Containment*.
 
 ## Badge — `.fdy-badge`
 Inline status pill: `--success` `--warning` `--danger` `--info` `--outline`. Never colour-only —

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.20.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.20.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
@@ -121,6 +143,8 @@ container-nya, bukan scroll sendiri.
 
 ### 3. Theming — 3 sumbu lewat `data-*` di root
 - `data-theme="light|dark"` — redefinisi token semantic (bind ke state tema app-mu).
+  Berlaku di **ancestor mana pun**, tak harus root: `<section data-theme="dark">` membalik region itu
+  dan semua komponen di dalamnya ikut (lihat [`USAGE.md`](USAGE.md) §5b).
 - `data-density="comfortable|compact"` — tinggi kontrol (`--control-h`) untuk layar padat data.
   Ini auto-apply hanya ke kontrol bawaan Freeday (button, input, combo, dst); komponen
   custom/hand-built harus baca `--control-h` sendiri (mis. `height: var(--control-h)`) supaya ikut

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.20.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.20.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
@@ -121,6 +142,8 @@ of scrolling.
 
 ### 3. Theming — 3 axes via `data-*` on the root
 - `data-theme="light|dark"` — redefines the semantic tokens (bind it to your app's theme state).
+  Works on **any ancestor**, not just the root: `<section data-theme="dark">` inverts that region
+  and every component inside it follows (see [`USAGE.md`](USAGE.md) §5b).
 - `data-density="comfortable|compact"` — control height (`--control-h`) for data-dense screens.
   This auto-applies only to Freeday's built-in controls (button, input, combo, etc.);
   custom/hand-built components must read `--control-h` themselves (e.g. `height: var(--control-h)`)

package/USAGE.md

@@ -82,6 +82,27 @@ point, everything around it quiet.
 - **Surfaces:** most backgrounds are `--color-surface`; `--color-surface-2`/`-3` for a recessed area;
   `--color-primary-soft` only when you want a tinted callout, not as a default panel colour.
 
+## 5b. Theme — global by default, per-subtree when a region is inverted
+
+`data-theme="light|dark"` redefines the semantic tokens. Set it on `<html>` and it themes the app;
+that is the normal case and nothing about it has changed.
+
+**It is also per-subtree.** The two explicit selectors are bare `[data-theme="dark"]` /
+`[data-theme="light"]`, and semantic tokens are inheriting custom properties — so a
+`<section data-theme="dark">` inverts that region and **every Freeday component inside it follows**:
+card surfaces, inputs, buttons, and text roles like `.fdy-title-page` that set
+`color: var(--color-text)` explicitly. A dark brand panel beside a light sign-in form needs no
+per-element re-colouring, and a `[data-theme="light"]` island nested back inside a dark region wins
+in turn.
+
+Do **not** invert a region by hand with `--color-inverse-*` plus `color-mix`. That pair is right for
+a one-off band of your own markup, but it stops scaling the moment the region contains a real
+component — anything that sets its own colour from a token never sees your override, and you end up
+restating colours per element.
+
+The **system** default (`@media (prefers-color-scheme: dark)`) stays root-scoped on purpose: that
+rule is about the document, and un-rooting it would re-darken the children of a light island.
+
 ## 6. Density — `compact` for data-dense screens
 
 `data-density="compact"` tightens control height **and** the mid-range spacing scale
@@ -94,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