Layout API Reference

API reference › The dashboard layout

All 29 pages Everything on one page → Developer guide →

The dashboard layout

modules/layout is an opt-in reconfigurable dashboard surface: a cell grid inside an element, and a set of windows placed on it that a user can move, resize and close - by drag or by keyboard. It is the thing a customer would otherwise reach for GridStack or react-grid-layout to get, which means a second dependency, a second sizing model, and a seam where the viewers in it do not resize properly.

It is payload-agnostic, and that is the whole design. A window body is a div with an id. The module creates it, sizes it, and never reads or writes its contents - it does not import createGrid, does not know what a payload is, and never calls into one. What it does instead is emit window:resized with the measured content box, which is the contract. That rule is what keeps the whole module to about 17,500 bytes gzipped (measured on the built bundle: its own code over a shared module runtime of roughly 2KB) and what makes it usable for a payload we have not written yet.

import { createLayout } from '@toclocoinc/lattice-grid/modules/layout';

const layout = createLayout(document.querySelector('#dash'), {
  columns: 12, rows: 8, gap: 8,
  overflowX: 'static', overflowY: 'scroll', rowHeight: '160px',
  windows: [
    { id: 'pipeline', title: 'Pipeline', xPos: 1, yPos: 1, xSize: 6, ySize: 4,
      movable: true, resizable: true, closable: true },
    { id: 'trend', title: 'Trend', xPos: 7, yPos: 1, xSize: 6, ySize: 4,
      movable: true, resizable: true },
  ],
  onWindowResized: ({ id, width, height }) => redraw(id, width, height),
});

// The module made the container; you fill it and you own what is inside it.
createGrid(layout.payload('pipeline'), { rowKey: 'id', rows, columns });

Two independent overflow axes, not one setting. overflowX and overflowY are each 'static' or 'scroll', because a dashboard that scrolls both ways is ordinary and a single enum cannot express it. The difference is what happens to a track's size. A static axis divides the mounted element with minmax(0, 1fr) - never a bare 1fr, whose implicit auto minimum lets one stubborn payload drag a track past the container. A scrolling axis repeats a fixed track (columnWidth / rowHeight) and the canvas extends past the viewport, which then scrolls. That is the owner's "maintaining their sizing", and it is the difference between this and flex-wrap: measured in a real browser, ten 200px columns in a 600px host paint at 200px each over a 2000px canvas, and shrinking the host to 300px leaves the column at 200px and scrolls further.

Spacing takes a real CSS length. gap, padding, columnWidth and rowHeight each accept a number (pixels), or a string: '200px', '25%', '1fr', '2rem', '10vh'. Percentages that sum past 100 are allowed to overflow and scroll rather than being silently scaled down, which is the honest outcome. Anything outside that vocabulary - including calc() and var() - is refused by name with one warning and replaced by the default, because the value is written into an inline style.

Rearrangement. compact: 'vertical' (the default) pushes displaced windows down and then pulls everything up into whatever space that left, so a window dropped into empty space falls to the top of its column - window:moved carries both to (where it was asked to go) and landed (where it actually ended up). compact: 'none' keeps every window exactly where it is put, and enforces non-overlap instead of compacting it away: a resize stops at the nearest neighbour’s edge with the ghost showing the clamped size, a move that would land on a neighbour snaps back, and overlapping placements handed to config.windows or setLayout() are repaired - the later windows move to the next free cells, with one warning naming them. compact: 'horizontal' floats windows left into vacated space instead, so dragging a window out of a row closes the hole sideways rather than leaving it open. It is a third value, not a second pass over the other axis: one gravity direction, never two, because two directions each vacate space the other wants and the arrangement would then depend on which ran last. It settles windows in a canonical left-to-right, then top-to-bottom order, exactly mirroring vertical's top-to-bottom, then left-to-right, so the result depends only on where the windows are and never on the order they were declared or dragged in - the same guarantee vertical has always made, now made on both axes and asserted over all 720 declaration orders of a six-window dashboard on each axis. A value that is none of the three warns once, naming what it was given, and falls back to 'vertical'. The axis a mode compacts along is the axis that can overflow: under 'horizontal' a window that genuinely does not fit the columns settles in an implicit track and can be clipped on a static horizontal axis - exactly as a 'vertical' dashboard can be clipped past its rows on a static vertical axis today. overflowX: 'scroll' is to 'horizontal' what overflowY: 'scroll' is to the default.

