Designer API Reference

The palette lists a chart type registered at run time, disables what the source cannot fill, and adds a bar with its defaults

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

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

const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rowKey: 'id', rows: [{ id: 1, region: 'north', sales: 10 }],
    fields: [{ id: 'region', type: 'text' }, { id: 'sales', type: 'number' }] } },
  factories: { createGrid, createHeadlessGrid, createChart, createLayout },
});

registerChartType('docs-radial', { draw() {}, freeform: true });
const find = (id) => designer.palette.entries().find((e) => e.id === id);
const seen = [!!find('chart:docs-radial'), find('filter:dateRange').disabled];

const id = designer.palette.add('chart', 'bar');
const panel = designer.getState().pages[0].spec.panels[0];
seen.push(id === panel.id, [panel.options.type, panel.options.x, panel.options.y.col].join(','));
seen.push(designer.getState().pages[0].spec.layout.windows.length);
designer.palette.collapse();
seen.push(designer.getState().panels.palette.collapsed);
designer.destroy();
return seen.join(' | ');                                   // true | needs a date field | true | bar,region,sales | 1 | true

A global filter and a page filter narrow every widget reading their source, clearing keeps the filters, and a click-filter setting narrows and clears its targets

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

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

const rows = [
  { id: 'r1', region: 'north', sales: 100, name: 'Acme' },
  { id: 'r2', region: 'north', sales: 50, name: 'Bolt' },
  { id: 'r3', region: 'south', sales: 200, name: 'Acme East' },
  { id: 'r4', region: 'south', sales: 20, name: 'Crate' },
];
const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rowKey: 'id', rows,
    fields: [{ id: 'region', type: 'text' }, { id: 'sales', type: 'number' }, { id: 'name', type: 'text' }] } },
  state: { schemaVersion: 1, selectedPageId: 'p1', panels: {}, pages: [{ id: 'p1', title: 'Sales', spec: { panels: [
    { id: 'table', kind: 'grid', source: 'sales', options: { selection: 'single' } },
    { id: 'chart', kind: 'chart', source: 'sales', options: { type: 'bar', x: 'region', y: 'sales' } },
  ] } }] },
  factories: { createGrid, createHeadlessGrid, createChart, createLayout },
});
const table = () => designer.dashboard.panel('table').grid;
const chart = () => designer.dashboard.panel('chart').grid;
const seen = [];

// A global filter narrows every widget reading `sales`, table and chart alike.
const searchId = designer.filters.addFilter({ scope: 'global', type: 'search', source: 'sales', field: 'name' });
designer.filters.setValue(searchId, 'Acme');
seen.push(table().rows.matchCount(), chart().rows.matchCount());       // the two Acme rows
seen.push(designer.getState().filters[0].value);
designer.undo();                                                       // the value alone, not the filter
seen.push(designer.getState().filters[0].value === undefined);
designer.filters.removeFilter(searchId);

// A page filter does the same, scoped to this page only.
const rangeId = designer.filters.addFilter({ type: 'range', source: 'sales', field: 'sales' });
designer.filters.setValue(rangeId, [60, '']);
seen.push(table().rows.matchCount());                                  // sales >= 60: rows 1 and 3
seen.push(designer.filters.active()[0].scope);
designer.filters.clearAll();
seen.push(table().rows.matchCount());                                  // clear-all keeps the filter, drops its value
designer.filters.removeFilter(rangeId);

// Cross-filtering: clicking the table's row filters every other widget by region.
designer.filters.setClickFilter('table', { targets: 'all', on: 'region' });
const links = designer.getState().pages[0].spec.links;
seen.push(links.map((l) => `${l.from}-${l.to}:${l.on}`).join(','));
table().selection.set(['r3']);
flushFrames();
seen.push(chart().rows.matchCount());                                  // south only
table().selection.set([]);
flushFrames();
seen.push(chart().rows.matchCount());                                  // cleared
designer.filters.setClickFilter('table', null);
seen.push(designer.getState().pages[0].spec.links.length);

seen.push(!!designer.rails.filterBar);
designer.destroy();
return seen.join(' | ');   // 2 | 2 | Acme | true | 2 | page | 4 | table-chart:region | 2 | 4 | 0 | true

