@cahyo-dimas/freeday 1.15.0 → 1.17.0

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>

package/adapters/blazor/FdyCombo.razor.cs

@@ -0,0 +1,86 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyCombo<TValue>
+{
+    /// <summary>The selected value. Two-way bindable via <c>@bind-Value</c>.</summary>
+    [Parameter, EditorRequired] public TValue Value { get; set; } = default!;
+    [Parameter] public EventCallback<TValue> ValueChanged { get; set; }
+
+    /// <summary>The options to choose from.</summary>
+    [Parameter, EditorRequired] public IReadOnlyList<FdyComboOption<TValue>> Options { get; set; }
+        = Array.Empty<FdyComboOption<TValue>>();
+
+    /// <summary>Shown when no option matches the current value.</summary>
+    [Parameter] public string? Placeholder { get; set; }
+
+    /// <summary>Id of the element labelling the combobox (for accessibility).</summary>
+    [Parameter] public string? AriaLabelledby { get; set; }
+
+    /// <summary>Explicit id for the combobox button (else an auto id is used).</summary>
+    [Parameter] public string? Id { get; set; }
+
+    [Parameter] public bool Disabled { get; set; }
+
+    /// <summary>Locked/view mode: stays focusable and shows its value but can't be opened or changed.</summary>
+    [Parameter] public bool Readonly { get; set; }
+
+    [Parameter] public bool Invalid { get; set; }
+
+    private readonly string _autoId = $"fdy-combo-{Guid.NewGuid():N}";
+    private TValue _lastValue = default!;
+    private bool _ready;
+
+    // The enhancer owns this combo's DOM after hydration (open/close, aria-selected, the button
+    // label). Re-rendering here would fight it — e.g. reconciling the listbox mid-close leaves it
+    // stuck open. Render once for the initial markup, then never again; push external Value changes
+    // through the enhancer via comboSetValue instead.
+    protected override bool ShouldRender() => !Hydrated;
+
+    private string ButtonId => Id ?? _autoId;
+    private string RootClass => Invalid ? "fdy-combo fdy-combo--error" : "fdy-combo";
+    private FdyComboOption<TValue>? SelectedOption
+        => Options.FirstOrDefault(o => EqualityComparer<TValue>.Default.Equals(o.Value, Value));
+    private string SelectedLabel => SelectedOption?.Label ?? Placeholder ?? string.Empty;
+    private string SelectedKey => KeyOf(Value);
+
+    private static string KeyOf(TValue value) => value?.ToString() ?? string.Empty;
+
+    // The enhancer owns this combo's DOM; init it directly (initAll would skip Root itself).
+    protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayCombo.init", Root);
+
+    protected override async ValueTask OnHydratedAsync()
+    {
+        _lastValue = Value;
+        await SubscribeAsync("fdy-change", nameof(OnFdyChange));
+        _ready = true;
+    }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Push an externally-changed Value onto the enhancer-owned DOM (silent — no fdy-change echo).
+        if (_ready && !EqualityComparer<TValue>.Default.Equals(Value, _lastValue))
+        {
+            _lastValue = Value;
+            await JS.InvokeVoidAsync("FreedayBlazor.comboSetValue", Root, KeyOf(Value));
+        }
+    }
+
+    /// <summary>Invoked by the bridge when the user picks an option (enhancer's fdy-change).</summary>
+    [JSInvokable]
+    public async Task OnFdyChange(ChangeDetail detail)
+    {
+        FdyComboOption<TValue>? match = Options.FirstOrDefault(o => KeyOf(o.Value) == detail.Value);
+        if (match is not null)
+        {
+            _lastValue = match.Value;
+            Value = match.Value;
+            await ValueChanged.InvokeAsync(match.Value);
+        }
+    }
+
+    /// <summary>The detail shape of the enhancer's <c>fdy-change</c> event.</summary>
+    public sealed record ChangeDetail(string Value);
+}

package/adapters/blazor/FdyComboOption.cs

@@ -0,0 +1,7 @@
+namespace Freeday.Blazor;
+
+/// <summary>One selectable option for <see cref="FdyCombo{TValue}"/>.</summary>
+/// <typeparam name="TValue">The bound value type (string, an enum, an int, …).</typeparam>
+/// <param name="Value">The value bound through <c>@bind-Value</c> when this option is picked.</param>
+/// <param name="Label">The visible text.</param>
+public sealed record FdyComboOption<TValue>(TValue Value, string Label);

package/adapters/blazor/FdyDateRange.razor

