@cahyo-dimas/freeday 2.1.0 → 3.0.0

package/adapters/blazor/FdyAppShell.razor.cs

@@ -43,8 +43,20 @@ public partial class FdyAppShell
 
     [Parameter] public string ToggleLabel { get; set; } = "Toggle navigation";
 
+    /// <summary>
+    /// How a VISIBLE nav sits on a wide viewport: <see cref="FdyNavMode.Push"/> (default) makes it
+    /// a column that displaces the content, <see cref="FdyNavMode.Overlay"/> floats it over the page
+    /// with a backdrop. Below the nav breakpoint it is ignored — the nav is off-canvas there by
+    /// definition, so there is nothing to choose.
+    /// </summary>
+    [Parameter] public FdyNavMode NavMode { get; set; } = FdyNavMode.Push;
+
+    private string ShellClass =>
+        NavMode == FdyNavMode.Overlay ? "fdy-app fdy-app--nav-overlay" : "fdy-app";
+
     private int _navToken;
     private bool? _lastNavOpen;
+    private FdyNavMode _lastNavMode = FdyNavMode.Push;
 
     protected override async ValueTask HydrateAsync()
     {
@@ -77,6 +89,15 @@ public partial class FdyAppShell
             _lastNavOpen = wanted;
             await JS.InvokeVoidAsync("FreedayAppShell.setVisible", Root, wanted);
         }
+
+        // Switching the mode moves the answer to "is the nav visible?" from one state class to the
+        // other, so `inert` and `aria-expanded` describe the old arrangement until the shell re-reads
+        // the DOM. Blazor has rendered the new class by now; this tells the enhancer to look again.
+        if (_navToken != 0 && NavMode != _lastNavMode)
+        {
+            _lastNavMode = NavMode;
+            await JS.InvokeVoidAsync("FreedayAppShell.refresh", Root);
+        }
     }
 
     /// <summary>Invoked by the bridge when the shell's nav visibility changes for any reason,
@@ -112,3 +133,17 @@ public partial class FdyAppShell
 
     public sealed record NavDetail(bool Visible);
 }
+
+/// <summary>
+/// How a visible nav sits on a wide viewport. The JS adapters take the same idea as the string
+/// union <c>'push' | 'overlay'</c>; C# gets an enum, for the same reason the column filter type is
+/// one — a typo in a string reaches the renderer, a typo in an enum member does not compile.
+/// </summary>
+public enum FdyNavMode
+{
+    /// <summary>A column that displaces the content (the default, and what every 2.x shell did).</summary>
+    Push,
+
+    /// <summary>Floats over the page with a backdrop, the way it already behaves on a narrow one.</summary>
+    Overlay,
+}

package/adapters/blazor/FdyAutocomplete.razor

@@ -8,7 +8,10 @@
 <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" />
