Shell API Reference

API reference › The application shell

All 25 pages Everything on one page → Developer guide →

The shell module

modules/shell is an opt-in layout container: a tree of cells nested as rows and columns to any depth, sized by pure CSS flexbox, in its own bundle that grows grid core by nothing. It replaces DHX Layout in DemandFlow and is a sold Lattice feature. The main owner pain it removes is asynchronous redraw: when createShell(el, config) returns, every cell element is already in the document and already sized - a fixed size is a flex-basis, gravity is a flex-grow, and min/max are the CSS min-*/max-* properties - so there is no awaitRedraw(), no deferred JS paint and no requestAnimationFrame to wait on. A third-party widget mounted into getCell(id).el on the very next line measures a non-zero size in the same synchronous task, and a window resize reflows by CSS alone, with no listener or timer in the module.

import { createShell } from '@toclocoinc/lattice-grid/modules/shell';

const shell = createShell(document.querySelector('#shell'), {
  type: 'line',                  // separators: 'line' | 'wide' | 'space' | 'none'
  rows: [
    { id: 'nav', width: 220 },   // fixed px, never grows
    { id: 'main', gravity: 1,    // takes the remaining space
      cols: [
        { id: 'header', height: 40 },
        { id: 'body', gravity: 1 },
      ] },
  ],
});

shell.getCell('body').el.appendChild(widget);  // already sized
shell.destroy();

One element per cell. A cell is the flex item of its parent and, when it declares nested rows or cols, the flex container of its children - getCell(id).el is that single element, so a leaf cell is a plain block a widget fills and a nested cell already lays its own children out. Every size is an inline style, never a class, so the geometry a test reads is the geometry a host gets: width/height take a pixel number or any CSS length string ('30%', '12rem', 'calc(…)'); a cell with a fixed size never grows, and the gravity of the cells without one shares the space that is left after the fixed sizes are subtracted, in proportion. minWidth/maxWidth/minHeight/maxHeight clamp a cell exactly as the CSS properties do, padding pads the cell (its widget mounts inside the padding), align is the cell's align-self, and css is an object of camelCase properties or a string of declarations written straight onto the element - never parsed as HTML.

Headers and collapse. A cell may carry a header - text, a custom element to mount, or an image via headerImage/headerIcon - drawn as a strip headerHeight tall (default 32) above the content, with the cell's padding pushed down into the content area so the header spans the cell edge-to-edge. A collapsable cell gets a collapse control in that strip and collapse()/expand()/toggle() on its handle; collapsed: true starts it folded. Folding writes one thing - the cell's own flex-basis becomes the strip height - so the neighbours take the space and expand() restores the exact previous size, with the content element back in flow and measurable on the very next line: the transition is one synchronous pass of inline styles, no animation and no deferred paint. A folded strip among rows runs its text vertically (writing-mode: vertical-rl) so a narrow strip still reads. The change is gated and reported: cancellable beforeCollapse/beforeExpand (a handler calls preventDefault(reason?) or returns false) precede the move, and afterCollapse/afterExpand follow it, all subscribed through shell.on(name, fn). The control's accessible label is translated through config.messages, which the module resolves with its own English fallback.

Separators are the shell's type, not markup. 'line' draws a thin border between cells, 'wide' a thick one, 'space' an even gap, and 'none' (the default) nothing - each reads a --lattice-* theme token with a literal fallback, so a shell inside a themed grid inherits the theme and one on a bare page still draws, dark mode included. The interactive pieces the module adds are the collapse control on a collapsable cell - a native <button>, so Enter and Space toggle it and its aria-expanded/aria-label announce the state - and the splitters below; destroy() empties the element, removes the class the module added, restores the host's own inline style and drops every cell record and splitter listener, and the host still owns the element.

State round-trips the whole arrangement, content untouched. getState() snapshots the separator, the root padding/css and every cell's sizes, gravity, min/max and mutable collapsed/hidden/selected flags as one JSON-able object. setState(state) re-resolves and re-mounts it through the very same path a fresh config takes, then moves the exact DOM nodes a host mounted into each cell back into the matching cell by id - re-parented, never cloned - and fires stateChange with the state now live; on(name, fn)/off(name, fn) subscribe to it. The same snapshot is what the htmx data-lattice-shell history save/restore carries, and what the React, Vue, Svelte and Angular shell components re-emit, so a save/restore round-trip reproduces the layout exactly while a host's widgets survive it.

