@viliha/vui-ui 1.13.0 → 1.14.0

package/AGENT.md

@@ -173,6 +173,18 @@ scaffolded files in the repo are two separate things.
    `npx @viliha/vui-ui@latest init --dry-run`, then re-run with `--force` (commit
    or stash your work first so you can review the diff) or copy in just the files
    you want.
+   - **Keep-alive tab cache (1.13.1) lives in a scaffolded file**, so an upgrade
+     won't bring it. In `app/_components/open-tabs.tsx`, inside `KeepAliveTabs`,
+     make sure the cache is written **once per route**, not on every render:
+     ```ts
+     // ✅ preserves the mounted page across tab switches (no remount, no refetch)
+     if (!cache.current.has(active)) cache.current.set(active, children);
+     // ❌ old: cache.current.set(active, children)  // remounts on re-activation
+     ```
+     Re-pull the file with `init --force`, or apply this one-liner by hand.
+   - **Server tables that shouldn't refetch on tab switch:** use RecordView's
+     `fetcher` + `cacheKey` + `persistKey` (all in the package, so they arrive
+     with the upgrade) — see the Filtering/Tables notes above.
 5. **Re-check token overrides.** If you overrode any `theme.css` tokens, confirm
    they still line up after the upgrade.
 6. **Verify** before you commit: run type-check, lint, and build.
@@ -340,7 +352,12 @@ Form controls come from the field: `options` → `Select`, `input: "combobox"`
 
 Loading from a server: pass `loading` to `RecordView` while the fetch is in flight — it shows shimmering skeleton rows (matched to the columns) instead of an empty-state flash; clear it when the data arrives. Don't build your own spinner overlay.
 
-Server-side (large tables): set `manual` and RecordView stops filtering/sorting/paginating `data` — it renders it as the current page and reports the query via `onQueryChange({ page, pageSize, sort, search, filters })`. Pair with `rowCount` (totals) and `loading`. In your handler, fetch and set `data` + `rowCount` + `loading`; guard out-of-order responses with a request-id ref and debounce chatty keyword changes. Don't reimplement pagination/sort yourself. Reference: the Data Table demo page (shadcn/ui section) hits a simulated backend.
+Server-side (large tables) — two ways:
+
+1. **`fetcher` (preferred).** Pass `fetcher={(query, signal) => Promise<{ rows, total }>}` and RecordView owns the read path: it fetches on every query change, manages `data`/`rowCount`/`loading`, aborts superseded requests, and — with `cacheKey` — caches responses so returning to a tab is instant with no refetch. Add `persistKey` so page/sort/filters restore on remount and hit the cache. Optional `cache={{ max, ttlMs }}` and `onError`. Mutations are optimistic + invalidate + background refetch. Don't wire `data`/`onQueryChange`/`loading` yourself in this mode.
+2. **`manual` + `onQueryChange` (lower-level).** RecordView reports the query; you fetch and set `data` + `rowCount` + `loading`, guarding out-of-order responses and caching yourself.
+
+Either way, don't reimplement pagination/sort. Reference: the Data Table demo page (shadcn/ui section) uses `fetcher` + `cacheKey` + `persistKey` against a simulated backend.
 
 Dependent/cascading options: make `options` (form) or `filterable.options` (filter) a function — `(draft) => …` in the form, `(values) => …` in the filter — and one field's choices depend on another; RecordView clears the child when the parent change invalidates it. Keep `options` a static array for the bulk "Set {label}" action. If a field has both a function `options` and `renderInput`, guard with `Array.isArray(field.options)` before mapping (renderInput doesn't get the draft to resolve it).
 

package/CHANGELOG.md

