Interface MaidrLayer

What this layer is, when a subplot's layers are the same kind of thing.

Announced on a layer switch in place of the trace type. Without it, two layers of one type are indistinguishable — a hue-split error bar chart announces "Layer 1 of 2: error_bar plot" and then "Layer 2 of 2: error_bar plot", so a reader hears two different sets of numbers and is never told that the first is Male and the second Female, which is the whole content of the split and what a legend gives a sighted reader for free.

Distinct from title, which names the chart rather than the layer: producers put the figure's title there for every layer of a figure, so it cannot say which layer this is.

What the chart is called, when it is read as a trace type it is not: a deal pipeline read as a tree, its stages columns and its deals cards.

Said in place of the trace type's name wherever the chart's type is named -- its accessible name, the instruction on entering it, the description's Chart Type and layer tab, a layer switch -- and the description leaves out its "About this chart type" guide, which explains the trace type rather than this chart, unless the layer gives a guide to its own chart in typeGuide. Written as given, in every language, as title is: a diagram MAIDR knows is better named by diagramType, which MAIDR says in the reader's language.

A plain-language introduction to the chart typeLabel names, shown in the description's "About this chart type" section in place of the guide to the trace type, which a layer that names its chart leaves out.

Read only beside a typeLabel: that section is headed with the chart type's name, and without one it names the trace type, which this guide does not explain. All three parts must be given, since the section reads all three; a guide missing one, or blank in one, is not shown. Written as given, in every language, as typeLabel is.

What the chart is, when it is a diagram MAIDR knows but reads as a layer type it is not: a Mermaid flowchart read as a directed_graph, a kanban board as a tree, a packet diagram as a gantt.

MAIDR names the diagram wherever typeLabel would name it, and explains it in the description's "About this chart type" guide, both in the reader's language, as it does a layer type. Where MAIDR knows the diagram, this wins over typeLabel and typeGuide; a producer may give those as well, for a MAIDR that does not, and they are read as before. One this MAIDR does not know is said in the console.

Which element of the chart each point of the layer is drawn as.

What each shape means depends on the layer type, and is written down per type in the "Selectors" section of docs/SCHEMA.md: a string is resolved with querySelectorAll; a list is one element per point for a bar, one per series for the line family, and resolved entry by entry for most others; a grid names one element per cell of a segmented layer or a heat map. A layer whose selectors resolve to nothing is still read aloud, and MAIDR says so in the console.

