Documentation
API: core (@fragiola/tree)

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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string; expanded: boolean })

fieldtyperequireddescription
itemIdstringyesthe item
expandedbooleanyeswhether 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ expandedItemIds: string[] })

fieldtyperequireddescription
expandedItemIdsstring[]yesthe 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[] })

fieldtyperequireddescription
expandedItemIdsstring[]yesthe 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[] })

fieldtyperequireddescription
collapsedItemIdsstring[]yesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item
mode"replace" | "toggle" | "extend"noreplace (default): the item alone; toggle: added or removed; extend: the visible range from the selection anchor

Result ({ selectedItemIds: string[] })

fieldtyperequireddescription
selectedItemIdsstring[]yesthe 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[] })

fieldtyperequireddescription
itemIdsstring[]yesthe items to select

Result ({ selectedItemIds: string[] })

fieldtyperequireddescription
selectedItemIdsstring[]yesthe 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[] })

fieldtyperequireddescription
selectedItemIdsstring[]yesthe 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[] })

fieldtyperequireddescription
selectedItemIdsstring[]yesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item
checkedbooleanyestrue checks it, false unchecks it

Result ({ checkedItemIds: string[] })

fieldtyperequireddescription
checkedItemIdsstring[]yesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string; checked: boolean })

fieldtyperequireddescription
itemIdstringyesthe item
checkedbooleanyeswhether 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item
labelstringyesthe new label (not empty)

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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" })

fieldtyperequireddescription
itemIdstringyesthe item
status"loading" | "error"yesloading: the load started; error: it failed

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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>[] })

fieldtyperequireddescription
itemIdstringyesthe item
itemsobject[]yesthe children, in order

Result ({ itemId: string; childItemIds: string[] })

fieldtyperequireddescription
itemIdstringyesthe item
childItemIdsstring[]yesthe 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 })

fieldtyperequireddescription
itemIdstringyesthe item

Result ({ itemId: string; removedItemIds: string[] })

fieldtyperequireddescription
itemIdstringyesthe item
removedItemIdsstring[]yesthe 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 })

fieldtyperequireddescription
itemobjectyesthe new item
toobjectyeswhere it goes

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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[] })

fieldtyperequireddescription
itemIdsstring[]yesthe items to remove

Result ({ removedItemIds: string[] })

fieldtyperequireddescription
removedItemIdsstring[]yesevery 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 })

fieldtyperequireddescription
itemIdsstring[]yesthe items to move
toobjectyeswhere they go

Result ({ itemIds: string[] })

fieldtyperequireddescription
itemIdsstring[]yesthe 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>)

fieldtyperequireddescription
itemIdstringyesthe item
dataJSONnoits new data (any JSON value)

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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)

fieldtyperequireddescription
itemIdstringyesthe item
disabledboolean | nullnofocusable but not actionable: no expand, select, check, rename, move or drop; null removes the item's own value (the tree's default applies)
movableboolean | nullnowhether the item can be moved; null removes the item's own value (the tree's default applies)
renamableboolean | nullnowhether the item's label can be edited; null removes the item's own value (the tree's default applies)
droppableboolean | nullnowhether the item accepts items moved into it; null removes the item's own value (the tree's default applies)

Result ({ itemId: string })

fieldtyperequireddescription
itemIdstringyesthe 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 })

fieldtyperequireddescription
settingsobjectyesthe settings to change (the others are kept)

Result ({ settings: TreeSettings & { selectionMode?: SelectionMode; checkMode?: CheckMode; renamable?: boolean; }; })

fieldtyperequireddescription
settingsobjectyesthe 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> })

fieldtyperequireddescription
jsonobjectyesthe tree document

Result ({ itemIds: string[] })

fieldtyperequireddescription
itemIdsstring[]yesevery 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>[] })

fieldtyperequireddescription
commandsobject[]yesthe commands, in order

Result ({ results: unknown[] })

fieldtyperequireddescription
resultsJSON[]yeseach 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"}}]} }