@cahyo-dimas/freeday 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.17.0] — 2026-08-11
+### Added
+- **Avatar identity tones (`--tone-1`…`--tone-8`).** Decorative tints (from the categorical chart
+  palette) with a theme-aware, text-leaning foreground, so same-initial avatars — common where many
+  names share a prefix — stay distinguishable. Verified WCAG **AA** (≥4.5:1) in light **and** dark,
+  guarded by `test/contrast.test.mjs` (which gained a `color-mix()` evaluator). Hash a stable index
+  off the full name, not the initials.
+- **Size-matched skeletons (`.fdy-skeleton--avatar` + `--avatar-sm`/`--avatar-lg`).** Reserve the exact
+  `.fdy-avatar` box (2 / 2.5 / 3.5rem) so data landing causes no layout shift (a bare `--circle` has no
+  dimensions of its own).
+- **`.fdy-card--button`.** When the whole card *is* the control — a real `<button>` picker row, so it is
+  keyboard-reachable and announced — this resets the UA button box **without** stripping the card's own
+  surface/border.
+- **`.fdy-list-reset`.** Opt-in list reset for consumers who pair Freeday with a utility framework run
+  preflight-off (`base.css` is intentionally a *light* reset — it does not strip `ul`/`ol`/`p` margins).
+- **Toast `key` + `Freeday.dismiss()`.** `toast({ …, key })` replaces an existing same-key toast in
+  place instead of stacking a duplicate (a burst of identical failures shows one, refreshed);
+  `Freeday.dismiss(node | key)` closes one early. `toast()` already returned the element — both are now
+  in the `window.Freeday` type declarations.
+### Docs
+- State the scope boundary (components + tokens, **not** layout; pair with a utility framework run
+  preflight-off) in the README and getting-started; document that `--space-*`/`--radius-*` are public
+  tokens to build a utility theme on, and that `data-density` only re-scales control height.
+- Input docs now lead with `aria-invalid="true"` as the canonical accessible-field pattern (it does
+  both the visual state and the one screen readers act on); `.fdy-input--error` is the fallback.
+
+Additive; no breaking changes. Gate: `node --test` 22/22 (incl. avatar-tone contrast, both themes) ·
+`typecheck:react` 0 · new CSS/JS browser-verified in real Chrome. From real-app consumption feedback.
+
 ## [1.16.0] — 2026-08-11
 ### Added
 - **Native Blazor component library (`adapters/blazor/`) — first release, 10/10 parity.** A Razor

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.16.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.16.0)
+[![Release](https://img.shields.io/badge/release-v1.17.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.17.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`.
@@ -49,6 +49,14 @@ ter-publish → install tanpa build step; minify diserahkan ke bundler konsumen.
 Kelas komponen berprefix `fdy-` (mis. `fdy-btn`, `fdy-card`, `fdy-badge`). Pakai langsung di
 markup framework apa pun — Vue, React, Blazor, atau HTML polos.
 
+> **Scope: komponen + token, bukan layout.** Freeday punya komponen & design token; helper layout
+> cuma `.fdy-hidden` / `.fdy-visually-hidden`. Layout (stack/grid/gap) dari layer-mu sendiri —
+> pasangkan dengan utility framework (Tailwind, UnoCSS…) mode **utilities-only, preflight OFF**
+> (`base.css` Freeday = reset-nya). `base.css` itu reset *ringan* (tak me-reset margin `ul`/`ol`/`p` —
+> pakai `.fdy-list-reset` atau komponen list Freeday), dan skala spacing/radius/durasi adalah custom
+> property publik (`--space-0`…`--space-24`, …) yang bisa jadi dasar theme utility-mu. Detail:
+> [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
+
 > `.fdy-btn` **sudah** tombol primary — tak ada modifier `.fdy-btn--primary` terpisah.
 > Modifier untuk varian lain: `--ghost`, `--danger`, `--text`, `--sm`, `--lg`, `--icon`
 > (lihat `docs/index.html`).
@@ -126,17 +134,19 @@ import { useFreeday } from '@cahyo-dimas/freeday/react';
 const root = useRef<HTMLDivElement>(null);
 useFreeday(root);                     // event fdy-* bubbling → listen di root
 ```
-```csharp
-// Blazor — @cahyo-dimas/freeday/blazor (window.FreedayBlazor via JS interop)
-await JS.InvokeVoidAsync("FreedayBlazor.initAll", _root);
-await JS.InvokeAsync<int>("FreedayBlazor.on", _root, "fdy-cascade-change", _self, nameof(OnCascade));
+```razor
+@* Blazor — RCL Freeday.Blazor (net8.0): komponen native typed <FdyX> dengan @bind, 10/10 parity *@
+@using Freeday.Blazor
+<FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl" />
+<FdyTable TRow="Invoice" Columns="_cols" Rows="_rows" RowKey="@(i => i.Code)" PageSize="10" />
+@* Fallback untuk markup mentah: interop window.FreedayBlazor.initAll / .on *@
 ```
 
 | Framework | Adapter | Contoh jalan |
 |---|---|---|
-| Vue 3 | `@cahyo-dimas/freeday/vue` | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
-| React 19 | `@cahyo-dimas/freeday/react` | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
-| Blazor WASM (.NET 10) | `@cahyo-dimas/freeday/blazor` | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
+| Vue 3 | `@cahyo-dimas/freeday/vue` (`useFreeday` + komponen `v-model`) | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
+| React 19 | `@cahyo-dimas/freeday/react` (`useFreeday` + komponen `value`/`onChange`) | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
+| Blazor WASM (net8.0) | RCL `Freeday.Blazor` (`<FdyX>` + `@bind`) · interop `/blazor` | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
 
 Peta library & pola lengkap: [`docs/integrations.md`](docs/integrations.md).
 

package/README.md

@@ -5,7 +5,7 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.16.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.16.0)
+[![Release](https://img.shields.io/badge/release-v1.17.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.17.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`.
@@ -49,6 +49,14 @@ bundler. Because it's on **public npm**, `npm ci` runs in CI without auth or an
 Component classes are prefixed `fdy-` (e.g. `fdy-btn`, `fdy-card`, `fdy-badge`). Use them directly
 in any framework's markup — Vue, React, Blazor, or plain HTML.
 
+> **Scope: components + tokens, not layout.** Freeday owns components and design tokens; the only
+> layout helpers are `.fdy-hidden` / `.fdy-visually-hidden`. Bring your own layout layer — pair it
+> with a utility framework (Tailwind, UnoCSS…) run **utilities-only with preflight OFF** (Freeday's
+> `base.css` is the reset). `base.css` is a *light* reset (it doesn't strip `ul`/`ol`/`p` margins —
+> use `.fdy-list-reset` or a Freeday list component), and the spacing/radius/duration scales are
+> public custom properties (`--space-0`…`--space-24`, …) you can build your utility theme on. Full
+> notes: [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
+
 > `.fdy-btn` is **already** the primary button — there's no separate `.fdy-btn--primary` modifier.
 > Modifiers for other variants: `--ghost`, `--danger`, `--text`, `--sm`, `--lg`, `--icon`
 > (see `docs/index.html`).
@@ -126,17 +134,19 @@ import { useFreeday } from '@cahyo-dimas/freeday/react';
 const root = useRef<HTMLDivElement>(null);
 useFreeday(root);                     // fdy-* events bubble → listen at the root
 ```
-```csharp
-// Blazor — @cahyo-dimas/freeday/blazor (window.FreedayBlazor via JS interop)
-await JS.InvokeVoidAsync("FreedayBlazor.initAll", _root);
-await JS.InvokeAsync<int>("FreedayBlazor.on", _root, "fdy-cascade-change", _self, nameof(OnCascade));
+```razor
+@* Blazor — Freeday.Blazor RCL (net8.0): native typed <FdyX> with @bind, 10/10 parity *@
+@using Freeday.Blazor
+<FdyCombo TValue="string" @bind-Value="_status" Options="_statusOptions" AriaLabelledby="lbl" />
+<FdyTable TRow="Invoice" Columns="_cols" Rows="_rows" RowKey="@(i => i.Code)" PageSize="10" />
+@* Fallback for raw markup: window.FreedayBlazor.initAll / .on interop *@
 ```
 
 | Framework | Adapter | Working example |
 |---|---|---|
-| Vue 3 | `@cahyo-dimas/freeday/vue` | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
-| React 19 | `@cahyo-dimas/freeday/react` | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
-| Blazor WASM (.NET 10) | `@cahyo-dimas/freeday/blazor` | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
+| Vue 3 | `@cahyo-dimas/freeday/vue` (`useFreeday` + `v-model` components) | [`examples/vue-faktur/`](examples/vue-faktur/) (`npm install && npm run dev`) |
+| React 19 | `@cahyo-dimas/freeday/react` (`useFreeday` + `value`/`onChange` components) | [`examples/react-faktur/`](examples/react-faktur/) (`npm install && npm run dev`) |
+| Blazor WASM (net8.0) | `Freeday.Blazor` RCL (`<FdyX>` + `@bind`) · `/blazor` interop | [`examples/blazor-faktur/`](examples/blazor-faktur/) (`dotnet run`) |
 
 Full library map and patterns: [`docs/integrations.md`](docs/integrations.md).
 

package/dist/freeday-toast.js

@@ -1,14 +1,24 @@
 /* Freeday — toast API (optional, zero-dependency).
- * Freeday.toast({ variant, title, message, timeout }) shows a transient
+ * Freeday.toast({ variant, title, message, timeout, key }) shows a transient
  * notification in a live region (created on first use). Returns the element.
  *   variant: 'success' | 'warning' | 'danger' | 'info' (default: neutral)
  *   timeout: ms before auto-dismiss (default 4000; 0 = sticky)
+ *   key:     optional stable id — a new toast with the same key REPLACES the
+ *            existing one in place instead of stacking a duplicate (e.g. a burst
+ *            of identical failures shows one toast, refreshed).
+ * Freeday.dismiss(nodeOrKey) closes a toast early (pass the returned element or its key).
  * Danger toasts use role="alert"; others role="status".
  */
 (function () {
   'use strict';
 
   var region = null;
+  var keyed = {}; // key -> current node, for replace-in-place + dismiss-by-key
+
+  function forget(node) {
+    var k = node && node._fdyKey;
+    if (k != null && keyed[k] === node) delete keyed[k];
+  }
 
   function ensureRegion() {
     if (region && document.body.contains(region)) return region;
@@ -24,7 +34,9 @@
   }
 
   function dismiss(toast) {
+    if (typeof toast === 'string') toast = keyed[toast]; // dismiss by key
     if (!toast || toast.dataset.leaving === '1') return;
+    forget(toast);
     toast.dataset.leaving = '1';
     toast.classList.add('is-leaving');
     var remove = function () { if (toast.parentNode) toast.parentNode.removeChild(toast); };
@@ -64,6 +76,14 @@
     node.appendChild(accent);
     node.appendChild(body);
     node.appendChild(close);
+
+    // Replace-in-place: a same-key toast removes the previous one so bursts don't stack.
+    if (opts.key != null) {
+      var prev = keyed[opts.key];
+      if (prev && prev.parentNode) prev.parentNode.removeChild(prev);
+      node._fdyKey = opts.key;
+      keyed[opts.key] = node;
+    }
     region.appendChild(node);
 
     var timeout = opts.timeout == null ? 4000 : opts.timeout;
@@ -81,4 +101,5 @@
 
   window.Freeday = window.Freeday || {};
   window.Freeday.toast = toast;
+  window.Freeday.dismiss = dismiss; // dismiss(nodeOrKey)
 })();

package/dist/freeday.bundle.css

@@ -361,6 +361,11 @@ a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
+ * margins (see the kit's own list components, which each reset themselves). If you run a utility
+ * framework with its preflight OFF (the recommended pairing), a semantic <ul>/<ol> keeps native
+ * bullets + a 40px indent; add this class (or a Freeday list component) to normalise it. */
+.fdy-list-reset { list-style: none; margin: 0; padding: 0; }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .001ms !important; transition-duration: .001ms !important; }
 }
@@ -524,6 +529,19 @@ a { color: var(--color-primary); }
 .fdy-avatar-group{display:inline-flex;}
 .fdy-avatar-group .fdy-avatar{border:2px solid var(--color-surface);margin-left:calc(var(--space-2)*-1);}
 .fdy-avatar-group .fdy-avatar:first-child{margin-left:0;}
+/* Decorative identity tones — a soft tint of a categorical chart colour with a theme-aware,
+ * text-leaning foreground so initials keep WCAG AA (verified >=4.5:1 in light & dark by
+ * test/contrast.test.mjs). Use to disambiguate same-initial avatars (e.g. many "PT …" names):
+ * hash a stable 1..8 index off the FULL name in your app, then apply .fdy-avatar--tone-<n>. */
+.fdy-avatar--tone-1,.fdy-avatar--tone-2,.fdy-avatar--tone-3,.fdy-avatar--tone-4,.fdy-avatar--tone-5,.fdy-avatar--tone-6,.fdy-avatar--tone-7,.fdy-avatar--tone-8{background:color-mix(in srgb,var(--_fdy-avatar-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-avatar-tone) 50%,var(--color-text));}
+.fdy-avatar--tone-1{--_fdy-avatar-tone:var(--chart-1);}
+.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--chart-2);}
+.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--chart-3);}
+.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--chart-4);}
+.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--chart-5);}
+.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--chart-6);}
+.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--chart-7);}
+.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--chart-8);}
 
 /* Freeday — Badge */
 .fdy-badge{display:inline-flex;align-items:center;gap:var(--space-1);font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);line-height:1;white-space:nowrap;padding:.35em .7em;border-radius:var(--radius-full);color:var(--color-primary-strong);background:var(--color-primary-soft);border:var(--bw) solid color-mix(in srgb,var(--color-primary) 22%,transparent);box-shadow:0 1px 1.5px rgba(16,14,30,.05);}