A grid cell may be null, which says the chart drew no element for that cell — a category a series has no bar at, or a position a heat grid is not a rectangle at. That is different from a selector that fails to resolve, which is a mistake and declines the whole grid: without a way to tell the two apart, a producer whose layer has a gap has to choose between losing the highlight everywhere and inferring the gaps from the values, and a value of zero is not evidence that a bar was never drawn (#1002).

It is also not the same as a null in HeatmapData.points, which says the chart drew no value. A calendar has both, at different cells: a day inside the year with no row is drawn as a white square, so it has an element and no value, while the slots outside the year have neither (#1174).

Which way the layer is drawn. Defaults to Orientation.VERTICAL.

For one family of traces this key decides which field of a point holds the magnitude, so getting it wrong is not a cosmetic error — the trace reads a category name where it expects a number and sounds with no magnitude at all. For every other trace it changes only which axis label a reading is announced against, and the payload is written the same way whichever value is set.

What the two words name. Orientation is the direction the magnitude runs, not which axis happens to be called x. That is the convention the whole field uses: a horizontal bar chart is one whose bars run left to right, with the categories down the y axis — and it is how the drawing libraries name the same switch. Chart.js: indexAxis: 'y' gives "horizontal bars", the y axis holding the categories and the x axis the values. Highcharts: chart.inverted makes "the x axis vertical and y axis horizontal". Matplotlib 3.10 replaced boxplot(vert=False) with orientation='horizontal', which "plots the boxes horizontally". Plotly states it outright: with 'h', "the value of each bar spans along the horizontal".

A producer therefore reads its chart, not its API's vocabulary. Where a library names the other direction — ECharts' and amCharts' funnel orient/orientation name the way the stages progress, so their default funnels encode the value as a band's width and are horz here — the adapter translates, and says so where it does.

The rule is: the bar family swaps x and y; nothing else does.

The bar family is defined by what a type is built on rather than by what it is called, because the exchange is inherited from AbstractBarPlot's constructor: bar, histogram, stacked, dodged, normalized and the traces built on those (diverging, mosaic) — and also dot and lollipop, which the factory constructs as a BarTrace outright, and funnel, whose trace extends BarTrace and never undoes the exchange. Reading one model file at a time misses those last three, so test/type/orientationContract.test.ts runs the list rather than restating it.

Note that this is a different question from the one resolveOrientation() in src/util/orientation.ts answers. Its IS_ORIENTED record says whether a type has an orientation worth announcing ("vertical bar plot"); a type can be oriented in that sense and still not want its payload swapped, which is the trap this table exists to close. Both r-maidr #184 and #186 were emitted against the wrong half of it.

Where a pie's first slice begins, in degrees clockwise from 12 o'clock. Defaults to 0.

MAIDR lays the slices of a pie out round a dial from this point — the audio pan follows each slice round the circle and p names the slice's clock position — so a producer whose pie does not start at the top says where it does. matplotlib's default startangle=0 puts the first edge at 3 o'clock, which is 90 here; its startangle=90 is 0. Chart.js's rotation is already clockwise from the top and carries over unchanged. Plotly's rotation is too, but a counterclockwise plotly pie starts rotation plus its first wedge's sweep round: plotly ends the first wedge at rotation and draws it clockwise of there, then lays the rest out counterclockwise from rotation.

Read by the pie trace and ignored by every other type.

The way round the dial a pie's slices follow one another from MaidrLayer.startAngle. Defaults to PieDirection.CLOCKWISE.

MAIDR steps Right through a pie clockwise: the next slice under the Right arrow is the next one round the dial the way a clock hand goes, whatever order the producer wrote them in. A producer whose library laid the slices out the other way — matplotlib, base R's pie() and plotly all draw counterclockwise by default — says so here, and the trace walks data in reverse: the slice drawn last is the first one clockwise from the start, so Right still moves clockwise and the outline, the pan and the clock position all describe the wedge under the cursor. data and selectors stay in drawn order either way; only the walk changes.

Read by the pie trace and ignored by every other type. Omit it unless the drawn direction is known: a layer that declares 'counterclockwise' and is not drawn that way walks the pie backwards.

Optional DOM mapping hints. When provided, individual traces can opt-in to use these hints to map DOM elements to the internal row-major data grid without changing default behavior when omitted.

Axis configuration. Every axis (x, y, z) is specified as an AxisConfig object with an optional label, optional grid navigation properties (min, max, tickStep), and optional per-axis format.

Display configuration for a forest plot layer.

Where a sankey, alluvial or chord layer's nodes were drawn.

Threshold configuration for a volcano or Manhattan plot layer.

Optional display configuration for violin plot layers (VIOLIN_KDE and VIOLIN_BOX). Controls which summary statistics are shown in the violin box overlay.

Where a TraceType.STEP layer jumps between samples, and how a stepped TraceType.AREA band moves between them. Read by StepTrace and by AreaTrace -- line.shape and a fill are independent, so a band can be a staircase -- and ignored by every other trace type. Omit it when the producing library does not report one, rather than guessing: the announcement names the convention, and naming the wrong one is worse than staying silent.

Where a TraceType.BUMP layer draws first place: 'top', as a bump chart is usually drawn, with its rank axis running down the page, or 'bottom', on a chart whose rank axis runs up it.

Up and Down follow the drawing. With first place at the top, Up moves to the competitor one place better, drawn above, and Control + Up to first place; with first place at the bottom, Up moves one place worse, which is the place drawn above there. The pitch does not change with it: first place is the highest note either way, and ] goes to a competitor's best place.

Optional. Left out, MAIDR reads where first place is drawn from the marks the highlight resolves, and where it has nothing to measure -- a chart drawn to a canvas, or no highlight -- Up moves to the next larger rank number, as on a line. A layer left without it whose drawing turns Up and Down round from that rule logs a console warning, once, asking for it. Say it where the drawing cannot be measured: the Chart.js and amCharts adapters do, Highcharts says it from its reversed axis, and Frappe, which cannot reverse an axis, says 'bottom'. Read by BumpTrace and ignored by every other type.

The quantiles, from 0 to 1, at which a TraceType.BOX layer's lower and upper whiskers end: [0.1, 0.9] for whiskers drawn to the 10th and 90th percentiles. Read by BoxTrace and ignored by every other type.

A box's min and max are announced as "Minimum" and "Maximum", which is what they are for a Tukey or a range whisker. A library that draws its whiskers at fixed quantiles instead -- Nivo's box plot defaults to the 10th and 90th -- would have a reader told the 90th percentile was the largest value. With this set, the whisker ends are named as the percentiles they are, in the announcement, the section names and the summary.

Omit it when the whiskers end at the data's extremes or at 1.5 × IQR; a value of [0, 1], or one that is not two quantiles in increasing order, is treated as absent. Each end is read on its own: a lower end at 0 is still the minimum, and an upper end at 1 the maximum, so [0.05, 1] names only the lower end as a percentile.