Shell Plugin

The Shell plugin wraps the grid with an optional header bar (title + toolbar) and a collapsible tool panel sidebar. Features like visibility, filtering, and pivot register their tool panels into this shell.

Opt-in

The shell is opt-in and tree-shakeable. Enable it with import '@toolbox-web/grid/features/shell' + features: { shell: true } (or by registering ShellPlugin directly). Nothing shell-related is bundled unless you import it.

Installation

import '@toolbox-web/grid/features/shell';

The feature import registers the ShellPlugin and augments features with a typed shell option. Shell configuration types (ShellConfig, ToolPanelDefinition, …) are exported from @toolbox-web/grid/plugins/shell.

Basic Usage

Enable the shell by setting features: { shell } with a header.title. Features like visibility automatically register a tool panel when the shell is active.

TypeScript

import { queryGrid } from '@toolbox-web/grid';
import '@toolbox-web/grid/features/shell';
import '@toolbox-web/grid/features/visibility';

const grid = queryGrid('tbw-grid');
grid.gridConfig = {
  features: {
    shell: { header: { title: 'Employee Data' } },
    visibility: true,
  },
};

React

import '@toolbox-web/grid-react/features/visibility';
import '@toolbox-web/grid-react/features/shell';
import { DataGrid } from '@toolbox-web/grid-react';
import type { GridConfig } from '@toolbox-web/grid-react';

const gridConfig: GridConfig = {
  features: {
    shell: { header: { title: 'Employee Data' } },
    visibility: true,
  },
};

function MyGrid({ data }) {
  return <DataGrid rows={data} gridConfig={gridConfig} style={{ height: '400px' }} />;
}

Alternative: feature props

You can instead pass visibility and shell={{ … }} as individual props on <DataGrid>. That form is idiomatic React, but gridConfig keeps the configuration identical across every framework.

Vue

<script setup lang="ts">
import '@toolbox-web/grid-vue/features/visibility';
import '@toolbox-web/grid-vue/features/shell';
import { TbwGrid } from '@toolbox-web/grid-vue';
import type { GridConfig } from '@toolbox-web/grid-vue';

const gridConfig: GridConfig = {
  features: {
    shell: { header: { title: 'Employee Data' } },
    visibility: true,
  },
};
</script>

<template>
  <TbwGrid :rows="data" :grid-config="gridConfig" style="height: 400px" />
</template>

Alternative: feature props

You can instead bind visibility and :shell="{ … }" directly on <TbwGrid>. That form is idiomatic Vue, but gridConfig keeps the configuration identical across every framework.

Angular

Define everything inside gridConfig.features, exactly like the other frameworks. The side-effect import registers the feature so the adapter can bridge it.

import '@toolbox-web/grid-angular/features/visibility';
import '@toolbox-web/grid-angular/features/shell';
import { Component } from '@angular/core';
import { Grid } from '@toolbox-web/grid-angular';
import type { GridConfig } from '@toolbox-web/grid-angular';

@Component({
  selector: 'app-shell-grid',
  imports: [Grid],
  template: `
    <tbw-grid
      [rows]="rows"
      [gridConfig]="gridConfig"
      style="height: 400px; display: block;">
    </tbw-grid>
  `,
})
export class ShellGridComponent {
  rows = [];
  gridConfig: GridConfig = {
    features: {
      shell: { header: { title: 'Employee Data' } },
      visibility: true,
    },
  };
}

Alternative: per-feature directive

You can instead import GridVisibilityDirective and bind [visibility] directly on <tbw-grid>. That form gives a compile-time check that the feature is imported, but gridConfig.features above is the recommended, framework-consistent approach.

HEADER

Show titleShow title in shell header

Show header contentShow custom header content (row count)

Show toolbar buttonShow custom toolbar button

PLUGINS

Visibility pluginInclude VisibilityPlugin (column chooser)

PANELS

Custom tool panelShow custom tool panel via API

Panel positionTool panel position

leftright

Panel modeOverlay floats over the grid; push reflows the grid; dropdown anchors a popover to the toggle

overlaypushdropdown

Show source

Light DOM Configuration

Configure the shell declaratively using <tbw-grid-header> and <tbw-grid-header-content> elements. Still import '@toolbox-web/grid/features/shell' so the plugin is present:

<tbw-grid>
  <tbw-grid-header title="Employee Directory">
    <tbw-grid-header-content>
      <span id="row-count">0 employees</span>
    </tbw-grid-header-content>
  </tbw-grid-header>
