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.
A tree is one JSON document. createTreeModel<Types>(json) validates it against its JSON Schema
(treeSchema) and the rules below, and throws a TreeValidationError listing every problem with
its JSON path; validateTree(json) returns the same issues instead. model.get("tree-json")
writes the current state back as a document with every field filled in, so a round trip is stable.
{
"version": 1,
"settings": { "selectionMode": "multiple", "checkMode": "cascade" },
"rootItemIds": ["src", "readme"],
"items": {
"src": { "id": "src", "kind": "folder", "label": "src", "childItemIds": ["app", "lib"] },
"app": { "id": "app", "kind": "file", "label": "app.ts", "data": { "size": 120 } },
"lib": { "id": "lib", "kind": "folder", "label": "lib", "childrenStatus": "unloaded" },
"readme": { "id": "readme", "kind": "file", "label": "README.md", "data": { "size": 3 } }
},
"expandedItemIds": ["src"],
"selectedItemIds": [],
"checkedItemIds": [],
"selectionAnchorItemId": null,
"focusedItemId": "src",
"renamingItemId": null
}A field holding an id is named <entity>Id, a list of ids <entity>Ids.
The document
Its type is TreeJson<T>, typed by your registry T; its settings are a TreeSettingsJson.
| field | type | required | what it is |
|---|---|---|---|
version | 1 | yes | the document version |
settings | object | no | the modes and the flags' defaults (below) |
rootItemIds | string[] | yes | the root items, in order |
items | object | yes | every item, keyed by its id |
expandedItemIds | string[] | no | the expanded items |
selectedItemIds | string[] | no | selection(): the selection, in the order it was made |
checkedItemIds | string[] | no | checkboxes(): the checked items |
selectionAnchorItemId | string | null | no | selection(): where a range selection starts |
focusedItemId | string | null | no | the roving tab stop |
renamingItemId | string | null | no | rename(): the item whose label is being edited |
Settings
| field | values | default |
|---|---|---|
selectionMode | "none", "single", "multiple" (selection()) | the feature's mode option, "single" by default |
checkMode | "cascade", "independent" (checkboxes()) | the feature's mode option, "cascade" by default |
movable | boolean: the default of an item's movable | true |
renamable | boolean: the default of an item's renamable (rename()) | the feature's renamable option, true by default |
droppable | boolean: the default of an item's droppable | true |
Items
An item is written as a TreeItemInit<K, D> (kind K, data D); TreeItemJson<T> is the union
of your registry's kinds, so data is checked per kind (DataField<D> makes it optional when the
kind's data allows undefined). loadChildren, item.add and item.set-children take the same
shape.
| field | type | required | what it is |
|---|---|---|---|
id | string | no | the item's id: equal to its key in items when given |
kind | string | yes | what the item is: a key of the app's registry, which types data |
label | string | yes | the item's name, raw: the app renders it, the packages never do |
data | JSON | no | the app's data (required by the type when the kind's data does not allow undefined) |
childItemIds | string[] | no | its children, in order |
childrenStatus | "unloaded", "loading", "loaded", "error" | no | asyncChildren(): where its children come from the app's loader |
disabled | boolean | no | focusable, but not actionable |
movable | boolean | no | whether it can be moved (default: settings.movable) |
renamable | boolean | no | rename(): whether its label can be edited (default: settings.renamable) |
droppable | boolean | no | whether it accepts items moved into it (default: settings.droppable) |
An item with neither childItemIds nor childrenStatus is a leaf. An item with
childItemIds (possibly empty) holds its children itself. An item with a childrenStatus gets
them from the app's loader: unloaded until it is first expanded, loading while the engine
waits for loadChildren, loaded with its childItemIds, error when the load failed.
Rules
- Every id in
rootItemIdsandchildItemIdsis an item, and every item has exactly one place: one parent, or the root. An item no root reaches (an orphan, or a cycle) is an error. - A parent whose
childrenStatusisunloaded,loadingorerrorhas no children yet. expandedItemIds,selectedItemIds,checkedItemIdsand the single ids name items; no list repeats an id.selectionMode: "none"holds no selection,"single"at most one item.- A field of a feature (the ones marked
selection(),checkboxes(),rename()orasyncChildren()) loads only into a model with that feature: elsewhere it is an issue,requires the selection feature(Features).model.get("tree-json")writes only the installed features' fields. - With
dataSchemas(a JSON Schema per kind, an option ofcreateTreeModel), each item'sdatais validated against its kind's schema.
How a document is normalized
The state the model holds, and the document it writes back, is the loaded document with:
- every setting filled in from the defaults, and every list and single id present;
- an expanded leaf dropped from
expandedItemIds; - a
loadingitem madeunloadedagain (a load is never saved: the engine starts it again); - a disabled item dropped from the selection and from
renamingItemId; - a
loadedparent given an emptychildItemIdswhen it had none; - in
cascademode, the checks made consistent: a listed parent checks all its descendants, then a parent with children is checked exactly when all of them are (a parent with only some of its descendants checked ismixed:model.get("check-state-by", { itemId }), never stored); - a
focusedItemIdthat is hidden (inside a collapsed item) moved to its nearest visible ancestor.
Ids
A document's ids are its keys. Items created by commands without an id (item.add,
item.set-children) get one from createId (an option of createTreeModel), else the default
item-<n>; an id in use is never given again.