@viliha/vui-ui 1.5.0 → 1.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENT.md +70 -194
- package/README.md +77 -54
- package/bin/vui.mjs +11 -5
- package/package.json +1 -1
package/AGENT.md
CHANGED
|
@@ -14,11 +14,7 @@
|
|
|
14
14
|
> [CONTRIBUTING.md](https://github.com/myviliha/vui-starter/blob/main/CONTRIBUTING.md)
|
|
15
15
|
> and [AGENTS.md](https://github.com/myviliha/vui-starter/blob/main/AGENTS.md).
|
|
16
16
|
|
|
17
|
-
You are
|
|
18
|
-
|
|
19
|
-
Your responsibility is to build applications that are consistent, maintainable, accessible, and production-ready by fully embracing the VUI Design System.
|
|
20
|
-
|
|
21
|
-
Do not reinvent the framework. Build with it.
|
|
17
|
+
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.
|
|
22
18
|
|
|
23
19
|
> **What you get from the package vs. what to copy.** `@viliha/vui-ui` ships the
|
|
24
20
|
> component primitives (`Button`, `Input`, `Select`, `Dialog`, `Menu`,
|
|
@@ -36,7 +32,7 @@ Do not reinvent the framework. Build with it.
|
|
|
36
32
|
|
|
37
33
|
# Core Principles
|
|
38
34
|
|
|
39
|
-
|
|
35
|
+
Order your decisions by these priorities:
|
|
40
36
|
|
|
41
37
|
1. Reuse over rebuilding.
|
|
42
38
|
2. Consistency over customization.
|
|
@@ -47,21 +43,13 @@ Always prioritize:
|
|
|
47
43
|
7. Predictable user experiences.
|
|
48
44
|
8. Enterprise-grade maintainability.
|
|
49
45
|
|
|
50
|
-
When
|
|
46
|
+
When several approaches would work, pick the one that aligns best with VUI.
|
|
51
47
|
|
|
52
48
|
---
|
|
53
49
|
|
|
54
50
|
# Think Before You Build
|
|
55
51
|
|
|
56
|
-
Before
|
|
57
|
-
|
|
58
|
-
1. Search for an existing VUI component.
|
|
59
|
-
2. Search for an existing page pattern.
|
|
60
|
-
3. Search for an existing layout.
|
|
61
|
-
4. Search for an existing variant.
|
|
62
|
-
5. Search for an existing utility.
|
|
63
|
-
|
|
64
|
-
Never duplicate functionality already provided by VUI.
|
|
52
|
+
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.
|
|
65
53
|
|
|
66
54
|
---
|
|
67
55
|
|
|
@@ -95,20 +83,61 @@ dependencies** with the package manager it detects from the lockfile (npm / pnpm
|
|
|
95
83
|
alias, `import "./globals.css"`).
|
|
96
84
|
- **existing + theme-only** → nothing copied; prints the wiring steps.
|
|
97
85
|
|
|
98
|
-
Other flags: `--yes` / `--force` / `--dry-run`. If you only need components,
|
|
99
|
-
`--theme-only` (or skip `init`) and
|
|
86
|
+
Other flags: `--yes` / `--force` / `--dry-run`. If you only need the components, pass
|
|
87
|
+
`--theme-only` (or skip `init` entirely) and follow the setup below.
|
|
88
|
+
|
|
89
|
+
### Inside a Turborepo / monorepo
|
|
90
|
+
|
|
91
|
+
**Never scaffold into the repo root** — a monorepo root has no `app/` and no Next
|
|
92
|
+
app. Target the specific application, e.g. `apps/web`. Two equivalent ways:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
# A) from the repo root, name the app dir
|
|
96
|
+
npx @viliha/vui-ui init --turbo --dir apps/web
|
|
97
|
+
|
|
98
|
+
# B) from inside the app (simplest to reason about)
|
|
99
|
+
cd apps/web
|
|
100
|
+
npx @viliha/vui-ui init
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
In turbo mode the CLI **does not auto-install** (installs are workspace-specific),
|
|
104
|
+
so finish the setup yourself, scoped to that app:
|
|
105
|
+
|
|
106
|
+
```bash
|
|
107
|
+
cd apps/web # be inside the app, not the root
|
|
108
|
+
pnpm add @viliha/vui-ui … # or: pnpm --filter <app-name> add @viliha/vui-ui …
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Then confirm the app is in your workspace globs (`pnpm-workspace.yaml` /
|
|
112
|
+
`package.json` `workspaces`) and run it with a filter: `pnpm --filter <app-name>
|
|
113
|
+
dev`. The theme import, `transpilePackages`, and the `@/*` alias all belong in
|
|
114
|
+
**that app's** `globals.css` / `next.config` / `tsconfig`, not the root.
|
|
115
|
+
|
|
116
|
+
### End-to-end walkthroughs
|
|
117
|
+
|
|
118
|
+
- **New standalone app** — `npx create-next-app@latest my-app --ts --tailwind
|
|
119
|
+
--app --no-src-dir --use-npm`, then `cd my-app && npx @viliha/vui-ui init`
|
|
120
|
+
(fresh + prebuilt). It scaffolds config + shell + demo, installs deps, and you
|
|
121
|
+
run `npm run dev` → `/dashboard`.
|
|
122
|
+
- **New app in a monorepo** — scaffold your app under `apps/<name>` (e.g. with
|
|
123
|
+
`create-next-app`), then from that app dir run `npx @viliha/vui-ui init` (or
|
|
124
|
+
`--turbo --dir apps/<name>` from the root) and install deps in that app.
|
|
125
|
+
- **Existing app** — run `npx @viliha/vui-ui init --existing`. It never
|
|
126
|
+
overwrites your config; wire up the four things it prints (`transpilePackages`,
|
|
127
|
+
the `theme.css` import, the `@/*` alias, `import "./globals.css"`). Prefer only
|
|
128
|
+
the components? Use `--theme-only` (copies nothing) and follow the setup below.
|
|
100
129
|
|
|
101
130
|
VUI ships as TypeScript source.
|
|
102
131
|
|
|
103
132
|
## Next.js
|
|
104
133
|
|
|
105
|
-
|
|
134
|
+
Transpile the package:
|
|
106
135
|
|
|
107
136
|
```ts
|
|
108
137
|
transpilePackages: ["@viliha/vui-ui"]
|
|
109
138
|
```
|
|
110
139
|
|
|
111
|
-
Import once:
|
|
140
|
+
Import the theme once:
|
|
112
141
|
|
|
113
142
|
```css
|
|
114
143
|
@import "tailwindcss";
|
|
@@ -117,47 +146,21 @@ Import once:
|
|
|
117
146
|
|
|
118
147
|
## Vite
|
|
119
148
|
|
|
120
|
-
Import the theme once.
|
|
121
|
-
|
|
122
|
-
No additional transpilation is required.
|
|
149
|
+
Import the theme once. No extra transpilation needed.
|
|
123
150
|
|
|
124
151
|
---
|
|
125
152
|
|
|
126
153
|
# Design Tokens
|
|
127
154
|
|
|
128
|
-
VUI is
|
|
155
|
+
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`.
|
|
129
156
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
- colors
|
|
133
|
-
- spacing
|
|
134
|
-
- radius
|
|
135
|
-
- typography
|
|
136
|
-
- shadows
|
|
137
|
-
- borders
|
|
138
|
-
|
|
139
|
-
Always use semantic design tokens.
|
|
140
|
-
|
|
141
|
-
Examples:
|
|
142
|
-
|
|
143
|
-
- --button-primary
|
|
144
|
-
- --button-primary-hover
|
|
145
|
-
- --background
|
|
146
|
-
- --foreground
|
|
147
|
-
- --border
|
|
148
|
-
- --ring
|
|
149
|
-
- --chart-1
|
|
150
|
-
- --sidebar-primary
|
|
151
|
-
|
|
152
|
-
Never use arbitrary values unless absolutely necessary.
|
|
157
|
+
Avoid arbitrary values unless there's truly no token for the job.
|
|
153
158
|
|
|
154
159
|
---
|
|
155
160
|
|
|
156
161
|
# Application Structure
|
|
157
162
|
|
|
158
|
-
Organize
|
|
159
|
-
|
|
160
|
-
Example:
|
|
163
|
+
Organize the app around a feature-first architecture:
|
|
161
164
|
|
|
162
165
|
```
|
|
163
166
|
app/
|
|
@@ -175,13 +178,13 @@ services/
|
|
|
175
178
|
types/
|
|
176
179
|
```
|
|
177
180
|
|
|
178
|
-
Keep business logic
|
|
181
|
+
Keep business logic out of UI components.
|
|
179
182
|
|
|
180
183
|
---
|
|
181
184
|
|
|
182
185
|
# Page Layout
|
|
183
186
|
|
|
184
|
-
Every
|
|
187
|
+
Every page follows the standard VUI layout:
|
|
185
188
|
|
|
186
189
|
```
|
|
187
190
|
SetPageTitle
|
|
@@ -195,31 +198,19 @@ Action Header
|
|
|
195
198
|
Scrollable Content
|
|
196
199
|
```
|
|
197
200
|
|
|
198
|
-
Only the content area
|
|
199
|
-
|
|
200
|
-
The page structure should remain consistent throughout the application.
|
|
201
|
+
Only the content area scrolls, and this structure stays consistent across the whole app.
|
|
201
202
|
|
|
202
203
|
---
|
|
203
204
|
|
|
204
205
|
# Sections
|
|
205
206
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
Avoid deeply nested layouts.
|
|
209
|
-
|
|
210
|
-
Use spacing to create hierarchy before introducing additional borders.
|
|
207
|
+
Group content into bordered cards, and avoid deeply nested layouts. Reach for spacing to establish hierarchy before you add more borders.
|
|
211
208
|
|
|
212
209
|
---
|
|
213
210
|
|
|
214
211
|
# Navigation
|
|
215
212
|
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
- Breadcrumbs
|
|
219
|
-
- Sidebar
|
|
220
|
-
- Top Navigation
|
|
221
|
-
|
|
222
|
-
Do not build custom navigation systems unless the project explicitly requires it.
|
|
213
|
+
Navigate with the three provided pieces — breadcrumbs, sidebar, and top navigation. Don't build a custom navigation system unless the project explicitly demands one.
|
|
223
214
|
|
|
224
215
|
## Breadcrumbs
|
|
225
216
|
|
|
@@ -306,48 +297,13 @@ persistence, and nav-config wiring stay identical.
|
|
|
306
297
|
|
|
307
298
|
# Forms
|
|
308
299
|
|
|
309
|
-
|
|
310
|
-
|
|
311
|
-
Prefer:
|
|
312
|
-
|
|
313
|
-
- shadcn Form
|
|
314
|
-
- React Hook Form
|
|
315
|
-
- Zod
|
|
316
|
-
|
|
317
|
-
Every form should support:
|
|
318
|
-
|
|
319
|
-
- validation
|
|
320
|
-
- loading
|
|
321
|
-
- success
|
|
322
|
-
- error
|
|
323
|
-
- disabled
|
|
324
|
-
- keyboard navigation
|
|
325
|
-
|
|
326
|
-
Never rely on placeholders as labels.
|
|
300
|
+
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.
|
|
327
301
|
|
|
328
302
|
---
|
|
329
303
|
|
|
330
304
|
# Tables
|
|
331
305
|
|
|
332
|
-
Never build HTML
|
|
333
|
-
|
|
334
|
-
Always use RecordView.
|
|
335
|
-
|
|
336
|
-
Use:
|
|
337
|
-
|
|
338
|
-
- editable
|
|
339
|
-
- required
|
|
340
|
-
- copyable
|
|
341
|
-
- options
|
|
342
|
-
- render
|
|
343
|
-
|
|
344
|
-
Allow RecordView to manage:
|
|
345
|
-
|
|
346
|
-
- sorting
|
|
347
|
-
- filtering
|
|
348
|
-
- pagination
|
|
349
|
-
- bulk actions
|
|
350
|
-
- import/export
|
|
306
|
+
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.
|
|
351
307
|
|
|
352
308
|
## Add / edit form
|
|
353
309
|
|
|
@@ -367,17 +323,7 @@ shared `@viliha/vui-ui/breadcrumbs` component.
|
|
|
367
323
|
|
|
368
324
|
# Charts
|
|
369
325
|
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
ChartContainer
|
|
373
|
-
|
|
374
|
-
+
|
|
375
|
-
|
|
376
|
-
Recharts
|
|
377
|
-
|
|
378
|
-
Never hardcode chart colors.
|
|
379
|
-
|
|
380
|
-
Always map colors through chart tokens.
|
|
326
|
+
Build every chart with `ChartContainer` plus Recharts. Never hardcode chart colors — map them through the chart tokens.
|
|
381
327
|
|
|
382
328
|
---
|
|
383
329
|
|
|
@@ -391,101 +337,45 @@ app (they are built from published primitives: `Button`, `Input`, tokens).
|
|
|
391
337
|
|
|
392
338
|
Do not `import … from "@viliha/vui-ui/auth"` — no such entry point exists.
|
|
393
339
|
|
|
394
|
-
Wrap forms
|
|
340
|
+
Wrap the forms in semantic HTML.
|
|
395
341
|
|
|
396
342
|
---
|
|
397
343
|
|
|
398
344
|
# shadcn/ui Integration
|
|
399
345
|
|
|
400
|
-
VUI
|
|
401
|
-
|
|
402
|
-
Use shadcn for:
|
|
403
|
-
|
|
404
|
-
- forms
|
|
405
|
-
- dialogs
|
|
406
|
-
- sheets
|
|
407
|
-
- tabs
|
|
408
|
-
- popovers
|
|
409
|
-
- accordions
|
|
346
|
+
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.
|
|
410
347
|
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
- layouts
|
|
414
|
-
- RecordView
|
|
415
|
-
- enterprise components
|
|
416
|
-
- charts
|
|
417
|
-
- navigation patterns
|
|
418
|
-
|
|
419
|
-
VUI owns the design tokens.
|
|
420
|
-
|
|
421
|
-
Remove duplicated token definitions generated by shadcn.
|
|
348
|
+
VUI owns the design tokens — delete any duplicate token definitions shadcn generates.
|
|
422
349
|
|
|
423
350
|
---
|
|
424
351
|
|
|
425
352
|
# Accessibility
|
|
426
353
|
|
|
427
|
-
Every page
|
|
428
|
-
|
|
429
|
-
- keyboard navigation
|
|
430
|
-
- visible focus
|
|
431
|
-
- ARIA attributes
|
|
432
|
-
- screen readers
|
|
433
|
-
- WCAG AA contrast
|
|
434
|
-
|
|
435
|
-
Accessibility is never optional.
|
|
354
|
+
Every page supports keyboard navigation, visible focus, ARIA attributes, screen readers, and WCAG AA contrast. Accessibility is never optional.
|
|
436
355
|
|
|
437
356
|
---
|
|
438
357
|
|
|
439
358
|
# Responsive Design
|
|
440
359
|
|
|
441
|
-
Design mobile first.
|
|
442
|
-
|
|
443
|
-
Support:
|
|
444
|
-
|
|
445
|
-
- Mobile
|
|
446
|
-
- Tablet
|
|
447
|
-
- Desktop
|
|
448
|
-
- Large Desktop
|
|
449
|
-
|
|
450
|
-
Avoid horizontal scrolling whenever possible.
|
|
360
|
+
Design mobile first, then scale up cleanly through tablet, desktop, and large desktop. Avoid horizontal scrolling wherever you can.
|
|
451
361
|
|
|
452
362
|
---
|
|
453
363
|
|
|
454
364
|
# Performance
|
|
455
365
|
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
- Server Components
|
|
459
|
-
- Streaming
|
|
460
|
-
- Lazy loading
|
|
461
|
-
- Dynamic imports
|
|
462
|
-
|
|
463
|
-
Avoid unnecessary client components.
|
|
464
|
-
|
|
465
|
-
Memoize only when needed.
|
|
366
|
+
Default to Server Components, streaming, lazy loading, and dynamic imports. Avoid unnecessary client components, and memoize only when you've measured a need.
|
|
466
367
|
|
|
467
368
|
---
|
|
468
369
|
|
|
469
370
|
# UX Standards
|
|
470
371
|
|
|
471
|
-
Every feature
|
|
472
|
-
|
|
473
|
-
Support:
|
|
474
|
-
|
|
475
|
-
- Loading
|
|
476
|
-
- Success
|
|
477
|
-
- Empty
|
|
478
|
-
- Error
|
|
479
|
-
|
|
480
|
-
Long-running actions should provide visible progress.
|
|
481
|
-
|
|
482
|
-
Never leave users wondering what happened.
|
|
372
|
+
Every feature communicates its current state — loading, success, empty, and error. Give long-running actions visible progress, and never leave users wondering what happened.
|
|
483
373
|
|
|
484
374
|
---
|
|
485
375
|
|
|
486
376
|
# Naming
|
|
487
377
|
|
|
488
|
-
|
|
378
|
+
Name things descriptively.
|
|
489
379
|
|
|
490
380
|
Good
|
|
491
381
|
|
|
@@ -517,21 +407,7 @@ Panel
|
|
|
517
407
|
|
|
518
408
|
# AI Development Rules
|
|
519
409
|
|
|
520
|
-
Before
|
|
521
|
-
|
|
522
|
-
1. Reuse existing components.
|
|
523
|
-
2. Reuse existing layouts.
|
|
524
|
-
3. Reuse existing utilities.
|
|
525
|
-
4. Reuse existing variants.
|
|
526
|
-
5. Extend existing components before creating new ones.
|
|
527
|
-
|
|
528
|
-
Never duplicate code.
|
|
529
|
-
|
|
530
|
-
Never duplicate styling.
|
|
531
|
-
|
|
532
|
-
Keep APIs simple.
|
|
533
|
-
|
|
534
|
-
Keep components focused.
|
|
410
|
+
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.
|
|
535
411
|
|
|
536
412
|
---
|
|
537
413
|
|
package/README.md
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
# @viliha/vui-ui
|
|
2
2
|
|
|
3
|
-
A
|
|
4
|
-
CSS v4, shadcn-style patterns, and Radix Icons.
|
|
5
|
-
|
|
3
|
+
A **token-driven React component library** for admin and CRM interfaces, built on
|
|
4
|
+
Tailwind CSS v4, shadcn-style patterns, and Radix Icons. It ships as **TypeScript
|
|
5
|
+
source** rather than a prebuilt bundle, so your app's bundler compiles only the
|
|
6
|
+
components you actually import.
|
|
6
7
|
|
|
7
|
-
|
|
8
|
-
open-source admin design system.
|
|
8
|
+
It's part of [**Vui Starter**](https://github.com/myviliha/vui-starter), a free
|
|
9
|
+
and open-source admin design system.
|
|
9
10
|
|
|
10
11
|
- 🌐 **Live docs & demo:** [vui.viliha.com](https://vui.viliha.com)
|
|
11
12
|
- 📦 **Repository:** [github.com/myviliha/vui-starter](https://github.com/myviliha/vui-starter)
|
|
@@ -21,15 +22,15 @@ npm install -D tailwindcss @tailwindcss/postcss
|
|
|
21
22
|
|
|
22
23
|
## Setup
|
|
23
24
|
|
|
24
|
-
**1. Import the theme** in your global stylesheet
|
|
25
|
-
mapping, base reset, and component scanning
|
|
25
|
+
**1. Import the theme** in your global stylesheet. This one import brings in the
|
|
26
|
+
design tokens, the `@theme` mapping, the base reset, and component scanning:
|
|
26
27
|
|
|
27
28
|
```css
|
|
28
29
|
@import "tailwindcss";
|
|
29
30
|
@import "@viliha/vui-ui/theme.css";
|
|
30
31
|
```
|
|
31
32
|
|
|
32
|
-
**2. Next.js only
|
|
33
|
+
**2. Next.js only.** Transpile the source package in `next.config.ts`:
|
|
33
34
|
|
|
34
35
|
```ts
|
|
35
36
|
const nextConfig = { transpilePackages: ["@viliha/vui-ui"] };
|
|
@@ -40,29 +41,30 @@ export default nextConfig;
|
|
|
40
41
|
|
|
41
42
|
## Scaffold the full app + demo (`init`)
|
|
42
43
|
|
|
43
|
-
The package ships the **components
|
|
44
|
+
The package itself ships the **components**. The **app shell** (layout, sidebar,
|
|
44
45
|
browser-style **open tabs**, command palette, nav config, logo) and the **demo
|
|
45
|
-
pages**
|
|
46
|
+
pages** come from a one-shot scaffolder:
|
|
46
47
|
|
|
47
48
|
```bash
|
|
48
49
|
npx @viliha/vui-ui init
|
|
49
50
|
```
|
|
50
51
|
|
|
51
|
-
It's **interactive**
|
|
52
|
+
It's **interactive** and walks through a short decision tree:
|
|
52
53
|
|
|
53
|
-
1. **Fresh project?** (fresh vs existing)
|
|
54
|
-
2. **Pre-built theme?** — the full shell
|
|
55
|
-
|
|
54
|
+
1. **Fresh project?** (fresh vs. existing)
|
|
55
|
+
2. **Pre-built theme?** — the full shell plus demo pages, or just the theme wiring
|
|
56
|
+
for you to build on.
|
|
56
57
|
|
|
57
|
-
|
|
58
|
+
Everything it generates is copied into *your* repo, so you own and edit it.
|
|
58
59
|
|
|
59
60
|
| | **Pre-built** (shell + demo) | **Theme-only** (you configure) |
|
|
60
61
|
| --- | --- | --- |
|
|
61
62
|
| **Fresh** | full runnable app: config + shell + demo pages | just the theme wiring (`globals.css`, `next.config`) — build your own pages |
|
|
62
63
|
| **Existing** | shell + demo added; your config is **never** overwritten (prints merge steps) | nothing copied; prints the wiring steps |
|
|
63
64
|
|
|
64
|
-
|
|
65
|
-
|
|
65
|
+
Before that, it asks whether this is a standalone **Next.js** app or a
|
|
66
|
+
**Turborepo**; for a monorepo it scaffolds into a target app dir, such as
|
|
67
|
+
`apps/web`.
|
|
66
68
|
|
|
67
69
|
```
|
|
68
70
|
Flags (for CI / agents, skip the prompts):
|
|
@@ -75,15 +77,15 @@ Flags (for CI / agents, skip the prompts):
|
|
|
75
77
|
--dry-run preview without writing
|
|
76
78
|
```
|
|
77
79
|
|
|
78
|
-
`init` **
|
|
79
|
-
from
|
|
80
|
-
skip, or `--no-install` to
|
|
80
|
+
`init` **installs the dependencies for you** using the package manager it detects
|
|
81
|
+
from your lockfile (npm, pnpm, yarn, or bun). It prompts before doing so; pass
|
|
82
|
+
`--yes` to skip the prompt, or `--no-install` to handle it yourself.
|
|
81
83
|
|
|
82
84
|
### Fresh + pre-built (recommended for new apps)
|
|
83
85
|
|
|
84
|
-
Start from a `create-next-app` base **without `--src-dir`**
|
|
85
|
-
root `app/`
|
|
86
|
-
you
|
|
86
|
+
Start from a `create-next-app` base **without `--src-dir`** — the scaffold expects
|
|
87
|
+
a root `app/` with `@/*` → `./*` — then run `init`. It scaffolds the app, installs
|
|
88
|
+
the dependencies, and leaves you ready to run `dev`. Any package manager works:
|
|
87
89
|
|
|
88
90
|
```bash
|
|
89
91
|
# npm
|
|
@@ -103,16 +105,36 @@ bun create next-app my-app --ts --tailwind --app --no-src-dir
|
|
|
103
105
|
cd my-app && bunx @viliha/vui-ui init && bun dev
|
|
104
106
|
```
|
|
105
107
|
|
|
106
|
-
`init` writes `next.config.ts`, `tsconfig.json`, `app/globals.css`, the shell,
|
|
107
|
-
|
|
108
|
-
|
|
108
|
+
`init` writes `next.config.ts`, `tsconfig.json`, `app/globals.css`, the shell, and
|
|
109
|
+
the demo pages, overwriting the create-next-app boilerplate, and installs the
|
|
110
|
+
dependencies. The demo then runs out of the box at `/dashboard`.
|
|
111
|
+
|
|
112
|
+
### Turborepo / monorepo
|
|
113
|
+
|
|
114
|
+
Scaffold **inside the target app** (e.g. `apps/web`), never at the repo root —
|
|
115
|
+
the root has no `app/` and no Next.js app. Run `init` from the app, or name it
|
|
116
|
+
from the root with `--dir`:
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
# from inside the app (simplest)
|
|
120
|
+
cd apps/web && npx @viliha/vui-ui init
|
|
121
|
+
|
|
122
|
+
# …or from the repo root
|
|
123
|
+
npx @viliha/vui-ui init --turbo --dir apps/web
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
In monorepo mode `init` does **not** auto-install (installs are
|
|
127
|
+
workspace-specific), so add the deps to that app afterward — `cd apps/web && pnpm
|
|
128
|
+
add @viliha/vui-ui …`, or from the root `pnpm --filter web add @viliha/vui-ui …`.
|
|
129
|
+
The `transpilePackages` entry, the `theme.css` import, and the `@/*` alias all
|
|
130
|
+
belong to **that app**, not the root.
|
|
109
131
|
|
|
110
132
|
### ⚠️ Existing project — read this first
|
|
111
133
|
|
|
112
|
-
Adding VUI to an app you already have
|
|
113
|
-
overwrites your config.**
|
|
114
|
-
`app/(app)/` and `app/_components/`, or theme-only to copy nothing
|
|
115
|
-
prints the four things to wire up:
|
|
134
|
+
Adding VUI to an app you already have takes a little care. **`init --existing`
|
|
135
|
+
never overwrites your config.** Choose pre-built to add the shell and pages under
|
|
136
|
+
`app/(app)/` and `app/_components/`, or theme-only to copy nothing. Either way, it
|
|
137
|
+
prints the four things you need to wire up:
|
|
116
138
|
|
|
117
139
|
1. **`next.config`** — add `transpilePackages: ["@viliha/vui-ui"]`.
|
|
118
140
|
(Optional, for the open-tabs *keep-alive*: `output: "export"`,
|
|
@@ -127,19 +149,19 @@ prints the four things to wire up:
|
|
|
127
149
|
4. **Root `app/layout.tsx`** — `import "./globals.css"` (and mount fonts to match
|
|
128
150
|
the demo's look).
|
|
129
151
|
|
|
130
|
-
Run **`npx @viliha/vui-ui init --existing --prebuilt --dry-run`** first to
|
|
152
|
+
Run **`npx @viliha/vui-ui init --existing --prebuilt --dry-run`** first to preview
|
|
131
153
|
exactly what it will add. If you only want the components, choose **theme-only**
|
|
132
|
-
(or skip `init` and follow the [Setup](#setup) above), then import from
|
|
154
|
+
(or skip `init` entirely and follow the [Setup](#setup) above), then import from
|
|
133
155
|
`@viliha/vui-ui/*`.
|
|
134
156
|
|
|
135
|
-
> **
|
|
136
|
-
> `theme.css`. If your app already defines shadcn/ui or other CSS variables
|
|
137
|
-
> the same names, import `theme.css` **last** and remove the duplicates
|
|
138
|
-
>
|
|
157
|
+
> **A note on theming an existing app:** VUI owns its design tokens in
|
|
158
|
+
> `theme.css`. If your app already defines shadcn/ui or other CSS variables under
|
|
159
|
+
> the same names, import `theme.css` **last** and remove the duplicates so the two
|
|
160
|
+
> token sets don't collide. On a fresh project this never comes up.
|
|
139
161
|
|
|
140
162
|
## Usage
|
|
141
163
|
|
|
142
|
-
|
|
164
|
+
Every component has its own entry point, so you ship only what you use:
|
|
143
165
|
|
|
144
166
|
```tsx
|
|
145
167
|
import { Button } from "@viliha/vui-ui/button";
|
|
@@ -158,11 +180,11 @@ export function Example() {
|
|
|
158
180
|
|
|
159
181
|
### Datatables & forms
|
|
160
182
|
|
|
161
|
-
`RecordView`
|
|
162
|
-
editable cells, sorting, filtering, pagination, row
|
|
163
|
-
CSV / JSON / Excel / PDF import
|
|
164
|
-
form (slide-over or full-page). Required fields render a `*`, alignment and
|
|
165
|
-
colors come from the tokens
|
|
183
|
+
`RecordView` builds a complete admin datatable from a single `fields` array:
|
|
184
|
+
editable cells, sorting, filtering, pagination, row and bulk actions,
|
|
185
|
+
CSV / JSON / Excel / PDF import and export, and a buffered **Add / Edit / View**
|
|
186
|
+
form (slide-over or full-page). Required fields render a `*`, and alignment and
|
|
187
|
+
colors come from the tokens, so you never style a field by hand.
|
|
166
188
|
|
|
167
189
|
```tsx
|
|
168
190
|
import { RecordView, type RecordField } from "@viliha/vui-ui/record-view";
|
|
@@ -183,9 +205,9 @@ const fields: RecordField<Customer>[] = [
|
|
|
183
205
|
/>;
|
|
184
206
|
```
|
|
185
207
|
|
|
186
|
-
|
|
187
|
-
Info panel (from `formDescription`
|
|
188
|
-
[Data table docs](https://vui.viliha.com/docs/data-table).
|
|
208
|
+
That same `fields` array also drives `RecordForm`, the Add/Edit/View screen, along
|
|
209
|
+
with its Info panel (built from `formDescription` and each field's `description`).
|
|
210
|
+
See the [Data table docs](https://vui.viliha.com/docs/data-table) for the details.
|
|
189
211
|
|
|
190
212
|
## Patterns
|
|
191
213
|
|
|
@@ -205,14 +227,14 @@ The reference app composes these primitives into the conventions documented at
|
|
|
205
227
|
|
|
206
228
|
Copy them from the
|
|
207
229
|
[backoffice demo](https://github.com/myviliha/vui-starter/tree/main/apps/backoffice)
|
|
208
|
-
and adapt.
|
|
230
|
+
and adapt them to your app.
|
|
209
231
|
|
|
210
232
|
## Building with an AI agent
|
|
211
233
|
|
|
212
234
|
This package ships an **AI-agent usage guide** at
|
|
213
|
-
`node_modules/@viliha/vui-ui/AGENT.md
|
|
214
|
-
UI with VUI
|
|
215
|
-
|
|
235
|
+
`node_modules/@viliha/vui-ui/AGENT.md`. It captures the standards to follow when
|
|
236
|
+
generating UI with VUI: token discipline, reuse-first, page layout, RecordView,
|
|
237
|
+
forms, accessibility, and dark mode. The quickest way to load it is the shipped
|
|
216
238
|
`CLAUDE.template.md`:
|
|
217
239
|
|
|
218
240
|
```bash
|
|
@@ -220,8 +242,9 @@ cp node_modules/@viliha/vui-ui/CLAUDE.template.md ./CLAUDE.md # Claude Code
|
|
|
220
242
|
# or ./AGENTS.md for Cursor / Copilot
|
|
221
243
|
```
|
|
222
244
|
|
|
223
|
-
|
|
224
|
-
verbatim copy
|
|
245
|
+
That file is a one-line `@import` of `AGENT.md`, so the rules stay in a single
|
|
246
|
+
place. If you'd rather keep a verbatim copy, run
|
|
247
|
+
`cp node_modules/@viliha/vui-ui/AGENT.md AGENTS.md`.
|
|
225
248
|
|
|
226
249
|
## Components
|
|
227
250
|
|
|
@@ -234,9 +257,9 @@ wrapper) · `checkbox` · `command-palette` (⌘K launcher) · `dialog` ·
|
|
|
234
257
|
|
|
235
258
|
## Theming
|
|
236
259
|
|
|
237
|
-
Every design decision lives in `@viliha/vui-ui/theme.css` as CSS variables
|
|
238
|
-
|
|
239
|
-
to rebrand the
|
|
260
|
+
Every design decision lives in `@viliha/vui-ui/theme.css` as CSS variables —
|
|
261
|
+
colors, radius, typography, and dark mode. Override any token **after** the import
|
|
262
|
+
to rebrand the entire system:
|
|
240
263
|
|
|
241
264
|
```css
|
|
242
265
|
@import "@viliha/vui-ui/theme.css";
|
package/bin/vui.mjs
CHANGED
|
@@ -306,11 +306,17 @@ The shell + demo were added under app/(app)/ and app/_components/ — review the
|
|
|
306
306
|
}
|
|
307
307
|
|
|
308
308
|
if (turbo) {
|
|
309
|
-
console.log(`Turborepo
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
309
|
+
console.log(`Turborepo — finish inside the target app (${appDir}):
|
|
310
|
+
1. cd ${appDir}
|
|
311
|
+
2. Install the deps in THIS app (not the repo root):
|
|
312
|
+
${ADD_CMD[pm]} ${installList}
|
|
313
|
+
(or from the root with your workspace filter, e.g.
|
|
314
|
+
${pm} --filter <app-name> add ${installList})
|
|
315
|
+
3. Make sure your workspace globs include this app
|
|
316
|
+
(pnpm-workspace.yaml \`packages:\` or package.json \`workspaces\`).
|
|
317
|
+
4. Run it: ${pm} --filter <app-name> dev (or \`cd ${appDir} && ${pm} dev\`)
|
|
318
|
+
|
|
319
|
+
Deps were NOT auto-installed for a monorepo — installs are workspace-specific.
|
|
314
320
|
`);
|
|
315
321
|
}
|
|
316
322
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@viliha/vui-ui",
|
|
3
|
-
"version": "1.5.
|
|
3
|
+
"version": "1.5.2",
|
|
4
4
|
"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.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Suman Bonakurthi",
|