</tbw-grid>

Shell configured via <tbw-grid-header> light DOM elements — no JavaScript shell config needed.

20 employees

Show source

Multiple Tool Panels

Register multiple tool panels — each gets a tab in the sidebar. Panels can be registered via configuration, the framework wrapper components, or the plugin’s runtime registerToolPanel() API. Each panel requires a title.

TypeScript

import '@toolbox-web/grid/features/shell';

const shell = grid.getPluginByName('shell');
shell?.registerToolPanel({
  id: 'filter-panel',
  title: 'Filters',
  icon: '🔍',
  render(container) {
    container.innerHTML = '<p>Filter controls here</p>';
  },
});

React

import { DataGrid, GridToolPanel } from '@toolbox-web/grid-react';

function MyGrid({ rows }) {
  return (
    <DataGrid rows={rows} gridConfig={config}>
      <GridToolPanel id="filter-panel" title="Filters" icon="🔍">
        {({ grid }) => <p>Filter controls here</p>}
      </GridToolPanel>
    </DataGrid>
  );
}

Vue

<script setup lang="ts">
import { TbwGrid, TbwGridToolPanel } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="rows" :grid-config="config">
    <TbwGridToolPanel id="filter-panel" label="Filters" icon="🔍">
      <template #default="{ grid }">
        <p>Filter controls here</p>
      </template>
    </TbwGridToolPanel>
  </TbwGrid>
</template>

Angular

<tbw-grid [rows]="rows" [gridConfig]="config">
  <tbw-grid-tool-panel id="filter-panel" title="Filters" icon="🔍">
    <ng-template>
      <p>Filter controls here</p>
    </ng-template>
  </tbw-grid-tool-panel>
</tbw-grid>

Adapters auto-register the shell (v2.x)

While v2.x is current, the React, Vue, and Angular wrappers register the ShellPlugin automatically when you use a shell wrapper component (GridToolPanel, GridToolButtons, …) or pass features.shell, so adapter users do not need an explicit shell import. This auto-registration is a v2.x convenience and is removed at v3.0.0, where the shell becomes opt-in. Each adapter ships a side-effect feature import for the explicit opt-in: import '@toolbox-web/grid-react/features/shell' (and the matching grid-vue / grid-angular subpaths). Adding it now is forward-compatible and tree-shakeable.

Multiple tool panels (Columns, Filter, Settings). Click toolbar icons to toggle each.

Show source

Toolbar Buttons

Add custom buttons to the shell toolbar using framework wrapper components or light-DOM <tbw-grid-tool-buttons>:

TypeScript

<tbw-grid>
  <tbw-grid-tool-buttons>
    <button onclick="exportData()">📥 Export</button>
    <button onclick="printGrid()">🖨️ Print</button>
  </tbw-grid-tool-buttons>
</tbw-grid>

React

import { DataGrid, GridToolButtons } from '@toolbox-web/grid-react';

function MyGrid({ rows }) {
  return (
    <DataGrid rows={rows} gridConfig={config}>
      <GridToolButtons>
        <button onClick={exportData}>📥 Export</button>
        <button onClick={printGrid}>🖨️ Print</button>
      </GridToolButtons>
    </DataGrid>
  );
}

Vue

<script setup lang="ts">
import { TbwGrid, TbwGridToolButtons } from '@toolbox-web/grid-vue';
</script>

<template>
  <TbwGrid :rows="rows" :grid-config="config">
    <TbwGridToolButtons>
      <button @click="exportData">📥 Export</button>
      <button @click="printGrid">🖨️ Print</button>
    </TbwGridToolButtons>
  </TbwGrid>
</template>

Angular

<tbw-grid [rows]="rows" [gridConfig]="config">
  <tbw-grid-tool-buttons>
    <button (click)="exportData()">📥 Export</button>
    <button (click)="printGrid()">🖨️ Print</button>
  </tbw-grid-tool-buttons>
</tbw-grid>

Custom toolbar buttons via light DOM. The grid provides the container — you provide the HTML.

📥🖨️

Show source

Configuration Options

All options live under features.shell and are typed by ShellConfig (from @toolbox-web/grid/plugins/shell):