Declared and inferred fields, a relationship, and which sources are reachable from an order's source

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const designer = createDesigner(el, {
  mode: 'edit',
  sources: {
    // Declared fields, with a type, a format and a description.
    orders: {
      kind: 'rows',
      rows: [{ id: 'o1', customerId: 'c1', amount: 42 }],
      rowKey: 'id',
      fields: [
        { id: 'amount', label: 'Order total', type: 'currency', format: '$0,0.00', description: 'What the order was worth.' },
        { id: 'customerId', label: 'Customer', type: 'text' },
      ],
    },
    // No `fields`: inferred from the sampled rows.
    customers: { kind: 'rows', rows: [{ id: 'c1', region: 'north', since: '2024-05-01' }], rowKey: 'id' },
  },
  relationships: [{ from: 'orders.customerId', to: 'customers.id', type: 'many-to-one', fields: ['region'] }],
  guardrails: { sources: ['orders', 'customers'] },
  state: { pages: [{ id: 'p1', spec: { panels: [{ id: 'win', kind: 'grid', title: 'Orders', source: 'orders' }] } }], selectedPageId: 'p1' },
  factories: { createGrid, createHeadlessGrid, createLayout },
});

const bySource = Object.fromEntries(designer.dataPanel.sources().map((s) => [s.id, s]));
const seen = [
  bySource.orders.fields.map((f) => f.type).join(','),                // declared: currency, text
  bySource.customers.fields.map((f) => f.type).join(','),             // inferred: id (text), region (text), since (date)
  designer.dataPanel.reachable('orders').join(','),                    // customers, via the relationship
];

const edges = designer.dataPanel.compiledRelationships();
seen.push(edges[0].join.foreignKey === 'id' && edges[0].join.from === 'customers');

designer.destroy();
return seen.join(' | ');                                               // currency,text | text,text,date | customers | true

A two-panel page in view mode, the state round-tripping with an unknown key, a second page selected, and edit mode

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const rows = [{ id: 'a', region: 'north', sales: 10 }, { id: 'b', region: 'south', sales: 20 }];
const designer = createDesigner(el, {
  mode: 'view',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    schemaVersion: 1,
    pages: [
      { id: 'p1', title: 'Sales', spec: {
        layout: { columns: 2, rows: 1 },
        panels: [
          { id: 'table', kind: 'grid', title: 'Orders', source: 'sales' },
          { id: 'note', kind: 'html', title: 'Note', options: { text: 'Provisional figures.' } },
        ],
      } },
      { id: 'p2', title: 'Notes', spec: { panels: [{ id: 'only', kind: 'html', options: { text: 'Hello' } }] } },
    ],
    selectedPageId: 'p1',
    panels: {},
    myAppVersion: 3,                                  // a key the designer does not know
  },
  factories: { createGrid, createHeadlessGrid, createLayout },
  relationships: [], guardrails: {}, llm: null,       // kept on designer.context for later features
});
const seen = [designer.mode, designer.dashboard.panels().join(','), designer.problems().length];

// The state comes back as it went in, unknown key and all.
const state = designer.getState();
designer.setState(state);
seen.push(JSON.stringify(designer.getState()) === JSON.stringify(state));

// One event per change: selecting the second page builds it on the canvas.
const causes = [];
designer.on('state', (event) => causes.push(event.cause));
let heard = 0;
designer.onStateUpdated(() => { heard += 1; });
seen.push(designer.pages().map((p) => p.title).join(','));
designer.selectPage('p2');
seen.push(designer.dashboard.panels().join(','), causes.join(','), heard);

// Edit mode: the same canvas, with the windows made movable.
designer.setMode('edit');
seen.push(designer.mode, designer.dashboard.layout.getInteractive().movable);

// Properties by name: setProperty('mode', 'view') switches live.
seen.push(designer.setProperty('mode', 'view'), designer.getProperty('mode'));

designer.destroy();
seen.push(el.children.length === 0 ? 1 : 0);
return seen.join(' | ');                              // view | table,note | 0 | true | Sales,Notes | only | selectPage | 1 | edit | true | true | view | 1

A plain spec migrated to a one-page state, a dry-run report, and a newer version refused

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const designer = createDesigner(el, { factories: { createGrid, createHeadlessGrid, createLayout } });

// A plain createDashboard spec (no pages, no schemaVersion) is a v0 state:
// setState migrates it to a one-page v1 state, keeping an unknown option.
const spec = { panels: [{ id: 'a', kind: 'html', title: 'A', options: { text: 'Hi', custom: 'kept' } }] };
designer.setState(spec);
const pages = designer.getState().pages.length;            // the v0 spec is now one page
const kept = designer.getState().pages[0].spec.panels[0].options.custom; // and its unknown option survived