A cell marked resizable: true gets a splitter, not a separator. The splitter sits on the cell's trailing border and resizes that cell and its next sibling together, within both cells' minWidth/maxWidth (or minHeight/maxHeight on a column axis). It is a focusable role="separator" with aria-valuenow/aria-valuemin/aria-valuemax: drag it (mouse or touch) or focus it and use the arrow keys to step, Home/End to jump to the range, and double-click to restore the configured sizes. Every gesture runs through the shell's events - beforeResizeStart (cancellable: call event.preventDefault(reason) or return false to keep the sizes), then resize as it moves, then afterResizeEnd when it stops, each carrying the two cells' ids and their sizes - observed with on(name, fn) and detached with off(name, fn).

Content that never dies. cell.attach(content) takes a Lattice view (a grid, Gantt, scheduler, chart or layout), a DOM element or an HTML string (converted once), and the cell keeps the same element for its whole life: hide/show, collapse/expand, tab switches, resizes and moving the cell never re-render, innerHTML or destroy it, so a third-party widget's state and listeners persist. cell.getWidget() reads it, cell.detach() hands it back intact, and only detach() or destroy() releases it. Optional onHidden/onVisible hooks - in attach's options or on a tab - fire when the content hides and shows, and an attached Lattice view is re-measured on becoming visible through its own resize/refresh method, never a DHX-era paint(). A cell may instead declare tabs: [{ id, label, content? }] to render a keyboard-operable tab strip (ARIA tabs, arrow keys) with one attached content per tab, each preserved across switches; cell.getTab(id) reaches a tab and shell.on('tabChange', …) fires { cellId, tabId, previousTabId } on every switch.

Live structure. The tree is not frozen at creation. cell.hide() sets the cell's flex item to display:none, so its space is handed to its neighbours by CSS reflow alone; cell.show() restores the exact display the cell was built with, and cell.isVisible() reads the current state - a cell may also start hidden with hidden: true. shell.addCell(parentId, config, index?) builds a new cell through the view's one synchronous pass, so its element is already in the document and sized when the call returns (mountable on the very next line), and shell.removeCell(id) removes a cell and its whole subtree live, releasing every piece of content inside it (detached, never destroyed) and handing the space back. cell.progressShow() overlays an indeterminate spinner on one cell without touching its size or content, cell.progressHide() clears it, and a cell declared progressDefault: true starts with the overlay on. Every mutation is gated by a cancellable before* event and announced by an after* event - beforeHide/afterHide, beforeShow/afterShow, beforeAddCell/afterAddCell, beforeRemoveCell/afterRemoveCell - and a handler that calls event.preventDefault(reason) or returns false vetoes the change, which then happens not at all.

DHX Layout migration

DemandFlow moves from dhtmlx Layout to modules/shell. The arrangement is the same shape - nested rows/cols of named cells - but the shell is synchronous, token-themed and state-serialisable where DHX Layout is an imperative widget API.

Three levels, state round-trip, and teardown, executed

A row of a fixed nav and a gravity main, the main split into a fixed header and two gravity columns, walked, snapshot-and-restored through getState()/setState(), and torn down over the in-tree DOM test double - the sizes themselves are asserted against real Chrome in test/shell-browser.test.js.

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

const { root, document: doc } = createTestDom();
const shell = createShell(root, {
  type: 'line', padding: 4, css: { position: 'relative' },
  rows: [
    { id: 'nav', width: 200 },
    { id: 'main', gravity: 1, cols: [
      { id: 'top', height: 40, padding: 8 },
      { id: 'body', gravity: 2, minWidth: 50, maxWidth: 900 },
      { id: 'foot', gravity: 1 },
    ] },
  ],
});

const tag = shell.getCell('nav').el.tagName;        // DIV - the content element itself
const parent = shell.getCell('body').getParent().config.id; // 'main' - the cell that nests it
let walked = 0;
shell.forEach(() => { walked += 1; });              // nav, main, top, body, foot
const unknown = shell.getCell('nope') === undefined; // true - no such cell