@@ -643,6 +661,10 @@ a { color: var(--color-primary); }
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
+ * announced — reset the UA button box. Note: it does NOT reset background/border, because
+ * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
+.fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -1202,6 +1224,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-skeleton--text{height:.8rem;margin:.3rem 0;}
 .fdy-skeleton--title{height:1.2rem;width:40%;}
 .fdy-skeleton--circle{border-radius:var(--radius-full);}
+/* Size-matched to .fdy-avatar (2.5rem) and its --sm/--lg, so a skeleton reserves the exact avatar
+ * box and data landing causes no layout shift (a plain --circle has no dimensions of its own). */
+.fdy-skeleton--avatar{width:2.5rem;height:2.5rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-sm{width:2rem;height:2rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-lg{width:3.5rem;height:3.5rem;border-radius:var(--radius-full);}
 @keyframes fdy-skeleton{to{background-position:-200% 0;}}
 @media (prefers-reduced-motion:reduce){.fdy-skeleton{animation:none;}}
 

package/dist/freeday.css

@@ -16,6 +16,11 @@ a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
+ * margins (see the kit's own list components, which each reset themselves). If you run a utility
+ * framework with its preflight OFF (the recommended pairing), a semantic <ul>/<ol> keeps native
+ * bullets + a 40px indent; add this class (or a Freeday list component) to normalise it. */
+.fdy-list-reset { list-style: none; margin: 0; padding: 0; }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .001ms !important; transition-duration: .001ms !important; }
 }
@@ -179,6 +184,19 @@ a { color: var(--color-primary); }
 .fdy-avatar-group{display:inline-flex;}
 .fdy-avatar-group .fdy-avatar{border:2px solid var(--color-surface);margin-left:calc(var(--space-2)*-1);}
 .fdy-avatar-group .fdy-avatar:first-child{margin-left:0;}
+/* Decorative identity tones — a soft tint of a categorical chart colour with a theme-aware,
+ * text-leaning foreground so initials keep WCAG AA (verified >=4.5:1 in light & dark by
+ * test/contrast.test.mjs). Use to disambiguate same-initial avatars (e.g. many "PT …" names):
+ * hash a stable 1..8 index off the FULL name in your app, then apply .fdy-avatar--tone-<n>. */
+.fdy-avatar--tone-1,.fdy-avatar--tone-2,.fdy-avatar--tone-3,.fdy-avatar--tone-4,.fdy-avatar--tone-5,.fdy-avatar--tone-6,.fdy-avatar--tone-7,.fdy-avatar--tone-8{background:color-mix(in srgb,var(--_fdy-avatar-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-avatar-tone) 50%,var(--color-text));}
+.fdy-avatar--tone-1{--_fdy-avatar-tone:var(--chart-1);}
+.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--chart-2);}
+.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--chart-3);}
+.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--chart-4);}
+.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--chart-5);}
+.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--chart-6);}
+.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--chart-7);}
+.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--chart-8);}
 
 /* Freeday — Badge */
 .fdy-badge{display:inline-flex;align-items:center;gap:var(--space-1);font-family:var(--font-body);font-size:var(--text-xs);font-weight:var(--weight-semibold);line-height:1;white-space:nowrap;padding:.35em .7em;border-radius:var(--radius-full);color:var(--color-primary-strong);background:var(--color-primary-soft);border:var(--bw) solid color-mix(in srgb,var(--color-primary) 22%,transparent);box-shadow:0 1px 1.5px rgba(16,14,30,.05);}