+           placeholder="@Placeholder" aria-label="@AriaLabel"
+           id="@Id" aria-labelledby="@AriaLabelledby" aria-describedby="@Describedby"
+           disabled="@Disabled" readonly="@Readonly"
+           aria-invalid="@(Invalid ? "true" : null)" />
     <ul class="fdy-autocomplete__listbox" id="@_listId" role="listbox" hidden>
         @foreach (string item in Options)
         {

package/adapters/blazor/FdyAutocomplete.razor.cs

@@ -25,8 +25,34 @@ public partial class FdyAutocomplete
     protected override async ValueTask OnHydratedAsync()
         => await SubscribeAsync("fdy-autocomplete-select", nameof(OnSelect));
 
+    /// <summary>Explicit id for the input.</summary>
+    [Parameter] public string? Id { get; set; }
+
+    /// <summary>Id of the element that labels the input, when a visible label does the naming.</summary>
+    [Parameter] public string? AriaLabelledby { get; set; }
+
+    /// <summary>Id of the help or error text the input describes itself with.</summary>
+    [Parameter] public string? Describedby { get; set; }
+
+    /// <summary>Greyed and out of the tab order.</summary>
+    [Parameter] public bool Disabled { get; set; }
+
+    /// <summary>Locked/view mode: focusable and showing its value, not editable, and the
+    /// suggestion list will not open.</summary>
+    [Parameter] public bool Readonly { get; set; }
+
+    /// <summary>Marks the field invalid (<c>aria-invalid</c>).</summary>
+    [Parameter] public bool Invalid { get; set; }
+
     protected override bool ShouldRender() => !Hydrated;
 
+    protected override async Task OnParametersSetAsync()
+    {
+        if (!Hydrated) return;
+        await JS.InvokeVoidAsync("FreedayAutocomplete.setState", Root,
+            new { disabled = Disabled, @readonly = Readonly, invalid = Invalid });
+    }
+
     /// <summary>Invoked by the bridge when the user picks a suggestion.</summary>
     [JSInvokable]
     public async Task OnSelect(SelectDetail detail)

package/adapters/blazor/FdyCascade.razor

@@ -11,7 +11,12 @@
      data-placeholder="@Placeholder"
      data-separator="@Separator"
      data-fdy-text-back="@BackLabel"
-     data-fdy-text-submenu="@SubmenuLabel">
+     data-fdy-text-submenu="@SubmenuLabel"
+     data-id="@Id"
+     data-describedby="@Describedby"
+     data-disabled="@(Disabled ? "true" : null)"
+     data-readonly="@(Readonly ? "true" : null)"
+     data-invalid="@(Invalid ? "true" : null)">
     <ul>
         @foreach (FdyCascadeNode node in Nodes)
         {

package/adapters/blazor/FdyCascade.razor.cs

@@ -31,8 +31,32 @@ public partial class FdyCascade
     protected override async ValueTask OnHydratedAsync()
         => await SubscribeAsync("fdy-cascade-change", nameof(OnChange));
 
+    /// <summary>Id for the trigger the enhancer builds, so a form's label can point at it.</summary>
+    [Parameter] public string? Id { get; set; }
+
+    /// <summary>Id of the help or error text the trigger describes itself with.</summary>
+    [Parameter] public string? Describedby { get; set; }
+
+    /// <summary>Greyed and out of the tab order.</summary>
+    [Parameter] public bool Disabled { get; set; }
+
+    /// <summary>Locked/view mode: focusable and showing its value, but it will not open.</summary>
+    [Parameter] public bool Readonly { get; set; }
+
+    /// <summary>Marks the field invalid (<c>aria-invalid</c> + the error styling).</summary>
+    [Parameter] public bool Invalid { get; set; }
+
     protected override bool ShouldRender() => !Hydrated;
 
+    /* Pushed, not re-rendered: the seed's <ul> is consumed and removed by the enhancer, so this
+       component can never render again. */
+    protected override async Task OnParametersSetAsync()
+    {
+        if (!Hydrated) return;
+        await JS.InvokeVoidAsync("FreedayCascade.setState", Root,
+            new { disabled = Disabled, @readonly = Readonly, invalid = Invalid });
+    }
+
     /// <summary>Invoked by the bridge when the user selects a leaf.</summary>
     [JSInvokable]
     public async Task OnChange(ChangeDetail detail)

package/adapters/blazor/FdyCombo.razor

@@ -10,6 +10,7 @@
     <button id="@ButtonId" type="button" class="fdy-combo__button" role="combobox"
             aria-haspopup="listbox" aria-expanded="false"
             aria-labelledby="@AriaLabelledby"
+            aria-describedby="@Describedby"
             aria-invalid="@(Invalid ? "true" : null)"
             aria-readonly="@(Readonly ? "true" : null)"
             disabled="@Disabled">

package/adapters/blazor/FdyCombo.razor.cs

@@ -29,6 +29,10 @@ public partial class FdyCombo<TValue>
 
     [Parameter] public bool Invalid { get; set; }
 
+    /// <summary>Id of the help or error text the combobox describes itself with. Vue and React
+    /// have always had this one; Blazor was the odd stack out.</summary>
+    [Parameter] public string? Describedby { get; set; }
+
     private readonly string _autoId = $"fdy-combo-{Guid.NewGuid():N}";
     private TValue _lastValue = default!;
     private bool _ready;
@@ -66,6 +70,15 @@ public partial class FdyCombo<TValue>
             _lastValue = Value;
             await JS.InvokeVoidAsync("FreedayBlazor.comboSetValue", Root, KeyOf(Value));
         }
+
+        /* The three states need the same treatment for the same reason the value did: this
+           component stops rendering once hydrated, so a page that disables the field afterwards
+           was changing a parameter nothing read. */
+        if (_ready)
+        {
+            await JS.InvokeVoidAsync("FreedayCombo.setState", Root,
+                new { disabled = Disabled, @readonly = Readonly, invalid = Invalid });
+        }
     }
 
     /// <summary>Invoked by the bridge when the user picks an option (enhancer's fdy-change).</summary>