Option	Type	Default	Description
header.title	string	—	Title text in the header bar
header.visible	boolean	true	Render the header bar. Set false to suppress the entire .tbw-shell-header and own all chrome yourself
header.toolPanelToggle	boolean	true	Render the built-in panel toggle button + separator
toolPanel.position	'left' | 'right'	'right'	Sidebar position
toolPanel.width	number	280	Sidebar width in pixels
toolPanel.defaultOpen	string	—	Accordion section to auto-expand on first open. Also opens the sidebar on load — see #259 for the planned split. Prefer initialState / locked to control the open state and defaultOpen purely for section selection.
toolPanel.initialState	'open' | 'closed'	'closed'	Whether the sidebar starts open on grid load. Takes precedence over defaultOpen’s open-on-load behavior when set.
toolPanel.locked	boolean	false	Lock the sidebar open. Implies initialState: 'open', makes closeToolPanel() a no-op, and hides the built-in toggle button.
toolPanel.persistState	boolean	false	Remember open/closed state
toolPanel.closeOnClickOutside	boolean	false	Close on outside click (ignored in mode: 'push' or when locked: true; 'dropdown' always light-dismisses)
toolPanel.mode	'overlay' | 'push' | 'dropdown'	'overlay'	'overlay' floats over the grid; 'push' reflows the grid sideways so all cells stay visible; 'dropdown' renders the whole sidebar as an anchored popover

Tool-Panel Layout Modes

The tool panel supports three layout modes — pick whichever fits the viewport you’re targeting.

• 'overlay' (default): the panel is positioned over the grid content. Opening it does not change the grid’s available width. Best for narrow viewports where shrinking the grid would leave too little room for the data.
• 'push': the panel is laid out as a sibling of the grid content in a flex row. Opening it shrinks the grid’s available width; the grid’s ResizeObserver re-runs column virtualization, so cells that an overlay panel would hide remain reachable. Best for desktop layouts.
• 'dropdown': the entire sidebar (the full accordion) renders as an anchored popover built on the native Popover API. It floats above all other content in the top layer, is dismissed on Escape or click-outside, and is positioned via CSS anchor positioning where supported (with a JS bounding-rect fallback). The anchor is resolved by priority: an explicit anchor passed to openToolPanel() → the built-in toggle button → the grid corner. Best for compact toolbars and bring-your-own trigger buttons (e.g. a “columns” button in a custom column header).

import '@toolbox-web/grid/features/shell';

grid.gridConfig = {
  features: {
    shell: {
      toolPanel: {
        position: 'right',
        mode: 'push', // grid reflows when the panel opens/closes
      },
    },
  },
};

In 'push' mode the user-facing resize handle is hidden (the panel’s width is part of the layout, so drag-to-resize would fight the flex container) and closeOnClickOutside is treated as a no-op (there is no overlap to dismiss against). Drive the width via the --tbw-tool-panel-width CSS variable instead.

Dropdown mode + a custom column-header trigger

'dropdown' mode shines when you want the column chooser to hang off your own button rather than the built-in toolbar toggle. Pass that button as the anchor when you open the panel, and the popover positions itself directly below it:

const shell = grid.getPluginByName('shell');
// Mark your trigger so the popover can re-find it after a structural re-render.
columnsButton.setAttribute('data-panel-toggle', '');
columnsButton.addEventListener('click', () => {
  shell?.openToolPanel('columns', { anchor: columnsButton });
});

Mark a custom trigger with data-panel-toggle

A custom trigger button must carry the data-panel-toggle attribute. Toggling a column’s visibility or reordering columns from inside the panel triggers a structural re-render that rebuilds the trigger node — so the element reference you passed as anchor is detached and can no longer be re-anchored. The shell re-resolves the anchor after every re-render via the [data-panel-toggle] selector; without it, an open dropdown falls back to the grid corner instead of staying under your button.

The demo below renders a utility-type column whose header hosts a custom ▥ button. Clicking it opens the full tool panel as a dropdown anchored to that button — no toolbar required.

mode: 'dropdown' renders the full tool panel as an anchored popover. Here it is opened from a custom ▥ button in the header of a utility column — a bring-your-own trigger anchored via openToolPanel('columns', { anchor }).

In 'dropdown' mode the resize handle is hidden, the popover is capped to the viewport (max-height: min(70vh, 480px)) with internal scrolling for tall accordions, and dismissal (Escape / click-outside) is always active regardless of closeOnClickOutside.

Styling the Shell

