Creates a new scatter trace instance and organizes data by X and Y coordinates.
The MAIDR layer containing scatter plot data
Protected ReadonlyobserversProtectedisProtectedisTrue while AbstractTrace.getStateAt computes state at a temporarily moved cursor. Enforces (structurally, not just by documentation) that state getters never notify observers.
Protected ReadonlyidProtected ReadonlytypeProtected ReadonlytitleProtected ReadonlyxProtected ReadonlyyProtected ReadonlyzProtected ReadonlynavigationProtected ReadonlylayerProtected ReadonlymovableProtected ReadonlysupportsAbstract property that subclasses must implement to indicate extrema support
ProtectedhighlightGets the current state of the trace including audio, braille, text, and highlight information.
The current TraceState
ProtectedautoplayThe trace's chart type. Lightweight alternative to reading
state.traceType, which eagerly computes the full audio/braille/text/
highlight state just to expose this one string.
ProtectedhighlightReturns the appropriate highlight elements based on current navigation mode.
SVG elements for X-based or Y-based highlighting depending on mode
ProtectedvaluesProtectedbrailleProtectedaudioProtectedtextGets the description state for the scatter trace.
The description state containing chart metadata and data table
ProtecteddimensionProtectedhighlightProtectedhasProtectedoutReturns out-of-bounds state with correct position for grid mode panning. In grid mode, uses gridCol/gridRow for correct left/right audio panning.
ProtectedgetGets safe row and column indices to prevent accessing undefined values
Object with safe row and column indices
Registers an observer to receive state updates.
The observer to add
Removes an observer from receiving state updates.
The observer to remove
Notifies all registered observers with the current state.
Notifies observers that an out-of-bounds condition occurred.
Base implementation of navigation in HIGHER and LOWER modes of ROTOR, default is no-op Needs to be implemented in Line, Bar, Heatmap, Candlestick
Utility function to compare point values for rotor functionality
boolean value
Returns the rotor's compare-mode labels and boundary-message nouns. Override to rename the two compare units for a trace-specific semantic (e.g., the candlestick delta layer uses "above line" / "below line").
Get all highlight SVG elements for this trace Used by HighlightService for high contrast mode
Array of all SVG elements, or empty array if none
Get all original (visible) SVG elements for this trace. These are the actual rendered elements, not the hidden clones used for highlighting. Used by HighlightService for high contrast mode color changes.
Array of all original SVG elements, or empty array if none
Computes the trace state at an arbitrary position without moving the user's cursor or notifying observers. Used by monitor mode to sonify and announce a newly appended point while the user stays put.
The state getters read this.row/this.col internally, so the cursor
is moved temporarily and always restored in a finally block — this
method is the single owner of that pattern.
Re-entrancy hazard: this is only safe because the entire call chain is synchronous (no await points), so timers (e.g. autoplay ticks) cannot interleave before the finally-restore, and state getters never notify observers. If a getter ever becomes async or triggers notifications, callers could observe the temporary cursor.
The row of the position to compute state for
The column of the position to compute state for
The trace state at the requested position
Resets the trace to initial entry state
ProtectedgetReturns a human-readable label for this trace's chart type (e.g., 'Bar Chart', 'Scatter Plot') for display in the description modal. Falls back to the raw layer type if no mapping is registered.
ProtectedgetBuilds the axes object for the description state, including z only when the layer explicitly provides a z-axis label. Subclasses should call this instead of constructing the axes object inline so charts without a real z dimension don't surface the placeholder default.
Get available extrema targets for the current navigation context
Array of extrema targets that can be navigated to Default implementation returns empty array (no extrema support)
Base implementation for navigateToExtrema Subclasses must override to provide actual implementation
The extrema target to navigate to
ProtectedfinalizeCommon post-navigation cleanup that should be called by subclasses after they update their internal state
Returns true if this trace supports intersection navigation mode. Opt-in per trace type: override to return true (possibly conditionally, e.g. based on data shape) for trace types that expose point intersections between series. Intersection navigation is a trace-level capability — it has no meaning at the figure or subplot level, which is why it lives on AbstractTrace rather than AbstractPlot.
Move to the next point intersection (right arrow in intersection rotor mode). Default is a no-op returning false; subclasses that advertise supportsIntersectionMode must override to provide real behavior.
Move to the previous point intersection (left arrow in intersection rotor mode). Default is a no-op returning false; subclasses that advertise supportsIntersectionMode must override to provide real behavior.
Trace-specific rotor filter units appended to the rotor cycle after the built-in data/compare/grid/intersection modes. Each unit restricts navigation to points matching a predicate (e.g. only bullish candles). Default: none. Override to opt in (e.g. Candlestick exposes bullish/bearish/neutral units). The returned list is treated as read-only by the rotor service.
Moves within an active rotor filter unit along the filtered axis.
Called by RotorNavigationService when the current rotor mode is
one of this trace's getRotorFilterUnits. Filter units navigate a
single axis, so only left/right are dispatched here — the service
announces up/down as unavailable without calling the model (matching
intersection mode). Implementations should move to the nearest point
matching the unit identified by key and notify observers, returning
true; when no such point exists they should call notifyRotorBounds
and return false.
Default is a no-op that reports bounds, so a trace advertising a filter unit but forgetting to implement movement fails safe (announces "no point found") rather than moving unexpectedly.
The RotorFilterUnit.key of the active unit
The direction to search
True if the cursor moved, false otherwise
ProtectedupdateDefault implementation for updating visual point position Subclasses can override if they need custom positioning logic
Checks if this plot supports extrema navigation.
True if extrema navigation is supported
Base implementation for getting current X value Subclasses can override if they have different data structures
Moves to a specific X value in the trace.
The X value to navigate to
True if the move was successful, false otherwise
Gets the unique identifier for this trace.
The trace ID
Moves the active point to the pointer location and returns directional guidance toward the nearest data geometry in a single call.
Combining both operations avoids running findNearestPoint twice per
pointermove event — important on dense plots where the scan is the
hot path.
Screen-space x position of the pointer/finger
Screen-space y position of the pointer/finger
Guidance state relative to nearest point, or null when unavailable
Checks if the specified coordinates are within bounds of the element.
The x-coordinate
The y-coordinate
Object containing the SVG element and its position
True if the point is in bounds, false otherwise
Cleans up resources and removes all highlight elements from the DOM.
ProtectedgetReturns an empty object to avoid grouping scatter points by audio tone.
Empty object without groupIndex to maintain consistent audio feedback
ProtectedhandleInitializes scatter plot navigation at the origin in column mode.
Checks if movement in the specified direction is possible from current position.
Direction or coordinate to check
True if movement is possible, false otherwise
Returns true if this trace supports compare (lower/higher value) navigation. Override to false for trace types that don't use compare modes (e.g., scatter, which is all we currently have).
Returns the display name for the default data navigation mode. Override to provide a trace-specific name (e.g., "ROW AND COLUMN NAVIGATION" for scatter).
Checks if currently in grid cell mode (navigating points within a cell).
Enters grid cell mode to navigate points within the current cell. Groups cell points by X coordinate (like COL mode) for navigation.
true if entered successfully, false if no points in cell
Exits grid cell mode and returns to grid navigation.
Moves to the previous point within the current grid cell.
true if moved, false if at boundary
Moves to the next X-grouped point within the current grid cell.
true if moved, false if at boundary
Gets the current point index within the cell (0-indexed).
Gets the total number of X-grouped points in the current grid cell.
Gets the current X-grouped point within the grid cell.
ProtectedmapConverts SVG elements to center coordinates for proximity-based navigation.
Array of center points with coordinates and indices, or null if unavailable
Finds the nearest scatter point to the given screen coordinates.
The x-coordinate in screen space
The y-coordinate in screen space
The nearest point with its element and indices, or null if unavailable
ProtectedmoveSwitches scatter into column-navigation mode only when committing the
hovered point. Off-curve guidance probes intentionally skip the mode
change: moveToPointAndGetPointerGuidance fires on every pointermove,
and an unconditional reset would silently erase a ROW mode the user
set via keyboard while exploring nearby.
Interface for traces that support grid-based navigation. Implemented by trace types that can divide their plot area into navigable cells (e.g., ScatterTrace with grid config).