Dashboard API Reference

Five panels from one spec, a chart narrowing with its grid, spec() rebuilding the same dashboard, and destroy

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid, createHeadlessGrid } = await import('../packages/dom/src/index.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { createChart } = await import('../packages/modules/charts/index.js');
await import('../packages/modules/chart-markermap/index.js');
const { createKPI } = await import('../packages/modules/kpi/index.js');
const { createDashboard } = await import('../packages/modules/dashboard/index.js');

const { document, root } = createTestDom({ width: 1200, height: 800 });
const el = document.createElement('div');
root.appendChild(el);

const rows = Array.from({ length: 12 }, (_, i) => ({
  id: 'r' + i, region: ['north', 'south', 'east'][i % 3], sales: 10 * (i + 1),
  lon: -1 + i * 0.1, lat: 50 + i * 0.1,
}));

// Five panels, one source. The factories are handed in (on a script-tag page
// they are found on LatticeGrid, LatticeGridLayout and LatticeGridKPI).
const spec = {
  layout: { columns: 3, rows: 2 },
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  panels: [
    { id: 'table', kind: 'grid', title: 'Sales', source: 'sales', options: { selection: 'multiple' } },
    { id: 'byRegion', kind: 'chart', source: 'grid:table', options: { type: 'bar', x: 'region', y: 'sales' } },
    { id: 'total', kind: 'kpi', source: 'grid:table', options: { tiles: [{ id: 'sum', field: 'sales', aggregation: 'sum' }] } },
    { id: 'where', kind: 'map', source: 'sales', options: { type: 'markermap', lon: 'lon', lat: 'lat' } },
    { id: 'note', kind: 'html', options: { text: 'Provisional figures.' } },
  ],
};
const dashboard = createDashboard(el, spec, { createGrid, createHeadlessGrid, createLayout, createChart, createKPI });
const seen = [dashboard.panels().length, dashboard.problems().length];

// The chart views the table's grid, so filtering the table narrows it.
dashboard.panel('table').grid.filters.set({ col: 'region', op: 'eq', value: 'north' });
flushFrames();                                        // the next frame
seen.push(dashboard.panel('byRegion').viewer.data().categories.join('+'));

// spec() is what is on screen, placements included; it rebuilds the same dashboard.
const once = dashboard.spec();
dashboard.apply(once);
seen.push(JSON.stringify(dashboard.spec()) === JSON.stringify(once));

dashboard.destroy();                                 // every viewer, grid and window
seen.push(el.children.length);
return seen.join(' | ');                             // 5 | 0 | north | true | 0

Mixed sources, the Leaflet and deck.gl bindings, a selection filtering a chart, and a link refused by name

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid, createHeadlessGrid, createPushdownSource } = await import('../packages/dom/src/index.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { createChart } = await import('../packages/modules/charts/index.js');
const { bindLeaflet } = await import('../packages/modules/leaflet/index.js');
const { bindDeck } = await import('../packages/modules/deckgl/index.js');
const { createDashboard, validateDashboardSpec } = await import('../packages/modules/dashboard/index.js');

const { document, root } = createTestDom({ width: 1200, height: 800 });
const el = document.createElement('div');
root.appendChild(el);
const rows = Array.from({ length: 12 }, (_, i) => ({
  id: 'r' + i, region: ['north', 'south', 'east'][i % 3], sales: 10 * (i + 1), lon: -1 + i * 0.1, lat: 50 + i * 0.1,
}));
// Two engines with no router between them: stand-ins for two duckdbAdapter()s.
const engine = () => ({ capabilities: { filter: 'tree' }, execute: async () => ({ rows: [], total: 0 }) });
// Stand-ins for the page's L.map and deck.gl Deck.
const map = { addLayer() {}, removeLayer() {}, on() {}, off() {},
  getBounds: () => ({ getWest: () => -180, getSouth: () => -85, getEast: () => 180, getNorth: () => 85 }) };
const deck = { setProps() {} };

const spec = {
  sources: {
    sales: { kind: 'rows', rows, rowKey: 'id' },
    east: { kind: 'pushdown', adapter: engine(), rowKey: 'id', columns: [{ field: 'id' }, { field: 'region' }] },
    west: { kind: 'pushdown', adapter: engine(), rowKey: 'id', columns: [{ field: 'id' }, { field: 'region' }] },
  },
  panels: [
    { id: 'table', kind: 'grid', source: 'sales', options: { selection: 'multiple' } },
    { id: 'chart', kind: 'chart', source: 'sales', options: { type: 'bar', x: 'region', y: 'sales' } },
    { id: 'leaf', kind: 'map', binding: 'leaflet', source: 'sales', options: { map, layers: () => [], position: { lon: 'lon', lat: 'lat' } } },
    { id: 'gl', kind: 'map', binding: 'deckgl', source: 'sales', options: { deck, layers: () => [], position: { lon: 'lon', lat: 'lat' } } },
    { id: 'a', kind: 'grid', source: 'east' },
    { id: 'b', kind: 'grid', source: 'west' },
  ],
  links: [
    { from: 'table', to: 'chart', on: 'region' },    // the table's selection filters the chart
    { from: 'a', to: 'b', on: 'region' },            // refused: two engines, no shared router
  ],
};
const seen = [validateDashboardSpec(spec).ok];
const dashboard = createDashboard(el, spec, {
  createGrid, createHeadlessGrid, createPushdownSource, createLayout, createChart, bindLeaflet, bindDeck,
});
seen.push(dashboard.panels().length);

dashboard.panel('table').grid.selection.set(['r1']);   // a south row
flushFrames();                                        // the next frame
seen.push(dashboard.panel('chart').viewer.data().categories.join('+'));
seen.push(dashboard.problems().map((p) => p.path).join(', '));   // dashboard:link:a->b, at links[1]

// The validator names every problem by path, without building anything.
seen.push(validateDashboardSpec({ panels: [{ id: 'x', kind: 'gauge' }] }).problems[0].path);
dashboard.destroy();
return seen.join(' | ');   // true | 6 | south | links[1] | panels[0].kind

A proposal over a source, checked and applied; a view saved and restored; a presentation stepped

const { createTestDom, flushFrames } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid, createHeadlessGrid } = await import('../packages/dom/src/index.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { createChart } = await import('../packages/modules/charts/index.js');
const { createDashboard } = await import('../packages/modules/dashboard/index.js');

const { document, root } = createTestDom({ width: 1200, height: 800 });
const el = document.createElement('div');
root.appendChild(el);
const rows = Array.from({ length: 12 }, (_, i) => ({
  id: 'r' + i, region: ['north', 'south', 'east'][i % 3], sales: 10 * (i + 1),
}));

// The same ask() createAI takes. It sees the columns and the panel kinds, never
// the rows. A stand-in model answers with a table, a chart and a column that
// does not exist.
let asked = null;
const ask = async (payload) => {
  asked = payload.schema;
  return { structured: { panels: [
    { id: 'top', kind: 'grid', source: 'sales', options: { selection: 'single' } },
    { id: 'byRegion', kind: 'chart', source: 'grid:top', options: { type: 'bar', x: 'region', y: 'sales' } },
    { id: 'trend', kind: 'chart', source: 'sales', options: { type: 'line', x: 'month', y: 'sales' } },
  ] } };
};
const dashboard = createDashboard(el, { sources: { sales: { kind: 'rows', rows, rowKey: 'id' } }, panels: [] },
  { createGrid, createHeadlessGrid, createLayout, createChart, ai: { ask } });

const { spec, warnings } = await dashboard.propose('sales by region and a table', { source: 'sales' });
const seen = [asked.columns.map((c) => c.id).join(','), spec.panels.length, warnings.length];  // 'trend' named no column
dashboard.apply(spec);                                  // accepted: now it is built
flushFrames();

// A view is the spec plus every grid panel's state.
dashboard.panel('top').grid.filters.set({ col: 'region', op: 'eq', value: 'east' });
const view = dashboard.saveView('East only');
dashboard.panel('top').grid.filters.clear();
dashboard.applyView(view.id);
seen.push(dashboard.views().length, dashboard.panel('top').grid.rows.matchCount());

// Presentation steps through the panels, each filling the dashboard.
dashboard.present();
dashboard.step();
seen.push(dashboard.layout.maximised());
dashboard.stopPresenting();
dashboard.destroy();
return seen.join(' | ');                              // id,region,sales | 2 | 1 | 1 | 4 | byRegion