# shadcn Bộ điều hợp trực quan thành phần
## 🎯 Mục tiêu
Tái cấu trúc thành phần `` hiện có tại `` để khớp với **thiết kế, cấu trúc và hành vi trực quan** của thành phần tham chiếu có sẵn tại:
>
← tùy chọn; để trống nếu không có trang tài liệu tồn tại
KHÔNG thay thế logic nghiệp vụ, giao diện đạo cụ hiện có hoặc các mẫu tìm nạp dữ liệu. Hãy bảo tồn chúng.
Chỉ điều chỉnh **lớp trực quan**: cấu trúc đánh dấu, tên lớp, hình động và thuộc tính trợ năng.
---
## 📋 Bước 1 - Phân tích thành phần hiện có
Trước khi viết bất kỳ mã nào:
1. Đọc toàn bộ nguồn của ``.
2. Lập bản đồ:
- Tất cả **đạo cụ và loại của chúng** (giao diện TypeScript hoặc PropTypes).
- **Biến trạng thái** nội bộ** (`useState`, `useReducer`, lát cắt Zustand, v.v.).
- **Đã sử dụng **Nhà cung cấp bối cảnh hoặc móc tùy chỉnh**.
- **Thành phần con** được hiển thị và nơi chúng tồn tại.
- **Trình xử lý sự kiện** và lệnh gọi lại được hiển thị cho cấp độ gốc.
3. Liệt kê mọi **nhập** — gắn cờ bất kỳ nội dung nào sẽ xung đột với hoặc có thể được thay thế bằng shadcn nguyên thủy.
Xuất bảng kiểm tra ngắn gọn trước khi chạm vào bất kỳ mã nào:
| Mục | Giá trị hiện tại | Hành động |
|------|--------------|--------|
| Đạo cụ | ... | giữ/đổi tên/xóa |
| Tiểu bang | ... | giữ / di chuyển |
| Bối cảnh/Móc | ... | giữ/thay thế |
| Tiểu thành phần | ... | giữ/thay thế |
| Phụ thuộc | ... | giữ/cài đặt/gỡ bỏ |
---
## 📦 Bước 2 - Giải quyết phụ thuộc
Chạy lệnh cài đặt trực tiếp:
Sau khi lệnh hoàn thành, các tệp được tạo sẽ xuất hiện trong
/. Tiếp tục Bước 3 bằng cách sử dụng các tệp đó.
---
## 🔬 Bước 3 - Xem lại thành phần tham chiếu
NẾU được cung cấp → tìm nạp nó và trích xuất thông số trực quan như trước.
NẾU trống → đọc các tệp được tải xuống bằng lệnh CLI
ở Bước 2 và trích xuất thông tin tương tự từ mã nguồn trực tiếp:
- lược đồ biến thể cva
- thuộc tính trạng thái dữ liệu / dữ liệu bị vô hiệu hóa
- lớp hoạt hình/chuyển tiếp
- Vai trò và đạo cụ ARIA
- mẫu sử dụng cn()
---
## 🛠 Bước 4 - Tái cấu trúc thành phần
Áp dụng cấu trúc trực quan từ Bước 3 cho thành phần hiện có từ Bước 1.
###Quy tắc:
- ✅ Giữ tất cả **tên và loại prop hiện có** trừ khi tồn tại một shadcn tương đương trực tiếp.
- ✅ Giữ tất cả **tìm nạp dữ liệu, logic nghiệp vụ và lệnh gọi lại**.
- ✅ Bao bọc các phần gốc Radix bằng cách sử dụng **`forwardRef`** và trải rộng `...props` để duy trì tính linh hoạt.
- ✅ Sử dụng `cn()` để hợp nhất tất cả tên lớp - không bao giờ nối chuỗi.
- ✅ Xuất các thành phần phụ ghép có tên nếu thành phần tham chiếu sử dụng chúng (ví dụ: `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionContent`).
- ❌ KHÔNG nhập tệp shadcn đã tạo và xuất lại nó — xây dựng nội tuyến nguyên thủy trong tệp được tái cấu trúc để giữ logic cùng vị trí.
- ❌ KHÔNG thêm các lớp Tailwind không có trong thành phần tham chiếu mà không có hướng dẫn rõ ràng.
### Hành vi phản hồi (``):
Áp dụng các lớp đáp ứng ưu tiên thiết bị di động. Xác nhận các điểm dừng hiện tại trong `tailwind.config.ts` khớp với quy ước của dự án. Nếu tham chiếu sử dụng truy vấn vùng chứa, hãy cài đặt `@tailwindcss/container-queries`.
---
## 🧩 Bước 5 — Nhà cung cấp bối cảnh và Hooks
Nếu thành phần tham chiếu yêu cầu nhà cung cấp ngữ cảnh (ví dụ: `ToastProvider`, `TooltipProvider`):
1. Kiểm tra xem nó đã được gắn vào `` hay `` chưa.
2. Nếu không, hãy thêm nó vào tệp bố cục thích hợp. Cung cấp sự khác biệt chính xác.
3. Nếu cần có một hook tùy chỉnh (ví dụ: `useToast`, `useDialog`), hãy đặt nó vào `` và nhập nó từ đó.
---
## ❓ Bước 6 — Làm rõ câu hỏi (hỏi trước khi tạo nếu chưa biết)
Nếu bất kỳ điều nào sau đây không thể xác định được từ mã hiện có, **hãy hỏi trước khi viết**:
1. **Dữ liệu/đạo cụ**: Hình dạng dữ liệu nào sẽ được truyền? (Cung cấp một đối tượng mẫu nếu hữu ích.)
2. **Quản lý trạng thái**: Trạng thái thành phần là cục bộ hay được quản lý bên ngoài (Zustand, Redux, React Query)?
3. **Tài sản**: Có hình ảnh, logo hoặc biểu tượng tùy chỉnh bắt buộc nào không được lucide-react bao phủ không?
4. **Đáp ứng**: Bố cục dự kiến tại điểm ngắt `` là gì?
5. **Vị trí**: Thành phần này sẽ tồn tại ở đâu trong cây định tuyến/bố cục ứng dụng? (Quan trọng đối với vị trí nhà cung cấp ngữ cảnh.)
---
## 📐 Bước 7 — Định dạng đầu ra
Cho kết quả dưới dạng:
1. **``** — tệp thành phần được tái cấu trúc đầy đủ.
2. **`/.tsx`** — shadcn nguyên thủy (chỉ khi cần thiết và không được CLI tạo ra).
3. **`lib/utils.ts`** — chỉ khi nó cần được tạo hoặc cập nhật.
4. **Khác biệt về bố cục/nhà cung cấp** — chỉ khi cần thêm nhà cung cấp.
5. Danh sách phần **ghi chú di chuyển** ngắn gọn:
- Đã xóa phụ thuộc
- Đổi tên đạo cụ (nếu có)
- Bất kỳ bước thủ công nào được yêu cầu (ví dụ: thêm biến CSS vào `globals.css`)
---
## 🎨 Biến CSS Tailwind (mã thông báo thiết kế shadcn)
Xác nhận rằng `globals.css` chứa các thuộc tính tùy chỉnh CSS bắt buộc. Nếu thành phần tham chiếu sử dụng các mã thông báo như `--radius`, `--background`, `--foreground`, `--primary`, `--ring`, hãy nối thêm các biến bị thiếu. Sử dụng bộ mã thông báo mặc định shadcn cho `` trừ khi dự án đã xác định chủ đề tùy chỉnh.
---
## 🚫 Ràng buộc
- Khung: ****
- Tạo kiểu: **Chỉ CSS Tailwind ** — không có kiểu nội tuyến, không có mô-đun CSS, không có thành phần được tạo kiểu.
- TypeScript: **chế độ nghiêm ngặt**. Tất cả mã mới phải được gõ đầy đủ.
- Không nâng cấp hoặc hạ cấp bất kỳ phiên bản phụ thuộc hiện có nào trừ khi có xung đột trực tiếp giữa các phiên bản.
