@rowakit/table 0.5.0 → 1.0.0

package/README.md

@@ -1,56 +1,32 @@
 # @rowakit/table
 
-**Server-side-first React table for internal & business applications**
+**Server-side-first React table for internal & business applications.**
+Predictable API. Thin client. No data-grid bloat.
 
-RowaKit Table is an **opinionated React table component** designed for real-world internal apps and admin dashboards. It assumes **all data operations live on the server** and provides a clean, predictable API optimized for CRUD-style business screens.
+## Stability
 
-> If you are looking for a spreadsheet-like data grid with virtualization, grouping, or pivoting, this is intentionally **not** that library.
+`@rowakit/table` is **stable as of v1.0.0**.
 
----
-
-## Why RowaKit Table?
-
-Most React table libraries are **client-first** and optimized for maximum flexibility. RowaKit takes the opposite approach:
-
-* ✅ Server-side pagination, sorting, filtering by default
-* ✅ Minimal, convention-driven API (less boilerplate)
-* ✅ Strong TypeScript contracts between UI and backend
-* ✅ Built for long-lived internal tools, not demo-heavy grids
+See:
+- `docs/API_STABILITY.md`
+- `docs/API_FREEZE_SUMMARY.md`
 
-This makes RowaKit especially suitable for:
+---
 
-* Admin dashboards
-* Back-office / internal tools
-* B2B SaaS management screens
-* Enterprise CRUD applications
+## Why @rowakit/table?
 
----
+Most React table libraries grow into complex data grids.
+RowaKit Table is intentionally different:
 
-## Features
-
-* 🚀 **Server-side first** – pagination, sorting, filtering handled by your backend
-* 🎯 **Type-safe** – full TypeScript support with generics
-* 🧠 **Minimal API** – convention over configuration
-* 🪝 **Escape hatch** – `col.custom()` for full rendering control
-* 🎛️ **7 column types** – text, number, date, boolean, badge, actions, custom
-* 🖱️ **Column resizing** – drag handles, min/max width, double-click auto-fit (v0.4.0+)
-* 📌 **Saved views** – persist table state to localStorage (v0.4.0+)
-* 🔗 **URL sync** – share exact table state via query string (v0.4.0+)
-* 🧮 **Number range filters** – min/max with optional value transforms
-* ✅ **Row selection** – select/deselect rows with bulk header checkbox (v0.5.0+)
-* 🎬 **Bulk actions** – execute operations on multiple selected rows (v0.5.0+)
-* 💾 **CSV export** – server-triggered export with customizable formatter (v0.5.0+)
-* 🔄 **Multi-column sorting** – Ctrl+Click to sort by multiple columns with priority (v0.5.0+)
-* ♿ **Accessibility** – ARIA labels, keyboard navigation, focus management (v0.5.0+)
-* 🔄 **Smart fetching** – retry on error, stale request protection
-* ✅ **Built-in states** – loading, error, empty handled automatically
+* Backend owns data logic (pagination, sorting, filtering)
+* Frontend stays thin and predictable
+* API is opinionated and stable
+* Workflow features are built-in, not bolted on
 
 ---
 
 ## Installation
 
-RowaKit Table is published on npm and works with **npm**, **pnpm**, or **yarn**.
-
 ```bash
 npm install @rowakit/table
 # or
@@ -59,50 +35,41 @@ pnpm add @rowakit/table
 yarn add @rowakit/table
 ```
 
----
+Import base styles:
 
-## Quick Start (5 minutes)
+```ts
+import '@rowakit/table/styles';
+```
 
-### 1. Import
+---
+
+## Quick Start
 
 ```tsx
 import { RowaKitTable, col } from '@rowakit/table';
 import type { Fetcher } from '@rowakit/table';
 import '@rowakit/table/styles';
-```
 
-### 2. Define a fetcher (server contract)
+type User = { id: string; name: string; email: string; active: boolean };
 
-```tsx
-interface User {
-  id: string;
-  name: string;
-  email: string;
-  active: boolean;
-}
-
-const fetchUsers: Fetcher<User> = async ({ page, pageSize, sort, filters }) => {
+const fetchUsers: Fetcher<User> = async ({ page, pageSize, sort }) => {
   const params = new URLSearchParams({
     page: String(page),
     pageSize: String(pageSize),
   });
 
   if (sort) {
-    params.set('sortBy', sort.field);
+    params.set('sortField', sort.field);
     params.set('sortDir', sort.direction);
   }
 
   const res = await fetch(`/api/users?${params}`);
   if (!res.ok) throw new Error('Failed to fetch users');
 
-  return res.json(); // { items: User[], total: number }
+  return res.json();
 };
-```
 
