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.
Renaming is an opt-in feature: rename(), from @fragiola/tree/rename (re-exported, with the
part hook, by every adapter's /rename entry). A tree that never imports it does not ship it, and
its labels change only through a new document. Installed, renaming is a short-lived model state:
item.start-rename (F2 on the focused item) makes an
item the renaming item, item.rename sets its label and ends it, item.cancel-rename ends it
unchanged. The text field is yours: useTreeItemRename(item) gives it the editing behaviour, and
you render it only while the item is renaming. The rules for a good name are yours too.
The input
Put it in the row, next to (or instead of) the label, and name it:
import { type ItemOf, Tree } from "@fragiola/tree-react";
import { rename, useTreeItemRename } from "@fragiola/tree-react/rename";
// in the model's features: createTreeModel(json, { features: [rename()] })
function FileItem({ item }: { item: ItemOf<Types> }) {
const rename = useTreeItemRename(item);
return (
<Tree.Item item={item}>
<Tree.ItemContent className="row">
<Tree.Toggle>▸</Tree.Toggle>
<span className="label">{item.label}</span>
{rename.state.renaming && (
<input {...rename.props} aria-label={`Rename ${item.label}`} className="rename" />
)}
</Tree.ItemContent>
<Tree.Group<Types>>{(child) => <FileItem item={child} />}</Tree.Group>
</Tree.Item>
);
}.row[data-renaming] .label {
display: none;
}It opens with the label, focused and selected. Enter commits and Escape cancels, and focus goes back to the item. Leaving the field commits (or cancels, when the name is refused) and leaves focus where it went. The hook adds no part attribute: the element and its look are yours.
By hand
The hook is a convenience over two engine actions. Wire your own editor with them when you need
another element (a contenteditable, a combobox). A native input or textarea and a
contenteditable keep their own keys. Any other editor needs data-tree-no-drag, or the tree's
arrows, Space and type-ahead act while you type:
const { engine } = useTree<Types>();
// Enter: the label is committed (`item.rename`), then focus goes back to the item
engine.run("commit-rename", { itemId: item.id, label: value });
// Escape
engine.run("cancel-rename", { itemId: item.id });
// a blur: focus stays where it went
engine.run("commit-rename", { itemId: item.id, label: value, focus: false });A refused commit returns the command's failure ({ ok: false, error }) and the item keeps
renaming; engine.check("commit-rename", …) answers why without committing.
Starting a rename
F2 renames the focused item (rebind it with keyMap.rename). From a button, a menu or a double
click, run the command:
const { model } = useTree<Types>();
<Tree.ItemContent onDoubleClick={() => model.run("item.start-rename", { itemId: item.id })}>
{item.label}
</Tree.ItemContent>;It is refused for a disabled item and for one that is not renamable (on the item, or
settings.renamable for all of them).
Validating the name
The label is never empty (the command's schema). Every other rule is a middleware, which sees
each item.rename, from the input or from code, and can veto it or rewrite its payload:
import { veto } from "@fragiola/tree-react";
model.use((ctx, next) => {
if (ctx.command !== "item.rename") return next();
const label = ctx.payload.label.trim();
if (label.includes("/")) return veto("A name cannot contain “/”.");
const parent = ctx.get("item-parent-by", { itemId: ctx.payload.itemId });
const siblingIds = parent ? (parent.childItemIds ?? []) : ctx.state.rootItemIds;
const taken = siblingIds.some(
(id) => id !== ctx.payload.itemId && ctx.get("item-by", { id })?.label === label,
);
if (taken) return veto(`“${label}” is already in this folder.`);
ctx.payload = { ...ctx.payload, label }; // save the trimmed name
return next();
});Showing why
A refused commit keeps the input open with aria-invalid and data-invalid, and calls
onRenameError (an option of the hook; (renameError) in Angular) with the error. The hook's
state has invalid and error:
const [error, setError] = useState<string>();
const rename = useTreeItemRename(item, {
onRenameError: (failure) => setError(failure.message),
});
{rename.state.renaming && (
<input
{...rename.props}
aria-label={`Rename ${item.label}`}
aria-describedby={error ? errorId : undefined}
className={rename.state.invalid ? "rename rename-invalid" : "rename"}
onChange={(event) => {
rename.props.onChange?.(event);
setError(undefined);
}}
/>
)}
{error && <span id={errorId} role="alert">{error}</span>}Async loading
Load a parent's children the first time it is expanded, show the loading and error states, retry a failed load and refresh loaded children.
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.