Keyboard, to the same standard as the drag. Every movable and resizable window carries a focusable handle running the full grab / move / drop / cancel model the kanban board established: Space or Enter grabs, the arrow keys move a tentative placement, Enter drops it through the same beforeWindowMove gate the pointer drag uses, and Escape cancels. A polite live region announces every step - grabbed, each tentative position with its column and row, dropped, cancelled, and reverted when a handler vetoes the drop - and focus returns to the handle afterwards. A window with chrome: false still gets a handle, because a movable window a keyboard user cannot move is not movable.

An “Edit layout” button, without rebuilding the dashboard. closable, movable and resizable also take a layout-level default, so unlocking a twelve-window dashboard is one setting rather than twenty-four, and setInteractive(true|false|{movable, resizable, closable}) changes that default at runtime - unlock, let the user rearrange, lock again and save getLayout(). Nothing is destroyed and nothing is rebuilt, so every grid, chart and board mounted in a window survives the toggle untouched. The asymmetry is deliberate: you can always take a capability away; you can never grant one where the developer said no. setInteractive(false) locks every window, including one whose own spec says movable: true, so a dashboard hard-locks in a single call without auditing twelve window specs; setInteractive(true) unlocks only the windows that never opted out, so a masthead declared movable: false stays pinned. Both halves of the enforcement move together - the handles a window renders and the checks the pointer and keyboard paths make, because removing a handle stops a mouse while only the gesture check stops a keyboard user already standing on one. config.movable: false and setInteractive(false) are deliberately not the same thing: the config states the default for windows that declare nothing - and false is already that default, so it takes nothing away from a window that declared movable: true - while setInteractive(false) is an active lock that pins every window whatever its own spec says. getInteractive() reports all three states rather than two: undefined where no layout-level default is in force, true, or false for a lock. Reporting “unset” as false would read correctly and round-trip wrongly, so setInteractive(getInteractive()) is a no-op in every state, and a key carrying undefined means “leave this capability alone”. Interactivity is a mode, not part of the arrangement: getLayout() does not carry it, setLayout() does not read it, and no event fires. A locked layout is not a read-only dashboard: the module creates the payload container and never reads or writes its contents, so a grid inside a window is made read-only with the grid's own settings - a dashboard that must not be edited is two decisions, not one.

Which payloads re-lay-out on window:resized, honestly. The grid and the chart each own a ResizeObserver and respond correctly; the Gantt does too since 1.52.0; kanban and KPI do no JS work at all on a resize and need none, because they reflow by CSS construction (a kanban column keeps its 280px and the board starts scrolling). Every one of those is measured in test/layout-browser.test.js rather than asserted, including a grid column declared as a percentage (layout: { width: '50%' }), which follows the window: half of the viewport at 800px, half of it again at 400px.

Idle cost, measured. A twelve-window dashboard is indistinguishable from a page with no layout module on it at all. Over 8 seconds of real Chrome (bench/layout-idle.mjs), twelve windows with empty payloads, twelve independent live grids in them, and a single lone grid with no layout module all sit in the same few-millisecond band - under a tenth of one percent of a core. They are not separated here because they cannot be: seven runs across two machines land between 3.1ms and 9.0ms and the ordering between them inverts run to run, so a stated delta would be reporting the noise floor. The module adds no timer, no frame loop and no polling, and owns exactly one ResizeObserver for the whole layout rather than one per window. The one figure that is a result rather than noise is not this module's: twelve grids derived from one shared parent filtered at 20Hz cost 3,155-3,409ms over the same 8 seconds - several hundred times the quiet band, and stable across every run - because the engine's repaint listener for a derived source's rows:changed calls the renderer directly and bypasses grid.updates.pause(). The bench reports the size of that gap rather than leaving it inferred.

Closing a window does not destroy its payload. window:closed hands the payload container back; whatever you mounted inside it is yours to destroy. Stated plainly because a leaked grid per closed window is the obvious failure, and this module has no way to know that a div contains something with a destroy().

Not in v1: per-frame drag events; and responsive breakpoints - a twelve-window dashboard on a phone is unsolved, and this does not pretend otherwise. Server-side persistence is the host's, with getLayout().

Nesting is not a limitation, because a payload is an ordinary container. A window's payload is a plain div the module creates, sizes and never reads, so anything composes into it exactly as it would into any other element - including another createLayout dashboard, or a modules/tabs strip for tabbed windows. Neither is a special case this module wires up; both are the ordinary consequence of being payload-agnostic, and both are proved by test rather than asserted from the design (test/layout.test.js's two composition tests).