@@ -298,6 +316,10 @@ a { color: var(--color-primary); }
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
+ * announced — reset the UA button box. Note: it does NOT reset background/border, because
+ * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
+.fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}
@@ -857,6 +879,11 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 .fdy-skeleton--text{height:.8rem;margin:.3rem 0;}
 .fdy-skeleton--title{height:1.2rem;width:40%;}
 .fdy-skeleton--circle{border-radius:var(--radius-full);}
+/* Size-matched to .fdy-avatar (2.5rem) and its --sm/--lg, so a skeleton reserves the exact avatar
+ * box and data landing causes no layout shift (a plain --circle has no dimensions of its own). */
+.fdy-skeleton--avatar{width:2.5rem;height:2.5rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-sm{width:2rem;height:2rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-lg{width:3.5rem;height:3.5rem;border-radius:var(--radius-full);}
 @keyframes fdy-skeleton{to{background-position:-200% 0;}}
 @media (prefers-reduced-motion:reduce){.fdy-skeleton{animation:none;}}
 

package/dist/freeday.d.ts

@@ -10,11 +10,16 @@ export interface FreedayToastOptions {
   message?: string;
   /** Milliseconds before auto-dismiss. Default 4000; 0 = sticky. */
   timeout?: number;
+  /** Stable id: a new toast with the same key replaces the existing one in place instead of
+   *  stacking a duplicate (e.g. a burst of identical failures shows one, refreshed). */
+  key?: string;
 }
 
 export interface FreedayGlobal {
   /** Show a transient toast in a live region (created on first use). Returns the toast element. */
   toast(opts?: FreedayToastOptions): HTMLElement;
+  /** Dismiss a toast early — pass the element returned by toast(), or a key string. */
+  dismiss(target: HTMLElement | string): void;
 }
 
 declare global {

package/dist/freeday.js

@@ -3319,16 +3319,26 @@
 })();
 
 /* Freeday — toast API (optional, zero-dependency).
- * Freeday.toast({ variant, title, message, timeout }) shows a transient
+ * Freeday.toast({ variant, title, message, timeout, key }) shows a transient
  * notification in a live region (created on first use). Returns the element.
  *   variant: 'success' | 'warning' | 'danger' | 'info' (default: neutral)
  *   timeout: ms before auto-dismiss (default 4000; 0 = sticky)
+ *   key:     optional stable id — a new toast with the same key REPLACES the
+ *            existing one in place instead of stacking a duplicate (e.g. a burst
+ *            of identical failures shows one toast, refreshed).
+ * Freeday.dismiss(nodeOrKey) closes a toast early (pass the returned element or its key).
  * Danger toasts use role="alert"; others role="status".
  */
 (function () {
   'use strict';
 
   var region = null;
+  var keyed = {}; // key -> current node, for replace-in-place + dismiss-by-key
+
+  function forget(node) {
+    var k = node && node._fdyKey;
+    if (k != null && keyed[k] === node) delete keyed[k];
+  }
 
   function ensureRegion() {
     if (region && document.body.contains(region)) return region;
@@ -3344,7 +3354,9 @@
   }
 
   function dismiss(toast) {
+    if (typeof toast === 'string') toast = keyed[toast]; // dismiss by key
     if (!toast || toast.dataset.leaving === '1') return;
+    forget(toast);
     toast.dataset.leaving = '1';
     toast.classList.add('is-leaving');
     var remove = function () { if (toast.parentNode) toast.parentNode.removeChild(toast); };
@@ -3384,6 +3396,14 @@
     node.appendChild(accent);
     node.appendChild(body);
     node.appendChild(close);
+
+    // Replace-in-place: a same-key toast removes the previous one so bursts don't stack.
+    if (opts.key != null) {
+      var prev = keyed[opts.key];
+      if (prev && prev.parentNode) prev.parentNode.removeChild(prev);
+      node._fdyKey = opts.key;
+      keyed[opts.key] = node;
+    }
     region.appendChild(node);
 
     var timeout = opts.timeout == null ? 4000 : opts.timeout;
@@ -3401,6 +3421,7 @@
 
   window.Freeday = window.Freeday || {};
   window.Freeday.toast = toast;
+  window.Freeday.dismiss = dismiss; // dismiss(nodeOrKey)
 })();
 
 /* Freeday — tree checkbox cascade (optional, zero-dependency).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Freeday — token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",

package/src/base.css

@@ -15,6 +15,11 @@ a { color: var(--color-primary); }
 :focus-visible { outline: var(--focus-ring-width) solid var(--focus-ring); outline-offset: var(--focus-ring-width); border-radius: var(--radius-xs); }
 :where(button, input, select, textarea) { font: inherit; }
 .fdy-visually-hidden { position: absolute !important; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0, 0, 0, 0); white-space: nowrap; border: 0; }
+/* Opt-in list reset. base.css is intentionally a *light* reset — it does NOT strip list/paragraph
+ * margins (see the kit's own list components, which each reset themselves). If you run a utility
+ * framework with its preflight OFF (the recommended pairing), a semantic <ul>/<ol> keeps native
+ * bullets + a 40px indent; add this class (or a Freeday list component) to normalise it. */
+.fdy-list-reset { list-style: none; margin: 0; padding: 0; }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .001ms !important; transition-duration: .001ms !important; }
 }

