@cahyo-dimas/freeday 1.53.0 → 2.0.0

package/USAGE.md

@@ -1,16 +1,16 @@
 # Freeday — Usage doctrine
 
-Freeday ships tokens and components. This file ships the **decisions** — which token to use when,
+Freeday ships tokens and components. This file ships the **decisions**: which token to use when,
 how a page is assembled, what earns emphasis. A component library enforces consistent *values*; a
 design system also enforces consistent *decisions*. Skim this once before building a screen; it is
 what makes screens built by different people (or different sessions) look like one product.
 
-The rules are opinionated on purpose. When one conflicts with a real need, break it deliberately —
+The rules are opinionated on purpose. When one conflicts with a real need, break it deliberately, and
 but start here, not from a blank page.
 
 ---
 
-## 1. Type roles — three title levels, not eleven
+## 1. Type roles: three title levels, not eleven
 
 Do **not** reuse `.fdy-card__title` for a page title. Collapsing page/section/card into one style is
 the single biggest cause of "flat grey mush". Pick the role, not the size:
@@ -30,31 +30,31 @@ font size.
 
 ## Borders: two roles, two contrast contracts
 
-`--color-border` (and `-muted` / `-strong`) is **decoration** — a card edge, a table rule, a
+`--color-border` (and `-muted` / `-strong`) is **decoration**: a card edge, a table rule, a
 separator. Nothing in WCAG requires it to be visible, and it is deliberately faint (≈1.3:1).
 
-`--color-control-border` is the **boundary of a control** — input, textarea, checkbox, radio,
+`--color-control-border` is the **boundary of a control**: input, textarea, checkbox, radio,
 switch, dropzone. WCAG 1.4.11 requires 3:1 against every surface it can sit on, so it is
 necessarily darker than a card edge; that difference is the contract, not an inconsistency.
 
 It is tuned to clear that floor with margin (≈3.4–3.9 depending on surface) rather than to be as
 dark as it can be: a boundary that reads as loud as body text makes a form feel heavier than it is.
-Do not "harmonise" a control border down to `--color-border` — that drops a required 3:1 boundary to
+Do not "harmonise" a control border down to `--color-border`. That drops a required 3:1 boundary to
 1.3:1.
 
-## 2. Spacing rhythm — three gaps, always from the scale
+## 2. Spacing rhythm: three gaps, always from the scale
 
 Never a loose value; always `var(--space-N)` (a 4px scale). Three rhythms carry most layouts, and the
 composition primitives apply them for you:
 
-- **Between page sections:** `--space-8` — `.fdy-page` sets this gap between its children.
-- **Within a group** (heading ↔ its body, cards in a list): `--space-4` — `.fdy-page-section` sets it.
+- **Between page sections:** `--space-8`, which `.fdy-page` sets between its children.
+- **Within a group** (heading ↔ its body, cards in a list): `--space-4`, which `.fdy-page-section` sets.
 - **Inside a control/card** (label ↔ input, icon ↔ text): `--space-2` / `--space-3`.
 
 Reserve `--space-1` for hairline pairs and `--space-10`+ for deliberate breathing room (a hero, an
-empty state). Don't scatter `--space-6` everywhere — a page with one gap value has no rhythm.
+empty state). Don't scatter `--space-6` everywhere. A page with one gap value has no rhythm.
 
-## 3. Elevation — most surfaces are flat
+## 3. Elevation: most surfaces are flat
 
 Shadow is a signal, not decoration. There are two families, and the difference matters:
 
@@ -67,23 +67,23 @@ Shadow is a signal, not decoration. There are two families, and the difference m
 | Overlay | `--shadow-4` | `.fdy-drawer` |
 | **Lift** | `--shadow-lift` / `--shadow-lift-hover` | **`.fdy-card`** (and `--elevated` / `--interactive:hover`), `.fdy-modal` |
 
