@cahyo-dimas/freeday 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.16.0] — 2026-08-11
+### Added
+- **Native Blazor component library (`adapters/blazor/`) — first release, 10/10 parity.** A Razor
+  Class Library (`Freeday.Blazor`, net8.0) so Blazor consumers get typed `<FdyX>` components with
+  `@bind`, instead of hand-writing `fdy-*` markup + JS interop. Ten components at parity with the
+  Vue/React adapters: `FdyModal`, `FdyDrawer`, `FdyCombo<TValue>`, `FdyDatepicker`, `FdyAutocomplete`,
+  `FdyCascade`, `FdyDateRange`, `FdyCfl<TRow>`, `FdyChart`, and `FdyTable<TRow>`. Two patterns:
+  *wrapper-over-enhancer* (hydrate the vanilla enhancer once, `ShouldRender() => false` so Blazor
+  never fights the enhancer-owned DOM, push external value imperatively) and *controlled*
+  (`FdyModal`/`FdyDrawer`/`FdyCfl` render their own DOM; only the `<dialog>` show/close/Esc/backdrop
+  go through interop). Shared CRTP base `FreedayComponentBase<TSelf>` types the `DotNetObjectReference`
+  so `[JSInvokable]` dispatch resolves. Consumed via `<ProjectReference>`; the host loads
+  `dist/freeday.js` + `adapters/blazor/freeday-blazor.js` as `<script>`s.
+- **`FdyTable<TRow>`** is a full controlled data table — client mode (sort + four column-filter types
+  + pagination over `Rows`) and server mode (set `Page` → the headers/filters/pager only raise
+  `SortChanged`/`FiltersChanged`/`PageChanged` intent), plus row activation, expandable detail rows,
+  cell templates, and loading/empty states. Its sort/filter/paginate logic is `TableModel` — a pure
+  C# port of `adapters/core/table-model.js`.
+- **`freeday-blazor.js` bridge**: `chartUpdate` (repaint a chart from its data-* attributes) and a
+  generic `onOutside` light-dismiss primitive (outside-pointer / Esc).
+- **`src/freeday-select.js`** gained an additive `setValue` (silent programmatic select) so a Blazor
+  `@bind-Value` can push an external combo value without the enhancer echoing an `fdy-change` back.
+
 ## [1.15.0] — 2026-08-10
 ### Added
 - **Type declarations for every export (#40).** Only `./vue` and `./react` shipped a `types`

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.15.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.15.0)
+[![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)
 
 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`.

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.15.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.15.0)
+[![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)
 
 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`.

package/adapters/blazor/CflTypes.cs

@@ -0,0 +1,11 @@
+namespace Freeday.Blazor;
+
+/// <summary>A column in the <see cref="FdyCfl{TRow}"/> results table.</summary>
+/// <param name="Header">The column heading.</param>
+/// <param name="Cell">Projects a row to the cell's display text.</param>
+public sealed record CflColumn<TRow>(string Header, Func<TRow, string> Cell);
+
+/// <summary>One page of results returned by <see cref="FdyCfl{TRow}"/>'s data source.</summary>
+/// <param name="Rows">The rows in this page.</param>
+/// <param name="HasMore">True if another page can be requested (drives "load more").</param>
+public sealed record CflPage<TRow>(IReadOnlyList<TRow> Rows, bool HasMore);

package/adapters/blazor/FdyAutocomplete.razor

@@ -0,0 +1,19 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyAutocomplete>
+
+@* Typed wrapper over freeday-autocomplete.js (editable combobox). The enhancer filters the
+   option list as the user types and, on pick, fills the input + emits fdy-autocomplete-select
+   with the chosen text. Value is that text. The enhancer owns the input/listbox after
+   hydration (ShouldRender => false); the initial value seeds the input. *@
+<div @ref="Root" data-fdy-autocomplete class="fdy-autocomplete">
+    <input class="fdy-input" role="combobox" aria-expanded="false" aria-autocomplete="list"
+           aria-controls="@_listId" autocomplete="off" value="@Value"
+           placeholder="@Placeholder" aria-label="@AriaLabel" />
+    <ul class="fdy-autocomplete__listbox" id="@_listId" role="listbox" hidden>
+        @foreach (string item in Options)
+        {
+            <li class="fdy-autocomplete__option" role="option">@item</li>
+        }
+        <li class="fdy-autocomplete__empty" hidden>@EmptyText</li>
+    </ul>
+</div>

package/adapters/blazor/FdyAutocomplete.razor.cs

@@ -0,0 +1,40 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyAutocomplete
+{
+    /// <summary>The selected text. Two-way bindable via <c>@bind-Value</c>.</summary>
+    [Parameter] public string? Value { get; set; }
+    [Parameter] public EventCallback<string?> ValueChanged { get; set; }
+
+    /// <summary>The suggestions to filter and choose from (their text is the value).</summary>
+    [Parameter, EditorRequired] public IReadOnlyList<string> Options { get; set; } = Array.Empty<string>();
+
+    [Parameter] public string? Placeholder { get; set; }
+    [Parameter] public string? AriaLabel { get; set; }
+
+    /// <summary>Text shown when no option matches the typed query.</summary>
+    [Parameter] public string EmptyText { get; set; } = "No results";
+
+    private readonly string _listId = $"fdy-ac-{Guid.NewGuid():N}";
+
+    protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayAutocomplete.init", Root);
+
+    protected override async ValueTask OnHydratedAsync()
+        => await SubscribeAsync("fdy-autocomplete-select", nameof(OnSelect));
+
+    protected override bool ShouldRender() => !Hydrated;
+
+    /// <summary>Invoked by the bridge when the user picks a suggestion.</summary>
+    [JSInvokable]
+    public async Task OnSelect(SelectDetail detail)
+    {
+        Value = detail.Value;
+        await ValueChanged.InvokeAsync(detail.Value);
+    }
+
+    /// <summary>The (DOM-safe) detail of the enhancer's <c>fdy-autocomplete-select</c> event.</summary>
+    public sealed record SelectDetail(string? Value);
+}

package/adapters/blazor/FdyCascade.razor

@@ -0,0 +1,33 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyCascade>
+
+@* Typed wrapper over freeday-cascade.js. The enhancer reads the hidden nested <ul> as its data
+   model (a <li> with a child <ul> is a branch; without, a leaf), then REMOVES the source list and
+   builds a drill-down popover. Because it removes/owns that DOM, we render the tree once and never
+   re-render (ShouldRender => false). The chosen leaf value flows back through @bind-Value. *@
+<div @ref="Root" data-fdy-cascade
+     data-label="@Label"
+     data-value="@Value"
+     data-placeholder="@Placeholder"
+     data-separator="@Separator">
+    <ul>
+        @foreach (FdyCascadeNode node in Nodes)
+        {
+            @RenderNode(node)
+        }
+    </ul>
+</div>
+
+@code {
+    // Recursive: each <li> carries its own label text (before any nested <ul>) + data-value; a
+    // nested <ul> makes it a branch. Matches the enhancer's parse(ul) contract.
+    private RenderFragment RenderNode(FdyCascadeNode node) =>@<li data-value="@node.Value">@node.Label@if (node.Children is { Count: > 0 })
+    {
+        <ul>
+            @foreach (FdyCascadeNode child in node.Children)
+            {
+                @RenderNode(child)
+            }
+        </ul>
+    }</li>;
+}

package/adapters/blazor/FdyCascade.razor.cs

@@ -0,0 +1,38 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyCascade
+{
+    /// <summary>The hierarchy to drill through.</summary>
+    [Parameter, EditorRequired] public IReadOnlyList<FdyCascadeNode> Nodes { get; set; } = Array.Empty<FdyCascadeNode>();
+
+    /// <summary>The chosen leaf value. Two-way bindable via <c>@bind-Value</c>.</summary>
+    [Parameter] public string? Value { get; set; }
+    [Parameter] public EventCallback<string?> ValueChanged { get; set; }
+
+    [Parameter] public string? Label { get; set; }
+    [Parameter] public string? Placeholder { get; set; }
+
+    /// <summary>Separator between labels in the displayed path (default " / ").</summary>
+    [Parameter] public string Separator { get; set; } = " / ";
+
+    protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayCascade.init", Root);
+
+    protected override async ValueTask OnHydratedAsync()
+        => await SubscribeAsync("fdy-cascade-change", nameof(OnChange));
+
+    protected override bool ShouldRender() => !Hydrated;
+
+    /// <summary>Invoked by the bridge when the user selects a leaf.</summary>
+    [JSInvokable]
+    public async Task OnChange(ChangeDetail detail)
+    {
+        Value = detail.Value;
+        await ValueChanged.InvokeAsync(detail.Value);
+    }
+
+    /// <summary>The detail shape of the enhancer's <c>fdy-cascade-change</c> event.</summary>
+    public sealed record ChangeDetail(string? Value, string? Path, string[]? Labels);
+}

package/adapters/blazor/FdyCascadeNode.cs

@@ -0,0 +1,8 @@
+namespace Freeday.Blazor;
+
+/// <summary>A node in an <see cref="FdyCascade"/> hierarchy. A node with children is a branch
+/// (drills in); a node without is a leaf (selects, storing the full path as the value).</summary>
+/// <param name="Value">The value stored when this leaf is chosen (branches pass it through their leaves).</param>
+/// <param name="Label">The visible text.</param>
+/// <param name="Children">Child nodes, or null for a leaf.</param>
+public sealed record FdyCascadeNode(string Value, string Label, IReadOnlyList<FdyCascadeNode>? Children = null);

package/adapters/blazor/FdyCfl.razor

@@ -0,0 +1,93 @@
+@namespace Freeday.Blazor
+@typeparam TRow where TRow : class
+@inherits FreedayComponentBase<FdyCfl<TRow>>
+
+@* Controlled *async* choose-from-list. Unlike the enhancer-wrapper components, this is a
+   Blazor-native controlled component (like FdyTable): the read-only field + the .fdy-modal--cfl
+   dialog are rendered and re-rendered by Blazor, rows come from an async LoadPage callback, and
+   the <dialog> is opened/closed through the same freeday-blazor.js interop FdyModal uses. *@
+
+<div class="@FieldGroupClass">
+    <input class="fdy-input" type="text" readonly value="@DisplayValue"
+           placeholder="@Placeholder" aria-labelledby="@AriaLabelledby"
+           aria-invalid="@(Invalid ? "true" : null)" aria-readonly="@(Readonly ? "true" : null)" />
+    <button class="fdy-input-group__btn" type="button" @onclick="OpenAsync"
+            disabled="@(Disabled || Readonly)" aria-label="@SearchPlaceholder">
+        <svg viewBox="0 0 24 24" width="18" height="18" fill="none" stroke="currentColor"
+             stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+            <circle cx="11" cy="11" r="7"></circle><path d="m21 21-4.3-4.3"></path>
+        </svg>
+    </button>
+</div>
+
+<dialog @ref="Root" class="fdy-modal fdy-modal--cfl" aria-labelledby="@_titleId">
+    <div class="fdy-modal__header">
+        <h3 id="@_titleId" class="fdy-modal__title">@Title</h3>
+        <button class="fdy-modal__close" type="button" aria-label="@CloseLabel" @onclick="CloseAsync">&times;</button>
+    </div>
+
+    <div class="fdy-modal__body">
+        <div class="fdy-cfl__search">
+            <input class="fdy-input" type="search" data-fdy-cfl-search
+                   placeholder="@SearchPlaceholder" aria-label="@SearchPlaceholder"
+                   @bind="_query" @bind:event="oninput" @bind:after="OnQueryChangedAsync" />
+        </div>
+
+        <div class="fdy-cfl__results">
+            @if (IsInitialLoading)
+            {
+                <p class="fdy-cfl__empty" role="status">@LoadingText</p>
+            }
+            else if (IsBlockingError)
+            {
+                <div class="fdy-cfl__empty" role="alert">
+                    <span>@(_error ?? ErrorText)</span>
+                    <button class="fdy-btn fdy-btn--sm" type="button" @onclick="RetryAsync">@RetryText</button>
+                </div>
+            }
+            else if (IsEmpty)
+            {
+                <p class="fdy-cfl__empty">@EmptyText</p>
+            }
+            else
+            {
+                <table class="fdy-table" aria-label="@Title">
+                    <thead>
+                        <tr>
+                            @foreach (CflColumn<TRow> col in Columns)
+                            {
+                                <th scope="col">@col.Header</th>
+                            }
+                        </tr>
+                    </thead>
+                    <tbody>
+                        @foreach (TRow row in _rows)
+                        {
+                            <tr class="fdy-cfl__row" tabindex="0" @key="RowKey(row)" @onclick="() => ChooseAsync(row)">
+                                @foreach (CflColumn<TRow> col in Columns)
+                                {
+                                    <td>@col.Cell(row)</td>
+                                }
+                            </tr>
+                        }
+                    </tbody>
+                </table>
+
+                @if (_error is not null)
+                {
+                    <div class="fdy-cfl__empty" role="alert" style="padding:var(--space-4) var(--space-5)">
+                        <span>@_error</span>
+                        <button class="fdy-btn fdy-btn--sm" type="button" @onclick="RetryAsync">@RetryText</button>
+                    </div>
+                }
+                @if (_hasMore)
+                {
+                    <div class="fdy-cfl__actions">
+                        <button class="fdy-btn fdy-btn--ghost fdy-btn--sm" type="button"
+                                disabled="@_loading" @onclick="LoadMoreAsync">@MoreText</button>
+                    </div>
+                }
+            }
+        </div>
+    </div>
+</dialog>

package/adapters/blazor/FdyCfl.razor.cs

@@ -0,0 +1,146 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyCfl<TRow>
+{
+    /// <summary>The picked row (or null). Two-way bindable via <c>@bind-Value</c>.</summary>
+    [Parameter] public TRow? Value { get; set; }
+    [Parameter] public EventCallback<TRow?> ValueChanged { get; set; }
+
+    /// <summary>Async data source: <c>(query, page) =&gt; a page of rows</c>. The caller owns paging
+    /// and server-side search; page 0 is the first page.</summary>
+    [Parameter, EditorRequired] public Func<string, int, Task<CflPage<TRow>>> LoadPage { get; set; } = default!;
+
+    /// <summary>Result table columns.</summary>
+    [Parameter, EditorRequired] public IReadOnlyList<CflColumn<TRow>> Columns { get; set; } = Array.Empty<CflColumn<TRow>>();
+
+    /// <summary>Projects the picked row to the text shown in the read-only field.</summary>
+    [Parameter, EditorRequired] public Func<TRow, string> Display { get; set; } = default!;
+
+    /// <summary>A stable key per row (for diffing).</summary>
+    [Parameter, EditorRequired] public Func<TRow, string> RowKey { get; set; } = default!;
+
+    [Parameter] public string Title { get; set; } = "Choose data";
+    [Parameter] public string? Placeholder { get; set; }
+    [Parameter] public string SearchPlaceholder { get; set; } = "Search…";
+    [Parameter] public string LoadingText { get; set; } = "Loading…";
+    [Parameter] public string EmptyText { get; set; } = "No results.";
+    [Parameter] public string ErrorText { get; set; } = "Failed to load.";
+    [Parameter] public string RetryText { get; set; } = "Try again";
+    [Parameter] public string MoreText { get; set; } = "Load more";
+    [Parameter] public string CloseLabel { get; set; } = "Close";
+
+    [Parameter] public bool Disabled { get; set; }
+
+    /// <summary>Locked/view mode: shows the value but the search dialog can't be opened.</summary>
+    [Parameter] public bool Readonly { get; set; }
+    [Parameter] public bool Invalid { get; set; }
+    [Parameter] public string? AriaLabelledby { get; set; }
+
+    /// <summary>Debounce (ms) between a keystroke and the search request.</summary>
+    [Parameter] public int SearchDebounceMs { get; set; } = 250;
+
+    private readonly string _titleId = $"fdy-cfl-{Guid.NewGuid():N}-title";
+    private int _dialogToken;
+    private bool _open;
+    private string _query = string.Empty;
+    private readonly List<TRow> _rows = new();
+    private int _page;
+    private bool _hasMore;
+    private bool _loading;
+    private string? _error;
+    private int _reqSeq;      // out-of-order response guard
+    private int _debounceSeq; // supersedes stale debounced searches
+
+    private string DisplayValue => Value is null ? string.Empty : Display(Value);
+    private string FieldGroupClass => Invalid ? "fdy-input-group fdy-input-group--error" : "fdy-input-group";
+    private bool IsInitialLoading => _loading && _rows.Count == 0;
+    private bool IsBlockingError => _error is not null && _rows.Count == 0;
+    private bool IsEmpty => !_loading && _error is null && _rows.Count == 0;
+
+    // The dialog content is Blazor-rendered (so no ShouldRender override); only its show/close +
+    // Esc/backdrop dismissal go through interop.
+    protected override async ValueTask HydrateAsync()
+        => _dialogToken = await JS.InvokeAsync<int>("FreedayBlazor.dialogInit", Root, Self, nameof(OnDismiss), true);
+
+    private async Task OpenAsync()
+    {
+        if (Disabled || Readonly || _open) return;
+        _open = true;
+        _query = string.Empty;
+        await JS.InvokeVoidAsync("FreedayBlazor.dialogShow", Root);
+        await LoadAsync(reset: true);
+    }
+
+    private async Task CloseAsync()
+    {
+        if (!_open) return;
+        _open = false;
+        await JS.InvokeVoidAsync("FreedayBlazor.dialogClose", Root);
+    }
+
+    /// <summary>Invoked by the bridge on Esc / backdrop dismiss.</summary>
+    [JSInvokable]
+    public Task OnDismiss() => CloseAsync();
+
+    private async Task OnQueryChangedAsync()
+    {
+        int seq = ++_debounceSeq;
+        if (SearchDebounceMs > 0)
+        {
+            await Task.Delay(SearchDebounceMs);
+            if (seq != _debounceSeq) return; // a newer keystroke superseded this one
+        }
+        await LoadAsync(reset: true);
+    }
+
+    private async Task LoadAsync(bool reset)
+    {
+        _loading = true;
+        _error = null;
+        StateHasChanged();
+        int seq = ++_reqSeq;
+        try
+        {
+            CflPage<TRow> result = await LoadPage(_query, reset ? 0 : _page);
+            if (seq != _reqSeq) return; // a newer request superseded this response
+            if (reset) _rows.Clear();
+            _rows.AddRange(result.Rows);
+            _hasMore = result.HasMore;
+            _page = reset ? 1 : _page + 1;
+        }
+        catch (Exception ex)
+        {
+            if (seq == _reqSeq) _error = string.IsNullOrEmpty(ex.Message) ? ErrorText : ex.Message;
+        }
+        finally
+        {
+            if (seq == _reqSeq)
+            {
+                _loading = false;
+                StateHasChanged();
+            }
+        }
+    }
+
+    private Task LoadMoreAsync() => _hasMore && !_loading ? LoadAsync(reset: false) : Task.CompletedTask;
+
+    private Task RetryAsync() => LoadAsync(reset: true);
+
+    private async Task ChooseAsync(TRow row)
+    {
+        Value = row;
+        await ValueChanged.InvokeAsync(row);
+        await CloseAsync();
+    }
+
+    protected override async ValueTask CleanupAsync()
+    {
+        if (_dialogToken != 0)
+        {
+            await JS.InvokeVoidAsync("FreedayBlazor.dialogDispose", _dialogToken);
+        }
+    }
+}

package/adapters/blazor/FdyChart.razor

@@ -0,0 +1,25 @@
+@namespace Freeday.Blazor
+
+@* A thin Blazor wrapper over freeday's zero-dependency chart renderer (freeday-chart.js). Charts
+   are not form controls, so re-implementing the SVG maths in C# would only duplicate them. Instead
+   Blazor owns the outer <div> and its data-* attributes; after every render this calls
+   FreedayChart.update() (via the bridge) to repaint the SVG from those attributes — giving reactive,
+   typed charts with no external dependency. Because the renderer paints with CSS var()/--chart-*
+   tokens, charts also recolour on data-theme change for free. Requires dist/freeday.js loaded so
+   window.FreedayChart exists; until then the slotted fallback content stays visible. *@
+<div @ref="Root"
+     class="@RootClass"
+     data-fdy-chart="@Type"
+     data-series="@SeriesAttr"
+     data-values="@ValuesAttr"
+     data-labels="@LabelsAttr"
+     data-fdy-format="@Format"
+     data-fdy-stacked="@StackedAttr"
+     data-fdy-legend="@Legend"
+     data-fdy-colors="@ColorsAttr"
+     data-fdy-color="@Color"
+     data-fdy-center="@Center"
+     role="img"
+     aria-label="@AriaLabel">
+    @ChildContent
+</div>

package/adapters/blazor/FdyChart.razor.cs

@@ -0,0 +1,90 @@
+using System.Globalization;
+using System.Text.Json;
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+// Not a FreedayComponentBase: a chart has no fdy-* events and no <dialog>, and must repaint on
+// EVERY data change (not hydrate-once), so it drives its own render lifecycle directly.
+public partial class FdyChart : ComponentBase
+{
+    [Inject] private IJSRuntime JS { get; set; } = default!;
+
+    /// <summary>Chart kind: <c>line</c> | <c>area</c> | <c>bar</c> | <c>sparkline</c> | <c>donut</c>.</summary>
+    [Parameter, EditorRequired] public string Type { get; set; } = default!;
+
+    /// <summary>Multi-series data (line/area/bar). Takes precedence over <see cref="Values"/>.</summary>
+    [Parameter] public IReadOnlyList<FdyChartSeries>? Series { get; set; }
+
+    /// <summary>Single-series shortcut (sparkline/donut/simple bar).</summary>
+    [Parameter] public IReadOnlyList<double>? Values { get; set; }
+
+    /// <summary>Category axis labels.</summary>
+    [Parameter] public IReadOnlyList<string>? Labels { get; set; }
+
+    /// <summary>Value format: <c>number</c> | <c>percent</c> | <c>currency</c>.</summary>
+    [Parameter] public string? Format { get; set; }
+
+    /// <summary>Stack the series (bar/area). Switches a bar chart into cartesian layout.</summary>
+    [Parameter] public bool Stacked { get; set; }
+
+    /// <summary>Legend visibility: <c>auto</c> | <c>always</c> | <c>none</c>.</summary>
+    [Parameter] public string? Legend { get; set; }
+
+    /// <summary>Per-series colour override — semantic token names (primary/accent/success/…) or
+    /// categorical slots <c>chart-1</c>..<c>chart-8</c>. Omit for the default chart palette.</summary>
+    [Parameter] public IReadOnlyList<string>? Colors { get; set; }
+
+    /// <summary>Single-colour override for a one-series chart.</summary>
+    [Parameter] public string? Color { get; set; }
+
+    /// <summary>Donut centre label.</summary>
+    [Parameter] public string? Center { get; set; }
+
+    [Parameter] public string? AriaLabel { get; set; }
+
+    /// <summary>Fallback content shown until the renderer paints (e.g. before dist/freeday.js loads).</summary>
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+
+    /// <summary>The chart root; Blazor owns its attributes, the renderer paints its SVG children.</summary>
+    protected ElementReference Root;
+
+    private static readonly JsonSerializerOptions SeriesJson = new() { DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull };
+
+    // Cartesian (axes) for line/area, or a bar with multiple series / stacking; those get their
+    // layout class from the renderer. sparkline/donut/simple-bar need their layout class up front.
+    private bool IsCartesian =>
+        Type == "line" || Type == "area" || (Type == "bar" && (Series is not null || Stacked));
+
+    private string RootClass => Type switch
+    {
+        "sparkline" => "fdy-sparkline",
+        "donut" => "fdy-donut",
+        "bar" when !IsCartesian => "fdy-bars",
+        _ => string.Empty,
+    };
+
+    // null → Blazor omits the attribute entirely (the renderer then falls back correctly).
+    private string? SeriesAttr => Series is null ? null : JsonSerializer.Serialize(Series, SeriesJson);
+    private string? ValuesAttr => Values is null ? null : string.Join(",", Values.Select(v => v.ToString(CultureInfo.InvariantCulture)));
+    private string? LabelsAttr => Labels is null ? null : string.Join(",", Labels);
+    private string? ColorsAttr => Colors is null ? null : string.Join(",", Colors);
+    private string? StackedAttr => Stacked ? string.Empty : null; // presence attribute
+
+    // Signature of every data-affecting attribute — the C# analogue of the Vue/React watch list.
+    private string DataSignature => string.Join("
", Type, SeriesAttr, ValuesAttr, LabelsAttr,
+        Format, StackedAttr, Legend, ColorsAttr, Color, Center);
+
+    private string? _lastSignature;
+
+    // Repaint only when the chart's own data changed (first render, or a data-* attribute differs
+    // since the last paint) — so an unrelated parent re-render doesn't needlessly repaint the SVG.
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        string sig = DataSignature;
+        if (!firstRender && sig == _lastSignature) return;
+        _lastSignature = sig;
+        await JS.InvokeVoidAsync("FreedayBlazor.chartUpdate", Root);
+    }
+}