package/src/components/avatar.css

@@ -6,3 +6,16 @@
 .fdy-avatar-group{display:inline-flex;}
 .fdy-avatar-group .fdy-avatar{border:2px solid var(--color-surface);margin-left:calc(var(--space-2)*-1);}
 .fdy-avatar-group .fdy-avatar:first-child{margin-left:0;}
+/* Decorative identity tones — a soft tint of a categorical chart colour with a theme-aware,
+ * text-leaning foreground so initials keep WCAG AA (verified >=4.5:1 in light & dark by
+ * test/contrast.test.mjs). Use to disambiguate same-initial avatars (e.g. many "PT …" names):
+ * hash a stable 1..8 index off the FULL name in your app, then apply .fdy-avatar--tone-<n>. */
+.fdy-avatar--tone-1,.fdy-avatar--tone-2,.fdy-avatar--tone-3,.fdy-avatar--tone-4,.fdy-avatar--tone-5,.fdy-avatar--tone-6,.fdy-avatar--tone-7,.fdy-avatar--tone-8{background:color-mix(in srgb,var(--_fdy-avatar-tone) 18%,var(--color-surface));color:color-mix(in srgb,var(--_fdy-avatar-tone) 50%,var(--color-text));}
+.fdy-avatar--tone-1{--_fdy-avatar-tone:var(--chart-1);}
+.fdy-avatar--tone-2{--_fdy-avatar-tone:var(--chart-2);}
+.fdy-avatar--tone-3{--_fdy-avatar-tone:var(--chart-3);}
+.fdy-avatar--tone-4{--_fdy-avatar-tone:var(--chart-4);}
+.fdy-avatar--tone-5{--_fdy-avatar-tone:var(--chart-5);}
+.fdy-avatar--tone-6{--_fdy-avatar-tone:var(--chart-6);}
+.fdy-avatar--tone-7{--_fdy-avatar-tone:var(--chart-7);}
+.fdy-avatar--tone-8{--_fdy-avatar-tone:var(--chart-8);}

