LayoutEngine

"One layout on screen: the main layout's, or a popout window's (one engine per window). It measures the elements an adapter registers, positions tab panels over their content area (structural style only), owns the moveable elements that host tab content, and runs the drag and drop and the popout windows. It never changes the model except through commands."

In React you never create one: Dockable.Root does, and useDockable() gives you the engine of the window your component renders in. An engine has the model's verbs, for what only the screen can do: the model changes and reads the layout, the engine acts on windows, focus and measuring, and reads view facts. Where to go for what: Model and engine.

const { engine } = useDockable<Types>();
if (engine.can("popout", { nodeId: tab.id })) engine.run("popout", { nodeId: tab.id });
const panelId = engine.get("tab-panel-dom-id-by", { tabId: tab.id }); // for aria-controls

The verbs are bound, like the model's. There is one engine per window, and the main layout's owns the popout windows and the drag in progress, but an app never has to pick one: what concerns the whole page (whether popouts are supported, popping out, docking back) works from any engine, which hands it to the main one.

Running screen actions

engine.run(action, payload) performs what only the screen can do. An action's key has no dot, so it never reads as a command (tab.close): a command changes the layout through model.run, and engine.run("tab.close", …) does not compile. The actions that change the layout do it by running commands, so your middleware sees and can refuse them; can and check dry-run them.

Closing a window from the browser runs window.close, which docks its tabs back the same way. See Popouts and Dockable.PopoutTrigger.

Reading view facts

engine.get(key, payload) reads what the screen knows and the model does not. As on the model, a key names what it returns, and one that takes an id ends in -by, completed by the payload's field (engine.get("tab-panel-dom-id-by", { tabId })):

engine.is(key, payload) answers a yes/no question about the view:

The keys are typed (EngineActionKey, EngineGetKey, EngineIsKey, with their maps EngineActionMap, EngineGetMap and EngineIsMap, and EngineActionPayload<K>, EngineActionResult<K>, EngineGetPayload<K>, EngineGetResult<K>, EngineIsPayload<K>): an unknown key or a wrong payload does not compile.

Creating one

createLayoutEngine<T>(options: LayoutEngineOptions<T>): LayoutEngine<T> creates the engine of the main layout of model. Popout windows get their engines from the main one (createPopoutEngine): an adapter never creates those.

LayoutEngineOptions<T>:

idScope exists because default node ids (tab-1, window-1) are the same in every model: two layouts on one page would otherwise emit the same aria-controls and aria-labelledby ids and the same popout window names. It defaults to a page-unique d<n>-; Dockable.Root passes React's useId(), so server and client agree. Popout engines share their main engine's scope.

Settings

engine.adapter.setOptions(settings: LayoutEngineSettings<T>) updates the options an adapter may change on every render. LayoutEngineSettings<T> is the subset of LayoutEngineOptions<T> that can change: realtimeResize, tabDragSpeed, popout, onExternalDrag and dragGroup. An option left out goes back to its default. model, measure and idScope are fixed for the engine's life.

For adapter authors: engine.adapter

Everything else is on engine.adapter, a LayoutEngineAdapter<T>: the render cycle, element registration, the moveable elements, measured geometry, overlay borders, and the drag and popout machinery. A framework adapter (React today; Angular and Vue next) calls it; an app never needs it, and the examples never touch it.

The render cycle

The adapter's side of the cycle:

1. call prepare() before rendering a layout (paths and size ranges are computed as the render reads them);
2. render the structure, registering elements with registerMeasurable, registerTabPanel and registerSplitter;
3. run engine.run("measure-and-position") after every commit (a layout effect in React);
4. re-render when the revision from subscribe/getSnapshot changes.

"The engine never renders geometry through the adapter: panel positions are written directly, so a resize or splitter drag does not require a re-render." A transient row.resize (a realtime splitter drag) is applied by writing flex-grow on the registered elements, with no re-render at all; the lasting command at the release re-renders once.

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

const model = createModel<Types>(json);
const engine = createLayoutEngine({ model });
const { adapter } = engine;
adapter.attachRoot(rootElement);

