Reference line

referenceLine is the one mark that isn't a reading. Every other mark takes rows and draws what they say; this one is a statement about the plot — where today is, where the target sits, when the way a number was calculated changed.

It has no rows, so it spans the plot whatever the marks under it reach. A Today marker on a chart of bars is the full height of the plot rather than the height of today's bar, which is what makes it read as a marker rather than as one more series.

marks={[
	bar({ data: rows, x: 'day', y: 'sent' }),
	referenceLine({ x: today, label: 'Today' }),
]}

Name x for a rule down the plot at a position along the horizontal axis, and y for one across it at a value on the vertical axis — which is where a target or a threshold goes. Marks paint in order, so a rule declared after the bars is drawn over them and one declared before is drawn under.

The caption

label writes a few words beside the rule, inside the plot. Inside rather than out in the margin, which is what makes the caption belong to the rule it names: a caption beyond the plot's edge is a second axis label, and a chart with two annotations would have two of them with nothing saying which is which.

labelPlacement moves it to the other end — the foot of a rule down the plot, the right of one across it — for when the top of the plot is where the data is.

Keep it short. The plot is the data's room, and the caption is a guest in it.

The note

note is the sentence the caption was too small to hold, read by the tooltip at the position the rule marks:

referenceLine({
	x: new Date('2021-06-24T00:00:00Z'),
	label: 'Definition changed',
	note: 'Open rates before this date are not comparable.',
})

The rule takes no focus of its own. It marks a position the chart already answers at, so a target there would be a second tooltip for one place — and a keyboard cursor that stops somewhere with no value to read. Pointing at the column the rule crosses reads that column's values, with the note under them.

The rule does not have to sit exactly on a row. On a time or number axis the note belongs to the position the rule is nearest — the column the reader sees it crossing — so a change date picked by a human reads fine against buckets it never exactly matches. On a category axis a rule is on a category or it is nowhere, so the match is that category.

A note needs a position the reader can focus. A rule down the plot has one: the column it crosses. A rule across the plot marks a height rather than a position, and the chart focuses no height — so put what it has to say in its label.

Staying in view

On a time or number axis a rule widens the axis so it is visible, the way a mark's own values do. A Today marker on a chart whose last bucket is yesterday has to be somewhere, and a marker the reader cannot see is worse than one that moved the axis a little.

withDomain: false turns that off, for a rule that would distort the plot to be shown — a target ten times the largest value would flatten every bar under it to nothing. The rule is then drawn only when the data happens to reach it.

On a category axis — which is what a chart of bars has — a rule sits on a category the chart already draws, or it draws nothing. There is no range to widen: such an axis covers the categories it was given, so a value that is not one of them has nowhere to be. withDomain does nothing there, and a Today marker for a day the chart has no column for is a marker with no column to mark.

A marker on a chart of days

Apple's closing price with the day of its 2018 high ruled and captioned, and the note read by pointing at that day:

Accessibility

A rule is drawn into the scene, and the scene is one role="img" named by the chart's ariaLabel — so nothing inside it is announced on its own. What a marker means has to be in the chart's own description: give a chart carrying one an ariaDescription that says what is marked and why, as the example above does. The caption and the note are for readers who can see the plot.