Data and selection API

Dataset replacement

setData(input) is a complete reinitialization boundary. It validates and replaces the authoritative dataset, then clears selection, filters, plot state, prepared data, summaries, and dataset-derived UI state. Construction options and host event subscriptions remain installed.

Rows are rectangular JSON-compatible records containing only string, finite number, boolean, or null values. The configured row-ID column must exist and contain unique, non-empty string or finite-number values. IDs are normalized to strings. Invalid input rejects the complete replacement.

replaceData(input) is the state-preserving replacement boundary. It requires an existing dataset, validates the new table against the complete current workspace, and commits only when the workspace and visible plots remain valid. Failure leaves the previous dataset, workspace, and selection unchanged; it does not partially repair incompatible columns or plot configuration.

On success, replaceData preserves layout, active plot, all four plot states, filters, presets, and the selected preset name. Selection IDs absent from the new table are removed in their existing order. If the primary ID is absent it becomes null, even when other selected IDs survive. This host operation does not emit a user selection event.

Callers may provide a complete column schema and an ordered preFilterColumns list. When preFilterColumns is omitted, NicePool retains its conventional accept, channel, and roi_id filters when those columns exist. Supplying [] disables prefilters. A listed column appears in the Filters panel with All selected until a PlotState.preFilters value is set.

Each declared column provides a nonempty axis_label used for rendered plot axes and may provide a nonempty category. The four column selectors present eligible columns in category groups while preserving schema order. Category is presentation metadata and is independent of the categorical capability flag.

Column storage type and categorical presentation are independent. A numeric column declared with categorical: true remains available to numeric plots and also appears in Group and Color controls. Numeric categories are ordered by numeric value; other categories retain canonical string ordering. The row-ID column is never offered as an X, Y, Group, or Color choice.

Missing values

null is the only missing-value representation. Every row must include every dataset column; adapters must turn an absent CSV/table cell into null. undefined, NaN, infinity, arrays, objects, and dates are rejected.

The authoritative dataset retains rows containing null. A particular plot projection omits a row only when that plot requires a missing X, Y, Group, or Color-by value. An inactive filter includes missing rows, while null is not offered as a filter choice. NicePool does not invent a synthetic “(missing)” category.

Selection

Selection contains an optional primary row and a multi-row set:

interface NicePoolSelection {
  primaryRowId: string | null
  selectedRowIds: readonly string[]
}

Host calls do not emit user-selection events. Plot interactions emit selection-change from the Vue component and nicepool-selection-change from the Custom Element. Ordinary filtering preserves hidden selections; setData clears all selection, while replaceData prunes it.

An area selection replaces the shared selected-row set. A point click replaces it with exactly one primary row. Clearing selection publishes an empty set to every Plotly view. Each change also advances Plotly's selectionrevision, so Plotly cannot retain stale multi-selected points as internal interaction state. Selection events emitted by Plotly.react during programmatic synchronization are ignored; only genuine Plotly user events update the authoritative model.

The Custom Element also emits nicepool-state-change, nicepool-presets-change, nicepool-theme-change, nicepool-data-reset, and nicepool-data-replaced. Reset and replacement events are mutually exclusive. Host-facing methods include setState, getState, setNicePoolPresets, getNicePoolPresets, and applyNicePoolPreset in addition to the data and selection methods. setShowPresetEditing toggles the optional Name, Save, and Delete controls without hiding preset selection. setTheme('dark' | 'light') and getTheme() expose the presentation theme without changing serialized workspace state. setControlsCollapsed(true | false) and getControlsCollapsed() control the left controls panel without changing plot state or presets. Expanding restores the most recent nonzero controls width.

NiceGUI boundary

Python clients use NicePoolWebView from the nicewidgets package. The adapter converts pandas missing values, serves the bundled Custom Element, and exchanges data, state, and selection only through public element methods and custom events. Python hosts do not prepare plots or own selection.