@viliha/vui-ui 1.14.2 → 1.16.0

package/AGENT.md

@@ -346,6 +346,10 @@ 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.
+
+A choice field (`options`) shows the option's **label** in the cell (e.g. `SYSTEM` → "System") while staying editable — don't use `render` just to map an enum to a friendly label. To customize the full-page form's breadcrumb, pass a `crumbs` array to `RecordForm` (each `{ label, onClick? }`, last = current page) — e.g. to add an "Access" parent or rename "Create new role" → "New Role".
+
 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,46 @@ backward-compatible features, **major** for breaking changes.
 
 To upgrade, see [Upgrading](./AGENT.md#upgrading) in the agent guide.
 
+## 1.16.0 — 2026-07-27
+
+### Added
+
+- **Configurable page-form breadcrumb.** `RecordForm` (page layout) takes a
+  `crumbs` prop that fully replaces the default `Home › {title} › Create/Update
+  {singular}` trail — add parents (e.g. an "Access" section), rename the last
+  crumb ("New Role"), or reshape it per route. Each crumb is `{ label, onClick? }`;
+  the last is the current page. The `Crumb` type is re-exported from
+  `@viliha/vui-ui/record-view` (also in `@viliha/vui-ui/breadcrumbs`).
+
+### Changed
+
+- **Choice-field cells show the option label, not the raw value.** A field with
+  `options` now renders its matching label in the table (e.g. `SYSTEM` →
+  "System") while staying editable — no need for a read-only `render` just to map
+  an enum to a friendly label. Falls back to the raw value when unmatched.
+
+  **For agents:** use `options` labels for enum columns (not `render`), and pass
+  `crumbs` to `RecordForm` to shape a route's breadcrumb. Docs: `/docs/data-table`.
+
+## 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

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.2",
+  "version": "1.16.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

@@ -34,11 +34,13 @@ import {
 
 import { cn } from "./utils";
 import { Breadcrumbs, type Crumb } from "./breadcrumbs";
+export type { Crumb } from "./breadcrumbs";
 import { Button } from "./button";
 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 +247,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.
@@ -364,6 +369,26 @@ const RV_CACHE = new Map<string, Map<string, RvCacheEntry>>();
 // 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]);
 }
@@ -479,6 +504,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 }>({
@@ -509,6 +538,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.
@@ -1141,6 +1171,12 @@ export function RecordView<T extends { id: RowId }>({
       );
     }
     const value = String(row[field.key] ?? "");
+    // For a choice field, show the option's friendly label (e.g. SYSTEM →
+    // "System") while the cell stays editable — no `render`, no read-only.
+    const display = Array.isArray(field.options)
+      ? (field.options.find((o) => o.value === value)?.label ?? value)
+      : value;
+    const clip = clipCell(display, field.maxChars ?? maxCellChars);
     const cellKey = `${row.id}:${field.key}`;
     const hoverActions =
       (field.editable || (field.copyable && value)) ? (
@@ -1191,9 +1227,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>
@@ -1206,7 +1248,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>
     );
@@ -1749,6 +1797,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}
@@ -1816,9 +1865,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) => (
@@ -2025,6 +2080,11 @@ interface DetailPanelProps<T extends { id: RowId }> {
   /** Persist the in-progress draft under this key (e.g. the route), so a
    *  half-filled form survives leaving and returning via the open-tabs strip. */
   persistKey?: string;
+  /** Page-form breadcrumb override (fully configurable). When set, these crumbs
+   *  replace the default `Home › {title} › Create/Update {singular}` — so you can
+   *  add parents ("Access") or rename the last crumb ("New Role"). Build each
+   *  crumb as `{ label, onClick? }`; the last one is the current page. */
+  crumbs?: Crumb[];
 }
 
 function RecordDetailPanel<T extends { id: RowId }>({
@@ -2044,6 +2104,7 @@ function RecordDetailPanel<T extends { id: RowId }>({
   onHome,
   formDescription,
   persistKey,
+  crumbs,
 }: DetailPanelProps<T>) {
   const draftKey = persistKey ? `${persistKey}::draft` : undefined;
   const [draft, setDraft] = usePersistentState<T>(draftKey, row);
@@ -2315,11 +2376,14 @@ function RecordDetailPanel<T extends { id: RowId }>({
         <div className="flex h-12 shrink-0 items-center border-b border-border px-4">
           <Breadcrumbs
             onBack={onCancel}
-            crumbs={[
-              ...(onHome ? [{ label: "Home", onClick: onHome }] : []),
-              { label: title ?? singular, onClick: onCancel },
-              { label: crumb },
-            ] as Crumb[]}
+            crumbs={
+              crumbs ??
+              ([
+                ...(onHome ? [{ label: "Home", onClick: onHome }] : []),
+                { label: title ?? singular, onClick: onCancel },
+                { label: crumb },
+              ] as Crumb[])
+            }
           />
         </div>
         {/* Content — form card (left) + optional documentation panel (right). */}

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