@cahyo-dimas/freeday 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 Semua perubahan penting dicatat di sini. Format longgar mengikuti
 [Keep a Changelog](https://keepachangelog.com/); tiap versi = git tag.
 
+## [1.8.0] — 2026-07-28
+Release **1.8 — framework-safe data table, modal/drawer wrappers, and a monospace utility**.
+Non-breaking, purely additive. No existing selector, markup, or enhancer changed.
+
+### Added
+- **`FdyTable` (Vue + React) — a controlled data table.** Reads `rows` as the source of truth on
+  every render, so it is safe over a `v-for` / `.map()` bound to reactive data — unlike the
+  `freeday-table.js` enhancer, which snapshots the DOM and corrupts a framework list on the first
+  refetch. Two modes: **client** (component sorts/filters, and paginates when `pageSize` is set,
+  over the full `rows`) and **server** (`page` prop present → `rows` render as given and the
+  headers/filters/pager only emit `update:sort` / `update:filters` / `update:page`). Type-aware
+  column filters (**text / enum / number / date**) in a top-layer popover, sort toggles, and a
+  page-window pager — all over the existing `.fdy-table*` / `.fdy-filter*` / `.fdy-pagination__*`
+  classes. Column options: `sortable`, `filter`, `align`, `mono`, `sortType`, `value`, `options`.
+  Sort/filter/paginate logic lives in a shared, framework-agnostic core (`adapters/core/table-model.js`)
+  covered by `node --test` (`test/table-model.test.mjs`).
+- **`FdyModal` + `FdyDrawer` (Vue + React) — controlled `<dialog>` wrappers.** Reconcile a reactive
+  `open` boolean with the native `<dialog>`'s method-driven open/close: guarded
+  `showModal()`/`close()`, `@cancel`/`onCancel` + `preventDefault` so Esc routes through app state,
+  and backdrop-click via `event.target === dialogEl`. `open` + `close` event/`onClose`, `title`,
+  `size`/`side`, `dismissible` (default true), and `footer`. No new modal CSS.
+- **`.fdy-mono` utility.** Alignment-neutral monospace (data font + tabular figures) for identifier /
+  code / IP / timestamp cells or inline spans — the piece that previously only existed welded into
+  the right-aligned `.fdy-table__num`. `FdyTable` applies it for any `mono: true` column.
+- **`.fdy-drawer__footer`** — a bottom action bar for drawers (mirrors `.fdy-modal__footer`).
+
 ## [1.7.1] — 2026-07-27
 Docs & distribution patch. **No component/code changes** — `dist/`, `src/`, `adapters/`, and
 `tokens/` are byte-identical to 1.7.0.

package/README.id.md

@@ -5,7 +5,7 @@
 > **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.7.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.7.1)
