ReadonlyidReadonlyselectorReadonlyonFires whenever the keyboard scope this context is in changes.
The scope stack here is the authority on which scope is active;
KeybindingService owns the hotkeys-js scope that decides which bindings
fire. Announcing the change and applying it are two jobs, and only the
first belongs to the model — so this notifies, and Controller hands the
new scope to the service.
The plot element whose state drives the initial instruction text.
Which level of the figure the cursor is on.
The same answer state.type gives, without the state: reading it there
builds the active trace's whole audio/braille/text/highlight snapshot --
and for a figure-level cursor, recurses through the subplot to do it --
so a caller that only wants to know where it is paid for the announcement
as well. AutoplayService asks once per tick, which at the fastest rate
is a hundred times a second.
Exact rather than a shortcut: an element's state carries the same type
whether it is populated, empty or out of bounds.
The active element's level
Returns whether this figure has multiple subplots (facets/multi-panel).
Read from the figure rather than from figure.state, for the reason
given on Context.figureTitle.
Returns the figure-level title (the top-level plot title). Use isAuthoredTitle to distinguish an authored title from the model's default substitutions.
This and the five accessors below read the figure's own fields rather
than figure.state. The values are identical -- Figure.state copies
them out of the same constants -- but reading them there builds the
focused subplot's state, and through it the active trace's audio,
braille, text and highlight. DescriptionService reads five of these in
a row, which was five whole announcements assembled and discarded.
There is no empty case to fall back for: Figure.state always reports
empty: false, and the empty shape belongs to outOfBoundsState, which
Context never reads. test/model/contextFigureMetadata.test.ts pins
that, so an empty variant added later turns this red rather than silently
returning a real label where the old code returned a sentinel.
Returns the figure-level subtitle. Use isAuthoredSubtitle to distinguish an authored subtitle from the model's default substitution. See figureTitle for why this reads the figure, not its state.
Returns the figure-level caption. Use isAuthoredCaption to distinguish an authored caption from the model's default substitution. See figureTitle for why this reads the figure, not its state.
Returns the figure-wide X axis label (shared across all subplots). Use isAuthoredAxisLabel to distinguish an authored figure-level label from the absent default. See figureTitle for why this reads the figure, not its state.
Returns the figure-wide Y axis label (shared across all subplots). Use isAuthoredAxisLabel to distinguish an authored figure-level label from the absent default. See figureTitle for why this reads the figure, not its state.
Replaces the underlying figure with a rebuilt model (live data update), preserving the user's navigation position when the figure shape allows.
The old figure is disposed before createFigure runs so that stale
highlight clones are removed from the DOM before the new model queries
its SVG selectors.
Positions are restored silently (no observer notifications) so a data update never announces or sonifies by itself; monitor mode handles user-facing feedback separately.
Factory that builds the replacement figure
Optional position adjustments (e.g. sliding-window shift)
The newly created figure
Enable or disable rotor navigation for the current context.
true to enable rotor mode, false to disable
Return whether rotor navigation is currently enabled.
boolean
Returns true when the given title came from the MAIDR JSON, i.e. it is
not a placeholder default substituted by the Figure or Trace models
when the JSON omits title. Encapsulates the model's internal default
constants so callers (commands, services) can avoid importing them.
Delegates to the shared isAuthoredTitle predicate in plot.ts
(imported here as isAuthoredTitleValue), the single source of truth for
the placeholder-rejection rule.
The title string to check.
Returns true when the given subtitle came from the MAIDR JSON, i.e. it
is not the placeholder default the Figure model substitutes when the
JSON omits subtitle. Same empty-string and collision caveats apply
as isAuthoredTitle.
Currently DEFAULT_SUBTITLE and DEFAULT_CAPTION are both 'unavailable', so this method is functionally identical to isAuthoredCaption; they are kept separate so the two can diverge independently without touching callers.
The subtitle string to check.
Returns true when the given caption came from the MAIDR JSON, i.e. it
is not the placeholder default the Figure model substitutes when the
JSON omits caption. Same empty-string and collision caveats apply
as isAuthoredTitle; same independence rationale applies as
isAuthoredSubtitle.
The caption string to check.
Returns at-a-glance summaries for every subplot in the figure, in visual (top-left first) order. Empty for single-panel figures.
Returns true when the given axis label came from the MAIDR JSON's
figure-level axes, i.e. it is not the empty absent-default. Unlike layer
axes (which default to 'X'/'Y'), a figure-wide label is only meaningful
when explicitly authored, so an empty value means "fall back to the focused
subplot".
The figure-level axis label to check.
Re-announces the active element where it already stands.
Every other entry point here moves first and notifies as a consequence, so a caller that wants the current position sounded without a move has nothing to call. Autoplay is that caller: it starts by scheduling a move, so the point the user started from was never part of the pass and a left-to-right playthrough was missing its first point (#615).
Delegating rather than reaching for active at the call site keeps the
plot stack private, which is the same reason moveOnce and isMovable
are here.
Moves to the nearest point at (x, y) and returns directional guidance toward the nearest data geometry in a single call.
Screen-space x position
Screen-space y position
Guidance state, or null when unavailable for current scope
Replaces the active trace at the top of the plot context with another trace, leaving the rest of the stack (and its depth) untouched. Used by the candlestick delta feature to activate its virtual layer and to restore the real layer on exit.
The trace to make active
The trace that was active before the swap, or null when the current context is not at trace level (nothing is swapped then)
Returns the traces of the subplot the user is currently in, flattened in layer order. Used to discover sibling layers (e.g., reference lines for the candlestick delta feature).
At-a-glance summaries of the layers of the subplot the reader is in, for the chart description's layer tabs. Empty at figure level and for a single-layer subplot -- in both cases there is no layer choice to offer.
Makes the layer at index the active one without announcing the move.
The description dialog's layer tabs are the caller: the reader picks a layer while the modal is open, so the switch has to land in the model -- that is what makes Escape return them to that layer -- while staying silent, because the trace's own announcement would talk over the dialog. notifyActiveTrace is how the caller speaks it later.
A no-op at figure level and when the index is already active or out of range; the boundary tone stepTrace plays has no place here, where the reader chose a specific layer from a list rather than stepped off the end of one.
Zero-based layer index within the active subplot
True when the active layer changed
Announces the active layer as a layer switch -- "Layer 2 of 3: ..." -- through the trace's usual observer chain, so text, braille, audio and highlight all catch up at once.
Paired with selectTrace, which deliberately moves in silence: the description dialog switches the layer as the reader browses the tabs and calls this once, on close, so the reader is told which layer they have landed back on rather than hearing every tab they passed through.
Descends from the multi-panel lobby into the focused subplot, pushing the Subplot and its active Trace together so the stack never exposes a bare Subplot.
True when the subplot was entered; false when the active element is not the figure, or the focused subplot has no layers to enter — the caller then stays in the lobby and announces that the panel is empty.
Enters grid cell mode to navigate points within the current cell. Only works when the active trace supports grid navigation and is in grid mode.
true if successfully entered cell mode, 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.
Moves to the next point within the current grid cell.
Interface for objects that can be disposed to clean up resources or remove event listeners.