package/adapters/blazor/FdyDatepicker.razor

@@ -10,4 +10,18 @@
      data-label="@Label"
      data-placeholder="@Placeholder"
      data-min="@Min"
-     data-max="@Max"></div>
+     data-max="@Max"
+     data-id="@Id"
+     data-describedby="@Describedby"
+     data-disabled="@(Disabled ? "true" : null)"
+     data-readonly="@(Readonly ? "true" : null)"
+     data-invalid="@(Invalid ? "true" : null)"
+     data-fdy-text-prev-month="@PrevMonthLabel"
+     data-fdy-text-next-month="@NextMonthLabel"
+     data-fdy-text-prev-year="@PrevYearLabel"
+     data-fdy-text-next-year="@NextYearLabel"
+     data-fdy-text-prev-years="@PrevYearsLabel"
+     data-fdy-text-next-years="@NextYearsLabel"
+     data-fdy-text-choose-month="@ChooseMonthLabel"
+     data-fdy-text-choose-year="@ChooseYearLabel"
+     data-fdy-text-back-to-months="@BackToMonthsLabel"></div>

package/adapters/blazor/FdyDatepicker.razor.cs

@@ -18,6 +18,42 @@ public partial class FdyDatepicker
     [Parameter] public string? Min { get; set; }
     [Parameter] public string? Max { get; set; }
 
+    /// <summary>Id for the trigger the enhancer builds, so a form's own label can point at it.</summary>
+    [Parameter] public string? Id { get; set; }
+
+    /// <summary>Id of the help or error text the trigger describes itself with.</summary>
+    [Parameter] public string? Describedby { get; set; }
+
+    /// <summary>Greyed and out of the tab order.</summary>
+    [Parameter] public bool Disabled { get; set; }
+
+    /// <summary>Locked/view mode: focusable and showing its date, but the calendar will not open.
+    /// Unlike <see cref="Disabled"/> it keeps tab order and is not greyed.</summary>
+    [Parameter] public bool Readonly { get; set; }
+
+    /// <summary>Marks the field invalid (<c>aria-invalid</c> + the error styling).</summary>
+    [Parameter] public bool Invalid { get; set; }
+
+    /* The calendar's own navigation labels. Month and weekday NAMES follow the page's `lang`
+       through Intl and need nothing here; these are the buttons around them, which until 2.1.1
+       were literals inside the enhancer that no host could reach. Leave one null and the
+       enhancer's English default stands. */
+    [Parameter] public string? PrevMonthLabel { get; set; }
+    [Parameter] public string? NextMonthLabel { get; set; }
+    [Parameter] public string? PrevYearLabel { get; set; }
+    [Parameter] public string? NextYearLabel { get; set; }
+    [Parameter] public string? PrevYearsLabel { get; set; }
+    [Parameter] public string? NextYearsLabel { get; set; }
+
+    /// <summary>The title button that drills into the month grid. <c>{label}</c> is the period shown.</summary>
+    [Parameter] public string? ChooseMonthLabel { get; set; }
+
+    /// <summary>The title button that drills into the year grid. <c>{label}</c> is the period shown.</summary>
+    [Parameter] public string? ChooseYearLabel { get; set; }
+
+    /// <summary>The year grid's title, back to months. <c>{start}</c> and <c>{end}</c> are the page range.</summary>
+    [Parameter] public string? BackToMonthsLabel { get; set; }
+
     protected override ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayDatepicker.init", Root);
 
     protected override async ValueTask OnHydratedAsync()
