# Premium and feature events

> WestCoast Charts 1.1.5, release, public Core release, on npm. HTML: https://westcoast-charts.com/docs/reference/premium-events/ · Index for agents: https://westcoast-charts.com/llms.txt · Source: library guide, commit 95f093ba

> Generated from `types/premium-events.d.ts` and checked against literal emitters in `src/premium` and `src/features`. Edit the declarations, then run `node tools/docs/gen-events.cjs`.

`chart.eventSignature` defaults to `'legacy'`: each family keeps its established argument order. With `'standard'`, premium and feature callbacks and `chart.addEventListener()` listeners receive `(eventOrNull, chart, payload)`. Synthetic events use `null`; the Sankey `error` event supplies its `Error` as origin. Core lifecycle callbacks such as `mounted(chart, options)` are unchanged.

Inline chart-options callbacks remain permissively typed for compatibility, including strict TypeScript projects that omit eventSignature. Use named WccStandardEventHandler<Payload> or WccLegacyEventHandler<EventName> handlers for precise payload types. The eventSignature option selects the runtime argument convention; it does not change TypeScript contextual inference.

Event names are case-sensitive. Premium `drilldown` / `drillup` and feature `drillDownStart` / `drillDownEnd` / `drillUp` are separate contracts. Only rows marked cancelable use a callback return value of `false` to reject the pending operation. Notifications (including history replay) cannot be assumed to undo an action.

```ts
const onSelect: WccStandardEventHandler<WccPremiumEventPayloads['quintSelect']> =
  (event, chart, payload) => { console.log(payload.keys) }
const options = { chart: { eventSignature: 'standard' as const, events: { quintSelect: onSelect } } }
```

