PasswordField

Playground

Bấm nút hiện/ẩn thật, đổi autoComplete và ghi chú để xem cùng một PasswordField thích ứng.

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

function Example() {
  const [value, setValue] = useState("");
  return (
    <PasswordField
      label="Mật khẩu"
      value={value}
      onChange={setValue}
      autoComplete="current-password"
    />
  );
}

Bài toán

Một ô mật khẩu che chính thứ người dùng vừa gõ, nên tỉ lệ gõ sai cao và người dùng không có cách nào tự kiểm. Cách chữa đã thành chuẩn là một nút hiện/ẩn, nhưng nút đó cần một <button> thật để đến được bằng bàn phím, cần định vị tuyệt đối trong lòng ô, cần một aria-label đổi theo trạng thái, và cần lật type giữa password và text — tức nó phải sở hữu một mảnh state. Input là một primitive không state và không nên trở thành có state chỉ vì một ca dùng. Chỗ đúng cho nút đó là tầng trên cả Input lẫn Label, và đó cũng là lý do nó không thể là một variant của Field: Field không có state, composite này có.

Khi nào sử dụng

Nên dùng

Mọi ô nhập mật khẩu: đăng nhập, đăng ký, đặt lại mật khẩu, đổi mật khẩu trong trang bảo mật. Khi người dùng cần tự kiểm điều mình vừa gõ trước khi nộp.

Khi nào không dùng

Tránh dùng

Dựng từ

Anatomy

Cạnh nút bằng chiều cao ô là một token dùng hai lần, không phải hai con số tình cờ bằng nhau — nên chữ trong ô không bao giờ chạy xuống dưới nút.

States

Nút được focus: viền tiêu điểm vẽ vào trong (outline-offset âm) vì nút dính mép ô. Trạng thái hiện/ẩn không đặt lại khi value đổi. Hover, disabled của ô: kế thừa từ Input.

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

Seam — host sở hữu gì

PasswordField không đo độ mạnh mật khẩu, không áp luật độ dài, không so khớp hai ô, không nộp gì. Theo ADR-UI-003 clause 2 nó không fetch, không đọc router, không giữ session, không import gì từ next. Clause 6 cấm cụ thể hơn: dấu vân mật khẩu mô phỏng của bộ kit không được port, nên bất kỳ chỉ báo độ mạnh nào cũng phải là quyết định mới, không phải một thứ lặng lẽ xuất hiện ở đây.

Trạng thái duy nhất composite tự giữ là hiện/ẩn — trạng thái trình bày, cố ý không lộ ra API: không có prop defaultVisible.

API & triển khai

Design tokens

PasswordField đọc --nf-component-auth-field-gap cho khoảng cách dọc, --nf-component-field-height cho cạnh nút hiện/ẩn và padding-right của ô, --nf-component-focus-width / -focus-color cho viền tiêu điểm của nút, --nf-semantic-text-muted cho màu icon và gợi ý, --nf-semantic-status-danger-foreground cho màu lỗi. Cùng lỗ hổng đặt tên component.auth.fieldGap đã ghi ở Field, theo dõi bằng dòng ledger W10.19, áp cho cả trang này.

Do / Don't