@cahyo-dimas/freeday 1.21.0 → 1.23.0

package/dist/freeday.js

@@ -124,7 +124,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-autocomplete]')) initAutocomplete(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-autocomplete]'), initAutocomplete);
   }
 
   if (document.readyState === 'loading') {
@@ -288,7 +291,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-carousel]'), initCarousel);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-carousel]')) initCarousel(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-carousel]'), initCarousel);
   }
 
   if (document.readyState === 'loading') {
@@ -545,7 +551,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-cascade]'), initCascade);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-cascade]')) initCascade(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-cascade]'), initCascade);
   }
 
   if (document.readyState === 'loading') {
@@ -738,28 +747,33 @@
     };
   }
 
-  function initTriggers(context) {
-    var ctx = context || document;
+  function bindGroup(group) {
+    if (group.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
+    if (!dialog) return;
+    initDialog(dialog);
+    var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
+    if (!opener) return;
+    group.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), function (group) {
-      if (group.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(group.getAttribute('data-fdy-cfl'));
-      if (!dialog) return;
-      initDialog(dialog);
-      var opener = group.querySelector('[data-fdy-cfl-trigger], .fdy-input-group__btn');
-      if (!opener) return;
-      group.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(group, opener); });
-    });
+  function bindOpener(opener) {
+    if (opener.dataset.fdyCflBound === '1') return;
+    var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
+    if (!dialog) return;
+    initDialog(dialog);
+    opener.dataset.fdyCflBound = '1';
+    opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
+  }
 
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), function (opener) {
-      if (opener.dataset.fdyCflBound === '1') return;
-      var dialog = document.getElementById(opener.getAttribute('data-fdy-cfl-open'));
-      if (!dialog) return;
-      initDialog(dialog);
-      opener.dataset.fdyCflBound = '1';
-      opener.addEventListener('click', function () { dialog.fdyCflOpen(null, opener); });
-    });
+  function initTriggers(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-cfl]')) bindGroup(ctx);
+    if (ctx.matches && ctx.matches('[data-fdy-cfl-open]')) bindOpener(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl]'), bindGroup);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-cfl-open]'), bindOpener);
   }
 
   if (document.readyState === 'loading') {
@@ -1189,7 +1203,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-chart]'), initChart);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chart]')) initChart(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chart]'), initChart);
   }
 
   if (document.readyState === 'loading') {
@@ -1272,6 +1289,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-chips]')) initGroup(root);
+    if (root.matches && root.matches('.fdy-chip__remove')) initRemove(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-chips]'), initGroup);
     Array.prototype.forEach.call(root.querySelectorAll('.fdy-chip__remove'), initRemove);
   }
@@ -1593,9 +1613,12 @@
   }
 
   function initAll(context) {
-    var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-daterange]'), initRange);
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-datepicker]'), initPicker);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-daterange]')) initRange(root);
+    if (root.matches && root.matches('[data-fdy-datepicker]')) initPicker(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-daterange]'), initRange);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datepicker]'), initPicker);
   }
 
   if (document.readyState === 'loading') {
@@ -1679,7 +1702,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-datetimepicker]')) initDatetime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-datetimepicker]'), initDatetime);
   }
 
   if (document.readyState === 'loading') {
@@ -1709,19 +1735,24 @@
     });
   }
 
+  function bindTrigger(btn) {
+    if (btn.dataset.fdyDrawerBound === '1') return;
+    var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
+    if (!dialog) return;
+    initDrawer(dialog);
+    btn.dataset.fdyDrawerBound = '1';
+    btn.addEventListener('click', function () {
+      if (typeof dialog.showModal === 'function') dialog.showModal();
+      else dialog.setAttribute('open', '');
+    });
+  }
+
   function initTriggers(context) {
     var ctx = context || document;
-    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), function (btn) {
-      if (btn.dataset.fdyDrawerBound === '1') return;
-      var dialog = document.getElementById(btn.getAttribute('data-fdy-drawer'));
-      if (!dialog) return;
-      initDrawer(dialog);
-      btn.dataset.fdyDrawerBound = '1';
-      btn.addEventListener('click', function () {
-        if (typeof dialog.showModal === 'function') dialog.showModal();
-        else dialog.setAttribute('open', '');
-      });
-    });
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-drawer]')) bindTrigger(ctx);
+    if (ctx.matches && ctx.matches('.fdy-drawer')) initDrawer(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-drawer]'), bindTrigger);
     // Init any drawer dialogs even without a wired trigger (backdrop/close still work).
     Array.prototype.forEach.call(ctx.querySelectorAll('.fdy-drawer'), initDrawer);
   }
@@ -1905,7 +1936,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-validate]'), initForm);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-validate]')) initForm(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-validate]'), initForm);
   }
 
   if (document.readyState === 'loading') {
@@ -2019,6 +2053,9 @@
 
   function initAll(context) {
     var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-mask]')) initMask(root);
+    if (root.matches && root.matches('[data-fdy-password]')) initReveal(root);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-mask]'), initMask);
     Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-password]'), initReveal);
   }
