@viliha/vui-ui 1.12.0 → 1.13.1

package/AGENT.md

@@ -338,7 +338,9 @@ Sorting follows column visibility by default; use `sortable` to decouple them
 
 Form controls come from the field: `options` → `Select`, `input: "combobox"` → a searchable `Combobox` (`@viliha/vui-ui/combobox`, use for long lists), `input: "number" | "date"` → native inputs. For anything the built-ins don't cover (checkbox, radio group, slider, custom widget), set `renderInput({ value, onChange, field, invalid })` on the field — it drops any component into the Add/Edit form while the field keeps its label, required mark, and Save validation. Don't hand-build a `<form>`.
 
-Loading from a server: pass `loading` to `RecordView` while the fetch is in flight — it shows animated 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.
+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.
 
 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,44 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 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
+
+- **Server-side ("manual") mode for `RecordView`.** Set `manual` and RecordView
+  stops filtering/sorting/paginating `data` — it renders it as the current page
+  verbatim and reports the query via `onQueryChange({ page, pageSize, sort,
+  search, filters })` so your backend does the work. Pair with `rowCount` (drives
+  the footer + page count) and `loading`. Fires once on mount for the initial
+  load; per-field filters fire it on the Filter panel's Search/Clear. New exported
+  types: `SortState`, `ServerQuery<T>`. Default off — everything stays client-side.
+- **Data Table demo page** in the scaffold (shadcn/ui section) — a full
+  server-side table against a simulated backend (pagination, sort, keyword +
+  per-field filter, loading shimmer, out-of-order-response guard).
+
+### Changed
+
+- The loading skeleton now **shimmers left → right** (a `vui-shimmer` sweep in
+  `theme.css`) instead of a pulse — a clearer "records are loading" cue.
+
+  **For agents:** for a server-backed table use `manual` + `rowCount` +
+  `onQueryChange` (fetch → set `data`/`rowCount`/`loading`); guard stale
+  responses with a request-id ref. Don't reimplement pagination/sort. Demo:
+  the Data Table page. Docs: `/docs/data-table` (Server-side data).
+
 ## 1.12.0 — 2026-07-26
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "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

@@ -213,6 +213,21 @@ export type FilterValues<T> = Partial<
   Record<Extract<keyof T, string>, string | string[]>
 >;
 