-**`.fdy-card` is a lifted surface, not a hairline one** — `--shadow-lift` is a real 34px lift, ~6×
+**`.fdy-card` is a lifted surface, not a hairline one.** `--shadow-lift` is a real 34px lift, ~6×
 heavier than `--shadow-1`. That is the whole point of a card, and it is also why a *stack* of them
 reads wrong: a list of ten cards is ten objects floating off the page. For rows, use the flat
 container **`.fdy-list` / `.fdy-list__row`** (hairline border, `--color-border-muted` dividers, no
 shadow). Reach for `.fdy-card` when something genuinely is one pickable object.
 
-If every box on the screen has the same card shadow, none of them read as special — that's the
+If every box on the screen has the same card shadow, none of them read as special. That's the
 "identical card grid" failure. Prefer flat sections with **one** raised element that matters.
 
-## 4. Emphasis — exactly one primary per screen
+## 4. Emphasis: exactly one primary per screen
 
 `.fdy-btn` is *already* the primary action (there is no `--primary` modifier). Use it **once** per
-screen — the one thing you want the user to do. Everything else is `--ghost` or `--text`. Two primary
+screen: the one thing you want the user to do. Everything else is `--ghost` or `--text`. Two primary
 buttons on a screen means neither is. The same rule governs colour fills and `--shadow`: one focal
 point, everything around it quiet.
 
-## 5. Colour — semantic is reserved; categorical is `--tone`
+## 5. Colour: semantic is reserved; categorical is `--tone`
 
 - **Accent** (`--color-primary`, and `--color-accent` sparingly): interactive + brand. This is your
   one accent hue.
@@ -91,19 +91,19 @@ point, everything around it quiet.
   = caution only, `--color-danger` = destructive/error only. Never decorative. Encode state in a pill
   or chip, not just colour.
 - **Categorical** (`--tone-1` … `--tone-8`, the general alias of the validated chart palette): N
-  visually-distinct **non-semantic** colours — avatar tones, category chips, tags, legend swatches.
+  visually-distinct **non-semantic** colours: avatar tones, category chips, tags, legend swatches.
   Use the modifiers `.fdy-avatar--tone-N` / `.fdy-chip--tone-N` (both stay WCAG AA in light & dark),
   and hash a stable index off the full string so the same category always gets the same colour.
 - **Surfaces:** most backgrounds are `--color-surface`; `--color-surface-2`/`-3` for a recessed area;
   `--color-primary-soft` only when you want a tinted callout, not as a default panel colour.
 
-## 5b. Theme — global by default, per-subtree when a region is inverted
+## 5b. Theme: global by default, per-subtree when a region is inverted
 
 `data-theme="light|dark"` redefines the semantic tokens. Set it on `<html>` and it themes the app;
 that is the normal case and nothing about it has changed.
 
 **It is also per-subtree.** The two explicit selectors are bare `[data-theme="dark"]` /
-`[data-theme="light"]`, and semantic tokens are inheriting custom properties — so a
+`[data-theme="light"]`, and semantic tokens are inheriting custom properties, so a
 `<section data-theme="dark">` inverts that region and **every Freeday component inside it follows**:
 card surfaces, inputs, buttons, and text roles like `.fdy-title-page` that set
 `color: var(--color-text)` explicitly. A dark brand panel beside a light sign-in form needs no
@@ -112,40 +112,40 @@ in turn.
 
 Do **not** invert a region by hand with `--color-inverse-*` plus `color-mix`. That pair is right for
 a one-off band of your own markup, but it stops scaling the moment the region contains a real
-component — anything that sets its own colour from a token never sees your override, and you end up
+component. Anything that sets its own colour from a token never sees your override, and you end up
 restating colours per element.
 
 The **system** default (`@media (prefers-color-scheme: dark)`) stays root-scoped on purpose: that
 rule is about the document, and un-rooting it would re-darken the children of a light island.
 
-## 6. Density — `compact` for data-dense screens
+## 6. Density: `compact` for data-dense screens
 
 `data-density="compact"` tightens control height **and** the mid-range spacing scale
 (`--space-3`…`--space-6` step down a notch), so cards, toolbars and tables get denser. Use it on
 table-heavy back-office screens; leave `comfortable` (the default) for forms.
 
 **It is per-subtree, not only global.** The selector is a bare `[data-density="compact"]` and these