@@ -26,6 +62,16 @@ public partial class FdyDatepicker
     // The enhancer owns the built trigger + calendar; never let Blazor re-render the seed.
     protected override bool ShouldRender() => !Hydrated;
 
+    /* Which is exactly why the three states are pushed rather than re-rendered: the seed above is
+       written once, so a page that disables this field later would otherwise be ignored in
+       silence. */
+    protected override async Task OnParametersSetAsync()
+    {
+        if (!Hydrated) return;
+        await JS.InvokeVoidAsync("FreedayDatepicker.setState", Root,
+            new { disabled = Disabled, @readonly = Readonly, invalid = Invalid });
+    }
+
     /// <summary>Invoked by the bridge when the user picks (or clears) a date.</summary>
     [JSInvokable]
     public async Task OnChange(ChangeDetail detail)

package/adapters/blazor/FdyTable.razor

@@ -17,10 +17,34 @@
         </div>
     }
 
+    @if (Selectable)
+    {
+        <div class="fdy-table-bulkbar" hidden="@(SelectedCount == 0)" role="region" aria-label="@BulkLabel">
+            <span class="fdy-table-bulkbar__count" aria-live="polite">@SelectedLabel()</span>
+            <span class="fdy-table-bulkbar__spacer"></span>
+            <div class="fdy-table-bulkbar__actions">
+                @BulkContent
+                <button type="button" class="fdy-btn fdy-btn--ghost fdy-btn--sm" @onclick="ClearSelection">@ClearSelectionText</button>
+            </div>
+        </div>
+    }
+
     <div class="fdy-table-scroll">
-        <table class="fdy-table" aria-label="@AriaLabel">
+        <table class="fdy-table @(Striped ? "fdy-table--striped" : null)" aria-label="@AriaLabel">
             <thead>
                 <tr>
