Documentation
Concepts

Model and engine

The model holds every group's panels, sizes and rules, and the engine is those groups on screen. Both answer the same five verbs, from run to is.

Behind the primitives are two objects. The model is the layout as data: every group, its panels, their constraints, their sizes and which are collapsed, with the rules that keep them valid. It needs no DOM. The engine is the model's groups on screen: it measures them, runs the pointer drags and the keys on their separators, and answers what depends on the DOM. The outermost Splitter.Group creates both unless you pass a model; every group nested in it joins them.

One pattern on both

Each object has the same five verbs. Each takes a key and a payload:

verbmeanson the modelon the engine
rundo itmodel.run("panel.collapse", { panelId }): a commandengine.run("measure", {}): a screen action
cancould I? (a boolean)model.can("panel.expand", { panelId })engine.can("focus-separator", { separatorId })
checkwhat would happen?model.check("panel.resize", { panelId, size: "30%" })engine.check("measure", { groupId })
getread itmodel.get("layout-by", { groupId })engine.get("direction-by", { groupId })
isyes or no?model.is("panel-collapsed", { panelId })engine.is("group-dragging", { groupId })

Both also have use (a middleware), subscribe (a listener) and dispatch (run for untrusted JSON). Keys are kebab-case and typed; Model and Engine list them all.

Inside a group, useSplitter() returns both, with the enclosing group's id:

import { useSplitter } from "@fragiola/splitter-react";

export function CollapseButton({ panelId }: { panelId: string }) {
    const { model } = useSplitter();
    const collapsed = model.is("panel-collapsed", { panelId });
    return (
        <button
            type="button"
            disabled={!model.can(collapsed ? "panel.expand" : "panel.collapse", { panelId })}
            onClick={() => model.run(collapsed ? "panel.expand" : "panel.collapse", { panelId })}
        >
            {collapsed ? "Show" : "Hide"}
        </button>
    );
}

A component that reads the model this way re-renders when its parent does; to follow a value as it changes, use the callbacks (onLayoutChange, onCollapse, onResize) or model.subscribe. Outside the group, the external ref gives you the same object.

Reading a key

A key and its payload read as one sentence. A command has a dot, <entity>.<verb> (panel.resize, group.set-layout); an engine action never has one (measure, focus-separator). A field holding an id is <entity>Id (panelId, groupId, separatorId), except an entity's own id. A get key names its result and ends in -by when it takes an id (panel-by { id }, layout-by { groupId }); one that takes nothing has a plain name (groups, splitter-json). An is key is the question after "is": panel-collapsed, group-measured.

What lives where

questionasksbecause
a panel's size, its constraints in percent, whether it is collapsedthe modelthey are data: the rules need no DOM
a separator's aria-valuenow, -min, -maxthe model (separator-values-by)the same rules
the separator's ARIA attributes with the panel's DOM idthe engine (separator-aria-by)it knows the elements
a group's direction (ltr or rtl), what is draggingthe engineonly the DOM says
how many pixels a group measuresthe model, once the engine reported it (group.measure)so px, em, rem, vh and vw resolve without a DOM

The engine changes the model only by running commands, so a middleware sees a drag exactly as it sees a button: separator.move steps marked transient, then one final commit. See The model and commands.

Without React

The core runs anywhere. A model in Node, with no engine, applies the same rules:

import { createSplitterModel } from "@fragiola/splitter";

const model = createSplitterModel();
model.run("batch", {
    commands: [
        { command: "group.add", payload: { id: "main" } },
        { command: "panel.add", payload: { id: "nav", groupId: "main", minSize: "20%" } },
        { command: "panel.add", payload: { id: "editor", groupId: "main" } },
    ],
});
model.run("panel.resize", { panelId: "nav", size: "10%" }); // clamped to its minimum
model.get("layout-by", { groupId: "main" }); // { nav: 20, editor: 80 }