Ark Collection
Bộ sưu tập danh sách và cây phân cấp dữ liệu xây dựng từ @ark-ui/react/collection kết hợp với Tailwind CSS v4. Cung cấp cả List Collection (đồng bộ kích thước với Input & Button, lọc tìm kiếm, đa dạng bố cục) và Tree Collection (createTreeCollection, createFileTreeCollection, điều hướng tổ tiên - hậu duệ, lọc đệ quy và làm phẳng cây).
1. Đồng bộ kích thước với Input & Button (Size Sync)
Chứng minh sự thẳng hàng và khớp chuẩn 100% về chiều cao, padding, và typography của ArkCollection với Input và Button ở cả 4 kích thước.
Kiểm tra độ cao và font chữ trực quan giữa ArkCollection (chips/item), Input và Button để đảm bảo sự đồng bộ 100% trong toàn hệ thống:
ArkCollection Item
Input
Button
ArkCollection Item
Input
Button
ArkCollection Item
Input
Button
ArkCollection Item
Input
Button
2. Chọn 1 mục duy nhất (Single Selection)
Chế độ chọn đơn mục với radio indicator tự động, phản hồi giá trị lập tức.
Hệ quản trị cơ sở dữ liệu quan hệ mạnh mẽ, chuẩn SQL.
Cơ sở dữ liệu phổ biến, tối ưu cho ứng dụng web truyền thống.
Nhúng trực tiếp dạng tệp tin, nhẹ và không cần cấu hình server.
Cơ sở dữ liệu tài liệu NoSQL linh hoạt với cấu trúc JSON.
3. Chọn nhiều mục & Thanh công cụ (Multiple Selection)
Chế độ chọn nhiều mục kết hợp checkbox indicator, thanh công cụ Chọn tất cả, Bỏ chọn và huy hiệu đếm.
Toàn quyền truy cập và cấu hình toàn bộ hệ thống.
Được phép tạo, chỉnh sửa và xuất bản nội dung bài viết.
Kiểm duyệt bình luận, hình ảnh và tương tác người dùng.
Được phép viết bài mới nhưng cần phê duyệt trước khi đăng.
4. Tìm kiếm & Lọc trực tiếp (Searchable)
Tích hợp ô tìm kiếm lọc danh sách tức thì kèm nút xóa nhanh và trạng thái Empty khi không có kết quả.
JavaScript với static types an toàn.
Thư viện UI phổ biến nhất thế giới.
Utility-first CSS framework thế hệ mới.
Headless component library xây dựng trên Zag.js.
Framework full-stack hiệu năng cao.
Next-generation ORM cho Node.js và TypeScript.
5. Đa dạng bố cục hiển thị (Layouts)
Chuyển đổi linh hoạt giữa 3 dạng bố cục: Danh sách dòng (List), Lưới thẻ card (Grid), và Thẻ tag pills (Chips).
Tối ưu thời gian phản hồi dưới 50ms.
Xác thực CSRF và mã hóa nhiều lớp.
Kiến trúc modular sẵn sàng cho hàng triệu người dùng.
Thiết kế chuẩn Tailwind CSS v4 và Ark UI.
6. Biến thể phong cách (Variants)
4 biến thể giao diện: Default (viền chuẩn), Card (thẻ nổi bật), Subtle (nền dịu nhẹ), và Bordered (viền đậm 2px).
Mô tả ngắn gọn cho tùy chọn A
Mô tả ngắn gọn cho tùy chọn B
7. Quản lý danh sách động (useListCollection)
Tận dụng hook useListCollection từ @ark-ui/react/collection để thêm mới và xóa item theo thời gian thực.
8. Compound Component API
Khả năng tùy biến sâu sắc thông qua các sub-components: Root, Toolbar, Search, List, Item, ItemIndicator, ItemText, ItemBadge.
9. Tích hợp chuyên dụng Remix Hook Form (CollectionField)
Sử dụng CollectionField kết hợp RemixValidatedForm, ArkField và Zod schema để kiểm tra tính hợp lệ và thu thập dữ liệu form mượt mà.
10. Tree Collection: Cấu trúc Cây & Tra cứu Phân cấp (createTreeCollection)
Sử dụng createTreeCollection quản lý dữ liệu cây phân cấp doanh nghiệp/phòng ban. Tra cứu tức thời chuỗi node tổ tiên (getParentNodes), độ sâu (depth), kiểm tra nhánh (isBranchNode) và lấy toàn bộ con cháu (getDescendantValues).
Sử dụng createTreeCollection để quản lý dữ liệu cây phân cấp doanh nghiệp. Bấm vào bất kỳ node nào trong cây để kiểm tra các phương thức tra cứu thông minh thời gian thực:
Tra cứu TreeCollection (Node Inspector)
Vai trò: Giao diện & Trải nghiệm
11. File Tree Collection: Tự động phân giải đường dẫn tệp (createFileTreeCollection)
Tự động chuyển đổi mảng chuỗi đường dẫn tệp tin UNIX thành cây thư mục lồng nhau hoàn chỉnh. Hỗ trợ thêm đường dẫn mới trực tiếp và tính toán quan hệ thư mục cha-con.
Hàm createFileTreeCollection(paths) nhận vào một mảng chuỗi đường dẫn (file paths) và tự động xây dựng cây thư mục chuẩn xác. Nhập đường dẫn tệp mới để kiểm tra:
Thông tin tệp đang chọn
12. Thao tác động trên Cây phân cấp (Tree Mutations & Filtering)
Khả năng lọc cây bảo toàn phân cấp với tree.filter(predicate), thêm node con vào nhánh bất kỳ và xóa bỏ node kèm con cháu với tree.remove().
Trải nghiệm tính năng lọc phân cấp với tree.filter(predicate) (tự động giữ lại các node cha liên đới) và xóa nhánh với tree.remove(indexPaths):
13. Làm phẳng cây phân cấp (tree.flatten)
Chuyển đổi cây phân cấp lồng nhau phức tạp thành mảng tuyến tính kèm các chỉ số quan hệ _index, _parent và _children phục vụ ảo hóa (virtual list) và bảng phân tích.
Phương thức tree.flatten() chuyển đổi cây phân cấp lồng nhau thành một mảng phẳng duy nhất với các chỉ mục quan hệ _index, _parent, và _children.
| _index | Tên Node & Cấp bậc phân cấp | Mã ID (value) | _parent | _children |
|---|---|---|---|---|
| #0 | Tập đoàn Công nghệ ChillCMS Global | org-root | (Gốc) | [#1, #2, #3] |
| #1 | Khối Kỹ thuật & Công nghệ (Engineering) | eng | #0 | [#4, #5, #6] |
| #4 | Đội ngũ Frontend (React, Tailwind & Ark UI) | eng-frontend | #1 | - |
| #5 | Đội ngũ Backend (Node.js, Remix & Prisma) | eng-backend | #1 | - |
| #6 | Đội ngũ DevOps & Hạ tầng đám mây | eng-devops | #1 | - |
| #2 | Khối Sản phẩm & Thiết kế (Product & UX) | product | #0 | [#7, #8] |
| #7 | Đội ngũ UI/UX Design System | prod-uiux | #2 | - |
| #8 | Ban Quản trị Sản phẩm (Product Managers) | prod-pm | #2 | - |
| #3 | Khối Tăng trưởng & Marketing | growth | #0 | [#9, #10] |
| #9 | Đội ngũ Sáng tạo Nội dung & SEO | growth-content | #3 | - |
| #10 | Đội ngũ Tư vấn Doanh nghiệp (Enterprise) | growth-sales | #3 | - |
flatten() cho phép tích hợp trực tiếp với các thư viện ảo hóa như @tanstack/react-virtual, tính toán vị trí cuộn mượt mà mà không gặp giới hạn đệ quy DOM của cây lồng nhau hàng nghìn cấp.14. Bảng thông số thuộc tính ArkCollection (Props Reference)
Tài liệu chi tiết về các props cấu hình cho ArkCollection và CollectionField.
| Thuộc tính (Prop) | Kiểu dữ liệu (Type) | Mặc định | Mô tả |
|---|---|---|---|
| items | (ArkCollectionItem | string)[] | [] | Danh sách các mục hiển thị trong bộ sưu tập. |
| selectionMode | 'single' | 'multiple' | 'multiple' | Chế độ chọn 1 mục duy nhất hoặc chọn nhiều mục. |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Kích thước chuẩn hóa đồng bộ với Input và Button qua control-size. |
| layout | 'list' | 'grid' | 'chips' | 'list' | Dạng hiển thị: Danh sách dòng, Lưới thẻ card, hoặc Thẻ tag pills. |
| variant | 'default' | 'card' | 'subtle' | 'bordered' | 'default' | Biến thể đường viền và phong cách giao diện. |
| searchable | boolean | false | Hiển thị ô tìm kiếm lọc nội dung trực tiếp trong bộ sưu tập. |
| showToolbar | boolean | false | Hiển thị thanh công cụ với nút Chọn tất cả, Bỏ chọn và đếm số lượng. |
| clearable | boolean | false | Hiển thị nút xóa toàn bộ lựa chọn nhanh. |
| value / onValueChange | string[] | string / (values: string[]) => void | undefined | Quản lý trạng thái lựa chọn từ bên ngoài (Controlled state). |
15. Bảng phương thức Tra cứu & Thao tác TreeCollection (API Reference)
Danh sách các phương thức và hàm tiện ích tích hợp sẵn trong đối tượng TreeCollection của Ark UI / Zag.
| Phương thức (Method) | Cú pháp & Tham số | Kiểu trả về (Return) | Mô tả chức năng |
|---|---|---|---|
| flatten() | (rootNode?: T) => FlatTreeNode<T>[] | FlatTreeNode<T>[] | Chuyển đổi toàn bộ cấu trúc cây thành mảng phẳng tuyến tính kèm metadata quan hệ (_parent, _children, _index) phục vụ ảo hóa (virtualization). |
| findNode(value) | (value: string) => T | undefined | T | undefined | Tìm kiếm nhanh node trong cây theo mã định danh duy nhất (value/id). |
| getDepth(value) | (value: string) => number | number | Trả về độ sâu phân cấp của node (Node gốc = 0, node con trực tiếp = 1, ...). |
| getParentNode(value) | (value: string | IndexPath) => T | undefined | T | undefined | Truy xuất trực tiếp node cha quản lý của node hiện tại. |
| getParentNodes(value) | (value: string | IndexPath) => T[] | T[] | Trả về chuỗi danh sách tất cả các node tổ tiên từ gốc đến cha trực tiếp, lý tưởng cho Breadcrumbs. |
| getDescendantValues(value) | (value: string | IndexPath) => string[] | string[] | Lấy mảng chứa toàn bộ mã định danh (values) của con cháu nhiều cấp bên dưới node chỉ định. |
| isBranchNode(node) | (node: T) => boolean | boolean | Kiểm tra xem một node có phải là nhánh (có chứa node con) hay là node lá cuối cùng. |
| filter(predicate) | (predicate: (node: T) => boolean) => TreeCollection<T> | TreeCollection<T> | Lọc cây phân cấp và tạo bản sao TreeCollection mới, tự động bảo tồn chuỗi node cha dẫn đến node con khớp điều kiện. |
| remove(indexPaths) | (indexPaths: IndexPath[]) => TreeCollection<T> | TreeCollection<T> | Loại bỏ một hoặc nhiều node (kèm toàn bộ nhánh con) và trả về TreeCollection mới đã cập nhật. |
| insertBefore / insertAfter | (indexPath: IndexPath, nodes: T[]) => TreeCollection<T> | TreeCollection<T> | Chèn thêm các node mới vào trước hoặc sau vị trí indexPath chỉ định trong cây. |