-### 3. Render the table
-
-```tsx
-function UsersTable() {
+export function UsersTable() {
   return (
     <RowaKitTable
       fetcher={fetchUsers}
@@ -112,7 +79,7 @@ function UsersTable() {
         col.text('email', { header: 'Email' }),
         col.boolean('active', { header: 'Active' }),
         col.actions([
-          { id: 'edit', label: 'Edit', onClick: (row) => console.log(row) },
+          { id: 'edit', label: 'Edit' },
           { id: 'delete', label: 'Delete', confirm: true },
         ]),
       ]}
@@ -121,139 +88,179 @@ function UsersTable() {
 }
 ```
 
-That’s it — loading, error, pagination, sorting, and retry are handled automatically.
-
 ---
 
-## Core Concepts
+## Features (v1.0.0)
 
-### Fetcher Contract
+### Core table
+
+* Server-side pagination, sorting, filtering
+* Typed `Fetcher<T>` contract
+* Built-in loading / error / empty states
+* Stale request protection
+
+### Columns
+
+* `col.text`
+* `col.number`
+* `col.date`
+* `col.boolean`
+* `col.badge`
+* `col.actions`
+* `col.custom`
+
+### UX & workflows
+
+* Column resizing (pointer events)
+* Double-click auto-fit
+* URL sync
+* Saved views
+* Row selection (page-scoped)
+* Bulk actions
+* Export via `exporter` callback
+
+---
 
-The **Fetcher** defines the contract between the table and your backend.
+## Fetcher Contract
 
 ```ts
 type Fetcher<T> = (query: {
   page: number;
   pageSize: number;
+  /** Deprecated (kept for backward compatibility; planned removal in v2.0.0). */
   sort?: { field: string; direction: 'asc' | 'desc' };
+  /** Multi-column sorting (preferred). */
+  sorts?: Array<{ field: string; direction: 'asc' | 'desc'; priority: number }>;
   filters?: Record<string, unknown>;
 }) => Promise<{ items: T[]; total: number }>;
 ```
 
-* Fetcher is called on mount and whenever table state changes
-* Throw an error to trigger the built-in error + retry UI
-* Stale requests are ignored automatically
+Guidelines:
 
----
-
-## Column API
+* Backend is the source of truth
+* Throw errors to trigger built-in error UI
+* Ignore stale requests (handled internally)
 
-RowaKit provides a **column factory API** via `col.*` helpers.
+---
 
-### Basic columns
+## Row Selection
 
-```ts
-col.text('name')
-col.number('price', { format: { style: 'currency', currency: 'USD' } })
-col.date('createdAt', { sortable: true })
-col.boolean('active')
+```tsx
+<RowaKitTable
+  enableRowSelection
+  onSelectionChange={(keys) => console.log(keys)}
+  fetcher={fetchUsers}
+  columns={[/* ... */]}
+/>
 ```
 
-### Badge column (enum/status)
-
-```ts
-col.badge('status', {
-  header: 'Status',
-  sortable: true,
-  map: {
-    active: { label: 'Active', tone: 'success' },
-    pending: { label: 'Pending', tone: 'warning' },
-    error: { label: 'Error', tone: 'danger' },
-  },
-});
-```
+* Selection is page-scoped
+* Resets on page change
 
-### Actions column
+---
 
-```ts
-col.actions([
-  { id: 'edit', label: 'Edit', onClick: (row) => edit(row) },
-  { id: 'delete', label: 'Delete', confirm: true, onClick: (row) => remove(row) },
-]);
-```
+## Multi-Column Sorting
 
-### Custom column (escape hatch)
+Sort by multiple columns simultaneously using **Ctrl+Click** (Windows/Linux) or **Cmd+Click** (Mac) on column headers:
 
 ```tsx
-col.custom('user', (row) => (
-  <div style={{ display: 'flex', gap: 8 }}>
-    <img src={row.avatar} width={24} />
-    <span>{row.name}</span>
-  </div>
-));
-```
+// Hold Ctrl/Cmd and click column headers in order
+// Priority is determined by click order (first click = priority 1)
+
+// The fetcher receives sorts array:
+const fetcher = async (query: FetcherQuery) => {
+  // query.sorts = [
+  //   { field: 'lastName', direction: 'asc', priority: 1 },
+  //   { field: 'firstName', direction: 'asc', priority: 2 },
+  //   { field: 'salary', direction: 'desc', priority: 3 }
+  // ]
+  const res = await fetch('/api/users', {
+    method: 'POST',
+    body: JSON.stringify(query),
+  });
+  return res.json();
+};
 
----
+<RowaKitTable fetcher={fetcher} columns={[/* ... */]} />
+```
 