+                    @if (Selectable)
+                    {
+                        <th class="fdy-table__selcol" scope="col">
+                            <input type="checkbox"
+                                   class="fdy-checkbox"
+                                   data-fdy-select-all
+                                   @ref="_selectAllRef"
+                                   checked="@AllPageSelected"
+                                   aria-label="@SelectAllLabel"
+                                   @onchange="e => ToggleAllOnPage((bool)(e.Value ?? false))" />
+                        </th>
+                    }
                     @foreach (FdyTableColumn<TRow> col in Columns)
                     {
                         <th scope="col" style="@AlignStyle(col)" aria-sort="@AriaSortOf(col)">
@@ -47,12 +71,12 @@
             <tbody>
                 @if (Loading)
                 {
-                    <tr><td colspan="@Columns.Count" class="fdy-table__state" role="status">@LoadingText</td></tr>
+                    <tr><td colspan="@ColSpan" class="fdy-table__state" role="status">@LoadingText</td></tr>
                 }
                 else if (_displayRows.Count == 0)
                 {
                     <tr>
-                        <td colspan="@Columns.Count" class="fdy-table__state">
+                        <td colspan="@ColSpan" class="fdy-table__state">
                             @if (EmptyContent is not null)
                             {
                                 @EmptyContent
@@ -72,8 +96,24 @@
                         <tr class="@RowClasses(r)"
                             tabindex="@(RowActivatable ? 0 : (int?)null)"
                             aria-expanded="@ExpandedAttr(r)"
+                            aria-selected="@SelectedAttr(r)"
                             @onclick="() => OnRowClick(r)"
                             @onkeydown="e => OnRowKeydown(e, r)">
+                            @if (Selectable)
+                            {
+                                @* @onclick:stopPropagation: without it, ticking a checkbox in an
+                                   activatable row also raises RowActivate, so selecting a row
+                                   would navigate away from it. *@
+                                <td class="fdy-table__selcol">
+                                    <input type="checkbox"
+                                           class="fdy-checkbox"
+                                           data-fdy-row-select
+                                           checked="@IsSelected(r)"
+                                           aria-label="@SelectRowLabel"
+                                           @onclick:stopPropagation="true"
+                                           @onchange="e => ToggleRow(r, (bool)(e.Value ?? false))" />
+                                </td>
+                            }
                             @foreach (FdyTableColumn<TRow> col in Columns)
                             {
                                 <td class="@CellClass(col)" style="@AlignStyle(col)">
@@ -91,7 +131,7 @@
                         @if (RowDetail is not null && IsExpanded(r))
                         {
                             <tr class="fdy-table__detailrow">
-                                <td colspan="@Columns.Count">@RowDetail(r)</td>
+                                <td colspan="@ColSpan">@RowDetail(r)</td>
                             </tr>
                         }
                     }

package/adapters/blazor/FdyTable.razor.cs

@@ -1,5 +1,6 @@
 using Microsoft.AspNetCore.Components;
 using Microsoft.AspNetCore.Components.Web;
+using Microsoft.JSInterop;
 
 namespace Freeday.Blazor;
 
@@ -86,6 +87,29 @@ public partial class FdyTable<TRow>
     /// <summary>Optional toolbar (search box, actions) above the table.</summary>
     [Parameter] public RenderFragment? Toolbar { get; set; }
 
+    /// <summary>Zebra-stripe the body rows.</summary>
+    [Parameter] public bool Striped { get; set; }
+
+    /// <summary>Render the checkbox column and the bulk bar.</summary>
+    [Parameter] public bool Selectable { get; set; }
+
+    /// <summary>
+    /// Controlled selection, as <see cref="RowKey"/> values. Wire <c>@bind-SelectedKeys</c> to own
+    /// it; omit for internal (the column still works with nothing wired).
+    /// </summary>
+    [Parameter] public IReadOnlyList<object>? SelectedKeys { get; set; }
+    [Parameter] public EventCallback<IReadOnlyList<object>> SelectedKeysChanged { get; set; }
+
+    /// <summary>Bulk-bar count, <c>{n}</c> substituted.</summary>
+    [Parameter] public string SelectedText { get; set; } = "{n} selected";
+    [Parameter] public string ClearSelectionText { get; set; } = "Clear";
+    [Parameter] public string SelectAllLabel { get; set; } = "Select all rows on this page";
+    [Parameter] public string SelectRowLabel { get; set; } = "Select row";
+    [Parameter] public string BulkLabel { get; set; } = "Bulk actions";
+
+    /// <summary>Bulk-bar actions (Blazor equivalent of Vue's <c>bulk-actions</c> slot).</summary>
+    [Parameter] public RenderFragment? BulkContent { get; set; }
+
     private FdySortState? _internalSort;
     private Dictionary<string, FdyColumnFilter> _internalFilters = new();
     private int _internalPageIndex;
@@ -148,6 +172,7 @@ public partial class FdyTable<TRow>
             _processDirty = false;
             if (Process.HasDelegate) await Process.InvokeAsync(new FdyTableProcess<TRow>(_displayRows, _totalCount));
         }
+        await SyncSelectAllIndeterminateAsync();
     }
 
     // Recompute the visible rows from the current effective sort/filter/page. Called on every
@@ -306,6 +331,91 @@ public partial class FdyTable<TRow>
         await RowActivate.InvokeAsync(row);
     }
 
