@cahyo-dimas/freeday 1.17.0 → 1.20.0

package/README.id.md

@@ -5,13 +5,21 @@
 > **Lebih banyak _free day_ buat dev — UI kit-nya sudah siap pakai.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.17.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.17.0)
+[![Release](https://img.shields.io/badge/release-v1.20.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.20.0)
 
 UI KIT yang token-driven & framework-agnostic — satu sumber kebenaran untuk warna, tipografi,
 spasi, dan komponen. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
 **Referensi hidup:** **[cahyo-dimas.github.io/freeday-ui-kit](https://cahyo-dimas.github.io/freeday-ui-kit/)** — atau buka `docs/index.html` langsung di browser.
 
 > 🚀 **Baru mau pakai di project?** Langkah demi langkah per stack (HTML · Vue · React · Blazor): **[`docs/getting-started.md`](docs/getting-started.md)**.
+>
+> 📘 **Class apa saja yang ada, dan markup-nya?** Seluruh permukaan publik dalam satu file:
+> **[`COMPONENTS.md`](COMPONENTS.md)**. **Kapan pakai yang mana:** **[`USAGE.md`](USAGE.md)**.
+> Satu layar utuh yang sudah dirakit: **[`docs/reference-screen.html`](docs/reference-screen.html)**.
+>
+> 🤖 **Ngoding pakai AI agent (atau vibe code)?** Tak ada model yang tahu Freeday dari training —
+> berikan **[`docs/agent-onboarding.md`](docs/agent-onboarding.md)** (blok instruksi siap-tempel +
+> tabel mapping migrasi).
 
 ## Build
 ```bash
@@ -49,8 +57,18 @@ ter-publish → install tanpa build step; minify diserahkan ke bundler konsumen.
 Kelas komponen berprefix `fdy-` (mis. `fdy-btn`, `fdy-card`, `fdy-badge`). Pakai langsung di
 markup framework apa pun — Vue, React, Blazor, atau HTML polos.
 
+> **⚠️ Muat font-nya sendiri — paket ini tidak.** Token tipe menamai **Sora** / **IBM Plex Sans** /
+> **JetBrains Mono** tapi Freeday tak membundel file font. Muat (mis. `@import '@fontsource/sora/700.css'`
+> …) atau override `--font-display`/`--font-body`/`--font-mono` — kalau tidak, kit jatuh ke fallback
+> sistem dan terlihat "belum jadi". Detail: [`docs/getting-started.md`](docs/getting-started.md).
+
+> **Token/role mana dipakai kapan → [`USAGE.md`](USAGE.md).** Freeday menjaga konsistensi *nilai*;
+> `USAGE.md` = doktrin yang menjaga konsistensi *keputusan* — role tipe (`.fdy-title-page/-section/-card`),
+> ritme spasi, elevasi, satu-primary-per-layar, palet kategorikal `--tone-1…8`, dan primitif komposisi
+> halaman (`.fdy-page`, `.fdy-page-section`, `.fdy-stats`). Tiap app mulai di `.fdy-app`.
+
 > **Scope: komponen + token, bukan layout.** Freeday punya komponen & design token; helper layout
-> cuma `.fdy-hidden` / `.fdy-visually-hidden`. Layout (stack/grid/gap) dari layer-mu sendiri —
+> cuma `.fdy-hidden` / `.fdy-visually-hidden` plus primitif komposisi di atas. Layout grid dari layer-mu sendiri —
 > pasangkan dengan utility framework (Tailwind, UnoCSS…) mode **utilities-only, preflight OFF**
 > (`base.css` Freeday = reset-nya). `base.css` itu reset *ringan* (tak me-reset margin `ul`/`ol`/`p` —
 > pakai `.fdy-list-reset` atau komponen list Freeday), dan skala spacing/radius/durasi adalah custom

package/README.md

@@ -5,13 +5,21 @@
 > **More free days for devs — the UI kit is ready to use.**
 
 [![Live docs](https://img.shields.io/badge/docs-live-2050d8?style=flat-square)](https://cahyo-dimas.github.io/freeday-ui-kit/)
-[![Release](https://img.shields.io/badge/release-v1.17.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.17.0)
+[![Release](https://img.shields.io/badge/release-v1.20.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.20.0)
 
 A token-driven, framework-agnostic UI kit — one source of truth for color, typography,
 spacing, and components. Blueprint: `docs/superpowers/specs/2026-07-21-freeday-ui-kit-design.md`.
 **Living reference:** **[cahyo-dimas.github.io/freeday-ui-kit](https://cahyo-dimas.github.io/freeday-ui-kit/)** — or open `docs/index.html` directly in a browser.
 
 > 🚀 **Starting a project?** Step-by-step per stack (HTML · Vue · React · Blazor): **[`docs/getting-started.md`](docs/getting-started.md)**.
+>
+> 📘 **Which class exists, and what's its markup?** The whole public surface in one flat file:
+> **[`COMPONENTS.md`](COMPONENTS.md)**. **Which one to reach for, and when:** **[`USAGE.md`](USAGE.md)**.
+> A full screen assembled: **[`docs/reference-screen.html`](docs/reference-screen.html)**.
+>
+> 🤖 **Building with an AI agent (or vibe-coding)?** No model knows Freeday from training — give it
+> **[`docs/agent-onboarding.md`](docs/agent-onboarding.md)** (paste-ready project instructions +
+> a migration mapping table).
 
 ## Build
 ```bash
@@ -49,13 +57,23 @@ bundler. Because it's on **public npm**, `npm ci` runs in CI without auth or an
 Component classes are prefixed `fdy-` (e.g. `fdy-btn`, `fdy-card`, `fdy-badge`). Use them directly
 in any framework's markup — Vue, React, Blazor, or plain HTML.
 
+> **⚠️ Load the fonts — the package doesn't.** The type tokens name **Sora** / **IBM Plex Sans** /
+> **JetBrains Mono** but Freeday bundles no font files. Load them (e.g. `@import '@fontsource/sora/700.css'`
+> …) or override `--font-display`/`--font-body`/`--font-mono` — otherwise the kit renders in the system
+> fallback and looks unfinished. See [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
+
+> **Which token/role to use when → [`USAGE.md`](USAGE.md).** Freeday enforces consistent *values*;
+> `USAGE.md` is the doctrine that also makes *decisions* consistent — type roles (`.fdy-title-page/-section/-card`),
+> spacing rhythm, elevation, one-primary-per-screen, the `--tone-1…8` categorical palette, and the page-
+> composition primitives (`.fdy-page`, `.fdy-page-section`, `.fdy-stats`). Every app starts in `.fdy-app`.
+
 > **Scope: components + tokens, not layout.** Freeday owns components and design tokens; the only
-> layout helpers are `.fdy-hidden` / `.fdy-visually-hidden`. Bring your own layout layer — pair it
-> with a utility framework (Tailwind, UnoCSS…) run **utilities-only with preflight OFF** (Freeday's
-> `base.css` is the reset). `base.css` is a *light* reset (it doesn't strip `ul`/`ol`/`p` margins —
-> use `.fdy-list-reset` or a Freeday list component), and the spacing/radius/duration scales are
-> public custom properties (`--space-0`…`--space-24`, …) you can build your utility theme on. Full
-> notes: [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
+> layout helpers are `.fdy-hidden` / `.fdy-visually-hidden` plus the page-composition primitives above.
+> Bring your own grid layer — pair it with a utility framework (Tailwind, UnoCSS…) run **utilities-only
+> with preflight OFF** (Freeday's `base.css` is the reset). `base.css` is a *light* reset (it doesn't
+> strip `ul`/`ol`/`p` margins — use `.fdy-list-reset` or a Freeday list component), and the
+> spacing/radius/duration scales are public custom properties (`--space-0`…`--space-24`, …) you can
+> build your utility theme on. Full notes: [`docs/getting-started.md` §Core concepts](docs/getting-started.md).
 
 > `.fdy-btn` is **already** the primary button — there's no separate `.fdy-btn--primary` modifier.
 > Modifiers for other variants: `--ghost`, `--danger`, `--text`, `--sm`, `--lg`, `--icon`
@@ -177,10 +195,16 @@ src/components/*.css    one file per component (fdy-*)
 src/*.js               optional JS enhancers (reference, vanilla)
 dist/                  build output (COMMITTED):
   freeday.tokens.css   semantic tokens (light/dark/compact)
-  freeday.css          bundle of every component
+  freeday.css          every component (NO tokens)
+  freeday.bundle.css   tokens + components — link this one
   freeday.js           bundle of every enhancer (single <script>)
   freeday-*.js         per-file enhancers
+COMPONENTS.md          every class + markup skeleton + a11y contract
+USAGE.md               the usage doctrine (which token/role when)
 docs/index.html        living reference / demo site
+docs/reference-screen.html  one complete screen, assembled
+docs/agent-onboarding.md    onboarding for AI coding agents
+reference/             input material, never shipped (port source + layout archetypes)
 ```
 
 ## Component inventory

package/USAGE.md

@@ -0,0 +1,127 @@
+# Freeday — Usage doctrine
+
+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 —
+but start here, not from a blank page.
+
+---
+
+## 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:
+
+| Role | Class | When |
+|---|---|---|
+| Eyebrow | `.fdy-eyebrow` | A small uppercase label above a page/section title. Optional. |
+| Page title | `.fdy-title-page` | One per screen. The `<h1>`. |
+| Section title | `.fdy-title-section` | A region within the page (`<h2>`). |
+| Card / row title | `.fdy-title-card` (or `.fdy-card__title`) | A title inside a card or list row (`<h3>`). |
+| Body | *(default)* | Running text. |
+| Muted / caption | `.fdy-text-muted`, `.fdy-text-caption` | Secondary text, timestamps, help. |
+
+Everything else is body. If you reach for a fourth title size, you probably need a section, not a
+font size.
+
+## 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.
+- **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.
+
+## 3. Elevation — most surfaces are flat
+
+Shadow is a signal, not decoration. There are two families, and the difference matters:
+
+| Level | Token | What actually uses it |
+|---|---|---|
+| Flat | *(none)* | Page sections, `.fdy-page`, the app shell, `.fdy-toolbar` |
+| Hairline | `--shadow-1` | Bordered data containers: `.fdy-list`, `.fdy-table-wrap`, `.fdy-datatable`, `.fdy-stats--boxed` |
+| Raised | `--shadow-2` | `.fdy-tooltip`, `.fdy-appbar--elevated` |
+| Floating | `--shadow-3` | Things that float over the page: `.fdy-menu`, `.fdy-filter`, `.fdy-toast`, `.fdy-fab` |
+| 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×
+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
+"identical card grid" failure. Prefer flat sections with **one** raised element that matters.
+
+## 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
+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`
+
+- **Accent** (`--color-primary`, and `--color-accent` sparingly): interactive + brand. This is your
+  one accent hue.
+- **Semantic is reserved** and is *not* your accent: `--color-success` = good only, `--color-warning`
+  = 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.
+  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.
+
+## 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
+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.
+
+## 7. Assemble the page from the frame down
+
+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:
+   `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
+   `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
+   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
+`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.*

package/adapters/blazor/FdyTable.razor.cs

@@ -29,6 +29,24 @@ public partial class FdyTable<TRow>
     /// <summary>Client-side page size when <see cref="Page"/> is absent; 0 = render all rows (no pager).</summary>
     [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
+    /// 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).
+    /// </summary>
+    [Parameter] public int? PageIndex { get; set; }
+
+    /// <summary>Raised in client mode with <see cref="PageIndex"/> set: the table asks for a new
+    /// 0-based index (pager click, reset to 0 after sort/filter, or a clamp after filtering).</summary>
+    [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
+    /// export without re-deriving the pipeline. Mirrors <c>process</c> in the Vue/React adapters.</summary>
+    [Parameter] public EventCallback<FdyTableProcess<TRow>> Process { get; set; }
+
     [Parameter] public bool Loading { get; set; }
     [Parameter] public string LoadingText { get; set; } = "Loading…";
     [Parameter] public string EmptyText { get; set; } = "No data";
@@ -55,10 +73,19 @@ public partial class FdyTable<TRow>
 
     private List<TRow> _displayRows = new();
     private int _totalCount;
+    // Recompute() is synchronous (it runs from OnParametersSet), but notifying the parent is async.
+    // Both notifications are therefore queued here and flushed in OnAfterRenderAsync.
+    private int? _pendingClamp;
+    private bool _processDirty;
 
     private static readonly IReadOnlyDictionary<string, FdyColumnFilter> EmptyFilters = new Dictionary<string, FdyColumnFilter>();
 
     private bool ServerPaged => Page is not null;
+
+    // Client-side page index: the parameter when the parent owns it, the field otherwise. Every read
+    // goes through ClientPageIndex and every write through SetClientPageAsync.
+    private bool PageIndexControlled => PageIndex is not null;
+    private int ClientPageIndex => PageIndexControlled ? Math.Max(0, PageIndex!.Value) : _internalPageIndex;
     private bool SortControlled => ServerPaged || SortChanged.HasDelegate;
     private bool FiltersControlled => ServerPaged || FiltersChanged.HasDelegate;
 
@@ -67,7 +94,7 @@ public partial class FdyTable<TRow>
         FiltersControlled ? (Filters ?? EmptyFilters) : _internalFilters;
 
     private int PageSizeEff => ServerPaged ? Page!.Size : PageSize;
-    private int CurrentPage1 => (ServerPaged ? Page!.Index : _internalPageIndex) + 1;
+    private int CurrentPage1 => (ServerPaged ? Page!.Index : ClientPageIndex) + 1;
     private int TotalCount => _totalCount;
     private int TotalPages => PageSizeEff > 0 ? Math.Max(1, (int)Math.Ceiling((double)TotalCount / PageSizeEff)) : 1;
     private bool HasPager => PageSizeEff > 0 && TotalPages > 1;
@@ -77,6 +104,20 @@ public partial class FdyTable<TRow>
 
     protected override void OnParametersSet() => Recompute();
 
+    protected override async Task OnAfterRenderAsync(bool firstRender)
+    {
+        if (_pendingClamp is int clamp)
+        {
+            _pendingClamp = null;
+            await PageIndexChanged.InvokeAsync(clamp);
+        }
+        if (_processDirty)
+        {
+            _processDirty = false;
+            if (Process.HasDelegate) await Process.InvokeAsync(new FdyTableProcess<TRow>(_displayRows, _totalCount));
+        }
+    }
+
     // Recompute the visible rows from the current effective sort/filter/page. Called on every
     // parameter change and after any internal-state mutation (sort/filter/page click).
     private void Recompute()
@@ -91,13 +132,19 @@ public partial class FdyTable<TRow>
         {
             // Keep the page in range when a filter shrank the row set.
             int tp = Math.Max(1, (int)Math.Ceiling((double)_totalCount / PageSize));
-            if (_internalPageIndex > tp - 1) _internalPageIndex = Math.Max(0, tp - 1);
-            _displayRows = TableModel.Paginate(filteredSorted, _internalPageIndex, PageSize);
+            if (ClientPageIndex > tp - 1)
+            {
+                if (PageIndexControlled) _pendingClamp = Math.Max(0, tp - 1);
+                else _internalPageIndex = Math.Max(0, tp - 1);
+            }
+            _displayRows = TableModel.Paginate(filteredSorted, Math.Min(ClientPageIndex, tp - 1), PageSize);
         }
         else
         {
             _displayRows = filteredSorted;
         }
+
+        _processDirty = true;
     }
 
     private FdyColumnFilter? GetFilter(string key) => EffectiveFilters.TryGetValue(key, out FdyColumnFilter? f) ? f : null;
@@ -126,8 +173,7 @@ public partial class FdyTable<TRow>
         else
         {
             _internalSort = next;
-            _internalPageIndex = 0;
-            Recompute();
+            await SetClientPageAsync(0);
         }
     }
 
@@ -143,8 +189,7 @@ public partial class FdyTable<TRow>
         else
         {
             _internalFilters = next;
-            _internalPageIndex = 0;
-            Recompute();
+            await SetClientPageAsync(0);
         }
     }
 
@@ -157,6 +202,20 @@ public partial class FdyTable<TRow>
             await PageChanged.InvokeAsync(new FdyPageState(index0, Page!.Size, Page.Total));
         }
         else
+        {
+            await SetClientPageAsync(index0);
+        }
+    }
+
+    // One write path for the client index: ask the parent when controlled, mutate the field when not.
+    private async Task SetClientPageAsync(int index0)
+    {
+        if (PageIndexControlled)
+        {
+            if (index0 != PageIndex) await PageIndexChanged.InvokeAsync(index0);
+            else Recompute();
+        }
+        else
         {
             _internalPageIndex = index0;
             Recompute();

package/adapters/blazor/TableTypes.cs

@@ -21,6 +21,12 @@ public sealed record FdySortState(string Key, FdySortDir Dir);
 /// <see cref="FdyTable{TRow}.Page"/> switches the table into server mode.</summary>
 public sealed record FdyPageState(int Index, int Size, int Total);
 
+/// <summary>The processed page of rows (after filter/sort/paginate) plus the total row count, as
+/// raised by <see cref="FdyTable{TRow}.Process"/>. Lets a consumer render the same processed set
+/// somewhere else — a card list below the <c>md</c> breakpoint, a summary, an export — without
+/// re-deriving the pipeline. Mirrors the <c>process</c> event in the Vue/React adapters.</summary>
+public sealed record FdyTableProcess<TRow>(IReadOnlyList<TRow> Rows, int Total);
+
 /// <summary>The active filter for a single column (a closed set of shapes, one per filter type).</summary>
 public abstract record FdyColumnFilter
 {

package/adapters/react/components/FdyTable.tsx

@@ -44,6 +44,17 @@ export interface FdyTableProps<Row extends object> {
   onPageChange?: (page: FdyPageState) => void;
   /** Client-side page size when `page` is absent; 0/undefined = render all rows (no pager). */
   pageSize?: number;
+  /**
+   * Controlled client-side page index (0-based). Provide it — with `pageSize`, without `page` — to
+   * own the page while the table keeps doing filter/sort/paginate. This is what lets an EXTERNAL
+   * pager drive the table: a responsive screen that hides `.fdy-datatable` below `md` and renders a
+   * card list from `onProcess` can render one pager for both breakpoints and point it here.
+   * Omit for the internal index (unchanged default).
+   */
+  pageIndex?: number;
+  /** Client mode with `pageIndex` provided: the table asks for a new 0-based index (pager click, a
+   *  reset to 0 after sort/filter, or a clamp when filtering shrank the set). */
+  onPageIndexChange?: (index: number) => void;
   loading?: boolean;
   emptyText?: string;
   ariaLabel?: string;
@@ -57,6 +68,10 @@ export interface FdyTableProps<Row extends object> {
   rowClass?: (row: Row) => string | undefined;
   /** A row was activated (click, or Enter/Space while the row itself is focused). */
   onRowActivate?: (row: Row) => void;
+  /** Called with the processed page of rows (after filter/sort/paginate) plus the total row count —
+   *  in BOTH modes, whenever they change. Lets a consumer render the SAME processed set elsewhere
+   *  (a `< md` card list, a "selected" summary, export-to-CSV) without re-deriving the pipeline. */
+  onProcess?: (result: { rows: Row[]; total: number }) => void;
   /** Controlled: row keys whose detail is shown as a full-width row beneath them. */
   expandedKeys?: ReadonlyArray<string | number>;
   /** Renders the expandable detail row for an expanded row (React equivalent of Vue's `row-detail` slot). */
@@ -91,14 +106,26 @@ export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Ele
 
   const totalCount: number = serverPaged ? (props.page as FdyPageState).total : filteredSorted.length;
 
+  /* Client-side page index: the prop when the parent owns it, internal state otherwise. Every read
+   * goes through clientPageIndex and every write through setClientPage, so controlled and
+   * uncontrolled behave identically apart from where the number lives. */
+  const pageIndexControlled: boolean = props.pageIndex !== undefined;
+  const clientPageIndex: number = pageIndexControlled ? Math.max(0, props.pageIndex as number) : internalPageIndex;
+  const onPageIndexChange = props.onPageIndexChange;
+  function setClientPage(index0: number): void {
+    if (pageIndexControlled) {
+      if (index0 !== props.pageIndex) onPageIndexChange?.(index0);
+    } else setInternalPageIndex(index0);
+  }
+
   const displayRows: Row[] = useMemo(() => {
     if (serverPaged) return props.rows.slice();
-    if (props.pageSize && props.pageSize > 0) return paginate(filteredSorted, internalPageIndex, props.pageSize);
+    if (props.pageSize && props.pageSize > 0) return paginate(filteredSorted, clientPageIndex, props.pageSize);
     return filteredSorted;
-  }, [serverPaged, props.rows, props.pageSize, filteredSorted, internalPageIndex]);
+  }, [serverPaged, props.rows, props.pageSize, filteredSorted, clientPageIndex]);
 
   const pageSizeEff: number = serverPaged ? (props.page as FdyPageState).size : (props.pageSize ?? 0);
-  const currentPage1: number = (serverPaged ? (props.page as FdyPageState).index : internalPageIndex) + 1;
+  const currentPage1: number = (serverPaged ? (props.page as FdyPageState).index : clientPageIndex) + 1;
   const totalPages: number = pageSizeEff > 0 ? Math.max(1, Math.ceil(totalCount / pageSizeEff)) : 1;
   const hasPager: boolean = pageSizeEff > 0 && totalPages > 1;
   const pages: Array<number | 'ellipsis'> = pageWindow(currentPage1, totalPages);
@@ -107,8 +134,16 @@ export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Ele
 
   // Client mode: keep the page in range when a filter shrinks the row set.
   useEffect((): void => {
-    if (!serverPaged && internalPageIndex > totalPages - 1) setInternalPageIndex(Math.max(0, totalPages - 1));
-  }, [serverPaged, internalPageIndex, totalPages]);
+    if (!serverPaged && clientPageIndex > totalPages - 1) setClientPage(Math.max(0, totalPages - 1));
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- setClientPage is derived from these
+  }, [serverPaged, clientPageIndex, totalPages]);
+
+  // Surface the processed page + total to the parent (both modes), so the same result can drive a
+  // responsive card list / summary / export without re-implementing filter/sort/paginate.
+  const onProcess = props.onProcess;
+  useEffect((): void => {
+    onProcess?.({ rows: displayRows, total: totalCount });
+  }, [onProcess, displayRows, totalCount]);
 
   function ariaSortOf(col: FdyTableColumn<Row>): 'ascending' | 'descending' | undefined {
     if (effectiveSort === null || effectiveSort.key !== col.key) return undefined;
@@ -123,7 +158,7 @@ export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Ele
     if (sortControlled) props.onSortChange?.(next);
     else {
       setInternalSort(next);
-      setInternalPageIndex(0);
+      setClientPage(0);
     }
   }
   function onFilterChange(col: FdyTableColumn<Row>, filter: FdyColumnFilter | null): void {
@@ -133,7 +168,7 @@ export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Ele
     if (filtersControlled) props.onFiltersChange?.(nextMap);
     else {
       setInternalFilters(nextMap);
-      setInternalPageIndex(0);
+      setClientPage(0);
     }
   }
   function goTo(page1: number): void {
@@ -143,7 +178,7 @@ export function FdyTable<Row extends object>(props: FdyTableProps<Row>): JSX.Ele
       const p: FdyPageState = props.page as FdyPageState;
       props.onPageChange?.({ index: index0, size: p.size, total: p.total });
     } else {
-      setInternalPageIndex(index0);
+      setClientPage(index0);
     }
   }
 

package/adapters/vue/components/FdyDrawer.vue

@@ -8,12 +8,15 @@ import { computed, onMounted, useId, watch, type ComputedRef, type Ref, ref } fr
 // focus trap, focus restore, top-layer stacking and inert background; `dismissible` (default true)
 // gates Esc + backdrop dismissal.
 
-const props = defineProps<{
+// dismissible MUST go through withDefaults: Vue's boolean-cast gives an omitted Boolean prop
+// `false`, not `undefined`, so a bare `props.dismissible !== false` would make an un-annotated
+// drawer non-dismissible (no Esc, no backdrop, no close button) — the opposite of the default.
+const props = withDefaults(defineProps<{
   open: boolean;
   title: string;
   side?: 'left' | 'right';
   dismissible?: boolean;
-}>();
+}>(), { dismissible: true });
 
 const emit = defineEmits<{
   close: [];

package/adapters/vue/components/FdyModal.vue

@@ -10,12 +10,15 @@ import { computed, onMounted, useId, watch, type ComputedRef, type Ref, ref } fr
 // Native <dialog> already provides the focus trap, focus restore, top-layer stacking and inert
 // background — the wrapper only avoids breaking them. `dismissible` (default true) gates Esc + backdrop.
 
-const props = defineProps<{
+// dismissible MUST go through withDefaults: Vue's boolean-cast gives an omitted Boolean prop
+// `false`, not `undefined`, so a bare `props.dismissible !== false` would make an un-annotated
+// modal non-dismissible (no Esc, no backdrop, no close button) — the opposite of the default.
+const props = withDefaults(defineProps<{
   open: boolean;
   title: string;
   size?: 'sm' | 'md' | 'lg' | 'wide';
   dismissible?: boolean;
-}>();
+}>(), { dismissible: true });
 
 const emit = defineEmits<{
   close: [];

package/adapters/vue/components/FdyTable.vue

@@ -41,6 +41,14 @@ const props = defineProps<{
   page?: FdyPageState;
   /** Client-side page size when `page` is absent; 0/undefined = render all rows (no pager). */
   pageSize?: number;
+  /**
+   * Controlled client-side page index (0-based). Provide it — with `pageSize`, without `page` — to
+   * own the page while the table keeps doing filter/sort/paginate. This is what lets an EXTERNAL
+   * pager drive the table: a responsive screen that hides `.fdy-datatable` below `md` and renders a
+   * card list from the `process` event can render one pager for both breakpoints and point it here.
+   * Omit for the internal index (unchanged default).
+   */
+  pageIndex?: number;
   loading?: boolean;
   emptyText?: string;
   ariaLabel?: string;
@@ -56,8 +64,15 @@ const emit = defineEmits<{
   'update:sort': [sort: FdySortState | null];
   'update:filters': [filters: FdyFilterMap];
   'update:page': [page: FdyPageState];
+  /** Client mode with `pageIndex` provided: the table asks for a new 0-based index (pager click, or
+   *  a reset to 0 after sort/filter, or a clamp when filtering shrank the set). */
+  'update:pageIndex': [index: number];
   /** A row was activated (click, or Enter/Space while the row itself is focused). */
   'row-activate': [row: Row];
+  /** The processed page of rows (after filter/sort/paginate) plus the total row count — fires in
+   *  BOTH modes whenever they change. Lets a consumer render the SAME processed set elsewhere
+   *  (a `< md` card list, a "selected" summary, export-to-CSV) without re-deriving the pipeline. */
+  'process': [result: { rows: Row[]; total: number }];
 }>();
 
 const internalSort: Ref<FdySortState | null> = ref(null);
@@ -94,9 +109,22 @@ const filteredSorted: ComputedRef<Row[]> = computed((): Row[] => {
 const totalCount: ComputedRef<number> = computed((): number =>
   serverPaged.value ? (props.page as FdyPageState).total : filteredSorted.value.length,
 );
+/* Client-side page index: the prop when the parent owns it, the internal ref otherwise. Every read
+ * goes through clientPageIndex and every write through setClientPage, so controlled and uncontrolled
+ * behave identically apart from where the number lives. */
+const pageIndexControlled: ComputedRef<boolean> = computed((): boolean => props.pageIndex !== undefined);
+const clientPageIndex: ComputedRef<number> = computed((): number =>
+  pageIndexControlled.value ? Math.max(0, props.pageIndex as number) : internalPageIndex.value,
+);
+function setClientPage(index0: number): void {
+  if (pageIndexControlled.value) {
+    if (index0 !== props.pageIndex) emit('update:pageIndex', index0);
+  } else internalPageIndex.value = index0;
+}
+
 const displayRows: ComputedRef<Row[]> = computed((): Row[] => {
   if (serverPaged.value) return props.rows.slice();
-  if (props.pageSize && props.pageSize > 0) return paginate(filteredSorted.value, internalPageIndex.value, props.pageSize);
+  if (props.pageSize && props.pageSize > 0) return paginate(filteredSorted.value, clientPageIndex.value, props.pageSize);
   return filteredSorted.value;
 });
 
@@ -104,7 +132,7 @@ const pageSizeEff: ComputedRef<number> = computed((): number =>
   serverPaged.value ? (props.page as FdyPageState).size : (props.pageSize ?? 0),
 );
 const currentPage1: ComputedRef<number> = computed((): number =>
-  (serverPaged.value ? (props.page as FdyPageState).index : internalPageIndex.value) + 1,
+  (serverPaged.value ? (props.page as FdyPageState).index : clientPageIndex.value) + 1,
 );
 const totalPages: ComputedRef<number> = computed((): number =>
   pageSizeEff.value > 0 ? Math.max(1, Math.ceil(totalCount.value / pageSizeEff.value)) : 1,
@@ -122,9 +150,17 @@ const rangeTo: ComputedRef<number> = computed((): number =>
 
 // Client mode: keep the page in range when a filter shrinks the row set.
 watch(totalPages, (tp: number): void => {
-  if (!serverPaged.value && internalPageIndex.value > tp - 1) internalPageIndex.value = Math.max(0, tp - 1);
+  if (!serverPaged.value && clientPageIndex.value > tp - 1) setClientPage(Math.max(0, tp - 1));
 });
 
+// Surface the processed page + total to the parent (both modes), so the same result can drive a
+// responsive card list / summary / export without re-implementing filter/sort/paginate.
+watch(
+  [displayRows, totalCount],
+  (): void => emit('process', { rows: displayRows.value, total: totalCount.value }),
+  { immediate: true },
+);
+
 function ariaSortOf(col: FdyTableColumn<Row>): 'ascending' | 'descending' | undefined {
   const s: FdySortState | null = effectiveSort.value;
   if (s === null || s.key !== col.key) return undefined;
@@ -140,7 +176,7 @@ function onSort(col: FdyTableColumn<Row>): void {
   if (sortControlled.value) emit('update:sort', next);
   else {
     internalSort.value = next;
-    internalPageIndex.value = 0;
+    setClientPage(0);
   }
 }
 function onFilterChange(col: FdyTableColumn<Row>, filter: FdyColumnFilter | null): void {
@@ -150,7 +186,7 @@ function onFilterChange(col: FdyTableColumn<Row>, filter: FdyColumnFilter | null
   if (filtersControlled.value) emit('update:filters', nextMap);
   else {
     internalFilters.value = nextMap;
-    internalPageIndex.value = 0;
+    setClientPage(0);
   }
 }
 function goTo(page1: number): void {
@@ -160,7 +196,7 @@ function goTo(page1: number): void {
     const p: FdyPageState = props.page as FdyPageState;
     emit('update:page', { index: index0, size: p.size, total: p.total });
   } else {
-    internalPageIndex.value = index0;
+    setClientPage(index0);
   }
 }