FormError

Playground

Đổi brand, theme và nội dung để xem cùng một FormError thích ứng.

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

{submitFailed ? <FormError>"Sai tài khoản hoặc mật khẩu."</FormError> : null}

Bài toán

Khi một lần nộp biểu mẫu thất bại vì lý do không thuộc một field nào — sai thông tin đăng nhập, phiên hết hạn, máy chủ từ chối — thì không có ô nào để gắn lỗi vào. Lỗi ấy phải xuất hiện ở đầu biểu mẫu, phải được thông báo ngay chứ không đợi người dùng tự cuộn lên, và nó phải trông thuộc về biểu mẫu chứ không nổi lên như một thẻ riêng. Một primitive không giải được vì đây là ba quyết định ghép: vai trò aria (alert, không status), hình học bám field (bán kính ô, viền subtle), và một icon cảnh báo cố định. Alert tồn tại nhưng mang hình học của thẻ chứ không của field — xem mục kế tiếp.

Khi nào sử dụng

Nên dùng

Lỗi ở mức biểu mẫu, đặt ngay trước field đầu tiên hoặc ngay trên nút nộp. Lỗi phải được thông báo ngay khi xuất hiện: đăng nhập sai, mã hết hạn, hành động bị từ chối. Một dòng, một câu — composite này không có tiêu đề riêng và không có nút đóng.

Khi nào không dùng

Tránh dùng

Vì sao FormError chưa thu lại thành preset của Alert. Vai trò aria khớp nhau — Alert kind="danger" cũng mặc định role="alert". Viền, bán kính và đệm khác nhau vì một băng nằm trong biểu mẫu nên đồng hình với ô nhập, không với thẻ — vai trò thật. Nhưng FormError còn tự giữ một margin-bottom, và đó không phải vai trò, đó là một khiếm khuyết: một component không nên sở hữu lề ngoài của chính nó. Cách đóng đúng là cho Alert một knob tone="subtle" rồi FormError trở thành một preset mỏng và bỏ lề ngoài — việc đó chạm một primitive đã có consumer nên là quyết định riêng, theo dõi bằng dòng ledger W10.20.

Dựng từ

Đây là một trong hai composite trong tầng không dựng từ một primitive tầng 1 nào, và nó vẫn thuộc tầng 2 theo ADR-UI-005 clause 3: nó có thứ nó thêm mà không primitive nào có (hình học bám field, vai trò aria cố định), và nó không gọi tên khái niệm sản phẩm nào.

Anatomy

Hai phần: icon và chữ. Không tiêu đề, không nút đóng, không vùng hành động.

States

Không hiện: composite không có chế độ ẩn — caller render nó hoặc không. Hover, focus, disabled: không có. Đây không phải control; không có phần nào nhận tiêu điểm. Không có trạng thái "đóng" — băng biến mất khi nội dung sinh ra nó thay đổi, chứ không vì người dùng bấm vào một dấu nhân.

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

Seam — host sở hữu gì

FormError không biết vì sao lần nộp thất bại, không dịch mã lỗi thành câu chữ, không thử lại, và không quyết định khi nào nó nên xuất hiện. Theo ADR-UI-003 clause 2 nó không fetch, không đọc router, không giữ session, không import gì từ next.

Composite không giữ trạng thái nào. Không useState, không useId.

API & triển khai

Design tokens

FormError đọc --nf-component-field-radius, --nf-semantic-status-danger-border-subtle, -background, -foreground, -icon, cộng năm alias component.auth.banner* và component.auth.errorMarginBottom cho đệm, khoảng icon–chữ và lề dưới. Lỗ hổng đặt tên, ghi ra thay vì che: năm alias đó gọi tên "auth" trong khi composite này đã được ADR-UI-005 clause 5 xác định là chung — nhóm đúng là component.formBanner.*, theo dõi bằng dòng ledger W10.19. Cỡ chữ 0.8125rem là số trần trong file, không phải token.

Do / Don't