package/src/components/card.css

@@ -3,6 +3,10 @@
 .fdy-card--elevated{box-shadow:var(--shadow-lift-hover);}
 .fdy-card--interactive{cursor:pointer;}
 .fdy-card--interactive:hover{box-shadow:var(--shadow-lift-hover);transform:translateY(-3px);}
+/* When the whole card IS the control — a real <button> so the row is keyboard-reachable and
+ * announced — reset the UA button box. Note: it does NOT reset background/border, because
+ * .fdy-card already sets its own surface + border (resetting them here would strip the card). */
+.fdy-card--button{display:block;width:100%;text-align:inherit;color:inherit;appearance:none;-webkit-appearance:none;}
 .fdy-card__body{padding:var(--space-5);}
 .fdy-card__title{font-family:var(--font-display);font-size:var(--text-lg);font-weight:var(--weight-semibold);letter-spacing:var(--tracking-tight);color:var(--color-text);margin:0 0 var(--space-1);}
 .fdy-card__desc{font-size:var(--text-sm);color:var(--color-text-muted);margin:0;line-height:var(--leading-normal);}

package/src/components/skeleton.css

@@ -3,5 +3,10 @@
 .fdy-skeleton--text{height:.8rem;margin:.3rem 0;}
 .fdy-skeleton--title{height:1.2rem;width:40%;}
 .fdy-skeleton--circle{border-radius:var(--radius-full);}