+/** Current sort — the field key and direction, or `null` for unsorted. */
+export type SortState = { key: string; dir: "asc" | "desc" };
+
+/** The full query state reported by `onQueryChange` in server (`manual`) mode —
+ *  everything needed to build a request. `page` is 1-based. */
+export type ServerQuery<T> = {
+  page: number;
+  pageSize: number;
+  sort: SortState | null;
+  /** The keyword box. */
+  search: string;
+  /** Per-field filter values (from `filterable` fields). */
+  filters: FilterValues<T>;
+};
+
 export interface RecordField<T> {
   key: Extract<keyof T, string>;
   label: string;
@@ -384,6 +399,20 @@ interface RecordViewProps<T extends { id: RowId }> {
    *  from the server (an initial fetch or a filter/refetch). Set it around your
    *  async load; the toolbar stays usable. */
   loading?: boolean;
+  /** Server-side mode. When `true`, RecordView does NOT filter, sort, or
+   *  paginate `data` — it renders `data` as the current page verbatim and reports
+   *  query state via `onQueryChange`, so your backend does the work. Pair with
+   *  `rowCount` (for totals), `loading`, and `onQueryChange`. Default `false`
+   *  (everything client-side). */
+  manual?: boolean;
+  /** Total row count on the server — drives the pagination footer and page count
+   *  in `manual` mode (RecordView can't infer it from a single page of `data`). */
+  rowCount?: number;
+  /** Server mode: called with the full query whenever page, page size, sort, or
+   *  the keyword changes (and on the per-field Filter Search/Clear). Fetch and
+   *  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;
 }
 
 export function RecordView<T extends { id: RowId }>({
@@ -407,6 +436,9 @@ export function RecordView<T extends { id: RowId }>({
   resizableColumns = false,
   onFilter,
   loading = false,
+  manual = false,
+  rowCount,
+  onQueryChange,
 }: RecordViewProps<T>) {
   const { titleLeading } = React.useContext(PageChromeContext);
   // Surface the page title/icon in the app's global top bar.
@@ -554,6 +586,9 @@ 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;
     let out = rows;
     const q = filter.trim().toLowerCase();
     if (q) {
@@ -582,7 +617,7 @@ export function RecordView<T extends { id: RowId }>({
       });
     }
     return out;
-  }, [rows, filter, sort, fields, getPrimary]);
+  }, [manual, rows, filter, sort, fields, getPrimary]);
 
   const activeRow = rows.find((r) => r.id === activeId) ?? null;
   const deleteTarget =
@@ -591,17 +626,43 @@ export function RecordView<T extends { id: RowId }>({
       : null;
 
   // Pagination (derived; `page` is clamped so it never points past the last page).
-  const totalPages = Math.max(1, Math.ceil(processed.length / pageSize));
+  // 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 totalPages = Math.max(1, Math.ceil(total / pageSize));
   const safePage = Math.min(Math.max(1, page), totalPages);
-  const rangeStart = processed.length === 0 ? 0 : (safePage - 1) * pageSize + 1;
-  const rangeEnd = Math.min(safePage * pageSize, processed.length);
-  const paged = processed.slice((safePage - 1) * pageSize, safePage * pageSize);
+  const rangeStart = total === 0 ? 0 : (safePage - 1) * pageSize + 1;
+  const rangeEnd = manual
+    ? total === 0
+      ? 0
+      : Math.min(rangeStart + processed.length - 1, total)
+    : Math.min(safePage * pageSize, total);
+  const paged = manual
+    ? processed
+    : processed.slice((safePage - 1) * pageSize, safePage * pageSize);
 
   // Reset to the first page when the filter or page size changes.
   React.useEffect(() => {
     setPage(1);
   }, [filter, pageSize, setPage]);
 
+  // Server mode: report the query so the consumer can fetch. Fires on page,
+  // size, sort, and keyword changes (and once on mount for the initial load).
+  // Per-field filters emit via the Filter panel's Search/Clear instead, so they
+  // 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?.({
+      page: safePage,
+      pageSize,
+      sort,
+      search: filter,
+      filters: filterValues,
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [manual, safePage, pageSize, sort, filter, onQueryChange]);
+
   // Cascading filter options: when the values change, drop any filter value no
   // longer valid once its options recompute (e.g. changing Region invalidates a
   // Country filter). Only function-options filters cascade. Strings clear; multi
@@ -1246,13 +1307,33 @@ export function RecordView<T extends { id: RowId }>({
                       onClick={() => {
                         setFilterValues({});
                         onFilter?.({});
+                        setPage(1);
+                        if (manual)
+                          onQueryChange?.({
+                            page: 1,
+                            pageSize,
+                            sort,
+                            search: filter,
+                            filters: {},
+                          });
                       }}
                     >
                       Clear
                     </Button>
                     <Button
                       variant="primary"
-                      onClick={() => onFilter?.(filterValues)}
+                      onClick={() => {
+                        onFilter?.(filterValues);
+                        setPage(1);
+                        if (manual)
+                          onQueryChange?.({
+                            page: 1,
+                            pageSize,
+                            sort,
+                            search: filter,
+                            filters: filterValues,
+                          });
+                      }}
                     >
                       <Search className="size-3.5" />
                       Search
@@ -1341,7 +1422,7 @@ export function RecordView<T extends { id: RowId }>({
               ))}
             </Dropdown>
             <span className="whitespace-nowrap px-1 tabular-nums">
-              {rangeStart}–{rangeEnd} of {processed.length}
+              {rangeStart}–{rangeEnd} of {total}
             </span>
             <button
               type="button"
@@ -1468,22 +1549,22 @@ export function RecordView<T extends { id: RowId }>({
               Array.from({ length: Math.min(pageSize, 8) }).map((_, i) => (
                 <TableRow key={`skeleton-${i}`} className="hover:bg-transparent">
                   <TableCell style={{ width: CHECKBOX_W }}>
-                    <div className="mx-2 size-4 animate-pulse rounded bg-muted" />
+                    <div className="mx-2 size-4 vui-shimmer rounded" />
                   </TableCell>
                   <TableCell style={{ width: colWidths[NAME_COL] }}>
                     <div className="flex items-center gap-2">
-                      <div className="size-7 shrink-0 animate-pulse rounded-full bg-muted" />
-                      <div className="h-3.5 w-32 animate-pulse rounded bg-muted" />
+                      <div className="size-7 shrink-0 vui-shimmer rounded-full" />
+                      <div className="h-3.5 w-32 vui-shimmer rounded" />
                     </div>
                   </TableCell>
                   {visibleFields.map((f) => (
                     <TableCell key={f.key} style={{ width: colWidths[f.key] }}>
-                      <div className="h-3.5 w-20 animate-pulse rounded bg-muted" />
+                      <div className="h-3.5 w-20 vui-shimmer rounded" />
                     </TableCell>
                   ))}
                   <TableCell aria-hidden="true" className="border-r-0" />
                   <TableCell style={{ width: ACTIONS_W }}>
-                    <div className="mx-auto h-4 w-8 animate-pulse rounded bg-muted" />
+                    <div className="mx-auto h-4 w-8 vui-shimmer rounded" />
                   </TableCell>
                 </TableRow>
               ))

package/src/theme.css

@@ -273,6 +273,30 @@
   transform-origin: var(--vui-pop-origin, top);
 }
 
+/* Loading skeleton: a highlight band sweeping left → right over a muted base,
+   the "records are loading" cue. Used by RecordView's loading skeleton rows.
+   (prefers-reduced-motion is respected by the global clamp above.) */
+@keyframes vui-shimmer {
+  from {
+    background-position: -150% 0;
+  }
+  to {
+    background-position: 150% 0;
+  }
+}
+.vui-shimmer {
+  background-color: var(--muted);
+  background-image: linear-gradient(
+    90deg,
+    var(--muted) 0%,
+    color-mix(in oklab, var(--foreground) 12%, var(--muted)) 50%,
+    var(--muted) 100%
+  );
+  background-size: 150% 100%;
+  background-repeat: no-repeat;
+  animation: vui-shimmer 1.5s ease-in-out infinite;
+}
+
 @keyframes vui-slide-out-right {
   from {
     transform: translateX(0);

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

@@ -0,0 +1,15 @@
+import type { Metadata } from "next";
+
+export const metadata: Metadata = {
+  title: "Data Table",
+  description:
+    "Server-side data table demo — pagination, sorting, keyword and per-field filtering handled by the backend, with a loading shimmer, built on RecordView.",
+};
+
+export default function DataTableLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return children;
+}

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

@@ -0,0 +1,158 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import {
+  BackpackIcon as TeamIcon,
+  PersonIcon as RoleIcon,
+  SewingPinFilledIcon as LocationIcon,
+  TableIcon,
+} from "@radix-ui/react-icons";
+
+import {
+  RecordView,
+  type RecordField,
+  type ServerQuery,
+} from "@viliha/vui-ui/record-view";
+
+// A self-contained demo type + dataset. In a real app this lives in your
+// database; here it stands in for the backend table so pagination is visible.
+type Member = {
+  id: number;
+  name: string;
+  team: string;
+  role: string;
+  location: string;
+  commits: number;
+};
+
+const TEAMS = ["Platform", "Growth", "Design", "Data", "Mobile", "Security"];
+const ROLES = ["Engineer", "Manager", "Designer", "Analyst", "Lead"];
+const CITIES = ["Seattle", "Tokyo", "Berlin", "Austin", "Sydney", "London"];
+
+const ALL: Member[] = Array.from({ length: 213 }, (_, i) => ({
+  id: i + 1,
+  name: `Member ${String(i + 1).padStart(3, "0")}`,
+  team: TEAMS[i % TEAMS.length]!,
+  role: ROLES[i % ROLES.length]!,
+  location: CITIES[i % CITIES.length]!,
+  commits: (i * 7) % 500,
+}));
+
+// Simulated server endpoint: filter + sort + paginate, returning just the page
+// (plus the total). Swap this for a real `fetch` to your API.
+function fetchPage(
+  q: ServerQuery<Member>,
+): Promise<{ rows: Member[]; total: number }> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      let out = ALL;
+      const search = q.search.trim().toLowerCase();
+      if (search) {
+        out = out.filter((m) =>
+          [m.name, m.team, m.role, m.location].some((v) =>
+            v.toLowerCase().includes(search),
+          ),
+        );
+      }
+      const team = q.filters.team;
+      if (typeof team === "string" && team) {
+        out = out.filter((m) => m.team === team);
+      }
+      if (q.sort) {
+        const { key, dir } = q.sort;
+        out = [...out].sort((a, b) => {
+          const av = a[key as keyof Member];
+          const bv = b[key as keyof Member];
+          const cmp =
+            typeof av === "number" && typeof bv === "number"
+              ? av - bv
+              : String(av ?? "").localeCompare(String(bv ?? ""));
+          return dir === "asc" ? cmp : -cmp;
+        });
+      }
+      const total = out.length;
+      const start = (q.page - 1) * q.pageSize;
+      resolve({ rows: out.slice(start, start + q.pageSize), total });
+    }, 500);
+  });
+}
+
+const fields: RecordField<Member>[] = [
+  { key: "name", label: "Name", editable: true, required: true, group: "General", hideInTable: true, sortable: true },
+  {
+    key: "team",
+    label: "Team",
+    icon: TeamIcon,
+    editable: true,
+    group: "General",
+    filterable: {
+      control: "select",
+      options: TEAMS.map((t) => ({ value: t, label: t })),
+    },
+  },
+  { key: "role", label: "Role", icon: RoleIcon, editable: true, group: "General" },
+  { key: "location", label: "Location", icon: LocationIcon, editable: true, group: "General" },
+  {
+    key: "commits",
+    label: "Commits",
+    group: "System",
+    render: (row) => <span className="tabular-nums">{row.commits}</span>,
+  },
+];
+
+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() {
+  return (
+    <main className="h-full">
+      <ServerDataTable />
+    </main>
+  );
+}

