Documentation
Concepts

The model and commands

The layout is an immutable JSON-shaped state. Every change is a command that runs through a middleware chain, and every commit emits one event.

The model is the source of truth. What you render is a function of its state, and the state changes only through commands: model.run("tab.close", { tabId: "t1" }). Every command, whether your code runs it or a primitive does (a click, a drop, a splitter drag), goes through the same middleware chain, and every commit emits one event.

The model is the layout's data and its rules; what the screen does with it (measuring, popout windows, focus) is an engine's. Which one to go to for what is on Model and engine.

JSON in, JSON out

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

type Types = { tabs: { editor: { path: string }; 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" } }],
            },
        ],
    },
};

const model = createModel<Types>(json); // LayoutJson -> Model<Types>
const saved: LayoutJson<Types> = model.get("layout-json"); // Model -> LayoutJson (a writable copy)

A layout document is JSON v1: version: 1, a root row, and optionally defaults, the active and maximized tabsets, borders and popout windows. A tab names its component and carries its data, typed by the Types registry (Typed data). Every field is in the JSON model reference.

  • Ids are explicit. A node without an id gets one at load (tab-1, tabset-2, …, or your createId option), and model.get("layout-json") writes it, so a round trip is stable: createModel(model.get("layout-json")).state deep-equals model.state.
  • Loading validates. createModel checks the document against the JSON v1 schema (duplicate ids, two borders on one side, an active naming a missing tabset, …) and throws a LayoutValidationError whose issues list every problem with its JSON path. validateLayout(json) returns the same issues instead of throwing, for code that must not throw.
  • The model loads in plain Node. It needs no DOM, so it works in tests, on a server, or in a worker.

The state is plain data

model.state is the whole layout as readonly plain objects: no classes, no getters, no methods. A node is told apart by its type field ("row", "tabset", "tab", "border"), and its fields are read directly:

const tabset = model.get("node-by", { id: "editors" });
if (tabset?.type === "tabset") {
    tabset.children; // readonly TabOf<Types>[]
    tabset.selected; // the index of the selected tab, -1 when none
    tabset.weight; // its relative size in its row
}

The state is immutable. A command never changes it in place: it produces a new state that shares every untouched node with the previous one, and the objects are frozen. So a node you hold is a snapshot (read the model again to see a later change), before === after tells you nothing changed, and keeping an old state (for undo, a diff, a test) costs nothing.

The state holds only the layout. Measured rects, scroll positions, which tabs have rendered: that is view state, kept by the engine and keyed by node id (Geometry).

Running commands

A command is a name and a JSON payload. model.run is typed by your registry: the payload is checked against the command, and data against the component.

model.run("tab.select", { tabId: "readme" });
model.run("tab.close", { tabId: "readme" });
model.run("tab.add", { component: "log", label: "Log", to: "editors", select: true });
model.run("tab.move", { tabId: "log", to: "editors", location: "end" }); // split beside it
model.run("tab.rename", { tabId: "log", label: "Build log" });
model.run("tab.set-data", { tabId: "readme", data: { path: "/docs/README.md" } }); // a data patch
model.run("tabset.maximize", { tabsetId: "editors", value: true });

Every command returns a CommandResult, and never throws on bad input:

const result = model.run("tab.close", { tabId: "readme" });
if (result.ok) {
    result.value.tabId; // the command's value
} else {
    result.error.code; // "not_found", "refused", "vetoed", "invalid_payload", …
    result.error.message;
    result.error.path; // a JSON pointer into the payload, e.g. "/tab"
}

refused means a rule of the layout forbids it: a pinned tab cannot close, a tab whose draggable is false cannot move, a tabset with droppable: false takes no drop. The permission flags are enforced by the commands themselves, so code cannot bypass them either.

run is bound, so it can be passed around on its own. Inside Dockable.Root, useDockable() gives you the model:

import { useDockable } from "@fragiola/dockable-react";

function CloseButton({ tabId }: { tabId: string }) {
    const { model } = useDockable<Types>();
    return (
        <button type="button" aria-label="Close" onClick={() => model.run("tab.close", { tabId })}>
            ×
        </button>
    );
}

Outside the root, call model.run directly: the model is all a command needs, mounted or not.

The rest of the bus:

  • model.dispatch({ command, payload }) runs a command given as untrusted JSON (a stored layout, a message from a server, an AI tool call): the envelope and the payload are validated before anything runs.
  • model.can(command, payload) answers whether run would succeed, without committing or emitting anything: a boolean. Enable a button with model.can("tabset.maximize", { tabsetId, value: true }). model.check(command, payload) returns what run would return instead, with the error that says why it is refused.
  • model.run("batch", { commands: [...] }) runs several commands as one atomic step: if one fails, none applies, and the batch emits a single event.
  • run(command, payload, { transient: true }) marks a step of a continuous gesture (the splitters run row.resize this way on every pointer move); { meta } passes free-form information to middleware and listeners.
  • model.get("commands") lists every command with its description and the JSON Schemas of its payload and result.

Every command, its payload and its errors are in the commands reference; the bus itself (ordering, re-entrancy, error codes) is in the command bus reference.

Intercepting: middleware

model.use(middleware) adds a function that runs around every command: yours, and the ones the primitives run (a click selecting a tab, a drop moving one, a splitter resizing a row). It sees a context and a next function, and can do three things:

