Checkboxes
Tri-state checks for permission pickers and filters - checks that cascade to children and back up as mixed parents, with a check control of your own.
Checks are an opt-in feature: checkboxes(), from @fragiola/tree/checkboxes (re-exported by
every adapter's /checkboxes entry). A tree that never imports it does not ship it. Installed, it
holds the checks in the model (state.checkedItemIds), puts aria-checked on every item (mixed
included), makes Space toggle the focused item's check (when the tree has no selection(), or with
checkboxes({ space: "check" })), and gives each item its check state (checked, indeterminate,
checkState, and data-checked / data-indeterminate). The box is yours: any control that reads
that state and runs item.toggle-check. The package renders none. What a check means (a scope to
grant, a filter to apply) is yours too.
Turning them on
import { type ItemOf, Tree, useTree, useTreeItem } from "@fragiola/tree-react";
import { checkboxes } from "@fragiola/tree-react/checkboxes";
const features = [checkboxes()] as const;
function CheckBox({ item }: { item: ItemOf<Types> }) {
const { model } = useTree<Types, typeof features>();
const { state } = useTreeItem(item);
return (
<span
aria-hidden
data-tree-no-drag=""
className="box"
data-checked={state.checked ? "" : undefined}
data-indeterminate={state.indeterminate ? "" : undefined}
onClick={() => model.run("item.toggle-check", { itemId: item.id })}
>
<CheckIcon className="check" aria-hidden />
<MinusIcon className="dash" aria-hidden />
</span>
);
}
function PermissionItem({ item }: { item: ItemOf<Types> }) {
return (
<Tree.Item item={item}>
<Tree.ItemContent className="row">
<Tree.Toggle>▸</Tree.Toggle>
<CheckBox item={item} />
<span>{item.label}</span>
</Tree.ItemContent>
<Tree.Group<Types>>{(child) => <PermissionItem item={child} />}</Tree.Group>
</Tree.Item>
);
}
export function Permissions() {
return (
<Tree.Root<Types, typeof features>
defaultTree={json}
features={features}
aria-label="Permissions"
>
<Tree.Items<Types>>{(item) => <PermissionItem item={item} />}</Tree.Items>
</Tree.Root>
);
}.box .check,
.box .dash {
display: none;
}
.box[data-checked] .check,
.box[data-indeterminate] .dash {
display: block;
}In Vue, tree.ts holds features = [checkboxes()] as const (from @fragiola/tree-vue/checkboxes)
and Tree = typedTree<Types, typeof features>(). A press on the box toggles the check
(item.toggle-check); a press on the rest of the row still selects (with selection()). The item carries aria-checked (true, false or "mixed"), and Space acts on it, so
the box is an element that never takes focus, hidden from assistive technology (aria-hidden): a
screen reader reads the item, not a second checkbox inside it, and a press focuses the item, so the
arrows keep working. data-tree-no-drag keeps a press on it from starting a drag or a selection.
A button would take focus when clicked and keep the tree's keys to itself.
Cascade or independent
settings.checkMode is "cascade" (the default) or "independent":
- cascade: checking a parent checks its descendants; a parent is checked when all its
children are, and mixed when only some of its descendants are. Children loaded later
inherit a checked parent. A mixed parent is never stored:
model.get("check-state-by", { itemId })computes it, andcheckedItemIdsholds the fully checked items only. - independent: each item is checked on its own (a filter where a category and its entries mean different things).
model.run("tree.configure", { settings: { checkMode: "independent" } });From code
model.run("item.check", { itemId: "billing", checked: true });
model.run("item.toggle-check", { itemId: "billing.read" });
model.get("check-state-by", { itemId: "billing" }); // "checked" | "unchecked" | "mixed"
model.is("item-checked", { itemId: "billing" });A disabled item cannot be checked or unchecked.
Reading what is checked
In cascade mode, checkedItemIds lists parents and their children alike. Keep what your app
saves, here the leaves' data:
const scopes = useTreeState<Types, string>(
(state) =>
state.checkedItemIds
.flatMap((itemId) => {
const item = state.items[itemId];
return item?.kind === "permission" ? [item.data.scope] : [];
})
.join(" "),
{ model },
);The selector returns a string so that Object.is sees an unchanged selection as equal; pass
isEqual to compare arrays instead. To keep the checks in your app's state, control
checkedItemIds on the root (with onCheckedItemIdsChange in React, v-model:checked-item-ids
in Vue, [(checkedItemIds)] in Angular: Controlled state).
Inline rename
Edit an item's label in place with your own input and useTreeItemRename, validate the name with middleware, and show why it was refused.
Controlled state
Own the expanded, selected and checked items in your app state, decide what each change becomes, and keep the tree in step with your app.