-## Advanced Features (v0.4.0+)
+**Migration from deprecated `sort` field:**
+- Old format: `query.sort = { field: 'name', direction: 'asc' }`
+- New format: `query.sorts = [{ field: 'name', direction: 'asc', priority: 1 }]`
+- Both fields coexist during transition; `sort` will be removed in v2.0.0
 
-### Column Resizing
+**UI Indicators:**
+- Single column: Standard sort arrow indicator
+- Multiple columns: Priority number displayed on sorted column headers
 
-* Drag handle on header edge
-* Min/max width constraints
-* Double-click to auto-fit content
-* Pointer Events (mouse / touch / pen)
-* No accidental sort while resizing
+---
 
-### Saved Views + URL Sync
+## Bulk Actions
 
-* Persist page, sort, filters, and column widths
-* Share URLs that restore exact table state
-* Named views saved to localStorage
-* Safe parsing & corruption tolerance
+```tsx
+<RowaKitTable
+  enableRowSelection
+  bulkActions={[
+    {
+      id: 'delete',
+      label: 'Delete selected',
+      confirm: { title: 'Confirm delete' },
+      onClick: (keys) => console.log(keys),
+    },
+  ]}
+  fetcher={fetchUsers}
+  columns={[/* ... */]}
+/>
+```
 
 ---
 
