Documentation
API: core (@fragiola/splitter)

Model

createSplitterModel and the model's state, its get and is keys, the types that describe groups and panels, and the pure layout rules behind them.

The model holds every group's panels, their constraints, their sizes and their collapsed state, as plain, frozen, JSON-shaped data that only commands change. It needs no DOM: it runs in Node, on a server and in tests. The outermost Splitter.Group creates one unless you pass yours.

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

declare const saved: SplitterJson | undefined;

const model = createSplitterModel(saved, { createId: (kind) => `${kind}-${crypto.randomUUID()}` });
model.get("layout-by", { groupId: "main" });
model.is("panel-collapsed", { panelId: "sidebar" });

createSplitterModel

createSplitterModel<T>(json?, options?) returns a SplitterModel<T>, typed by your registry T (see Typed data). json is a saved document (see The JSON document); an invalid one throws a SplitterValidationError.

SplitterModelOptions:

optiontypedescription
createIdCreateIdgenerates the id of a group or panel added without one: (kind: IdKind) => string, IdKind being "group" or "panel"; default `${kind}-${n}` (no crypto needed). An id in use is skipped and asked again

The members

Every member is one verb, and every method is bound (it can be passed around on its own):

memberdoes
run(command, payload, options?)changes the state through the middleware chain; never throws on bad input
dispatch(input, options?)run for untrusted JSON { command, payload, transient? }, validated
can(command, payload, options?)whether run would succeed now
check(command, payload, options?)what run would return, without committing
get(key, payload?)reads from the current state
is(key, payload)asks a yes/no question
use(middleware)adds a middleware around every command; returns its remover
subscribe(listener)listens to every commit; returns its remover

run, dispatch, can, check, use and subscribe are on The command bus.

get keys

keypayloadreturns
"state"nonethe whole SplitterState (a new object after every change)
"groups"noneevery registered group, in registration order
"group-by"{ id }a group, or undefined
"panel-by"{ id }a panel, or undefined
"panels-by"{ groupId }a group's panels, in order
"layout-by"{ groupId }a group's layout: each panel's size in percent, by panel id
"panel-size-by"{ panelId }a PanelSize: in percent, and in pixels once its group is measured
"panel-constraints-by"{ panelId }its constraints resolved to percent (ResolvedConstraints)
"separators-by"{ groupId }a group's separators, in order
"separator-by"{ id }a separator by its id (<beforePanelId>:<afterPanelId>)
"separator-values-by"{ separatorId }its SeparatorValues: aria-valuenow, -min, -max
"group-path-by"{ groupId }its path (/g0, /g0/p1/g0)
"panel-path-by"{ panelId }its path (/g0/p1)
"separator-path-by"{ separatorId }its path (/g0/s0)
"splitter-json"nonethe JSON document of the state: what createSplitterModel(json) restores
"commands"noneevery command with its description and JSON Schemas (CommandInfo[])

is keys

keypayloadanswers
"panel-collapsed"{ panelId }the panel is collapsible and at its collapsed size
"panel-collapsible"{ panelId }the panel can collapse
"panel-disabled"{ panelId }no separator resizes it
"group-disabled"{ groupId }none of its separators can be used
"group-measured"{ groupId }the engine reported its size, so every unit resolves
"separator-disabled"{ separatorId }it, or its group, is disabled
"separator-resettable"{ separatorId }a double click on it would reset a panel (never when a panel beside it is disabled)

The key types are ModelGetKey, ModelGetMap<T>, ModelGetPayload<T, K> and ModelGetResult<T, K>, and ModelIsKey, ModelIsMap<T> and ModelIsPayload<T, K>. A key that takes nothing takes NoPayload; QueryArgs<P> makes the payload optional then.

The state

SplitterState:

fieldtypedescription
groupsRecord<string, GroupState>the registered groups, by id
panelsRecord<string, PanelState>the registered panels, by id
pendingRecord<string, GroupJson>saved groups of the loaded document whose panels have not all registered yet

GroupState:

fieldtypedescription
type"group"
idstringits id
orientationOrientation"horizontal" or "vertical"
parentPanelIdstringthe panel a nested group sits in
disabledbooleanno separator of the group can be used
panelIdsstring[]its panels, in order
layoutLayouteach panel's size in percent, summing to 100
measureGroupMeasurewhat the engine measured of it (not saved)
pristinebooleanthe layout is the default one: derived again when a new measure resolves its units
layoutMemoryRecord<string, Layout>the last layout the user gave the group with each other set of panels, keyed by the JSON of the set's sorted panel ids; it comes back when the panels are that set again (not saved)
separatorsRecord<string, SeparatorOptions>what the separators' markup declares, by separator id

