@viliha/vui-ui 1.0.11 → 1.1.1

package/AGENT.md

@@ -226,6 +226,20 @@ Allow RecordView to manage:
 - bulk actions
 - import/export
 
+## Add / edit form
+
+The buffered add/edit form renders in one of two layouts:
+
+- **Slide-over panel** — the default; nothing to configure.
+- **Full-page form** — set `formMode="page"` (with `formColumns={1 | 2}`). Add
+  `formDescription` and a per-field `description` to show an AWS-style help
+  panel beside the form.
+
+For the form on its own URL, render the exported `RecordForm` on a route and use
+controlled data (`data` + `onDataChange`) with `onCreate` / `onView` / `onEdit`
+to navigate instead of opening the overlay. Breadcrumbs everywhere come from the
+shared `@viliha/vui-ui/breadcrumbs` component.
+
 ---
 
 # Charts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.0.11",
+  "version": "1.1.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/breadcrumbs.tsx

@@ -0,0 +1,97 @@
+import * as React from "react";
+import {
+  ArrowLeftIcon as ArrowLeft,
+  ChevronRightIcon as ChevronRight,
+} from "@radix-ui/react-icons";
+
+import { cn } from "./utils";
+
+export interface Crumb {
+  label: React.ReactNode;
+  /** Navigate via a link (rendered with `linkComponent` if given, else <a>). */
+  href?: string;
+  /** Navigate via a handler (rendered as a button). Ignored if href is set. */
+  onClick?: () => void;
+}
+
+/** Minimal link contract so an app can pass its router link (e.g. next/link). */
+type LinkComponent = React.ComponentType<{
+  href: string;
+  className?: string;
+  children: React.ReactNode;
+}>;
+
+const CRUMB_LINK =
+  "shrink-0 text-muted-foreground transition-colors hover:text-foreground";
+
+/**
+ * Shared breadcrumb trail — one style used everywhere (route pages and forms).
+ * The LAST crumb is the current page (bold, non-interactive); earlier crumbs
+ * are links (href) or buttons (onClick).
+ */
+export function Breadcrumbs({
+  crumbs,
+  onBack,
+  linkComponent: Link,
+  className,
+}: {
+  crumbs: Crumb[];
+  /** Optional back button shown before the trail. */
+  onBack?: () => void;
+  linkComponent?: LinkComponent;
+  className?: string;
+}) {
+  return (
+    <div className={cn("flex min-w-0 items-center gap-2 text-sm", className)}>
+      {onBack && (
+        <button
+          type="button"
+          onClick={onBack}
+          aria-label="Go back"
+          title="Back"
+          className="grid size-6 shrink-0 place-items-center rounded-md text-muted-foreground transition-colors hover:bg-accent hover:text-foreground"
+        >
+          <ArrowLeft className="size-3.5" />
+        </button>
+      )}
+      <nav aria-label="Breadcrumb" className="flex min-w-0 items-center gap-1">
+        {crumbs.map((c, i) => {
+          const isLast = i === crumbs.length - 1;
+          return (
+            <span key={i} className="flex min-w-0 items-center gap-1">
+              {isLast ? (
+                <span className="truncate font-medium text-foreground">
+                  {c.label}
+                </span>
+              ) : (
+                <>
+                  {c.href && Link ? (
+                    <Link href={c.href} className={CRUMB_LINK}>
+                      {c.label}
+                    </Link>
+                  ) : c.href ? (
+                    <a href={c.href} className={CRUMB_LINK}>
+                      {c.label}
+                    </a>
+                  ) : (
+                    <button
+                      type="button"
+                      onClick={c.onClick}
+                      className={CRUMB_LINK}
+                    >
+                      {c.label}
+                    </button>
+                  )}
+                  <ChevronRight
+                    className="size-3 shrink-0 text-muted-foreground/60"
+                    aria-hidden="true"
+                  />
+                </>
+              )}
+            </span>
+          );
+        })}
+      </nav>
+    </div>
+  );
+}

package/src/record-view.tsx