package/template/app/_components/nav-config.ts

@@ -24,6 +24,7 @@ import {
   RowsIcon as StepsIcon,
   SewingPinFilledIcon as MapPin,
   Share2Icon as Network,
+  TableIcon,
   TargetIcon as Target,
   TextIcon as Languages,
   TokensIcon as Coins,
@@ -75,6 +76,7 @@ export const NAV: NavSection[] = [
     title: "shadcn/ui",
     items: [
       { label: "Components", href: "/components", icon: Blocks, color: "text-indigo-500" },
+      { label: "Data Table", href: "/data-table", icon: TableIcon, color: "text-amber-500" },
       { label: "Forms", href: "/forms", icon: FormInput, color: "text-teal-500" },
       { label: "Steps", href: "/steps", icon: StepsIcon, color: "text-violet-500" },
       { label: "Calendar", href: "/calendar", icon: CalendarIcon, color: "text-rose-500" },

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/app/_components/route-meta.ts

@@ -6,6 +6,7 @@ export const SEGMENT_LABELS: Record<string, string> = {
   dashboard: "Home",
   charts: "Charts",
   components: "Components",
+  "data-table": "Data Table",
   forms: "Forms",
   steps: "Steps",
   calendar: "Calendar",
@@ -36,6 +37,7 @@ export const ROUTE_COLORS: Record<string, string> = {
   "/dashboard": "text-blue-500",
   "/charts": "text-fuchsia-500",
   "/components": "text-indigo-500",
+  "/data-table": "text-amber-500",
   "/forms": "text-teal-500",
   "/steps": "text-violet-500",
   "/calendar": "text-rose-500",
@@ -65,6 +67,7 @@ export const ROUTE_ACCENT: Record<string, string> = {
   "/dashboard": "#3b82f6",
   "/charts": "#d946ef",
   "/components": "#6366f1",
+  "/data-table": "#f59e0b",
   "/forms": "#14b8a6",
   "/steps": "#8b5cf6",
   "/calendar": "#f43f5e",