doxa-maps/library/dashboards/README.md

The dashboard kit contract

Four panels — a map, a data table, a charts rail and a detail drawer — behave as one dashboard without importing each other. This file is the contract they share. It is documentation of what exists today, verified against development, not a proposal.

The components still live in plugin-designs/research-dashboard/src/components/dashboards/. They are not in library/ yet. Under the repo's "reusable by default" rule (skills/plugin-designer, section 3), a component another dashboard could use belongs in library/, driven by props; moving these is a library change for the build owner.

The shape

One composable provides; every panel injects. Nothing is passed down as props, and no panel imports another.

plugin-designs/research-dashboard/src/composables/useDashboardShell.js provides five keys:

key	what it is
selectionBus	the shared event bus and selection/filter state (library/composables/useSelectionBus.js)
dashboardData	the row store the panels read
dashboardConfig	per-profile configuration — labels, colours, which column is the photo
dataStore	the underlying data source
searchSourceId	identifies whose search a result belongs to

A panel takes what it needs and tolerates absence:

const dash = inject('dashboardData', null)
const bus  = inject('selectionBus', null)
const cfg  = inject('dashboardConfig', {})

The null defaults are load-bearing. A panel rendered outside a shell must degrade, not throw — a thrown setup() removes the subtree with an empty error and no build failure, which is expensive to diagnose.

The bus carries two different things

on(event, cb) and emit(event, payload) are generic: any string is a valid event. That makes the bus easy to extend and easy to misread, so the distinction matters.

State events — owned by useSelectionBus, emitted only by it, in response to its own mutators:

event	payload	emitted when
filter	filterSet	setFilter, clearFilters, toggleFilterValue
select	selectionSet	toggleSelect, selectMany, deselectMany, setSelection, clearSelection
search	the term	setSearch
hover	the key, or null	setHover

UI events — passed through the same bus by panels, with no composable behind them: focusRow, mapFocus, toggleTable, toggleRail, toggleFacet, resetLayout, layoutResizing.

★ Do not look for a state event's emitter in the panels. Two panels listen for select and no panel emits it; the emitter is useSelectionBus.js:202. Grepping components for the bus's traffic cannot see the bus itself, and reading that absence as a dead contract is a mistake worth naming here because it has already been made twice while auditing this kit.

Selection does not travel by emit

selectionSet is a plain Set<slug>, deliberately not reactive — a per-row toggleSelect() loop firing a synchronous emit('select') per row is why. selectionVersion is the reactive handle: watch that, read the Set.

So a panel reacting to selection watches selectionVersion (or subscribes to select) and then reads bus.selectionSet. The table writes into it; the map frames its camera off the full row store rather than the filtered rows, so a record selected and then filtered out of scope still shows.

What each panel does with it today

panel	reads	writes
data table	selectionSet, filter	selectionSet, toggleTable
map panel	select, focusRow, toggleTable, layoutResizing	focusRow, mapFocus
detail drawer	select, focusRow	—
charts rail	filterSet via isFilterActive / rowMatchesFilters	setFilter

★ The charts rail participates in filtering only. Clicking a slice narrows the map; selecting a pin does not highlight its slice, because the rail neither emits nor listens for select. That is the current contract, not an oversight to fix casually — whether selection should reach the charts is a product decision, and it is open.

Adding a panel

Inject the three keys with null/{} defaults, subscribe in setup, and unsubscribe on unmount — on() returns its own unsubscribe function. Read state from bus, never from another panel. If a new cross-panel signal is needed, prefer a state event with a mutator on the composable over a new ad-hoc UI event: the ad-hoc ones are invisible to anyone reading useSelectionBus.js, which is where a maintainer looks first.