document select

[Fil]

for #1343

note that we don't cover the case where symbol is constant, but we try to select it with select({symbol: "min"}); this should be red:

[mbostock]

we don't cover the case where symbol is constant, but we try to select it

This is true in general; the types don’t validate that the channels referenced in the outputs actually exist. For example, you could declare title: "mean" as an output, but you wouldn’t get an error if you don’t declare the title channel as an input.

[mbostock]

The “usually defined by stroke, fill or z” feels unnecessarily imprecise. How would the user know when or not the “usual” definition applies? We should list these channels in order of precedence: z, fill, stroke. The README is more definite:

The data are grouped into series using the z, fill, or stroke channel in the same fashion as the area and line marks.

And similarly for the area mark:

By default, the data is assumed to represent a single series (i.e., a single value that varies over time). If the z channel is specified, data is grouped by z to form separate series. Typically z is a categorical value such as a series name. If z is not specified, it defaults to fill if a channel, or stroke if a channel.