// designer.migrate reports the migration; dryRun reports without applying.
const dry = designer.migrate({ panels: [{ id: 'b', kind: 'html' }] }, { dryRun: true });
const live = designer.migrate({ panels: [{ id: 'c', kind: 'html', options: { x: 1 } }] });

// A state from a NEWER version is refused by name, not half-loaded.
const refused = designer.migrate({ schemaVersion: 2, pages: [] }, { dryRun: true });

const out = [
  pages, kept,
  dry.applied, dry.state.pages[0].spec.panels[0].id,   // dry run: reported, not applied
  live.applied, live.state.pages[0].spec.panels[0].id, // live run: applied
  refused.ok, refused.reason,                          // a newer version is refused
];
designer.destroy();
return out.join(' | ');                                 // 1 | kept | true | b | true | c | false | newer

Laziness builds only the selected page's grids; add, duplicate, rename, reorder and delete are one state change each; keepPagesAlive keeps a page built

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

// Count the grid builds: laziness means only the selected page's grid lives.
let grids = 0;
const base = { createGrid, createHeadlessGrid, createLayout };
const factories = {
  createGrid: (mount, cfg) => { grids += 1; return base.createGrid(mount, cfg); },
  createHeadlessGrid: base.createHeadlessGrid,
  createLayout: base.createLayout,
};
const rows = [{ id: 'a', region: 'north', sales: 10 }];
const designer = createDesigner(el, {
  mode: 'view',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    pages: [
      { id: 'p1', title: 'Sales', spec: { panels: [{ id: 'table', kind: 'grid', title: 'Orders', source: 'sales' }] } },
      { id: 'p2', title: 'Notes', spec: { panels: [{ id: 'only', kind: 'html', options: { text: 'Hi' } }] } },
    ],
    selectedPageId: 'p1',
  },
  factories,
});

// p1's grid is built once; leaving for p2 disposes it; returning rebuilds it.
const seen = [grids];
designer.selectPage('p2'); seen.push(grids);
designer.selectPage('p1'); seen.push(grids);

// addPage (blank, then a duplicate of p2), rename, move, remove - each one step.
const added = designer.addPage({ title: 'Extra' }); seen.push(added !== null, designer.pages().length);
const dup = designer.addPage({ duplicate: 'p2' }); seen.push(dup !== null, designer.pages().length);
seen.push(designer.renamePage('p2', 'Details'));
seen.push(designer.movePage('p1', 1));
seen.push(designer.removePage(added));
designer.destroy();

// keepPagesAlive keeps a visited page built, so its grid is never rebuilt.
let kept = 0;
const el2 = document.createElement('div');
root.appendChild(el2);
const keepAlive = createDesigner(el2, {
  mode: 'view',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    pages: [
      { id: 'a', title: 'A', spec: { panels: [{ id: 'g', kind: 'grid', title: 'G', source: 'sales' }] } },
      { id: 'b', title: 'B', spec: { panels: [{ id: 'h', kind: 'html', options: { text: 'Hi' } }] } },
    ],
    selectedPageId: 'a',
  },
  factories: {
    createGrid: (mount, cfg) => { kept += 1; return base.createGrid(mount, cfg); },
    createHeadlessGrid: base.createHeadlessGrid,
    createLayout: base.createLayout,
  },
  keepPagesAlive: true,
});
keepAlive.selectPage('b'); keepAlive.selectPage('a'); keepAlive.destroy();
seen.push(kept);
return seen.join(' | ');                              // 1 | 1 | 2 | true | 3 | true | 4 | true | true | true | 1

The six kinds, column profile's generated role, group comparison's options, and an added widget's numbers matching grid.statistics.profile directly

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

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

const rows = Array.from({ length: 30 }, (unused, i) => ({
  id: `r${i}`, region: i % 2 === 0 ? 'north' : 'south', month: i, sales: 100 + i * 5 + (i % 4) * 10,
}));

const designer = createDesigner(el, {
  mode: 'edit',
  sources: { orders: { kind: 'rows', rows, rowKey: 'id' } },
  state: { pages: [{ id: 'p1', spec: { panels: [] } }] },
  factories: { createGrid, createHeadlessGrid, createLayout, createChart },
});

// Six widget kinds, each a kind: 'chart' panel of its own type - "add" is one
// undoable commit through designer.addWidget, same as any other widget.
const kinds = designer.statisticsWidgets.kinds.slice().sort();
designer.statisticsWidgets.add('columnProfile', 'w1', { source: 'orders', options: { y: 'sales' } });