@@ -0,0 +1,16 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyDateRange>
+
+@* Two linked seed datepickers (freeday-datepicker.js data-fdy-daterange: the end can't precede
+   the start). The daterange sits INSIDE Root so initAll(Root) finds and links it as a descendant.
+   Both children emit fdy-datepicker-change; the bridge's dateRangeOn tags each with its data-role
+   so From/To bind separately. Enhancer-owned DOM → render once (ShouldRender => false). *@
+<div @ref="Root">
+    <div data-fdy-daterange role="group" aria-label="@AriaLabel">
+        <div data-fdy-datepicker data-role="from"
+             data-value="@From" data-placeholder="@FromPlaceholder" data-min="@Min" data-max="@Max"></div>
+        <span class="fdy-daterange__sep">@Separator</span>
+        <div data-fdy-datepicker data-role="to"
+             data-value="@To" data-placeholder="@ToPlaceholder" data-min="@Min" data-max="@Max"></div>
+    </div>
+</div>

package/adapters/blazor/FdyDateRange.razor.cs

@@ -0,0 +1,58 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyDateRange
+{
+    /// <summary>Range start (ISO <c>yyyy-MM-dd</c> or ""). Two-way bindable via <c>@bind-From</c>.</summary>
+    [Parameter] public string? From { get; set; }
+    [Parameter] public EventCallback<string?> FromChanged { get; set; }
+
+    /// <summary>Range end (ISO <c>yyyy-MM-dd</c> or ""). Two-way bindable via <c>@bind-To</c>.</summary>
+    [Parameter] public string? To { get; set; }
+    [Parameter] public EventCallback<string?> ToChanged { get; set; }
+
+    [Parameter] public string? AriaLabel { get; set; }
+    [Parameter] public string? FromPlaceholder { get; set; }
+    [Parameter] public string? ToPlaceholder { get; set; }
+    [Parameter] public string? Min { get; set; }
+    [Parameter] public string? Max { get; set; }
+    [Parameter] public string Separator { get; set; } = "–";
+
+    private int _token;
+
+    // initAll(Root) links the daterange (descendant) and inits both child pickers.
+    protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayDatepicker.initAll", Root);
+
+    protected override async ValueTask OnHydratedAsync()
+        => _token = await JS.InvokeAsync<int>("FreedayBlazor.dateRangeOn", Root, Self, nameof(OnChange));
+
+    protected override bool ShouldRender() => !Hydrated;
+
+    /// <summary>Invoked by the bridge for either child's change; routes by data-role.</summary>
+    [JSInvokable]
+    public async Task OnChange(RangeDetail detail)
+    {
+        if (detail.Role == "from")
+        {
+            From = detail.Value;
+            await FromChanged.InvokeAsync(detail.Value);
+        }
+        else if (detail.Role == "to")
+        {
+            To = detail.Value;
+            await ToChanged.InvokeAsync(detail.Value);
+        }
+    }
+
+    protected override async ValueTask CleanupAsync()
+    {
+        if (_token != 0)
+        {
+            await JS.InvokeVoidAsync("FreedayBlazor.off", _token);
+        }
+    }
+
+    public sealed record RangeDetail(string? Value, string? Role);
+}

package/adapters/blazor/FdyDatepicker.razor

@@ -0,0 +1,13 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyDatepicker>
+
+@* Seed-based wrapper over freeday-datepicker.js: the enhancer builds the input-styled
+   trigger + calendar popover from this empty div and emits fdy-datepicker-change. The
+   enhancer owns that DOM, so we render the seed once (ShouldRender => false) and read the
+   picked value back through @bind-Value. Value is an ISO date string ("yyyy-MM-dd") or "". *@
+<div @ref="Root" data-fdy-datepicker
+     data-value="@Value"
+     data-label="@Label"
+     data-placeholder="@Placeholder"
+     data-min="@Min"
+     data-max="@Max"></div>

package/adapters/blazor/FdyDatepicker.razor.cs

@@ -0,0 +1,39 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyDatepicker
+{
+    /// <summary>Selected date as an ISO string (<c>yyyy-MM-dd</c>), or "" when unset.
+    /// Two-way bindable via <c>@bind-Value</c>.</summary>
+    [Parameter] public string? Value { get; set; }
+    [Parameter] public EventCallback<string?> ValueChanged { get; set; }
+
+    /// <summary>Accessible label for the trigger.</summary>
+    [Parameter] public string? Label { get; set; }
+    [Parameter] public string? Placeholder { get; set; }
+
+    /// <summary>Earliest selectable date (ISO <c>yyyy-MM-dd</c>); days before it are disabled.</summary>
+    [Parameter] public string? Min { get; set; }
+    [Parameter] public string? Max { get; set; }
+
+    protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayDatepicker.init", Root);
+
+    protected override async ValueTask OnHydratedAsync()
+        => await SubscribeAsync("fdy-datepicker-change", nameof(OnChange));
+
+    // The enhancer owns the built trigger + calendar; never let Blazor re-render the seed.
+    protected override bool ShouldRender() => !Hydrated;
+
+    /// <summary>Invoked by the bridge when the user picks (or clears) a date.</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-datepicker-change</c> event.</summary>
+    public sealed record ChangeDetail(string? Value, string? Date);
+}