-are inheriting custom properties, so the attribute works on `<html>` *or* on any wrapper — a route
+are inheriting custom properties, so the attribute works on `<html>` *or* on any wrapper: a route
 container, a single `<section>`. An app whose two list screens are dense and whose three form screens
 are not should scope it per screen rather than densifying everything. Set it at one level per screen,
 never per component.
 
 **And it goes both ways.** `data-density="comfortable"` is a real rule, not just the absence of
-`compact`, so an app that is dense *at the root* can opt one region back out — a header, a toolbar,
+`compact`, so an app that is dense *at the root* can opt one region back out: a header, a toolbar,
 a footer shared with a sibling product that has to line up pixel for pixel. Inheritance only runs
 downhill; without that rule a compact root left every subtree compact and a `comfortable` wrapper
 changed nothing. Do not restate the five values by hand: that copy goes stale the moment the kit
 retunes a step.
 
-## 6b. Navigation: one component, two orientations — and never a tab role
+## 6b. Navigation: one component, two orientations, and never a tab role
 
 A navigation link is an `<a class="fdy-nav__item">` marked **`aria-current="page"`**. That does not
 change with the layout:
 
-- **Sidebar app** — `.fdy-nav` inside `.fdy-app__sidebar` (the default).
-- **Top-nav app** — `.fdy-nav.fdy-nav--horizontal` inside `.fdy-appbar` or `.fdy-app__topbar`, with
+- **Sidebar app:** `.fdy-nav` inside `.fdy-app__sidebar` (the default).
+- **Top-nav app:** `.fdy-nav.fdy-nav--horizontal` inside `.fdy-appbar` or `.fdy-app__topbar`, with
   no sidebar. Same items, same states; on `.fdy-appbar--primary` the links go on-colour for you.
-- **Routed sub-navigation that should look like tabs** (`/settings/profile` · `/settings/billing`) —
+- **Routed sub-navigation that should look like tabs** (`/settings/profile` · `/settings/billing`):
   put `.fdy-tabs__list` / `.fdy-tabs__tab` on plain `<a>`s. Those classes honour `aria-current="page"`
   as well as `aria-selected="true"` precisely for this. Do **not** add `role="tab"`/`role="tablist"`
   or `freeday-tabs.js`: those promise a roving-tabindex, arrow-key, one-panel-per-tab contract that
@@ -154,38 +154,42 @@ change with the layout:
 Reserve the full `.fdy-tabs` component (with its roles and its enhancer) for **in-page** tabs, where
 nothing navigates.
 
-**Toggles:** a button that is on/off carries `aria-pressed`, and the kit styles it — soft primary
+**Toggles:** a button that is on/off carries `aria-pressed`, and the kit styles it: soft primary
 fill on `--ghost`/`--text`, a sunken gradient on the solid button. A `.fdy-btn-group` of `--ghost`
 buttons with exactly one `aria-pressed="true"` **is** the segmented control; don't hand-tint it.
 
 ## 7. Assemble the page from the frame down
 
-1. **Shell:** every application starts inside **`.fdy-app`** — a flex row of `__sidebar` (with
+1. **Shell:** every application starts inside **`.fdy-app`**, a flex row of `__sidebar` (with
    `__brand` + `.fdy-nav`) and `__content` (which holds `__topbar` + `__main`, plus `__navtoggle`
-   and `__backdrop`). The nesting is fixed; don't hand-roll a shell from flexbox — the toggle and
-   backdrop plumbing are already there. Skeleton: `COMPONENTS.md` §App shell; a working screen:
+   and `__backdrop`). The nesting is fixed; don't hand-roll a shell from flexbox. **Take the
+   behaviour too:** `<FdyAppShell>` in Vue/React/Blazor, or `data-fdy-app` plus
+   `freeday-app-shell.js` in plain markup. Until 1.53.0 the kit shipped the classes and left every
+   consumer to write the toggle, Escape, focus trap, focus restore and `inert` themselves, and the
+   two copies in this repo's own docs had already drifted apart; a nav panel you cannot escape from
+   with the keyboard is the usual result. Skeleton: `COMPONENTS.md` §App shell; a working screen:
    `docs/reference-screen.html`.
 2. **Page:** wrap the screen body in **`.fdy-page`** (vertical section rhythm), opening with a
    **`.fdy-page__header`** (eyebrow + `.fdy-title-page` + `.fdy-page__desc` on the left, the one
    primary action on the right).
 3. **Sections:** each region is a **`.fdy-page-section`** (a `.fdy-title-section` + optional
    `.fdy-toolbar`, then its body).
