Documentation
Concepts

The model and commands

Every change is a command run through middleware, from a drag to a button. Run commands from code, veto or rewrite them, and listen to every commit.

The model's state is plain, frozen, JSON-shaped data, and only commands change it. A drag, a key press, a double click, a prop that changed and a button in your toolbar all end in the same place: model.run(command, payload). That is what lets you drive a layout from anywhere, refuse a change whoever asked for it, and record every change for undo or persistence.

Running a command

model.run returns a result, never throws on bad input:

const result = model.run("panel.resize", { panelId: "sidebar", size: "30%" });
if (result.ok) {
    console.log(result.value.size); // the size it took, in percent
} else {
    console.log(result.error.code); // "not_found", "refused", "vetoed", ...
}

model.can says whether run would succeed, model.check returns what it would return, and neither commits anything. Use them to enable a button:

<button
    type="button"
    disabled={!model.can("panel.expand", { panelId: "terminal" })}
    onClick={() => model.run("panel.expand", { panelId: "terminal" })}
>
    Show the terminal
</button>

The commands are listed, with their payloads, results and errors, on Commands. The ones you call most:

commanddoes
panel.resizegives a panel a size, in any unit; the others make room
panel.collapse / panel.expandcollapses a collapsible panel, or gives it back the size it had
group.set-layoutsets a whole layout at once (validated against the constraints)
group.resetputs a group back to its default layout
batchruns several commands as one atomic step

From outside the group

A toolbar above the group reaches the model through an external ref:

"use client";

import { Splitter, type SplitterRef, useSplitter, useSplitterRef } from "@fragiola/splitter-react";

function Toolbar({ splitterRef }: { splitterRef: SplitterRef }) {
    const splitter = useSplitter(splitterRef); // null until the group mounts
    if (!splitter) return null;
    const { model, groupId } = splitter;
    return (
        <div role="toolbar" aria-label="Layout">
            <button type="button" onClick={() => model.run("panel.resize", { panelId: "sidebar", size: "20%" })}>
                Narrow sidebar
            </button>
            <button type="button" onClick={() => model.run("group.reset", { groupId })}>
                Reset
            </button>
        </div>
    );
}

export function Editor() {
    const splitterRef = useSplitterRef();
    return (
        <>
            <Toolbar splitterRef={splitterRef} />
            <Splitter.Group id="editor-layout" splitterRef={splitterRef} className="h-96">
                <Splitter.Panel id="sidebar" defaultSize="25%" minSize="10%">…</Splitter.Panel>
                <Splitter.Separator aria-label="Resize sidebar" className="w-1" />
                <Splitter.Panel id="editor">…</Splitter.Panel>
            </Splitter.Group>
        </>
    );
}
Controlled from code
Gallery

You can also create the model yourself with createSplitterModel() and pass it to the root group's model prop: code that holds it needs no ref at all.

Middleware: veto or rewrite

model.use adds a function around every command, whoever issued it. Return an error without calling next to veto (veto() builds one), assign ctx.payload to rewrite, or call next() and look at the result to observe. Checking ctx.command narrows ctx.payload.

import { createSplitterModel, veto } from "@fragiola/splitter-react";

const model = createSplitterModel();

// while a presentation runs, nobody resizes the panels: not a drag, not a key, not a button
let presenting = false;
model.use((ctx, next) => {
    if (presenting && (ctx.command === "separator.move" || ctx.command === "panel.resize")) {
        return veto("the layout is locked while presenting");
    }
    return next();
});

export function startPresenting() {
    presenting = true;
}

A vetoed drag puts the panels back where the drag started: the engine runs the drag's steps as transient commands, then one final separator.move, and restores the origin when that final one is refused.

Listening: every commit

model.subscribe calls a listener once per committed command, with the state before and after, whether it was transient (a drag step) and its meta:

const stop = model.subscribe((event) => {
    if (event.transient) return; // a drag in progress
    console.log(event.command, event.after.groups);
});

What the adapter runs for the markup (a panel mounting, a prop changing) carries meta: { source: "adapter" } (see Command bus).

States are immutable: an untouched group keeps its object, so before.groups.main === after.groups.main means that group did not change. This is all undo and redo and persistence need.

Transient steps and batches

{ transient: true } marks a step of a gesture. A drag sends one separator.move per pointer move with it, then a final non-transient one; onLayoutChange sees every step, onLayoutCommit only the final one. batch runs a list of commands as one step: they all apply or none does, and listeners receive one event with every step in commands.

model.run("batch", {
    commands: [
        { command: "panel.collapse", payload: { panelId: "sidebar" } },
        { command: "panel.expand", payload: { panelId: "terminal" } },
    ],
});

The full surface

The command bus documents run, can, check, dispatch, use and subscribe, the result and the error codes; Commands is generated from the registry.