package/adapters/blazor/FdyDrawer.razor

@@ -0,0 +1,36 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyDrawer>
+
+@* Controlled wrapper over freeday's .fdy-drawer native <dialog> side panel. Same contract and
+   bridge as FdyModal (open/close + Esc/backdrop route through freeday-blazor.js) applied to a
+   panel that anchors left (default) or right. Native <dialog> gives the focus trap, focus
+   restore, top-layer stacking and inert background for free. *@
+<dialog @ref="Root" class="@DrawerClass" aria-labelledby="@_titleId">
+    <div class="fdy-drawer__header">
+        <h3 id="@_titleId" class="fdy-drawer__title">
+            @if (TitleContent is not null)
+            {
+                @TitleContent
+            }
+            else
+            {
+                @Title
+            }
+        </h3>
+        @if (Dismissible)
+        {
+            <button class="fdy-drawer__close" type="button" aria-label="@CloseLabel" @onclick="DismissAsync">&times;</button>
+        }
+    </div>
+
+    <div class="fdy-drawer__body">
+        @ChildContent
+    </div>
+
+    @if (FooterContent is not null)
+    {
+        <div class="fdy-drawer__footer">
+            @FooterContent
+        </div>
+    }
+</dialog>

package/adapters/blazor/FdyDrawer.razor.cs

@@ -0,0 +1,88 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyDrawer
+{
+    /// <summary>Whether the drawer is open. Two-way bindable via <c>@bind-Open</c>.</summary>
+    [Parameter] public bool Open { get; set; }
+    [Parameter] public EventCallback<bool> OpenChanged { get; set; }
+
+    /// <summary>Plain-text title; ignored when <see cref="TitleContent"/> is supplied.</summary>
+    [Parameter] public string Title { get; set; } = string.Empty;
+    [Parameter] public RenderFragment? TitleContent { get; set; }
+
+    /// <summary>The drawer body.</summary>
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+
+    /// <summary>Optional footer (action buttons). Omitted entirely when null.</summary>
+    [Parameter] public RenderFragment? FooterContent { get; set; }
+
+    /// <summary>Which edge the panel anchors to: <c>left</c> (default) or <c>right</c>.</summary>
+    [Parameter] public string Side { get; set; } = "left";
+
+    /// <summary>When true (default), Esc and a backdrop click dismiss the drawer and a close
+    /// button is shown. Set false for a panel the user must resolve via an explicit action.</summary>
+    [Parameter] public bool Dismissible { get; set; } = true;
+
+    [Parameter] public string CloseLabel { get; set; } = "Close";
+
+    /// <summary>Raised after any dismissal (close button, Esc, or backdrop).</summary>
+    [Parameter] public EventCallback OnClose { get; set; }
+
+    private readonly string _titleId = $"fdy-drawer-{Guid.NewGuid():N}-title";
+    private int _dialogToken;
+    private bool _lastOpen;
+
+    private string DrawerClass => Side == "right" ? "fdy-drawer fdy-drawer--right" : "fdy-drawer";
+
+    protected override async ValueTask HydrateAsync()
+    {
+        _dialogToken = await JS.InvokeAsync<int>(
+            "FreedayBlazor.dialogInit", Root, Self, nameof(OnDismiss), Dismissible);
+        await SyncAsync();
+    }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Only reconcile once the dialog is wired (token != 0) and the open state actually changed.
+        if (_dialogToken != 0 && Open != _lastOpen)
+        {
+            await SyncAsync();
+        }
+    }
+
+    private async ValueTask SyncAsync()
+    {
+        _lastOpen = Open;
+        await JS.InvokeVoidAsync(Open ? "FreedayBlazor.dialogShow" : "FreedayBlazor.dialogClose", Root);
+    }
+
+    /// <summary>Invoked by the bridge when the user dismisses via Esc or a backdrop click.</summary>
+    [JSInvokable]
+    public Task OnDismiss() => DismissAsync();
+
+    private async Task DismissAsync()
+    {
+        if (OpenChanged.HasDelegate)
+        {
+            await OpenChanged.InvokeAsync(false);
+        }
+        else
+        {
+            Open = false;
+            _lastOpen = false;
+            await JS.InvokeVoidAsync("FreedayBlazor.dialogClose", Root);
+        }
+        await OnClose.InvokeAsync();
+    }
+
+    protected override async ValueTask CleanupAsync()
+    {
+        if (_dialogToken != 0)
+        {
+            await JS.InvokeVoidAsync("FreedayBlazor.dialogDispose", _dialogToken);
+        }
+    }
+}

