Documentation
Guides

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>}
Inline rename
Gallery