@cahyo-dimas/freeday 1.15.0 → 1.17.0

package/adapters/blazor/TableModel.cs

@@ -0,0 +1,196 @@
+using System.Collections.Concurrent;
+using System.Globalization;
+using System.Reflection;
+using System.Text.RegularExpressions;
+
+namespace Freeday.Blazor;
+
+/// <summary>
+/// The sort / filter / paginate logic for <see cref="FdyTable{TRow}"/> — the C# counterpart of the
+/// framework-agnostic adapters/core/table-model.js shared by the Vue and React adapters. Kept as a
+/// separate pure-function class (no rendering, no state) so it mirrors that reference faithfully and
+/// stays unit-testable. Every method is pure: inputs are never mutated (rows are copied before sort).
+/// </summary>
+public static class TableModel
+{
+    private static readonly ConcurrentDictionary<(Type, string), PropertyInfo?> PropCache = new();
+    private static readonly Regex NonNumeric = new(@"[^\d.-]", RegexOptions.Compiled);
+
+    /// <summary>Numeric value, tolerant of formatted strings ("Rp 1.000"); non-numeric -> 0.</summary>
+    private static double ToNumber(object? v)
+    {
+        if (v is null) return 0;
+        if (v is double d) return double.IsFinite(d) ? d : 0;
+        if (v is IConvertible && v is not string)
+        {
+            try { return Convert.ToDouble(v, CultureInfo.InvariantCulture); } catch { /* fall through */ }
+        }
+        string cleaned = NonNumeric.Replace(v.ToString() ?? string.Empty, string.Empty);
+        return double.TryParse(cleaned, NumberStyles.Any, CultureInfo.InvariantCulture, out double n) ? n : 0;
+    }
+
+    /// <summary>Epoch ms; unparseable -> 0.</summary>
+    private static double ToTime(object? v)
+    {
+        if (v is null) return 0;
+        if (v is DateTime dt) return new DateTimeOffset(dt.ToUniversalTime()).ToUnixTimeMilliseconds();
+        if (v is DateTimeOffset dto) return dto.ToUnixTimeMilliseconds();
+        return DateTimeOffset.TryParse(v.ToString(), CultureInfo.InvariantCulture, DateTimeStyles.AssumeUniversal, out DateTimeOffset parsed)
+            ? parsed.ToUnixTimeMilliseconds()
+            : 0;
+    }
+
+    /// <summary>ISO calendar day (yyyy-MM-dd) — lexicographically comparable.</summary>
+    private static string DateOnly(object? v)
+    {
+        if (v is DateTime dt) return dt.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture);
+        if (v is DateTimeOffset dto) return dto.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture);
+        string s = v?.ToString() ?? string.Empty;
+        return s.Length >= 10 ? s[..10] : s;
+    }
+
+    /// <summary>Raw cell value for a column: the accessor if present, else the property named Key.</summary>
+    public static object? CellValue<TRow>(TRow row, FdyTableColumn<TRow> column)
+    {
+        if (column.Value is not null) return column.Value(row);
+        PropertyInfo? prop = PropCache.GetOrAdd((typeof(TRow), column.Key),
+            static k => k.Item1.GetProperty(k.Item2, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase));
+        return prop?.GetValue(row);
+    }
+
+    /// <summary>Cell value as trimmed display text (null -> "").</summary>
+    public static string CellText<TRow>(TRow row, FdyTableColumn<TRow> column)
+    {
+        object? v = CellValue(row, column);
+        return v is null ? string.Empty : (Convert.ToString(v, CultureInfo.CurrentCulture) ?? string.Empty).Trim();
+    }
+
+    /// <summary>Effective comparator type: explicit SortType, else derived from the filter type.</summary>
+    public static FdyColumnType ColumnSortType<TRow>(FdyTableColumn<TRow> column)
+    {
+        if (column.SortType is { } t) return t;
+        return column.Filter switch
+        {
+            FdyColumnFilterType.Number => FdyColumnType.Number,
+            FdyColumnFilterType.Date => FdyColumnType.Date,
+            _ => FdyColumnType.Text,
+        };
+    }
+
+    /// <summary>Ascending comparison of two raw cell values under a comparator type.</summary>
+    public static int CompareBy(FdyColumnType type, object? a, object? b) => type switch
+    {
+        FdyColumnType.Number => ToNumber(a).CompareTo(ToNumber(b)),
+        FdyColumnType.Date => ToTime(a).CompareTo(ToTime(b)),
+        _ => string.Compare(a?.ToString() ?? string.Empty, b?.ToString() ?? string.Empty,
+            StringComparison.CurrentCultureIgnoreCase),
+    };
+
+    /// <summary>True when a filter would actually narrow the rows (worth applying / showing as active).</summary>
+    public static bool IsFilterActive(FdyColumnFilter? filter) => filter switch
+    {
+        FdyColumnFilter.Text t => t.Value.Trim().Length > 0,
+        FdyColumnFilter.Enum e => e.Values.Count > 0,
+        FdyColumnFilter.Number n => n.Min is not null || n.Max is not null,
+        FdyColumnFilter.Date d => d.From is not null || d.To is not null,
+        _ => false,
+    };
+
+    private static bool RowPassesFilter<TRow>(TRow row, FdyTableColumn<TRow> column, FdyColumnFilter filter)
+    {
+        switch (filter)
+        {
+            case FdyColumnFilter.Text t:
+            {
+                string needle = t.Value.Trim().ToLowerInvariant();
+                return needle.Length == 0 || CellText(row, column).ToLowerInvariant().Contains(needle);
+            }
+            case FdyColumnFilter.Enum e:
+                return e.Values.Count == 0 || e.Values.Contains(CellText(row, column));
+            case FdyColumnFilter.Number n:
+            {
+                double v = ToNumber(CellValue(row, column));
+                if (n.Min is { } min && v < min) return false;
+                if (n.Max is { } max && v > max) return false;
+                return true;
+            }
+            case FdyColumnFilter.Date d:
+            {
+                string day = DateOnly(CellValue(row, column));
+                if (d.From is { } from && string.CompareOrdinal(day, from) < 0) return false;
+                if (d.To is { } to && string.CompareOrdinal(day, to) > 0) return false;
+                return true;
+            }
+            default:
+                return true;
+        }
+    }
+
+    /// <summary>Rows passing every active column filter (logical AND). Input is never mutated.</summary>
+    public static List<TRow> FilterRows<TRow>(
+        IReadOnlyList<TRow> rows,
+        IReadOnlyList<FdyTableColumn<TRow>> columns,
+        IReadOnlyDictionary<string, FdyColumnFilter> filters)
+    {
+        List<(FdyTableColumn<TRow> Col, FdyColumnFilter Filter)> active = new();
+        foreach (FdyTableColumn<TRow> col in columns)
+        {
+            if (filters.TryGetValue(col.Key, out FdyColumnFilter? f) && IsFilterActive(f))
+            {
+                active.Add((col, f));
+            }
+        }
+        if (active.Count == 0) return rows.ToList();
+        return rows.Where(row => active.All(e => RowPassesFilter(row, e.Col, e.Filter))).ToList();
+    }
+
+    /// <summary>Rows sorted by the given sort state. Stable via OrderBy; input is never mutated.</summary>
+    public static List<TRow> SortRows<TRow>(
+        IReadOnlyList<TRow> rows,
+        IReadOnlyList<FdyTableColumn<TRow>> columns,
+        FdySortState? sort)
+    {
+        if (sort is null) return rows.ToList();
+        FdyTableColumn<TRow>? column = columns.FirstOrDefault(c => c.Key == sort.Key);
+        if (column is null) return rows.ToList();
+        FdyColumnType type = ColumnSortType(column);
+        int factor = sort.Dir == FdySortDir.Desc ? -1 : 1;
+        return rows
+            .OrderBy(r => r, Comparer<TRow>.Create((a, b) => CompareBy(type, CellValue(a, column), CellValue(b, column)) * factor))
+            .ToList();
+    }
+
+    /// <summary>Page slice (0-based page index). A non-positive size returns all rows.</summary>
+    public static List<TRow> Paginate<TRow>(IReadOnlyList<TRow> rows, int pageIndex, int pageSize)
+    {
+        if (pageSize <= 0) return rows.ToList();
+        return rows.Skip(pageIndex * pageSize).Take(pageSize).ToList();
+    }
+
+    /// <summary>Distinct non-empty cell texts for a column, naturally sorted — the enum-filter source.</summary>
+    public static List<string> DistinctValues<TRow>(IReadOnlyList<TRow> rows, FdyTableColumn<TRow> column)
+    {
+        HashSet<string> seen = new();
+        List<string> outList = new();
+        foreach (TRow row in rows)
+        {
+            string v = CellText(row, column);
+            if (v.Length > 0 && seen.Add(v)) outList.Add(v);
+        }
+        outList.Sort((a, b) => string.Compare(a, b, StringComparison.CurrentCultureIgnoreCase));
+        return outList;
+    }
+
+    /// <summary>Page-number window: first and last page always shown, current ±1, null for the
+    /// "ellipsis" gaps between. <paramref name="current"/> and returned page numbers are 1-based.</summary>
+    public static List<int?> PageWindow(int current, int totalPages)
+    {
+        List<int?> outList = new();
+        for (int p = 1; p <= totalPages; p++)
+        {
+            if (p == 1 || p == totalPages || (p >= current - 1 && p <= current + 1)) outList.Add(p);
+            else if (outList.Count == 0 || outList[^1] is not null) outList.Add(null);
+        }
+        return outList;
+    }
+}

