Documentation
API: core (@fragiola/tree)

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.

fieldtyperequiredwhat it is
version1yesthe document version
settingsobjectnothe modes and the flags' defaults (below)
rootItemIdsstring[]yesthe root items, in order
itemsobjectyesevery item, keyed by its id
expandedItemIdsstring[]nothe expanded items
selectedItemIdsstring[]noselection(): the selection, in the order it was made
checkedItemIdsstring[]nocheckboxes(): the checked items
selectionAnchorItemIdstring | nullnoselection(): where a range selection starts
focusedItemIdstring | nullnothe roving tab stop
renamingItemIdstring | nullnorename(): the item whose label is being edited

Settings

fieldvaluesdefault
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
movableboolean: the default of an item's movabletrue
renamableboolean: the default of an item's renamable (rename())the feature's renamable option, true by default
droppableboolean: the default of an item's droppabletrue

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.

fieldtyperequiredwhat it is
idstringnothe item's id: equal to its key in items when given
kindstringyeswhat the item is: a key of the app's registry, which types data
labelstringyesthe item's name, raw: the app renders it, the packages never do
dataJSONnothe app's data (required by the type when the kind's data does not allow undefined)
childItemIdsstring[]noits children, in order
childrenStatus"unloaded", "loading", "loaded", "error"noasyncChildren(): where its children come from the app's loader
disabledbooleannofocusable, but not actionable
movablebooleannowhether it can be moved (default: settings.movable)
renamablebooleannorename(): whether its label can be edited (default: settings.renamable)
droppablebooleannowhether 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 rootItemIds and childItemIds is 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 childrenStatus is unloaded, loading or error has no children yet.
  • expandedItemIds, selectedItemIds, checkedItemIds and 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() or asyncChildren()) 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 of createTreeModel), each item's data is 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 loading item made unloaded again (a load is never saved: the engine starts it again);
  • a disabled item dropped from the selection and from renamingItemId;
  • a loaded parent given an empty childItemIds when it had none;
  • in cascade mode, 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 is mixed: model.get("check-state-by", { itemId }), never stored);
  • a focusedItemId that 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.