@capy-vn/ui 0.1.0

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.
Files changed (10) hide show
  1. package/README.md +299 -0
  2. package/dist/index.browser.js +51746 -0
  3. package/dist/index.cjs +5682 -0
  4. package/dist/index.cjs.map +1 -0
  5. package/dist/index.d.cts +1391 -0
  6. package/dist/index.d.ts +1391 -0
  7. package/dist/index.js +5435 -0
  8. package/dist/index.js.map +1 -0
  9. package/package.json +82 -0
  10. package/src/styles/globals.css +99 -0
package/README.md ADDED
@@ -0,0 +1,299 @@
1
+ # @capy/ui
2
+
3
+ Thư viện component dùng chung cho các project frontend, xây dựng trên shadcn/ui + Radix UI + Tailwind CSS.
4
+
5
+ ---
6
+
7
+ ## Cài đặt
8
+
9
+ Thêm package vào project qua git dependency:
10
+
11
+ ```bash
12
+ # npm
13
+ npm install "git+https://gitlab.com/capy-agents/capy-frontend-components.git#main"
14
+
15
+ # yarn
16
+ yarn add "git+https://gitlab.com/capy-agents/capy-frontend-components.git#main"
17
+
18
+ # pnpm
19
+ pnpm add "git+https://gitlab.com/capy-agents/capy-frontend-components.git#main"
20
+ ```
21
+
22
+ Để pin vào một commit cụ thể (khuyến nghị cho production):
23
+
24
+ ```bash
25
+ npm install "git+https://gitlab.com/capy-agents/capy-frontend-components.git#<commit-hash>"
26
+ ```
27
+
28
+ ---
29
+
30
+ ## Setup
31
+
32
+ ### 1. Import CSS
33
+
34
+ Trong `app/globals.css` hoặc `app/layout.tsx`:
35
+
36
+ ```css
37
+ /* globals.css */
38
+ @import "@capy/ui/styles";
39
+ @tailwind base;
40
+ @tailwind components;
41
+ @tailwind utilities;
42
+ ```
43
+
44
+ Hoặc trong `layout.tsx`:
45
+
46
+ ```tsx
47
+ import "@capy/ui/styles";
48
+ ```
49
+
50
+ ### 2. Cấu hình Tailwind
51
+
52
+ Thêm path vào `tailwind.config.js` để Tailwind scan được class từ library:
53
+
54
+ ```js
55
+ /** @type {import('tailwindcss').Config} */
56
+ module.exports = {
57
+ content: [
58
+ "./app/**/*.{ts,tsx}",
59
+ "./components/**/*.{ts,tsx}",
60
+ "./node_modules/@capy/ui/dist/**/*.{js,mjs}", // <-- thêm dòng này
61
+ ],
62
+ theme: {
63
+ extend: {},
64
+ },
65
+ plugins: [],
66
+ };
67
+ ```
68
+
69
+ ### 3. Thêm Toaster (cho toast notifications)
70
+
71
+ Trong root layout:
72
+
73
+ ```tsx
74
+ import { Toaster } from "@capy/ui";
75
+
76
+ export default function RootLayout({ children }) {
77
+ return (
78
+ <html>
79
+ <body>
80
+ {children}
81
+ <Toaster />
82
+ </body>
83
+ </html>
84
+ );
85
+ }
86
+ ```
87
+
88
+ ---
89
+
90
+ ## Sử dụng
91
+
92
+ ```tsx
93
+ import { Button, Input, Card, CardContent } from "@capy/ui";
94
+
95
+ export function LoginCard() {
96
+ return (
97
+ <Card>
98
+ <CardContent className="space-y-4 p-6">
99
+ <Input placeholder="Email" type="email" />
100
+ <Button className="w-full">Đăng nhập</Button>
101
+ </CardContent>
102
+ </Card>
103
+ );
104
+ }
105
+ ```
106
+
107
+ ### Form với react-hook-form
108
+
109
+ Các component `Form*` đã tích hợp sẵn `react-hook-form`:
110
+
111
+ ```tsx
112
+ import { useForm } from "react-hook-form";
113
+ import { Form, FormInput, FormSelect, Button } from "@capy/ui";
114
+
115
+ export function CreateUserForm() {
116
+ const form = useForm({ defaultValues: { name: "", role: "" } });
117
+
118
+ return (
119
+ <Form {...form}>
120
+ <form onSubmit={form.handleSubmit(console.log)} className="space-y-4">
121
+ <FormInput name="name" label="Tên" placeholder="Nhập tên..." />
122
+ <FormSelect
123
+ name="role"
124
+ label="Vai trò"
125
+ options={[
126
+ { value: "admin", label: "Admin" },
127
+ { value: "user", label: "User" },
128
+ ]}
129
+ />
130
+ <Button type="submit">Tạo</Button>
131
+ </form>
132
+ </Form>
133
+ );
134
+ }
135
+ ```
136
+
137
+ ---
138
+
139
+ ## Danh sách Components
140
+
141
+ ### UI Primitives
142
+
143
+ | Component | Import |
144
+ |-----------|--------|
145
+ | `Button` | `@capy/ui` |
146
+ | `Input` | `@capy/ui` |
147
+ | `Textarea` | `@capy/ui` |
148
+ | `Label` | `@capy/ui` |
149
+ | `Checkbox` | `@capy/ui` |
150
+ | `Switch` | `@capy/ui` |
151
+ | `RadioGroup`, `RadioGroupItem` | `@capy/ui` |
152
+ | `Select`, `SelectTrigger`, `SelectContent`, `SelectItem` | `@capy/ui` |
153
+ | `SearchSelect` | `@capy/ui` |
154
+ | `MultiSelect` | `@capy/ui` |
155
+ | `NumberInput` | `@capy/ui` |
156
+ | `Slider` | `@capy/ui` |
157
+ | `OtpInput` | `@capy/ui` |
158
+ | `FileUpload` | `@capy/ui` |
159
+ | `Badge` | `@capy/ui` |
160
+ | `Avatar`, `AvatarImage`, `AvatarFallback` | `@capy/ui` |
161
+ | `Card`, `CardHeader`, `CardContent`, `CardFooter`, `CardTitle`, `CardDescription` | `@capy/ui` |
162
+ | `Alert`, `AlertTitle`, `AlertDescription` | `@capy/ui` |
163
+ | `Separator` | `@capy/ui` |
164
+ | `Progress` | `@capy/ui` |
165
+ | `Skeleton` | `@capy/ui` |
166
+ | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent` | `@capy/ui` |
167
+ | `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogFooter` | `@capy/ui` |
168
+ | `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, ... | `@capy/ui` |
169
+ | `Sheet`, `SheetTrigger`, `SheetContent` | `@capy/ui` |
170
+ | `Popover`, `PopoverTrigger`, `PopoverContent` | `@capy/ui` |
171
+ | `DropdownMenu`, `DropdownMenuTrigger`, `DropdownMenuContent`, `DropdownMenuItem` | `@capy/ui` |
172
+ | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` | `@capy/ui` |
173
+ | `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider` | `@capy/ui` |
174
+ | `ScrollArea` | `@capy/ui` |
175
+ | `Breadcrumb`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbSeparator` | `@capy/ui` |
176
+ | `Calendar` | `@capy/ui` |
177
+ | `DatePicker` | `@capy/ui` |
178
+ | `DateRangePicker` | `@capy/ui` |
179
+ | `TimePicker` | `@capy/ui` |
180
+ | `DatetimePicker` | `@capy/ui` |
181
+ | `DatetimeRangePicker` | `@capy/ui` |
182
+ | `Toaster` | `@capy/ui` |
183
+
184
+ ### Forms (tích hợp react-hook-form)
185
+
186
+ | Component | Mô tả |
187
+ |-----------|-------|
188
+ | `FormInput` | Input field |
189
+ | `FormTextarea` | Textarea field |
190
+ | `FormCheckbox` | Checkbox field |
191
+ | `FormSwitch` | Switch field |
192
+ | `FormSelect` | Select dropdown |
193
+ | `FormNumberInput` | Số nguyên / thập phân |
194
+ | `FormSlider` | Range slider |
195
+ | `FormOtpInput` | OTP input |
196
+ | `FormMultiSelect` | Multi-select |
197
+ | `FormFileUpload` | File upload |
198
+ | `FormDatePicker` | Chọn ngày |
199
+ | `FormTimePicker` | Chọn giờ |
200
+ | `FormDatetimePicker` | Chọn ngày + giờ |
201
+ | `FormDateRangePicker` | Chọn khoảng ngày |
202
+ | `FormDatetimeRangePicker` | Chọn khoảng ngày + giờ |
203
+
204
+ Tất cả Form components nhận prop `name`, `label`, và `description` (optional hint text).
205
+
206
+ ### Layout
207
+
208
+ | Component | Mô tả |
209
+ |-----------|-------|
210
+ | `PageLayout` | Layout trang đầy đủ với header/content |
211
+ | `SidebarLayout` | Layout có sidebar |
212
+ | `Container` | Wrapper có max-width và padding |
213
+ | `Stack` | Flex stack (vertical) |
214
+ | `HStack` | Flex stack ngang |
215
+ | `VStack` | Flex stack dọc |
216
+
217
+ ### Navigation
218
+
219
+ | Component | Mô tả |
220
+ |-----------|-------|
221
+ | `Pagination` | Phân trang với `usePagination` hook |
222
+ | `Stepper` | Stepper multi-step |
223
+
224
+ ### Data Display
225
+
226
+ | Component | Mô tả |
227
+ |-----------|-------|
228
+ | `DataTable` | Table với TanStack Table |
229
+ | `StatCard` | Card hiển thị số liệu |
230
+ | `EmptyState` | Màn hình trống |
231
+ | `DescriptionList` | Danh sách key-value |
232
+ | `Timeline` | Timeline sự kiện |
233
+
234
+ ### Feedback
235
+
236
+ | Component | Mô tả |
237
+ |-----------|-------|
238
+ | `LoadingSpinner` | Spinner loading |
239
+ | `LoadingOverlay` | Overlay loading toàn màn hình |
240
+ | `ConfirmDialog` | Dialog xác nhận hành động |
241
+ | `Result` | Trang trạng thái (success/error/warning) |
242
+
243
+ ---
244
+
245
+ ## Hooks
246
+
247
+ ```tsx
248
+ import { useDisclosure, useDebounce, usePagination, useLocalStorage } from "@capy/ui";
249
+ ```
250
+
251
+ | Hook | Mô tả |
252
+ |------|-------|
253
+ | `useDisclosure()` | Quản lý trạng thái open/close (modal, dropdown) |
254
+ | `useDebounce(value, delay)` | Debounce giá trị |
255
+ | `usePagination(options)` | Logic phân trang |
256
+ | `useLocalStorage(key, initial)` | Đọc/ghi localStorage |
257
+
258
+ ---
259
+
260
+ ## Utilities
261
+
262
+ ```tsx
263
+ import { cn } from "@capy/ui";
264
+
265
+ // Kết hợp Tailwind class
266
+ <div className={cn("base-class", condition && "conditional-class")} />
267
+ ```
268
+
269
+ ---
270
+
271
+ ## Peer Dependencies
272
+
273
+ Project sử dụng library cần có sẵn:
274
+
275
+ ```json
276
+ {
277
+ "react": "^18.0.0",
278
+ "react-dom": "^18.0.0",
279
+ "tailwindcss": "^3.0.0"
280
+ }
281
+ ```
282
+
283
+ Next.js là optional — library hoạt động với bất kỳ React 18+ project nào.
284
+
285
+ ---
286
+
287
+ ## Cập nhật
288
+
289
+ Để lấy version mới nhất từ `main`:
290
+
291
+ ```bash
292
+ npm install "git+https://gitlab.com/capy-agents/capy-frontend-components.git#main"
293
+ ```
294
+
295
+ ---
296
+
297
+ ## License
298
+
299
+ MIT © Tâm Nguyễn