@cahyo-dimas/freeday 1.18.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.18.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.18.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

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.18.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.18.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
@@ -187,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

@@ -41,12 +41,22 @@ empty state). Don't scatter `--space-6` everywhere — a page with one gap value
 
 ## 3. Elevation — most surfaces are flat
 
-Shadow is a signal, not decoration. Spend it sparingly:
+Shadow is a signal, not decoration. There are two families, and the difference matters:
 
-- **Flat** (no shadow, border only, or nothing): the default. Page sections, list rows, the app shell.
-- **`--shadow-1`:** a card that is a distinct object you could pick up — a workspace tile, a panel.
-- **`--shadow-2`/`3`:** something that *floats over* the page — a popover, menu, or dropdown.
-- **`--shadow-4`:** a modal / drawer overlay only.
+| 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.
@@ -74,21 +84,34 @@ point, everything around it quiet.
 
 ## 6. Density — `compact` for data-dense screens
 
-`data-density="compact"` on `<html>` tightens control height **and** the mid-range spacing scale
+`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 and marketing-adjacent
-pages. Set it once at the app root, not per component.
+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`** (`__topbar`, `__sidebar`, `__main`,
-   `__content`, `__navtoggle`, `__backdrop`). Don't hand-roll a shell from flexbox — the toggle and
-   backdrop plumbing are already there. See `docs/getting-started.md`.
+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.

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;
@@ -95,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);
@@ -111,8 +134,9 @@ 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.
@@ -134,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 {
@@ -144,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 {
@@ -154,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/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,6 +64,9 @@ 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
@@ -98,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;
 });
 
@@ -108,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,
@@ -126,7 +150,7 @@ 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
@@ -152,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 {
@@ -162,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 {
@@ -172,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);
   }
 }
 

package/dist/freeday.bundle.css

@@ -347,7 +347,11 @@
   --chart-tick: var(--slate-400);
   --focus-ring: var(--azure-600);
 }