package/adapters/blazor/FdyModal.razor

@@ -0,0 +1,36 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyModal>
+
+@* Controlled wrapper over freeday's .fdy-modal native <dialog>. Blazor can't call
+   showModal()/close() from C#, so open/close + Esc/backdrop dismissal route through the
+   freeday-blazor.js bridge. Native <dialog> gives the focus trap, focus restore, top-layer
+   stacking and inert background for free — this only reconciles it with Blazor state. *@
+<dialog @ref="Root" class="@ModalClass" aria-labelledby="@_titleId">
+    <div class="fdy-modal__header">
+        <h3 id="@_titleId" class="fdy-modal__title">
+            @if (TitleContent is not null)
+            {
+                @TitleContent
+            }
+            else
+            {
+                @Title
+            }
+        </h3>
+        @if (Dismissible)
+        {
+            <button class="fdy-modal__close" type="button" aria-label="@CloseLabel" @onclick="DismissAsync">&times;</button>
+        }
+    </div>
+
+    <div class="fdy-modal__body">
+        @ChildContent
+    </div>
+
+    @if (FooterContent is not null)
+    {
+        <div class="fdy-modal__footer">
+            @FooterContent
+        </div>
+    }
+</dialog>

package/adapters/blazor/FdyModal.razor.cs

@@ -0,0 +1,88 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyModal
+{
+    /// <summary>Whether the dialog is open. Two-way bindable via <c>@bind-Open</c>.</summary>
+    [Parameter] public bool Open { get; set; }
+    [Parameter] public EventCallback<bool> OpenChanged { get; set; }
+
+    /// <summary>Plain-text title; ignored when <see cref="TitleContent"/> is supplied.</summary>
+    [Parameter] public string Title { get; set; } = string.Empty;
+    [Parameter] public RenderFragment? TitleContent { get; set; }
+
+    /// <summary>The dialog body.</summary>
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+
+    /// <summary>Optional footer (action buttons). Omitted entirely when null.</summary>
+    [Parameter] public RenderFragment? FooterContent { get; set; }
+
+    /// <summary>Size modifier: <c>sm</c> | <c>md</c> | <c>lg</c> | <c>wide</c>.</summary>
+    [Parameter] public string? Size { get; set; }
+
+    /// <summary>When true (default), Esc and a backdrop click dismiss the dialog and a close
+    /// button is shown. Set false for a modal the user must resolve via an explicit action.</summary>
+    [Parameter] public bool Dismissible { get; set; } = true;
+
+    [Parameter] public string CloseLabel { get; set; } = "Close";
+
+    /// <summary>Raised after any dismissal (close button, Esc, or backdrop).</summary>
+    [Parameter] public EventCallback OnClose { get; set; }
+
+    private readonly string _titleId = $"fdy-modal-{Guid.NewGuid():N}-title";
+    private int _dialogToken;
+    private bool _lastOpen;
+
+    private string ModalClass => Size is null ? "fdy-modal" : $"fdy-modal fdy-modal--{Size}";
+
+    protected override async ValueTask HydrateAsync()
+    {
+        _dialogToken = await JS.InvokeAsync<int>(
+            "FreedayBlazor.dialogInit", Root, Self, nameof(OnDismiss), Dismissible);
+        await SyncAsync();
+    }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Only reconcile once the dialog is wired (token != 0) and the open state actually changed.
+        if (_dialogToken != 0 && Open != _lastOpen)
+        {
+            await SyncAsync();
+        }
+    }
+
+    private async ValueTask SyncAsync()
+    {
+        _lastOpen = Open;
+        await JS.InvokeVoidAsync(Open ? "FreedayBlazor.dialogShow" : "FreedayBlazor.dialogClose", Root);
+    }
+
+    /// <summary>Invoked by the bridge when the user dismisses via Esc or a backdrop click.</summary>
+    [JSInvokable]
+    public Task OnDismiss() => DismissAsync();
+
+    private async Task DismissAsync()
+    {
+        if (OpenChanged.HasDelegate)
+        {
+            await OpenChanged.InvokeAsync(false);
+        }
+        else
+        {
+            Open = false;
+            _lastOpen = false;
+            await JS.InvokeVoidAsync("FreedayBlazor.dialogClose", Root);
+        }
+        await OnClose.InvokeAsync();
+    }
+
+    protected override async ValueTask CleanupAsync()
+    {
+        if (_dialogToken != 0)
+        {
+            await JS.InvokeVoidAsync("FreedayBlazor.dialogDispose", _dialogToken);
+        }
+    }
+}