The model and commands
The tree is a typed, immutable state that only commands change. Run them, ask whether they would succeed, read the state and listen to every commit.
A tree model (createTreeModel<Types>(json)) holds the whole tree: its items, what is expanded,
selected, checked and focused, and its settings. The state is plain, frozen, JSON-shaped data, and
only commands change it. Every member of the model is one verb:
| verb | does |
|---|---|
model.run(command, payload) | changes the tree: runs a command, typed, through the middleware chain |
model.dispatch(input) | run for untrusted JSON { command, payload }, validated first |
model.can(command, payload) | whether run would succeed now; nothing changes |
model.check(command, payload) | what run would return (its value, or why it is refused); nothing changes |
model.get(key, payload) | reads: an item, its parent, the visible items, the document |
model.is(key, payload) | asks a yes/no question: is this item expanded, selected, movable? |
model.use(middleware) | adds a middleware around every command |
model.subscribe(listener) | listens to every committed command |
Running a command
A command has a dotted name and a JSON payload. A field that holds an id says so (itemId,
itemIds, parentItemId), and a key and its payload read as one sentence:
import { createTreeModel } from "@fragiola/tree-react";
const model = createTreeModel<Types>(json);
model.run("item.expand", { itemId: "src" });
model.run("item.select", { itemId: "app", mode: "toggle" });
model.run("item.move", { itemIds: ["readme"], to: { parentItemId: "src", index: 0 } });
const result = model.run("item.rename", { itemId: "app", label: "" });
if (!result.ok) console.log(result.error.code); // "invalid_payload": a label is never emptyrun never throws on bad input: it returns { ok: true, value } or { ok: false, error },
with an error code (not_found, refused, invalid_payload, vetoed, …) and a message.
The 27 commands are on Commands.
Asking before acting
The rules (a disabled item, an item that is not movable, a folder that is not droppable, the
selection mode) are enforced by the commands themselves, so can and check answer exactly what
run would do, middleware included. Ask them to decide what to render:
function DeleteButton({ itemId }: { itemId: string }) {
const { model } = useTree<Types>();
if (!model.can("item.remove", { itemIds: [itemId] })) return null;
return (
<button type="button" onClick={() => model.run("item.remove", { itemIds: [itemId] })}>
Delete
</button>
);
}A drag asks the same question: the engine runs model.can("item.move", …) for every drop target,
and a refused one never shows.
Reading the state
model.state is the current state (a new object after every change). model.get and model.is
read it through named keys; a key that takes an id ends in -by:
model.get("item-by", { id: "app" }); // the item, or undefined
model.get("item-parent-by", { itemId: "app" }); // its parent
model.get("visible-items"); // the render order, with level, posinset and setsize
model.get("tree-json"); // the document, ready to save
model.is("item-expanded", { itemId: "src" });
model.is("item-movable", { itemId: "license" });In a component, useTreeState (injectTreeState in Angular) selects a value and re-renders only
when it changes
(Hooks). Every key is on Model.
Middleware and listeners
A middleware runs around every command, whoever issued it (a key, a click, a drop, your code, an assistant): it can veto it, rewrite its payload, or observe its result. A listener sees each commit once, with the state before and after:
import { veto } from "@fragiola/tree-react";
model.use((ctx, next) =>
ctx.command === "item.remove" && ctx.payload.itemIds.includes("readme")
? veto("The README stays.")
: next(),
);
model.subscribe((event) => {
console.log(event.command, event.before === event.after ? "no change" : "changed");
});ctx.command narrows ctx.payload. See Middleware and permissions and
The command bus.
Structural sharing
A command produces a new state that shares every item it did not touch: after
item.rename on app, after.items.readme === before.items.readme. A state that did not change
is the same object (before === after), which makes change detection, memoization and undo
cheap.
Styling the depth
Indent rows with the --tree-depth custom property every part carries, and keep the drop indicator's level in line with your indentation.
Model and engine
The model holds what is true with no screen; the engine is one tree on screen. Here is which state lives where, and why it matters.