Combobox

Playground

Gõ để lọc trong hai mươi khách hàng, dùng mũi tên để đổi dòng hoạt động, Enter để chốt. Bật "Đang tải" để xem danh sách cũ bị thay hoàn toàn bằng nhãn đang tải -- không hiện cả hai cùng lúc. Gõ một chuỗi không khớp ai để xem danh sách rỗng.

import { Combobox } from "@nexobox/ui";

function Example() {
  const [query, setQuery] = useState("");
  const [value, setValue] = useState<string | null>(null);
  const options = customers.filter((c) =>
    c.label.toLocaleLowerCase("vi").includes(query.trim().toLocaleLowerCase("vi")),
  );
  return (
    <Combobox
      label="Khách hàng"
      options={options}
      value={value}
      onValueChange={setValue}
      query={query}
      onQueryChange={setQuery}
      emptyLabel="Không tìm thấy khách hàng nào."
    />
  );
}

Bài toán

Khi một ô nhập phải chọn từ một tập lớn hoặc chưa biết trước — một khách hàng trong mười nghìn, một nhân sự, một kênh — cả hai control có sẵn đều sai. Select buộc toàn bộ tuỳ chọn có mặt sẵn và không cho gõ để thu hẹp, nên vô dụng ở quy mô đó và không dùng được với dữ liệu lấy từ server. Input cho gõ nhưng không gợi ý gì. Việc còn lại — một ô nhập chữ cộng một danh sách gợi ý điều hướng được bằng bàn phím, trong đó tiêu điểm nằm ở ô và danh sách chỉ được trỏ tới — không thuộc về primitive nào: Input không biết có một danh sách, Popover không biết nội dung nó mở ra là một listbox, và không primitive nào được phép giữ aria-activedescendant của một cái khác.

Khi nào sử dụng

Nên dùng

Chọn một giá trị từ một tập lớn, nơi gõ để thu hẹp là cách tìm chính. Tập tuỳ chọn đến từ server, thay đổi theo từng lần gõ, hoặc dài tới mức một danh sách phẳng không đọc được. Khi người dùng có thể biết tên thứ mình cần nhưng không biết nó nằm ở đâu trong danh sách.

Khi nào không dùng

Tránh dùng

Dựng từ

Ba primitive là nhiều nhất trong tầng 2 — sáu composite kia dùng không quá hai.

Anatomy

PopoverContent bọc Portal, nên listbox render vào <body>, không nằm cạnh ô — aria-controls và aria-activedescendant vẫn giải quyết được vì IDREF có phạm vi toàn document. Popover giữ modal ở mặc định false: một popover modal sẽ aria-hidden phần còn lại của trang, tức cả ô đang giữ tiêu điểm.

States

Năm trạng thái mở của bảng contract — có tuỳ chọn, một tuỳ chọn đang hoạt động, tuỳ chọn đã chọn nằm trong danh sách, rỗng và đang tải — đòi danh sách thật sự mở, và danh sách chỉ tồn tại khi open === true. Dùng Playground ở trên để mở: gõ để thấy danh sách có tuỳ chọn, mũi tên để thấy dòng hoạt động (nền --nf-component-menu-item-hover, aria-activedescendant trỏ vào nó), chọn một khách hàng rồi mở lại để thấy dòng đó mang aria-selected="true", gõ một chuỗi không khớp ai để thấy danh sách rỗng, và bật "Đang tải" để thấy danh sách cũ bị thay hoàn toàn bằng loadingLabel — không bao giờ hiện cả hai cùng lúc.

Bàn phím & trợ năng

Seam — host sở hữu gì

Combobox không lọc, không gọi gì, không debounce, không biết options từ đâu ra. Theo ADR-UI-003 clause 2 nó không fetch, không đọc router, không giữ session, không import gì từ next.

Trang này lọc ở host, đúng như bảng trên đòi hỏi: filterCustomers chạy toLocaleLowerCase("vi") rồi includes trên toàn bộ hai mươi khách hàng, cùng idiom với filterNavSections của thanh điều hướng trang này. Trạng thái duy nhất Combobox tự giữ là open và activeIndex.

API & triển khai

Design tokens

Combobox đọc --nf-component-auth-field-gap cho khoảng dọc, --nf-component-menu-radius và --nf-component-menu-padding cho hộp danh sách, --nf-component-menu-item-padding-inline, -item-padding-block, -item-gap cho một dòng, --nf-component-field-radius và --nf-component-menu-item-height — cùng token SelectItem và DropdownMenuItem dùng, 36 px comfortable / 32 px compact / 44 px con trỏ thô, rời khỏi thang hàng bảng cũ (48 px) theo DS-017 clause 8. Dòng hoạt động đọc --nf-component-menu-item-hover; giữ chuột xuống đọc --nf-component-menu-item-pressed, không co scale. --nf-semantic-text-muted cho description/gợi ý/emptyLabel, --nf-semantic-status-danger-foreground cho lỗi, và cặp --nf-motion-menu-in / -menu-out cho hộp danh sách. Một xung đột hình học, ghi ra thay vì che: PopoverContent mặc định bind component.panel.radius (16) và component.popover.padding; một danh sách tuỳ chọn là một menu, không phải một panel nội dung tự do (DS-015 clause 4), nên Combobox truyền className ghi đè bán kính và đệm sang bậc menu, cộng cặp presence menu-in/menu-out thay popover-in/popover-out. Đây là lần ghi đè được cho phép và đã ghi sổ, không phải một chỗ trôi — bản sửa đúng (một knob bề mặt trên Popover) là dòng ledger W10.26, ngoài phạm vi trang này.

Do / Don't