-   **Toolbar or filter bar — pick by whether the fields carry visible labels.** `.fdy-toolbar` is
+   **Toolbar or filter bar? Pick by whether the fields carry visible labels.** `.fdy-toolbar` is
    `align-items:center`, right for bare controls (buttons, a search box, chips); put a labelled
    `.fdy-field` in it and that field sits half a label-height low against its neighbours. Fields
    with visible labels belong in **`.fdy-filterbar`**, which is `align-items:flex-end` for exactly
    this reason (and has the width rhythm `--w-sm`…`--w-grow`). In a toolbar, label fields with
    `.fdy-visually-hidden` or a placeholder.
-4. **KPIs:** a **`.fdy-stats`** grid of **`.fdy-stat`** tiles — deliberately *not* cards, so a metric
+4. **KPIs:** a **`.fdy-stats`** grid of **`.fdy-stat`** tiles, deliberately *not* cards, so a metric
    strip doesn't become an identical-card grid. Wrap in `.fdy-stats--boxed` for one shared strip.
 5. **Content:** components (`.fdy-card`, `.fdy-datatable`, `.fdy-chart`, …) go inside sections.
 
 Freeday deliberately owns **components + tokens, not layout**. Everything above is layout in the kit's
 own language; for the rest (grids, one-off spacing), pair a utility framework run **utilities-only,
-preflight-off** — and build its theme on `var(--space-N)` so the two systems agree. See
+preflight-off**, and build its theme on `var(--space-N)` so the two systems agree. See
 `docs/getting-started.md` §Core concepts.
 
 ---
 
 *Layout classes here live in `src/components/composition.css`. If a screen needs a primitive that
-isn't here, it probably belongs here — open an issue rather than re-inventing it per screen.*
+isn't here, it probably belongs here. Open an issue rather than re-inventing it per screen.*

package/adapters/blazor/FdyAppShell.razor

@@ -0,0 +1,50 @@
+@namespace Freeday.Blazor
+@inherits FreedayComponentBase<FdyAppShell>
+
+@* Blazor wrapper over freeday's .fdy-app shell. Unlike FdyModal and FdyDrawer, which drive a native
+   <dialog> through the bridge, this one hands the whole behaviour to freeday-app-shell.js via
+   `data-fdy-app` and binds to it: the enhancer announces changes as a bubbling `fdy-app-nav` event
+   and accepts them through FreedayAppShell.setVisible. That is the bridge's own doctrine: the
+   enhancers stay the source of truth, and it keeps the focus trap from existing a third time. *@
+<div @ref="Root" class="fdy-app" data-fdy-app>
+    @SkipContent
+
+    <aside class="fdy-app__sidebar">
+        @BrandContent
+        @NavContent
+    </aside>
+
+    <div class="fdy-app__content">
+        <header class="fdy-app__topbar">
+            <button class="fdy-app__navtoggle" type="button" aria-label="@ToggleLabel">
+                @if (ToggleIcon is not null)
+                {
+                    @ToggleIcon
+                }
+                else
+                {
+                    <text>&#9776;</text>
+                }
+            </button>
+
+            <h1 class="fdy-app__title">
+                @if (TitleContent is not null)
+                {
+                    @TitleContent
+                }
+                else
+                {
+                    @Title
+                }
+            </h1>
+
+            @TopbarContent
+        </header>
+
+        <main class="fdy-app__main">
+            @ChildContent
+        </main>
+    </div>
+
+    <div class="fdy-app__backdrop"></div>
+</div>

package/adapters/blazor/FdyAppShell.razor.cs

@@ -0,0 +1,114 @@
+using Microsoft.AspNetCore.Components;
+using Microsoft.JSInterop;
+
+namespace Freeday.Blazor;
+
+public partial class FdyAppShell
+{
+    /// <summary>
+    /// Whether the nav is visible to the reader, one idea, in both modes: above the nav breakpoint
+    /// a hidden nav is a collapsed column, below it a visible nav is an overlay. The kit owns that
+    /// mapping so an app never reasons about the viewport to answer a question about its own UI.
+    /// <para>
+    /// Leave it <c>null</c> (the default) and the shell keeps its own, starting from the viewport:
+    /// a column on a wide screen, hidden on a narrow one. That default is why this is nullable,
+    /// a caller cannot express it as a single initial value before it knows the viewport. Bind it
+    /// (<c>@bind-NavOpen</c>) when the app wants to drive it from a menu or a saved preference.
+    /// </para>
+    /// </summary>
+    [Parameter] public bool? NavOpen { get; set; }
+    [Parameter] public EventCallback<bool?> NavOpenChanged { get; set; }
+
+    /// <summary>Plain-text page 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 brand block at the top of the sidebar.</summary>
+    [Parameter] public RenderFragment? BrandContent { get; set; }
+
+    /// <summary>The navigation itself, normally a <c>.fdy-nav</c> list.</summary>
+    [Parameter] public RenderFragment? NavContent { get; set; }
+
+    /// <summary>Topbar actions, rendered after the title.</summary>
+    [Parameter] public RenderFragment? TopbarContent { get; set; }
+
+    /// <summary>The skip link, if the app ships one. Rendered as the shell's first child.</summary>
+    [Parameter] public RenderFragment? SkipContent { get; set; }
+
+    /// <summary>The page itself.</summary>
+    [Parameter] public RenderFragment? ChildContent { get; set; }
+
+    /// <summary>Custom glyph for the nav toggle; a hamburger is used when null.</summary>
+    [Parameter] public RenderFragment? ToggleIcon { get; set; }
+
+    [Parameter] public string ToggleLabel { get; set; } = "Toggle navigation";
+
+    private int _navToken;
+    private bool? _lastNavOpen;
+
+    protected override async ValueTask HydrateAsync()
+    {
+        await JS.InvokeVoidAsync("FreedayBlazor.initAll", Root);
+        _navToken = await JS.InvokeAsync<int>(
+            "FreedayBlazor.on", Root, "fdy-app-nav", Self, nameof(OnNavChanged));
+
+        if (NavOpen is bool wanted)
+        {
+            // A caller that bound a value is authoritative, push it down.
+            await JS.InvokeVoidAsync("FreedayAppShell.setVisible", Root, wanted);
+            _lastNavOpen = wanted;
+        }
+        else
+        {
+            // Nobody bound one, so adopt what the shell decided from the viewport. Without this the
+            // bound value would claim `false` next to a nav that is plainly a visible column.
+            bool visible = await JS.InvokeAsync<bool>("FreedayAppShell.isVisible", Root);
+            _lastNavOpen = visible;
+            await SetNavOpenAsync(visible);
+        }
+    }
+
+    protected override async Task OnParametersSetAsync()
+    {
+        // Only reconcile once the shell is wired, and only when the caller actually changed it,
+        // echoing our own event back down would fight the enhancer for the same state.
+        if (_navToken != 0 && NavOpen is bool wanted && wanted != _lastNavOpen)
+        {
+            _lastNavOpen = wanted;
+            await JS.InvokeVoidAsync("FreedayAppShell.setVisible", Root, wanted);
+        }
+    }
+
+    /// <summary>Invoked by the bridge when the shell's nav visibility changes for any reason,
+    /// the toggle, Esc, the backdrop, following a nav link, or the viewport crossing the
+    /// breakpoint.</summary>
+    [JSInvokable]
+    public async Task OnNavChanged(NavDetail detail)
+    {
+        _lastNavOpen = detail.Visible;
+        await SetNavOpenAsync(detail.Visible);
+    }
+
+    private async Task SetNavOpenAsync(bool visible)
+    {
+        if (NavOpenChanged.HasDelegate)
+        {
+            await NavOpenChanged.InvokeAsync(visible);
+        }
+        else
+        {
+            NavOpen = visible;
+            StateHasChanged();
+        }
+    }
+
+    protected override async ValueTask CleanupAsync()
+    {
+        if (_navToken != 0)
+        {
+            await JS.InvokeVoidAsync("FreedayBlazor.off", _navToken);
+        }
+    }
+
+    public sealed record NavDetail(bool Visible);
+}

