@viliha/vui-ui 1.0.9 → 1.0.11

package/AGENT.md

@@ -0,0 +1,425 @@
+# Using VUI in your project (AI agent guide)
+
+> **Audience:** developers — and their AI agents — **consuming** `@viliha/vui-ui`
+> in a downstream app. This file ships with the npm package; point your agent at
+> `node_modules/@viliha/vui-ui/AGENT.md` (or copy it into your repo, e.g. rename
+> to `AGENTS.md` so agent tools auto-load it). To *contribute to* the theme
+> itself, see [CONTRIBUTING.md](https://github.com/myviliha/vui-starter/blob/main/CONTRIBUTING.md)
+> and [AGENTS.md](https://github.com/myviliha/vui-starter/blob/main/AGENTS.md).
+
+You are an expert Frontend Architect building enterprise applications using **VUI Starter**.
+
+Your responsibility is to build applications that are consistent, maintainable, accessible, and production-ready by fully embracing the VUI Design System.
+
+Do not reinvent the framework. Build with it.
+
+> **What you get from the package vs. what to copy.** `@viliha/vui-ui` ships the
+> component primitives (`Button`, `Input`, `Select`, `Dialog`, `Menu`,
+> `RecordView`, `ChartContainer`, `theme.css`, …). App-shell patterns referenced
+> below — `SetPageTitle`, `Breadcrumbs`, the sidebar/`nav-config`, and the
+> `AuthCard*` auth screens — are **reference-app patterns**, not package exports.
+> Copy them from the [backoffice demo](https://github.com/myviliha/vui-starter/tree/main/apps/backoffice)
+> and adapt.
+
+---
+
+# Core Principles
+
+Always prioritize:
+
+1. Reuse over rebuilding.
+2. Consistency over customization.
+3. Composition over configuration.
+4. Simplicity over abstraction.
+5. Accessibility by default.
+6. Performance by default.
+7. Predictable user experiences.
+8. Enterprise-grade maintainability.
+
+When multiple approaches exist, choose the one that best aligns with VUI.
+
+---
+
+# Think Before You Build
+
+Before creating anything:
+
+1. Search for an existing VUI component.
+2. Search for an existing page pattern.
+3. Search for an existing layout.
+4. Search for an existing variant.
+5. Search for an existing utility.
+
+Never duplicate functionality already provided by VUI.
+
+---
+
+# Installation Requirements
+
+VUI ships as TypeScript source.
+
+## Next.js
+
+Always configure:
+
+```ts
+transpilePackages: ["@viliha/vui-ui"]
+```
+
+Import once:
+
+```css
+@import "tailwindcss";
+@import "@viliha/vui-ui/theme.css";
+```
+
+## Vite
+
+Import the theme once.
+
+No additional transpilation is required.
+
+---
+
+# Design Tokens
+
+VUI is completely token-driven.
+
+Never hardcode:
+
+- colors
+- spacing
+- radius
+- typography
+- shadows
+- borders
+
+Always use semantic design tokens.
+
+Examples:
+
+- --button-primary
+- --button-primary-hover
+- --background
+- --foreground
+- --border
+- --ring
+- --chart-1
+- --sidebar-primary
+
+Never use arbitrary values unless absolutely necessary.
+
+---
+
+# Application Structure
+
+Organize applications using feature-first architecture.
+
+Example:
+
+```
+app/
+
+components/
+
+features/
+
+hooks/
+
+lib/
+
+services/
+
+types/
+```
+
+Keep business logic outside UI components.
+
+---
+
+# Page Layout
+
+Every application page should follow the standard VUI layout.
+
+```
+SetPageTitle
+
+↓
+
+Action Header
+
+↓
+
+Scrollable Content
+```
+
+Only the content area should scroll.
+
+The page structure should remain consistent throughout the application.
+
+---
+
+# Sections
+
+Use bordered cards.
+
+Avoid deeply nested layouts.
+
+Use spacing to create hierarchy before introducing additional borders.
+
+---
+
+# Navigation
+
+Always use:
+
+- Breadcrumbs
+- Sidebar
+- Top Navigation
+
+Do not build custom navigation systems unless the project explicitly requires it.
+
+---
+
+# Forms
+
+Use VUI and shadcn/ui together.
+
+Prefer:
+
+- shadcn Form
+- React Hook Form
+- Zod
+
+Every form should support:
+
+- validation
+- loading
+- success
+- error
+- disabled
+- keyboard navigation
+
+Never rely on placeholders as labels.
+
+---
+
+# Tables
+
+Never build HTML tables.
+
+Always use RecordView.
+
+Use:
+
+- editable
+- required
+- copyable
+- options
+- render
+
+Allow RecordView to manage:
+
+- sorting
+- filtering
+- pagination
+- bulk actions
+- import/export
+
+---
+
+# Charts
+
+Always build charts with:
+
+ChartContainer
+
++
+
+Recharts
+
+Never hardcode chart colors.
+
+Always map colors through chart tokens.
+
+---
+
+# Authentication
+
+The auth screens are a **demo pattern in the reference app**, not exports of the
+`@viliha/vui-ui` package. `AuthCard`, `AuthCardHeader`, `AuthCardBody`,
+`AuthCardFooter` and `AuthCardAside` live in
+`apps/backoffice/app/_components/auth.tsx` — **copy and adapt them** into your
+app (they are built from published primitives: `Button`, `Input`, tokens).
+
+Do not `import … from "@viliha/vui-ui/auth"` — no such entry point exists.
+
+Wrap forms with semantic HTML.
+
+---
+
+# shadcn/ui Integration
+
+VUI complements shadcn/ui.
+
+Use shadcn for:
+
+- forms
+- dialogs
+- sheets
+- tabs
+- popovers
+- accordions
+
+Use VUI for:
+
+- layouts
+- RecordView
+- enterprise components
+- charts
+- navigation patterns
+
+VUI owns the design tokens.
+
+Remove duplicated token definitions generated by shadcn.
+
+---
+
+# Accessibility
+
+Every page should support:
+
+- keyboard navigation
+- visible focus
+- ARIA attributes
+- screen readers
+- WCAG AA contrast
+
+Accessibility is never optional.
+
+---
+
+# Responsive Design
+
+Design mobile first.
+
+Support:
+
+- Mobile
+- Tablet
+- Desktop
+- Large Desktop
+
+Avoid horizontal scrolling whenever possible.
+
+---
+
+# Performance
+
+Prefer:
+
+- Server Components
+- Streaming
+- Lazy loading
+- Dynamic imports
+
+Avoid unnecessary client components.
+
+Memoize only when needed.
+
+---
+
+# UX Standards
+
+Every feature should communicate its current state.
+
+Support:
+
+- Loading
+- Success
+- Empty
+- Error
+
+Long-running actions should provide visible progress.
+
+Never leave users wondering what happened.
+
+---
+
+# Naming
+
+Prefer descriptive names.
+
+Good
+
+```
+OrganizationTable
+
+InvoiceSummaryCard
+
+UserSettingsForm
+
+RevenueChart
+```
+
+Avoid
+
+```
+Card2
+
+Widget
+
+Thing
+
+Data
+
+Panel
+```
+
+---
+
+# AI Development Rules
+
+Before writing code:
+
+1. Reuse existing components.
+2. Reuse existing layouts.
+3. Reuse existing utilities.
+4. Reuse existing variants.
+5. Extend existing components before creating new ones.
+
+Never duplicate code.
+
+Never duplicate styling.
+
+Keep APIs simple.
+
+Keep components focused.
+
+---
+
+# Definition of Done
+
+A feature is complete only when:
+
+✓ Uses VUI components where appropriate.
+
+✓ Uses semantic design tokens.
+
+✓ Supports light and dark mode.
+
+✓ Supports responsive layouts.
+
+✓ Supports accessibility.
+
+✓ Includes loading, empty, success, and error states.
+
+✓ Keeps business logic outside UI components.
+
+✓ Introduces no duplicated code.
+
+✓ Introduces no duplicated styling.
+
+✓ Passes lint and type checking.
+
+✓ Is production ready.

package/README.md

@@ -57,6 +57,14 @@ export function Example() {
 }
 ```
 
+## Building with an AI agent
+
+This package ships an **AI-agent usage guide** at
+`node_modules/@viliha/vui-ui/AGENT.md` — the standards to follow when generating
+UI with VUI (token discipline, reuse-first, page layout, RecordView, a11y, dark
+mode). Point your agent at it, or copy it into your repo as `AGENTS.md` so tools
+auto-load it.
+
 ## Components
 
 `avatar` · `badge` · `button` · `card` · `chart` (themed Recharts wrapper) ·

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viliha/vui-ui",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "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",
@@ -32,7 +32,8 @@
   "files": [
     "src",
     "!src/**/*.test.ts",
-    "!src/**/*.test.tsx"
+    "!src/**/*.test.tsx",
+    "AGENT.md"
   ],
   "exports": {
     "./theme.css": "./src/theme.css",

package/src/record-view.tsx

@@ -951,7 +951,10 @@ export function RecordView<T extends { id: RowId }>({
           <TableHeader className="sticky top-0 z-20 bg-background [&_th]:sticky [&_th]:top-0 [&_th]:z-20 [&_th]:bg-background">
             <TableRow className="hover:bg-transparent">
               <TableHead style={{ width: CHECKBOX_W }} className="p-0">
-                <div className="flex h-8 items-center pl-8">
+                <div className="flex h-8 items-center gap-2 pl-2 pr-3">
+                  {/* Spacer matching the row drag-grip slot so this checkbox
+                      lines up vertically with the row checkboxes below. */}
+                  <span aria-hidden="true" className="h-6 w-4 shrink-0" />
                   <Checkbox
                     checked={allSelected}
                     onChange={toggleSelectAll}
@@ -1002,16 +1005,18 @@ export function RecordView<T extends { id: RowId }>({
                   </TableHead>
                 );
               })}
+              {/* Flex spacer absorbs leftover width so data columns keep their
+                  natural size AND the Actions column stays pinned to the right
+                  edge. Borderless so no stray divider shows in the gap. */}
+              <TableHead aria-hidden="true" className="w-full border-r-0" />
               <TableHead
                 style={{ width: ACTIONS_W }}
-                className="border-r-0 text-right"
+                className="sticky right-0 z-30 border-l border-border text-right shadow-[-8px_0_12px_-8px_rgb(0_0_0/0.12)]"
               >
-                <span className="flex h-8 items-center justify-end whitespace-nowrap pr-2">
+                <span className="flex h-8 items-center justify-center whitespace-nowrap px-2">
                   Actions
                 </span>
               </TableHead>
-              {/* Filler so row borders reach the right edge of the page. */}
-              <TableHead aria-hidden="true" />
             </TableRow>
           </TableHeader>
           <TableBody>
@@ -1043,12 +1048,12 @@ export function RecordView<T extends { id: RowId }>({
                     }}
                     className="group data-[active=true]:bg-accent/60 data-[dragover=true]:border-t-2 data-[dragover=true]:border-t-primary data-[flash=true]:bg-primary/10"
                   >
-                    <TableCell className="p-0">
-                      <div className="relative flex h-8 items-center pl-8">
+                    <TableCell className="p-0" style={{ width: CHECKBOX_W }}>
+                      <div className="flex h-8 items-center gap-2 pl-2 pr-3">
                         {/* Drag grip — always visible in a light color (so the
                             reorder affordance is discoverable), darkening on
-                            hover. Sits in its own reserved slot in the left
-                            gutter so it never overlaps the checkbox. */}
+                            hover. Inline before the checkbox; plain glyph (no
+                            icon-chip border) so it doesn't read as a box. */}
                         <div
                           draggable
                           onDragStart={(e) => {
@@ -1062,9 +1067,9 @@ export function RecordView<T extends { id: RowId }>({
                           }}
                           aria-label={`Drag ${primary.title || singular} to reorder`}
                           title="Drag to reorder"
-                          className="absolute left-1.5 top-1/2 flex h-6 w-4 -translate-y-1/2 cursor-grab items-center justify-center text-muted-foreground/40 transition-colors hover:text-foreground active:cursor-grabbing"
+                          className="flex h-6 w-4 shrink-0 cursor-grab items-center justify-center text-muted-foreground/40 transition-colors hover:text-foreground active:cursor-grabbing"
                         >
-                          <GripVertical className="size-3.5" />
+                          <GripVertical className="size-3.5 border-transparent bg-transparent" />
                         </div>
                         <Checkbox
                           checked={selected.has(row.id)}
@@ -1099,11 +1104,12 @@ export function RecordView<T extends { id: RowId }>({
                         {renderCellValue(row, f)}
                       </TableCell>
                     ))}
+                    <TableCell aria-hidden="true" className="w-full border-r-0" />
                     <TableCell
-                      className="border-r-0 p-0"
+                      className="sticky right-0 z-10 border-l border-border bg-card p-0 shadow-[-8px_0_12px_-8px_rgb(0_0_0/0.12)]"
                       style={{ width: ACTIONS_W }}
                     >
-                      <div className="flex items-center justify-end gap-0.5 pr-2">
+                      <div className="flex items-center justify-center gap-0.5 px-2">
                         <button
                           type="button"
                           onClick={() => openView(row.id)}
@@ -1133,7 +1139,6 @@ export function RecordView<T extends { id: RowId }>({
                         </button>
                       </div>
                     </TableCell>
-                    <TableCell aria-hidden="true" />
                   </TableRow>
                 );
               })