<tbw-grid> renders into the light DOM, so the shell’s internals are reachable from any outer stylesheet — no ::part() needed. Theme-level overrides applied to a top-level CSS file affect every grid in the application uniformly.

Stable selectors:

Selector	Element
tbw-grid .tbw-shell-header	Header bar (title + content + toolbar)
tbw-grid .tbw-shell-title	Title element
tbw-grid .tbw-shell-toolbar	Toolbar (flex container; custom content + toggle)
tbw-grid .tbw-toolbar-btn	Buttons inside the toolbar (incl. panel toggle)
tbw-grid [data-panel-toggle]	The single panel toggle button
tbw-grid .tbw-toolbar-separator	Separator between custom content and the toggle
tbw-grid .tbw-tool-panel	Tool-panel sidebar
tbw-grid .tbw-accordion-header	Tool-panel section header (one per registered panel)

Recipe — move the panel toggle to the start of the toolbar (left in LTR):

The toolbar is a flex row, so reordering is purely a CSS concern — use order on both the toggle and its separator so they stay grouped together:

/* App-level theme — affects every <tbw-grid> uniformly */
tbw-grid [data-panel-toggle],
tbw-grid .tbw-toolbar-separator {
  order: -1;
}

No grid configuration is required; this is the recommended way to standardize toolbar layout across an application’s grids.

Bring Your Own Tool-Panel Toggle

If you need to replace the built-in toggle button entirely — for example, to use a design-system button instead of styling .tbw-toolbar-btn — set header.toolPanelToggle: false. The grid will not render the built-in button or the auto-inserted separator next to it; tool panels themselves remain fully functional and can be toggled from any element via the plugin’s toggleToolPanel(), opened directly on a specific section via openToolPanel(panelId), or driven section-by-section with toggleToolPanelSection(id).

import '@toolbox-web/grid/features/shell';

const shell = grid.getPluginByName('shell');

const config = {
  features: {
    shell: {
      header: {
        title: 'Employees',
        toolPanelToggle: false, // suppress built-in <button data-panel-toggle> + separator
        toolbarContents: [
          {
            id: 'my-buttons',
            render: (container) => {
              const filters = document.createElement('my-button');
              filters.textContent = 'Filters';
              filters.addEventListener('click', () => shell?.openToolPanel('filters'));

              const settings = document.createElement('my-button');
              settings.textContent = 'Settings';
              settings.addEventListener('click', () => shell?.openToolPanel('settings'));

              container.append(filters, settings);
            },
          },
        ],
      },
    },
  },
};

Passing a panelId to openToolPanel() jumps straight to that accordion section (one click, no double-tap). It takes precedence over toolPanel.defaultOpen; if the ID isn’t registered, the call falls back to default behavior and emits a TBW072 warning.

Hide the Shell Header Bar Entirely

toolPanelToggle: false removes the built-in toggle button but keeps the header bar (with its title and any toolbar contents). To suppress the entire .tbw-shell-header bar — for example when you want to open tool panels from a custom column header icon and own all chrome yourself — set header.visible: false.

import '@toolbox-web/grid/features/shell';

const shell = grid.getPluginByName('shell');

const config = {
  columns: [
    // …
    {
      field: '__actions',
      width: 56,
      utility: true, // excluded from print, export, reorder, visibility, etc.
      resizable: false,
      sortable: false,
      headerRenderer: () => {
        const btn = document.createElement('button');
        btn.type = 'button';
        btn.textContent = '⚙';
        btn.setAttribute('aria-label', 'Open tool panel');
        btn.addEventListener('click', () => shell?.toggleToolPanel());
        return btn;
      },
    },
  ],
  features: {
    shell: {
      header: { visible: false },
      toolPanel: {
        closeOnClickOutside: true, // optional — see below
      },
    },
  },
};

When header.visible: false, tool panels remain fully functional and are opened with the plugin’s toggleToolPanel() / openToolPanel(panelId) from any element you like. Because there is no header toggle to close the panel, the grid provides three additional dismissal affordances:

• Close button — a small ✕ button (exposed as the tool-panel-close CSS part) is rendered to dismiss the panel. With a single panel it sits inline on the first accordion header row; with multiple panels it gets its own row at the top of the panel (exposed as the tool-panel-header CSS part). It is omitted when toolPanel.locked is true (a locked panel cannot be closed) and in dropdown mode, where the popover already light-dismisses on Esc / click-outside.
• Escape key — pressing Esc closes an open overlay panel. It yields to more specific handlers (e.g. an active cell editor that has already handled the key), and is a no-op for push-mode panels, which are persistent sidebars.
• Click-outside — set toolPanel.closeOnClickOutside: true to dismiss an open overlay panel when clicking anywhere in the window outside the panel. This is opt-in and, like Esc, is a no-op in push mode.

