Ark Fieldset
Thành phần nhóm các trường nhập liệu chuẩn ngữ nghĩa HTML5 <fieldset> và <legend>. Tích hợp máy trạng thái Zag.js, hỗ trợ tính năng tự động vô hiệu hóa (cascade disabled) toàn bộ form controls bên trong, thông báo lỗi WAI-ARIA, 5 biến thể kiểu dáng và 4 kích cỡ token tiêu chuẩn.
1. Hai phương thức sử dụng: Shorthand & Compound Anatomy
Hai mô hình APIArkFieldset hỗ trợ cả cú pháp 1 dòng tiện ích (Shorthand) lẫn cấu trúc Compound Components để tùy biến sâu sắc.
Truyền các props như legend, description, required, actions trực tiếp vào component.
Sử dụng ArkFieldset.Root, Legend, HelperText, Content, ErrorText.
2. Ma trận kiểu dáng (Variants)
5 Biến thểKhám phá 5 biến thể trực quan: Plain (tối giản), Card (thẻ nổi), Bordered (viền sắc nét), Subtle (nền dịu) và Outline (kính mờ).
3. Đồng bộ kích thước Controls (Sizes Matrix)
xs / sm / md / lgCả 4 kích cỡ (xs, sm, md, lg) được chuẩn hóa theo token ControlSize, căn chỉnh hoàn hảo với Input, Button và Switch.
So sánh trực tiếp cả 4 kích cỡ (xs, sm, md, lg):
4. Trạng thái tương tác & Kiểm tra tính hợp lệ (States & Validation)
Interactive ControlsKiểm thử tính năng tự động vô hiệu hóa toàn bộ controls bên trong (HTML5 Cascade Disabled) và thông báo lỗi WAI-ARIA.
5. Kịch bản ứng dụng thực tế (Real-World Scenarios)
Thực tếKhám phá các mô hình thiết kế thực tế: Hồ sơ người dùng, Thanh toán trực tuyến, Cấu hình thông báo và Fieldset lồng nhau.
Kịch bản 1: Hồ sơ & Thông tin tài khoản người dùng
Kịch bản 2: Thông tin thanh toán & Thẻ tín dụng quốc tế
Kịch bản 3: Kênh nhận thông báo hệ thống
Kịch bản 4: Fieldset lồng nhau (Nested Fieldsets)
6. Mã nguồn mẫu & Cách tích hợp
Code SnippetMã nguồn React mẫu để bạn có thể sao chép và áp dụng ngay vào các module của ChillCMS.
import { ArkFieldset } from '~/components/ui/ark-fieldset';
import { Input } from '~/components/ui/input';
// Cách 1: Shorthand API
<ArkFieldset
variant="card"
size="md"
legend="Thông tin cá nhân"
description="Vui lòng cung cấp chính xác họ tên và email."
required
>
<Input placeholder="Họ và tên..." />
<Input type="email" placeholder="Địa chỉ email..." />
</ArkFieldset>
// Cách 2: Compound Anatomy API
<ArkFieldset.Root variant="card" size="md">
<ArkFieldset.Legend required>Thông tin cá nhân</ArkFieldset.Legend>
<ArkFieldset.HelperText>Vui lòng cung cấp chính xác họ tên và email.</ArkFieldset.HelperText>
<ArkFieldset.Content>
<Input placeholder="Họ và tên..." />
<Input type="email" placeholder="Địa chỉ email..." />
</ArkFieldset.Content>
<ArkFieldset.ErrorText>Dữ liệu không hợp lệ.</ArkFieldset.ErrorText>
</ArkFieldset.Root>7. Tra cứu Props & Cấu trúc thành phần (API Reference)
DocumentationToàn bộ props của ArkFieldset, các Compound Subcomponents và Zag state machine hook.
| Thuộc tính (Prop) | Kiểu dữ liệu (Type) | Mặc định | Mô tả |
|---|---|---|---|
| legend | ReactNode | - | Tiêu đề của Fieldset khi dùng Shorthand API. |
| description / helperText | ReactNode | - | Đoạn văn mô tả phụ hiển thị bên dưới Legend. |
| errorText | ReactNode | - | Nội dung thông báo lỗi khi trường hợp `invalid` xảy ra. |
| variant | 'plain' | 'card' | 'bordered' | 'subtle' | 'outline' | 'plain' | Kiểu dáng hiển thị viền và nền của Fieldset. |
| size | 'xs' | 'sm' | 'md' | 'lg' | 'md' | Kích cỡ token padding và khoảng cách các trường. |
| required | boolean | false | Hiển thị dấu hoa thị đỏ (*) báo hiệu nhóm bắt buộc. |
| optional | boolean | false | Hiển thị dòng chữ `(Không bắt buộc)` cạnh Legend. |
| disabled | boolean | false | Vô hiệu hóa toàn bộ các input/button bên trong fieldset theo chuẩn HTML5. |
| invalid | boolean | false | Bật trạng thái lỗi và kích hoạt hiển thị `ErrorText`. |
| actions | ReactNode | - | Slot nội dung góc phải thanh Legend (nút bấm, badge, switch). |
| legendVariant | 'default' | 'badge' | 'bordered' | 'default' | Kiểu dáng hiển thị của Legend (tiêu chuẩn, dạng huy hiệu, hoặc gạch chân). |
Danh sách Compound Subcomponents:
ArkFieldset.Root: Thẻ fieldset bao ngoài, cung cấp contextArkFieldset.Legend: Thẻ tiêu đề nhóm biểu mẫuArkFieldset.HelperText: Văn bản hướng dẫn phụArkFieldset.ErrorText: Văn bản thông báo lỗi (tự ẩn khi hợp lệ)ArkFieldset.Content: Container chứa danh sách inputsArkFieldset.Context: Render prop truy cập máy trạng thái Zag