The command bus

Every change to a layout is a command that goes through the model's bus. The bus validates the payload, runs the middleware chain, applies the command to a draft of the state and commits it, then tells every listener. The engine and the primitives use the same bus as your code: a drag, a splitter or a close button issues a command like any other, so a middleware sees them all.

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

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

const model = createModel<Types>(json);

model.use((ctx, next) =>
    ctx.command === "tabset.close" && ctx.payload.tabset === "console"
        ? veto("The console stays open.")
        : next(),
);
model.subscribe((event) => console.log(event.command, event.result));

const result = model.run("tab.add", {
    component: "editor",
    data: { name: "a.ts", path: "/a.ts", dirty: false },
    to: "editors",
});
if (!result.ok) console.warn(result.error.code, result.error.message);

The commands themselves (every name, payload and result) are on Commands. The model's queries are on Model, and why every change is a command is in The model and commands.

run, dispatch, can, use and subscribe are bound to the model, so they can be passed around on their own (const { run } = model).

Running commands

None of them throws on bad input: an unknown name, a malformed payload, a missing node or a refusal is an { ok: false, error } result.

run

run<C extends CommandName>(
    command: C,
    payload: PayloadOf<T, C>,
    options?: RunOptions,
): CommandResult<ResultOf<T, C>>;

The payload type follows the command name, and a tab's data follows its component, so the compiler checks both against your registry (Typed data). The value of a successful result is typed too:

const added = model.run("tab.add", {
    component: "log",
    data: { name: "Build" },
    to: "tools",
    select: true,
});
if (added.ok) {
    model.run("tab.pin", { tab: added.value.tab, value: true });
}

The payload is still validated at run time, so a call from plain JavaScript (or with a cast) gets invalid_payload rather than a broken state.

dispatch

dispatch(input: unknown, options?: DispatchOptions): CommandResult<unknown>;

For input you did not type yourself: a saved file, a message from another window or a server, an assistant's tool call. dispatch checks the envelope before the payload:

Then it runs the command as run does. The paths of the payload's own problems start with /payload, so they point into the input you passed:

const result = model.dispatch(JSON.parse(message));
// { ok: false, error: { code: "not_found", message: 'no tab "zz"', path: "/payload/tab" } }

dispatch takes an optional second argument, DispatchOptions ({ meta }): the app's meta for middleware and listeners ({ source: "assistant" }, say). It is never read from the input: an input with a meta key is refused at /meta.

can

can<C extends CommandName>(
    command: C,
    payload: PayloadOf<T, C>,
    options?: RunOptions,
): CommandResult<ResultOf<T, C>>;

A dry run: the lookup, the validation, the middleware and the command's rules all run, on a draft that is thrown away. It returns the result the command would have and commits and emits nothing (a generated id in its value is only indicative: the real run may generate another one). Middleware sees ctx.dryRun set to true and must not cause side effects then.

The engine asks can on every dragover: a drop target is refused exactly when the command the drop would run is refused, whether by a node flag or by your middleware (Restricting drops). Use it the same way to enable a menu item:

const closable = model.can("tab.close", { tab: tab.id }).ok;

RunOptions

The third argument of run and can.

Results and errors

CommandResult

type CommandResult<R> =
    | { readonly ok: true; readonly value: R }
    | { readonly ok: false; readonly error: CommandError };

ResultOf<T, C> is the value type of command C ({ tab: string } for tab.add, the closed tab ids for tabset.close, …).

CommandError

CommandErrorCode

Every code the bus returns. Commands lists which ones each command's rules return.

Middleware

use(middleware: Middleware<T>): () => void;

type Middleware<T> = (
    ctx: CommandContext<T>,
    next: () => CommandResult<unknown>,
) => CommandResult<unknown> | undefined;

model.use adds a middleware and returns the function that removes it. A middleware runs around every command, whoever issues it: your code, the engine (drags, splitters, keyboard), a dispatch from JSON, a can dry run. It can do three things:

• Veto: return an error without calling next(). veto(message?) builds it: { ok: false, error: { code: "vetoed", message } } (the default message is "vetoed by a middleware").
• Rewrite: assign a new object to ctx.payload, then call next(). The new payload is validated again before the command runs.
• Observe: call next(), look at its result, and return it.

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

// veto: tabs of the "console" tabset stay where they are
const lockConsole: Middleware<Types> = (ctx, next) => {
    if (ctx.command === "tab.move" && ctx.parentOf(ctx.payload.tab)?.id === "console") {
        return veto("Console tabs cannot move.");
    }
    return next();
};

// rewrite: new editors always open in the "editors" tabset
const editorsHome: Middleware<Types> = (ctx, next) => {
    if (ctx.command === "tab.add" && ctx.payload.component === "editor") {
        ctx.payload = { ...ctx.payload, to: "editors", location: "center" };
    }
    return next();
};

