Layout JSON

A layout is saved and loaded as a LayoutJson<T> document, version 1. createModel(json) and the layout.load command read it, and model.get("layout-json") writes it. It is plain JSON: the state the model holds has the same shape, with the omitted fields filled in.

{
    "version": 1,
    "defaults": { "tab": { "poppable": true }, "border": { "size": 220 } },
    "root": {
        "type": "row",
        "id": "root",
        "children": [
            {
                "type": "tabset",
                "id": "editors",
                "weight": 70,
                "children": [
                    { "id": "readme", "component": "editor", "label": "README.md", "data": { "path": "/README.md" } }
                ]
            },
            {
                "type": "tabset",
                "id": "tools",
                "weight": 30,
                "droppable": false,
                "children": [{ "id": "log", "component": "log", "label": "Log", "pinned": true }]
            }
        ]
    },
    "active": "editors",
    "borders": [
        { "location": "start", "mode": "overlay", "children": [{ "component": "files", "label": "Files" }] }
    ],
    "windows": [
        {
            "id": "w1",
            "rect": { "x": 100, "y": 100, "width": 600, "height": 400 },
            "root": { "type": "row", "children": [{ "type": "tabset", "children": [{ "component": "log", "label": "Build" }] }] }
        }
    ]
}

A tab's text (its name, icon, tooltip) is not a layout field: it lives in the tab's data, typed by your registry (Typed data). The layout stores structure, sizes and behaviour only.

The top-level row is horizontal (unless defaults.layout.rootOrientation is "vertical"); a row inside a row takes the opposite orientation, so it acts as a column. Orientation is never stored.

The document

LayoutJson<T>:

active and maximized are stored on the layout, not on a tabset: a layout has at most one of each, and each must name a tabset of that layout.

Rows

RowJson<T>:

Tabsets

TabsetJson<T>, which also takes every field of TabsetDefaults:

A behaviour field left out follows the layout's defaults.tabset, then the built-in value (Settings).

Tabs

TabJson<T> is a TabInit (the fields a new tab is created with, shared with tab.add and drag sources) whose type may be omitted:

The types:

• TabInit<K, D>: the fields above for component K with data D.
• TabOwnFields: pinned, borderWidth and borderHeight, the fields of a tab no layout default applies to; the others follow TabDefaults.
• TabInitOf<T>: a union of TabInit over the registry's components, so data is checked against component.
• TabJson<T>: TabInitOf<T> with an optional type: "tab".
• DataField<D>: how data is declared, optional exactly when D allows undefined.

import type { TabJson } from "@fragiola/dockable";

const readme: TabJson<Types> = {
    id: "readme",
    component: "editor",
    label: "README.md",
    data: { path: "/README.md", dirty: false },
};

Borders

BorderJson<T>, which also takes every field of BorderDefaults:

See Borders.

Windows

WindowJson<T>, one entry of windows: a popout window and its layout.

The engine records a window's rect when the user moves or resizes it (window.configure), so a saved layout reopens its windows in place (Popouts).

Defaults

defaults holds the value a node's behaviour field takes when the node does not set it, and the layout-wide settings. LayoutDefaults:

The rule is node.x ?? defaults[kind].x ?? BUILT_IN[kind].x, with no other inheritance (Settings). Change the defaults at runtime with layout.configure (LayoutDefaultsPatch).

TabDefaults (built-in values in the last column):

TabsetDefaults:

BorderDefaults:

LayoutSettings:

SizeLimits is the size part of tabs, tabsets and their defaults, in px:

The state

Loading a document gives the state model.state holds: a LayoutState<T> whose nodes are the document's, frozen, with every omitted structural field filled in. The node types are what the queries return.

A node's behaviour fields stay as the document set them (absent means "use the defaults"), so model.get("layout-json") writes back exactly what was set. selected is an index into children, -1 for none. Loading also tidies the tree, as every command does: an empty tabset is removed when it allows it (deleteWhenEmpty and closable), an empty nested row is removed, a nested row with one child is replaced by that child, and an empty window is removed. The main layout always keeps a tabset: when tidying would leave it with none, one of its empty tabsets stays, with its id: the active one, else the first (so { "type": "tabset", "id": "editor", "children": [] } loads as is, ready for a tab.add to "editor"), and a main layout with no tabset at all gets a new empty one. Either becomes active, and neither stays maximized.

Validation

createModel and layout.load validate a document before anything changes, and report every problem, each with a JSON pointer (RFC 6901) into the document:

• against layoutSchema, the JSON Schema of LayoutJson (exported, so other tools can use it);
• then what a schema cannot check: duplicate ids, the reserved id "main", two borders on one side, a pinned tab in a border, and an active or maximized that is not a tabset of its layout;
• and each tab's data against its component's schema, when you registered one (dataSchemas, on Model).

Each problem is a ValidationIssue:

How each entry point reports them:

import { createModel, type LayoutJson, validateLayout } from "@fragiola/dockable";

const checked = validateLayout<LayoutJson<Types>>(JSON.parse(text));
const model = checked.ok
    ? createModel<Types>(checked.value)
    : createModel<Types>(defaultLayout);
if (!checked.ok) {
    for (const issue of checked.issues) console.warn(issue.path || "/", issue.message);
}

In a running app, prefer loading into the model you have, as untrusted JSON: model.dispatch({ command: "layout.load", payload: { layout } }) validates it and changes nothing when it is invalid (Saving and restoring).

JSON Schema types

layoutSchema, a command's payloadSchema and your dataSchemas are JsonSchema objects: the subset of JSON Schema 2020-12 that the model's validator checks.

Other keywords may be present (a data schema written for another validator), and are ignored. JsonValue is any JSON value. FromSchema<S> turns such a schema into its TypeScript type (Model).

From the old format

Documents written for FlexLayout's format do not load: v1 is a new format. What became of the old attributes: