Ark Field Component
Thành phần form field toàn diện, đóng gói ngữ cảnh trợ năng (accessible context) chuẩn WAI-ARIA với khả năng tự động liên kết nhãn qua aria-labelledby, gợi ý và thông báo lỗi qua aria-describedby, cùng các data-attributes trạng thái (data-invalid, data-disabled, data-readonly, data-required). Hỗ trợ cả hai phong cách lập trình Compound API và Shorthand API với 4 kích thước đồng bộ.
1. Bảng điều khiển tương tác (Interactive Playground)
Live ControlsThử nghiệm thời gian thực các kích cỡ, bố cục, trạng thái và nội dung văn bản của thành phần ArkField.
2. Hai phương thức sử dụng: Shorthand API & Compound Components
Hai mô hình APILinh hoạt lựa chọn cú pháp 1 dòng tinh gọn cho các form cơ bản hoặc cấu trúc ghép nối linh hoạt để tùy biến DOM chuyên sâu.
Truyền các props như label, helperText, errorText, required trực tiếp vào component.
<ArkField
label="Địa chỉ Email"
required
placeholder="ban@chillcms.vn"
helperText="Chúng tôi không bao giờ chia sẻ email..."
startAdornment={<Mail className="size-4" />}
/>Ghép nối các phần tử con ArkField.Root, ArkField.Label, ArkField.Input, ArkField.HelperText, ArkField.ErrorText.
<ArkField.Root required>
<div className="flex justify-between">
<ArkField.Label>Tên đăng nhập hệ thống</ArkField.Label>
<span className="text-xs">Có thể đổi sau</span>
</div>
<ArkField.Input placeholder="chill_admin" />
<ArkField.HelperText>Chỉ bao gồm chữ thường...</ArkField.HelperText>
</ArkField.Root>3. Hỗ trợ đầy đủ các loại Native Controls
Input • Textarea • SelectArkField hỗ trợ liền mạch các phần tử form gốc của HTML: Text Input, Textarea tự động dãn độ cao (autoresize) và Select dropdown.
1. Native Input
2. Textarea (Autoresize)
3. Native Select
4. Biểu tượng đầu dòng & Hành động tương tác cuối dòng (Adornments)
Start & End AdornmentsDễ dàng chèn icon chỉ dẫn ở đầu ô nhập hoặc các nút thao tác tương tác (Clear, Show/Hide Password) ở cuối ô nhập.
Tìm kiếm với nút Xóa nhanh
Clear ActionMật khẩu với nút Ẩn / Hiện
Toggle Visibility5. Bố cục ngang (Horizontal Layout) cho Trang Cài Đặt
Admin Settings LayoutHỗ trợ thuộc tính orientation='horizontal' tự động chuyển đổi sang dạng grid 3 cột trên màn hình desktop, tiêu chuẩn của các trang Settings/Profile.
6. Multi-control Fields với ArkField.Item & target
Field.Item & TargetKhi một Field chứa nhiều ô nhập liệu (ví dụ: Chọn tiền tệ + Ô nhập số tiền), sử dụng ArkField.Item và target để gán nhãn chính xác vào ô mong muốn.
target="amount-input".7. Tích hợp với các thành phần Ark UI khác (ArkSwitch, ArkPinInput)
Ark UI Ecosystem IntegrationCác thành phần form trong hệ sinh thái Ark UI tự động nhận biết và kế thừa trạng thái disabled, invalid, required khi được đặt trong ArkField.Root.
Tích hợp với ArkSwitch
ArkSwitch in FieldLabel của Field tự động kích hoạt chuyển trạng thái Switch khi người dùng nhấp vào.
Tích hợp với ArkPinInput
ArkPinInput in FieldMã PIN bảo mật kế thừa ngữ cảnh trợ năng và thông báo lỗi tập trung.
8. Form kiểm tra hợp lệ thời gian thực (Real-time Validation Demo)
Form ValidationMẫu form đăng ký hoàn chỉnh kiểm tra logic dữ liệu khi người dùng submit hoặc tương tác, kích hoạt ErrorText linh hoạt.
9. Bảng tra cứu thành phần & Thuộc tính (API Reference)
Reference GuideTổng quan đầy đủ các subcomponents và props được hỗ trợ trong gói ArkField.
| Thành phần (Component) | Anatomy Part | Props bổ sung | Mô tả chức năng |
|---|---|---|---|
| ArkField.Root | root | size, orientation, required, invalid, disabled, readOnly | Container cấp cao quản lý context trợ năng WAI-ARIA cho toàn bộ field. |
| ArkField.Label | label | optional, optionalText, showRequiredIndicator, requiredMark | Nhãn hiển thị, tự động liên kết với control qua id và hỗ trợ indicator bắt buộc/tùy chọn. |
| ArkField.Input | input | size, startAdornment, endAdornment, wrapperClassName | Ô nhập liệu native input bọc sẵn style Tailwind v4 và hỗ trợ icon hai đầu. |
| ArkField.Textarea | textarea | size, autoresize | Ô nhập nhiều dòng với tính năng autoresize tự động chỉnh chiều cao. |
| ArkField.Select | select | size | Menu chọn lựa native select với giao diện đồng bộ hệ thống. |
| ArkField.HelperText | helper-text | size | Văn bản chỉ dẫn phụ, tự động liên kết với control qua aria-describedby. |
| ArkField.ErrorText | error-text | size, icon | Thông báo lỗi màu đỏ tự động hiển thị khi invalid=true, ẩn khi hợp lệ. |
| ArkField.RequiredIndicator | required-indicator | fallback | Dấu hoa thị đỏ (*) hoặc nội dung thay thế hiển thị khi trường là bắt buộc. |
| ArkField.Item | item | value | Phân nhóm ô nhập liệu trong trường hợp một field có nhiều controls. |