// State round-trips the whole arrangement, content untouched.
const widget = doc.createElement('div');
widget.textContent = 'kept';
shell.getCell('body').el.appendChild(widget);
let events = 0;
const onStateChange = () => { events += 1; };
shell.on('stateChange', onStateChange);
shell.setState(shell.getState());                    // re-mounts and fires stateChange
shell.off('stateChange', onStateChange);             // off - the subscription is removed
const kept = shell.getCell('body').el.contains(widget); // true - the same node, re-parented
const widthAfter = shell.getState().rows[0].width;  // 200 - sizes survived
shell.destroy();
return [tag, parent, walked, unknown, root.children.length, kept, events, widthAfter].join('|');

A resizable cell, its splitter and the resize events, executed

A cell marked resizable: true puts a focusable role="separator" on its trailing border; dragging or arrow keys resize it and its next sibling within both cells' min/max, and on(name, fn) observes the gesture. The drag itself is asserted against real Chrome in test/shell-splitter-browser.test.js; this block asserts the splitter's DOM and the event surface over the test DOM.

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

const { root } = createTestDom();
const shell = createShell(root, { type: 'line', rows: [
  { id: 'a', width: 200, minWidth: 100, maxWidth: 300, resizable: true },
  { id: 'b', gravity: 1 },
] });

const splitter = root.querySelector('[role="separator"]');
const oriented = splitter.getAttribute('aria-orientation');  // 'vertical' - a row resizes widths
const labelled = splitter.getAttribute('aria-label');         // 'Resize'
const tabbable = splitter.tabIndex === 0;                     // true - keyboard reachable

let resized = 0;
const off = shell.on('resize', () => { resized += 1; });      // subscribe; returns an unsubscribe fn
off();                                                          // remove the handler
shell.on('nope', () => { resized += 1; });                      // unknown name: never subscribed
shell.destroy();                                                // removes the splitter too
return [oriented, labelled, tabbable, resized, typeof shell.off].join('|');

Headers, collapse, a vetoed fold and translated labels, executed

A column cell with a text header folds to its strip, a beforeCollapse handler vetoes the first fold, expand() restores it, and config.messages supplies the control's own labels - all synchronous, over the in-tree DOM test double; the real rects are asserted against Chrome in test/shell-browser.test.js.

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

const { root } = createTestDom();
const shell = createShell(root, {
  messages: { t: (key, params) => (key === 'shell.collapse' ? `Hide ${params.name}` : `Show ${params.name}`) },
  cols: [
    { id: 'top', height: 120, header: 'Top', collapsable: true },
    { id: 'bottom', gravity: 1 },
  ],
});

const top = shell.getCell('top');
const btn = top.el.parentNode.querySelector('.lat-shell__header-btn');
const label = btn.getAttribute('aria-label');       // 'Hide Top' - the catalogue reached the control
const start = top.collapsed;                         // false - open at mount

const refuse = (e) => e.preventDefault('not yet');
shell.on('beforeCollapse', refuse);
const vetoed = top.collapse();                       // false - the host refused the fold
shell.off('beforeCollapse', refuse);
const folded = top.collapse();                       // true - folds to the strip
const after = top.collapsed;                         // true
const restored = top.expand();                       // true - back to the exact size
shell.destroy();
return [label, start, vetoed, folded, after, restored].join('|');

Attach, tab switching and detach, executed

A tabbed cell holds one content per tab; switching hides the outgoing panel without touching its content, tabChange fires, and detach() hands the element back - run over the in-tree DOM test double, with the same-element identity and a real grid's re-measure asserted against real Chrome in test/shell-content-browser.test.js.

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

const { root } = createTestDom();
const shell = createShell(root, {
  rows: [{ id: 'main', tabs: [
    { id: 'a', label: 'A', content: '<b>one</b>' },
    { id: 'b', label: 'B' },
  ] }],
});
const cell = shell.getCell('main');
const widget = root.ownerDocument.createElement('div');
cell.getTab('b').attach(widget);                  // b was empty - attach straight to it
let last = '';
shell.on('tabChange', (e) => { last = e.tabId; });
cell.getTab('b').activate();                      // switch: a hides, b shows
const switched = last === 'b';                // tabChange fired
const kept = cell.getTab('a').getWidget().textContent === '<b>one</b>'; // a's content survived the switch
const same = cell.getWidget() === widget;     // the same element, not a clone
const back = cell.detach();                   // detach b's content intact
shell.destroy();
return [switched, kept, same, back === widget].join('|');

