Creates a new Candlestick instance from a MAIDR layer
The MAIDR layer containing candlestick 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 ReadonlynameWhat this layer is, when the producer named it. See MaidrLayer.name.
Protected ReadonlylayerProtected ReadonlysupportsAbstract property that subclasses must implement to indicate extrema support
Protected ReadonlymovableProtected ReadonlyhighlighthighlightValues[row][col], or null for the whole trace when it
highlights nothing.
A single cell may also be null, meaning the chart drew no element
there. That is a narrower claim than the trace-wide null: the rest of
the grid still highlights, and only this position falls back to the
out-of-bounds state. A Google Charts calendar is the case it exists for
-- its first and last columns are ragged, so a handful of grid positions
have no rect at all while every other day does (#1174).
ProtectedhighlightProtectedxThe x axis's name, falling back to a generic one the layer authored none.
A getter rather than a field set in the constructor: the fallback is a translated word, and a trace outlives a language change — a name resolved once at construction would keep the language the chart was built in.
ProtectedyThe y axis's name, or a generic one. See xAxis.
ProtectedzThe z axis's name, or a generic one. See xAxis.
ProtectedisWhether the cursor has no point to report.
Read from dimension rather than from any one trace's data,
because that is the one shape every trace already answers in. It is also
evaluated at the cursor — LineTrace returns the current series'
length as cols — so this covers a ragged layer, where one series has
points and another has none, and not only a layer that is empty
throughout.
True when there is nothing at (row, col) to describe
Gets the current state of the trace including audio, braille, text, and highlight information.
The current TraceState
ProtectedoutThe state pushed to observers when navigation leaves the data.
Declared as TraceEmptyState rather than the whole TraceState union
because that is what every implementation actually returns — the accessor
exists so AbstractPlot.notifyOutOfBounds has an empty state to
push. Narrowing it here is what lets the braille and highlight callers
hand the value straight on: those states accept the empty trace shape but
not a populated one, so a wider declaration would force each of them to
cast, and a cast is exactly what stops the compiler from noticing if an
override ever starts returning a populated state.
The empty trace state, positioned for out-of-bounds audio panning.
ProtectedhighlightProtectedautoplayProtectedhasHow this layer names itself in the description dialog's layer tabs.
The producer's name when there is one, and the chart-type label
otherwise — the same fallback order TextService.layerIdentity uses for
the spoken layer-switch announcement, so a tab and the announcement single
out the same layer by the same name. The two differ only in register: the
announcement says "point plot" where the dialog says "Scatter Plot",
because that written form is what the dialog's own Chart Type line has
always shown and a tab sitting above it should agree with it.
A plain-language introduction to this layer's chart type, for the description dialog. See chartGuide.
A layer that names its own chart type never gets the trace type's: that guide explains the type the chart is read as, which is not what the chart is, and a gantt's tasks, dates and project plans said of a packet's bit fields are false. It gets the guide to the diagram it names (MaidrLayer.diagramType), or the one it gives to its own chart (MaidrLayer.typeGuide), or none.
Which way this chart is drawn, or undefined for a type that has no orientation to speak of.
Entering the chart already announces it -- "This is a maidr plot of type: horizontal bar" -- but the description dialog said only "Chart Type: Bar Chart", and for the box, violin and boxen families the orientation also silently reverses the order of the rows in the table underneath, because their constructors reverse the groups when the chart is horizontal. A reader comparing the table with what they walked had no way to know why the two disagreed.
Exposed here, and read once by the description service, rather than pushed
as a stat by each of the thirty-odd traces that has one. Named apart from
the bar and distribution families' own orientation fields, which hold the
declared* value and default it to vertical for every type -- including the
ones that have no orientation at all.
horizontal or vertical, or undefined when the type has no
orientation to report.
The 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.
Gets the description state for the candlestick trace.
The description state containing chart metadata and data table
ProtectedvaluesGets the 2D array of candlestick values
Array of candlestick values for all segments
ProtectedaudioProtectedbrailleProtectedtextProtecteddimensionRuns action with this element's observers muted.
A cursor move normally is the announcement -- moveToIndex notifies, and
everything downstream of it speaks, brailles and highlights. That is wrong
for a move the reader did not make and is not waiting to hear: the
description dialog's layer tabs relocate the reader in the chart while the
modal is open, and the trace's announcement would land in the same live
region the dialog is using, so one of the two is dropped. The caller
announces afterwards, once, when the reader is back on the chart.
Nesting is safe and the flag is restored on every path, including a throw, because a flag left raised would silence the chart for good.
The moves to make in silence
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.
Utility function to compare point values for rotor functionality
boolean value
ProtectedcompareRotor compare search along one row of numeric values.
Steps from the current column in the given direction and moves to the first value that satisfies the comparison; reports the rotor boundary when nothing further qualifies. For the traces whose values are a plain numeric grid indexed [row][col]; a trace with a richer layout (the bar's orientation-normalised rows, the candlestick's segments) keeps its own.
The values of the row being searched
Which way to search
Whether a lower or a higher value is sought
True when a matching value was found and moved to
Whether the rotor offers its lower and higher value modes on this trace.
Exactly when the trace overrides moveToNextCompareValue. The base search is a no-op that reports a boundary, so offering the modes without one told a reader "No lower value found" with a lower value beside them, or said nothing at all; tying the offer to the search keeps the two from drifting apart again. A subclass can still override this to withhold the modes (scatter, whose arrows walk points rather than values), and a trace that compares only through the rotor's arrow methods must override it to offer them.
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).
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").
ProtectedauthoredThe format the layer's author declared for an axis, or null when they declared none.
For a number the description states rather than tabulates. The table reads each column through the axis's declared format, and so does every announcement, but a stat printed the raw number: a margin drawn as a percentage was "Min value: 0.12" over a table and a cursor saying 12%. Null rather than the default format when nothing was declared, so a chart nobody formatted reads as it did, which is the rule the table follows.
The axis whose format to read
The format, or null when the layer declared none
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
ProtectedoriginalThe chart's own element a marker this trace drew stands for, where the trace marks a point with a dot of its own rather than with a copy of the mark. None by default.
A marker in this trace's highlight values
The element the marker stands for, or null
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
ProtectedgetResets 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.
ProtectedspokenWhat the entry instruction calls this chart: the name the layer gives its own chart type (MaidrLayer.diagramType or MaidrLayer.typeLabel), or the trace's word.
A trace that names itself -- a line "single line" or "multiline", a radar "polar area" -- passes its word through here, so a layer that names its chart type is called by that name whichever trace reads it, and the instruction a reader hears once in the chart says what the one built from the layer before it said.
The trace's word for its type
The word the instruction uses
ProtectedgetBuilds the axes object for the description state, carrying only the axes the layer actually authored a label for. Subclasses should call this instead of constructing the axes object inline so charts without a real z dimension don't surface the placeholder default.
Every axis is gated, not just z. xAxis and yAxis fall back to the
literal 'X' and 'Y' when the JSON authors no label -- legal, and
common in adapter-generated specs -- and the dialog rendered that as
"X: X", a line that says nothing twice. The figure-level branch of the
description already showed only authored labels
(DescriptionService.getFigureAxes), so gating here is what makes
the two levels of the same dialog follow one rule.
Blankness is tested with trim(), the same rule named applies
when it decides whether to substitute the fallback in the first place. A
whitespace-only z label is truthy but blank, so the untrimmed guard used
to pass it through and then print the 'Level' placeholder the guard
existed to keep out.
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.
Returns true if this trace supports point-by-point navigation mode. Opt-in per trace type: override to return true for traces that expose individual data points navigable in reading order (left/right) and column-major order (up/down). Currently only ScatterTrace.
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.
Notifies the trace that the rotor is entering or leaving INTERSECTION_MODE. Default is a no-op; line-style traces don't need to track mode state because their state output is unchanged by the rotor mode. Traces whose audio/text output differs in intersection mode (e.g. ScatterTrace, which normally plays the whole x-column as a chord and must instead focus a single point) override this to flip an internal flag.
True when entering intersection mode, false when leaving.
Notifies the trace which of its getRotorFilterUnits the rotor is on, or null when it is on none of them. Default is a no-op: a unit usually changes only where Left and Right go, which moveToRotorFilter answers. A trace whose unit also changes what Control with them should reach -- a tree's Level, where Left and Right walk the whole level -- overrides this, because the jump is not routed through the rotor.
The RotorFilterUnit.key of the active unit, or null
Every object the o list offers on this chart, or null where there is
none to offer.
Null for every chart walked along x and y axes: the arrows already reach each point in order there, and a list of them would repeat the axis. A chart whose objects have no such order -- the nodes of a network, the tiles of a treemap -- overrides this and builds the list from its own structure, with the sorts and filters that make sense for it.
List only, as the rotor units are, with no flag beside it: a flag that said yes over an empty list would open a dialog with nothing to choose. Labels are built on each call, because the trace outlives a change of language; anything expensive to compute is kept by the trace that computes it.
The list, or null
Moves to the object the list knows by this key, announcing it through the usual observer chain.
Looks the key up in a list built now rather than trusting a cell the dialog was handed when it opened, so a chart whose data changed under the dialog moves the reader to the object they chose or nowhere at all.
The key the object list gave the object
True when the cursor moved, false when no object has the key or its cell cannot be reached
Checks if this plot supports extrema navigation.
True if extrema navigation is supported
Whether a mark of this trace sits at exactly this X, as moveToXValue finds one before it falls back to the nearest.
A layer switch asks this to choose between the two X values a position
can offer (see Trace.getAlternateXValue). Reads the x of each point;
a trace that keeps its X some other way answers false unless it says
otherwise, and the switch then carries what it always carried.
The X a layer switch would carry
True when some point's x is exactly xValue
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
ProtectedupdateUpdates visual position for point highlighting and segment position
The segment the cursor stands on, which Context carries across a live
data update so restoreCursor can put the reader back on it.
The segment, or null when there is none
Takes the cursor from row/col after a live data update restored them
onto this rebuilt trace, which starts at the first candle's close.
col is the candle. The segment is the one the reader was on (key)
when that candle still has it, even if new values moved it to another
rank -- a candle that turns from bearish to bullish swaps its open and
close. Only without one does row, the segment's value-sorted position
(see updateVisualSegmentPosition), decide.
Optionalkey: string | nullThe segment captured by cursorKey before the update
ProtectedhandleHandles initial entry into the candlestick chart, setting default position
Moves navigation position one step in the specified direction
Direction to move (UPWARD, DOWNWARD, FORWARD, BACKWARD)
Computes the state at an arbitrary position without moving the cursor.
Candlestick state getters read currentPointIndex/currentSegmentType
rather than row/col, so those are mapped from the requested position
and restored alongside the 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
Checks if movement to the target position or direction is possible
Target position array or movement direction
True if movement is possible, false otherwise
Cleans up resources and disposes of the candlestick instance
ProtectedmapMaps candlestick selectors to 2D array of SVG elements for highlighting
CSS selectors or structured candlestick selectors
2D array of SVG elements or null if no selectors provided
Gets the current candlestick trend for audio palette selection
The trend of the current candlestick point
Gets the candle data points. Used by the candlestick delta feature to derive a virtual comparison layer against a reference line.
The candle points in x order
Gets the current X value from the candlestick trace
The current X value or null if not available
Moves the candlestick to the position that matches the given X value
The X value to move to
True if the position was found and set, false otherwise
Gets extrema targets for the current candlestick trace with labels and descriptions
Array of extrema targets for navigation
Navigates to a specific extrema target
The extrema target to navigate to
Moves to the next value in the specified direction that matches the comparison type
Direction to search (left or right)
Comparison type (lower or higher)
True if a matching value was found and moved to
Moves upward between segments within a candle in rotor mode
True if the move was successful
Moves downward between segments within a candle in rotor mode
True if the move was successful
Exposes the bullish/bearish/neutral rotor filter units. These are appended after the built-in lower/higher value compare units, so cycling the rotor offers: all data point (default), lower value, higher value, and one unit per trend that actually occurs in the data. The default "all data point" unit is provided by the built-in data mode.
A trend with no candles is omitted so the rotor cycle carries no dead-end modes (where every move would just report "no point found"), mirroring how GRID_MODE / INTERSECTION_MODE are gated on capability. The list is precomputed in the constructor (candles are immutable), so this returns the cached reference — callers must treat it as read-only.
The present trend-filter rotor units in cycle order
Jumps to the previous/next candle whose trend matches the active filter unit, preserving the current segment. Trend filtering runs along the candle axis; the rotor service handles up/down (announcing them as unavailable) and only dispatches left/right here.
The trend to navigate ('Bull', 'Bear', or 'Neutral')
The direction to search
True if a matching candle was found and moved to
ProtectedmapMaps SVG elements to their center coordinates for click navigation
Array of center coordinates with row/col indices or null
Finds the nearest candlestick point to the given coordinates
X coordinate
Y coordinate
Nearest point information or null
ProtectedmoveMoves the trace to the nearest highlight point for a pointer/hover event.
The highlight grid is [sortedSegmentPosition][pointIndex] in BOTH
orientations (see mapToSvgElements), so nearest.col is always the candle
index and nearest.row is the value-sorted segment position. Those sorted
coordinates are translated straight into the candle/segment model state
here, rather than delegating to moveToIndex, which interprets rows in
static CANDLESTICK_SECTIONS order — an interpretation the braille path
relies on and must keep.
Screen-space x position of the pointer
Screen-space y position of the pointer
The nearest highlight point in sorted grid coordinates
Whether the pointer is within the point's bounds
Interface representing a trace with navigation and observation capabilities