function render() {
    adapter.prepare();
    // … build the DOM, then register each element by node id:
    adapter.registerMeasurable(tabset.id, "tabset", tabsetElement);
    adapter.registerMeasurable(tabset.id, "tabsetcontent", contentElement);
    adapter.registerTabPanel(tab.id, panelElement);
    adapter.attachMoveable(tab.id, panelElement);
    engine.run("measure-and-position");
}
adapter.subscribe(render);
render();

Registration by id

Elements are registered against node ids, never node objects: a node is a new object in every state that changes it, its id is not.

Derived view data

Moveables

The content of a tab lives in a moveable element that the engine owns, keyed by tab id. It is re-parented with appendChild, never cloned, so moving a tab between tabsets, borders and popout windows never remounts its content.

MoveableOptions (how a panel hosts its content, a view option rather than layout state; the scrollable and remountInWindow props of Dockable.Panel):

Popouts

The main engine owns the popout windows: one native window per window layout of the state, opened while the main engine is attached. Apps pop out and dock back with engine.run; an adapter reaches the windows themselves through the manager.

Interaction

Geometry

The core never touches the global document or window: all DOM access goes through the root element's ownerDocument and defaultView, which is why the same engine runs inside a popout window.

The document and window the layout renders in are view facts any code may need: engine.get("owner-document") and engine.get("owner-window").

Paths

The data-layout-path scheme, as functions: every adapter emits the same values, so e2e selectors work across frameworks. See Layout paths.

Attributes

Types

Drag and drop

The drag-and-drop machine lives in the core: one DragDropManager per engine, working on native drag events that the engine listens to on its root, so the same code path runs in a popout document. The drag in progress is page-wide (a static DragState), so a drag crosses the layouts and windows of a model, and, with a drag group, of other models.

A drop resolves in two steps: the geometric candidates under the pointer (open overlay borders, the root row's edge bands, the maximized tabset or the tabsets under the pointer, then the border strips and open border panels), each turned into the command the drop would run (tab.move, tabset.move, or tab.add for a new tab) and asked of model.can. The first accepted candidate is the target; the first refused one is reported as refused (data-drop-refused). So a middleware veto refuses a drop: see Restricting drops. The drop runs that command through model.run.

Every Dockable drag sets DRAG_TYPE ("application/x-dockable") on its data transfer, and the manager claims only the events that carry it: another library's drag passes through, or goes to onExternalDrag. Every drop and dragend in the document ends the page's drag, even one whose propagation your content stops: the manager listens in the capture phase.

DragDropManager

Static members, for the page:

Members of a layout's manager (engine.adapter.getDragDropManager()):

Whether a drag is over this layout is getIndicatorState().dragging.

DragState

The drag in progress; there is one for the page, shared by every window of a model.

Drag types

DropIndicatorSnapshot, what a drop indicator shows (the same object until it changes; the React Dockable.DropIndicator renders it):

Splitters

SplitterController is the headless behaviour of one splitter: the splitter before child index (1-based) of a row, or a border's splitter. The adapter forwards native pointer and keyboard events and renders the ARIA values and state. It runs row.resize or border.resize: transient on every move of a realtime drag, then one lasting command on release. Without realtime resize, it exposes the bounded preview offset instead, and commits on release.

createSplitterController<T>(engine, nodeId, index) creates one; useSplitter does it for you.

SplitterAria, the ARIA attributes of a splitter (role="separator"):

SplitterControllerState, the drag state of a splitter:

Keyboard

The configurable command shortcuts. Dockable.Root takes a KeyMap as keyMap; see Keyboard.

KeyMap, bindings as "Ctrl+Shift+Key" strings (modifiers in any order, key compared case-insensitively against KeyboardEvent.key); an explicit undefined disables a shortcut:

Tab overflow

The arithmetic behind registerTabList: which tabs of a strip fit, and which go to an overflow menu. Dockable hides the tabs that do not fit (keeping the selected one) instead of scrolling the strip. See Tab overflow.

computeTabOverflow(input: TabOverflowInput): TabOverflowResult splits a strip's tabs into the visible and the hidden ones. When every tab fits, all are visible. Otherwise the tabs fit from the start into available - reserve, stopping at the first that does not fit; when the selected tab is not among them, tabs are taken off the end until it fits, and it is shown in its place. The selected tab always shows, even alone in too small a strip; with no selection, the first tab does.

TabOverflowInput (sizes in px along the strip's axis):

TabOverflowResult: