Documentation
API: core (@fragiola/splitter)

Commands

Every command the model runs, with its payload and result types and how to run it from code or as JSON. Generated from the registry.

The model runs 15 commands. Each one takes a JSON payload, checked against its JSON Schema, and returns a CommandResult: { ok: true, value }, or { ok: false, error }. Run one with model.run(name, payload) (typed by your registry), or give it as untrusted JSON to model.dispatch({ command, payload }), which validates it first. model.get("commands") returns this same list with the schemas, ready to become tool definitions for an assistant.

Every command can return invalid_payload (the payload does not match its schema, with the path of each problem), vetoed (a middleware refused it), queued (a middleware ran it while another command was running) and middleware_error; each command lists the ones its own rules add: not_found (a group, panel or separator it names is missing) and refused (a rule of the splitter refuses the change).

Sizes in payloads follow React Resizable Panels: a number is pixels, a string carries its unit (%, px, em, rem, vh, vw), and a string without one is a percentage. A layout is always in percent. The payload types below use T, your registry of group and panel ids.

Groups

group.add

Registers a group: panels laid out side by side (horizontal) or stacked (vertical). Its panels are added with panel.add. A nested group names the panel it sits in. A group the loaded document saved takes its saved layout once all its saved panels are added.

Payload (GroupAddPayload<T>)

fieldtyperequireddescription
idstringnothe new group's id (generated when absent)
orientation"horizontal" | "vertical"nohow its panels are laid out (default horizontal)
parentPanelIdstringnothe panel a nested group sits in
disabledbooleannono separator of the group can be used (default false)

Result ({ groupId: string })

fieldtyperequireddescription
groupIdstringyesthe new group's id

Errors: refused, besides those every command can return.

model.run("group.add", {
    id: "main",
    orientation: "horizontal"
});
{ "command": "group.add", "payload": {"id":"main","orientation":"horizontal"} }

group.update

Changes what a group's markup declares: its orientation, the panel it sits in (null: none), whether it is disabled.

Payload (GroupUpdatePayload<T>)

fieldtyperequireddescription
groupIdstringyesthe group to change
orientation"horizontal" | "vertical"nohow its panels are laid out
parentPanelIdstring | nullnothe panel it sits in; null: it is not nested
disabledbooleannono separator of the group can be used

Result ({ groupId: string })

fieldtyperequireddescription
groupIdstringyesthe group changed

Errors: not_found, besides those every command can return.

model.run("group.update", {
    groupId: "main",
    disabled: true
});
{ "command": "group.update", "payload": {"groupId":"main","disabled":true} }

group.remove

Unregisters a group and its panels. Groups nested in its panels stay: they are removed on their own. With keepLayout, a layout the user changed is kept as a saved group (it stays in the JSON document) and comes back when the group registers again with the same panels: a view that unmounts and mounts again keeps its layout.

Payload ({ groupId: GroupIdOf<T>; keepLayout?: boolean })

fieldtyperequireddescription
groupIdstringyesthe group to remove
keepLayoutbooleannokeep the group's layout, when it is not the default one, until it registers again

Result ({ groupId: string; panelIds: string[] })

fieldtyperequireddescription
groupIdstringyesthe removed group
panelIdsstring[]yesthe panels removed with it

Errors: not_found, besides those every command can return.

model.run("group.remove", {
    groupId: "main"
});
{ "command": "group.remove", "payload": {"groupId":"main"} }

group.set-layout

Sets a group's whole layout: each panel's size in percent, by panel id (every panel of the group, no other). Sizes that do not sum to 100 are scaled; each is clamped to its panel's constraints (disabled panels included). Returns the layout applied.

It may run as a step of a continuous gesture: model.run(…, { transient: true }).

Payload ({ groupId: GroupIdOf<T>; layout: Layout })

fieldtyperequireddescription
groupIdstringyesthe group to lay out
layoutobjectyeseach panel's size in percent, by panel id: every panel of the group

Result ({ layout: Layout })