+    // Selection is keyed by RowKey, exactly as ExpandedKeys is, and for the same reason: a key
+    // survives the re-fetch that replaces every row object, an object identity does not.
+    private List<object> _internalSelectedKeys = new();
+    private bool SelectionControlled => SelectedKeysChanged.HasDelegate;
+    private IReadOnlyList<object> EffectiveSelectedKeys =>
+        SelectionControlled ? (SelectedKeys ?? Array.Empty<object>()) : _internalSelectedKeys;
+    private int SelectedCount => EffectiveSelectedKeys.Count;
+
+    // The select-all box acts on the CURRENT PAGE, not on every filtered row: a header checkbox that
+    // silently selects rows the reader cannot see is how bulk deletes go wrong. Keys picked on other
+    // pages are preserved rather than dropped, so paging away and back does not lose them.
+    private List<object> PageKeys => _displayRows.Select(RowKey).ToList();
+    private bool AllPageSelected
+    {
+        get
+        {
+            List<object> keys = PageKeys;
+            return keys.Count > 0 && keys.All(EffectiveSelectedKeys.Contains);
+        }
+    }
+    private bool SomePageSelected => !AllPageSelected && PageKeys.Any(EffectiveSelectedKeys.Contains);
+
+    private async Task SetSelection(List<object> keys)
+    {
+        if (!SelectionControlled) _internalSelectedKeys = keys;
+        if (SelectedKeysChanged.HasDelegate) await SelectedKeysChanged.InvokeAsync(keys);
+    }
+
+    private bool IsSelected(TRow row) => EffectiveSelectedKeys.Contains(RowKey(row));
+
+    private async Task ToggleRow(TRow row, bool selected)
+    {
+        object key = RowKey(row);
+        List<object> next = EffectiveSelectedKeys.Where(k => !Equals(k, key)).ToList();
+        if (selected) next.Add(key);
+        await SetSelection(next);
+    }
+
+    private async Task ToggleAllOnPage(bool selected)
+    {
+        HashSet<object> onPage = PageKeys.ToHashSet();
+        List<object> offPage = EffectiveSelectedKeys.Where(k => !onPage.Contains(k)).ToList();
+        if (selected) offPage.AddRange(PageKeys);
+        await SetSelection(offPage);
+    }
+
+    private Task ClearSelection() => SetSelection(new List<object>());
+
+    [Inject] private IJSRuntime JS { get; set; } = default!;
+    private ElementReference _selectAllRef;
+    private bool? _pushedIndeterminate;
+
+    /// <summary>
+    /// <c>indeterminate</c> is a DOM property with no HTML attribute, so Blazor's renderer cannot
+    /// express it — without this the tri-state select-all box would render as a plain unchecked one
+    /// whenever only some rows on the page are selected. Pushed only when it actually changed, and
+    /// only while <see cref="Selectable"/>, so a table without a checkbox column makes no JS call at
+    /// all. The table's subtree already depends on the JS bridge (FdyTableFilter), so this adds no
+    /// new dependency, and running in OnAfterRender keeps it out of the prerender pass where there
+    /// is no element to touch yet.
+    /// </summary>
+    private async Task SyncSelectAllIndeterminateAsync()
+    {
+        if (!Selectable) return;
+        bool mixed = SomePageSelected;
+        if (_pushedIndeterminate == mixed) return;
+        _pushedIndeterminate = mixed;
+        try
+        {
+            await JS.InvokeVoidAsync("FreedayBlazor.setIndeterminate", _selectAllRef, mixed);
+        }
+        catch (JSDisconnectedException)
+        {
+            // circuit/runtime already gone
+        }
+    }
+
+    private string SelectedLabel() => SelectedText.Replace("{n}", SelectedCount.ToString());
+
+    private string? SelectedAttr(TRow row) => Selectable ? (IsSelected(row) ? "true" : "false") : null;
+
+    // The checkbox column widens every full-width row (loading, empty, row detail) by one. Deriving
+    // it once is what keeps a later column change from leaving one of the three behind.
+    private int ColSpan => Columns.Count + (Selectable ? 1 : 0);
+
     private bool IsExpanded(TRow row) => ExpandedKeys?.Contains(RowKey(row)) == true;
     private string? ExpandedAttr(TRow row) => RowDetail is null ? null : (IsExpanded(row) ? "true" : "false");
 }

package/adapters/blazor/freeday-blazor.js

@@ -168,6 +168,13 @@
     }
   }
 
