Select

Select Component Generation Skill

Skill này hướng dẫn bạn (AI Agent) tạo component Select / Dropdown — cho phép user chọn một (hoặc nhiều) giá trị từ danh sách predefined.

1. Mục tiêu (Objective)

Tạo component Select hoàn chỉnh, hỗ trợ single/multi select, searchable, grouped options, và tích hợp 100% Design Tokens. Có thể dùng native <select> hoặc custom dropdown tuỳ yêu cầu.

2. AI Context & Intent (Ngữ cảnh cho AI)

Khi nào dùng Select?

• Chọn từ danh sách có sẵn: quốc gia, loại tài khoản, danh mục
• Danh sách > 5 options: nếu ≤ 5, cân nhắc Radio (single) hoặc Checkbox (multi)
• Không cần user tự nhập giá trị mới

Phân biệt với component khác

Decision Tree cho AI

User cần chọn từ danh sách?
├─ Single selection
│   ├─ > 5 options → Select
│   └─ ≤ 5 options → Radio Group
├─ Multi selection
│   ├─ > 5 options → Select (multi)
│   └─ ≤ 5 options → Checkbox Group
├─ Cần search/filter trong list → Select (searchable) hoặc Combobox
└─ Chỉ 2 trạng thái (on/off) → Switch

3. Ngữ nghĩa & Phân loại (Semantics)

3.1. Default Select (Single)

• Mục đích: Chọn 1 giá trị từ dropdown.
• Đặc điểm: Trigger button hiển thị giá trị hiện tại, mở dropdown panel khi click.
• Tương đồng: Exposed Dropdown Menu (Material 3), Picker (iOS).

3.2. Multi Select

• Mục đích: Chọn nhiều giá trị, hiển thị dạng chips/tags.
• Đặc điểm: Checkbox trong mỗi option, chips hiển thị các giá trị đã chọn.

3.3. Searchable Select

• Mục đích: Danh sách rất dài (> 20 items), cần tìm kiếm nhanh.
• Đặc điểm: Input field tích hợp trong dropdown để filter.

3.4. Grouped Select

• Mục đích: Options được phân nhóm theo danh mục.
• Đặc điểm: <optgroup> hoặc section headers trong custom dropdown.

3.5. States

3.5. Slot Map (Figma ↔ Code)

📎 Source: slot-manifest.json → select · Layer: item

4. Token Mapping

📦 Token values: Xem ATOMIC-MAPPING.md — single source of truth cho tất cả actual token values.

5. Props & API

interface SelectProps {
  /** Single or multi select */
  mode?: 'single' | 'multiple';
  /** Options list */
  options: SelectOption[];
  /** Placeholder khi chưa chọn */
  placeholder?: string;
  /** Label */
  label?: string;
  /** Enable search/filter */
  searchable?: boolean;
  /** Size */
  size?: 'sm' | 'md' | 'lg';
  /** Error message */
  errorMessage?: string;
  /** Helper text */
  helperText?: string;
  /** Disabled */
  disabled?: boolean;
  /** Full width */
  fullWidth?: boolean;
  /** Clearable — cho phép xoá selection */
  clearable?: boolean;
}

interface SelectOption {
  value: string;
  label: string;
  disabled?: boolean;
  group?: string; // Tên nhóm
}

6. Accessibility (a11y)

• ARIA: Trigger phải có role="combobox", aria-expanded, aria-haspopup="listbox".
• Listbox: Dropdown panel phải có role="listbox", mỗi option role="option".
• Keyboard: Enter/Space mở dropdown, Arrow Up/Down di chuyển focus, Escape đóng, Enter chọn.
• Multi select: Option selected phải có aria-selected="true".
• Searchable: Input tìm kiếm có aria-autocomplete="list".
• Label: Liên kết qua aria-labelledby.
• Focus trap: Focus phải ở trong dropdown khi mở, trả lại trigger khi đóng.

7. Best Practices & Rules

• Native fallback: Với form đơn giản hoặc mobile, ưu tiên <select> native.
• Custom dropdown: Khi cần searchable, multi, grouped — dùng custom component.
• Z-index: Dropdown panel phải có z-index cao hơn surrounding content.
• Portal: Render dropdown qua Portal để tránh overflow hidden issues.
• Không Hardcode: Mọi giá trị từ Token.
• Icon: Dropdown arrow (chevron-down), check icon (check), clear icon (x) CHỈ dùng Lucide icon từ assets/icons/. CẤM dùng text emoji. Xem icon.md mục 10.
• Max height: Dropdown panel nên có max-height + scroll khi > 8 items.

8. Example Usage

{/* Basic single */}
<Select
  label="Quốc gia"
  placeholder="Chọn quốc gia"
  options={[
    { value: 'vn', label: 'Việt Nam' },
    { value: 'us', label: 'United States' },
    { value: 'jp', label: 'Japan' },
  ]}
/>

{/* Multi select with search */}
<Select
  mode="multiple"
  searchable
  label="Kỹ năng"
  placeholder="Chọn kỹ năng..."
  options={skills}
/>

{/* Grouped */}
<Select
  label="Sản phẩm"
  options={[
    { value: 'visa', label: 'Visa', group: 'Thẻ quốc tế' },
    { value: 'master', label: 'Mastercard', group: 'Thẻ quốc tế' },
    { value: 'napas', label: 'Napas', group: 'Thẻ nội địa' },
  ]}
/>