// The properties panel's generated editor already offers
// column profile's one role and group comparison's test/confidence options - // no designer code of its own.
const { chartRoles, chartOptions } = await import('../packages/modules/charts/capabilities.js');
const profileRoles = chartRoles('profile').map((r) => r.role);
const groupOptions = chartOptions('groupComparison').map((o) => o.name);

// What it drew matches grid.statistics.profile directly.
const grid = designer.dashboard.panel('w1').grid;
const direct = grid.statistics.profile('sales');

const undone = designer.undo(); // the add is one step

designer.destroy();
return [
  kinds.join(','),
  profileRoles.join(','),
  groupOptions.includes('test') && groupOptions.includes('confidence'),
  direct.rows,
  undone,
  designer.getState().pages[0].spec.panels.length,
].join(' | ');                 // columnProfile,correlation,distribution,forecast,groupComparison,modelError | field | true | 30 | true | 0

A REST-like adapter that can only page rows: its fields from describe(), its aggregations and steps refused by name, an edit refused, a derived pivot refused

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

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

// An adapter that pages rows and nothing else; describe() is its schema.
const adapter = {
  name: 'rest',
  capabilities: { range: true, total: true },
  describe: async () => [{ name: 'id', type: 'Edm.Int32' }, { name: 'name', type: 'Edm.String' }, { name: 'at', type: 'Edm.DateTimeOffset' }],
  execute: async () => ({ rows: [{ id: 1, name: 'a', at: '2024-01-01T00:00:00Z' }], total: 1 }),
};

const designer = createDesigner(el, {
  mode: 'edit',
  pushdownDebounceMs: 150,
  sources: { api: { kind: 'pushdown', adapter, pageSize: 50 } },
  state: { pages: [{ id: 'p1', spec: { panels: [
    { id: 'rows', kind: 'grid', title: 'Rows', source: 'api' },
    { id: 'by', kind: 'chart', title: 'By name', source: 'api', options: { type: 'bar', x: 'name', y: { col: 'id', fn: 'avg' } } },
  ] } }] },
  factories: { createPushdownSource, createGrid, createHeadlessGrid, createLayout, createChart },
});

// Fields: the adapter's own, typed, with no row read to learn them.
const fields = (await designer.pushdown.describe('api')).map((f) => `${f.id}:${f.type}`).join(',');

// Refusals: named, with the reason.
const sum = designer.pushdown.refusal('api', { aggregation: 'sum' });
const steps = designer.pushdown.refusals('api').filter((r) => r.kind === 'step').map((r) => r.name).filter((n) => n !== 'filter' && n !== 'sort');

// The properties panel never commits a refused aggregation ...
designer.properties.selectPanel('by');
const edited = designer.properties.editRole({ role: 'y', aggregated: true, repeatable: false }, 0, 'id', 'sum');

// ... and a derived step the adapter cannot answer is refused, not computed over the window.
const derived = designer.commands.run('addDerivedGrid', { from: 'rows', steps: [] });
const pivoted = designer.commands.run('addDerivedStep', derived, { kind: 'pivot', rows: ['name'], column: 'id', measures: [{ of: 'id', fn: 'sum' }] });

designer.destroy();
return [fields, sum.slice(0, sum.indexOf(',')), steps.join(','), edited, pivoted].join(' | ');

Keys only: switch to edit mode, add three widgets, hear each one, and audit the chrome

const { createTestDom, TestEvent } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const rows = [{ id: 'a', region: 'north', sales: 10 }, { id: 'b', region: 'south', sales: 20 }];
const designer = createDesigner(el, {
  theme: 'auto',                                        // follows the system, live, in CSS
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  factories: { createGrid, createHeadlessGrid, createLayout },
  state: { pages: [{ id: 'p1', title: 'Sales', spec: { panels: [] } }] },
});
const said = () => el.querySelector('.lattice-designer-status').textContent;
const key = (letter) => designer.canvas.dispatchEvent(new TestEvent('keydown', { key: letter, code: `Key${letter}`, altKey: true, shiftKey: true }));

const seen = [designer.theme, designer.setTheme('dark')];
key('M'); seen.push(designer.mode, said());            // Alt+Shift+M
key('N'); seen.push(said());                           // a text widget
key('G'); seen.push(said());                           // a grid
key('N'); seen.push(said());
seen.push(designer.dashboard.panels().length, designer.audit().length);
seen.push(designer.regions.list().join(','), designer.shortcuts.list().length > 5);
designer.announce('Saved');
seen.push(said());
designer.destroy();
return seen.join(' | ');                               // auto | dark | edit | Edit mode | Text added: Text 1 | Grid added: Grid 1 | Text added: Text 2 | 3 | 0 | toolbar,palette,canvas | true | Saved