+  // `indeterminate` is a DOM PROPERTY with no matching HTML attribute, so Blazor's renderer cannot
+  // express it and a tri-state select-all box would silently render as a plain unchecked one. Vue
+  // and React set the property directly; this is Blazor's way to the same place.
+  function setIndeterminate(element, value) {
+    if (element) element.indeterminate = !!value;
+  }
+
   // Flip the document theme (data-theme on <html>), for the demo toggle.
   function toggleTheme() {
     var e = document.documentElement;
@@ -177,6 +184,7 @@
   window.FreedayBlazor = {
     initAll: initAll, on: on, off: off, onOutside: onOutside, toast: toast, toggleTheme: toggleTheme,
     comboSetValue: comboSetValue, dateRangeOn: dateRangeOn, chartUpdate: chartUpdate,
+    setIndeterminate: setIndeterminate,
     dialogInit: dialogInit, dialogShow: dialogShow, dialogClose: dialogClose, dialogDispose: dialogDispose,
   };
 })();

package/adapters/react/components/FdyAppShell.tsx

@@ -31,6 +31,12 @@ export interface FdyAppShellProps {
   nav?: ReactNode;
   topbar?: ReactNode;
   children?: ReactNode;
+  /**
+   * How a VISIBLE nav sits on a wide viewport: `push` (default) makes it a column that displaces
+   * the content, `overlay` floats it over the page with a backdrop. Below the nav breakpoint it is
+   * ignored — the nav is off-canvas there by definition, so there is nothing to choose.
+   */
+  navMode?: 'push' | 'overlay';
 }
 
 export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
@@ -39,9 +45,19 @@ export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
   /* Set while a viewport change is driving the state, so the effect below reconciles `inert` and
      the classes but leaves FOCUS alone: a resize is not a reader asking to go somewhere. */
   const fromResizeRef = useRef<boolean>(false);
-  const [overlay, setOverlay] = useState<boolean>(false);
+  /* The viewport half of the answer, kept separate from `overlay` now that a prop can also decide
+     it: a mode switch and a resize both change whether the nav floats, and only one of them is a
+     viewport event. The ref shadows the state because the media listener subscribes once and must
+     read the CURRENT value without resubscribing. */
+  const [wide, setWide] = useState<boolean>(true);
+  const wideRef = useRef<boolean>(true);
   const [uncontrolled, setUncontrolled] = useState<boolean>(true);
 
+  const navMode: 'push' | 'overlay' = props.navMode ?? 'push';
+  const navModeRef = useRef<'push' | 'overlay'>(navMode);
+  navModeRef.current = navMode;
+
+  const overlay: boolean = !wide || navMode === 'overlay';
   const controlled: boolean = props.navOpen !== undefined;
   const navVisible: boolean = controlled ? props.navOpen === true : uncontrolled;
 
@@ -65,20 +81,41 @@ export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
   useEffect((): (() => void) => {
     const media: MediaQueryList = window.matchMedia(NAV_QUERY);
     const onChange = (): void => {
-      const nowOverlay: boolean = !media.matches;
-      setOverlay((was: boolean): boolean => {
-        if (was !== nowOverlay) fromResizeRef.current = true;
-        return nowOverlay;
-      });
-      if (nowOverlay && navVisibleRef.current) setVisibleRef.current(false);
+      const nowWide: boolean = media.matches;
+      if (nowWide === wideRef.current) return;
+      const mode: 'push' | 'overlay' = navModeRef.current;
+      const wasOverlay: boolean = !wideRef.current || mode === 'overlay';
+      const nextOverlay: boolean = !nowWide || mode === 'overlay';
+      /* Only when the effect below will actually re-run. In overlay MODE, crossing the breakpoint
+         changes neither `overlay` nor `navVisible`, and a flag left standing here would silently
+         swallow the focus move of the next real toggle. */
+      if (wasOverlay !== nextOverlay) fromResizeRef.current = true;
+      wideRef.current = nowWide;
+      setWide(nowWide);
+      if (nextOverlay && !wasOverlay && navVisibleRef.current) setVisibleRef.current(false);
     };
     // Mount: adopt the viewport without the hide-on-narrow side effect, nothing is open yet.
-    setOverlay(!media.matches);
-    if (!controlled) setUncontrolled(media.matches);
+    wideRef.current = media.matches;
+    setWide(media.matches);
+    /* An overlay nav starts CLOSED even on a wide screen: it covers the page, so opening it unasked
+       is the same intrusion it would be on a phone. A pushing column starts open. */
+    if (!controlled) setUncontrolled(media.matches && navModeRef.current !== 'overlay');
     media.addEventListener('change', onChange);
     return (): void => media.removeEventListener('change', onChange);
   }, [controlled]);
 
