@viliha/vui-ui 1.1.4 → 1.1.6

package/AGENT.md

@@ -207,6 +207,17 @@ One trail, **derived from the route — never hand-written per page.**
 
 To reorder or rename, edit the nav config; the trail follows automatically.
 
+## Open tabs
+
+Enterprise apps often keep several pages open at once. The reference app ships a
+browser-style **tab strip** under the top bar (a reference-app pattern — copy
+`open-tabs.tsx`): an `OpenTabsProvider` tracks opened routes, switching is a
+router push, and the list persists in `sessionStorage`. Tab labels/icons come
+from the same nav config as the sidebar. ⌘/Ctrl-click a nav item opens a
+background tab; expose an `openTab(href, { background })` for custom "open in new
+tab" buttons. Keep it a navigation-tab model (don't try to keep every page
+mounted) unless you specifically need live state preserved across tabs.
+
 ---
 
 # Forms

package/README.md

@@ -57,6 +57,57 @@ export function Example() {
 }
 ```
 
+### Datatables & forms
+
+`RecordView` is a complete admin datatable from a single `fields` array —
+editable cells, sorting, filtering, pagination, row actions, bulk actions,
+CSV / JSON / Excel / PDF import & export, and a buffered **Add / Edit / View**
+form (slide-over or full-page). Required fields render a `*`, alignment and
+colors come from the tokens — you never style a field by hand.
+
+```tsx
+import { RecordView, type RecordField } from "@viliha/vui-ui/record-view";
+
+const fields: RecordField<Customer>[] = [
+  { key: "name", label: "Name", required: true, hideInTable: true },
+  { key: "email", label: "Email", copyable: true },
+  { key: "country", label: "Country" },
+];
+
+<RecordView
+  title="Customers"
+  singular="Customer"
+  fields={fields}
+  initialData={rows}
+  getPrimary={(r) => ({ title: r.name, initials: r.name.slice(0, 2) })}
+  makeEmptyRow={() => ({ id: Date.now(), name: "", email: "", country: "" })}
+/>;
+```
+
+The same `fields` also drive `RecordForm` — the Add/Edit/View screen — and its
+Info panel (from `formDescription` + per-field `description`). See the
+[Data table docs](https://vui.viliha.com/docs/data-table).
+
+## Patterns
+
+The reference app composes these primitives into the conventions documented at
+[vui.viliha.com/docs/layout](https://vui.viliha.com/docs/layout):
+
+- **Five page types** — data table, record form (Add / Edit / View), dashboard,
+  settings, and kanban board.
+- **Command palette** — Quick actions (`⌘K`, navigate pages) and Global search
+  (`⌘⌥K`, find records), both built on the exported `CommandPalette`.
+- **Open tabs** — a browser-style strip of opened pages under the top bar
+  (⌘-click a nav item for a background tab), persisted across reloads.
+- **Multi-step wizard** — the exported `Steps` indicator + your step state for
+  guided flows (see the `/register-business` demo).
+- **Breadcrumbs** — the exported `Breadcrumbs` component fed a route-derived
+  trail.
+
+Copy them from the
+[backoffice demo](https://github.com/myviliha/vui-starter/tree/main/apps/backoffice)
+and adapt.
+
 ## Building with an AI agent
 
 This package ships an **AI-agent usage guide** at
@@ -78,9 +129,9 @@ verbatim copy? `cp node_modules/@viliha/vui-ui/AGENT.md AGENTS.md`.
 `avatar` · `badge` · `breadcrumbs` · `button` · `card` · `chart` (themed Recharts
 wrapper) · `checkbox` · `command-palette` (⌘K launcher) · `dialog` ·
 `confirm-dialog` · `dropdown-menu` · `input` · `kbd` (key caps + `Shortcut`) ·
-`menu` · `required-mark` · `select` · `table` · `record-view` (the full datatable
-+ `RecordForm`) · plus the `utils` (`cn`) helper and the `theme.css` design
-tokens.
+`menu` · `required-mark` · `select` · `steps` (multi-step wizard indicator) ·
+`table` · `record-view` (the full datatable + `RecordForm`) · plus the `utils`
+(`cn`) helper and the `theme.css` design tokens.
 
 ## Theming
 

package/package.json

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

@@ -196,6 +196,54 @@ export interface RecordField<T> {
   options?: { value: string; label: string }[];
 }
 
+/**
+ * `useState` that mirrors to `sessionStorage` under `key`, so a page's work
+ * (table filters/sort/page, a form draft) survives leaving and returning — the
+ * per-tab work-preservation behind the open-tabs strip. When `key` is undefined
+ * it is a plain `useState`, so this is fully opt-in and backward compatible.
+ * Restores on mount (client-only, so exported/SSR markup still matches) and
+ * never clobbers stored data with the initial value.
+ */
+function usePersistentState<T>(
+  key: string | undefined,
+  initial: T,
+): [T, React.Dispatch<React.SetStateAction<T>>] {
+  const [state, setState] = React.useState<T>(initial);
+  const firstWrite = React.useRef(true);
+  React.useEffect(() => {
+    if (!key) return;
+    try {
+      const raw = sessionStorage.getItem(key);
+      if (raw !== null) setState(JSON.parse(raw) as T);
+    } catch {
+      // ignore malformed storage
+    }
+  }, [key]);
+  React.useEffect(() => {
+    if (!key) return;
+    if (firstWrite.current) {
+      firstWrite.current = false; // don't overwrite stored value with `initial`
+      return;
+    }
+    try {
+      sessionStorage.setItem(key, JSON.stringify(state));
+    } catch {
+      // ignore storage failures (private mode, quota)
+    }
+  }, [key, state]);
+  return [state, setState];
+}
+
+/** Drop a persisted key — e.g. once a form Save/Cancel discards its draft. */
+function clearPersisted(key: string | undefined) {
+  if (!key) return;
+  try {
+    sessionStorage.removeItem(key);
+  } catch {
+    // ignore
+  }
+}
+
 interface RecordViewProps<T extends { id: RowId }> {
   title: string;
   singular: string;
@@ -228,6 +276,9 @@ interface RecordViewProps<T extends { id: RowId }> {
    *  of opening the built-in overlay form. */
   onView?: (id: RowId) => void;
   onEdit?: (id: RowId) => void;
+  /** Persist this view's filter / sort / page under this key (e.g. the route),
+   *  so the work survives leaving and returning via the open-tabs strip. */
+  persistKey?: string;
 }
 
 export function RecordView<T extends { id: RowId }>({
@@ -247,6 +298,7 @@ export function RecordView<T extends { id: RowId }>({
   onCreate,
   onView,
   onEdit,
+  persistKey,
 }: RecordViewProps<T>) {
   const { titleLeading } = React.useContext(PageChromeContext);
   // Surface the page title/icon in the app's global top bar.
@@ -269,11 +321,14 @@ export function RecordView<T extends { id: RowId }>({
     },
     [controlled, data, onDataChange],
   );
-  const [filter, setFilter] = React.useState("");
-  const [sort, setSort] = React.useState<{
+  const [filter, setFilter] = usePersistentState(
+    persistKey ? `${persistKey}::filter` : undefined,
+    "",
+  );
+  const [sort, setSort] = usePersistentState<{
     key: string;
     dir: "asc" | "desc";
-  } | null>(null);
+  } | null>(persistKey ? `${persistKey}::sort` : undefined, null);
   const [hidden, setHidden] = React.useState<Set<string>>(new Set());
   const [selected, setSelected] = React.useState<Set<RowId>>(new Set());
   const [editing, setEditing] = React.useState<{
@@ -289,7 +344,10 @@ export function RecordView<T extends { id: RowId }>({
   const [bulkDeleteOpen, setBulkDeleteOpen] = React.useState(false);
   // Whether the detail panel opened read-only (View) or editable (Edit / Add).
   const [panelReadOnly, setPanelReadOnly] = React.useState(false);
-  const [page, setPage] = React.useState(1);
+  const [page, setPage] = usePersistentState(
+    persistKey ? `${persistKey}::page` : undefined,
+    1,
+  );
   const [pageSize, setPageSize] = React.useState<number>(25);
   const [flashId, setFlashId] = React.useState<RowId | null>(null);
   const [copiedKey, setCopiedKey] = React.useState<string | null>(null);
@@ -418,7 +476,7 @@ export function RecordView<T extends { id: RowId }>({
   // Reset to the first page when the filter or page size changes.
   React.useEffect(() => {
     setPage(1);
-  }, [filter, pageSize]);
+  }, [filter, pageSize, setPage]);
 
   function startEdit(row: T, key: string) {
     setEditing({ id: row.id, key });
@@ -1390,6 +1448,9 @@ interface DetailPanelProps<T extends { id: RowId }> {
   onHome?: () => void;
   /** Intro text for the documentation panel. */
   formDescription?: string;
+  /** 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;
 }
 
 function RecordDetailPanel<T extends { id: RowId }>({
@@ -1408,13 +1469,19 @@ function RecordDetailPanel<T extends { id: RowId }>({
   title,
   onHome,
   formDescription,
+  persistKey,
 }: DetailPanelProps<T>) {
-  const [draft, setDraft] = React.useState<T>(row);
-  // Reset the buffered form when a different record is opened.
+  const draftKey = persistKey ? `${persistKey}::draft` : undefined;
+  const [draft, setDraft] = usePersistentState<T>(draftKey, row);
+  // Reset the buffered form only when a *genuinely different* record is opened.
+  // Tracking the last id (not a "first run" flag) is StrictMode-safe: the dev
+  // double-invoke sees the same id and won't wipe a restored / in-progress draft.
+  const lastRowId = React.useRef(row.id);
   React.useEffect(() => {
+    if (lastRowId.current === row.id) return;
+    lastRowId.current = row.id;
     setDraft(row);
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [row.id]);
+  }, [row, setDraft]);
 
   const primary = getPrimary(draft);
   const HeaderIcon = TitleIcon ?? DEFAULT_FIELD_ICON;
@@ -1458,9 +1525,16 @@ function RecordDetailPanel<T extends { id: RowId }>({
       setErrors(new Set(missing.map((f) => f.key)));
       return;
     }
+    clearPersisted(draftKey); // work committed — drop the saved draft
     dismiss(() => onSave(draft));
   };
 
+  // Cancel/close discards the draft too, so it doesn't reappear next visit.
+  const handleCancel = () => {
+    clearPersisted(draftKey);
+    dismiss(onCancel);
+  };
+
   // Grouped field sections — shared by the slide-over and full-page layouts.
   const formBody = GROUP_ORDER.map((group) => {
     const groupFields = fields.filter((f) => (f.group ?? "General") === group);
@@ -1528,7 +1602,7 @@ function RecordDetailPanel<T extends { id: RowId }>({
     <div className="flex shrink-0 items-center justify-end gap-2 border-y border-border bg-muted/40 px-4 py-3">
       {readOnly ? (
         <>
-          <Button onClick={() => dismiss(onCancel)}>
+          <Button onClick={handleCancel}>
             <X className="size-4" />
             Close
           </Button>
@@ -1541,7 +1615,7 @@ function RecordDetailPanel<T extends { id: RowId }>({
         </>
       ) : (
         <>
-          <Button onClick={() => dismiss(onCancel)}>
+          <Button onClick={handleCancel}>
             <X className="size-4" />
             Cancel
           </Button>
@@ -1644,7 +1718,7 @@ function RecordDetailPanel<T extends { id: RowId }>({
           "fixed inset-0 z-[55] bg-foreground/25",
           closing ? "vui-overlay-out" : "vui-overlay-in",
         )}
-        onClick={() => requestClose(onCancel)}
+        onClick={handleCancel}
         aria-hidden="true"
       />
       <aside
@@ -1677,7 +1751,7 @@ function RecordDetailPanel<T extends { id: RowId }>({
           <Button
             variant="ghost"
             size="icon"
-            onClick={() => requestClose(onCancel)}
+            onClick={handleCancel}
             aria-label="Close"
             className="ml-auto"
           >

package/src/select.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import * as React from "react";
+import { createPortal } from "react-dom";
 import {
   CheckIcon as Check,
   ChevronDownIcon as ChevronDown,
@@ -13,10 +14,20 @@ export interface SelectOption {
   label: string;
 }
 
+type Placement = {
+  left: number;
+  width: number;
+  top?: number;
+  bottom?: number;
+  maxHeight: number;
+};
+
 /**
  * Custom single-select styled to match the app (Input-like trigger + popover
  * list), replacing the native `<select>`. Click-to-open, outside-click/Escape
- * to close, checkmark on the active option.
+ * to close, checkmark on the active option. The list is rendered in a portal
+ * with fixed positioning so it floats above any scrolling/overflow container
+ * (forms, dialogs, the tab-kept pages) instead of being clipped.
  */
 export function Select({
   value,
@@ -37,14 +48,47 @@ export function Select({
   className?: string;
 }) {
   const [open, setOpen] = React.useState(false);
-  const ref = React.useRef<HTMLDivElement>(null);
+  const [pos, setPos] = React.useState<Placement | null>(null);
+  const rootRef = React.useRef<HTMLDivElement>(null);
+  const triggerRef = React.useRef<HTMLButtonElement>(null);
+  const listRef = React.useRef<HTMLDivElement>(null);
+
+  const place = React.useCallback(() => {
+    const el = triggerRef.current;
+    if (!el) return;
+    const r = el.getBoundingClientRect();
+    const below = window.innerHeight - r.bottom;
+    const above = r.top;
+    // Flip up when there isn't room below and there's more room above.
+    const openUp = below < 240 && above > below;
+    setPos({
+      left: r.left,
+      width: r.width,
+      top: openUp ? undefined : r.bottom + 4,
+      bottom: openUp ? window.innerHeight - r.top + 4 : undefined,
+      maxHeight: Math.min(240, (openUp ? above : below) - 8),
+    });
+  }, []);
+
+  React.useLayoutEffect(() => {
+    if (!open) return;
+    place();
+    const reflow = () => place();
+    // capture: catch scrolls inside any ancestor container, not just the window
+    window.addEventListener("scroll", reflow, true);
+    window.addEventListener("resize", reflow);
+    return () => {
+      window.removeEventListener("scroll", reflow, true);
+      window.removeEventListener("resize", reflow);
+    };
+  }, [open, place]);
 
   React.useEffect(() => {
     if (!open) return;
     const onDown = (e: MouseEvent) => {
-      if (ref.current && !ref.current.contains(e.target as Node)) {
-        setOpen(false);
-      }
+      const t = e.target as Node;
+      if (rootRef.current?.contains(t) || listRef.current?.contains(t)) return;
+      setOpen(false);
     };
     const onKey = (e: KeyboardEvent) => {
       if (e.key === "Escape") setOpen(false);
@@ -60,8 +104,9 @@ export function Select({
   const selected = options.find((o) => o.value === value);
 
   return (
-    <div className={cn("relative", className)} ref={ref}>
+    <div className={cn("relative", className)} ref={rootRef}>
       <button
+        ref={triggerRef}
         type="button"
         id={id}
         aria-haspopup="listbox"
@@ -84,39 +129,52 @@ export function Select({
           aria-hidden="true"
         />
       </button>
-      {open && (
-        <div
-          role="listbox"
-          aria-label={ariaLabel}
-          tabIndex={-1}
-          className="vui-pop-in absolute z-50 mt-1 max-h-60 w-full min-w-max overflow-auto rounded-md border border-border bg-popover text-popover-foreground shadow-md"
-        >
-          {options.map((o) => {
-            const active = o.value === value;
-            return (
-              <button
-                key={o.value}
-                type="button"
-                role="option"
-                aria-selected={active}
-                onClick={() => {
-                  onValueChange(o.value);
-                  setOpen(false);
-                }}
-                className={cn(
-                  "flex w-full items-center justify-between gap-2 border-b border-border px-3 py-2 text-left last:border-b-0 hover:bg-accent hover:text-accent-foreground",
-                  active && "bg-accent/60",
-                )}
-              >
-                <span className="truncate">{o.label}</span>
-                {active && (
-                  <Check className="size-3.5 shrink-0 text-[var(--button-primary)]" />
-                )}
-              </button>
-            );
-          })}
-        </div>
-      )}
+      {open &&
+        pos &&
+        typeof document !== "undefined" &&
+        createPortal(
+          <div
+            ref={listRef}
+            role="listbox"
+            aria-label={ariaLabel}
+            tabIndex={-1}
+            style={{
+              position: "fixed",
+              left: pos.left,
+              width: pos.width,
+              top: pos.top,
+              bottom: pos.bottom,
+              maxHeight: pos.maxHeight,
+            }}
+            className="vui-pop-in z-[200] overflow-auto rounded-md border border-border bg-popover text-popover-foreground shadow-md"
+          >
+            {options.map((o) => {
+              const active = o.value === value;
+              return (
+                <button
+                  key={o.value}
+                  type="button"
+                  role="option"
+                  aria-selected={active}
+                  onClick={() => {
+                    onValueChange(o.value);
+                    setOpen(false);
+                  }}
+                  className={cn(
+                    "flex w-full items-center justify-between gap-2 border-b border-border px-3 py-2 text-left last:border-b-0 hover:bg-accent hover:text-accent-foreground",
+                    active && "bg-accent/60",
+                  )}
+                >
+                  <span className="truncate">{o.label}</span>
+                  {active && (
+                    <Check className="size-3.5 shrink-0 text-[var(--button-primary)]" />
+                  )}
+                </button>
+              );
+            })}
+          </div>,
+          document.body,
+        )}
     </div>
   );
 }

package/src/steps.tsx

@@ -0,0 +1,104 @@
+import * as React from "react";
+import { CheckIcon } from "@radix-ui/react-icons";
+
+import { cn } from "./utils";
+
+export type Step = {
+  /** Short title shown under the marker. */
+  label: string;
+  /** Optional secondary line under the label. */
+  description?: string;
+};
+
+/**
+ * A horizontal, numbered step indicator for multi-step forms / wizards.
+ * Presentational and controlled: pass the steps and the current index. Completed
+ * steps fill with the brand primary and a check; the current step is ringed;
+ * upcoming steps are muted. All color comes from theme tokens.
+ *
+ * ```tsx
+ * <Steps
+ *   current={step}
+ *   steps={[
+ *     { label: "Organization", description: "Business details" },
+ *     { label: "Account", description: "Your credentials" },
+ *     { label: "Review", description: "Confirm details" },
+ *   ]}
+ * />
+ * ```
+ */
+export function Steps({
+  steps,
+  current,
+  className,
+}: {
+  steps: Step[];
+  /** Zero-based index of the active step. */
+  current: number;
+  className?: string;
+}) {
+  return (
+    <ol
+      className={cn("flex items-start", className)}
+      aria-label={`Step ${current + 1} of ${steps.length}`}
+    >
+      {steps.map((step, i) => {
+        const state =
+          i < current ? "complete" : i === current ? "current" : "upcoming";
+        const isLast = i === steps.length - 1;
+        return (
+          <React.Fragment key={step.label}>
+            <li
+              className="flex flex-col items-center gap-2 text-center"
+              aria-current={state === "current" ? "step" : undefined}
+            >
+              <span
+                className={cn(
+                  "grid size-8 shrink-0 place-items-center rounded-full border-2 text-sm font-semibold transition-colors",
+                  state === "complete" &&
+                    "border-transparent bg-[var(--button-primary)] text-[var(--button-primary-foreground)]",
+                  state === "current" &&
+                    "border-[var(--button-primary)] text-[var(--button-primary)]",
+                  state === "upcoming" &&
+                    "border-border bg-background text-muted-foreground",
+                )}
+              >
+                {state === "complete" ? (
+                  <CheckIcon className="size-4" />
+                ) : (
+                  i + 1
+                )}
+              </span>
+              <span className="flex flex-col gap-0.5">
+                <span
+                  className={cn(
+                    "text-sm font-medium leading-none",
+                    state === "upcoming"
+                      ? "text-muted-foreground"
+                      : "text-foreground",
+                  )}
+                >
+                  {step.label}
+                </span>
+                {step.description && (
+                  <span className="text-xs text-muted-foreground">
+                    {step.description}
+                  </span>
+                )}
+              </span>
+            </li>
+            {!isLast && (
+              <span
+                aria-hidden="true"
+                className={cn(
+                  "mt-4 h-0.5 min-w-6 flex-1 rounded-full transition-colors",
+                  i < current ? "bg-[var(--button-primary)]" : "bg-border",
+                )}
+              />
+            )}
+          </React.Fragment>
+        );
+      })}
+    </ol>
+  );
+}