@@ -22,6 +22,7 @@ import {
   DotsHorizontalIcon as MoreHorizontal,
   DragHandleDots2Icon as GripVertical,
   EyeOpenIcon as Eye,
+  InfoCircledIcon as Info,
   MagnifyingGlassIcon as Search,
   MixerHorizontalIcon as ListFilter,
   MixerHorizontalIcon as SlidersHorizontal,
@@ -32,6 +33,7 @@ import {
 } from "@radix-ui/react-icons";
 
 import { cn } from "./utils";
+import { Breadcrumbs, type Crumb } from "./breadcrumbs";
 import { Button } from "./button";
 import { Checkbox } from "./checkbox";
 import { Input } from "./input";
@@ -171,6 +173,8 @@ export function usePageTitle(title: string, icon?: IconType) {
 export interface RecordField<T> {
   key: Extract<keyof T, string>;
   label: string;
+  /** Help text shown in the page-form documentation panel. */
+  description?: string;
   icon?: IconType;
   editable?: boolean;
   /** Mark the field mandatory — shows a `*` next to its label. */
@@ -204,6 +208,26 @@ interface RecordViewProps<T extends { id: RowId }> {
     initials: string;
     subtitle?: string;
   };
+  /** Add/Edit form presentation: "panel" slide-over (default) or "page" full-page. */
+  formMode?: "panel" | "page";
+  /** Full-page form column count (page mode only). Default 1. */
+  formColumns?: 1 | 2;
+  /** Navigate to Home from the page-form breadcrumb (e.g. router.push). */
+  onHome?: () => void;
+  /** Intro text for the page-form documentation panel ("about this form"). */
+  formDescription?: string;
+  /** Controlled rows. When set, RecordView renders these and reports edits via
+   *  onDataChange instead of holding rows in internal state. */
+  data?: T[];
+  /** Receives the next rows array in controlled mode. */
+  onDataChange?: (rows: T[]) => void;
+  /** When set, the "add" button calls this (e.g. navigate to a create route)
+   *  instead of opening the built-in form. */
+  onCreate?: () => void;
+  /** When set, opening/editing a row navigates (e.g. to an edit route) instead
+   *  of opening the built-in overlay form. */
+  onView?: (id: RowId) => void;
+  onEdit?: (id: RowId) => void;
 }
 
 export function RecordView<T extends { id: RowId }>({
@@ -214,11 +238,37 @@ export function RecordView<T extends { id: RowId }>({
   initialData,
   makeEmptyRow,
   getPrimary,
+  formMode = "panel",
+  formColumns = 1,
+  onHome,
+  formDescription,
+  data,
+  onDataChange,
+  onCreate,
+  onView,
+  onEdit,
 }: RecordViewProps<T>) {
   const { titleLeading } = React.useContext(PageChromeContext);
   // Surface the page title/icon in the app's global top bar.
   usePageTitle(title, TitleIcon);
-  const [rows, setRows] = React.useState<T[]>(initialData);
+  // Rows are either controlled (data + onDataChange) or held internally.
+  const [internalRows, setInternalRows] = React.useState<T[]>(initialData);
+  const controlled = data !== undefined;
+  const rows = controlled ? data : internalRows;
+  const setRows = React.useCallback(
+    (updater: React.SetStateAction<T[]>) => {
+      if (controlled) {
+        const next =
+          typeof updater === "function"
+            ? (updater as (prev: T[]) => T[])(data as T[])
+            : updater;
+        onDataChange?.(next);
+      } else {
+        setInternalRows(updater);
+      }
+    },
+    [controlled, data, onDataChange],
+  );
   const [filter, setFilter] = React.useState("");
   const [sort, setSort] = React.useState<{
     key: string;
@@ -449,6 +499,11 @@ export function RecordView<T extends { id: RowId }>({
     setBulkDeleteOpen(false);
   }
   function addRow() {
+    // Routed create: delegate to the caller (e.g. navigate to /new).
+    if (onCreate) {
+      onCreate();
+      return;
+    }
     const row = { ...makeEmptyRow(), id: nextId.current++ };
     // Prepend so the new record is immediately visible at the top…
     setRows((prev) => [row, ...prev]);
@@ -459,11 +514,19 @@ export function RecordView<T extends { id: RowId }>({
   }
   /** Open the detail panel read-only (View). */
   function openView(id: RowId) {
+    if (onView) {
+      onView(id);
+      return;
+    }
     setPanelReadOnly(true);
     setActiveId(id);
   }
   /** Open the detail panel editable (Edit). */
   function openEdit(id: RowId) {
+    if (onEdit) {
+      onEdit(id);
+      return;
+    }
     setPanelReadOnly(false);
     setActiveId(id);
   }
@@ -701,6 +764,30 @@ export function RecordView<T extends { id: RowId }>({
     );
   }
 
+  // Full-page form mode: replace the table chrome entirely while adding/editing
+  // (this also hides the import/export/add actions, which live in that chrome).
+  if (formMode === "page" && activeRow) {
+    return (
+      <RecordDetailPanel
+        layout="page"
+        columns={formColumns}
+        isNew={activeId === newRowId}
+        title={title}
+        onHome={onHome}
+        formDescription={formDescription}
+        fields={fields}
+        row={activeRow}
+        singular={singular}
+        icon={TitleIcon}
+        getPrimary={getPrimary}
+        readOnly={panelReadOnly}
+        onEdit={() => setPanelReadOnly(false)}
+        onSave={saveForm}
+        onCancel={cancelForm}
+      />
+    );
+  }
+
   return (
     <div className="flex h-full flex-col">
       {/* Header — title/icon now live in the global top bar; this row holds the
@@ -1189,7 +1276,7 @@ export function RecordView<T extends { id: RowId }>({
             type="button"
             role="menuitem"
             onClick={() => {
-              setActiveId(menu.id);
+              openView(menu.id);
               setMenu(null);
             }}
             className="flex w-full items-center gap-2 rounded-sm px-2 py-1.5 text-left hover:bg-accent hover:text-accent-foreground"
@@ -1284,6 +1371,18 @@ interface DetailPanelProps<T extends { id: RowId }> {
   onSave: (row: T) => void;
   /** Discard the draft (and drop the row if it was never saved). */
   onCancel: () => void;
+  /** "panel" = slide-over (default); "page" = full-page form. */
+  layout?: "panel" | "page";
+  /** Full-page form column count. Default 1. */
+  columns?: 1 | 2;
+  /** New (unsaved) record — drives the "Create new …" breadcrumb. */
+  isNew?: boolean;
+  /** Plural collection title (e.g. "Organizations") — the clickable parent crumb. */
+  title?: string;
+  /** Navigate to Home from the breadcrumb. */
+  onHome?: () => void;
+  /** Intro text for the documentation panel. */
+  formDescription?: string;
 }
 
 function RecordDetailPanel<T extends { id: RowId }>({
@@ -1296,6 +1395,12 @@ function RecordDetailPanel<T extends { id: RowId }>({
   onEdit,
   onSave,
   onCancel,
+  layout = "panel",
+  columns = 1,
+  isNew = false,
+  title,
+  onHome,
+  formDescription,
 }: DetailPanelProps<T>) {
   const [draft, setDraft] = React.useState<T>(row);
   // Reset the buffered form when a different record is opened.
@@ -1330,6 +1435,10 @@ function RecordDetailPanel<T extends { id: RowId }>({
     pending.current = action;
     setClosing(true);
   };
+  // The page layout has no slide-out animation — run the action immediately.
+  const dismiss = (action: () => void) =>
+    layout === "page" ? action() : requestClose(action);
+
   const handleSave = () => {
     const missing = fields.filter(
       (f) =>
@@ -1342,9 +1451,181 @@ function RecordDetailPanel<T extends { id: RowId }>({
       setErrors(new Set(missing.map((f) => f.key)));
       return;
     }
-    requestClose(() => onSave(draft));
+    dismiss(() => onSave(draft));
   };
 
+  // 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);
+    if (groupFields.length === 0) return null;
+    return (
+      <section
+        key={group}
+        className="overflow-hidden rounded-lg border border-border"
+      >
+        <h3 className="border-b border-border bg-muted/40 px-3 py-2 font-semibold text-[var(--button-primary)]">
+          {group}
+        </h3>
+        <dl className="divide-y divide-border">
+          {groupFields.map((f) => (
+            <div
+              key={f.key}
+              className="flex items-start gap-3 px-3 py-3 leading-relaxed"
+            >
+              <dt className="flex w-28 shrink-0 items-center gap-1.5 pt-1.5 text-muted-foreground">
+                {f.icon && (
+                  <f.icon className="size-3.5 text-[var(--button-primary)]" />
+                )}
+                {f.label}
+                {f.required && <RequiredMark />}
+              </dt>
+              <dd className="min-w-0 flex-1">
+                {f.render ? (
+                  <div className="pt-0.5">{f.render(draft)}</div>
+                ) : !readOnly && f.editable ? (
+                  <textarea
+                    value={String(draft[f.key as keyof T] ?? "")}
+                    onChange={(e) => setField(f.key as keyof T, e.target.value)}
+                    aria-label={f.label}
+                    aria-invalid={errors.has(f.key) || undefined}
+                    placeholder={`Add ${f.label.toLowerCase()}`}
+                    rows={1}
+                    // field-sizing grows the box to fit long/wrapped text
+                    className={cn(
+                      "w-full resize-none rounded-sm border bg-background px-2 py-1.5 outline-none [field-sizing:content] placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-inset",
+                      errors.has(f.key)
+                        ? "border-destructive focus-visible:ring-destructive"
+                        : "border-input focus-visible:ring-ring",
+                    )}
+                  />
+                ) : (
+                  <span className="block whitespace-pre-wrap break-words px-2 pt-1.5">
+                    {String(draft[f.key as keyof T] ?? "") || (
+                      <span className="text-muted-foreground">—</span>
+                    )}
+                  </span>
+                )}
+              </dd>
+            </div>
+          ))}
+        </dl>
+      </section>
+    );
+  });
+
+  // Footer actions — View shows Close/Edit; Add/Edit shows Cancel/Save.
+  const formFooter = (
+    <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)}>
+            <X className="size-4" />
+            Close
+          </Button>
+          {onEdit && (
+            <Button variant="primary" onClick={onEdit}>
+              <Pencil className="size-4" />
+              Edit
+            </Button>
+          )}
+        </>
+      ) : (
+        <>
+          <Button onClick={() => dismiss(onCancel)}>
+            <X className="size-4" />
+            Cancel
+          </Button>
+          <Button variant="primary" onClick={handleSave}>
+            <Check className="size-4" />
+            Save
+          </Button>
+        </>
+      )}
+    </div>
+  );
+
+  // Full-page form: breadcrumb header → scrollable single column → fixed actions.
+  if (layout === "page") {
+    const crumb = readOnly
+      ? primary.title || `View ${singular.toLowerCase()}`
+      : isNew
+        ? `Create new ${singular.toLowerCase()}`
+        : `Update ${singular.toLowerCase()}`;
+    // AWS-style documentation column: an intro plus per-field help text.
+    const documentedFields = fields.filter((f) => f.description);
+    const docPanel =
+      formDescription || documentedFields.length > 0 ? (
+        <aside
+          aria-label={`${title ?? singular} help`}
+          className="hidden w-80 shrink-0 overflow-y-auto rounded-lg border border-border bg-muted/20 lg:block"
+        >
+          <div className="space-y-4 p-4 text-sm">
+            <div className="space-y-1.5">
+              <h2 className="flex items-center gap-1.5 font-semibold text-[var(--button-primary)]">
+                <Info className="size-4 text-[var(--button-primary)]" />
+                About {title ?? singular}
+              </h2>
+              {formDescription && (
+                <p className="leading-relaxed text-muted-foreground">
+                  {formDescription}
+                </p>
+              )}
+            </div>
+            {documentedFields.length > 0 && (
+              <dl className="divide-y divide-border border-t border-border">
+                {documentedFields.map((f) => (
+                  <div key={f.key} className="space-y-0.5 py-3 first:pt-4">
+                    <dt className="font-medium text-foreground">{f.label}</dt>
+                    <dd className="leading-relaxed text-muted-foreground">
+                      {f.description}
+                    </dd>
+                  </div>
+                ))}
+              </dl>
+            )}
+          </div>
+        </aside>
+      ) : null;
+    return (
+      <div className="flex h-full flex-col">
+        {/* Breadcrumb — the shared Breadcrumbs component (consistent app-wide). */}
+        <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[]}
+          />
+        </div>
+        {/* Content — form card (left) + optional documentation panel (right). */}
+        <div className="min-h-0 flex-1 overflow-hidden p-4">
+          <div className="flex h-full gap-4">
+            {/* Padded, bordered card — matches the datatable content container. */}
+            <div className="flex h-full min-w-0 flex-1 flex-col overflow-hidden rounded-lg border border-border bg-card">
+              <div className="min-h-0 flex-1 overflow-y-auto p-4 md:p-6">
+                <div
+                  className={cn(
+                    "w-full",
+                    columns === 2
+                      ? "mx-auto grid max-w-5xl grid-cols-1 items-start gap-4 md:grid-cols-2"
+                      : // One column: sections span the full container width.
+                        "space-y-4",
+                  )}
+                >
+                  {formBody}
+                </div>
+              </div>
+              {formFooter}
+            </div>
+            {docPanel}
+          </div>
+        </div>
+      </div>
+    );
+  }
+
   return (
     <>
       {/* Dimmed backdrop — click to close. */}
@@ -1370,122 +1651,48 @@ function RecordDetailPanel<T extends { id: RowId }>({
           }
         }}
       >
-      {/* Header — icon + title (placeholder when new); matches the page header. */}
-      <div className="flex h-12 shrink-0 items-center gap-2 border-b border-border px-4">
-        <span className="flex size-6 shrink-0 items-center justify-center rounded bg-muted text-muted-foreground">
-          <HeaderIcon className="size-3.5" />
-        </span>
-        <span
-          className={cn(
-            "truncate font-semibold",
-            !primary.title && "text-muted-foreground",
-          )}
-        >
-          {primary.title || `New ${singular}`}
-        </span>
-        <Button
-          variant="ghost"
-          size="icon"
-          onClick={() => requestClose(onCancel)}
-          aria-label="Close"
-          className="ml-auto"
-        >
-          <X className="size-4" />
-        </Button>
-      </div>
+        {/* Header — icon + title (placeholder when new); matches the page header. */}
+        <div className="flex h-12 shrink-0 items-center gap-2 border-b border-border px-4">
+          <span className="flex size-6 shrink-0 items-center justify-center rounded bg-muted text-muted-foreground">
+            <HeaderIcon className="size-3.5" />
+          </span>
+          <span
+            className={cn(
+              "truncate font-semibold",
+              !primary.title && "text-muted-foreground",
+            )}
+          >
+            {primary.title || `New ${singular}`}
+          </span>
+          <Button
+            variant="ghost"
+            size="icon"
+            onClick={() => requestClose(onCancel)}
+            aria-label="Close"
+            className="ml-auto"
+          >
+            <X className="size-4" />
+          </Button>
+        </div>
 
-      {/* Body — one bordered section per field group. */}
-      <div className="min-h-0 flex-1 space-y-4 overflow-y-auto p-4">
-        {GROUP_ORDER.map((group) => {
-          const groupFields = fields.filter(
-            (f) => (f.group ?? "General") === group,
-          );
-          if (groupFields.length === 0) return null;
-          return (
-            <section
-              key={group}
-              className="overflow-hidden rounded-lg border border-border"
-            >
-              <h3 className="border-b border-border bg-muted/40 px-3 py-2 font-medium text-muted-foreground">
-                {group}
-              </h3>
-              <dl className="divide-y divide-border">
-                {groupFields.map((f) => (
-                  <div
-                    key={f.key}
-                    className="flex items-start gap-3 px-3 py-3 leading-relaxed"
-                  >
-                    <dt className="flex w-28 shrink-0 items-center gap-1.5 pt-1.5 text-muted-foreground">
-                      {f.icon && <f.icon className="size-3.5" />}
-                      {f.label}
-                      {f.required && <RequiredMark />}
-                    </dt>
-                    <dd className="min-w-0 flex-1">
-                      {f.render ? (
-                        <div className="pt-0.5">{f.render(draft)}</div>
-                      ) : !readOnly && f.editable ? (
-                        <textarea
-                          value={String(draft[f.key as keyof T] ?? "")}
-                          onChange={(e) =>
-                            setField(f.key as keyof T, e.target.value)
-                          }
-                          aria-label={f.label}
-                          aria-invalid={errors.has(f.key) || undefined}
-                          placeholder={`Add ${f.label.toLowerCase()}`}
-                          rows={1}
-                          // field-sizing grows the box to fit long/wrapped text
-                          className={cn(
-                            "w-full resize-none rounded-sm border bg-background px-2 py-1.5 outline-none [field-sizing:content] placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-inset",
-                            errors.has(f.key)
-                              ? "border-destructive focus-visible:ring-destructive"
-                              : "border-input focus-visible:ring-ring",
-                          )}
-                        />
-                      ) : (
-                        <span className="block whitespace-pre-wrap break-words px-2 pt-1.5">
-                          {String(draft[f.key as keyof T] ?? "") || (
-                            <span className="text-muted-foreground">—</span>
-                          )}
-                        </span>
-                      )}
-                    </dd>
-                  </div>
-                ))}
-              </dl>
-            </section>
-          );
-        })}
-      </div>
+        {/* Body — one bordered section per field group. */}
+        <div className="min-h-0 flex-1 space-y-4 overflow-y-auto p-4">
+          {formBody}
+        </div>
 
-      {/* Footer — View shows Close/Edit; Edit shows Cancel/Save. */}
-      <div className="flex shrink-0 items-center justify-end gap-2 border-t border-border px-4 py-3">
-        {readOnly ? (
-          <>
-            <Button onClick={() => requestClose(onCancel)}>
-              <X className="size-4" />
-              Close
-            </Button>
-            {onEdit && (
-              <Button variant="primary" onClick={onEdit}>
-                <Pencil className="size-4" />
-                Edit
-              </Button>
-            )}
-          </>
-        ) : (
-          <>
-            <Button onClick={() => requestClose(onCancel)}>
-              <X className="size-4" />
-              Cancel
-            </Button>
-            <Button variant="primary" onClick={handleSave}>
-              <Check className="size-4" />
-              Save
-            </Button>
-          </>
-        )}
-      </div>
+        {formFooter}
       </aside>
     </>
   );
 }
+
+/**
+ * Standalone full-page record form for a dedicated route (e.g. `/…/new`).
+ * Wraps the page layout of the detail panel so the same form/breadcrumb/doc
+ * chrome is reused outside the table.
+ */
+export function RecordForm<T extends { id: RowId }>(
+  props: Omit<DetailPanelProps<T>, "layout">,
+) {
+  return <RecordDetailPanel layout="page" {...props} />;
+}

package/src/theme.css

@@ -32,7 +32,8 @@
   --destructive-foreground: oklch(0.985 0 0);
   --border: oklch(0.922 0 0);
   --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
+  /* Focus ring uses the brand primary so highlighted fields read as "active". */
+  --ring: var(--button-primary);
   /* Per-page accent (overridden by the app per route) — tints module icons. */
   --page-accent: var(--muted-foreground);
   /* Text highlight (::selection) */
@@ -87,7 +88,7 @@
   --destructive-foreground: oklch(0.985 0 0);
   --border: oklch(1 0 0 / 10%);
   --input: oklch(1 0 0 / 15%);
-  --ring: oklch(0.556 0 0);
+  --ring: var(--button-primary);
   --chart-1: oklch(0.488 0.243 264.376);
   --chart-2: oklch(0.696 0.17 162.48);
   --chart-3: oklch(0.769 0.188 70.08);