-## Styling
+## Export (CSV)
+
+```tsx
+const exporter = async (query) => {
+  const res = await fetch('/api/export', {
+    method: 'POST',
+    body: JSON.stringify(query),
+  });
 
-RowaKit ships with minimal default styles via CSS variables.
+  const { url } = await res.json();
+  return { url };
+};
 
-```ts
-import '@rowakit/table/styles';
+<RowaKitTable exporter={exporter} fetcher={fetchUsers} columns={[/* ... */]} />
 ```
 
-You can:
-
-* Override CSS variables for theming
-* Use `className` to scope custom styles
-* Skip default styles and fully style from scratch
+Export is server-triggered and scales well for large datasets.
 
 ---
 
-## Philosophy & Scope
+## Roadmap & Versioning
 
-* **Server-side first** – client stays thin
-* **Small core** – no grid bloat
-* **Clear escape hatch** – `col.custom()`
-* **Business tables ≠ spreadsheets**
+* Current: **1.0.0** (stable)
+* No breaking changes in 1.x (breaking changes require v2.0.0)
+* Public API stability policy applies from v1.0.0
 
-See the scope lock and rationale in the root repository docs.
+See roadmap: [docs/ROADMAP.md](docs/ROADMAP.md)
 
 ---
 
-## Versioning & Roadmap
+## Support RowaKit
+
+If RowaKit helps your team:
+
+* ⭐ Star the repo
+* 💖 [Sponsor on GitHub](https://github.com/sponsors/midflow)
+* ☕ [Buy us a coffee](https://buymeacoffee.com/midflow)
 
-* Current: **v0.5.x** (Stage E – row selection, bulk actions, export, multi-sort, a11y)
-* API is stable; patches are backward compatible
-* Completed: Stages A-E with full feature set for internal business applications
-* See [CHANGELOG.md](./CHANGELOG.md) for detailed v0.5.0 features and [docs/ROADMAP.md](../../docs/ROADMAP.md)
+Every bit of support helps sustain long-term maintenance.
 
 ---
 
 ## License
 
-MIT
+MIT © RowaKit Contributors
 
 ---
 
-Built for teams shipping serious internal tools, not toy demos.
+**Built for teams shipping internal tools, not demos.**

package/dist/index.cjs

@@ -569,11 +569,22 @@ function parseUrlState(params, defaultPageSize, pageSizeOptions) {
     } catch {
     }
   }
+  if (!result.sorts) {
+    const sortStr = params.get("sort");
+    if (sortStr) {
+      const [field, dir] = sortStr.split(":");
+      if (field && (dir === "asc" || dir === "desc")) {
+        result.sort = { field, direction: dir };
+        result.sorts = [{ field, direction: dir, priority: 0 }];
+      }
+    }
+  }
   if (!result.sorts) {
     const sortField = params.get("sortField");
     const sortDir = params.get("sortDirection");
     if (sortField && (sortDir === "asc" || sortDir === "desc")) {
       result.sort = { field: sortField, direction: sortDir };
+      result.sorts = [{ field: sortField, direction: sortDir, priority: 0 }];
     }
   }
   const filtersStr = params.get("filters");
@@ -645,40 +656,59 @@ function useUrlSync({
   setColumnWidths
 }) {
   const didHydrateUrlRef = react.useRef(false);
-  const didSkipInitialUrlSyncRef = react.useRef(false);
   const urlSyncDebounceRef = react.useRef(null);
+  const isApplyingUrlStateRef = react.useRef(false);
+  const clearApplyingTimerRef = react.useRef(null);
+  const hasWrittenUrlRef = react.useRef(false);
+  const lastQueryForUrlRef = react.useRef(null);
+  const defaultPageSizeRef = react.useRef(defaultPageSize);
+  const pageSizeOptionsRef = react.useRef(pageSizeOptions);
+  const enableColumnResizingRef = react.useRef(enableColumnResizing);
+  const columnsRef = react.useRef(columns);
+  defaultPageSizeRef.current = defaultPageSize;
+  pageSizeOptionsRef.current = pageSizeOptions;
+  enableColumnResizingRef.current = enableColumnResizing;
+  columnsRef.current = columns;
   react.useEffect(() => {
     if (!syncToUrl) {
-      didSkipInitialUrlSyncRef.current = false;
-      return;
-    }
-    if (!didSkipInitialUrlSyncRef.current) {
-      didSkipInitialUrlSyncRef.current = true;
+      hasWrittenUrlRef.current = false;
+      lastQueryForUrlRef.current = null;
       return;
     }
+    if (!didHydrateUrlRef.current) return;
+    if (isApplyingUrlStateRef.current) return;
     if (urlSyncDebounceRef.current) {
       clearTimeout(urlSyncDebounceRef.current);
       urlSyncDebounceRef.current = null;
     }
-    const urlStr = serializeUrlState(query, filters, columnWidths, defaultPageSize, enableColumnResizing);
+    const urlStr = serializeUrlState(query, filters, columnWidths, defaultPageSizeRef.current, enableColumnResizingRef.current);
     const qs = urlStr ? `?${urlStr}` : "";
-    window.history.replaceState(null, "", `${window.location.pathname}${qs}${window.location.hash}`);
+    const nextUrl = `${window.location.pathname}${qs}${window.location.hash}`;
+    const prevQuery = lastQueryForUrlRef.current;
+    const shouldPush = hasWrittenUrlRef.current && prevQuery != null && prevQuery.page !== query.page;
+    if (shouldPush) {
+      window.history.pushState(null, "", nextUrl);
+    } else {
+      window.history.replaceState(null, "", nextUrl);
+    }
+    hasWrittenUrlRef.current = true;
+    lastQueryForUrlRef.current = query;
   }, [
     query,
     filters,
     syncToUrl,
-    enableColumnResizing,
-    defaultPageSize,
     columnWidths
   ]);
   react.useEffect(() => {
-    if (!syncToUrl || !enableColumnResizing) return;
-    if (!didSkipInitialUrlSyncRef.current) return;
+    if (!syncToUrl || !enableColumnResizingRef.current) return;
+    if (!didHydrateUrlRef.current) return;
+    if (!hasWrittenUrlRef.current) return;
+    if (isApplyingUrlStateRef.current) return;
     if (urlSyncDebounceRef.current) {
       clearTimeout(urlSyncDebounceRef.current);
     }
     urlSyncDebounceRef.current = setTimeout(() => {
-      const urlStr = serializeUrlState(query, filters, columnWidths, defaultPageSize, enableColumnResizing);
+      const urlStr = serializeUrlState(query, filters, columnWidths, defaultPageSizeRef.current, enableColumnResizingRef.current);
       const qs = urlStr ? `?${urlStr}` : "";
       window.history.replaceState(null, "", `${window.location.pathname}${qs}${window.location.hash}`);
       urlSyncDebounceRef.current = null;
@@ -692,36 +722,52 @@ function useUrlSync({
   }, [
     columnWidths,
     syncToUrl,
-    enableColumnResizing,
     query,
-    filters,
-    defaultPageSize
+    filters
   ]);
-  react.useEffect(() => {
-    if (!syncToUrl) {
-      didHydrateUrlRef.current = false;
-      return;
+  function scheduleClearApplyingFlag() {
+    if (clearApplyingTimerRef.current) {
+      clearTimeout(clearApplyingTimerRef.current);
+      clearApplyingTimerRef.current = null;
     }
-    if (didHydrateUrlRef.current) return;
-    didHydrateUrlRef.current = true;
+    clearApplyingTimerRef.current = setTimeout(() => {
+      isApplyingUrlStateRef.current = false;
+      clearApplyingTimerRef.current = null;
+    }, 0);
+  }
+  function applyUrlToState() {
     const params = new URLSearchParams(window.location.search);
-    const parsed = parseUrlState(params, defaultPageSize, pageSizeOptions);
-    setQuery({
+    const parsed = parseUrlState(params, defaultPageSizeRef.current, pageSizeOptionsRef.current);
+    const nextQuery = {
       page: parsed.page,
       pageSize: parsed.pageSize,
       sort: parsed.sort,
       sorts: parsed.sorts,
       filters: parsed.filters
-    });
-    if (parsed.filters) {
-      setFilters(parsed.filters);
+    };
+    isApplyingUrlStateRef.current = true;
+    scheduleClearApplyingFlag();
+    setQuery(nextQuery);
+    setFilters(parsed.filters ?? {});
+    if (!hasWrittenUrlRef.current) {
+      const urlStr = serializeUrlState(
+        nextQuery,
+        parsed.filters ?? {},
+        parsed.columnWidths ?? {},
+        defaultPageSizeRef.current,
+        enableColumnResizingRef.current
+      );
+      const qs = urlStr ? `?${urlStr}` : "";
+      window.history.replaceState(null, "", `${window.location.pathname}${qs}${window.location.hash}`);
+      hasWrittenUrlRef.current = true;
+      lastQueryForUrlRef.current = nextQuery;
     }
-    if (parsed.columnWidths && enableColumnResizing) {
+    if (enableColumnResizingRef.current && parsed.columnWidths) {
       const clamped = {};
       for (const [colId, rawWidth] of Object.entries(parsed.columnWidths)) {
         const widthNum = typeof rawWidth === "number" ? rawWidth : Number(rawWidth);
         if (!Number.isFinite(widthNum)) continue;
-        const colDef = columns.find((c) => c.id === colId);
+        const colDef = columnsRef.current.find((c) => c.id === colId);
         if (!colDef) continue;
         const minW = colDef.minWidth ?? 80;
         const maxW = colDef.maxWidth;
@@ -732,17 +778,44 @@ function useUrlSync({
         clamped[colId] = finalW;
       }
       setColumnWidths(clamped);
+    } else if (enableColumnResizingRef.current) {
+      setColumnWidths({});
     }
+  }
+  react.useEffect(() => {
+    if (!syncToUrl) {
+      didHydrateUrlRef.current = false;
+      hasWrittenUrlRef.current = false;
+      lastQueryForUrlRef.current = null;
+      return;
+    }
+    if (didHydrateUrlRef.current) return;
+    didHydrateUrlRef.current = true;
+    applyUrlToState();
   }, [
     syncToUrl,
-    defaultPageSize,
-    enableColumnResizing,
-    pageSizeOptions,
-    columns,
     setQuery,
     setFilters,
     setColumnWidths
   ]);
+  react.useEffect(() => {
+    if (!syncToUrl) return;
+    const onPopState = () => {
+      applyUrlToState();
+    };
+    window.addEventListener("popstate", onPopState);
+    return () => {
+      window.removeEventListener("popstate", onPopState);
+    };
+  }, [syncToUrl, setQuery, setFilters, setColumnWidths]);
+  react.useEffect(() => {
+    return () => {
+      if (clearApplyingTimerRef.current) {
+        clearTimeout(clearApplyingTimerRef.current);
+        clearApplyingTimerRef.current = null;
+      }
+    };
+  }, []);
 }
 var FOCUSABLE_SELECTORS = [
   "button",
@@ -1093,9 +1166,13 @@ function RowaKitTable({
   const headerChecked = isAllSelected(selectedKeys, pageRowKeys);
   const headerIndeterminate = isIndeterminate(selectedKeys, pageRowKeys);
   react.useEffect(() => {
-    if (!enableRowSelection) return;
     setSelectedKeys(clearSelection());
-  }, [enableRowSelection, query.page, dataState.items]);
+  }, [query.page]);
+  react.useEffect(() => {
+    if (!enableRowSelection) {
+      setSelectedKeys(clearSelection());
+    }
+  }, [enableRowSelection]);
   react.useEffect(() => {
     if (!enableRowSelection || !onSelectionChange) return;
     onSelectionChange(selectedKeys);
@@ -1772,7 +1849,7 @@ function RowaKitTable({
 var SmartTable = RowaKitTable;
 
 // src/index.ts
-var VERSION = "0.5.0" ;
+var VERSION = "1.0.0" ;
 
 exports.RowaKitTable = RowaKitTable;
 exports.SmartTable = SmartTable;