| Event | Family | Legacy arguments | Standard arguments | Payload | Cancelable | Meaning |
| --- | --- | --- | --- | --- | --- | --- |
| `beatChange` | storyboard | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ index: number; key?: string \| number; previous: number; direction: -1 \| 0 \| 1; element: Element \| null }` | No | The active story beat changed. |
| `childrenLoad` | tree | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ w: WccEventChartState; id: string; node: WccEventRecord; children: WccEventRecord[] }` | No | Lazy children arrived. |
| `childrenLoadError` | tree | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ w: WccEventChartState; id: string; node: WccEventRecord; error: unknown }` | No | Loading lazy children failed. |
| `crossFilter` | link | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ sourceChartID: string; xaxis: { min: number; max: number } }` | No | A linked range filter changed. |
| `dataPointMouseEnter` | gantt, sankey, stock, tree | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccTaskPointEvent \| WccFlowPointEvent \| WccStockPointEvent \| WccTreePointEvent` | No | The pointer entered a premium mark; narrow by its family payload fields. |
| `dataPointMouseLeave` | gantt, sankey, tree | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccTaskPointEvent \| WccFlowPointEvent \| WccTreePointEvent` | No | The pointer left a premium mark. |
| `dataPointSelection` | chord, gantt, map, marimekko, network, radialColumn, sankey, stock, tree | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccPremiumPointEvent` | No | A premium mark was selected; payload shape is family-specific. |
| `dependencyCreate` | gantt | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccDependencyEvent` | Yes — return false | A dependency is proposed; false rejects creation. |
| `dependencyDelete` | gantt | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccDependencyEvent` | Yes — return false | A dependency is proposed for removal; false rejects removal. |
| `drawingChange` | stock | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ w: WccEventChartState; action: string; drawing: WccStockDrawing \| null; drawings: WccStockDrawing[] }` | Yes — return false | A drawing is added, edited or removed; false rejects the change. |
| `drilldown` | sankey, map | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccPremiumDrillEvent` | Yes — return false | A premium level is about to open; false rejects navigation. |
| `drillDownEnd` | drilldown feature | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccFeatureDrillEvent` | No | A core drilldown transition completed; case-sensitive name. |
| `drilldownError` | sankey, map | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccPremiumDrillEvent` | No | A premium level loader failed. |
| `drillDownError` | drilldown feature | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ id: string \| number; error: unknown }` | No | A core drilldown loader failed; case-sensitive name. |
| `drillDownStart` | drilldown feature | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccFeatureDrillEvent` | No | A core drilldown transition started; case-sensitive name. |
| `drillup` | sankey, map | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccPremiumDrillEvent` | Yes — return false | A premium level is about to close; false rejects navigation. |
| `drillUp` | drilldown feature | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccFeatureDrillEvent` | No | A core drill-up transition completed; case-sensitive name. |
| `error` | sankey | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ type: 'sankey'; cycle: string[] }` | No | The Sankey cycle policy rejected input; the origin argument is the error. |
| `filterChange` | link | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ filters: Record<string, unknown>; filteredCount: number; total: number; sourceChartID: string; key: unknown }` | No | A crossfilter bucket selection or clear changed the filter set. |
| `groupToggle` | gantt | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ w: WccEventChartState; group: string; collapsed: boolean }` | No | A task group was collapsed or expanded. |
| `highlightFilterChanged` | highlight-filter | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ active: boolean; phase: 'enter' \| 'update' \| 'clear' }` | No | The highlight filter was applied, updated or cleared. |
| `historyChange` | gantt | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ w: WccEventChartState; action: string; entry: WccEventRecord; canUndo: boolean; canRedo: boolean; undo: number; redo: number }` | No | The Gantt edit history changed. |
| `layoutSettled` | network | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ nodes: number }` | No | A network layout reached its settled position. |
| `legendClick` | marimekko, radialColumn | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ seriesName: string; hidden: boolean }` | No | A premium legend toggle changed visibility; false does not veto it. |
| `nodeDragEnd` | network | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ node: WccEventNetworkNode }` | No | A network node drag ended. |
| `nodeMove` | sankey | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ w: WccEventChartState; node: { id: string; name: string }; offset: number }` | No | A Sankey node drag ended; offset is the layout-axis displacement. |
| `nodeToggle` | tree | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccTreePointEvent` | Yes — return false | A tree node is about to toggle; collapsed is the proposed state and false rejects it. |
| `panelMounted` | trellis | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccPanelEvent` | No | A trellis panel mounted or remounted. |
| `panelPromoted` | trellis-extras | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccPanelEvent` | No | A trellis panel was promoted to the main view. |
| `panelRestored` | trellis-extras | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccPanelEvent` | No | A promoted panel was restored to the grid. |
| `perspectiveApplied` | perspectives | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccPerspectiveEvent` | No | A captured view state was applied. |
| `perspectiveCaptured` | perspectives | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccPerspectiveEvent` | No | A view state was captured. |
| `playbackFrame` | sankey | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `{ w: WccEventChartState; frame: number; label?: string }` | No | A Sankey playback frame changed. |
| `quintLens` | quintTimeline, quintConvergence | `(payload, chart)` | `(eventOrNull, chart, payload)` | `{ enabled: boolean }` | No | The Quint lens was enabled or disabled. |
| `quintPin` | quintTimeline, quintConvergence | `(payload, chart)` | `(eventOrNull, chart, payload)` | `{ time: number \| null; slot: number \| null }` | No | The Quint time pin changed or was cleared. |
| `quintSelect` | quintTimeline, quintConvergence | `(payload, chart)` | `(eventOrNull, chart, payload)` | `{ keys: string[] \| null }` | No | The selected Quint keys changed or were cleared. |
| `scheduleChange` | schedule | `(payload, chart)` | `(eventOrNull, chart, payload)` | `WccScheduleProposalEvent` | No | A controlled move proposal was produced; the application decides whether to apply it. |
| `scheduleConflict` | schedule | `(payload, chart)` | `(eventOrNull, chart, payload)` | `{ conflicts: WccScheduleConflictEvent[] }` | No | Once per render, conflicts in the visible schedule are reported. |
| `scheduleSelect` | schedule | `(payload, chart)` | `(eventOrNull, chart, payload)` | `{ item: string \| null; person: string \| null }` | No | The selected appointment or highlighted person changed. |
| `slotClick` | schedule | `(payload, chart)` | `(eventOrNull, chart, payload)` | `{ time: number; lane: string \| null; by: 'person' \| 'resource'; day: number }` | No | Free schedule time was clicked. |
| `taskChange` | gantt | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccTaskChangeEvent` | Yes — return false | A task edit is proposed; false rejects it. |
| `taskCreate` | gantt | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccTaskMutationEvent` | Yes — return false | A task creation is proposed; false rejects it. History replay also reports this event. |
| `taskDelete` | gantt | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccTaskMutationEvent` | Yes — return false | A task deletion is proposed; false rejects it. History replay also reports this event. |
| `trellisMounted` | trellis | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ panels: WccPanelEvent[] }` | No | The trellis grid mounted or changed its mounted panels. |
| `wccDrillPathChange` | drilldown feature | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ path: Array<string \| number>; depth: number }` | No | The current drill path changed. |
| `wccFrameChange` | narrative | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ index: number; t?: number \| string; label: string; direction: number }` | No | The narrative frame changed. |
| `wccHistoryChange` | history feature | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccHistoryPositionEvent` | No | The shared history journal position changed. |
| `wccNarrativeState` | narrative | `(chart, payload)` | `(eventOrNull, chart, payload)` | `{ playing: boolean; live: boolean }` | No | Narrative playback state changed. |
| `wccOrientChange` | orient | `(chart, payload)` | `(eventOrNull, chart, payload)` | `WccOrientChangeEvent` | No | The radial view orientation changed. |
| `zoomed` | gantt, stock, network | `(event, chart, payload)` | `(eventOrNull, chart, payload)` | `WccZoomEvent` | No | A premium date range or network scale changed. |

## Payload contracts

Required and optional fields, unions for per-family selections, and reusable nested structures are declared below. Raw caller data and error values stay `unknown`; no promise is made about renderer internals in `w`.

```ts
type WccEventRecord = Record<string, unknown>

