Commands
Every command the model runs, with its payload and result types and how to run it from code or as JSON. Generated from the registry.
The model runs 27 commands. Each one takes a JSON payload, checked against its JSON Schema, and returns a CommandResult: { ok: true, value }, or { ok: false, error }. Run one with model.run(name, payload) (typed by your registry), or give it as untrusted JSON to model.dispatch({ command, payload }), which validates it first. model.get("commands") returns this same list with the schemas, ready to become tool definitions for an assistant.
Every command can return invalid_payload (the payload does not match its schema, with the path of each problem), vetoed (a middleware refused it), queued (a middleware ran it while another command was running) and middleware_error; each command lists the ones its own rules add: not_found (an item it names is missing) and refused (a rule of the tree refuses the change).
The payload types below use T, your registry: an item's data is checked against its kind.
Expanding and collapsing
item.expand
Expand an item: its children are shown. An item whose children come from the app's loader (childrenStatus unloaded) is expanded at once and the engine loads them. Refused for a leaf or a disabled item.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, refused, besides those every command can return.
model.run("item.expand", {
itemId: "src"
});{ "command": "item.expand", "payload": {"itemId":"src"} }item.collapse
Collapse an item: its children are hidden. When the focused item was inside it, the focus moves to it. Refused for a leaf or a disabled item.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, refused, besides those every command can return.
model.run("item.collapse", {
itemId: "src"
});{ "command": "item.collapse", "payload": {"itemId":"src"} }item.toggle
Expand a collapsed item, or collapse an expanded one. Refused for a leaf or a disabled item.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string; expanded: boolean })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
expanded | boolean | yes | whether the item is now expanded |
Errors: not_found, refused, besides those every command can return.
model.run("item.toggle", {
itemId: "src"
});{ "command": "item.toggle", "payload": {"itemId":"src"} }item.expand-siblings
Expand every parent among an item's siblings, the item included (the WAI-ARIA tree's * key). Leaves and disabled items are left as they are.
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ expandedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
expandedItemIds | string[] | yes | the items this expanded |
Errors: not_found, besides those every command can return.
model.run("item.expand-siblings", {
itemId: "src"
});{ "command": "item.expand-siblings", "payload": {"itemId":"src"} }tree.expand-all
Expand every parent whose children are loaded (or that holds them itself). Parents whose children come from the loader and are not loaded stay collapsed, so expanding all never starts a load storm; disabled items are left as they are.
Payload (NoPayload)
No fields.
Result ({ expandedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
expandedItemIds | string[] | yes | the items this expanded |
Errors: only those every command can return.
model.run("tree.expand-all", {});{ "command": "tree.expand-all", "payload": {} }tree.collapse-all
Collapse every item. The focus moves to the root item it was under.
Payload (NoPayload)
No fields.
Result ({ collapsedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
collapsedItemIds | string[] | yes | the items this collapsed |
Errors: only those every command can return.
model.run("tree.collapse-all", {});{ "command": "tree.collapse-all", "payload": {} }Focus
item.focus
Make an item the tree's focused item: the roving tab stop, the one item with tabindex 0 (moving DOM focus is the engine's focus action). Disabled items can be focused. Refused for an item that is not visible (an ancestor is collapsed).
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, refused, besides those every command can return.
model.run("item.focus", {
itemId: "app"
});{ "command": "item.focus", "payload": {"itemId":"app"} }Selection
These commands come with the selection feature: install selection() from @fragiola/tree/selection (createTreeModel(json, { features: [selection()] })). Without it, each one returns not_found.
item.select
Select an item. mode replace (default) selects it alone and makes it the selection anchor; toggle adds or removes it and makes it the anchor; extend selects the visible items from the anchor to it (multiple mode; in single mode it acts as replace). Disabled items are never selected. Refused when the selection mode is none.
Payload ({ itemId: string; mode?: SelectMode })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
mode | "replace" | "toggle" | "extend" | no | replace (default): the item alone; toggle: added or removed; extend: the visible range from the selection anchor |
Result ({ selectedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
selectedItemIds | string[] | yes | the selection after the command |
Errors: not_found, refused, besides those every command can return.
model.run("item.select", {
itemId: "app",
mode: "extend"
});{ "command": "item.select", "payload": {"itemId":"app","mode":"extend"} }tree.select
Replace the selection with these items (at most one in single mode). Refused when one is disabled, or when the selection mode is none.
Payload ({ itemIds: string[] })
| field | type | required | description |
|---|---|---|---|
itemIds | string[] | yes | the items to select |
Result ({ selectedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
selectedItemIds | string[] | yes | the selection after the command |
Errors: not_found, refused, besides those every command can return.
model.run("tree.select", {
itemIds: [
"app",
"readme"
]
});{ "command": "tree.select", "payload": {"itemIds":["app","readme"]} }tree.select-all
Select every visible item that is not disabled (Ctrl+A). Refused unless the selection mode is multiple.
Payload (NoPayload)
No fields.
Result ({ selectedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
selectedItemIds | string[] | yes | the selection after the command |
Errors: refused, besides those every command can return.
model.run("tree.select-all", {});{ "command": "tree.select-all", "payload": {} }tree.clear-selection
Select nothing: the selection and its anchor are cleared.
Payload (NoPayload)
No fields.
Result ({ selectedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
selectedItemIds | string[] | yes | the selection after the command |
Errors: only those every command can return.
model.run("tree.clear-selection", {});{ "command": "tree.clear-selection", "payload": {} }Checkboxes
These commands come with the checkboxes feature: install checkboxes() from @fragiola/tree/checkboxes (createTreeModel(json, { features: [checkboxes()] })). Without it, each one returns not_found.
item.check
Check or uncheck an item's checkbox. In cascade mode its loaded descendants follow it and its ancestors are recomputed (checked when all their children are, mixed when some are); children loaded later inherit a checked parent. In independent mode only the item changes. Refused for a disabled item.
Payload ({ itemId: string; checked: boolean })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
checked | boolean | yes | true checks it, false unchecks it |
Result ({ checkedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
checkedItemIds | string[] | yes | the checked items after the command |
Errors: not_found, refused, besides those every command can return.
model.run("item.check", {
itemId: "src",
checked: true
});{ "command": "item.check", "payload": {"itemId":"src","checked":true} }item.toggle-check
Toggle an item's checkbox: a checked item is unchecked, an unchecked or mixed one is checked (with the cascade of item.check). Refused for a disabled item.
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string; checked: boolean })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
checked | boolean | yes | whether the item is now checked |
Errors: not_found, refused, besides those every command can return.
model.run("item.toggle-check", {
itemId: "app"
});{ "command": "item.toggle-check", "payload": {"itemId":"app"} }Rename
These commands come with the rename feature: install rename() from @fragiola/tree/rename (createTreeModel(json, { features: [rename()] })). Without it, each one returns not_found.
item.start-rename
Start renaming an item: it becomes the renaming item (the one whose label is edited; any other stops). Refused for an item that is disabled or not renamable.
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, refused, besides those every command can return.
model.run("item.start-rename", {
itemId: "app"
});{ "command": "item.start-rename", "payload": {"itemId":"app"} }item.rename
Set an item's label, and stop renaming it when it was the renaming item. The label is raw model data: the app renders it, the packages never do. Refused for an item that is disabled or not renamable.
Payload ({ itemId: string; label: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
label | string | yes | the new label (not empty) |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, refused, besides those every command can return.
model.run("item.rename", {
itemId: "app",
label: "main.ts"
});{ "command": "item.rename", "payload": {"itemId":"app","label":"main.ts"} }item.cancel-rename
Stop renaming an item without changing its label. Refused when the item is not the renaming item.
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, refused, besides those every command can return.
model.run("item.cancel-rename", {
itemId: "app"
});{ "command": "item.cancel-rename", "payload": {"itemId":"app"} }Async children
These commands come with the async-children feature: install asyncChildren() from @fragiola/tree/async-children (createTreeModel(json, { features: [asyncChildren()] })). Without it, each one returns not_found.
item.set-children-status
Mark the load of an item's children as started (loading) or failed (error). Only for an item whose children come from the loader (it has a childrenStatus); its current children, if any, are removed. The engine runs it around the app's loadChildren.
Payload ({ itemId: string; status: "loading" \| "error" })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
status | "loading" | "error" | yes | loading: the load started; error: it failed |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, refused, besides those every command can return.
model.run("item.set-children-status", {
itemId: "lib",
status: "loading"
});{ "command": "item.set-children-status", "payload": {"itemId":"lib","status":"loading"} }item.set-children
Give an item the children the app's loader returned (each an item JSON, its id generated when omitted; a child that has children of its own gets a childrenStatus and loads them later). They replace any current children, and the status becomes loaded. In cascade mode they inherit a checked parent. Only for an item whose children come from the loader.
Payload ({ itemId: string; items: TreeItemJson<T>[] })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
items | object[] | yes | the children, in order |
Result ({ itemId: string; childItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
childItemIds | string[] | yes | the children's ids, in order |
Errors: not_found, refused, besides those every command can return.
model.run("item.set-children", {
itemId: "lib",
items: [
{
kind: "file",
label: "index.ts",
data: {
size: 80
}
}
]
});{ "command": "item.set-children", "payload": {"itemId":"lib","items":[{"kind":"file","label":"index.ts","data":{"size":80}}]} }item.reset-children
Forget an item's loaded children (and everything inside them): its status goes back to unloaded, so the next expand loads them again. Only for an item whose children come from the loader.
Payload ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Result ({ itemId: string; removedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
removedItemIds | string[] | yes | the items removed |
Errors: not_found, refused, besides those every command can return.
model.run("item.reset-children", {
itemId: "lib"
});{ "command": "item.reset-children", "payload": {"itemId":"lib"} }Structure
item.add
Add a new item. item is its JSON: kind names what it is (a key of the app's registry), label its name and data its state (validated when the app registered a data schema); give it childItemIds: [] for an empty parent, or childrenStatus: "unloaded" for a parent the loader fills. to.parentItemId is its parent (null for the root) and to.index its position (omitted: last). In cascade mode it inherits a checked parent. Refused for a parent that is a leaf or whose children are not loaded, or a taken id.
Payload ({ item: TreeItemJson<T>; to: AddPlacement })
| field | type | required | description |
|---|---|---|---|
item | object | yes | the new item |
to | object | yes | where it goes |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the new item's id |
Errors: not_found, refused, besides those every command can return.
model.run("item.add", {
item: {
kind: "file",
label: "new.ts",
data: {
size: 0
}
},
to: {
parentItemId: "src",
index: 0
}
});{ "command": "item.add", "payload": {"item":{"kind":"file","label":"new.ts","data":{"size":0}},"to":{"parentItemId":"src","index":0}} }item.remove
Remove items and everything inside them. The expanded, selected and checked lists forget them; when the focused item goes, the focus moves to the visible item now at its place. Ancestors' checkboxes are recomputed.
Payload ({ itemIds: string[] })
| field | type | required | description |
|---|---|---|---|
itemIds | string[] | yes | the items to remove |
Result ({ removedItemIds: string[] })
| field | type | required | description |
|---|---|---|---|
removedItemIds | string[] | yes | every item removed, descendants included |
Errors: not_found, besides those every command can return.
model.run("item.remove", {
itemIds: [
"app"
]
});{ "command": "item.remove", "payload": {"itemIds":["app"]} }item.move
Move items (and their subtrees) into a parent, before the child at to.index (counted among the parent's children as they are now, the moved items included; past the end: last). Several items keep their order in the tree; an item inside another moved one goes with it. Refused into an item itself or one of its descendants, into a leaf, an unloaded, disabled or non-droppable parent, and for a disabled or non-movable item. This is what a drop runs.
Payload ({ itemIds: string[]; to: MovePlacement })
| field | type | required | description |
|---|---|---|---|
itemIds | string[] | yes | the items to move |
to | object | yes | where they go |
Result ({ itemIds: string[] })
| field | type | required | description |
|---|---|---|---|
itemIds | string[] | yes | the items moved, in their new order |
Errors: not_found, refused, besides those every command can return.
model.run("item.move", {
itemIds: [
"readme"
],
to: {
parentItemId: "src",
index: 0
}
});{ "command": "item.move", "payload": {"itemIds":["readme"],"to":{"parentItemId":"src","index":0}} }item.set-data
Replace an item's data (validated against its kind's data schema when the app registered one). Omit data to remove it.
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload (ItemSetDataPayload<T>)
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
data | JSON | no | its new data (any JSON value) |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, besides those every command can return.
model.run("item.set-data", {
itemId: "app",
data: {
size: 140
}
});{ "command": "item.set-data", "payload": {"itemId":"app","data":{"size":140}} }item.set-flags
Set an item's permission flags: disabled (focusable, not actionable), movable, droppable, and renamable (with the rename feature). A flag set to null takes the tree's default again (settings). A disabled item stops renaming.
Payload (ItemSetFlagsPayload)
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
disabled | boolean | null | no | focusable but not actionable: no expand, select, check, rename, move or drop; null removes the item's own value (the tree's default applies) |
movable | boolean | null | no | whether the item can be moved; null removes the item's own value (the tree's default applies) |
renamable | boolean | null | no | whether the item's label can be edited; null removes the item's own value (the tree's default applies) |
droppable | boolean | null | no | whether the item accepts items moved into it; null removes the item's own value (the tree's default applies) |
Result ({ itemId: string })
| field | type | required | description |
|---|---|---|---|
itemId | string | yes | the item |
Errors: not_found, besides those every command can return.
model.run("item.set-flags", {
itemId: "app",
movable: false
});{ "command": "item.set-flags", "payload": {"itemId":"app","movable":false} }The tree
tree.configure
Change the tree's settings: the defaults of the movable and droppable flags, and an installed feature's: the selection mode (none, single, multiple; a narrower mode trims the selection; the selection feature), the check mode (cascade or independent; switching to cascade makes the checks consistent; the checkboxes feature), the default of the renamable flag (the rename feature).
Payload ({ settings: TreeSettingsPatch })
| field | type | required | description |
|---|---|---|---|
settings | object | yes | the settings to change (the others are kept) |
Result ({ settings: TreeSettings & { selectionMode?: SelectionMode; checkMode?: CheckMode; renamable?: boolean; }; })
| field | type | required | description |
|---|---|---|---|
settings | object | yes | the settings after the command |
Errors: only those every command can return.
model.run("tree.configure", {
settings: {
selectionMode: "multiple"
}
});{ "command": "tree.configure", "payload": {"settings":{"selectionMode":"multiple"}} }tree.load
Replace the whole tree with a document (version 1, the same JSON model.get("tree-json") writes). The document is validated first; every problem is reported with its path. An item that keeps its id keeps its identity when nothing about it changed.
Payload ({ json: TreeJson<T> })
| field | type | required | description |
|---|---|---|---|
json | object | yes | the tree document |
Result ({ itemIds: string[] })
| field | type | required | description |
|---|---|---|---|
itemIds | string[] | yes | every item of the new tree |
Errors: only those every command can return.
model.run("tree.load", {
json: {
version: 1,
rootItemIds: [
"src"
],
items: {
src: {
kind: "folder",
label: "src",
childItemIds: []
}
}
}
});{ "command": "tree.load", "payload": {"json":{"version":1,"rootItemIds":["src"],"items":{"src":{"kind":"folder","label":"src","childItemIds":[]}}}} }Batches
batch
Run several commands as one step: they apply in order, each seeing the result of the ones before it, and either all of them apply (one event, one undo step) or none does (the first failure is returned, at its path in commands).
It may run as a step of a continuous gesture: model.run(…, { transient: true }).
Payload ({ commands: BatchEntry<T>[] })
| field | type | required | description |
|---|---|---|---|
commands | object[] | yes | the commands, in order |
Result ({ results: unknown[] })
| field | type | required | description |
|---|---|---|---|
results | JSON[] | yes | each command's value, in order |
Errors: those of the commands it runs (the first failure, at its path in commands); nothing applies unless all succeed.
model.run("batch", {
commands: [
{
command: "item.expand",
payload: {
itemId: "src"
}
},
{
command: "item.focus",
payload: {
itemId: "app"
}
}
]
});{ "command": "batch", "payload": {"commands":[{"command":"item.expand","payload":{"itemId":"src"}},{"command":"item.focus","payload":{"itemId":"app"}}]} }The command bus
How a command runs - run, dispatch, can and check, the results and error codes, middleware around every command, change events and batches.
The JSON model
The tree document (version 1) that createTreeModel loads and get("tree-json") writes back, with its fields, its rules and how it is normalized.