Keyboard and type-ahead
The tree's keys follow the WAI-ARIA APG tree view, with type-ahead, rename and a keyboard drag. Every binding is an action you can rebind.
The engine handles the keys on the tree, following the WAI-ARIA Authoring Practices tree view
pattern; adapters never hard-code a key. The tree is one stop in the page's tab order (the roving
tab stop), and every binding can be changed with the root's keyMap.
The default keys
DEFAULT_KEY_MAP maps each action to its keys:
| action | keys | does |
|---|---|---|
"focus-next" | ArrowDown | the next visible item |
"focus-previous" | ArrowUp | the previous visible item |
"focus-first" | Home | the first visible item |
"focus-last" | End | the last visible item |
"focus-page-down" | PageDown | the item a view's worth of rows down, in a virtualized tree; otherwise the key scrolls as usual |
"focus-page-up" | PageUp | the item a view's worth of rows up, in a virtualized tree; otherwise the key scrolls as usual |
"expand-or-focus-child" | ArrowRight | expands a collapsed parent, else focuses its first child |
"collapse-or-focus-parent" | ArrowLeft | collapses an expanded parent, else focuses the parent |
"expand-siblings" | * | expands the focused item's siblings |
"select" | Enter | selects the focused item (selection()) |
"toggle" | Space | toggles its selection (multiple), selects it (single), or toggles its check with checkboxes() when the tree has no selection() (or with checkboxes({ space: "check" })) |
"toggle-selection" | Ctrl/Cmd + Space | toggles its selection without moving |
"extend-next" | Shift + ArrowDown | moves down and extends the selection |
"extend-previous" | Shift + ArrowUp | moves up and extends the selection |
"extend-to-focused" | Shift + Space | extends from the anchor to the focused item |
"extend-to-first" | Ctrl/Cmd + Shift + Home | extends to the first visible item |
"extend-to-last" | Ctrl/Cmd + Shift + End | extends to the last visible item |
"select-all" | Ctrl/Cmd + A | selects every visible item |
"rename" | F2 | starts renaming the focused item (rename()) |
"start-drag" | Ctrl/Cmd + Shift + D | starts a keyboard drag of the selection, or of the focused item |
In a right-to-left tree, ArrowRight and ArrowLeft swap (Right-to-left trees).
Type-ahead
Type-ahead is an opt-in feature: typeAhead(), from @fragiola/tree/type-ahead (every adapter's
/type-ahead entry); a tree without it leaves typed characters alone. Installed, typing a
printable character focuses the next visible item whose label starts with it, ignoring case;
characters typed within typeAhead({ timeout }) milliseconds (default 500) extend one search
("re" finds "README.md"). The model answers the same question with no screen:
model.get("type-ahead-match", { text: "re", fromItemId: "app" });Changing a binding
keyMap takes, per action, the full list of its keys, over the defaults. A key is a
KeyboardEvent.key value with its modifiers ("Shift+ArrowDown", "Control+a", " " for
Space); letters ignore case. An empty list turns an action off:
import { type KeyMap, Tree } from "@fragiola/tree-react";
const keyMap: Partial<KeyMap> = {
rename: ["F2", "Enter"], // Enter renames, as in Finder
select: [],
"start-drag": ["Alt+m"],
};
<Tree.Root<Types> defaultTree={json} keyMap={keyMap} aria-label="Files">
<Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
</Tree.Root>;The keyboard drag
"start-drag" picks up the selection (or the focused item). Then ArrowDown and ArrowUp step
through the drop targets the model accepts, Enter drops (one item.move) and Escape cancels. The
live region tells a screen reader where the drop would go, in your words:
Drag and drop.
Keys of your own
The root's onKeyDown (@keydown in Vue, (keydown) in Angular) runs after the engine's handler; a key the engine used has its default
prevented (event.defaultPrevented). Add a shortcut the tree does not use:
const [model] = useState(() => createTreeModel<Types>(json));
<Tree.Root<Types>
model={model}
aria-label="Files"
onKeyDown={(event) => {
if (event.key === "Delete" && !event.defaultPrevented) {
model.run("item.remove", { itemIds: [...model.state.selectedItemIds] });
}
}}
>
<Tree.Items<Types>>{(item) => <FileItem item={item} />}</Tree.Items>
</Tree.Root>;Focus
Tab moves into the tree onto its focused item (or the first selected, or the first visible
item), and out of it in one step. engine.run("focus", { itemId }) moves DOM focus from code.