@@ -7,6 +7,55 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.14.0 — 2026-07-26
+
+### Added
+
+- **Built-in server data source for `RecordView`: `fetcher` + query cache.** Pass
+  `fetcher={(query, signal) => Promise<{ rows, total }>}` and RecordView owns the
+  whole read path — it fetches on every query change, manages `data` / `rowCount`
+  / `loading`, aborts superseded requests via the `signal`, and (with `cacheKey`)
+  caches responses so returning to a tab is instant with no refetch. Combine with
+  `persistKey` to restore page/sort/filters on remount and hit the cache. New
+  props: `fetcher`, `cacheKey`, `cache` (`{ max, ttlMs }` LRU), `onError`.
+  Mutations are optimistic → invalidate → background refetch. This replaces the
+  hand-wired `data`/`onQueryChange`/`loading` + `Map` boilerplate (still supported
+  as the lower-level API). The Data Table demo now uses it.
+- **Changelog on the docs site** at `/docs/changelog`, rendered straight from this
+  file at build time (single source, never drifts). Linked in the docs nav.
+
+  **For agents:** for a server-backed table, prefer `fetcher` + `cacheKey` +
+  `persistKey` over wiring `onQueryChange`/`data`/`loading` + a cache yourself.
+  Docs: `/docs/data-table` (Server-side data → "Let RecordView own the fetch").
+
+## 1.13.2 — 2026-07-26
+
+### Fixed
+
+- **Data Table demo no longer reloads on tab switch.** Keep-alive keeps a page
+  mounted, but under the App Router an async (server-fetching) page can still
+  remount on tab switch and re-run its fetch. The demo now caches fetched pages
+  in a module-scoped `Map` keyed by the query (served synchronously, no shimmer)
+  and passes `persistKey`, so returning to the tab restores the exact page/sort/
+  filters and shows the data instantly — no round-trip.
+
+  **For agents:** for a server-backed table, cache responses (module `Map` or
+  your data layer) and use `persistKey`; don't rely on keep-alive alone to avoid
+  refetches. Docs: `/docs/data-table` (Persisting across tab switches).
+
+## 1.13.1 — 2026-07-26
+
+### Fixed
+
+- **Keep-alive tabs now truly preserve a page's live state across tab switches**
+  (within `NEXT_PUBLIC_MAX_TABS`). The scaffold's `KeepAliveTabs` was overwriting
+  a route's cached element with Next's fresh `children` on every re-activation,
+  which remounted the page and threw away its state — so a server-backed table
+  (e.g. the Data Table demo) refetched every time you returned to its tab. It now
+  caches each route's element once and reuses it, so switching away and back keeps
+  the loaded data, scroll, and form state with no reload. Query-param routes
+  (`/organizations/edit?id=…`) still update via their own `useSearchParams`.
+
 ## 1.13.0 — 2026-07-26
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Vui UI — a clean, token-driven React admin/CRM component library built on Tailwind CSS v4, shadcn-style patterns, and Radix Icons. Ships as TypeScript source (Just-in-Time), compiled by the consuming app.",
   "license": "MIT",
   "author": "Suman Bonakurthi",

package/src/record-view.tsx

@@ -352,6 +352,48 @@ function resolveOptions<T>(
   return typeof opts === "function" ? opts(draft) : (opts ?? []);
 }
 