package/adapters/blazor/FdyChartSeries.cs

@@ -0,0 +1,10 @@
+using System.Text.Json.Serialization;
+
+namespace Freeday.Blazor;
+
+/// <summary>One data series in a multi-series chart (line/area/bar). Serialised to the renderer's
+/// <c>data-series</c> JSON shape <c>{ label, values, role? }</c> — hence the camelCase names.</summary>
+public sealed record FdyChartSeries(
+    [property: JsonPropertyName("label")] string Label,
+    [property: JsonPropertyName("values")] IReadOnlyList<double> Values,
+    [property: JsonPropertyName("role")] string? Role = null);

package/adapters/blazor/FdyCombo.razor

@@ -0,0 +1,28 @@
+@namespace Freeday.Blazor
+@typeparam TValue
+@inherits FreedayComponentBase<FdyCombo<TValue>>
+
+@* Typed wrapper over freeday's .fdy-combo (WAI-ARIA select-only combobox). Blazor renders the
+   markup the freeday-select.js enhancer expects; the enhancer owns the open/keyboard/focus
+   behaviour and emits fdy-change, which flows back to @bind-Value. An externally-changed Value
+   is pushed onto the enhancer silently (no event echo). *@
+<div @ref="Root" class="@RootClass" data-fdy-combo data-value="@SelectedKey">
+    <button id="@ButtonId" type="button" class="fdy-combo__button" role="combobox"
+            aria-haspopup="listbox" aria-expanded="false"
+            aria-labelledby="@AriaLabelledby"
+            aria-invalid="@(Invalid ? "true" : null)"
+            aria-readonly="@(Readonly ? "true" : null)"
+            disabled="@Disabled">
+        <span class="fdy-combo__value@(SelectedOption is null ? " fdy-combo__value--placeholder" : "")">@SelectedLabel</span>
+    </button>
+    <ul class="fdy-combo__listbox" role="listbox" aria-labelledby="@AriaLabelledby" hidden>
+        @foreach (FdyComboOption<TValue> opt in Options)
+        {
+            bool selected = Equals(opt.Value, Value);
+            <li class="fdy-combo__option" role="option" data-value="@KeyOf(opt.Value)"
+                aria-selected="@(selected ? "true" : "false")">
+                <span class="fdy-combo__check">@(selected ? "✓" : "")</span>@opt.Label
+            </li>
+        }
+    </ul>
+</div>