import { type Middleware, veto } from "@fragiola/dockable-react";

const policy: Middleware<Types> = (ctx, next) => {
    // veto: return an error without calling next(); the "readme" tab cannot be closed
    if (ctx.command === "tab.close" && ctx.payload.tabId === "readme") {
        return veto("The README stays open.");
    }
    // rewrite: assign a new payload, then call next() (it is validated again)
    if (ctx.command === "tab.add") {
        ctx.payload = { ...ctx.payload, select: true };
    }
    // observe: call next() and look at its result
    return next();
};

const remove = model.use(policy); // returns the function that removes it

Checking ctx.command narrows ctx.payload to that command's payload. The context also carries the committed state, ctx.get("node-by", { id }) and ctx.get("node-parent-by", { nodeId }) (as the command sees them, inside a batch too), meta, transient, and dryRun.

A drag is not special. While you drag, the engine asks the model for the command each drop target would run, on every dragover: a middleware veto hides the drop indicator over that target, and a drop runs the command through the chain again. One policy covers drags, keyboard, menus and code. See Restricting drops.

No side effects in a dry run

model.can and model.check run the middleware chain with ctx.dryRun set to true, and the drop indicator asks on every dragover. Log, notify or fetch only when ctx.dryRun is false.

Middleware is synchronous, and runs outermost first (the first one added wraps the others). A middleware that throws yields a middleware_error result, and nothing is committed.

Reacting: events

model.subscribe(listener) is called once per commit, with a CommandEvent: the command, its payload and result, the state before and after, transient and meta (and, for a batch, the commands it ran). It is the place to persist the layout, sync it or log it:

const unsubscribe = model.subscribe((event) => {
    if (!event.transient) {
        localStorage.setItem("layout", JSON.stringify(model.get("layout-json")));
    }
});

While a splitter is dragged live, the engine runs row.resize as transient on every pointer move, and each one emits an event. Skip them (as above) or debounce: the gesture ends with a normal, non-transient command. Persistence and undo/redo are both built on these events.

In React, useModelState(selector) subscribes a component to a slice of the state, and re-renders it only when that slice changes:

const count = useModelState<Types, number>((state, model) => model.get("all-tabs").length);

Reading the model

Two verbs read the current state: get reads something, is asks a yes/no question. Both take a key and a payload, like a command; each is O(1) or a walk of the tree, and safe during render.

model.state; // LayoutState<Types>: root, borders, windows, active, maximized, defaults
model.get("node-by", { id: "readme" }); // a node by id
model.get("node-parent-by", { nodeId: "readme" }); // its row, tabset or border
model.get("layout-id-by", { nodeId: "readme" }); // MAIN_LAYOUT, or a window id
model.get("root-row"); // a layout's root row (default the main layout)
model.get("all-tabs"); // every tab, in tree order: TabOf<Types>[]
model.get("tabsets"); // a layout's tabsets
model.get("selected-tab-by", { tabsetId: "editors" }); // a tabset's selected tab
model.get("selected-tab-by", { borderId: "border_start" }); // a border's (none while it is closed)
model.get("active-tabset"); // the active tabset of a layout
model.get("maximized-tabset"); // the maximized tabset of a layout
model.get("tab-settings-by", { tabId: "readme" }); // a tab's flags, resolved through the defaults
model.get("layout-settings"); // the layout-wide settings, resolved
model.is("tabset-maximized", { tabsetId: "editors" }); // is this tabset maximized?
model.is("node-hidden-by-maximize", { nodeId: "tools" }); // hidden because another tabset is maximized

Every key is on the Model reference. A flag a node does not set comes from the layout defaults (then from the built-in value), so read it through the *-settings keys, not from the node: model.get("tab-settings-by", { tabId: tab.id })?.closable. To know whether something is allowed right now (the defaults, the rules and your middleware together), ask model.can("tab.close", { tabId: tab.id }).

The primitives re-render when the state changes, so reading the model inside the layout is always current. Outside it, subscribe: useModelState(selector, { model }) in React, or model.subscribe.

Replacing the layout: layout.load

A saved layout, an undo step or a remote update replaces the whole state with one command, in place:

const result = model.run("layout.load", { layout: savedJson });
if (result.ok) {
    result.value.addedNodeIds; // node and window ids only in the new layout
    result.value.removedNodeIds; // ids only in the old one
}

The model keeps its identity; only its state changes, so Dockable.Root keeps its engine. Nodes keep their identity by id: a tab whose id is in both layouts keeps its mounted content (its moveable element, its scroll position), wherever it moves. Only the removed tabs unmount.

layout.load validates the document like createModel, but returns the problems instead of throwing: invalid_payload with every issue, its paths under /layout. For stored text, run it through model.dispatch, which validates the whole input:

const result = model.dispatch({ command: "layout.load", payload: { layout: JSON.parse(text) } });

One model, several layouts

A model holds the main layout (MAIN_LAYOUT, "main": the root row, the borders, the active and maximized tabsets) and one window layout per popout window (model.get("windows"), each with its own root row). The keys that depend on a layout take a layout id and default to the main one, and useDockable().layoutId says which layout a component renders in. Each layout on screen has its own engine (Model and engine).

See it

Layout lab
Gallery
Command console
Gallery