fieldtyperequireddescription
layoutobjectyesthe group's layout after the command

Errors: not_found, besides those every command can return.

model.run("group.set-layout", {
    groupId: "main",
    layout: {
        nav: 25,
        editor: 75
    }
});
{ "command": "group.set-layout", "payload": {"groupId":"main","layout":{"nav":25,"editor":75}} }

group.reset

Resets a group to its default layout: each panel at its defaultSize, the others sharing the rest equally.

Payload ({ groupId: GroupIdOf<T> })

fieldtyperequireddescription
groupIdstringyesthe group to reset

Result ({ layout: Layout })

fieldtyperequireddescription
layoutobjectyesthe group's layout after the command

Errors: not_found, besides those every command can return.

model.run("group.reset", {
    groupId: "main"
});
{ "command": "group.reset", "payload": {"groupId":"main"} }

group.measure

Reports what a group measures on screen, so sizes in px, em, rem, vh and vw resolve without a DOM. The engine runs it as a transient step whenever the group resizes; it is not saved in the JSON. Panels with groupResizeBehavior preserve-pixel-size keep their pixels; the layout is clamped to the constraints the measure resolves.

It may run as a step of a continuous gesture: model.run(…, { transient: true }).

Payload (GroupMeasurePayload<T>)

fieldtyperequireddescription
groupIdstringyesthe group measured
axisSizenumberyesthe group's size along its orientation, in pixels (the sum of its panels' sizes)
fontSizenumbernothe group's computed font size, in pixels (em)
rootFontSizenumbernothe root element's font size, in pixels (rem)
viewportWidthnumbernothe viewport's width, in pixels (vw)
viewportHeightnumbernothe viewport's height, in pixels (vh)

Result ({ layout: Layout })

fieldtyperequireddescription
layoutobjectyesthe group's layout after the command

Errors: not_found, besides those every command can return.

model.run("group.measure", {
    groupId: "main",
    axisSize: 1200,
    fontSize: 16,
    rootFontSize: 16,
    viewportWidth: 1280,
    viewportHeight: 800
});
{ "command": "group.measure", "payload": {"groupId":"main","axisSize":1200,"fontSize":16,"rootFontSize":16,"viewportWidth":1280,"viewportHeight":800} }

Panels

panel.add

Registers a panel in a group, with its constraints as declared (sizes: a number is px; a string carries its unit, %, px, em, rem, vh or vw; a string without one is %). Panels sort by order (their document position), so a panel rendered conditionally lands in its place. The group's layout becomes the saved one once the group holds exactly its saved panels, else the layout the group last had with its panels (the one it leaves is remembered for the panel set it had), else its default layout.

Payload (PanelAddPayload<T>)

fieldtyperequireddescription
idstringnothe new panel's id (generated when absent)
groupIdstringyesthe group the panel belongs to
ordernumbernowhere the panel sits among its group's panels (its document position); default: after the others
minSizenumber | stringnothe smallest size the panel takes when expanded (default 0)
maxSizenumber | stringnothe largest size the panel takes (default 100%)
defaultSizenumber | stringnothe size the panel starts with when no saved layout has one (default: an equal share of what is left)
collapsiblebooleannowhether the panel can collapse below its minimum, to its collapsed size
collapsedSizenumber | stringnothe panel's size when collapsed (default 0)
collapsedThresholdnumber | stringnohow far past its minimum a drag goes before the panel collapses (default: halfway between collapsed and minimum)
disabledbooleannothe panel is resized neither directly nor by resizing its neighbours (code still can)
groupResizeBehavior"preserve-relative-size" | "preserve-pixel-size"nowhen the group resizes, keep the panel's percentage (preserve-relative-size, default) or its pixels (preserve-pixel-size)

Result ({ panelId: string })

fieldtyperequireddescription
panelIdstringyesthe new panel's id

Errors: not_found, refused, besides those every command can return.