+// Module-scoped response cache for RecordView's `fetcher` mode. Namespaced by
+// `cacheKey` and living outside any component, so a cached page survives a
+// remount / tab switch — the return is instant with no refetch. LRU per
+// namespace (insertion order = recency), optional TTL.
+type RvCacheEntry = { rows: unknown[]; total: number; at: number };
+const RV_CACHE = new Map<string, Map<string, RvCacheEntry>>();
+
+function rvQueryKey<T>(q: ServerQuery<T>): string {
+  return JSON.stringify([q.page, q.pageSize, q.sort, q.search, q.filters]);
+}
+function rvCacheGet(
+  ns: string,
+  key: string,
+  ttlMs: number,
+): RvCacheEntry | null {
+  const bucket = RV_CACHE.get(ns);
+  const hit = bucket?.get(key);
+  if (!hit) return null;
+  if (ttlMs > 0 && Date.now() - hit.at > ttlMs) {
+    bucket!.delete(key);
+    return null;
+  }
+  // Refresh recency.
+  bucket!.delete(key);
+  bucket!.set(key, hit);
+  return hit;
+}
+function rvCacheSet(ns: string, key: string, entry: RvCacheEntry, max: number) {
+  let bucket = RV_CACHE.get(ns);
+  if (!bucket) {
+    bucket = new Map();
+    RV_CACHE.set(ns, bucket);
+  }
+  bucket.delete(key);
+  bucket.set(key, entry);
+  while (bucket.size > max) {
+    const oldest = bucket.keys().next().value;
+    if (oldest === undefined) break;
+    bucket.delete(oldest);
+  }
+}
+
 interface RecordViewProps<T extends { id: RowId }> {
   title: string;
   singular: string;
@@ -413,6 +455,25 @@ interface RecordViewProps<T extends { id: RowId }> {
    *  update `data` + `rowCount` + `loading` in response. Fires once on mount for
    *  the initial load; debounce inside if keyword changes are chatty. */
   onQueryChange?: (query: ServerQuery<T>) => void;
+  /** Server data source. Providing it turns on `manual` and hands RecordView
+   *  ownership of the read path: it calls this on every query change and manages
+   *  `data` / `rowCount` / `loading` + caching itself — so you don't wire those
+   *  or `onQueryChange`. Return the current page plus the server total. The
+   *  `signal` aborts superseded requests. Mutually exclusive with the
+   *  consumer-managed props above (if both are set, `fetcher` wins). */
+  fetcher?: (
+    query: ServerQuery<T>,
+    signal: AbortSignal,
+  ) => Promise<{ rows: T[]; total: number }>;
+  /** Namespaces the `fetcher` response cache (like `persistKey`). Responses are
+   *  cached per query and survive remounts / tab switches, so returning to a tab
+   *  is instant with no refetch. Omit → no caching (always refetch). */
+  cacheKey?: string;
+  /** `fetcher` cache tuning. Default `{ max: 50, ttlMs: 0 }` (LRU, no expiry). */
+  cache?: { max?: number; ttlMs?: number };
+  /** Called when a `fetcher` request rejects (non-abort). RecordView keeps the
+   *  previously loaded data and clears the loading state. */
+  onError?: (error: unknown, query: ServerQuery<T>) => void;
 }
 
 export function RecordView<T extends { id: RowId }>({
@@ -439,16 +500,89 @@ export function RecordView<T extends { id: RowId }>({
   manual = false,
   rowCount,
   onQueryChange,
+  fetcher,
+  cacheKey,
+  cache,
+  onError,
 }: RecordViewProps<T>) {
   const { titleLeading } = React.useContext(PageChromeContext);
   // Surface the page title/icon in the app's global top bar.
   usePageTitle(title, TitleIcon);
-  // Rows are either controlled (data + onDataChange) or held internally.
+  // Rows: `fetcher`-owned (server), controlled (data + onDataChange), or held
+  // internally. `fetcher` implies manual mode.
+  const fetching = fetcher !== undefined;
+  const isManual = manual || fetching;
   const [internalRows, setInternalRows] = React.useState<T[]>(initialData);
   const controlled = data !== undefined;
-  const rows = controlled ? data : internalRows;
+
+  // Fetcher-managed state (only used when `fetcher` is set).
+  const [fetchedData, setFetchedData] = React.useState<T[]>([]);
+  const [fetchedTotal, setFetchedTotal] = React.useState(0);
+  const [fetchedLoading, setFetchedLoading] = React.useState(fetching);
+  const reqIdRef = React.useRef(0);
+  const abortRef = React.useRef<AbortController | null>(null);
+  const queryRef = React.useRef<ServerQuery<T> | null>(null);
+  const ttlMs = cache?.ttlMs ?? 0;
+  const cacheMax = cache?.max ?? 50;
+
+  const runFetch = React.useCallback(
+    (q: ServerQuery<T>, opts?: { background?: boolean }) => {
+      if (!fetcher) return;
+      // Foreground: serve from cache if present (instant, no shimmer).
+      if (!opts?.background && cacheKey) {
+        const hit = rvCacheGet(cacheKey, rvQueryKey(q), ttlMs);
+        if (hit) {
+          setFetchedData(hit.rows as T[]);
+          setFetchedTotal(hit.total);
+          setFetchedLoading(false);
+          return;
+        }
+      }
+      const id = ++reqIdRef.current;
+      abortRef.current?.abort();
+      const controller = new AbortController();
+      abortRef.current = controller;
+      if (!opts?.background) setFetchedLoading(true);
+      fetcher(q, controller.signal)
+        .then((res) => {
+          if (id !== reqIdRef.current) return; // superseded
+          if (cacheKey)
+            rvCacheSet(
+              cacheKey,
+              rvQueryKey(q),
+              { rows: res.rows, total: res.total, at: Date.now() },
+              cacheMax,
+            );
+          setFetchedData(res.rows);
+          setFetchedTotal(res.total);
+          setFetchedLoading(false);
+        })
+        .catch((err) => {
+          if (controller.signal.aborted || id !== reqIdRef.current) return;
+          setFetchedLoading(false);
+          onError?.(err, q);
+        });
+    },
+    [fetcher, cacheKey, ttlMs, cacheMax, onError],
+  );
+  // Abort any in-flight request on unmount.
+  React.useEffect(() => () => abortRef.current?.abort(), []);
+
+  const rows = fetching ? fetchedData : controlled ? data : internalRows;
   const setRows = React.useCallback(
     (updater: React.SetStateAction<T[]>) => {
+      if (fetching) {
+        // Optimistic local update, then invalidate the cache and refetch the
+        // current query in the background so the table reflects server truth.
+        setFetchedData((prev) =>
+          typeof updater === "function"
+            ? (updater as (p: T[]) => T[])(prev)
+            : updater,
+        );
+        if (cacheKey) RV_CACHE.delete(cacheKey);
+        if (queryRef.current) runFetch(queryRef.current, { background: true });
+        return;
+      }
       if (controlled) {
         const next =
           typeof updater === "function"
@@ -459,7 +593,7 @@ export function RecordView<T extends { id: RowId }>({
         setInternalRows(updater);
       }
     },
-    [controlled, data, onDataChange],
+    [fetching, cacheKey, runFetch, controlled, data, onDataChange],
   );
   const [filter, setFilter] = usePersistentState(
     persistKey ? `${persistKey}::filter` : undefined,
@@ -588,7 +722,7 @@ export function RecordView<T extends { id: RowId }>({
   const processed = React.useMemo(() => {
     // Server mode: `rows` is already the filtered/sorted current page — render
     // it verbatim (no client-side filter/sort).
-    if (manual) return rows;
+    if (isManual) return rows;
     let out = rows;
     const q = filter.trim().toLowerCase();
     if (q) {
@@ -617,7 +751,7 @@ export function RecordView<T extends { id: RowId }>({
       });
     }
     return out;
-  }, [manual, rows, filter, sort, fields, getPrimary]);
+  }, [isManual, rows, filter, sort, fields, getPrimary]);
 
   const activeRow = rows.find((r) => r.id === activeId) ?? null;
   const deleteTarget =
@@ -628,18 +762,32 @@ export function RecordView<T extends { id: RowId }>({
   // Pagination (derived; `page` is clamped so it never points past the last page).
   // Server mode: totals come from `rowCount`, and `data` is already this page —
   // so render it whole (no slice) and size the range to what the server returned.
-  const total = manual ? (rowCount ?? processed.length) : processed.length;
+  const total = isManual
+    ? fetching
+      ? fetchedTotal
+      : (rowCount ?? processed.length)
+    : processed.length;
   const totalPages = Math.max(1, Math.ceil(total / pageSize));
   const safePage = Math.min(Math.max(1, page), totalPages);
   const rangeStart = total === 0 ? 0 : (safePage - 1) * pageSize + 1;
-  const rangeEnd = manual
+  const rangeEnd = isManual
     ? total === 0
       ? 0
       : Math.min(rangeStart + processed.length - 1, total)
     : Math.min(safePage * pageSize, total);
-  const paged = manual
+  const paged = isManual
     ? processed
     : processed.slice((safePage - 1) * pageSize, safePage * pageSize);
+  // Loading state comes from the fetcher when it owns the data.
+  const effectiveLoading = fetching ? fetchedLoading : loading;
+  // Keep the current query fresh for post-mutation background refetches.
+  queryRef.current = {
+    page: safePage,
+    pageSize,
+    sort,
+    search: filter,
+    filters: filterValues,
+  };
 
   // Reset to the first page when the filter or page size changes.
   React.useEffect(() => {
@@ -652,16 +800,19 @@ export function RecordView<T extends { id: RowId }>({
   // apply on demand, not per keystroke. `filterValues` is read fresh here but
   // deliberately left out of the deps for that reason.
   React.useEffect(() => {
-    if (!manual) return;
-    onQueryChange?.({
+    if (!isManual) return;
+    const query: ServerQuery<T> = {
       page: safePage,
       pageSize,
       sort,
       search: filter,
       filters: filterValues,
-    });
+    };
+    // `fetcher` owns the fetch; otherwise hand the query to the consumer.
+    if (fetching) runFetch(query);
+    else onQueryChange?.(query);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [manual, safePage, pageSize, sort, filter, onQueryChange]);
+  }, [isManual, fetching, safePage, pageSize, sort, filter, onQueryChange, runFetch]);
 
   // Cascading filter options: when the values change, drop any filter value no
   // longer valid once its options recompute (e.g. changing Region invalidates a
@@ -1308,14 +1459,15 @@ export function RecordView<T extends { id: RowId }>({
                         setFilterValues({});
                         onFilter?.({});
                         setPage(1);
-                        if (manual)
-                          onQueryChange?.({
-                            page: 1,
-                            pageSize,
-                            sort,
-                            search: filter,
-                            filters: {},
-                          });
+                        const q: ServerQuery<T> = {
+                          page: 1,
+                          pageSize,
+                          sort,
+                          search: filter,
+                          filters: {},
+                        };
+                        if (fetching) runFetch(q);
+                        else if (manual) onQueryChange?.(q);
                       }}
                     >
                       Clear
@@ -1325,14 +1477,15 @@ export function RecordView<T extends { id: RowId }>({
                       onClick={() => {
                         onFilter?.(filterValues);
                         setPage(1);
-                        if (manual)
-                          onQueryChange?.({
-                            page: 1,
-                            pageSize,
-                            sort,
-                            search: filter,
-                            filters: filterValues,
-                          });
+                        const q: ServerQuery<T> = {
+                          page: 1,
+                          pageSize,
+                          sort,
+                          search: filter,
+                          filters: filterValues,
+                        };
+                        if (fetching) runFetch(q);
+                        else if (manual) onQueryChange?.(q);
                       }}
                     >
                       <Search className="size-3.5" />
@@ -1544,7 +1697,7 @@ export function RecordView<T extends { id: RowId }>({
             </TableRow>
           </TableHeader>
           <TableBody>
-            {loading ? (
+            {effectiveLoading ? (
               // Animated skeleton rows while data loads from the server.
               Array.from({ length: Math.min(pageSize, 8) }).map((_, i) => (
                 <TableRow key={`skeleton-${i}`} className="hover:bg-transparent">

package/template/app/(app)/data-table/page.tsx

@@ -1,6 +1,5 @@
 "use client";
 
-import { useCallback, useRef, useState } from "react";
 import {
   BackpackIcon as TeamIcon,
   PersonIcon as RoleIcon,
@@ -39,7 +38,7 @@ const ALL: Member[] = Array.from({ length: 213 }, (_, i) => ({
 }));
 
 // Simulated server endpoint: filter + sort + paginate, returning just the page
-// (plus the total). Swap this for a real `fetch` to your API.
+// (plus the total). Swap this for a real `fetch(url, { signal })` to your API.
 function fetchPage(
   q: ServerQuery<Member>,
 ): Promise<{ rows: Member[]; total: number }> {
@@ -100,59 +99,36 @@ const fields: RecordField<Member>[] = [
   },
 ];
 
-function ServerDataTable() {
-  // Server-side mode: RecordView reports the query; we fetch the page and feed
-  // back `data` + `rowCount` + `loading`. It never filters/sorts/paginates here.
-  const [data, setData] = useState<Member[]>([]);
-  const [rowCount, setRowCount] = useState(0);
-  const [loading, setLoading] = useState(true);
-  const reqId = useRef(0);
-
-  const handleQuery = useCallback((q: ServerQuery<Member>) => {
-    const id = ++reqId.current;
-    setLoading(true);
-    void fetchPage(q).then(({ rows, total }) => {
-      if (id !== reqId.current) return; // ignore out-of-order responses
-      setData(rows);
-      setRowCount(total);
-      setLoading(false);
-    });
-  }, []);
-
-  return (
-    <RecordView
-      title="Data Table"
-      singular="Member"
-      icon={TableIcon}
-      manual
-      rowCount={rowCount}
-      loading={loading}
-      onQueryChange={handleQuery}
-      fields={fields}
-      initialData={data}
-      data={data}
-      onDataChange={setData}
-      getPrimary={(row) => ({
-        title: row.name,
-        subtitle: `${row.team} · ${row.role}`,
-        initials: row.name.slice(0, 2).toUpperCase(),
-      })}
-      makeEmptyRow={() => ({
-        id: Date.now(),
-        name: "",
-        team: "",
-        role: "",
-        location: "",
-        commits: 0,
-      })}
-    />
-  );
-}
-
 export default function DataTablePage() {
+  // `fetcher` gives RecordView ownership of the read path: it calls the endpoint
+  // on every query change, manages data / rowCount / loading, and caches
+  // responses under `cacheKey`. With `persistKey`, returning to the tab restores
+  // the same page/sort/filters and hits the cache — instant, no refetch.
   return (
     <main className="h-full">
-      <ServerDataTable />
+      <RecordView
+        title="Data Table"
+        singular="Member"
+        icon={TableIcon}
+        persistKey="/data-table"
+        cacheKey="data-table"
+        fetcher={fetchPage}
+        fields={fields}
+        initialData={[]}
+        getPrimary={(row) => ({
+          title: row.name,
+          subtitle: `${row.team} · ${row.role}`,
+          initials: row.name.slice(0, 2).toUpperCase(),
+        })}
+        makeEmptyRow={() => ({
+          id: Date.now(),
+          name: "",
+          team: "",
+          role: "",
+          location: "",
+          commits: 0,
+        })}
+      />
     </main>
   );
 }

package/template/app/_components/open-tabs.tsx

@@ -503,11 +503,14 @@ export function KeepAliveTabs({ children }: { children: React.ReactNode }) {
   const active = tabKey(usePathname());
   const { tabs } = useOpenTabs();
   const cache = React.useRef(new Map<string, React.ReactNode>());
-  // Refresh the active route's element (so re-opening an /edit tab with a
-  // different record shows the right data); inactive tabs keep their cached
-  // element and stay mounted. In-progress form work survives via RecordForm's
-  // sessionStorage draft (see persistKey), which is StrictMode-safe.
-  cache.current.set(active, children);
+  // Cache each route's element ONCE, on first activation, and reuse it — never
+  // overwrite on re-activation. Reusing the same element reference is what lets
+  // React keep the mounted instance (and its loaded data / scroll / form state)
+  // across tab switches; overwriting with Next's fresh `children` would remount
+  // the subtree and reload everything. Routes that vary by query param (e.g.
+  // /organizations/edit?id=…) share one tab and update themselves via
+  // `useSearchParams`, so they don't need a refresh here.
+  if (!cache.current.has(active)) cache.current.set(active, children);
   // Drop entries for tabs that have been closed.
   const open = new Set(tabs.map((t) => t.href));
   for (const key of [...cache.current.keys()]) {

package/template/lib/seo.ts

@@ -163,6 +163,7 @@ export const PUBLIC_ROUTES: string[] = [
   "/docs/layout",
   "/docs/components",
   "/docs/data-table",
+  "/docs/changelog",
   "/docs/steps",
   "/docs/charts",
   "/docs/auth",