Undo and redo: one committed change is one step, undo restores the exact prior state, redo re-applies it, the toolbar and scoped shortcuts drive it, and a host setState clears it

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const rows = [{ id: 'a', region: 'north', sales: 10 }, { id: 'b', region: 'south', sales: 20 }];
const designer = createDesigner(el, {
  mode: 'edit',
  historyDepth: 3,
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    schemaVersion: 1,
    pages: [
      { id: 'p1', title: 'Sales', spec: { layout: { columns: 2, rows: 1 }, panels: [
        { id: 'table', kind: 'grid', title: 'Orders', source: 'sales' },
        { id: 'note', kind: 'html', title: 'Note', options: { text: 'Provisional figures.' } },
      ] } },
      { id: 'p2', title: 'Notes', spec: { panels: [{ id: 'only', kind: 'html', options: { text: 'Hello' } }] } },
    ],
    selectedPageId: 'p1',
    panels: {},
  },
  factories: { createGrid, createHeadlessGrid, createLayout },
});

const seen = [designer.canUndo(), designer.canRedo()];   // false, false

// One committed change: a page op, recorded at the single commit.
const causes = [];
designer.on('state', (event) => causes.push(event.cause));
designer.selectPage('p2');
seen.push(designer.canUndo(), designer.canRedo());       // true, false

// Undo restores the exact prior state and fires state with cause 'undo'...
seen.push(designer.undo(), designer.getState().selectedPageId, designer.canRedo());
// ...and redo re-applies it.
seen.push(designer.redo(), designer.getState().selectedPageId);

// The chrome carries the two buttons, enabled exactly when there is a step.
seen.push(designer.chrome.querySelectorAll('.lattice-designer-tool').length);

// A host setState clears the history unless it passes { keepHistory: true }.
designer.setState(designer.getState());
seen.push(designer.canUndo());

seen.push(causes.join(','));                             // selectPage,undo,redo
designer.destroy();
return seen.join(' | ');

Widgets restricted to grids, the locked note, and a run-time change that clears the guardrails

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const rows = [{ id: 'a', region: 'north', sales: 10 }, { id: 'b', region: 'south', sales: 20 }];
const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    schemaVersion: 1,
    pages: [{ id: 'p1', title: 'Sales', spec: {
      layout: { columns: 2, rows: 1 },
      panels: [
        { id: 'table', kind: 'grid', title: 'Orders', source: 'sales' },
        { id: 'note', kind: 'html', title: 'Note', options: { text: 'Provisional figures.' } },
      ],
    } }],
    selectedPageId: 'p1',
    panels: {},
  },
  factories: { createGrid, createHeadlessGrid, createLayout, createChart },
  guardrails: { widgets: ['grid'] },                  // only grids: the html note is locked
});
const seen = [];

// The live handle answers the same questions the palette would ask.
seen.push(designer.guardrails.allowsWidget('grid'), designer.guardrails.allowsWidget('html'));
seen.push(designer.guardrails.refuse('widget', 'html'));  // the guardrail that refuses it, by name
seen.push(designer.guardrails.widgetLimit() === null);

// The restricted note still renders, but edit mode pins it and hides the grips.
const note = [...designer.canvas.querySelectorAll('.lat-layout__window')]
  .find((n) => n.getAttribute('data-window-id') === 'note');
seen.push(note.getAttribute('data-locked'), note.querySelector('.lat-layout__grip') === null);

// Change the guardrails at run time, then clear them again.
seen.push(designer.setProperty('guardrails', { widgets: ['grid', 'html'] }));
seen.push(designer.guardrails.allowsWidget('html'));
seen.push(designer.setGuardrails(undefined));
seen.push(designer.getProperty('guardrails').widgets === null);

designer.destroy();
return seen.join(' | ');              // true | false | widgets | true | widgets | true | true | true | true | true