model.run("panel.add", {
    id: "nav",
    groupId: "main",
    order: 0,
    minSize: "15%",
    defaultSize: 240,
    collapsible: true
});
{ "command": "panel.add", "payload": {"id":"nav","groupId":"main","order":0,"minSize":"15%","defaultSize":240,"collapsible":true} }

panel.update

Changes what a panel's markup declares: its order or its constraints (null removes one, so its default applies). The layout is clamped to the new constraints.

Payload (PanelUpdatePayload<T>)

fieldtyperequireddescription
panelIdstringyesthe panel to change
ordernumbernowhere the panel sits among its group's panels (its document position)
minSizenumber | string | nullnothe smallest size the panel takes when expanded (default 0); null removes it
maxSizenumber | string | nullnothe largest size the panel takes (default 100%); null removes it
defaultSizenumber | string | nullnothe size the panel starts with when no saved layout has one (default: an equal share of what is left); null removes it
collapsibleboolean | nullnowhether the panel can collapse below its minimum, to its collapsed size; null removes it
collapsedSizenumber | string | nullnothe panel's size when collapsed (default 0); null removes it
collapsedThresholdnumber | string | nullnohow far past its minimum a drag goes before the panel collapses (default: halfway between collapsed and minimum); null removes it
disabledboolean | nullnothe panel is resized neither directly nor by resizing its neighbours (code still can); null removes it
groupResizeBehavior"preserve-relative-size" | "preserve-pixel-size" | nullnowhen the group resizes, keep the panel's percentage (preserve-relative-size, default) or its pixels (preserve-pixel-size); null removes it

Result ({ panelId: string })

fieldtyperequireddescription
panelIdstringyesthe panel

Errors: not_found, besides those every command can return.

model.run("panel.update", {
    panelId: "nav",
    maxSize: "40%",
    minSize: null
});
{ "command": "panel.update", "payload": {"panelId":"nav","maxSize":"40%","minSize":null} }

panel.remove

Unregisters a panel. Its group's layout becomes the saved one when the group now holds exactly its saved panels, else the layout the group last had with these panels (the one it leaves is remembered for the panel set it had, so the panel comes back to it), else the default layout of the panels left.

Payload ({ panelId: PanelIdOf<T> })

fieldtyperequireddescription
panelIdstringyesthe panel to remove

Result ({ panelId: string })

fieldtyperequireddescription
panelIdstringyesthe panel

Errors: not_found, besides those every command can return.

model.run("panel.remove", {
    panelId: "nav"
});
{ "command": "panel.remove", "payload": {"panelId":"nav"} }

panel.resize

Resizes a panel to a size (a number is px; a string carries its unit, %, px, em, rem, vh or vw; a string without one is %). The nearest panels make room within their constraints, those after it first. A size other than % needs the group measured. Code may resize a disabled panel. Returns the size it got, in percent.

It may run as a step of a continuous gesture: model.run(…, { transient: true }).

Payload ({ panelId: PanelIdOf<T>; size: SizeValue })

fieldtyperequireddescription
panelIdstringyesthe panel to resize
sizenumber | stringyesthe size to give it

Result ({ size: number })

fieldtyperequireddescription
sizenumberyesthe panel's size after the command, in percent

Errors: not_found, refused, besides those every command can return.

model.run("panel.resize", {
    panelId: "nav",
    size: "30%"
});
{ "command": "panel.resize", "payload": {"panelId":"nav","size":"30%"} }

panel.collapse

Collapses a collapsible panel to its collapsed size; the panel remembers its size to return to it on expand. Refused when the panel is not collapsible or the other panels cannot take its space. Returns its size, in percent.

Payload ({ panelId: PanelIdOf<T> })

fieldtyperequireddescription
panelIdstringyesthe panel to collapse

Result ({ size: number })

fieldtyperequireddescription
sizenumberyesthe panel's size after the command, in percent

Errors: not_found, refused, besides those every command can return.

model.run("panel.collapse", {
    panelId: "nav"
});
{ "command": "panel.collapse", "payload": {"panelId":"nav"} }