type WccEventOrigin = Event | Error | null

interface WccEventChartState { config: ApexCharts.ApexOptions; globals: WccEventRecord }

interface WccEventPointIndex { seriesIndex: number; dataPointIndex: number; w?: WccEventChartState }

interface WccEventFlow { from: string; to: string; value: number }

interface WccEventNode { id: string; name: string; value?: number; inflow?: number; outflow?: number; column?: number }

interface WccEventNetworkNode { id: string; name: string; group?: string; value?: number; degree: number; keys?: string[] }

interface WccEventTask { id: string; name: string; start: number; end: number; progress?: number; group: string; critical: boolean }

interface WccTaskPointEvent extends WccEventPointIndex { task: WccEventTask; selected?: string[] }

interface WccTreePointEvent extends WccEventPointIndex { node: WccEventRecord; id: string; name: string; depth: number; collapsed: boolean; children: number }

interface WccStockPointEvent extends WccEventPointIndex { x: number; open: number; high: number; low: number; close: number; volume?: number }

interface WccFlowPointEvent extends WccEventPointIndex { kind: 'link' | 'node'; link?: WccEventFlow; node?: WccEventNode }

interface WccNetworkPointEvent extends WccEventPointIndex { node?: WccEventNetworkNode; edge?: { from: string; to: string; weight: number; causal?: boolean } }

interface WccMapPointEvent extends WccEventPointIndex { id?: string; name?: string; value?: number; distance?: number; data?: unknown; properties?: WccEventRecord; selected: boolean }

interface WccMekkoPointEvent extends WccEventPointIndex { category: string; series: string; value: number }

interface WccRadialPointEvent {
  seriesIndex?: number; dataPointIndex?: number; category?: string;
  values?: Array<{ series: string; value: number | null }>;
  layerIndex?: number; layer?: string; flow?: WccEventFlow;
  segment?: { name: string; value?: number | null; path: string[]; row?: unknown; col?: unknown };
  linked?: string[]; selected: boolean
}

type WccPremiumPointEvent = WccTaskPointEvent | WccTreePointEvent | WccStockPointEvent | WccFlowPointEvent | WccNetworkPointEvent | WccMapPointEvent | WccMekkoPointEvent | WccRadialPointEvent

interface WccScheduleConflictEvent {
  id: string; type: 'room' | 'person' | 'transfer' | 'hours'; severity: 'error' | 'warning';
  items: string[]; resource?: string; person?: string; resources?: string[];
  from: number; to: number; gap?: number; outside?: number; text: string
}

interface WccSchedulePosition { start: number; end: number; resource: string; people: string[] }

interface WccScheduleProposalEvent { id: string; from: WccSchedulePosition; to: WccSchedulePosition; conflicts: WccScheduleConflictEvent[]; added: WccScheduleConflictEvent[]; resolved: WccScheduleConflictEvent[] }

interface WccTaskChangeEvent extends WccTaskPointEvent { start: number; end: number; previous: { start: number; end: number; name?: string }; source: string; name?: string }

interface WccTaskMutationEvent { w?: WccEventChartState; seriesIndex: number; index: number; data: WccEventRecord; source: string; start?: number; end?: number; task?: WccEventTask; dataPointIndex?: number }

interface WccDependencyEvent { w: WccEventChartState; from: string; to: string; type?: 'FS' | 'SS' | 'FF' | 'SF'; lag?: number; source: string }

interface WccPremiumDrillEvent { w: WccEventChartState; id?: string; name?: string; value?: number; depth: number; label?: string; error?: unknown }

interface WccFeatureDrillEvent { from: string | number | null; to: string | number | null; point?: unknown; seriesIndex?: number; dataPointIndex?: number }

interface WccHistoryPositionEvent { index: number; size: number; canUndo: boolean; canRedo: boolean }

type WccPanelKey = string | number | boolean | null | WccPanelKey[]

interface WccPanelEvent { key: WccPanelKey; index?: number; chart?: ApexCharts | null; el?: Element; remounted?: boolean }

interface WccPerspectiveEvent { state: WccEventRecord; requested?: WccEventRecord }