Selecting a widget by id, reading the selection, and adding then removing a widget - each one undoable state change

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const rows = [{ id: 'a', region: 'north', sales: 10 }, { id: 'b', region: 'south', sales: 20 }];
const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: { schemaVersion: 1, selectedPageId: 'p1', panels: {}, pages: [
    { id: 'p1', title: 'Sales', spec: {
      layout: { columns: 2, rows: 2, compact: 'none', windows: [
        { id: 'table', xPos: 1, yPos: 1, xSize: 1, ySize: 1 },
        { id: 'chart', xPos: 2, yPos: 1, xSize: 1, ySize: 1 } ] },
      panels: [
        { id: 'table', kind: 'grid', title: 'Orders', source: 'sales' },
        { id: 'chart', kind: 'chart', title: 'Revenue by region', source: 'grid:table',
          options: { type: 'bar', x: 'region', y: 'sales' } } ] } } ] },
  factories: { createGrid, createHeadlessGrid, createLayout, createChart },
});
const out = [];

// Select a widget: it drives selectedWidget() and takes an accessible name.
designer.selectWidget('chart');
const sel = designer.selectedWidget();
out.push(sel.id, sel.panel.title);
out.push(el.querySelector('[data-window-id="chart"]').getAttribute('aria-label'));

// The layout carries the selection too: select(id) is programmatic, selected() reads it.
out.push(designer.dashboard.layout.selected());
designer.dashboard.layout.select(null);
out.push(designer.dashboard.layout.selected() === null);

// Add a widget, then remove one: one undoable state event each.
const causes = [];
designer.on('state', (event) => causes.push(event.cause));
designer.addWidget({ id: 'extra', kind: 'html', title: 'Extra', options: { text: 'x' } }, { xPos: 1, yPos: 2, xSize: 2, ySize: 1 });
designer.removeWidget('table');
out.push(causes.join(','));
out.push(designer.getState().pages[0].spec.panels.map((p) => p.id).join(','));

designer.destroy();
return out.join(' | ');                              // chart | Revenue by region | Chart: Revenue by region, selected | chart | true | addWidget,removeWidget | chart,extra

A chart's editor generated from the registry: a measure with an aggregation, one event per edit, and a type switch that reports what it dropped

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

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

const rows = [{ id: 'a', region: 'north', sales: 10 }, { id: 'b', region: 'south', sales: 20 }];
const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    schemaVersion: 1,
    pages: [{ id: 'p1', title: 'Page', spec: { panels: [
      { id: 'c1', kind: 'chart', title: 'Chart', source: 'sales', options: { type: 'scatter', x: 'region', y: 'sales', size: 'sales' } },
    ] } }],
    selectedPageId: 'p1',
    panels: {},
  },
  factories: { createGrid, createHeadlessGrid, createChart, createLayout },
});

// The editor is generated from the registry: a scatter's roles, in order.
const roles = chartEditorModel('scatter').roles.map((r) => r.role).join(',');

// One edit is one state event; a measure carries its aggregation.
const props = designer.properties;
let events = 0;
const off = designer.on('state', () => { events += 1; });
const y = chartEditorModel('scatter').roles.find((r) => r.role === 'y');
props.editRole(y, 0, 'sales', 'avg');
const afterEdit = events;
const measure = designer.getState().pages[0].spec.panels[0].options.y;
const yStored = `${measure.col}/${measure.fn}`;

// A type switch keeps the compatible roles and reports the dropped one.
const switched = props.switchType('line');
const type = designer.getState().pages[0].spec.panels[0].options.type;
off();
designer.destroy();

return [roles, afterEdit, yStored, switched.dropped.join(','), type].join(' | ');

A grid's columns edited through the generated controls: pick a column, set its width and total, move it first, and turn on the grand total row

const { createTestDom, TestEvent } = await import('../packages/dom/src/renderer/testdom.js');
const { createGrid, createHeadlessGrid } = await import('../packages/dom/src/index.js');
const { createChart, chartEditorModel, registeredChartTypes } = await import('../packages/modules/charts/index.js');
const { createLayout } = await import('../packages/modules/layout/index.js');
const { createDesigner } = await import('../packages/modules/designer/index.js');

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

const rows = [{ id: 'a', region: 'north', sales: 10 }, { id: 'b', region: 'south', sales: 20 }];
const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    schemaVersion: 1,
    pages: [{ id: 'p1', title: 'Page', spec: { panels: [
      { id: 'g1', kind: 'grid', title: 'Orders', source: 'sales', options: { columns: [{ field: 'region' }] } },
    ] } }],
    selectedPageId: 'p1',
    panels: {},
  },
  // The chart metadata comes from the charts module the host loaded.
  factories: { createGrid, createHeadlessGrid, createChart, createLayout, chartEditorModel, registeredChartTypes },
});

