useOptimisticList

Cập nhật lạc quan cho danh sách: giao diện đổi ngay khi bấm, gửi lên server phía sau; thất bại thì hoàn tác đúng thay đổi đó và báo bằng toast.

mutate(update, commit, options) áp update lên danh sách ngay, chờ commit(); thành công thì gộp vào dữ liệu gốc, thất bại thì gỡ riêng thay đổi đó — các thay đổi khác đang chờ vẫn giữ — rồi hiện toast lỗi (không tự đóng) có nút Thử lại. update phải là hàm thuần dựa trên id vì nó được áp lại lên dữ liệu mới nhất. Trả về true / false để xử lý tiếp (vd. trả lại nội dung cho ô nhập).

Mọi thay đổi đã được lưu

Duyệt thiết kế trang chủ
Viết tài liệu Wait UX
Chuẩn bị demo thứ Sáu

Import

Cài từ npm, chép mã nguồn vào dự án bằng @yugen-ui/cli hoặc shadcn CLI, hoặc import thẳng khi làm việc trong repo này.

TSX

// npm install yugen-uiimport { useOptimisticList } from "yugen-ui";

Biến thể

Mỗi ô là một mẫu độc lập: hover để Copy, hoặc bấm Code để xem mã nguồn.

Chờ server

Lạc quan

Chờ server và lạc quan

Với mạng chậm, nút bên trái quay 2 giây; nút bên phải đổi ngay và chỉ quay về khi lỗi.

Màu hồng này đẹp quá!
Năm nay hoa nở sớm hơn mọi năm.

Thêm mục và trả lại nội dung khi lỗi

mutate trả về false khi thất bại — đưa bình luận lại vào ô nhập để người dùng không mất chữ.

Cách dùng

Nên

Dùng cho thao tác gần như luôn thành công và dễ hoàn tác: thích, tích việc, sắp xếp, đổi tên.
Viết update theo id, không theo vị trí.
Báo lỗi rõ ràng khi hoàn tác và cho thử lại.

Không nên

Không dùng cho thanh toán, xoá vĩnh viễn hay thao tác không hoàn tác được — hãy chờ server.
Không lặng lẽ hoàn tác mà không báo.
Không khoá cả danh sách trong lúc chờ — đó là việc của cách làm bi quan.

Props

Prop · Kiểu	Mặc định	Mô tả
useOptimisticList(initial)T[] \| () => T[]	Mặc định: —	Dữ liệu ban đầu (đã xác nhận).
itemsT[]	Mặc định: —	Dữ liệu gốc + mọi thay đổi đang chờ.
mutate(update, commit, options?)(T[] => T[], () => Promise, OptimisticOptions) => Promise<boolean>	Mặc định: —	Áp update ngay, chờ commit; true khi thành công.
options.errorTitle / errorBodyReactNode	Mặc định: "Couldn't save changes"	Nội dung toast khi thất bại.
options.toast / onErrorboolean · (error) => void	Mặc định: true	Tắt toast mặc định / tự xử lý lỗi.
setItemsDispatch<SetStateAction<T[]>>	Mặc định: —	Thay dữ liệu gốc (vd. sau khi tải lại từ server).
pendingboolean	Mặc định: —	Còn thay đổi đang chờ — kết hợp useSpinDelay cho dòng “Đang lưu…”.

Messages

Chữ có sẵn của component: nhãn, aria-label, thông báo cho trình đọc màn hình.

Mặc định là tiếng Anh. Đổi qua prop messages của YugenProvider, theo namespace bên dưới; messagesVi chứa bản tiếng Việt. Xem Ngôn ngữ giao diện.

messages.optimisticList

Khoá · Kiểu	Mặc định (tiếng Anh)	messagesVi
errorTitlestring	Mặc định (tiếng Anh)`"Couldn't save changes"`	messagesVi`"Không lưu được thay đổi"`
errorBodystring	Mặc định (tiếng Anh)`"Your changes were undone."`	messagesVi`"Thay đổi đã được hoàn tác."`
retrystring Nút trong toast.	Mặc định (tiếng Anh)`"Retry"`	messagesVi`"Thử lại"`
retryAltTextstring Mô tả thay thế của nút (cho trình đọc màn hình).	Mặc định (tiếng Anh)`"Retry the last action"`	messagesVi`"Thực hiện lại thao tác vừa rồi"`