@viliha/vui-ui 1.11.1 → 1.12.0

package/AGENT.md

@@ -338,6 +338,8 @@ 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.
+
 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).
 
 ## Filtering

package/CHANGELOG.md

@@ -7,6 +7,19 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.12.0 — 2026-07-26
+
+### Added
+
+- **`RecordView` `loading` prop** — while `true`, the table body renders animated
+  skeleton rows (matched to the columns) instead of an empty-state flash, for
+  slow server loads (initial fetch or refetch). The toolbar stays usable; clear
+  `loading` when the data arrives.
+
+  **For agents:** wrap your fetch with `loading` (`setLoading(true)` → fetch →
+  `finally(() => setLoading(false))`); don't hand-roll a spinner overlay. Demo:
+  `markets` simulates a load on first visit. Docs: `/docs/data-table`.
+
 ## 1.11.1 — 2026-07-26
 
 ### Changed

package/package.json

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

@@ -380,6 +380,10 @@ interface RecordViewProps<T extends { id: RowId }> {
    *  or client-side filtering here. In per-field mode the panel does not match
    *  rows itself, so the behavior is entirely yours. */
   onFilter?: (values: FilterValues<T>) => void;
+  /** Show animated skeleton rows instead of the table body while data loads
+   *  from the server (an initial fetch or a filter/refetch). Set it around your
+   *  async load; the toolbar stays usable. */
+  loading?: boolean;
 }
 
 export function RecordView<T extends { id: RowId }>({
@@ -402,6 +406,7 @@ export function RecordView<T extends { id: RowId }>({
   persistKey,
   resizableColumns = false,
   onFilter,
+  loading = false,
 }: RecordViewProps<T>) {
   const { titleLeading } = React.useContext(PageChromeContext);
   // Surface the page title/icon in the app's global top bar.
@@ -1458,7 +1463,31 @@ export function RecordView<T extends { id: RowId }>({
             </TableRow>
           </TableHeader>
           <TableBody>
-            {processed.length ? (
+            {loading ? (
+              // 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">
+                  <TableCell style={{ width: CHECKBOX_W }}>
+                    <div className="mx-2 size-4 animate-pulse rounded bg-muted" />
+                  </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>
+                  </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" />
+                    </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" />
+                  </TableCell>
+                </TableRow>
+              ))
+            ) : processed.length ? (
               paged.map((row) => {
                 const primary = getPrimary(row);
                 return (

package/template/app/(app)/markets/markets-table.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useEffect, useState } from "react";
 import {
   CubeIcon as Building,
   GlobeIcon as Compass,
@@ -51,13 +52,28 @@ const fields: RecordField<Market>[] = [
 ];
 
 export function MarketsTable() {
+  // Demo: simulate loading records from a server so the skeleton state shows on
+  // first visit. In a real app, set `loading` around your fetch/refetch.
+  const [data, setData] = useState<Market[]>([]);
+  const [loading, setLoading] = useState(true);
+  useEffect(() => {
+    const t = setTimeout(() => {
+      setData(markets);
+      setLoading(false);
+    }, 900);
+    return () => clearTimeout(t);
+  }, []);
+
   return (
     <RecordView
       title="Markets"
       singular="Market"
       icon={MapPin}
+      loading={loading}
       fields={fields}
-      initialData={markets}
+      initialData={data}
+      data={data}
+      onDataChange={setData}
       getPrimary={(row) => ({
         title: row.name,
         subtitle: row.organization,