groups

Adds the button that opens and closes a collapsible group of columns.

Import	import { groups } from '@dzgrid/dom/groups';
Signature	groups(): GroupsFeature
Texts	no bundle of its own
Own CSS	GROUPS_CSS — to add yourself with injectStyles: false
Declared in	packages/dom/src/groups/index.ts

What it does

A column group with collapsible: true gets a small button in its header. Closed, the group shows its columns marked groupShow: 'closed' or not marked; open, it shows its columns marked 'open' or not marked. Enter or Space on the focused group header does the same as the button, and the new state is said. open: false on the group starts it closed. A column the user hid stays hidden when its group opens, and the columns chooser keeps a column folded by its group ticked.

The group rows themselves are drawn by spans(), which is needed too. A closed group that would show no column shows its first one, with an invalid-column-group warning. A fold that would leave no column on screen is refused. The open or closed state of each group is saved by gridState(), and the column menu’s « Reset columns » brings back the definitions’. From code: groupsFeature.api(grid) gives toggle, isOpen, reset, get and set.

Its texts are in the -columns bundle. With a collapsible group and without them, the grid is not made: an error names the missing key.

Example

import { createGrid } from '@dzgrid/dom';
import type { ColumnOrGroup } from '@dzgrid/core';
import { spans } from '@dzgrid/dom/spans';
import { groups } from '@dzgrid/dom/groups';
import { EN } from '@dzgrid/dom/locales/en';
import { EN_COLUMNS } from '@dzgrid/dom/locales/en-columns';

type Station = { id: string; name: string; tempMin: number; tempMax: number; rain: number };

const columns: ColumnOrGroup<Station>[] = [
  { id: 'name', header: 'Station' },
  { id: 'weather', header: 'Weather', collapsible: true, open: false, children: [
    { id: 'tempMin', header: 'Min °C', type: 'number', groupShow: 'open' },
    { id: 'tempMax', header: 'Max °C', type: 'number', groupShow: 'closed' },
    { id: 'rain', header: 'Rain (mm)', type: 'number', groupShow: 'open' },
  ] },
];

const folds = groups();

const grid = createGrid<Station>(document.getElementById('stations')!, {
  rows: [{ id: 's1', name: 'Cape Lumen', tempMin: 4, tempMax: 17, rain: 2.5 }],
  columns,
  getRowId: (s) => s.id,
  messages: { ...EN, text: { ...EN.text, ...EN_COLUMNS.text } },
  features: [spans(), folds],
});

folds.api(grid)?.toggle('weather');

Live demo

The group’s button folds Weather to its Max °C column.

See also

• The groupShow column option.
• The spans feature: group header rows.
• Columns: column groups in the guide.