package/adapters/blazor/TableTypes.cs

@@ -0,0 +1,69 @@
+using Microsoft.AspNetCore.Components;
+
+namespace Freeday.Blazor;
+
+/// <summary>Sort direction for a column.</summary>
+public enum FdySortDir { Asc, Desc }
+
+/// <summary>A column's comparator type — how its values are ordered when sorting.</summary>
+public enum FdyColumnType { Text, Number, Date }
+
+/// <summary>Cell alignment. Maps to <c>text-align</c> on the header and body cells.</summary>
+public enum FdyColumnAlign { Left, Right, Center }
+
+/// <summary>The kind of column filter to offer (a funnel popover in the header).</summary>
+public enum FdyColumnFilterType { Text, Enum, Number, Date }
+
+/// <summary>Which column is sorted and in what direction.</summary>
+public sealed record FdySortState(string Key, FdySortDir Dir);
+
+/// <summary>Server-driven pagination state (0-based page index). Its presence on
+/// <see cref="FdyTable{TRow}.Page"/> switches the table into server mode.</summary>
+public sealed record FdyPageState(int Index, int Size, int Total);
+
+/// <summary>The active filter for a single column (a closed set of shapes, one per filter type).</summary>
+public abstract record FdyColumnFilter
+{
+    public sealed record Text(string Value) : FdyColumnFilter;
+    public sealed record Enum(IReadOnlyList<string> Values) : FdyColumnFilter;
+    public sealed record Number(double? Min, double? Max) : FdyColumnFilter;
+    public sealed record Date(string? From, string? To) : FdyColumnFilter;
+}
+
+/// <summary>One column definition. <typeparamref name="TRow"/> is the row type.</summary>
+/// <typeparam name="TRow">The row model.</typeparam>
+public sealed class FdyTableColumn<TRow>
+{
+    /// <summary>Row property key; the sort/filter identity and, when <see cref="Value"/> is unset,
+    /// the default cell accessor (resolved by reflection against a property of this name).</summary>
+    public required string Key { get; init; }
+
+    /// <summary>Header label.</summary>
+    public required string Label { get; init; }
+
+    /// <summary>Show a sort toggle in the header.</summary>
+    public bool Sortable { get; init; }
+
+    /// <summary>Offer a column filter of this type (null = no filter).</summary>
+    public FdyColumnFilterType? Filter { get; init; }
+
+    /// <summary>Cell alignment (null = left).</summary>
+    public FdyColumnAlign? Align { get; init; }
+
+    /// <summary>Render cells in the monospace data font (<c>.fdy-mono</c>).</summary>
+    public bool Mono { get; init; }
+
+    /// <summary>Override the comparator type; defaults to one derived from <see cref="Filter"/>, else Text.</summary>
+    public FdyColumnType? SortType { get; init; }
+
+    /// <summary>Typed value accessor for sort/filter/default cell text; defaults to the property named
+    /// <see cref="Key"/> (reflection). Prefer setting this for strongly-typed, allocation-free access.</summary>
+    public Func<TRow, object?>? Value { get; init; }
+
+    /// <summary>Explicit options for an enum filter; defaults to the distinct values in the current
+    /// rows. Provide this in server-paged mode, where the rows on screen are only one page.</summary>
+    public IReadOnlyList<string>? Options { get; init; }
+
+    /// <summary>Custom cell template; defaults to the accessor's text.</summary>
+    public RenderFragment<TRow>? Cell { get; init; }
+}

