Yugen UI

Focus management

useArrowNavigationGroup và useFocusableGroup quản lý focus bằng bàn phím cho nhóm phần tử, như Tabster của Fluent.

useArrowNavigationGroup: roving tabindex — Tab vào/ra nhóm một lần, mũi tên di chuyển giữa các phần tử (axis horizontal / vertical / both / grid), Home/End tới đầu/cuối, circular quay vòng, memorizeCurrent nhớ vị trí; ←/→ tự đảo trong RTL. useFocusableGroup: biến phần tử chứa thành một điểm dừng Tab — Enter để vào trong, Esc để ra; kết hợp hai hook để điều hướng giữa các thẻ. Trải toàn bộ kết quả hook lên phần tử chứa.

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 { useArrowNavigationGroup, useFocusableGroup } 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.

Lưới (grid) & memorizeCurrent

↑/↓ đi theo cột thị giác, ←/→ theo thứ tự; Tab ra rồi vào lại sẽ về ô vừa rời.

Dọc, quay vòng

axis="vertical" + circular: ↓ ở mục cuối quay về mục đầu.

Ra mắt Yugen UI
Bảng màu Sakura

useFocusableGroup trong nhóm mũi tên

←/→ giữa các thẻ; Enter vào trong thẻ, Tab xoay vòng giữa các nút (limited-trap-focus), Esc trở lại thẻ.

Cách dùng

Nên
  • Dùng arrow navigation cho toolbar, danh sách, lưới ô — mọi nhóm có nhiều phần tử cùng loại.
  • Đặt role và aria-label phù hợp trên phần tử chứa (toolbar, group, list).
  • Kết hợp useFocusableGroup cho thẻ có nhiều nút bên trong.
Không nên
  • Không bọc ô nhập văn bản trong nhóm mũi tên (mũi tên dành cho con trỏ).
  • Không tự đặt tabIndex cho phần tử con — hook đã quản lý roving tabindex.

Props

Prop · KiểuMặc địnhMô tả
axis"horizontal" | "vertical" | "both" | "grid"Mặc định: "vertical"Phím mũi tên được dùng.
circularbooleanMặc định: falseQuay vòng ở hai đầu.
memorizeCurrentbooleanMặc định: falseTab quay lại nhóm về phần tử focus gần nhất.
tabbablebooleanMặc định: falseGiữ mọi phần tử trong thứ tự Tab (tắt roving tabindex).
roleAriaRoleMặc định: —Trả kèm role trong object props.
useFocusableGroup({ tabBehavior })"limited" | "limited-trap-focus" | "unlimited"Mặc định: "limited"limited: Enter vào, Esc ra · trap: Tab xoay vòng bên trong · unlimited: Tab đi xuyên qua.
(returns){ ref, onKeyDown, onFocus, onBlur, … }Mặc định: —Trải lên phần tử chứa; tự gộp nếu cần thêm handler riêng.