Model

Model<T> (from @fragiola/dockable) holds the layout: the main layout's tree, its borders, the popout window layouts, the layout defaults and each layout's active and maximized tabset. Its state is a tree of plain, frozen objects; a command replaces it with a new one. It needs no DOM, so layout logic runs and is testable in plain Node.

The core API pages import from @fragiola/dockable, the framework-free core. A React app imports the same names from @fragiola/dockable-react, which re-exports the whole core (Installation).

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

type Types = {
    tabs: {
        editor: { path: string; dirty: boolean };
        log: undefined;
    };
};

const json: LayoutJson<Types> = {
    version: 1,
    root: {
        type: "row",
        children: [
            {
                type: "tabset",
                id: "editors",
                children: [
                    {
                        id: "readme",
                        component: "editor",
                        label: "README.md",
                        data: { path: "/README.md", dirty: false },
                    },
                ],
            },
        ],
    },
};

const model = createModel<Types>(json);
model.get("selected-tab-by", { tabsetId: "editors" })?.data; // typed by the registry
model.is("tabset-maximized", { tabsetId: "editors" }); // false
model.run("tab.close", { tabId: "readme" });
const saved = model.get("layout-json"); // a LayoutJson<Types> again

Every member is one verb, and each verb takes a key and a payload, the way a command does:

Every method is bound: const { run, get } = model works. Never change the state yourself: it is frozen, and every change goes through a command (The model and commands). This page covers creating a model and reading it; run, dispatch, can, check, middleware and change events are on The command bus, the commands themselves on Commands, and the document format on Layout JSON. What the model is next to an engine: Model and engine.

Creating a model

function createModel<T extends DockableTypes = AnyTypes>(
    json?: LayoutJson<T>,
    options?: ModelOptions<T>,
): Model<T>;

createModel validates the document, fills what it omits, generates the missing ids and tidies the tree. Without a document it creates an empty layout: a root row with one empty, active tabset. An invalid document throws a LayoutValidationError listing every problem with its JSON path (Validation); for input you do not trust, check it first with validateLayout, or load it into an existing model with dispatch, which returns the problems instead of throwing.

T is your type registry (below). Pass it explicitly: get, run and middleware are typed by it.

ModelOptions

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

const logSchema = {
    type: "object",
    properties: { maxLines: { type: "integer", minimum: 1 } },
    required: ["maxLines"],
    additionalProperties: false,
} as const;

type Types = {
    tabs: { log: FromSchema<typeof logSchema> }; // { maxLines: number }
};

const model = createModel<Types>(json, {
    createId: (kind) => `${kind}-${crypto.randomUUID()}`,
    dataSchemas: { log: logSchema },
});

Ids

Every node and window has an explicit id in the state; reading never assigns one. A node created without an id (in a document, or by tab.add, a split or a popout) gets one when it is created:

• CreateId is (kind: IdKind) => string, and IdKind is NodeKind | "window": the kind the id is for ("row", "tabset", "tab" or "window").
• The default generator is deterministic and needs no crypto: `${kind}-${n}` with one counter per kind (tab-1, tabset-2), skipping ids already in use.
• A custom generator is asked again when it returns an empty string or an id in use (up to 100 times, then the default takes over).
• A border without an id is border_<location> (there is one border per side).
• Ids are unique across all nodes and windows, and MAIN_LAYOUT ("main") is reserved.

Ids are stable: a node keeps its id when it moves, and layout.load keeps the mounted content of every tab whose id survives. Keep references by id, not by layout path.

Reading: get

model.get(key, payload) reads the current state. The key says what it returns, and the payload says whose, so the call reads as one sentence. A key that takes an id ends in -by, and the payload's field completes it: id when it is the id of what the key returns (model.get("node-by", { id })), <entity>Id otherwise (model.get("node-parent-by", { nodeId }), model.get("selected-tab-by", { tabsetId })). A key whose only input is a layout has no -by: its layoutId is optional, MAIN_LAYOUT (the default) or a popout window's id (model.get("tabsets")). A key that takes nothing has a plain name (model.get("all-tabs")). An unknown id reads undefined.

A payload field that names an entity reads only that kind: selected-tab-by with { tabsetId } set to a border's id reads undefined. A tab is selected and a tabset is active (Selected and active).

state is a property, not a key: model.state is the current LayoutState<T>, immutable, a new object after every change, with unchanged subtrees shared (compare with ===).

Asking: is