-:root[data-density="compact"] {
+/* Density is deliberately NOT scoped to :root. These are custom properties, so they inherit —
+ * putting the attribute on any ancestor (a route wrapper, one section) densifies just that
+ * subtree, which is how density is actually decided: per screen, not per app. The root still
+ * matches, so setting data-density on the html element keeps working exactly as before. */
+[data-density="compact"] {
   --space-3: 0.625rem;
   --space-4: 0.75rem;
   --space-5: 1rem;
@@ -1184,6 +1188,36 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 /* Freeday — Keyboard key */
 .fdy-kbd{display:inline-flex;align-items:center;justify-content:center;min-width:1.5rem;height:1.5rem;padding:0 var(--space-2);font-family:var(--font-mono);font-size:var(--text-xs);color:var(--color-text);background:var(--color-surface-2);border:var(--bw) solid var(--color-border-strong);border-bottom-width:2px;border-radius:var(--radius-sm);}
 
+/* Freeday — List: the FLAT row container.
+ *
+ * USAGE.md §3 puts list rows among the surfaces that should be flat, but until now the only
+ * container the kit shipped was .fdy-card — which carries --shadow-lift (a real 34px lift). A
+ * responsive table that becomes a list below `md` therefore had to choose between a stack of
+ * shadowed cards (against the doctrine) or a hand-built box, which needs a colour and so escapes
+ * the token system. This is that missing container: one flat surface, hairline dividers, no shadow.
+ *
+ * Not to be confused with .fdy-list-reset (base.css), which only strips UA bullets/indent.
+ * Works on <ul>/<ol> (list-style is reset here) or on plain <div>s. */
+.fdy-list{list-style:none;margin:0;padding:0;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;}
+.fdy-list__row{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);min-width:0;}
+/* Divider between rows. Two shapes are supported and both are load-bearing: rows as direct children
+ * of the list, and rows wrapped in <li> (the semantic shape, where the ADJACENT siblings are the
+ * <li>s — a bare `.fdy-list__row + .fdy-list__row` silently matches nothing there). */
+.fdy-list__row + .fdy-list__row,
+.fdy-list > * + * > .fdy-list__row{border-top:var(--bw) solid var(--color-border-muted);}
+/* A row that is itself the control: render it as <button>/<a> and the UA box is reset without
+ * touching the list surface (same contract as .fdy-card--button). */
+.fdy-list__row--button{width:100%;text-align:inherit;color:inherit;font:inherit;background:none;border:0;appearance:none;-webkit-appearance:none;cursor:pointer;}
+.fdy-list__row--button:hover,.fdy-list__row--interactive:hover{background:var(--color-surface-2);}
+.fdy-list__row--button:focus-visible{outline:none;box-shadow:inset 0 0 0 2px var(--color-primary);}
+.fdy-list__row--interactive{cursor:pointer;}
+/* Row internals: a title/meta stack that truncates, and a trailing slot pinned right. */
+.fdy-list__main{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;flex:1;}
+.fdy-list__title{font-weight:var(--weight-medium);color:var(--color-text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.fdy-list__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);flex-wrap:wrap;}
+.fdy-list__aside{flex:none;display:flex;align-items:center;gap:var(--space-2);}
+/* Density: rows tighten with the rest of the kit (--space-* mid-range steps under compact). */
+
 /* Freeday — Menu (action popup) + Split button. Enhanced by freeday-menu.js. */
 .fdy-menu-wrap{position:relative;display:inline-flex;}
 .fdy-menu{position:absolute;top:calc(100% + var(--space-1));left:0;z-index:130;min-width:11rem;margin:0;padding:var(--space-1);list-style:none;background:var(--color-surface);color:var(--color-text);border:var(--bw) solid var(--color-border-strong);border-radius:var(--radius-md);box-shadow:var(--shadow-3);}

package/dist/freeday.css

@@ -827,6 +827,36 @@ fieldset.fdy-field>legend{padding:0;float:none;}
 /* Freeday — Keyboard key */
 .fdy-kbd{display:inline-flex;align-items:center;justify-content:center;min-width:1.5rem;height:1.5rem;padding:0 var(--space-2);font-family:var(--font-mono);font-size:var(--text-xs);color:var(--color-text);background:var(--color-surface-2);border:var(--bw) solid var(--color-border-strong);border-bottom-width:2px;border-radius:var(--radius-sm);}
 
+/* Freeday — List: the FLAT row container.
+ *
+ * USAGE.md §3 puts list rows among the surfaces that should be flat, but until now the only
+ * container the kit shipped was .fdy-card — which carries --shadow-lift (a real 34px lift). A
+ * responsive table that becomes a list below `md` therefore had to choose between a stack of
+ * shadowed cards (against the doctrine) or a hand-built box, which needs a colour and so escapes
+ * the token system. This is that missing container: one flat surface, hairline dividers, no shadow.
+ *
+ * Not to be confused with .fdy-list-reset (base.css), which only strips UA bullets/indent.
+ * Works on <ul>/<ol> (list-style is reset here) or on plain <div>s. */
+.fdy-list{list-style:none;margin:0;padding:0;background:var(--color-surface);border:var(--bw) solid var(--color-border);border-radius:var(--radius-lg);overflow:hidden;}
+.fdy-list__row{display:flex;align-items:center;gap:var(--space-3);padding:var(--space-4) var(--space-5);min-width:0;}
+/* Divider between rows. Two shapes are supported and both are load-bearing: rows as direct children
+ * of the list, and rows wrapped in <li> (the semantic shape, where the ADJACENT siblings are the
+ * <li>s — a bare `.fdy-list__row + .fdy-list__row` silently matches nothing there). */
+.fdy-list__row + .fdy-list__row,
+.fdy-list > * + * > .fdy-list__row{border-top:var(--bw) solid var(--color-border-muted);}
+/* A row that is itself the control: render it as <button>/<a> and the UA box is reset without
+ * touching the list surface (same contract as .fdy-card--button). */
+.fdy-list__row--button{width:100%;text-align:inherit;color:inherit;font:inherit;background:none;border:0;appearance:none;-webkit-appearance:none;cursor:pointer;}
+.fdy-list__row--button:hover,.fdy-list__row--interactive:hover{background:var(--color-surface-2);}
+.fdy-list__row--button:focus-visible{outline:none;box-shadow:inset 0 0 0 2px var(--color-primary);}
+.fdy-list__row--interactive{cursor:pointer;}
+/* Row internals: a title/meta stack that truncates, and a trailing slot pinned right. */
+.fdy-list__main{display:flex;flex-direction:column;gap:var(--space-1);min-width:0;flex:1;}
+.fdy-list__title{font-weight:var(--weight-medium);color:var(--color-text);overflow:hidden;text-overflow:ellipsis;white-space:nowrap;}
+.fdy-list__meta{font-size:var(--text-sm);color:var(--color-text-muted);display:flex;align-items:center;gap:var(--space-2);flex-wrap:wrap;}
+.fdy-list__aside{flex:none;display:flex;align-items:center;gap:var(--space-2);}
+/* Density: rows tighten with the rest of the kit (--space-* mid-range steps under compact). */
+
 /* Freeday — Menu (action popup) + Split button. Enhanced by freeday-menu.js. */
 .fdy-menu-wrap{position:relative;display:inline-flex;}
 .fdy-menu{position:absolute;top:calc(100% + var(--space-1));left:0;z-index:130;min-width:11rem;margin:0;padding:var(--space-1);list-style:none;background:var(--color-surface);color:var(--color-text);border:var(--bw) solid var(--color-border-strong);border-radius:var(--radius-md);box-shadow:var(--shadow-3);}

package/dist/freeday.tokens.css

@@ -346,7 +346,11 @@
   --chart-tick: var(--slate-400);
   --focus-ring: var(--azure-600);
 }
-:root[data-density="compact"] {
+/* Density is deliberately NOT scoped to :root. These are custom properties, so they inherit —
+ * putting the attribute on any ancestor (a route wrapper, one section) densifies just that
+ * subtree, which is how density is actually decided: per screen, not per app. The root still
+ * matches, so setting data-density on the html element keeps working exactly as before. */
+[data-density="compact"] {
   --space-3: 0.625rem;
   --space-4: 0.75rem;
   --space-5: 1rem;