+  /* Switching mode is not a reader asking to go somewhere either, so focus stays put. Turning
+     overlay ON over a visible column would drop a panel across a page nobody asked to leave, so it
+     closes; turning it OFF leaves visibility alone, because `navOpen` is the reader's answer and a
+     mode change is not a reason to overrule it. */
+  const prevModeRef = useRef<'push' | 'overlay'>(navMode);
+  useEffect((): void => {
+    if (prevModeRef.current === navMode) return;
+    prevModeRef.current = navMode;
+    fromResizeRef.current = true;
+    if (navMode === 'overlay' && wideRef.current && navVisibleRef.current) setVisibleRef.current(false);
+  }, [navMode]);
+
   // Focus moves only after the class change has been painted, or the panel is still off-canvas and
   // the browser refuses to focus what it cannot lay out.
   useEffect((): void => {
@@ -109,9 +146,13 @@ export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
     return (): void => document.removeEventListener('keydown', onKeydown);
   }, [overlay, navVisible, setVisible]);
 
+  /* `--nav-overlay` rides on the MODE, not on the viewport: below the breakpoint the stylesheet's
+     own media query already makes the nav off-canvas, so the class would be redundant there, and
+     carrying it anyway is what lets one class answer "is this shell in overlay mode?" at any width. */
+  const modeClass: string = navMode === 'overlay' ? ' fdy-app--nav-overlay' : '';
   const shellClass: string = overlay
-    ? (navVisible ? 'fdy-app fdy-app--nav-open' : 'fdy-app')
-    : (navVisible ? 'fdy-app' : 'fdy-app fdy-app--nav-collapsed');
+    ? `fdy-app${modeClass}${navVisible ? ' fdy-app--nav-open' : ''}`
+    : `fdy-app${modeClass}${navVisible ? '' : ' fdy-app--nav-collapsed'}`;
 
   return (
     <div ref={rootRef} className={shellClass}>

package/adapters/react/components/FdyDrawer.tsx

@@ -14,6 +14,8 @@ export interface FdyDrawerProps {
   onClose: () => void;
   side?: 'left' | 'right';
   dismissible?: boolean;
+  /** aria-label for the × button. Default 'Close'. */
+  closeLabel?: string;
   footer?: ReactNode;
   children?: ReactNode;
 }
@@ -47,7 +49,7 @@ export function FdyDrawer(props: FdyDrawerProps): JSX.Element {
       <div className="fdy-drawer__header">
         <h3 id={titleId} className="fdy-drawer__title">{props.title}</h3>
         {dismissible && (
-          <button className="fdy-drawer__close" type="button" aria-label="Close" onClick={props.onClose}>&times;</button>
+          <button className="fdy-drawer__close" type="button" aria-label={props.closeLabel ?? 'Close'} onClick={props.onClose}>&times;</button>
         )}
       </div>
 

package/adapters/react/components/FdyModal.tsx

@@ -15,6 +15,8 @@ export interface FdyModalProps {
   onClose: () => void;
   size?: 'sm' | 'md' | 'lg' | 'wide';
   dismissible?: boolean;
+  /** aria-label for the × button. Default 'Close'. */
+  closeLabel?: string;
   footer?: ReactNode;
   children?: ReactNode;
 }
@@ -51,7 +53,7 @@ export function FdyModal(props: FdyModalProps): JSX.Element {
       <div className="fdy-modal__header">
         <h3 id={titleId} className="fdy-modal__title">{props.title}</h3>
         {dismissible && (
-          <button className="fdy-modal__close" type="button" aria-label="Close" onClick={props.onClose}>&times;</button>
+          <button className="fdy-modal__close" type="button" aria-label={props.closeLabel ?? 'Close'} onClick={props.onClose}>&times;</button>
         )}
       </div>