header.visible: false keeps the shell active (the panel overlay still mounts); it only suppresses the header bar element. This is the supported alternative to hiding .tbw-shell-header with CSS.

Migrating from the Core Shell (pre-v3)

The shell used to be part of grid core: auto-registered with no import, driven by grid.register* / openToolPanel element delegates, with its config types exported from the package root. Those surfaces were removed in v3.0.0. The shell configuration object itself is still augmented onto gridConfig by the plugin. Migrate as follows:

Removed in v3	Use instead
Implicit shell (no import)	import '@toolbox-web/grid/features/shell'
grid.registerToolPanel(panel)	grid.getPluginByName('shell')?.registerToolPanel(panel)
grid.unregisterToolPanel(id)	grid.getPluginByName('shell')?.unregisterToolPanel(id)
grid.registerHeaderContent(c)	grid.getPluginByName('shell')?.registerHeaderContent(c)
grid.registerToolbarContent(c)	grid.getPluginByName('shell')?.registerToolbarContent(c)
grid.openToolPanel(id) / closeToolPanel() / toggleToolPanel()	grid.getPluginByName('shell')?.openToolPanel(id) (same method names)
Shell types from @toolbox-web/grid	Shell types from @toolbox-web/grid/plugins/shell

Notes:

• For advanced/explicit control you can register the plugin directly: plugins: [new ShellPlugin(shellConfig)] (from @toolbox-web/grid/plugins/shell).
• Adapters no longer auto-register the ShellPlugin. React/Vue/Angular users must add the adapter side-effect import import '@toolbox-web/grid-{react,vue,angular}/features/shell'.
• Shell usage without the feature/plugin enabled throws a clear error with a migration link.
• See the v3 migration guide for the full change set.

Accessibility

The tool panel is resized by dragging the splitter between the panel and the grid. WCAG 2.2 SC 2.5.7 Dragging Movements requires a single-pointer alternative for every such gesture, so the splitter is a button as well as a drag target.

• Tap the splitter — press and release without moving and the size popover opens against it, with − / a width field / + / Reset. Dragging behaves exactly as before; the two are told apart by whether the pointer moved.
• The same popover used for columns — it is the shared control from column resizing, so the gesture, keyboard behaviour, and appearance are identical wherever something is resizable. − and + step by 32px, the field takes an exact pixel value, and Reset drops the explicit width. Escape, or a press anywhere outside, dismisses it.
• Same limits as the drag — every path through the popover clamps to the same 200px minimum and the same available maximum, so no pointer alternative can produce a size the drag could not.
• No reserved chrome — nothing extra is drawn. The alternative reuses the affordance you would have dragged, and the splitter carries role="button" with an accessible name instead of aria-hidden.
• A 24px target on every pointer — SC 2.5.8 Target Size (Minimum) applies to a mouse as well as a finger, so the splitter’s invisible hit area is 24px wide while the lit bar stays 6px. It straddles the docked edge, half over the grid and half over the panel, so it never covers the panel’s own controls. Raising --tbw-touch-target-min for the rest of the grid? Raise --tbw-tool-panel-resize-overhang to half that value as well — see Hit-target sizing.

See the accessibility guide for the full inventory of drag alternatives across the grid.

How the Shell Wraps the Grid

The shell is unusual among plugins: most plugins enrich the grid (tagging rows, decorating cells), but the shell wraps it — it consumes the freshly built grid DOM and renders its own chrome (header bar + tool-panel sidebar) around it. It does this from the afterStructuralRender() lifecycle hook, relocating the existing .tbw-grid-content node into the shell wrapper (preserving the subtree, its listeners, and the grid’s cached refs) rather than re-creating it.

If you want to build another grid-wrapping plugin, this pattern is documented as a reusable recipe in Plugin Architecture → Wrapping plugins.

See Also

• Filtering — Registers a filter tool panel into the shell
• Pivot — Registers a pivot configuration tool panel
• Core Features — Columns, renderers, formatters, events, and methods
• Plugins Overview — Plugin compatibility and combinations