PanelState extends PanelConstraints:

fieldtypedescription
type"panel"
idstringits id
groupIdstringits group
ordernumberits document position: panels sort by it, then by when they were added
restoreSizenumberthe size in percent it returns to when it expands
minSize, maxSize, defaultSize, collapsedSize, collapsedThresholdSizeValueits constraints as declared
collapsible, disabledboolean
groupResizeBehaviorGroupResizeBehavior"preserve-relative-size" or "preserve-pixel-size"

SeparatorState (derived, never registered), with SeparatorOptions (what its markup declares, disabled and resetOnDoubleClick):

fieldtypedescription
type"separator"
idstring<beforePanelId>:<afterPanelId>
groupIdstringits group
indexnumberits position among the group's separators
panelIds[string, string]the panels before and after it
disabledbooleanit, or its group, is disabled
resetOnDoubleClickbooleana double click resets its panel

Layout is Record<string, number>. SplitterTypes is the registry shape, AnyTypes the default one (any string id); GroupIdOf<T> and PanelIdOf<T> read their id types.

PanelSize, what panel-size-by and a panel's onResize give:

fieldtypedescription
percentagenumberthe size in percent of its group
pixelsnumber | undefinedthe size in pixels; undefined until its group is measured

Resolved constraints and measures

ResolvedConstraints is a panel's constraints in percent of its group, what the rules use: a size that cannot be resolved yet counts as absent.

fieldtypedescription
panelIdstringthe panel
minSize, maxSizenumberits limits in percent (0 and 100 when absent)
defaultSizenumber | undefinedits default size in percent
collapsibleboolean
collapsedSizenumberin percent
collapsedThresholdnumber | undefinedin percent
disabledboolean
groupResizeBehaviorGroupResizeBehavior

GroupMeasure, what group.measure reports:

fieldtypedescription
axisSizenumberthe group's size along its orientation in pixels: the sum of its panels
fontSizenumberthe group element's font size (what em resolves against)
rootFontSizenumberthe root element's font size (rem)
viewportWidth, viewportHeightnumberthe viewport (vw, vh)

Units

exportdoes
SizeValuea declared size: a number (pixels) or a string ("30%", "240px", "15rem", "2em", "40vh", "25vw", or "30" for percent)
SizeUnit"%" | "px" | "em" | "rem" | "vh" | "vw"
parseSize(size)splits a size into a ParsedSize (value, unit), or undefined when invalid
sizeToPixels(size, measure)a size in pixels, or undefined when the measure it needs is missing
sizeToPercentage(size, measure)a size in percent of its group, or undefined when it cannot resolve yet

The pure rules

The model's rules are exported as pure functions (they never mutate their input), for tools, tests and adapters of your own. Each takes ResolvedConstraints in panel order.

exportdoes
defaultLayout(constraints)the default layout: each defaultSize, the rest shared equally, validated
validateLayout(layout, constraints)the valid layout closest to layout: scaled to 100 and clamped
normalizeLayout(layout, panelIds)a layout scaled to sum to 100, without constraints
adjustLayoutByDelta(input: AdjustLayoutByDeltaInput)the layout after a separator moves by delta percent (initialLayout, prevLayout, constraints, pivotIndices, trigger)
resizePanel(input: ResizePanelInput)the layout after one panel takes size (layout, constraints, panelId, size, allowPartialSize)
validatePanelSize(input: ValidatePanelSizeInput)the size a panel takes when size is asked: snapped at its collapse threshold, clamped (constraints, prevSize, size, overrideDisabled)
preservePixelSizes(input: PreservePixelSizesInput)the layout after the group resized, preserve-pixel-size panels keeping their pixels (layout, constraints, prevAxisSize, nextAxisSize)
resolveConstraints(panelId, declared, measure)a panel's PanelConstraints resolved to percent
separatorValues(layout, constraints, index)the SeparatorValues of the separator after panel index: panelId, valueNow, valueMin, valueMax

Their input types are AdjustLayoutByDeltaInput, ResizePanelInput, ValidatePanelSizeInput and PreservePixelSizesInput.

ResizeTrigger ("pointer" \| "keyboard" \| "code") says what started a change: a pointer snaps a collapsible panel at its threshold, the keyboard collapses it in one step, and code may resize a disabled panel.