@@ -2114,7 +2151,10 @@
   }
 
   function initAll(ctx) {
-    Array.prototype.forEach.call((ctx || document).querySelectorAll('[data-fdy-menu]'), initMenu);
+    var root = ctx || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-menu]')) initMenu(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-menu]'), initMenu);
   }
 
   if (document.readyState === 'loading') {
@@ -2235,7 +2275,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-rating]'), initRating);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-rating]')) initRating(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-rating]'), initRating);
   }
 
   if (document.readyState === 'loading') {
@@ -2438,11 +2481,10 @@
   }
 
   function initAll(context) {
-    var scope = context || document;
-    Array.prototype.forEach.call(
-      scope.querySelectorAll('[data-fdy-combo]'),
-      initCombo
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-combo]')) initCombo(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-combo]'), initCombo);
   }
 
   // One global handler closes the open combo on an outside click.
@@ -2489,7 +2531,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-slider]'), initSlider);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-slider]')) initSlider(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-slider]'), initSlider);
   }
 
   if (document.readyState === 'loading') {
@@ -2580,7 +2625,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-stepper]'), initStepper);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-stepper]')) initStepper(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-stepper]'), initStepper);
   }
 
   if (document.readyState === 'loading') {
@@ -3053,10 +3101,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-table]'),
-      initTable
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-table]')) initTable(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-table]'), initTable);
   }
 
   if (document.readyState === 'loading') {
@@ -3122,10 +3170,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call(
-      (context || document).querySelectorAll('[data-fdy-tabs]'),
-      initTabs
-    );
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tabs]')) initTabs(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tabs]'), initTabs);
   }
 
   if (document.readyState === 'loading') {
@@ -3306,7 +3354,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-timepicker]'), initTime);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-timepicker]')) initTime(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-timepicker]'), initTime);
   }
 
   if (document.readyState === 'loading') {
@@ -3507,7 +3558,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-tree]'), initTree);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-tree]')) initTree(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-tree]'), initTree);
   }
 
   if (document.readyState === 'loading') {
@@ -3714,7 +3768,10 @@
   }
 
   function initAll(context) {
-    Array.prototype.forEach.call((context || document).querySelectorAll('[data-fdy-dropzone]'), initDropzone);
+    var root = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON the widget. */
+    if (root.matches && root.matches('[data-fdy-dropzone]')) initDropzone(root);
+    Array.prototype.forEach.call(root.querySelectorAll('[data-fdy-dropzone]'), initDropzone);
   }
 
   if (document.readyState === 'loading') {

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.23.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.23.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 browser/root-init.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/avatar.css

@@ -1,6 +1,11 @@
 /* Freeday — Avatar */
 .fdy-avatar{display:inline-flex;align-items:center;justify-content:center;flex:none;width:2.5rem;height:2.5rem;border-radius:var(--radius-full);background:var(--color-primary-soft);color:var(--color-primary-strong);font-family:var(--font-body);font-weight:var(--weight-semibold);font-size:var(--text-sm);line-height:1;overflow:hidden;user-select:none;}
 .fdy-avatar img{width:100%;height:100%;object-fit:cover;}
+/* --xs exists for an avatar INSIDE a control: `.fdy-btn--sm` is exactly 2rem tall, which is also
+   `--sm`'s size, so a small avatar in a small button fills it edge to edge and the ghost border
+   crosses the circle. 1.5rem leaves the same ~4px breathing room the kit's controls give their
+   icons. Uses `--text-xs` (the smallest type token the kit has — there is no `2xs`). */
+.fdy-avatar--xs{width:1.5rem;height:1.5rem;font-size:var(--text-xs);}
 .fdy-avatar--sm{width:2rem;height:2rem;font-size:var(--text-xs);}
 .fdy-avatar--lg{width:3.5rem;height:3.5rem;font-size:var(--text-lg);}
 .fdy-avatar-group{display:inline-flex;}

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/stepper.css

@@ -7,7 +7,12 @@
 .fdy-step.is-active::before,.fdy-step.is-complete::before{background:var(--color-primary);}
 .fdy-step__btn{position:relative;z-index:1;display:flex;flex-direction:column;align-items:center;gap:var(--space-2);padding:0 var(--space-2);background:none;border:0;font:inherit;color:inherit;cursor:pointer;max-width:100%;}
 .fdy-step__btn:disabled{cursor:default;}
-.fdy-step__marker{display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
+/* The marker carries the lift itself, NOT `__btn`. The connector above is position:absolute with
+   z-index:0, and a positioned box paints after in-flow inline content in the same stacking context —
+   so a marker that is merely inline (an indicator-only stepper with no `__btn`) gets painted THROUGH
+   by the connector line. Lifting the part that must always exist makes that assembly impossible;
+   `__btn`'s own z-index stays, harmlessly, for the navigable case. */
+.fdy-step__marker{position:relative;z-index:1;display:inline-flex;align-items:center;justify-content:center;width:1.75rem;height:1.75rem;flex:none;border-radius:var(--radius-full);background:var(--color-surface);border:2px solid var(--color-border-strong);color:var(--color-text-muted);font-size:var(--text-sm);font-weight:var(--weight-semibold);font-variant-numeric:tabular-nums;}
 .fdy-step__marker svg{display:block;width:1rem;height:1rem;}
 .fdy-step.is-active .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary-soft);color:var(--color-primary-strong);}
 .fdy-step.is-complete .fdy-step__marker{border-color:var(--color-primary);background:var(--color-primary);color:var(--color-on-primary);}

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;}