@viliha/vui-ui 1.5.0 → 1.5.1

package/AGENT.md

@@ -14,11 +14,7 @@
 > [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.
+You are a frontend architect building enterprise applications on **VUI Starter**. Your job is to ship apps that are consistent, maintainable, accessible, and production-ready by leaning fully on the VUI Design System. Don't 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`,
@@ -36,7 +32,7 @@ Do not reinvent the framework. Build with it.
 
 # Core Principles
 
-Always prioritize:
+Order your decisions by these priorities:
 
 1. Reuse over rebuilding.
 2. Consistency over customization.
@@ -47,21 +43,13 @@ Always prioritize:
 7. Predictable user experiences.
 8. Enterprise-grade maintainability.
 
-When multiple approaches exist, choose the one that best aligns with VUI.
+When several approaches would work, pick the one that aligns best 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.
+Before you create anything, search for what already exists — a VUI component, a page pattern, a layout, a variant, or a utility. Never duplicate functionality VUI already provides.
 
 ---
 
@@ -95,20 +83,20 @@ dependencies** with the package manager it detects from the lockfile (npm / pnpm
   alias, `import "./globals.css"`).
 - **existing + theme-only** → nothing copied; prints the wiring steps.
 
-Other flags: `--yes` / `--force` / `--dry-run`. If you only need components, use
-`--theme-only` (or skip `init`) and do the setup below.
+Other flags: `--yes` / `--force` / `--dry-run`. If you only need the components, pass
+`--theme-only` (or skip `init` entirely) and follow the setup below.
 
 VUI ships as TypeScript source.
 
 ## Next.js
 
-Always configure:
+Transpile the package:
 
 ```ts
 transpilePackages: ["@viliha/vui-ui"]
 ```
 
-Import once:
+Import the theme once:
 
 ```css
 @import "tailwindcss";
@@ -117,47 +105,21 @@ Import once:
 
 ## Vite
 
-Import the theme once.
-
-No additional transpilation is required.
+Import the theme once. No extra transpilation needed.
 
 ---
 
 # Design Tokens
 
-VUI is completely token-driven.
-
-Never hardcode:
-
-- colors
-- spacing
-- radius
-- typography
-- shadows
-- borders
+VUI is entirely token-driven. Never hardcode colors, spacing, radius, typography, shadows, or borders — reach for the semantic design token instead. For example: `--button-primary`, `--button-primary-hover`, `--background`, `--foreground`, `--border`, `--ring`, `--chart-1`, `--sidebar-primary`.
 
-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.
+Avoid arbitrary values unless there's truly no token for the job.
 
 ---
 
 # Application Structure
 
-Organize applications using feature-first architecture.
-
-Example:
+Organize the app around a feature-first architecture:
 
 ```
 app/
@@ -175,13 +137,13 @@ services/
 types/
 ```
 
-Keep business logic outside UI components.
+Keep business logic out of UI components.
 
 ---
 
 # Page Layout
 
-Every application page should follow the standard VUI layout.
+Every page follows the standard VUI layout:
 
 ```
 SetPageTitle
@@ -195,31 +157,19 @@ Action Header
 Scrollable Content
 ```
 
-Only the content area should scroll.
-
-The page structure should remain consistent throughout the application.
+Only the content area scrolls, and this structure stays consistent across the whole app.
 
 ---
 
 # Sections
 
-Use bordered cards.
-
-Avoid deeply nested layouts.
-
-Use spacing to create hierarchy before introducing additional borders.
+Group content into bordered cards, and avoid deeply nested layouts. Reach for spacing to establish hierarchy before you add more borders.
 
 ---
 
 # Navigation
 
-Always use:
-
-- Breadcrumbs
-- Sidebar
-- Top Navigation
-
-Do not build custom navigation systems unless the project explicitly requires it.
+Navigate with the three provided pieces — breadcrumbs, sidebar, and top navigation. Don't build a custom navigation system unless the project explicitly demands one.
 
 ## Breadcrumbs
 
@@ -306,48 +256,13 @@ persistence, and nav-config wiring stay identical.
 
 # 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.
+Build forms with VUI and shadcn/ui together, reaching for shadcn Form, React Hook Form, and Zod. Every form handles the full lifecycle — validation, loading, success, error, disabled, and keyboard navigation. Never use a placeholder in place of a label.
 
 ---
 
 # 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
+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.
 
 ## Add / edit form
 
@@ -367,17 +282,7 @@ shared `@viliha/vui-ui/breadcrumbs` component.
 
 # Charts
 
-Always build charts with:
-
-ChartContainer
-
-+
-
-Recharts
-
-Never hardcode chart colors.
-
-Always map colors through chart tokens.
+Build every chart with `ChartContainer` plus Recharts. Never hardcode chart colors — map them through the chart tokens.
 
 ---
 
@@ -391,101 +296,45 @@ 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.
+Wrap the forms in semantic HTML.
 
 ---
 
 # shadcn/ui Integration
 
-VUI complements shadcn/ui.
-
-Use shadcn for:
-
-- forms
-- dialogs
-- sheets
-- tabs
-- popovers
-- accordions
-
-Use VUI for:
+VUI and shadcn/ui complement each other, so split the work along their strengths. Reach for shadcn for forms, dialogs, sheets, tabs, popovers, and accordions; reach for VUI for layouts, `RecordView`, enterprise components, charts, and navigation patterns.
 
-- layouts
-- RecordView
-- enterprise components
-- charts
-- navigation patterns
-
-VUI owns the design tokens.
-
-Remove duplicated token definitions generated by shadcn.
+VUI owns the design tokens — delete any duplicate token definitions shadcn generates.
 
 ---
 
 # Accessibility
 
-Every page should support:
-
-- keyboard navigation
-- visible focus
-- ARIA attributes
-- screen readers
-- WCAG AA contrast
-
-Accessibility is never optional.
+Every page supports keyboard navigation, visible focus, ARIA attributes, screen readers, and WCAG AA contrast. Accessibility is never optional.
 
 ---
 
 # Responsive Design
 
-Design mobile first.
-
-Support:
-
-- Mobile
-- Tablet
-- Desktop
-- Large Desktop
-
-Avoid horizontal scrolling whenever possible.
+Design mobile first, then scale up cleanly through tablet, desktop, and large desktop. Avoid horizontal scrolling wherever you can.
 
 ---
 
 # Performance
 
-Prefer:
-
-- Server Components
-- Streaming
-- Lazy loading
-- Dynamic imports
-
-Avoid unnecessary client components.
-
-Memoize only when needed.
+Default to Server Components, streaming, lazy loading, and dynamic imports. Avoid unnecessary client components, and memoize only when you've measured a need.
 
 ---
 
 # 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.
+Every feature communicates its current state — loading, success, empty, and error. Give long-running actions visible progress, and never leave users wondering what happened.
 
 ---
 
 # Naming
 
-Prefer descriptive names.
+Name things descriptively.
 
 Good
 
@@ -517,21 +366,7 @@ 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.
+Before you write code, reuse what's already there — components, layouts, utilities, and variants — and extend an existing component before creating a new one. Never duplicate code or styling. Keep APIs simple and components focused.
 
 ---
 

package/README.md

@@ -1,11 +1,12 @@
 # @viliha/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) — your app's bundler compiles only what you import.
+A **token-driven React component library** for admin and CRM interfaces, built on
+Tailwind CSS v4, shadcn-style patterns, and Radix Icons. It ships as **TypeScript
+source** rather than a prebuilt bundle, so your app's bundler compiles only the
+components you actually import.
 
-Part of [**Vui Starter**](https://github.com/myviliha/vui-starter) — a free,
-open-source admin design system.
+It's part of [**Vui Starter**](https://github.com/myviliha/vui-starter), a free
+and open-source admin design system.
 
 - 🌐 **Live docs & demo:** [vui.viliha.com](https://vui.viliha.com)
 - 📦 **Repository:** [github.com/myviliha/vui-starter](https://github.com/myviliha/vui-starter)
@@ -21,15 +22,15 @@ npm install -D tailwindcss @tailwindcss/postcss
 
 ## Setup
 
-**1. Import the theme** in your global stylesheet (design tokens, `@theme`
-mapping, base reset, and component scanning — all in one import):
+**1. Import the theme** in your global stylesheet. This one import brings in the
+design tokens, the `@theme` mapping, the base reset, and component scanning:
 
 ```css
 @import "tailwindcss";
 @import "@viliha/vui-ui/theme.css";
 ```
 
-**2. Next.js only** — transpile the source package in `next.config.ts`:
+**2. Next.js only.** Transpile the source package in `next.config.ts`:
 
 ```ts
 const nextConfig = { transpilePackages: ["@viliha/vui-ui"] };
@@ -40,29 +41,30 @@ export default nextConfig;
 
 ## Scaffold the full app + demo (`init`)
 
-The package ships the **components**; the **app shell** (layout, sidebar,
+The package itself ships the **components**. The **app shell** (layout, sidebar,
 browser-style **open tabs**, command palette, nav config, logo) and the **demo
-pages** live in a one-shot scaffolder:
+pages** come from a one-shot scaffolder:
 
 ```bash
 npx @viliha/vui-ui init
 ```
 
-It's **interactive** — a short decision tree:
+It's **interactive** and walks through a short decision tree:
 
-1. **Fresh project?** (fresh vs existing)
-2. **Pre-built theme?** — the full shell + demo pages, or just the theme wiring
-   that you configure yourself.
+1. **Fresh project?** (fresh vs. existing)
+2. **Pre-built theme?** — the full shell plus demo pages, or just the theme wiring
+   for you to build on.
 
-Files are copied into *your* repo, so you own and edit them.
+Everything it generates is copied into *your* repo, so you own and edit it.
 
 | | **Pre-built** (shell + demo) | **Theme-only** (you configure) |
 | --- | --- | --- |
 | **Fresh** | full runnable app: config + shell + demo pages | just the theme wiring (`globals.css`, `next.config`) — build your own pages |
 | **Existing** | shell + demo added; your config is **never** overwritten (prints merge steps) | nothing copied; prints the wiring steps |
 
-It first asks whether this is a standalone **Next.js** app or a **Turborepo**
-(for a monorepo it scaffolds into a target app dir, e.g. `apps/web`).
+Before that, it asks whether this is a standalone **Next.js** app or a
+**Turborepo**; for a monorepo it scaffolds into a target app dir, such as
+`apps/web`.
 
 ```
 Flags (for CI / agents, skip the prompts):
@@ -75,15 +77,15 @@ Flags (for CI / agents, skip the prompts):
   --dry-run                   preview without writing
 ```
 
-`init` **auto-installs the dependencies** with your package manager (detected
-from the lockfile — npm, pnpm, yarn, or bun). It prompts first; pass `--yes` to
-skip, or `--no-install` to do it yourself.
+`init` **installs the dependencies for you** using the package manager it detects
+from your lockfile (npm, pnpm, yarn, or bun). It prompts before doing so; pass
+`--yes` to skip the prompt, or `--no-install` to handle it yourself.
 
 ### Fresh + pre-built (recommended for new apps)
 
-Start from a `create-next-app` base **without `--src-dir`** (the scaffold uses a
-root `app/` + `@/*` → `./*`), then run `init` — it scaffolds, installs deps, and
-you're ready for `dev`. Use whichever package manager you like:
+Start from a `create-next-app` base **without `--src-dir`** — the scaffold expects
+a root `app/` with `@/*` → `./*` — then run `init`. It scaffolds the app, installs
+the dependencies, and leaves you ready to run `dev`. Any package manager works:
 
 ```bash
 # npm
@@ -103,16 +105,16 @@ bun create next-app my-app --ts --tailwind --app --no-src-dir
 cd my-app && bunx @viliha/vui-ui init && bun dev
 ```
 
-`init` writes `next.config.ts`, `tsconfig.json`, `app/globals.css`, the shell,
-and the demo pages (overwriting the create-next-app boilerplate) and installs the
-deps, so the demo runs out of the box at `/dashboard`.
+`init` writes `next.config.ts`, `tsconfig.json`, `app/globals.css`, the shell, and
+the demo pages, overwriting the create-next-app boilerplate, and installs the
+dependencies. The demo then runs out of the box at `/dashboard`.
 
 ### ⚠️ Existing project — read this first
 
-Adding VUI to an app you already have needs care. **`init --existing` never
-overwrites your config.** Pick pre-built to add the shell + pages under
-`app/(app)/` and `app/_components/`, or theme-only to copy nothing — either way it
-prints the four things to wire up:
+Adding VUI to an app you already have takes a little care. **`init --existing`
+never overwrites your config.** Choose pre-built to add the shell and pages under
+`app/(app)/` and `app/_components/`, or theme-only to copy nothing. Either way, it
+prints the four things you need to wire up:
 
 1. **`next.config`** — add `transpilePackages: ["@viliha/vui-ui"]`.
    (Optional, for the open-tabs *keep-alive*: `output: "export"`,
@@ -127,19 +129,19 @@ prints the four things to wire up:
 4. **Root `app/layout.tsx`** — `import "./globals.css"` (and mount fonts to match
    the demo's look).
 
-Run **`npx @viliha/vui-ui init --existing --prebuilt --dry-run`** first to see
+Run **`npx @viliha/vui-ui init --existing --prebuilt --dry-run`** first to preview
 exactly what it will add. If you only want the components, choose **theme-only**
-(or skip `init` and follow the [Setup](#setup) above), then import from
+(or skip `init` entirely and follow the [Setup](#setup) above), then import from
 `@viliha/vui-ui/*`.
 
-> **Note on the theme in an existing app:** VUI owns its design tokens in
-> `theme.css`. If your app already defines shadcn/ui or other CSS variables with
-> the same names, import `theme.css` **last** and remove the duplicates, or the
-> two token sets will fight. On a fresh project this never comes up.
+> **A note on theming an existing app:** VUI owns its design tokens in
+> `theme.css`. If your app already defines shadcn/ui or other CSS variables under
+> the same names, import `theme.css` **last** and remove the duplicates so the two
+> token sets don't collide. On a fresh project this never comes up.
 
 ## Usage
 
-Each component is its own entry point, so you only ship what you use:
+Every component has its own entry point, so you ship only what you use:
 
 ```tsx
 import { Button } from "@viliha/vui-ui/button";
@@ -158,11 +160,11 @@ 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.
+`RecordView` builds a complete admin datatable from a single `fields` array:
+editable cells, sorting, filtering, pagination, row and bulk actions,
+CSV / JSON / Excel / PDF import and export, and a buffered **Add / Edit / View**
+form (slide-over or full-page). Required fields render a `*`, and alignment and
+colors come from the tokens, so you never style a field by hand.
 
 ```tsx
 import { RecordView, type RecordField } from "@viliha/vui-ui/record-view";
@@ -183,9 +185,9 @@ const fields: RecordField<Customer>[] = [
 />;
 ```
 
-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).
+That same `fields` array also drives `RecordForm`, the Add/Edit/View screen, along
+with its Info panel (built from `formDescription` and each field's `description`).
+See the [Data table docs](https://vui.viliha.com/docs/data-table) for the details.
 
 ## Patterns
 
@@ -205,14 +207,14 @@ The reference app composes these primitives into the conventions documented at
 
 Copy them from the
 [backoffice demo](https://github.com/myviliha/vui-starter/tree/main/apps/backoffice)
-and adapt.
+and adapt them to your app.
 
 ## 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, forms,
-a11y, dark mode). The quickest way to load it is the shipped
+`node_modules/@viliha/vui-ui/AGENT.md`. It captures the standards to follow when
+generating UI with VUI: token discipline, reuse-first, page layout, RecordView,
+forms, accessibility, and dark mode. The quickest way to load it is the shipped
 `CLAUDE.template.md`:
 
 ```bash
@@ -220,8 +222,9 @@ cp node_modules/@viliha/vui-ui/CLAUDE.template.md ./CLAUDE.md   # Claude Code
 # or ./AGENTS.md for Cursor / Copilot
 ```
 
-It's a one-line `@import` of `AGENT.md`, so the rules stay in one place. Prefer a
-verbatim copy? `cp node_modules/@viliha/vui-ui/AGENT.md AGENTS.md`.
+That file is a one-line `@import` of `AGENT.md`, so the rules stay in a single
+place. If you'd rather keep a verbatim copy, run
+`cp node_modules/@viliha/vui-ui/AGENT.md AGENTS.md`.
 
 ## Components
 
@@ -234,9 +237,9 @@ wrapper) · `checkbox` · `command-palette` (⌘K launcher) · `dialog` ·
 
 ## Theming
 
-Every design decision lives in `@viliha/vui-ui/theme.css` as CSS variables
-(colors, radius, typography, dark mode). Override any token **after** the import
-to rebrand the whole system:
+Every design decision lives in `@viliha/vui-ui/theme.css` as CSS variables —
+colors, radius, typography, and dark mode. Override any token **after** the import
+to rebrand the entire system:
 
 ```css
 @import "@viliha/vui-ui/theme.css";

package/package.json

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