// Find a generated control by its accessible name, and change it as a person would.
const panel = designer.properties.el;
const control = (name) => ['select', 'input', 'button'].flatMap((tag) => panel.querySelectorAll(tag))
  .find((n) => n.getAttribute('aria-label') === name);
const change = (name, value) => {
  const c = control(name);
  if (c.type === 'checkbox') c.checked = value; else c.value = value;
  c.dispatchEvent(new TestEvent('change', {}));
};
const columns = () => designer.getState().pages[0].spec.panels[0].options.columns;

change('Columns 2', 'sales');                       // the trailing row adds a column
const picked = columns().map((c) => c.field).join(',');

let events = 0;
const off = designer.on('state', () => { events += 1; });
change('Columns 2 width', '140');                  // one edit, one state event
const oneEvent = events;
off();

const total = control('Columns 2 total');          // an enum: its choices are the registry's values
change('Columns 2 total', total.querySelectorAll('option').find((o) => o.textContent === 'sum').value);
control('Move Columns 2 (sales) earlier').dispatchEvent(new TestEvent('click', {}));
change('Grand total row', true);

const spec = designer.getState().pages[0].spec.panels[0].options;
const first = spec.columns[0];
const minWidth = control('Columns 1 width').getAttribute('min');   // the registry's range is on the control
designer.destroy();

return [picked, oneEvent, spec.columns.map((c) => c.field).join(','), `${first.layout.width}/${first.total}`, spec.grandTotalRow, minWidth].join(' | ');

Add a calculated field, see its type and preview, read it in the grid, and get a named error for a misspelt field

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

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

const rows = [{ id: 'a', revenue: 100, cost: 60 }, { id: 'b', revenue: 200, cost: 50 }];
const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rows, rowKey: 'id' } },
  state: {
    schemaVersion: 1,
    pages: [{ id: 'p1', title: 'Page', spec: { panels: [{ id: 'g1', kind: 'grid', title: 'Sales', source: 'sales' }] } }],
    selectedPageId: 'p1',
    panels: {},
  },
  factories: { createGrid, createHeadlessGrid, createChart, createLayout },
});

const calc = designer.calculated;
const preview = calc.preview('sales', 'revenue - cost');           // the type and the first rows
const shown = preview.rows.map((r) => r.value).join(',');
const bad = calc.add('sales', { id: 'oops', expression: 'revenue - revnue' });  // refused, by name

let events = 0;
const off = designer.on('state', () => { events += 1; });
calc.add('sales', { id: 'margin', label: 'Margin', expression: 'revenue - cost' });  // one commit
const grid = designer.dashboard.panel('g1').grid;
const margin = grid.rows.value('a', 'margin');                     // a field like any other
off();
designer.undo();                                                   // one undo step removes it
const left = calc.list('sales').length;
designer.destroy();

return [preview.type, shown, margin, `${bad.errors[0].token} at ${bad.errors[0].at}`, events, left].join(' | ');

A derived grid grouped and rolled up from its parent, its lineage, and a step undone

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const designer = createDesigner(el, {
  mode: 'edit',
  sources: {
    orders: {
      kind: 'rows', rowKey: 'id',
      rows: [
        { id: '1', rep: 'Ana', region: 'EU', amount: 100 }, { id: '2', rep: 'Ben', region: 'EU', amount: 40 },
        { id: '3', rep: 'Ana', region: 'US', amount: 60 }, { id: '4', rep: 'Cy', region: 'US', amount: 200 },
      ],
      fields: [{ id: 'rep', type: 'text' }, { id: 'region', type: 'text' }, { id: 'amount', type: 'number' }],
    },
  },
  state: { pages: [{ id: 'p1', spec: { panels: [{ id: 'orders', kind: 'grid', title: 'Orders', source: 'orders' }] } }], selectedPageId: 'p1' },
  factories: { createGrid, createHeadlessGrid, createLayout },
});

// Build a derived grid: the sales, grouped by rep, with each rep's revenue - // a `grid:orders` source re-derived whenever the orders grid changes.
const id = designer.commands.run('addDerivedGrid', {
  from: 'orders', title: 'Top reps', fromLabel: 'Orders',
  steps: [{ kind: 'group', by: 'rep', measures: [{ id: 'amount', of: 'amount', fn: 'sum' }] }],
});

const panel = designer.getState().pages[0].spec.panels.find((p) => p.id === id);
const repCol = panel.options.columns.find((c) => c.field === 'rep');
const amountCol = panel.options.columns.find((c) => c.field === 'amount');
const lineage = designer.derived.lineage(id);