panel.expand

Expands a collapsed panel to the size it had before collapsing (its minimum when it has none), or to the largest size that fits when the other panels cannot make room for all of it. Refused when the panel is not collapsible or nothing can make room. Returns its size, in percent.

Payload ({ panelId: PanelIdOf<T> })

fieldtyperequireddescription
panelIdstringyesthe panel to expand

Result ({ size: number })

fieldtyperequireddescription
sizenumberyesthe panel's size after the command, in percent

Errors: not_found, refused, besides those every command can return.

model.run("panel.expand", {
    panelId: "nav"
});
{ "command": "panel.expand", "payload": {"panelId":"nav"} }

Separators

separator.move

Moves a separator by delta percent of its group: positive grows the panels before it (the start side), negative the panels after it. The panels on the shrinking side give space nearest first, within their constraints; a collapsible panel snaps collapsed or open at its threshold; disabled panels do not change. A drag sends every step from the layout it started from (origin), as a transient step, then once more to commit. Refused when the separator or its group is disabled. Returns the layout applied.

It may run as a step of a continuous gesture: model.run(…, { transient: true }).

Payload (SeparatorMovePayload)

fieldtyperequireddescription
separatorIdstringyesthe separator to move: <beforePanelId>:<afterPanelId>
deltanumberyeshow far to move it, in percent of the group: positive grows the panels before it
originobjectnothe layout the move is measured from (a drag's layout when it started); default: the layout now
source"pointer" | "keyboard"nowhat moves it (default pointer): the keyboard collapses or expands a collapsible panel in one step instead of at its threshold

Result ({ layout: Layout })

fieldtyperequireddescription
layoutobjectyesthe group's layout after the move

Errors: not_found, refused, besides those every command can return.

model.run("separator.move", {
    separatorId: "nav:editor",
    delta: 5
});
{ "command": "separator.move", "payload": {"separatorId":"nav:editor","delta":5} }

separator.update

Changes what a separator's markup declares: whether it is disabled (it cannot resize its panels; they may still resize through another separator) and whether a double click resets its panel to its default size.

Payload (SeparatorUpdatePayload)

fieldtyperequireddescription
separatorIdstringyesthe separator to change: <beforePanelId>:<afterPanelId>
disabledbooleannothe separator cannot be used
resetOnDoubleClickbooleannoa double click resets its panel to its default size (default true)

Result ({ separatorId: string })

fieldtyperequireddescription
separatorIdstringyesthe separator changed

Errors: not_found, besides those every command can return.

model.run("separator.update", {
    separatorId: "nav:editor",
    resetOnDoubleClick: false
});
{ "command": "separator.update", "payload": {"separatorId":"nav:editor","resetOnDoubleClick":false} }

Batches

batch

Runs several commands in order as one atomic step: if any fails, none applies. Emits one change event. Nested batches are flattened. An adapter registers a group and its panels with one batch.

It may run as a step of a continuous gesture: model.run(…, { transient: true }).

Payload ({ commands: BatchEntry<T>[] })

fieldtyperequireddescription
commandsobject[]yesthe commands to run, in order

Result ({ results: unknown[] })

fieldtyperequireddescription
resultsJSON[]yeseach command's value, in order

Errors: those of the commands it runs (the first failure, at its path in commands); nothing applies unless all succeed.

model.run("batch", {
    commands: [
        {
            command: "group.add",
            payload: {
                id: "main"
            }
        },
        {
            command: "panel.add",
            payload: {
                id: "nav",
                groupId: "main"
            }
        },
        {
            command: "panel.add",
            payload: {
                id: "editor",
                groupId: "main"
            }
        }
    ]
});
{ "command": "batch", "payload": {"commands":[{"command":"group.add","payload":{"id":"main"}},{"command":"panel.add","payload":{"id":"nav","groupId":"main"}},{"command":"panel.add","payload":{"id":"editor","groupId":"main"}}]} }