package/adapters/blazor/FdyCfl.razor.cs

@@ -195,7 +195,7 @@ public partial class FdyCfl<TRow>
         else _picked.RemoveAt(at);
     }
 
-    /* A click means "tick this" in multi and "this is my answer" in single — the whole difference. */
+    /* A click means "tick this" in multi and "this is my answer" in single, the whole difference. */
     private async Task RowClickAsync(TRow row)
     {
         if (Multiple) TogglePick(row);

package/adapters/blazor/FdyChart.razor

@@ -3,7 +3,7 @@
 @* 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,
+   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. *@

package/adapters/blazor/FdyChart.razor.cs

@@ -32,7 +32,7 @@ public partial class FdyChart : ComponentBase
     /// <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
+    /// <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; }
 
@@ -72,14 +72,14 @@ public partial class FdyChart : ComponentBase
     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.
+    // 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.
+    // 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;

package/adapters/blazor/FdyChartSeries.cs

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

package/adapters/blazor/FdyCombo.razor.cs

@@ -34,7 +34,7 @@ public partial class FdyCombo<TValue>
     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
+    // 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;
@@ -60,7 +60,7 @@ public partial class FdyCombo<TValue>
 
     protected override async Task OnParametersSetAsync()
     {
-        // Push an externally-changed Value onto the enhancer-owned DOM (silent — no fdy-change echo).
+        // 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;

package/adapters/blazor/FdyModal.razor

@@ -4,7 +4,7 @@
 @* 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. *@
+   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">

package/adapters/blazor/FdyTable.razor.cs

@@ -30,8 +30,8 @@ public partial class FdyTable<TRow>
     [Parameter] public int PageSize { get; set; }
 
     /// <summary>
-    /// Controlled client-side page index (0-based). Set it — with <see cref="PageSize"/>, without
-    /// <see cref="Page"/> — to own the page while the table keeps doing filter/sort/paginate. That is
+    /// Controlled client-side page index (0-based). Set it, with <see cref="PageSize"/>, without
+    /// <see cref="Page"/>, to own the page while the table keeps doing filter/sort/paginate. That is
     /// what lets an EXTERNAL pager drive the table: a responsive screen that hides the datatable below
     /// the <c>md</c> breakpoint and renders a card list from <see cref="Process"/> can render one pager
     /// for both breakpoints and bind it here. Leave null for the internal index (unchanged default).
@@ -45,14 +45,14 @@ public partial class FdyTable<TRow>
     /// Offer a rows-per-page control in the footer, beside the range and the pager. Leave null for
     /// none (unchanged default). Every back office has one, and a table that renders two thirds of
     /// its own footer forces the app to rebuild all three to add the last (#008).
-    /// Server mode reports the pick through <see cref="PageChanged"/> — same callback as a page
+    /// Server mode reports the pick through <see cref="PageChanged"/>, same callback as a page
     /// click, with a new size. Client mode applies it internally and also raises
     /// <see cref="PageSizeChanged"/>, so the control works with nothing wired.
     /// </summary>
     [Parameter] public IReadOnlyList<int>? PageSizes { get; set; }
 
     /// <summary>Raised in client mode when the reader picks a new rows-per-page. The table has
-    /// already applied it — this is for a caller that wants to persist the choice.</summary>
+    /// already applied it, this is for a caller that wants to persist the choice.</summary>
     [Parameter] public EventCallback<int> PageSizeChanged { get; set; }
 
     [Parameter] public int? PageIndex { get; set; }
@@ -62,7 +62,7 @@ public partial class FdyTable<TRow>
     [Parameter] public EventCallback<int> PageIndexChanged { get; set; }
 
     /// <summary>Raised whenever the processed page of rows (after filter/sort/paginate) or the total
-    /// changes, in BOTH modes — so the same processed set can drive a card list, a summary or an
+    /// changes, in BOTH modes, so the same processed set can drive a card list, a summary or an
     /// export without re-deriving the pipeline. Mirrors <c>process</c> in the Vue/React adapters.</summary>
     [Parameter] public EventCallback<FdyTableProcess<TRow>> Process { get; set; }
 
@@ -113,7 +113,7 @@ public partial class FdyTable<TRow>
         FiltersControlled ? (Filters ?? EmptyFilters) : _internalFilters;
 
     /* Client-mode rows-per-page. PageSize is a plain parameter with no callback, so a footer control
-     * that only reported would do nothing in the app that wired nothing — the table applies the pick
+     * that only reported would do nothing in the app that wired nothing, the table applies the pick
      * itself and reports it. An explicit change to the parameter wins back (see OnParametersSet). */
     private int? _internalPageSize;
     private int _prevPageSize;
@@ -298,7 +298,7 @@ public partial class FdyTable<TRow>
 
     // Enter/Space activate a focused row. Blazor's KeyboardEventArgs can't tell whether the row
     // itself vs an inner control is the target, so activatable rows should not embed focusable
-    // controls (the common drill-in-row pattern) — matching the Vue guard's practical effect.
+    // controls (the common drill-in-row pattern), matching the Vue guard's practical effect.
     private async Task OnRowKeydown(KeyboardEventArgs e, TRow row)
     {
         if (!RowActivatable) return;

package/adapters/blazor/FdyTableFilter.razor

@@ -3,7 +3,7 @@
 @* Internal to FdyTable: one column's header funnel button + its type-aware filter popover
    (text / enum / number / date), over freeday's .fdy-table__filterbtn + .fdy-filter* classes.
    The panel is position:fixed (top layer) so it escapes the table's overflow; light-dismiss
-   (outside pointer / Esc) is wired through FreedayBlazor.onOutside. Purely controlled — it renders
+   (outside pointer / Esc) is wired through FreedayBlazor.onOutside. Purely controlled: it renders
    the current Filter and raises the next one (or null to clear). *@
 <span @ref="_root" class="fdy-table__filterwrap">
     <button type="button"

package/adapters/blazor/FdyTableFooter.razor

@@ -1,7 +1,7 @@
 @* The band under a table: what you are looking at, how much of it you see, where you are.
 
    FdyTable renders this itself, so most screens never use it directly. It is public for the one
-   shape that cannot use the table's own — a RESPONSIVE list, where a .fdy-datatable at lg and a
+   shape that cannot use the table's own: a RESPONSIVE list, where a .fdy-datatable at lg and a
    .fdy-list below it are two renderings of ONE page of rows. A footer inside the table is inside the
    half that is hidden on a phone, so those screens render it once, outside both (improvement notes
    #005 and #008, from IDU_EMATE_APPL_WEB). *@

package/adapters/blazor/FdyTableFooter.razor.cs

@@ -3,7 +3,7 @@ using Microsoft.AspNetCore.Components;
 namespace Freeday.Blazor;
 
 /// <summary>
-/// The table footer — range, optional rows-per-page, pager — as a component of its own.
+/// The table footer, range, optional rows-per-page, pager, as a component of its own.
 /// It owns nothing: <see cref="Page"/> in, <see cref="PageChanged"/> out, the same contract as
 /// <c>FdyTable</c>'s server mode.
 /// </summary>
@@ -15,7 +15,7 @@ public partial class FdyTableFooter
     [Parameter] public EventCallback<FdyPageState> PageChanged { get; set; }
 
     /// <summary>
-    /// Offer a rows-per-page control. Leave null for none — the footer is then range + pager,
+    /// Offer a rows-per-page control. Leave null for none; the footer is then range + pager,
     /// exactly as before. Picking a size raises <see cref="PageChanged"/> with the new size and the
     /// index that still holds the row the reader was looking at.
     /// </summary>
@@ -28,7 +28,7 @@ public partial class FdyTableFooter
     private IReadOnlyList<FdyComboOption<string>> SizeOptions =>
         Sizes.Select(size => new FdyComboOption<string>(size.ToString(), size.ToString())).ToList();
 
-    // The combo is labelled by the visible word beside it — a <label for> cannot reach inside a
+    // The combo is labelled by the visible word beside it, a <label for> cannot reach inside a
     // component, and an aria-label would leave that word attached to nothing.
     private readonly string SizeLabelId = $"fdy-rows-{Guid.NewGuid():N}";
 
@@ -40,7 +40,7 @@ public partial class FdyTableFooter
 
     private bool HasPager => Page.Size > 0 && TotalPages > 1;
 
-    // One page and no size control means there is nothing here to say — the table has always
+    // One page and no size control means there is nothing here to say, the table has always
     // withheld the whole band in that case, and this is where that decision now lives.
     private bool Visible => HasPager || Sizes.Count > 0;
 

package/adapters/blazor/Freeday.Blazor.csproj

@@ -1,4 +1,4 @@
-<!-- Freeday — Blazor component library (Razor Class Library).
+<!-- Freeday. Blazor component library (Razor Class Library).
      Typed wrappers over the vanilla `fdy-*` enhancers; the host page must load
      dist/freeday.js + adapters/blazor/freeday-blazor.js. Targets net8.0 (LTS) so it can
      be referenced from net8/9/10 apps. Consume via <ProjectReference> to this .csproj

package/adapters/blazor/FreedayComponentBase.cs

@@ -36,7 +36,7 @@ public abstract class FreedayComponentBase<TSelf> : ComponentBase, IAsyncDisposa
     /// registered enhancer over <see cref="Root"/>; override to call a specific enhancer.</summary>
     protected virtual ValueTask HydrateAsync() => JS.InvokeVoidAsync("FreedayBlazor.initAll", Root);
 
-    /// <summary>Runs once after the first render, right after <see cref="HydrateAsync"/> — wire event
+    /// <summary>Runs once after the first render, right after <see cref="HydrateAsync"/>, wire event
     /// subscriptions here.</summary>
     protected virtual ValueTask OnHydratedAsync() => ValueTask.CompletedTask;
 

package/adapters/blazor/TableModel.cs

@@ -6,7 +6,7 @@ using System.Text.RegularExpressions;
 namespace Freeday.Blazor;
 
 /// <summary>
-/// The sort / filter / paginate logic for <see cref="FdyTable{TRow}"/> — the C# counterpart of the
+/// The sort / filter / paginate logic for <see cref="FdyTable{TRow}"/>, the C# counterpart of the
 /// framework-agnostic adapters/core/table-model.js shared by the Vue and React adapters. Kept as a
 /// separate pure-function class (no rendering, no state) so it mirrors that reference faithfully and
 /// stays unit-testable. Every method is pure: inputs are never mutated (rows are copied before sort).
@@ -40,7 +40,7 @@ public static class TableModel
             : 0;
     }
 
-    /// <summary>ISO calendar day (yyyy-MM-dd) — lexicographically comparable.</summary>
+    /// <summary>ISO calendar day (yyyy-MM-dd), lexicographically comparable.</summary>
     private static string DateOnly(object? v)
     {
         if (v is DateTime dt) return dt.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture);
@@ -167,7 +167,7 @@ public static class TableModel
         return rows.Skip(pageIndex * pageSize).Take(pageSize).ToList();
     }
 
-    /// <summary>Distinct non-empty cell texts for a column, naturally sorted — the enum-filter source.</summary>
+    /// <summary>Distinct non-empty cell texts for a column, naturally sorted, the enum-filter source.</summary>
     public static List<string> DistinctValues<TRow>(IReadOnlyList<TRow> rows, FdyTableColumn<TRow> column)
     {
         HashSet<string> seen = new();