+[![Release](https://img.shields.io/badge/release-v1.8.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.8.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`.

package/README.md

@@ -5,7 +5,7 @@
 > **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.7.1-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.7.1)
+[![Release](https://img.shields.io/badge/release-v1.8.0-0078d4?style=flat-square)](https://github.com/cahyo-dimas/freeday-ui-kit/tree/v1.8.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`.

package/adapters/core/table-model.d.ts

@@ -0,0 +1,78 @@
+// Types for the framework-agnostic table model (adapters/core/table-model.js).
+// Shared by FdyTable in both the Vue and React adapters.
+
+export type FdySortDir = 'asc' | 'desc';
+
+/** Which column is sorted and in what direction. */
+export interface FdySortState {
+  key: string;
+  dir: FdySortDir;
+}
+
+/** A column's comparator type — how its values are ordered when sorting. */
+export type FdyColumnType = 'text' | 'number' | 'date';
+
+/** Cell alignment. Maps to `text-align` on the header and body cells. */
+export type FdyColumnAlign = 'left' | 'right' | 'center';
+
+/** The kind of column filter to offer (a funnel popover in the header). */
+export type FdyColumnFilterType = 'text' | 'enum' | 'number' | 'date';
+
+/** One column definition. `T` is the row type. */
+export interface FdyTableColumn<T> {
+  /** Row property key; also the default cell accessor and the filter/sort identity. */
+  key: string;
+  /** Header label. */
+  label: string;
+  /** Show a sort toggle in the header. */
+  sortable?: boolean;
+  /** Offer a column filter of this type. */
+  filter?: FdyColumnFilterType;
+  /** Cell alignment (default left). */
+  align?: FdyColumnAlign;
+  /** Render cells in the monospace data font (`.fdy-mono`). */
+  mono?: boolean;
+  /** Override the comparator type; defaults to one derived from `filter`, else 'text'. */
+  sortType?: FdyColumnType;
+  /** Custom value accessor; defaults to `row[key]`. Used for sort, filter, and default cell text. */
+  value?: (row: T) => unknown;
+  /** Explicit options for an enum filter; defaults to the distinct values in the current rows.
+   *  Provide this in server-paged mode, where the rows on screen are only one page. */
+  options?: ReadonlyArray<string>;
+}
+
+/** The active filter for a single column. */
+export type FdyColumnFilter =
+  | { type: 'text'; text: string }
+  | { type: 'enum'; values: readonly string[] }
+  | { type: 'number'; min: number | null; max: number | null }
+  | { type: 'date'; from: string | null; to: string | null };
+
+/** Column-key → active filter. */
+export type FdyFilterMap = Record<string, FdyColumnFilter>;
+
+/** Server-driven pagination state (0-based page index). */
+export interface FdyPageState {
+  index: number;
+  size: number;
+  total: number;
+}
+
+export function cellValue<T>(row: T, column: FdyTableColumn<T>): unknown;
+export function cellText<T>(row: T, column: FdyTableColumn<T>): string;
+export function columnSortType<T>(column: FdyTableColumn<T>): FdyColumnType;
+export function compareBy(type: FdyColumnType, a: unknown, b: unknown): number;
+export function isFilterActive(filter: FdyColumnFilter | undefined): boolean;
+export function filterRows<T>(
+  rows: readonly T[],
+  columns: ReadonlyArray<FdyTableColumn<T>>,
+  filters: FdyFilterMap,
+): T[];
+export function sortRows<T>(
+  rows: readonly T[],
+  columns: ReadonlyArray<FdyTableColumn<T>>,
+  sort: FdySortState | null,
+): T[];
+export function paginate<T>(rows: readonly T[], pageIndex: number, pageSize: number): T[];
+export function distinctValues<T>(rows: readonly T[], column: FdyTableColumn<T>): string[];
+export function pageWindow(current: number, totalPages: number): Array<number | 'ellipsis'>;

package/adapters/core/table-model.js

@@ -0,0 +1,156 @@
+// Freeday — framework-agnostic table model (pure functions, zero dependencies).
+//
+// The sort / filter / paginate logic shared by adapters/vue/components/FdyTable.vue and
+// adapters/react/components/FdyTable.tsx. Kept here — plain ESM with a .d.ts sidecar — so the
+// two adapters can't drift and so the logic is unit-testable under `node --test`
+// (test/table-model.test.mjs) without a framework runtime. Every function is pure: inputs are
+// never mutated (rows are sliced before sorting), so it is safe to call on each render.
+//
+// Types live in table-model.d.ts. FdyTableColumn<T> = { key, label, sortable?, filter?, align?,
+// mono?, sortType?, value? }. A column's cell value is `col.value(row)` when given, else row[key].
+
+/** @param {unknown} v @returns {number} numeric value, tolerant of formatted strings ("Rp 1.000"); non-numeric -> 0 */
+function toNumber(v) {
+  if (typeof v === 'number') return Number.isFinite(v) ? v : 0;
+  const n = parseFloat(String(v == null ? '' : v).replace(/[^\d.-]/g, ''));
+  return Number.isNaN(n) ? 0 : n;
+}
+
+/** @param {unknown} v @returns {number} epoch ms; unparseable -> 0 */
+function toTime(v) {
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? 0 : v.getTime();
+  const t = Date.parse(String(v == null ? '' : v));
+  return Number.isNaN(t) ? 0 : t;
+}
+
+/** @param {unknown} v @returns {string} ISO calendar day (yyyy-mm-dd) — lexicographically comparable */
+function dateOnly(v) {
+  if (v instanceof Date) return Number.isNaN(v.getTime()) ? '' : v.toISOString().slice(0, 10);
+  return String(v == null ? '' : v).slice(0, 10);
+}
+
+/** Raw cell value for a column: the column accessor if present, else row[key]. */
+export function cellValue(row, column) {
+  return typeof column.value === 'function' ? column.value(row) : row[column.key];
+}
+
+/** Cell value as trimmed display text (null/undefined -> ''). */
+export function cellText(row, column) {
+  const v = cellValue(row, column);
+  return v === null || v === undefined ? '' : String(v).trim();
+}
+
+/** Effective comparator type for a column: explicit sortType, else derived from its filter type. */
+export function columnSortType(column) {
+  if (column.sortType) return column.sortType;
+  if (column.filter === 'number') return 'number';
+  if (column.filter === 'date') return 'date';
+  return 'text';
+}
+
+/** Ascending comparison of two raw cell values under a comparator type. */
+export function compareBy(type, a, b) {
+  if (type === 'number') return toNumber(a) - toNumber(b);
+  if (type === 'date') return toTime(a) - toTime(b);
+  return String(a == null ? '' : a).localeCompare(String(b == null ? '' : b), undefined, {
+    numeric: true,
+    sensitivity: 'base',
+  });
+}
+
+/** True when a filter would actually narrow the rows (i.e. worth applying / showing as active). */
+export function isFilterActive(filter) {
+  if (!filter) return false;
+  switch (filter.type) {
+    case 'text':
+      return filter.text.trim() !== '';
+    case 'enum':
+      return filter.values.length > 0;
+    case 'number':
+      return filter.min !== null || filter.max !== null;
+    case 'date':
+      return filter.from !== null || filter.to !== null;
+    default:
+      return false;
+  }
+}
+
+function rowPassesFilter(row, column, filter) {
+  switch (filter.type) {
+    case 'text': {
+      const needle = filter.text.trim().toLowerCase();
+      return needle === '' || cellText(row, column).toLowerCase().includes(needle);
+    }
+    case 'enum':
+      return filter.values.length === 0 || filter.values.includes(cellText(row, column));
+    case 'number': {
+      const v = toNumber(cellValue(row, column));
+      if (filter.min !== null && v < filter.min) return false;
+      if (filter.max !== null && v > filter.max) return false;
+      return true;
+    }
+    case 'date': {
+      const day = dateOnly(cellValue(row, column));
+      if (filter.from !== null && day < filter.from) return false;
+      if (filter.to !== null && day > filter.to) return false;
+      return true;
+    }
+    default:
+      return true;
+  }
+}
+
+/** Rows passing every active column filter (logical AND). Input is never mutated. */
+export function filterRows(rows, columns, filters) {
+  const active = columns
+    .map((col) => ({ col, filter: filters[col.key] }))
+    .filter((e) => isFilterActive(e.filter));
+  if (active.length === 0) return rows.slice();
+  return rows.filter((row) => active.every((e) => rowPassesFilter(row, e.col, e.filter)));
+}
+
+/** Rows sorted by the given sort state. Stable-enough via a sliced copy; input is never mutated. */
+export function sortRows(rows, columns, sort) {
+  if (!sort) return rows.slice();
+  const column = columns.find((c) => c.key === sort.key);
+  if (!column) return rows.slice();
+  const type = columnSortType(column);
+  const factor = sort.dir === 'desc' ? -1 : 1;
+  return rows
+    .slice()
+    .sort((a, b) => compareBy(type, cellValue(a, column), cellValue(b, column)) * factor);
+}
+
+/** Page slice (0-based page index). A non-positive size returns all rows. */
+export function paginate(rows, pageIndex, pageSize) {
+  if (!pageSize || pageSize <= 0) return rows.slice();
+  const start = pageIndex * pageSize;
+  return rows.slice(start, start + pageSize);
+}
+
+/** Distinct non-empty cell texts for a column, naturally sorted — the source for an enum filter. */
+export function distinctValues(rows, column) {
+  const seen = new Set();
+  const out = [];
+  for (const row of rows) {
+    const v = cellText(row, column);
+    if (v && !seen.has(v)) {
+      seen.add(v);
+      out.push(v);
+    }
+  }
+  return out.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+}
+
+/**
+ * Page-number window for a pager: first and last page always shown, current ±1, "ellipsis"
+ * gaps between. `current` and the returned page numbers are 1-based.
+ */
+export function pageWindow(current, totalPages) {
+  const out = [];
+  for (let p = 1; p <= totalPages; p++) {
+    if (p === 1 || p === totalPages || (p >= current - 1 && p <= current + 1)) out.push(p);
+    else if (out[out.length - 1] !== 'ellipsis') out.push('ellipsis');
+  }
+  return out;
+}

package/adapters/react/components/FdyDrawer.tsx

@@ -0,0 +1,59 @@
+import type { JSX, ReactNode } from 'react';
+import { useEffect, useId, useRef } from 'react';
+
+// A controlled React wrapper over freeday's `.fdy-drawer` native <dialog> side panel
+// (src/components/drawer.css). React port of adapters/vue/components/FdyDrawer.vue — the same
+// controlled glue as FdyModal (guarded showModal()/close(), onCancel + preventDefault so Esc routes
+// through app state, backdrop-click via `event.target === dialogEl`) applied to a drawer that anchors
+// left (default) or right. Native <dialog> supplies the focus trap, focus restore, top-layer stacking
+// and inert background; `dismissible` (default true) gates Esc + backdrop dismissal.
+
+export interface FdyDrawerProps {
+  open: boolean;
+  title: ReactNode;
+  onClose: () => void;
+  side?: 'left' | 'right';
+  dismissible?: boolean;
+  footer?: ReactNode;
+  children?: ReactNode;
+}
+
+export function FdyDrawer(props: FdyDrawerProps): JSX.Element {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const titleId: string = `${useId()}-title`;
+  const dismissible: boolean = props.dismissible !== false;
+  const drawerClass: string = props.side === 'right' ? 'fdy-drawer fdy-drawer--right' : 'fdy-drawer';
+
+  useEffect((): void => {
+    const el: HTMLDialogElement | null = dialogRef.current;
+    if (el === null) return;
+    if (props.open && !el.open) el.showModal();
+    else if (!props.open && el.open) el.close();
+  }, [props.open]);
+
+  return (
+    <dialog
+      ref={dialogRef}
+      className={drawerClass}
+      aria-labelledby={titleId}
+      onCancel={(e): void => {
+        e.preventDefault();
+        if (dismissible) props.onClose();
+      }}
+      onClick={(e): void => {
+        if (dismissible && e.target === dialogRef.current) props.onClose();
+      }}
+    >
+      <div className="fdy-drawer__header">
+        <h3 id={titleId} className="fdy-drawer__title">{props.title}</h3>
+        {dismissible && (
+          <button className="fdy-drawer__close" type="button" aria-label="Close" onClick={props.onClose}>&times;</button>
+        )}
+      </div>
+
+      <div className="fdy-drawer__body">{props.children}</div>
+
+      {props.footer !== undefined && <div className="fdy-drawer__footer">{props.footer}</div>}
+    </dialog>
+  );
+}

package/adapters/react/components/FdyModal.tsx

@@ -0,0 +1,63 @@
+import type { JSX, ReactNode } from 'react';
+import { useEffect, useId, useRef } from 'react';
+
+// A controlled React wrapper over freeday's `.fdy-modal` native <dialog> (src/components/modal.css).
+// React port of adapters/vue/components/FdyModal.vue: reconciles the reactive `open` boolean with a
+// DOM element whose open/close is a method call — showModal()/close() guarded against the
+// already-open/closed cases (showModal() on an open dialog throws), onCancel + preventDefault so Esc
+// routes through app state instead of closing the DOM behind its back, and backdrop-click detection
+// via `event.target === dialogEl`. Native <dialog> already gives the focus trap, focus restore,
+// top-layer stacking and inert background. `dismissible` (default true) gates Esc + backdrop.
+
+export interface FdyModalProps {
+  open: boolean;
+  title: ReactNode;
+  onClose: () => void;
+  size?: 'sm' | 'md' | 'lg' | 'wide';
+  dismissible?: boolean;
+  footer?: ReactNode;
+  children?: ReactNode;
+}
+
+export function FdyModal(props: FdyModalProps): JSX.Element {
+  const dialogRef = useRef<HTMLDialogElement>(null);
+  const titleId: string = `${useId()}-title`;
+  const dismissible: boolean = props.dismissible !== false;
+  const modalClass: string = props.size !== undefined ? `fdy-modal fdy-modal--${props.size}` : 'fdy-modal';
+
+  // Reconcile `open` with the dialog's method-driven state (runs on mount and whenever open changes).
+  // showModal() on an already-open dialog throws, so guard both directions.
+  useEffect((): void => {
+    const el: HTMLDialogElement | null = dialogRef.current;
+    if (el === null) return;
+    if (props.open && !el.open) el.showModal();
+    else if (!props.open && el.open) el.close();
+  }, [props.open]);
+
+  return (
+    <dialog
+      ref={dialogRef}
+      className={modalClass}
+      aria-labelledby={titleId}
+      onCancel={(e): void => {
+        e.preventDefault(); // stop the native close; app state stays the single source of truth
+        if (dismissible) props.onClose();
+      }}
+      onClick={(e): void => {
+        // The ::backdrop is not a separate element — target === the dialog box means a backdrop click.
+        if (dismissible && e.target === dialogRef.current) props.onClose();
+      }}
+    >
+      <div className="fdy-modal__header">
+        <h3 id={titleId} className="fdy-modal__title">{props.title}</h3>
+        {dismissible && (
+          <button className="fdy-modal__close" type="button" aria-label="Close" onClick={props.onClose}>&times;</button>
+        )}
+      </div>
+
+      <div className="fdy-modal__body">{props.children}</div>
+
+      {props.footer !== undefined && <div className="fdy-modal__footer">{props.footer}</div>}
+    </dialog>
+  );
+}

package/adapters/react/components/FdyTable.tsx

@@ -0,0 +1,234 @@
+import type { CSSProperties, JSX, ReactNode } from 'react';
+import { useEffect, useMemo, useState } from 'react';
+import {
+  cellValue,
+  cellText,
+  distinctValues,
+  filterRows,
+  sortRows,
+  paginate,
+  pageWindow,
+} from '../../core/table-model.js';
+import type {
+  FdyTableColumn,
+  FdySortState,
+  FdyColumnFilter,
+  FdyFilterMap,
+  FdyPageState,
+} from '../../core/table-model.js';
+import { FdyTableFilter } from './FdyTableFilter';
+
+// A controlled React data table over freeday's `.fdy-datatable` / `.fdy-table*` / `.fdy-filter*` /
+// `.fdy-pagination__*` classes. React port of adapters/vue/components/FdyTable.vue. Unlike the
+// freeday-table.js enhancer (which snapshots static rows and fights React's reconciler), this reads
+// `rows` as the source of truth on every render. Two modes:
+//   • Client mode (no `page` prop): the component sorts/filters (and paginates when `pageSize` is
+//     set) over the full `rows`. `sort`/`filters` are controlled when provided, else internal.
+//   • Server mode (`page` prop present): `rows` render exactly as given (server already
+//     sorted/filtered/paged); the headers, filters and pager only signal intent via
+//     `onSortChange` / `onFiltersChange` / `onPageChange` for the caller to feed back into its query.
+// Column filters (text/enum/number/date) apply live; in server mode, debounce the callback if needed.
+
+export interface FdyTableProps<Row extends Record<string, unknown>> {
+  columns: ReadonlyArray<FdyTableColumn<Row>>;
+  rows: ReadonlyArray<Row>;
+  rowKey: (row: Row) => string | number;
+  /** Controlled sort. Provide (even as null) to own sorting; omit for internal client sort. */
+  sort?: FdySortState | null;
+  onSortChange?: (sort: FdySortState | null) => void;
+  /** Controlled filter map keyed by column key. Provide to own filtering; omit for internal. */
+  filters?: FdyFilterMap;
+  onFiltersChange?: (filters: FdyFilterMap) => void;
+  /** Server pagination state (0-based index). Presence switches the table into server mode. */
+  page?: FdyPageState;
+  onPageChange?: (page: FdyPageState) => void;
+  /** Client-side page size when `page` is absent; 0/undefined = render all rows (no pager). */
+  pageSize?: number;
+  loading?: boolean;
+  emptyText?: string;
+  ariaLabel?: string;
+  /** Custom cell renderer; return undefined for a column to use the default text. */
+  renderCell?: (column: FdyTableColumn<Row>, row: Row, value: unknown) => ReactNode;
+  toolbar?: ReactNode;
+  empty?: ReactNode;
+}
+
+export function FdyTable<Row extends Record<string, unknown>>(props: FdyTableProps<Row>): JSX.Element {
+  const serverPaged: boolean = props.page != null;
+  const sortControlled: boolean = serverPaged || props.sort !== undefined;
+  const filtersControlled: boolean = serverPaged || props.filters !== undefined;
+
+  const [internalSort, setInternalSort] = useState<FdySortState | null>(null);
+  const [internalFilters, setInternalFilters] = useState<FdyFilterMap>({});
+  const [internalPageIndex, setInternalPageIndex] = useState<number>(0);
+
+  const effectiveSort: FdySortState | null = sortControlled ? (props.sort ?? null) : internalSort;
+  const effectiveFilters: FdyFilterMap = filtersControlled ? (props.filters ?? {}) : internalFilters;
+
+  // Enum options: explicit (server mode) or distinct values across the current rows (client mode).
+  const enumOptionsMap: Record<string, ReadonlyArray<string>> = useMemo(() => {
+    const out: Record<string, ReadonlyArray<string>> = {};
+    for (const col of props.columns) {
+      if (col.filter === 'enum') out[col.key] = col.options ?? distinctValues(props.rows, col);
+    }
+    return out;
+  }, [props.columns, props.rows]);
+
+  const filteredSorted: Row[] = useMemo(() => {
+    if (serverPaged) return props.rows.slice();
+    return sortRows(filterRows(props.rows, props.columns, effectiveFilters), props.columns, effectiveSort);
+  }, [serverPaged, props.rows, props.columns, effectiveFilters, effectiveSort]);
+
+  const totalCount: number = serverPaged ? (props.page as FdyPageState).total : filteredSorted.length;
+
+  const displayRows: Row[] = useMemo(() => {
+    if (serverPaged) return props.rows.slice();
+    if (props.pageSize && props.pageSize > 0) return paginate(filteredSorted, internalPageIndex, props.pageSize);
+    return filteredSorted;
+  }, [serverPaged, props.rows, props.pageSize, filteredSorted, internalPageIndex]);
+
+  const pageSizeEff: number = serverPaged ? (props.page as FdyPageState).size : (props.pageSize ?? 0);
+  const currentPage1: number = (serverPaged ? (props.page as FdyPageState).index : internalPageIndex) + 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);
+  const rangeFrom: number = totalCount === 0 ? 0 : (currentPage1 - 1) * pageSizeEff + 1;
+  const rangeTo: number = totalCount === 0 ? 0 : rangeFrom - 1 + displayRows.length;
+
+  // 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]);
+
+  function ariaSortOf(col: FdyTableColumn<Row>): 'ascending' | 'descending' | undefined {
+    if (effectiveSort === null || effectiveSort.key !== col.key) return undefined;
+    return effectiveSort.dir === 'asc' ? 'ascending' : 'descending';
+  }
+  function onSort(col: FdyTableColumn<Row>): void {
+    if (col.sortable !== true) return;
+    const next: FdySortState =
+      effectiveSort !== null && effectiveSort.key === col.key
+        ? { key: col.key, dir: effectiveSort.dir === 'asc' ? 'desc' : 'asc' }
+        : { key: col.key, dir: 'asc' };
+    if (sortControlled) props.onSortChange?.(next);
+    else {
+      setInternalSort(next);
+      setInternalPageIndex(0);
+    }
+  }
+  function onFilterChange(col: FdyTableColumn<Row>, filter: FdyColumnFilter | null): void {
+    const nextMap: FdyFilterMap = { ...effectiveFilters };
+    if (filter === null) delete nextMap[col.key];
+    else nextMap[col.key] = filter;
+    if (filtersControlled) props.onFiltersChange?.(nextMap);
+    else {
+      setInternalFilters(nextMap);
+      setInternalPageIndex(0);
+    }
+  }
+  function goTo(page1: number): void {
+    const clamped: number = Math.min(Math.max(1, page1), totalPages);
+    const index0: number = clamped - 1;
+    if (serverPaged) {
+      const p: FdyPageState = props.page as FdyPageState;
+      props.onPageChange?.({ index: index0, size: p.size, total: p.total });
+    } else {
+      setInternalPageIndex(index0);
+    }
+  }
+
+  function cellClass(col: FdyTableColumn<Row>): string | undefined {
+    return col.mono === true ? 'fdy-mono' : undefined;
+  }
+  function alignStyle(col: FdyTableColumn<Row>): CSSProperties | undefined {
+    return col.align !== undefined ? { textAlign: col.align } : undefined;
+  }
+  function renderCellContent(col: FdyTableColumn<Row>, row: Row): ReactNode {
+    if (props.renderCell !== undefined) {
+      const custom: ReactNode = props.renderCell(col, row, cellValue(row, col));
+      if (custom !== undefined) return custom;
+    }
+    return cellText(row, col);
+  }
+
+  const colCount: number = props.columns.length;
+
+  return (
+    <div className="fdy-datatable">
+      {props.toolbar !== undefined && <div className="fdy-table-toolbar">{props.toolbar}</div>}
+
+      <div className="fdy-table-scroll">
+        <table className="fdy-table" aria-label={props.ariaLabel}>
+          <thead>
+            <tr>
+              {props.columns.map((col: FdyTableColumn<Row>): JSX.Element => (
+                <th key={col.key} scope="col" style={alignStyle(col)} aria-sort={ariaSortOf(col)}>
+                  {col.sortable ? (
+                    <button type="button" className="fdy-table__sortbtn" onClick={(): void => onSort(col)}>{col.label}</button>
+                  ) : (
+                    col.label
+                  )}
+                  {col.filter && (
+                    <FdyTableFilter
+                      label={col.label}
+                      type={col.filter}
+                      filter={effectiveFilters[col.key]}
+                      options={enumOptionsMap[col.key] ?? []}
+                      onChange={(f: FdyColumnFilter | null): void => onFilterChange(col, f)}
+                    />
+                  )}
+                </th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {props.loading ? (
+              <tr>
+                <td colSpan={colCount} className="fdy-table__state" role="status">Loading…</td>
+              </tr>
+            ) : displayRows.length === 0 ? (
+              <tr>
+                <td colSpan={colCount} className="fdy-table__state">{props.empty ?? props.emptyText ?? 'No data'}</td>
+              </tr>
+            ) : (
+              displayRows.map((row: Row): JSX.Element => (
+                <tr key={props.rowKey(row)}>
+                  {props.columns.map((col: FdyTableColumn<Row>): JSX.Element => (
+                    <td key={col.key} className={cellClass(col)} style={alignStyle(col)}>{renderCellContent(col, row)}</td>
+                  ))}
+                </tr>
+              ))
+            )}
+          </tbody>
+        </table>
+      </div>
+
+      {hasPager && (
+        <div className="fdy-table-footer">
+          <span className="fdy-table-footer__info">Showing {rangeFrom}–{rangeTo} of {totalCount}</span>
+          <nav aria-label="Pagination">
+            <ul className="fdy-pagination__list">
+              <li>
+                <button type="button" className="fdy-pagination__link" aria-label="Previous page" disabled={currentPage1 === 1} onClick={(): void => goTo(currentPage1 - 1)}>‹</button>
+              </li>
+              {pages.map((p: number | 'ellipsis', i: number): JSX.Element => (
+                <li key={typeof p === 'number' ? `p-${p}` : `gap-${i}`}>
+                  {p === 'ellipsis' ? (
+                    <span className="fdy-pagination__ellipsis">…</span>
+                  ) : p === currentPage1 ? (
+                    <span className="fdy-pagination__link" aria-current="page">{p}</span>
+                  ) : (
+                    <button type="button" className="fdy-pagination__link" aria-label={`Go to page ${p}`} onClick={(): void => goTo(p)}>{p}</button>
+                  )}
+                </li>
+              ))}
+              <li>
+                <button type="button" className="fdy-pagination__link" aria-label="Next page" disabled={currentPage1 === totalPages} onClick={(): void => goTo(currentPage1 + 1)}>›</button>
+              </li>
+            </ul>
+          </nav>
+        </div>
+      )}
+    </div>
+  );
+}