Hide, show, add, remove, progress and a vetoed add, executed

A cell hides and shows, a new cell is added and removed live, the progress overlay mounts and clears, and a beforeAddCell handler vetoes one add so nothing is created - run over the in-tree DOM test double, with the real flexbox geometry (the space a hide gives and a show restores, and the size of a synchronously added cell) asserted against real Chrome in test/shell-live-browser.test.js.

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

const { root } = createTestDom();
const shell = createShell(root, { rows: [
  { id: 'a', width: 200 },
  { id: 'b', gravity: 1, progressDefault: true }, // starts with the spinner on
] });
const a = shell.getCell('a');
const hidden = a.hide().isVisible() === false;   // display:none, the space reflows
const shown = a.show().isVisible() === true;     // show restores the exact display
shell.on('beforeAddCell', (e) => { if (e.id === 'no') e.preventDefault(); });
const added = shell.addCell(null, { id: 'c', width: 100 });   // sized synchronously
const vetoed = shell.addCell(null, { id: 'no' }) === undefined; // vetoed: nothing made
const busy = shell.getCell('b').el.getAttribute('aria-busy') === 'true';
shell.getCell('c').progressShow();                // overlay the new cell
const overlay = shell.getCell('c').el.children.length === 1;
shell.getCell('c').progressHide();
const cleared = shell.getCell('c').el.children.length === 0;
const removed = shell.removeCell('c').config.id;  // live remove, content released
const gone = shell.getCell('c') === undefined;
shell.destroy();
return [hidden, shown, !!added, vetoed, busy, overlay, cleared, removed, gone].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 shell module

ShellWidget

A Lattice view as `attach()` sees it: an object exposing its root element and, optionally, a resize/refresh method the shell nudges on show.

ShellAttachHooks

The optional hooks `attach(content, opts)` takes, fired when the content hides or shows.

ShellTab

One tab of a tabbed cell: its identity, its strip label, and the content it holds across switches.

ShellCell

One cell of a shell. A cell either mounts content or nests `rows`/`cols`.

ShellConfig

The configuration for {@link createShell}.

ShellCellInstance

The cell handle `getCell(id)` and `forEach` hand back.

ShellTabInstance

The tab handle `getTab(id)` hands back for one tab of a tabbed cell.

ShellEventPayloads

What a handler receives, per shell event.

ShellCellEvent

The fields every shell event carries.

ShellBeforeToggleEvent

A `beforeCollapse` or `beforeExpand` payload. A handler refuses the change by calling `preventDefault(reason?)` or returning `false` (or a Promise that resolves `false`); the cell then does not move.

ShellAfterToggleEvent

An `afterCollapse` or `afterExpand` payload - a notification, not a gate.

ShellBeforeAddCellEvent

The payload of a `beforeAddCell` event.

ShellAfterAddCellEvent

The payload of an `afterAddCell` event.

ShellBeforeRemoveCellEvent

The payload of a `beforeRemoveCell` event.

ShellAfterRemoveCellEvent

The payload of an `afterRemoveCell` event.

ShellBeforeHideEvent

The payload of a `beforeHide` event.

ShellAfterHideEvent

The payload of an `afterHide` event.

ShellBeforeShowEvent

The payload of a `beforeShow` event.

ShellAfterShowEvent

The payload of an `afterShow` event.

ShellTabChangeEvent

The payload of a `tabChange` event.

ShellState

The JSON-able snapshot `getState()` returns and `setState()` accepts.

ShellStateChangeEvent

`stateChange`: `setState()` applied a snapshot and the arrangement now matches it. A notification, so it carries no `preventDefault`.

ShellBeforeEvent

The members every cancellable shell before-event carries.

ShellResizeEvent

The two neighbouring cells a splitter resize affects, plus their sizes.

Shell

The shell instance {@link createShell} returns.

Properties

Methods

Events