@viliha/vui-ui 1.14.1 → 1.15.0

package/AGENT.md

@@ -346,6 +346,8 @@ Build forms with VUI and shadcn/ui together, reaching for shadcn Form, React Hoo
 
 Never hand-build an HTML table; always use `RecordView`. Configure columns through its field props (`editable`, `required`, `copyable`, `options`, `render`), and let `RecordView` own the rest: sorting, filtering, pagination, bulk actions, and import/export.
 
+Long cell text never wraps: cells truncate to one line at `maxCellChars` (view prop; defaults to `NEXT_PUBLIC_MAX_CELL_CHARS` or 25) with an ellipsis + hover tooltip. Override a column with the field's `maxChars` (`0` = never truncate). Don't add your own `truncate`/`title` on cells — it's built in.
+
 Sorting follows column visibility by default; use `sortable` to decouple them — `sortable: true` sorts a field with no column (e.g. a `hideInTable` name shown via `getPrimary`), `sortable: false` locks a visible column. Set the flag; don't rewire the Sort dropdown or headers.
 
 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>`.

package/CHANGELOG.md

@@ -7,6 +7,41 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.15.0 — 2026-07-27
+
+### Added
+
+- **Cell truncation in `RecordView` — long text stays on one line.** A cell
+  longer than `maxCellChars` is clipped with an ellipsis (…) and shows the full
+  value in a **styled hover tooltip**, so a sentence never wraps to a second row.
+  The limit defaults to `NEXT_PUBLIC_MAX_CELL_CHARS` (or 25) and is overridable
+  per view (`maxCellChars` prop) or per column (a field's `maxChars`; `0` = never
+  truncate). Applies to the identity/Name cell and every value column.
+- **`Tooltip`** (`@viliha/vui-ui/tooltip`) — a lightweight, dependency-free themed
+  tooltip (portal + fixed positioning, hover/focus, auto-flip). Used by the cell
+  truncation above; reusable anywhere.
+
+  **For agents:** rely on cell truncation instead of adding `truncate`/`title`
+  to cells yourself; set `maxChars` on a field to widen/disable a specific column.
+  For your own tooltips use `Tooltip`, not native `title`. Env:
+  `NEXT_PUBLIC_MAX_CELL_CHARS`. Docs: `/docs/data-table`, `/docs/configuration`.
+
+## 1.14.2 — 2026-07-26
+
+### Changed
+
+- **Consistent loading feedback in `fetcher` mode.** A cache hit is served from
+  the in-memory cache (no server round-trip), but the loading shimmer now stays
+  up for a short minimum (300ms) so a cached load looks the same as a real
+  fetch — no confusing "loading but blank" flash on tab switch. Real fetches
+  longer than the minimum are unaffected; background (post-mutation) refetches
+  stay silent.
+
+  Note: the `fetcher` cache (added in 1.14.0) stores each page's data in a
+  module-scoped `Map` in JS memory, so switching tabs serves from memory and does
+  **not** re-hit the server. If you still see a refetch, you're on a build older
+  than 1.14.0 (the demo before that had no cache).
+
 ## 1.14.1 — 2026-07-26
 
 ### Fixed

package/README.md

@@ -252,7 +252,7 @@ place. If you'd rather keep a verbatim copy, run
 wrapper) · `checkbox` · `combobox` (searchable single-select) · `command-palette`
 (⌘K launcher) · `dialog` · `confirm-dialog` · `dropdown-menu` · `input` · `kbd`
 (key caps + `Shortcut`) · `menu` · `required-mark` · `select` · `steps`
-(multi-step wizard indicator) ·
+(multi-step wizard indicator) · `tooltip` ·
 `table` · `record-view` (the full datatable + `RecordForm`) · plus the `utils`
 (`cn`) helper and the `theme.css` design tokens.
 

package/package.json

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

@@ -39,6 +39,7 @@ import { Checkbox } from "./checkbox";
 import { Input } from "./input";
 import { Select } from "./select";
 import { Combobox } from "./combobox";
+import { Tooltip } from "./tooltip";
 import {
   Table,
   TableBody,
@@ -245,6 +246,9 @@ export interface RecordField<T> {
   width?: number;
   /** Show a copy-to-clipboard action on hover (e.g. email, phone). */
   copyable?: boolean;
+  /** Max characters this cell shows before truncating with an ellipsis + hover
+   *  tooltip. Overrides the view's `maxCellChars`. Set `0` to never truncate. */
+  maxChars?: number;
   /** Show in the detail panel only, not as a table column (e.g. first/last name). */
   hideInTable?: boolean;
   /** Whether this field can be sorted — decoupled from column visibility.
@@ -359,6 +363,31 @@ function resolveOptions<T>(
 type RvCacheEntry = { rows: unknown[]; total: number; at: number };
 const RV_CACHE = new Map<string, Map<string, RvCacheEntry>>();
 
+// Minimum time the loading shimmer stays up per `fetcher` load, so a cache hit
+// (instant, from memory) shows the same animation as a real fetch — consistent
+// feedback instead of a blank flash. Real fetches longer than this are unaffected.
+const RV_MIN_LOADING_MS = 300;
+
+// `process.env.NEXT_PUBLIC_*` is statically inlined by the consumer's bundler
+// (Next / Vite) at build; declare its shape so this source type-checks on its
+// own (the package ships without @types/node).
+declare const process: { env: Record<string, string | undefined> };
+
+// Default max characters a table cell shows before truncating with an ellipsis
+// (+ hover tooltip). From env (inlined at build), fallback 25. Override per-view
+// with `maxCellChars`, or per-field with `maxChars` (0 = never truncate).
+const MAX_CELL_CHARS = (() => {
+  const n = Number(process.env.NEXT_PUBLIC_MAX_CELL_CHARS);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 25;
+})();
+
+/** Clip a cell string to `max` characters. Returns the display text and, when
+ *  clipped, the full text for a `title` (hover tooltip). */
+function clipCell(value: string, max: number): { text: string; full?: string } {
+  if (max <= 0 || value.length <= max) return { text: value };
+  return { text: value.slice(0, max).trimEnd() + "…", full: value };
+}
+
 function rvQueryKey<T>(q: ServerQuery<T>): string {
   return JSON.stringify([q.page, q.pageSize, q.sort, q.search, q.filters]);
 }
@@ -474,6 +503,10 @@ interface RecordViewProps<T extends { id: RowId }> {
   /** 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;
+  /** Max characters any table cell shows before truncating to one line with an
+   *  ellipsis + hover tooltip (long text never wraps). Defaults to
+   *  `NEXT_PUBLIC_MAX_CELL_CHARS` (or 25). Per-field `maxChars` overrides it. */
+  maxCellChars?: number;
 }
 
 export function RecordView<T extends { id: RowId }>({
@@ -504,6 +537,7 @@ export function RecordView<T extends { id: RowId }>({
   cacheKey,
   cache,
   onError,
+  maxCellChars = MAX_CELL_CHARS,
 }: RecordViewProps<T>) {
   const { titleLeading } = React.useContext(PageChromeContext);
   // Surface the page title/icon in the app's global top bar.
@@ -528,17 +562,32 @@ export function RecordView<T extends { id: RowId }>({
   const runFetch = React.useCallback(
     (q: ServerQuery<T>, opts?: { background?: boolean }) => {
       if (!fetcher) return;
-      // Foreground: serve from cache if present (instant, no shimmer).
+      const id = ++reqIdRef.current;
+      const started = Date.now();
+      // Reveal the data, but hold the shimmer for a consistent minimum so a
+      // cache hit (served from memory, no server call) looks the same as a real
+      // fetch — same animation every time, never a confusing blank flash.
+      const commit = (rows: T[], total: number) => {
+        const apply = () => {
+          if (id !== reqIdRef.current) return; // superseded
+          setFetchedData(rows);
+          setFetchedTotal(total);
+          setFetchedLoading(false);
+        };
+        const wait = RV_MIN_LOADING_MS - (Date.now() - started);
+        if (opts?.background || wait <= 0) apply();
+        else window.setTimeout(apply, wait);
+      };
+
+      // Foreground cache hit: no server round-trip — the data is in memory.
       if (!opts?.background && cacheKey) {
         const hit = rvCacheGet(cacheKey, rvQueryKey(q), ttlMs);
         if (hit) {
-          setFetchedData(hit.rows as T[]);
-          setFetchedTotal(hit.total);
-          setFetchedLoading(false);
+          setFetchedLoading(true);
+          commit(hit.rows as T[], hit.total);
           return;
         }
       }
-      const id = ++reqIdRef.current;
       abortRef.current?.abort();
       const controller = new AbortController();
       abortRef.current = controller;
@@ -553,9 +602,7 @@ export function RecordView<T extends { id: RowId }>({
               { rows: res.rows, total: res.total, at: Date.now() },
               cacheMax,
             );
-          setFetchedData(res.rows);
-          setFetchedTotal(res.total);
-          setFetchedLoading(false);
+          commit(res.rows, res.total);
         })
         .catch((err) => {
           if (controller.signal.aborted || id !== reqIdRef.current) return;
@@ -1123,6 +1170,7 @@ export function RecordView<T extends { id: RowId }>({
       );
     }
     const value = String(row[field.key] ?? "");
+    const clip = clipCell(value, field.maxChars ?? maxCellChars);
     const cellKey = `${row.id}:${field.key}`;
     const hoverActions =
       (field.editable || (field.copyable && value)) ? (
@@ -1173,9 +1221,15 @@ export function RecordView<T extends { id: RowId }>({
               ALIGN_BOX[alignOf(field.key)],
             )}
           >
-            <span className="truncate">
-              {value || <span className="text-muted-foreground">—</span>}
-            </span>
+            {clip.full ? (
+              <Tooltip content={clip.full} className="truncate">
+                {clip.text}
+              </Tooltip>
+            ) : (
+              <span className="truncate">
+                {clip.text || <span className="text-muted-foreground">—</span>}
+              </span>
+            )}
           </button>
           {hoverActions}
         </div>
@@ -1188,7 +1242,13 @@ export function RecordView<T extends { id: RowId }>({
           ALIGN_BOX[alignOf(field.key)],
         )}
       >
-        <span className="truncate">{value}</span>
+        {clip.full ? (
+          <Tooltip content={clip.full} className="truncate">
+            {clip.text}
+          </Tooltip>
+        ) : (
+          <span className="truncate">{clip.text}</span>
+        )}
         {hoverActions}
       </div>
     );
@@ -1731,6 +1791,7 @@ export function RecordView<T extends { id: RowId }>({
             ) : processed.length ? (
               paged.map((row) => {
                 const primary = getPrimary(row);
+                const nameClip = clipCell(primary.title, maxCellChars);
                 return (
                   <TableRow
                     key={row.id}
@@ -1798,9 +1859,15 @@ export function RecordView<T extends { id: RowId }>({
                         <span className="flex size-5 shrink-0 items-center justify-center rounded bg-muted font-medium text-muted-foreground">
                           {primary.initials}
                         </span>
-                        <span className="truncate">
-                          {primary.title || "—"}
-                        </span>
+                        {nameClip.full ? (
+                          <Tooltip content={nameClip.full} className="truncate">
+                            {nameClip.text}
+                          </Tooltip>
+                        ) : (
+                          <span className="truncate">
+                            {nameClip.text || "—"}
+                          </span>
+                        )}
                       </button>
                     </TableCell>
                     {visibleFields.map((f) => (

package/src/tooltip.tsx

@@ -0,0 +1,98 @@
+"use client";
+
+import * as React from "react";
+import { createPortal } from "react-dom";
+
+import { cn } from "./utils";
+
+type Placement = { left: number; top: number; up: boolean };
+
+/**
+ * Lightweight styled tooltip. Wraps a trigger and shows `content` in a themed
+ * popover on hover/focus (after a short delay), rendered in a portal with fixed
+ * positioning so it floats above any scroll/overflow container. Flips above or
+ * below depending on room. No dependency — same portal pattern as `Select`.
+ */
+export function Tooltip({
+  content,
+  children,
+  className,
+  delay = 350,
+}: {
+  content: React.ReactNode;
+  /** The trigger — wrapped in an inline element that carries the hover/focus. */
+  children: React.ReactNode;
+  /** Applied to the inline trigger wrapper (e.g. `truncate` for a table cell). */
+  className?: string;
+  /** Hover open delay in ms. */
+  delay?: number;
+}) {
+  const [pos, setPos] = React.useState<Placement | null>(null);
+  const ref = React.useRef<HTMLSpanElement>(null);
+  const timer = React.useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+
+  const place = React.useCallback(() => {
+    const el = ref.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    const up = r.top > 72; // room above? else drop below
+    setPos({
+      left: r.left + r.width / 2,
+      top: up ? r.top - 6 : r.bottom + 6,
+      up,
+    });
+  }, []);
+
+  const open = React.useCallback(() => {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(place, delay);
+  }, [place, delay]);
+
+  const close = React.useCallback(() => {
+    clearTimeout(timer.current);
+    setPos(null);
+  }, []);
+
+  React.useEffect(() => () => clearTimeout(timer.current), []);
+  // Close on scroll (position would go stale).
+  React.useEffect(() => {
+    if (!pos) return;
+    window.addEventListener("scroll", close, true);
+    return () => window.removeEventListener("scroll", close, true);
+  }, [pos, close]);
+
+  return (
+    <span
+      ref={ref}
+      onMouseEnter={open}
+      onMouseLeave={close}
+      onFocus={open}
+      onBlur={close}
+      className={className}
+    >
+      {children}
+      {pos &&
+        typeof document !== "undefined" &&
+        createPortal(
+          <div
+            role="tooltip"
+            style={{
+              position: "fixed",
+              left: pos.left,
+              top: pos.top,
+              transform: pos.up
+                ? "translate(-50%, -100%)"
+                : "translate(-50%, 0)",
+            }}
+            className={cn(
+              "vui-fade-in pointer-events-none z-[220] max-w-xs rounded-md border border-border bg-popover px-2 py-1",
+              "text-xs leading-snug text-popover-foreground shadow-md",
+            )}
+          >
+            {content}
+          </div>,
+          document.body,
+        )}
+    </span>
+  );
+}

package/template/.env.example

@@ -40,6 +40,12 @@ NEXT_PUBLIC_LICENSE="MIT Licensed"
 # more evicts the oldest tab with a warning.
 NEXT_PUBLIC_MAX_TABS="5"
 
+# Max characters a data-table cell shows before truncating to one line with an
+# ellipsis (…) + hover tooltip. Long text never wraps. Default 25. Override per
+# table with the RecordView `maxCellChars` prop, or per column with a field's
+# `maxChars` (0 = never truncate that column).
+NEXT_PUBLIC_MAX_CELL_CHARS="25"
+
 # How a collapsed sidebar rail reveals a group's sub-items. One of:
 #   inline        — expands underneath the icon, in the rail itself
 #   flyout-click  — click the icon to open a floating panel beside the rail