Placement, compaction and a saved arrangement, executed

createLayout needs a real host element, the same way createGrid does, so this executed example reaches for the same in-tree DOM test double the suite runs the renderer against headlessly (packages/dom/src/renderer/testdom.js). demo/layout.html is the browser version, with a real grid, chart and KPI rail in three windows that you can drag, resize with the keyboard, close, save and restore.

const { createTestDom } = await import('../packages/dom/src/renderer/testdom.js');
const { root } = createTestDom();
const { createLayout } = await import('../packages/modules/layout/index.js');

const layout = createLayout(root, {
  columns: 4, rows: 4,
  windows: [
    { id: 'a', title: 'A', xPos: 1, yPos: 1, xSize: 2, ySize: 1 },
    { id: 'b', title: 'B', xSize: 2, ySize: 1 },   // no coordinates: auto-placed
  ],
});
const shape = () => layout.getLayout().windows.map((w) => `${w.id}@${w.xPos},${w.yPos}`).join(' ');

const placed = shape();                        // B landed in the first free cell: 3,1
const saved = JSON.parse(JSON.stringify(layout.getLayout()));

layout.move('a', { xPos: 3, yPos: 1 });        // drop A on top of B; one layout:changed fires
const pushed = shape();                        // B is pushed down to 3,2

layout.setLayout(saved);                       // the saved arrangement round-trips
const restored = shape();

layout.select('a');                            // programmatic select: rings and focuses A
const sel = layout.selected();                 // read the selection back: 'a'

const payload = layout.payload('a').id;        // the container you fill: 'a-body'
layout.destroy();
return [placed, pushed, restored, payload, sel].join('|');

Type reference

Generated from the type declarations, so it always matches the release. Each surface lists its properties, its methods and the events it raises as three tables; an option or value type lists its members once.

The dashboard layout

LayoutWindow

One window on the cell grid. Deliberately **not** named `WindowSpec`: that name is already taken by the rolling-statistics window (`{ kind: 'count'|'time'|'session', span, size }`) and reusing it would put `kind: 'session'` next to a dashboard pane.

LayoutInteractive

The three capabilities a layout-level default and `setInteractive()` cover. These are the layout **defaults**, not the per-window resolution: a window that declared `movable: false` stays pinned whatever these say. Three values, not two. `undefined` means no layout-level default is in force and each window's own flag decides; `true` unlocks everything that did not opt out; `false` is an active lock. Reporting `undefined` as `false` would read correctly and round-trip wrongly, so it is reported as it is.

LayoutSnapshot

The plain, JSON-safe arrangement `getLayout()` returns and `setLayout()` takes.

LayoutPlacement

A cell placement, as carried on the move and resize events.

LayoutMoveEvent

The payload of `window:moved`, `beforeWindowMove`, `beforeWindowResize`.

LayoutResizeEvent

The payload of `window:resized` - the measured **content box** of the payload container, not a cell count. Emitted when the container genuinely changes size, including on the opening frame; never with a zero box.

LayoutCloseEvent

The payload of `window:closed` and `beforeWindowClose`.

LayoutWindowMovedEvent

`window:moved`: a window finished moving. The past-tense event, so there is no `preventDefault` on it - the move has happened, and `beforeWindowMove` ({@link LayoutMoveEvent}) is where it could have been stopped.

LayoutWindowClosedEvent

`window:closed`: a window was removed and its payload container handed back. The past-tense event: no `preventDefault`, because the window has gone. The container is **not** destroyed - whatever the host mounted in it is the host's to tear down.

LayoutMoveCancelledEvent

`windowMove:cancelled` and `windowResize:cancelled`: a `before…` handler refused the gesture. A notification, so it carries no `preventDefault`.

LayoutCloseCancelledEvent

`windowClose:cancelled`: a `beforeWindowClose` handler refused the close. A notification, so it carries no `preventDefault`.

LayoutEventPayloads

What a handler receives, per layout event.

LayoutChangedEvent

The payload of `layout:changed`: the whole arrangement, plus what moved it.

LayoutConfig

Dashboard layout configuration.

Layout

A reconfigurable dashboard: a cell grid inside an element, and a set of windows on it that a user can move, resize and close by pointer or by keyboard. The module is **payload-agnostic**: a window body is a container with an id, which this module creates and sizes and never reads. It tells a payload it was resized by emitting `window:resized`; it never calls into one, because it cannot know what one is.

Properties

Methods

Events