package/adapters/blazor/_Imports.razor

@@ -0,0 +1,5 @@
+@using System.Threading.Tasks
+@using Microsoft.AspNetCore.Components
+@using Microsoft.AspNetCore.Components.Web
+@using Microsoft.JSInterop
+@using Freeday.Blazor

package/adapters/blazor/freeday-blazor.js

@@ -55,11 +55,44 @@
     return token;
   }
 
-  // Remove a subscription created by on().
+  // Subscribe to a daterange's child datepicker changes, forwarding {value, role} so a Blazor
+  // wrapper can bind From/To separately — both children emit the same fdy-datepicker-change, so
+  // the originating child's data-role is what tells them apart.
+  function dateRangeOn(element, dotNetRef, methodName) {
+    var handler = function (e) {
+      var origin = e.target && e.target.closest ? e.target.closest('[data-role]') : null;
+      dotNetRef.invokeMethodAsync(methodName, {
+        value: (e.detail && e.detail.value) || '',
+        role: origin ? origin.getAttribute('data-role') : null
+      });
+    };
+    element.addEventListener('fdy-datepicker-change', handler);
+    var token = ++seq;
+    subs[token] = { el: element, type: 'fdy-datepicker-change', fn: handler };
+    return token;
+  }
+
+  // Fire a .NET callback when a pointerdown lands outside `element`, or Escape is pressed —
+  // the light-dismiss primitive for Blazor-owned popovers (e.g. FdyTable's column filter, which
+  // is position:fixed in the top layer and so escapes the table's overflow). Returns an off() token.
+  function onOutside(element, dotNetRef, methodName) {
+    if (!element) return 0;
+    var onPointer = function (e) { if (!element.contains(e.target)) dotNetRef.invokeMethodAsync(methodName); };
+    var onKey = function (e) { if (e.key === 'Escape') dotNetRef.invokeMethodAsync(methodName); };
+    document.addEventListener('pointerdown', onPointer, true);
+    document.addEventListener('keydown', onKey, true);
+    var token = ++seq;
+    subs[token] = { el: document, type: 'pointerdown', fn: onPointer, key: onKey, capture: true };
+    return token;
+  }
+
+  // Remove a subscription created by on() / onOutside(); removes with the same capture flag it
+  // was added with (a bubble-phase listener can't be removed with capture:true and vice versa).
   function off(token) {
     var s = subs[token];
     if (s) {
-      s.el.removeEventListener(s.type, s.fn);
+      s.el.removeEventListener(s.type, s.fn, s.capture === true);
+      if (s.key) s.el.removeEventListener('keydown', s.key, true);
       delete subs[token];
     }
   }
@@ -69,11 +102,76 @@
     if (window.Freeday && typeof window.Freeday.toast === 'function') window.Freeday.toast(options);
   }
 
+  // Passthrough to a combo's programmatic setter (window.FreedayCombo.setValue) so a
+  // Blazor @bind-Value can push an external value change onto the enhancer-owned DOM
+  // without the enhancer echoing an fdy-change back.
+  function comboSetValue(element, value) {
+    if (window.FreedayCombo && typeof window.FreedayCombo.setValue === 'function') {
+      window.FreedayCombo.setValue(element, value);
+    }
+  }
+
+  // Repaint a chart from its current data-* attributes. FdyChart keeps the outer <div> +
+  // attributes under Blazor's control and calls this after each render, so the SVG re-renders
+  // when the bound data changes (window.FreedayChart.update === renderChart).
+  function chartUpdate(element) {
+    if (element && window.FreedayChart && typeof window.FreedayChart.update === 'function') {
+      window.FreedayChart.update(element);
+    }
+  }
+
+  // --- Native <dialog> control for FdyModal ---------------------------------
+  // The kit styles `.fdy-modal` as a <dialog> but nothing drives it; Blazor can't call
+  // showModal()/close() from C#, and Esc/backdrop dismissal must route through .NET state
+  // (not close the DOM behind its back). dialogInit wires cancel + backdrop → a [JSInvokable]
+  // dismiss callback; showModal()/close() are guarded (showModal on an open dialog throws).
+  var dialogSubs = {};
+  var dialogSeq = 0;
+
+  function dialogInit(dialog, dotNetRef, dismissMethod, dismissible) {
+    if (!dialog) return 0;
+    var onCancel = function (e) {
+      e.preventDefault(); // stop the native close; app state is the single source of truth
+      if (dismissible) dotNetRef.invokeMethodAsync(dismissMethod);
+    };
+    var onClick = function (e) {
+      // The ::backdrop is not a separate element — a click whose target is the dialog box
+      // itself (not its content) is a backdrop click.
+      if (dismissible && e.target === dialog) dotNetRef.invokeMethodAsync(dismissMethod);
+    };
+    dialog.addEventListener('cancel', onCancel);
+    dialog.addEventListener('click', onClick);
+    var token = ++dialogSeq;
+    dialogSubs[token] = { el: dialog, cancel: onCancel, click: onClick };
+    return token;
+  }
+
+  function dialogShow(dialog) {
+    if (dialog && typeof dialog.showModal === 'function' && !dialog.open) dialog.showModal();
+  }
+
+  function dialogClose(dialog) {
+    if (dialog && dialog.open) dialog.close();
+  }
+
+  function dialogDispose(token) {
+    var s = dialogSubs[token];
+    if (s) {
+      s.el.removeEventListener('cancel', s.cancel);
+      s.el.removeEventListener('click', s.click);
+      delete dialogSubs[token];
+    }
+  }
+
   // Flip the document theme (data-theme on <html>), for the demo toggle.
   function toggleTheme() {
     var e = document.documentElement;
     e.setAttribute('data-theme', e.getAttribute('data-theme') === 'dark' ? 'light' : 'dark');
   }
 