// Provenance and refusals: a memory parent pushes nothing down, so the engine
// is null, every step is client-side, and nothing is refused.
const provenance = designer.derived.provenance(id);
const refusals = designer.derived.refusals(id);

// A second step, then undo it: each step is one undoable change.
designer.commands.run('addDerivedStep', id, { kind: 'sort', by: [{ col: 'amount', dir: 'desc' }] });
const after = designer.derived.steps(id).length;
designer.undo();
const undone = designer.derived.steps(id).length;
designer.destroy();

return [panel.source, repCol.group.enabled, amountCol.total, lineage, provenance.engine, provenance.pushed.length, refusals.length, after, undone].join(' | ');

A grid's route carries only its fields and its GROUP BY; changing one widget's aggregation re-plans only that widget; a page filter change re-plans every widget on the page

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const designer = createDesigner(el, {
  mode: 'view',
  sources: { orders: { kind: 'rows', rowKey: 'id', rows: [{ id: '1', region: 'EU', amount: 100 }] } },
  state: {
    pages: [{
      id: 'p1',
      filters: [],
      spec: {
        panels: [
          { id: 'a', kind: 'grid', source: 'orders', options: { columns: [{ field: 'region', group: true }, { field: 'amount', total: 'sum' }] } },
          { id: 'b', kind: 'grid', source: 'orders', options: { columns: [{ field: 'amount', total: 'avg' }] } },
        ],
      },
    }],
    selectedPageId: 'p1',
  },
  factories: { createGrid, createHeadlessGrid, createLayout },
});

// Widget `a`'s route: only the fields its columns bind, and its GROUP BY.
const routeA = designer.dataRoutes.route('a');
const routeBBefore = designer.dataRoutes.route('b');

// Edit only `a`'s aggregation - one state change: re-plans and re-requests only `a`.
const state = designer.getState();
state.pages[0].spec.panels[0].options.columns[1].total = 'avg';
designer.setState(state, { keepHistory: true });

const routeAAfter = designer.dataRoutes.route('a');
const routeBAfter = designer.dataRoutes.route('b');
const requestsBefore = designer.dataRoutes.requests().length;

// A page filter change is not on either widget's own row, yet both read it.
state.pages[0].filters = [{ id: 'f1', source: 'orders', field: 'region', op: 'eq', value: 'EU' }];
designer.setState(state, { keepHistory: true });
const bothStale = designer.dataRoutes.route('a') !== routeAAfter && designer.dataRoutes.route('b') !== routeBAfter;
const requestsAfter = designer.dataRoutes.requests().length;

designer.destroy();

return [
  routeA.fields.join(','),
  routeA.groupBy.join(','),
  routeAAfter.aggregates[0].fn,
  routeBAfter === routeBBefore,
  requestsAfter - requestsBefore,
  bothStale,
].join(' | ');

A stub model proposes a grid, the preview is accepted as one undoable step, and undo restores the page

const { createTestDom } = 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 { createDesigner } = await import('../packages/modules/designer/index.js');

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

const rows = [{ region: 'north', sales: 10 }, { region: 'south', sales: 20 }];
// The host's model: a stub that answers with a grid proposal. The designer
// hands it the request; it carries no key and no endpoint.
const ask = async () => ({ panels: [
  { id: 'grid', kind: 'grid', source: 'sales', title: 'Sales by region', options: { columns: [{ field: 'region' }, { field: 'sales' }] } },
] });

const designer = createDesigner(el, {
  mode: 'edit',
  sources: { sales: { kind: 'rows', rows, fields: [{ id: 'region', type: 'text' }, { id: 'sales', type: 'number' }] } },
  state: { schemaVersion: 1, pages: [{ id: 'p1', title: 'Sales', spec: { panels: [] } }], selectedPageId: 'p1', panels: {} },
  llm: ask,
  factories: { createGrid, createHeadlessGrid, createLayout },
});

const seen = [];
const result = await designer.assist.propose('Add a grid of sales by region');
seen.push(result.ok, result.diff.added.join(','), result.warnings.length);      // true, grid, 0
seen.push(designer.assist.pending !== null);                                     // true (a preview is showing)
seen.push(designer.assist.accept());                                             // true (one undo step)
seen.push(designer.getState().pages[0].spec.panels.map((p) => p.id).join(',')); // grid
seen.push(designer.undo());                                                      // true (the accept, undone)
seen.push(designer.getState().pages[0].spec.panels.length);                      // 0
designer.destroy();
return seen.join(' | ');