model.is(key, payload) answers a yes/no question about the current state: every state a primitive shows as a data-* attribute that comes from the model alone, and where a node lives. A key reads as the question after "is" (tabset-active: is the tabset active?), and its payload is the id of the entity it names first. An unknown id, or the id of another kind of node, answers false.

The keys are typed: an unknown key or a wrong payload field does not compile, and get's result is typed by its key and your registry. The key types are exported as ModelGetKey, ModelIsKey, ModelGetMap<T> and ModelIsMap, with ModelGetPayload<T, K>, ModelGetResult<T, K> and ModelIsPayload<K>; QueryArgs<P> makes the payload optional when it has no required field, NoPayload is the payload of a key that takes none, and SelectedTabByPayload is the payload of selected-tab-by.

Nodes are plain objects with a type field ("row", "tabset", "tab", "border"), no classes and no methods. A tab of TabOf<T> narrows on component, so its data is typed:

function title(tab: TabOf<Types>): string {
    switch (tab.component) {
        case "editor":
            return tab.data.dirty ? `${tab.label} •` : tab.label;
        case "log":
            return tab.label;
    }
}

const node = model.get("node-by", { id: "editors" });
if (node?.type === "tabset") {
    node.children.map(title);
}

In React, read through useModelState or useDockable so a component re-renders when the state changes (Hooks).

Settings

A node stores only the behaviour fields it sets itself. The effective value of a field is:

node.x ?? state.defaults[kind].x ?? BUILT_IN[kind].x

There is no other inheritance: a tab does not inherit from its tabset. The *-settings keys of get apply the rule and return every field, resolved:

A resolved border's size, minSize and maxSize are its panel's effective values: the selected tab's own borderWidth (start and end borders) or borderHeight (top and bottom) replaces size, and the tab's size limits narrow minSize and maxSize. show is true unless the border sets it to false.

const tab = model.get("selected-tab-by", { tabsetId: "editors" });
if (tab && model.get("tab-settings-by", { tabId: tab.id })?.closable) {
    // render a close button
}

BUILT_IN is the last step of the rule, the frozen built-in value of every field:

The layout's own defaults are the defaults of the document (Defaults), changed at runtime with layout.configure.

Saving and loading

layout.load keeps the model (and so your middleware, listeners and the rendered view) and replaces its state. A node is the same node when its id is in both states, so the tabs whose ids survive keep their mounted content; the result lists the addedNodeIds and removedNodeIds.

import { toLayoutJson } from "@fragiola/dockable";

// restore something you saved (validated like any untrusted JSON)
const restored = model.dispatch({
    command: "layout.load",
    payload: { layout: JSON.parse(text) },
});
if (!restored.ok) console.warn(restored.error.issues);

// go back to a state you kept
const previous = model.state;
model.run("layout.load", { layout: toLayoutJson(previous) });

Saving and restoring and Undo and redo build on these.

ModelHandle

The part of a model that does not depend on its registry: dispatch(input, options?), get("commands") and get("layout-json") (the document as unknown). Every Model<T> is a ModelHandle. APIs that join models of different registries take one: a drag group's transfers name their from and to models as ModelHandles; compare them with your own models by reference (===).

MAIN_LAYOUT

MAIN_LAYOUT is "main", the id of the main layout: the state's root, active, maximized and its borders. A popout window's layout id is its window's id. Every get key whose only input is an optional layoutId (tabs, tabsets, root-row, active-tabset, default-tabset, maximized-tabset) and every primitive that takes a layout id defaults to it, and no node or window may use it as an id.

import { MAIN_LAYOUT } from "@fragiola/dockable";

for (const windowLayout of model.get("windows")) {
    model.get("tabs", { layoutId: windowLayout.id }); // the tabs of one popout window
}
model.get("tabs", { layoutId: MAIN_LAYOUT }); // the main layout's tabs, its borders' included

The type registry

The model, its commands and the React primitives are generic over one type, the registry that says what data each tab component holds (Typed data):

type Types = {
    tabs: {
        editor: { path: string; dirty: boolean };
        log: undefined;
    };
    tabset: { name: string };
};

DockableTypes is what a registry must satisfy:

AnyTypes ({ tabs: Record<string, unknown> }) is the default when you pass none: any component, unknown data.

FromSchema lets one schema be both the runtime check (dataSchemas) and the data type, as in the options example. The node types themselves (TabNode, TabsetNode, RowNode, BorderNode, WindowLayout, LayoutState) are on Layout JSON.