-  window.FreedayBlazor = { initAll: initAll, on: on, off: off, toast: toast, toggleTheme: toggleTheme };
+  window.FreedayBlazor = {
+    initAll: initAll, on: on, off: off, onOutside: onOutside, toast: toast, toggleTheme: toggleTheme,
+    comboSetValue: comboSetValue, dateRangeOn: dateRangeOn, chartUpdate: chartUpdate,
+    dialogInit: dialogInit, dialogShow: dialogShow, dialogClose: dialogClose, dialogDispose: dialogDispose,
+  };
 })();

package/dist/freeday-select.js

@@ -91,7 +91,11 @@
       setHighlight(-1);
       if (openClose === close) openClose = null;
     }
-    function choose(opt) {
+    // Mark an option selected + reflect it in the button. `silent` skips the change
+    // event, close, and focus — used by the programmatic setValue() below so a host
+    // (e.g. a Blazor/framework wrapper) can push a value in without echoing an event
+    // back to itself or stealing focus. User-driven picks go through choose() (loud).
+    function select(opt, silent) {
       options.forEach(function (other) {
         var on = other === opt;
         other.setAttribute('aria-selected', on ? 'true' : 'false');
@@ -101,12 +105,24 @@
       root.setAttribute('data-value', opt.getAttribute('data-value') || '');
       valueEl.textContent = optionLabel(opt);
       valueEl.classList.remove('fdy-combo__value--placeholder');
-      root.dispatchEvent(new CustomEvent('fdy-change', {
-        bubbles: true,
-        detail: { value: opt.getAttribute('data-value') }
-      }));
-      close();
-      button.focus();
+      if (!silent) {
+        root.dispatchEvent(new CustomEvent('fdy-change', {
+          bubbles: true,
+          detail: { value: opt.getAttribute('data-value') }
+        }));
+        close();
+        button.focus();
+      }
+    }
+    function choose(opt) { select(opt, false); }
+    // Programmatic set (no event, no focus change). No-op if no option matches.
+    function setValue(value) {
+      for (var i = 0; i < options.length; i++) {
+        if ((options[i].getAttribute('data-value') || '') === String(value)) {
+          select(options[i], true);
+          return;
+        }
+      }
     }
 
     button.addEventListener('click', function () {
@@ -167,6 +183,9 @@
     root.addEventListener('focusout', function (e) {
       if (!root.contains(e.relatedTarget)) close();
     });
+
+    // Per-instance API for programmatic control (host wrappers / two-way binding).
+    root._fdyCombo = { setValue: setValue };
   }
 
   function initAll(context) {
@@ -190,5 +209,10 @@
     initAll();
   }
 
-  window.FreedayCombo = { init: initCombo, initAll: initAll };
+  // Programmatic set on an already-initialised combo root (no fdy-change dispatched).
+  function setValue(root, value) {
+    if (root && root._fdyCombo) root._fdyCombo.setValue(value);
+  }
+
+  window.FreedayCombo = { init: initCombo, initAll: initAll, setValue: setValue };
 })();

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 {