Creates a new directed graph trace.
The MAIDR layer carrying the nodes
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 ReadonlysupportsNo go-to-extrema dialog: the graph inputs and outputs are named in the
description and every item is one arrow from its siblings, and its nodes
carry no values to rank, which DirectedGraphTrace.noExtremaReason
says. Leaving it true without targets is the keyboard trap
extremaContract guards against.
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).
ProtectedcategoriesWhether this trace's grid lists its categories as columns while the chart draws them one above another: a horizontal bar, dot, lollipop, funnel, dumbbell or forest chart. Its arrow keys are then turned to follow the drawing (keyDirection), as a horizontal box plot's already were: Up and Down move between the categories, and Left and Right along one, between the series, ends or sections drawn across it.
False here; true on the traces of that shape drawn on their side
ProtectedxThe 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
ProtectedautoplayProtectedhasHow 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.
How far the layer's measured values spread: its largest less its
smallest, or 0 with fewer than two. The scale at which [, ] and the
Go To dialog read two values as one extreme
(MathUtil.nearlyEqualInRange).
Read from values, the numbers the layer is sounded and brailled from; a trace whose extrema rank something else says so by overriding it.
The span, never negative
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.
The state, with where the item sits among the items of its scope and at which depth of nesting, the place a tree gives its node.
The position key read the pan, whose column is the item's place in its scope and whose row its depth, and announced them as a column and a row: the first step of Mermaid's flowchart example was "column 1 of 4, row 1 of 2", a column and a row the drawing does not have. Placed as a tree's node is, it is "Level 1 of 2, Position is 1 of 4", and an item inside a scope names the scope.
The trace state
ProtectedvaluesProtectedaudioProtectedoutThe boundary tone sounds where the item the reader stopped at sounds, at the edge of its scope, rather than at its index across the whole depth.
The empty trace state, panned to the cursor's item
ProtectedbrailleProtectedtextProtecteddimensionProtectedhighlightOn a scope, every declared node inside it.
The chart was given no element for a scope, which is derived from its nodes' paths rather than declared, so its own cell is a hidden placeholder. Outlining that took the previous outline away and drew nothing in its place -- on as many as one stop in three of a diagram of subgraphs, and on the stop every nested scope is entered through -- while a canvas chart lit the scope's members. Its members are what the scope is drawn round, so they are outlined instead.
The highlight at the cursor
The declared nodes the cursor covers, as indices into layer.data.
The nodes coveredMembers names
Runs 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.
The rotor's LOWER and HIGHER VALUE search. The base is a no-op that reports the boundary: a trace that can compare overrides it, and supportsCompareMode offers the two modes exactly where it does.
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").
Movability by the same rule, so check-then-move (autoplay's idiom) agrees with the move it checks.
A direction, or a cell
Whether the move is possible
The rotor's lower and higher value search, Up: on a chart drawn on its side, along the categories toward the one drawn above, as Up moves. Elsewhere the rotor reads Up as Right.
Optionalmode: "lower" | "higher"Whether a lower or a higher value is sought
Whether the cursor moved
The rotor's search, Down: toward the category drawn below. See moveUpRotor.
Optionalmode: "lower" | "higher"Whether a lower or a higher value is sought
Whether the cursor moved
The rotor, Left: on a chart drawn on its side, the plain move along the category, as a horizontal box plot's rotor moves along its box. The search runs along the categories, which Up and Down walk there.
Optionalmode: "lower" | "higher"Whether a lower or a higher value is sought
Whether the cursor moved. False at the end of the category -- on a chart of one series, always -- so the rotor says there is nothing further that way; it reported true, and the rotor said nothing.
The rotor, Right. See moveLeftRotor.
Optionalmode: "lower" | "higher"Whether a lower or a higher value is sought
Whether the cursor moved, false at the end of the category
ProtectedkeyThe direction to move the grid for a key, which is the key's own except on a trace whose categories run down the page. There the grid's columns are drawn one above another and its rows across them, so Up and Down step the columns, toward the category drawn above or below, and Right and Left step the rows. On a horizontal bar chart Right and Left moved down and up the page between the bars, and Up and Down said there was no more data: the other way round from a horizontal box plot or violin.
The key's direction
The direction to move the grid in
ProtectedfirstWhether the first category is drawn above the last.
Producers list a horizontal chart's categories both ways: matplotlib, ggplot2, base R and Plotly draw the first at the bottom, and Highcharts, ApexCharts, Vega-Lite, seaborn and most hand-drawn charts at the top. So it is measured, as a Gantt chart measures its lanes, from the marks the highlight holds: in the first row that has two, the first category's mark is above the last one's, or below it. Measured on every vertical key, an autoplay step included, rather than once. That is two boxes a key, however many categories the chart has: the two marks are found from the ends of the row, and the read forces at most the layout the highlight's move would cause before the next paint. An answer kept from the first key was kept from a chart not yet laid out, or one since re-rendered the other way round, and a cache would have to be cleared on every redraw and resize to avoid that.
Where nothing can be measured now, the last measurement holds, so a chart hidden for a moment does not turn the keys round under the reader. Where nothing has ever been measured -- a chart drawn to a canvas, one with no highlight, one not laid out yet, or one category -- the layer's MaidrLayer.firstCategory says where the first is drawn. Without it, the first is taken to be at the bottom, as row 0 of a grid is, and Up moves to the next.
True when the first category is drawn at the top
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.
Taken from FormatUtil.axisFormat, as the announcements and the table take theirs, so a histogram's bin edges read with the same decimals in all three.
The axis whose format to read
The format, or null when the layer declared none
Cleans up trace resources including values and highlighted SVG elements.
Only removes elements MAIDR created (hidden clones, synthetic markers); traces that highlight the chart's original live elements in place (e.g. heatmap cells, line dots) merely drop their references so the visible chart geometry survives focusout and live-data rebuilds.
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
ProtectedgetComputes 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.
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.
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
Whether the cursor stands on an extremum target, for a trace whose cursor its row and column do not hold: a scatter plot in point navigation keeps a point's index instead. Null leaves the answer to the row and column, which is how every other trace's cursor is read.
A target from getExtremaTargets
True or false where the trace keeps its cursor elsewhere, and otherwise null
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
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
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
How this layer's x axis writes an x: through the format the layer declares for it, or null where it declares none.
A layer switch carries a number this way to a layer that holds the same
place as text (see Subplot.carriedXValue).
An x of this layer's
Its reading, or null
The x of this layer's that its axis writes as reading: the first in
the order the points are held, or null where the layer declares no x
format or none of its x reads that way.
A layer switch carries text this way to a layer that holds the same
place as a number its axis formats (see Subplot.carriedXValue).
The text another layer holds the place as
The x, or null
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
ProtectedmoveMoves the trace to the nearest point when the pointer is within its bounds and the trace is not already focused on that point.
onCurve is intentionally non-optional: the caller has already paid
the cost of isPointInBounds to assemble guidance state, and
forcing subclasses to accept the value makes the contract explicit so a
future override cannot silently recompute (or worse, ignore) it.
Subclasses override this to customise hover-driven navigation:
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
Why [, ] and G have nothing to go to here.
That the nodes carry no values
The item's name, which is what another layer of the same chart can find it by. The default read a magnitude or nothing, so a layer switch landed a reader on whatever came first rather than on the same item.
The name of the item under the cursor, or null off the chart
Moves to the item carrying a name, keeping the cursor where it is when it already does (see findNamedCell).
The name another layer was on
True when a item carries it and the cursor moved there
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
Offers the edges on either side of the current item.
The arrows walk the scope in order and never follow an edge, so this is where the edges are followed: Outputs downstream, Inputs upstream. Withheld on a graph with no edges, where both could only answer "none".
The edge units alongside whatever else is offered
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.
True if the cursor moved, false otherwise
Ends any edge walk before a jump.
A jump from the object list can land on the very item a walk last stepped to, and the walk would then carry on through the edges of the item it started from rather than of the one the reader chose. The walk's own steps move the cursor directly, so they are not affected.
The depth to move to
The item's position at that depth
True when the cursor moved
Ends any edge walk before an arrow move.
The walk knew the reader had moved off only by the cursor no longer being where its last step left it, which an arrow move that comes back cannot show: on In stock?, reached by an Outputs step from Order received, Left then Right put the cursor back where the step had, and the next Outputs step carried on through Order received's one output and said In stock? had none. A reader who moves with the arrows has left the walk, so the next step starts one from where they are.
The key's direction
True when the cursor moved
Ends any edge walk before a move to the end of a scope, for the reason DirectedGraphTrace.moveOnce gives.
The key's direction
True when the cursor moved
Every item, for the o list: the declared nodes and the scopes holding
them, in outline order -- each scope followed by what it holds, siblings
in the order the arrows walk them, which is the tree a graph viewer shows.
It opens on that order, because on a model graph the order is the
reading: input to output, block by block. Each item is listed bare, as a
move names it, with its scope, its connections and its role beside it --
what the announcement says -- and a scope with how much it holds. A list
that opened every scope at once has to say where conv is, since several
blocks have one.
Betweenness is offered once the data branches or merges: on a chain it would only say which nodes sit nearer the middle, which the graph order already says. The producer's numeric attributes -- a parameter count -- sort the list, and its other attributes -- a layer type -- narrow it.
The list, or null on a graph with nothing in it
Protectedfind
Trace implementation for directed graphs nested in scopes -- the architecture of a neural network, or any other computation graph.
A NetworkTrace reads an undirected graph by degree. A model graph is read for other questions: what feeds this layer and what it feeds, where the data branches and where it merges (a skip connection, a multi-input model), and -- because a real graph runs to hundreds of ops -- which block a layer belongs to. A two-hundred-op graph is legible only as ten blocks.
The scopes navigate as a tree, on the keys a tree already uses. A scope is an item of its own, collapsed: down opens it onto its first member, up closes it again by returning to the scope. That is the TreemapTrace interaction, and a reader enters at the top level with every scope closed, which is the ten-block view.
Left and right walk the items of one scope in topological order, input to output. A sibling is never stranded, whatever the edges do, which is the guarantee NetworkTrace keeps for the same reason; and on the chain most of a model graph is, the next item in that order is the one the data flows to. Where it is not -- the second arm of a branch -- every move names what the node is fed from, so a step between parallel arms is heard as one.
Following an edge is the rotor, as it is on a sankey: the Outputs unit steps along the edges leaving the node, downstream, and the Inputs unit back along the edges arriving at it, upstream. An edge into a closed scope lands on the scope.
What a move announces is the node, its connections as
2 inputs, 1 output, whether it is a graph input or output or a branch or merge point, the names on either side, the producer's attributes, and its place in the scope's order.