@cahyo-dimas/freeday 1.15.0 → 1.17.0

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 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
+  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.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.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.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/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>