+/* Size-matched to .fdy-avatar (2.5rem) and its --sm/--lg, so a skeleton reserves the exact avatar
+ * box and data landing causes no layout shift (a plain --circle has no dimensions of its own). */
+.fdy-skeleton--avatar{width:2.5rem;height:2.5rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-sm{width:2rem;height:2rem;border-radius:var(--radius-full);}
+.fdy-skeleton--avatar-lg{width:3.5rem;height:3.5rem;border-radius:var(--radius-full);}
 @keyframes fdy-skeleton{to{background-position:-200% 0;}}
 @media (prefers-reduced-motion:reduce){.fdy-skeleton{animation:none;}}

package/src/freeday-toast.js

@@ -1,14 +1,24 @@
 /* Freeday — toast API (optional, zero-dependency).
- * Freeday.toast({ variant, title, message, timeout }) shows a transient
+ * Freeday.toast({ variant, title, message, timeout, key }) shows a transient
  * notification in a live region (created on first use). Returns the element.
  *   variant: 'success' | 'warning' | 'danger' | 'info' (default: neutral)
  *   timeout: ms before auto-dismiss (default 4000; 0 = sticky)
+ *   key:     optional stable id — a new toast with the same key REPLACES the
+ *            existing one in place instead of stacking a duplicate (e.g. a burst
+ *            of identical failures shows one toast, refreshed).
+ * Freeday.dismiss(nodeOrKey) closes a toast early (pass the returned element or its key).
  * Danger toasts use role="alert"; others role="status".
  */
 (function () {
   'use strict';
 
   var region = null;
+  var keyed = {}; // key -> current node, for replace-in-place + dismiss-by-key
+
+  function forget(node) {
+    var k = node && node._fdyKey;
+    if (k != null && keyed[k] === node) delete keyed[k];
+  }
 
   function ensureRegion() {
     if (region && document.body.contains(region)) return region;
@@ -24,7 +34,9 @@
   }
 
   function dismiss(toast) {
+    if (typeof toast === 'string') toast = keyed[toast]; // dismiss by key
     if (!toast || toast.dataset.leaving === '1') return;
+    forget(toast);
     toast.dataset.leaving = '1';
     toast.classList.add('is-leaving');
     var remove = function () { if (toast.parentNode) toast.parentNode.removeChild(toast); };
@@ -64,6 +76,14 @@
     node.appendChild(accent);
     node.appendChild(body);
     node.appendChild(close);
+
+    // Replace-in-place: a same-key toast removes the previous one so bursts don't stack.
+    if (opts.key != null) {
+      var prev = keyed[opts.key];
+      if (prev && prev.parentNode) prev.parentNode.removeChild(prev);
+      node._fdyKey = opts.key;
+      keyed[opts.key] = node;
+    }
     region.appendChild(node);
 
     var timeout = opts.timeout == null ? 4000 : opts.timeout;
@@ -81,4 +101,5 @@
 
   window.Freeday = window.Freeday || {};
   window.Freeday.toast = toast;
+  window.Freeday.dismiss = dismiss; // dismiss(nodeOrKey)
 })();