interface WccOrientChangeEvent extends WccOrientState { previous: number; picked: string | null }

interface WccZoomEvent { w?: WccEventChartState; xaxis?: { min: number; max: number }; scale?: number }
```

## Source coverage

Every literal premium/feature chart event must have a declaration; conditional event names are included. The generator rejects unknown or stale event names. Low-level crossfilter-engine `.on('change')` listeners are engine events, separate from `chart.events.filterChange` and `chart.events.crossFilter`.

| Event | Emitters |
| --- | --- |
| `beatChange` | `src/features/storyboard/index.js` |
| `childrenLoad` | `src/premium/tree/Tree.js` |
| `childrenLoadError` | `src/premium/tree/Tree.js` |
| `crossFilter` | `src/features/link/Controller.js` |
| `dataPointMouseEnter` | `src/premium/gantt/Gantt.js`, `src/premium/sankey/Sankey.js`, `src/premium/stock/Stock.js`, `src/premium/tree/Tree.js` |
| `dataPointMouseLeave` | `src/premium/gantt/Gantt.js`, `src/premium/sankey/Sankey.js`, `src/premium/tree/Tree.js` |
| `dataPointSelection` | `src/premium/chord/Chord.js`, `src/premium/gantt/Gantt.js`, `src/premium/map/GeoMap.js`, `src/premium/marimekko/Marimekko.js`, `src/premium/network/Network.js`, `src/premium/radial/RadialColumn.js`, `src/premium/sankey/Sankey.js`, `src/premium/stock/Stock.js`, `src/premium/tree/Tree.js` |
| `dependencyCreate` | `src/premium/gantt/extras.js` |
| `dependencyDelete` | `src/premium/gantt/extras.js` |
| `drawingChange` | `src/premium/stock/drawings.js` |
| `drillDownEnd` | `src/features/drilldown/Controller.js` |
| `drillDownError` | `src/features/drilldown/Controller.js` |
| `drillDownStart` | `src/features/drilldown/Controller.js` |
| `drillUp` | `src/features/drilldown/Controller.js` |
| `drilldown` | `src/premium/base/drill.js` |
| `drilldownError` | `src/premium/base/drill.js` |
| `drillup` | `src/premium/base/drill.js` |
| `error` | `src/premium/sankey/Sankey.js` |
| `filterChange` | `src/features/link/Controller.js` |
| `groupToggle` | `src/premium/gantt/Gantt.js` |
| `highlightFilterChanged` | `src/features/highlight-filter/Controller.js` |
| `historyChange` | `src/premium/gantt/Gantt.js` |
| `layoutSettled` | `src/premium/network/Network.js` |
| `legendClick` | `src/premium/marimekko/Marimekko.js`, `src/premium/radial/RadialColumn.js` |
| `nodeDragEnd` | `src/premium/network/Network.js` |
| `nodeMove` | `src/premium/sankey/Sankey.js` |
| `nodeToggle` | `src/premium/tree/Tree.js` |
| `panelMounted` | `src/features/trellis/Host.js` |
| `panelPromoted` | `src/features/trellis-extras/host.js` |
| `panelRestored` | `src/features/trellis-extras/host.js` |
| `perspectiveApplied` | `src/features/perspectives/index.js` |
| `perspectiveCaptured` | `src/features/perspectives/index.js` |
| `playbackFrame` | `src/premium/sankey/Sankey.js` |
| `quintLens` | `src/premium/layers/quint/Quint.js` |
| `quintPin` | `src/premium/layers/quint/Quint.js` |
| `quintSelect` | `src/premium/layers/quint/Quint.js` |
| `scheduleChange` | `src/premium/layers/schedule/Schedule.js` |
| `scheduleConflict` | `src/premium/layers/schedule/Schedule.js` |
| `scheduleSelect` | `src/premium/layers/schedule/Schedule.js` |
| `slotClick` | `src/premium/layers/schedule/Schedule.js` |
| `taskChange` | `src/premium/gantt/Gantt.js` |
| `taskCreate` | `src/premium/gantt/Gantt.js` |
| `taskDelete` | `src/premium/gantt/Gantt.js` |
| `trellisMounted` | `src/features/trellis/Host.js` |
| `wccDrillPathChange` | `src/features/drilldown/Controller.js`, `src/features/drilldown/index.js` |
| `wccFrameChange` | `src/features/narrative/index.js` |
| `wccHistoryChange` | `src/features/history/index.js` |
| `wccNarrativeState` | `src/features/narrative/index.js` |
| `wccOrientChange` | `src/features/orient/index.js` |
| `zoomed` | `src/premium/gantt/Gantt.js`, `src/premium/network/Network.js`, `src/premium/stock/Stock.js` |