Analysis to records

Analysis is only useful if it leads somewhere. A pivot value, a chart mark or a bucket of your own ("31–60 days late") names exactly the records behind it. Showing them goes wherever your app shows records (the grid's table, your own panel or route), and the person comes back to the analysis as they left it.

Naming recordsCopy Anchor Link

A record set says what the records are, which ones they are now, and the condition that names them:

import type { GridApi, GridRecordSet } from '@witbybit/wit-grid-react';

type Deal = { id: string; region: string; stage: string; amount: number };
declare const api: GridApi<Deal>;

const won: GridRecordSet | null = api.pivotRecords('group:region=East', 'won'); // a pivot value cell
const late = api.recordsWhere({ stage: { type: 'select', values: ['won'] } }, { label: 'Won deals' }); // your own bucket
won?.label; // 'Won revenue · East'
won?.ids; // the records now: a snapshot
won?.filters; // the condition naming exactly them, as column filters: live
won?.complete; // false when only loaded records were counted, or none can be named

• Exact: a value's where ("amount where stage is won") is part of the condition, so "Won revenue · East" names East's won deals and not its lost ones.
• Snapshot and live: ids are the records when the set was named. filters are the condition, so a record that starts or stops matching it shows or leaves as data changes. Pick the one your destination needs.
• When records cannot be named: a calculated value (a win rate) has no records of its own (complete: false, a reason, no filters). A key no filter can name (the folded "Other") has ids but no filters. On remote data only the loaded records are counted (complete: false); the filters, when there are any, still show the whole set.
• A chart names a mark's records too: chart.recordsAt(category, series) from createGridChart. With click: 'records', clicking a mark shows its records.

Showing themCopy Anchor Link

import type { GridApi, GridRecordSet } from '@witbybit/wit-grid-react';

declare const api: GridApi;
declare const records: GridRecordSet;

const result = await api.showRecords(records); // { status: 'shown' | 'cancelled' | 'declined', reason? }

"Show these records" on a pivot cell, the workspace chart's Show in table, and a chart with click: 'records' all call it. Without a destination of your own, the records go to the table:

• The pivot (or the view) turns off and the set's filters are joined to the person's own filters, field by field. Two value lists keep what both hold, and two conditions apply together. The person's filters are never replaced.
• A field already filtered by an either/or cannot take another condition, and a set with no filters cannot be shown by them. In both cases the table declines and says why.
• getStatus().shown holds the set and the way back. The workspace shows "12 records · Won revenue · East" above the table, says when the live records differ from those named ("2 changed since"), and has a Back button.

Your own destinationCopy Anchor Link

The showRecords grid option receives every request. Show the records in your own route or panel, or pass them to the table:

import { Grid, type GridShowRecordsRequest } from '@witbybit/wit-grid-react';

type Invoice = { id: string; vendor: string; amount: number };
declare function openPanel(ids: readonly string[], label: string): void;

const showRecords = (request: GridShowRecordsRequest<Invoice>) => {
	if (request.records.origin === 'app')
		openPanel(request.records.ids, request.records.label); // your buckets: your panel
	else request.showInTable(); // a pivot value or chart mark: the table, with the way back
};

<Grid<Invoice> rows={[]} columns={[]} showRecords={showRecords} />;

Return false to cancel. Records shown in your own panel act on the grid like any others: run your commands on them with api.runCommand(id, { rowIds }), and a writing command shows its review as usual.

Going backCopy Anchor Link

request.back (and getStatus().shown.back) is where the person was. It holds the view and its layout, the pivot, filters, sort, grouping, open groups, page and selection, plus the record at the top of the table. It is plain data, so keep it in your route's state.

import type { GridApi, GridReturnPoint } from '@witbybit/wit-grid-react';

declare const api: GridApi;
declare const back: GridReturnPoint;

api.goBack(); // the table's shown records: back to the analysis
api.goBack(back); // a way back you kept: restores what it holds
api.goBack({ state: { filter: back.state.filter }, place: null }); // only the filters: stay in the table, show every record

• A way back holds no policy. Rules, capabilities and columns are the grid's options, so going back never restores an older policy. A filter on a field that no longer exists is left out.
• Navigation never touches data: drafts, edits and unsaved changes made while away are still there.
• There is one level. Showing records again from the table keeps the first way back.