// observe: log what was refused, but not the drag probes
const logRefusals: Middleware<Types> = (ctx, next) => {
    const result = next();
    if (!result.ok && !ctx.dryRun) {
        console.info(ctx.command, result.error.code, result.error.message);
    }
    return result;
};

const removers = [lockConsole, editorsHome, logRefusals].map(model.use);
// later: removers.forEach((remove) => remove());

The rules:

• Order. The first middleware added is the outermost: it runs first, its next() runs the second one, and the last one's next() runs the command. After the command, results travel back in the reverse order.
• undefined passes on the result of next() when the middleware called it, and is a veto (vetoed) when it did not.
• next() twice runs the rest of the chain once; the second call returns the same result.
• Throwing returns middleware_error; nothing is committed.
• Synchronous. A middleware cannot wait for a promise: the drop probe asks can on every dragover. To ask the user first, veto, then run the command again once they confirm.
• Batches. A batch runs the chain once as batch, then once for each command inside it with ctx.inBatch set, so a batch cannot get around a veto. A nested batch is flattened: only its commands run the chain.
• Dry runs. During can (ctx.dryRun), the same chain runs and must have no side effects.

CommandContext

What a middleware receives. CommandContext<T> is a union discriminated by command: once you check ctx.command, ctx.payload is that command's payload (PayloadOf<T, C>), typed by your registry. The fields every command shares are CommandContextBase<T>.

Read nodes with ctx.get rather than ctx.state when the middleware may run inside a batch: a tab the batch added a step earlier is in the draft, not yet in the committed state.

Batches

batch is a command whose payload is a list of commands. They run in order, on one draft, as one atomic step:

const result = model.run("batch", {
    commands: [
        { command: "tab.close", payload: { tab: "log" } },
        { command: "tabset.maximize", payload: { tabset: "editors", value: true } },
    ],
});
// result.value.results: each command's value, in order

• Atomic. The first command that fails stops the batch: nothing is committed and no event is emitted. The error is that command's, its path prefixed with /commands/<i>/payload (or /commands/<i>/command for an unknown name).
• One event. A successful batch emits a single event, whose commands lists every command it ran (BatchStep: command, payload, result), flattened.
• Flattened. A batch inside a batch contributes its commands, in place; its results are part of the outer results.
• Middleware. Every command inside it passes the chain with ctx.inBatch (see above).
• Transient. A batch may run with transient: true when every command in it is transient-capable.

Each entry is a BatchEntry<T>: { command, payload } with the payload typed by the command.

Events

subscribe(listener: CommandListener<T>): () => void;

type CommandListener<T> = (event: CommandEvent<T>) => void;

model.subscribe adds a listener and returns the function that removes it. Every successful commit delivers one CommandEvent<T> to every listener, including a command that changed nothing (then before === after). Failed commands and dry runs emit nothing.

const unsubscribe = model.subscribe((event) => {
    if (event.before !== event.after && !event.transient) {
        localStorage.setItem("layout", JSON.stringify(model.toJSON()));
    }
});

States are immutable and structurally shared, so before and after can be kept for free and compared by reference, node by node. Undo and redo keeps before and loads it back with toLayoutJson and layout.load.

A listener that throws does not stop the others: every listener runs, then the first error is rethrown from the run that committed (the commit stands).

Discovering commands

commands(): readonly CommandInfo[];

model.commands() lists every command with what an assistant, a command palette or a protocol needs to call it:

const tools = model.commands().map((info) => ({
    name: info.name.replace(".", "_"),
    description: info.description,
    input_schema: info.payloadSchema,
}));
// an assistant's tool call comes back as JSON: dispatch validates it
model.dispatch({ command: "tab.select", payload: call.input });

AI and automation builds on this, and the command-console example lists the schemas and runs commands typed by hand:

Re-entrancy

Code that reacts to a command may run another one. The bus keeps commits in order:

• From a listener, run and dispatch execute immediately (the previous commit is complete). Their event is delivered after the events still being delivered, so every listener sees every commit, in commit order.
• From a middleware, while a command is in flight, run and dispatch do not run: they return { ok: false, error: { code: "queued" } } at once, and the command executes after the current one commits (or fails). Its own result is not returned to anyone; subscribe to see it.
• can runs immediately from anywhere: it commits nothing.
• An exception thrown by a command itself (a bug, not a refusal) is rethrown by run once the chain has unwound; nothing is committed.

Types

Everything on this page is exported from @fragiola/dockable.

The payload type of each command (TabAddPayload<T>, TabMovePayload, …) is named on Commands.

Placement

LayoutDefaultsPatch

The defaults of layout.configure: { tab?, tabset?, border?, layout? }, each a patch of that part of the layout defaults. Fields are merged into the current defaults; a null field removes it, and a null part removes the whole part.

model.run("layout.configure", {
    defaults: {
        tab: { enablePopout: true, minWidth: 120 },
        border: { size: null }, // borders without their own size: the built-in 200
        layout: null, // every layout setting back to its built-in value
    },
});