@fusion.dev/helix-headless 0.40.0 → 0.41.0

package/types/vue.d.ts

@@ -402,9 +402,13 @@ export type HelixHeadlessAppHeaderVueEvents = {
 export type HelixHeadlessAreaChartVueProps = {
   /** How a band's edge gets from one reading to the next.
 
-Absent is `straight`, for the reason the class doc gives, and absent rather
-than defaulted because a reflecting property with a default writes its
-attribute onto every host, including the ones nobody configured. */
+Three values, and the class doc argues for each: `straight` is absent and
+is the default, `smooth` is for a stack read as a shape and is the one that
+can draw a part as less than nothing, `step` is for a quantity that changes
+at a moment and is ordered the way `straight` is.
+
+Absent rather than defaulted because a reflecting property with a default
+writes its attribute onto every host, including the ones nobody configured. */
   curve?: (HelixHeadlessAreaChart["curve"]) | undefined;
   /** Which rules are drawn across the plot, if any.
 
@@ -553,28 +557,38 @@ and reach no reader through the table. */
   gridlines?: (HelixHeadlessBarChart["gridlines"]) | undefined;
   /** Which series are drawn as a line instead of as columns, by name.
 
-Space separated, matched against the column headings the table gives, so a
-chart says `lines="Margin"` rather than counting columns. Names because
-they are what the table already carries and what the legend already shows:
-an index is a fourth place the column order is written down and the first
-one to go stale when somebody moves a column.
-
-**A combination chart is one scale, and that is the honest half of it.**
-Both marks are measured against the same domain, so a line here says
-something comparable to the columns beside it. The usual reason to reach
-for a combination chart is the other thing, a count against a percentage on
-a second axis, and that is deliberately not this: two scales on one frame
-let the author put any two shapes in any relation by choosing the ranges,
-and the reader has no way to see it happening.
-
-A line among columns still measures from zero, because the columns do and
-they share the axis. */
+Separated by whitespace or commas and matched against the column headings
+the table gives, so a chart says `lines="Margin"` rather than counting
+columns. Names because they are what the table already carries and what the
+legend already shows: an index is a fourth place the column order is
+written down and the first one to go stale when somebody moves a column.
+
+**This says which mark a series takes and nothing about which scale it is
+measured on.** Named here alone, a line shares the columns' domain, so it
+says something comparable to the columns beside it.
+
+The other half of a combination chart, a count against a percentage on a
+scale of its own, is `secondary`, which is a separate property because it
+is a separate question and because the two compose: `with-a-second-axis`
+ships naming one series in both. The argument for why a second scale is opt
+in, and why setting it labels both axes, is written there.
+
+A line among columns measures from zero, because the columns do and they
+share the axis. So does a line on the second scale, which is that scale's
+own rule rather than this one's. */
   lines?: (HelixHeadlessBarChart["lines"]) | undefined;
   /** Which series are measured against a scale of their own, by name.
 
-Space separated and matched the way `lines` is, against the column headings
-the table gives. Opt in: absent, every series shares one domain, which is
-what makes a chart comparable and is the right default.
+Separated and matched the way `lines` is, against the column headings the
+table gives. Opt in: absent, every series shares one domain, which is what
+makes a chart comparable and is the right default.
+
+**The scale, and `lines` is the mark.** The two are separate properties
+because they answer separate questions and a series usually wants both:
+a percentage beside a count is drawn as a line *and* measured on its own
+axis, which is what `with-a-second-axis` writes out. Neither implies the
+other, so a series can be a line on the shared scale and a column can have
+a scale to itself.
 
 **Two scales on one frame let an author put any two shapes in any relation
 by choosing the ranges, and a reader cannot see it happening.** That is not
@@ -2884,7 +2898,15 @@ the bar chart's baseline is not a property at all.
 circumference, which needs the radius, and reading a custom property means
 `getComputedStyle`, which is client-only: a server would draw a different
 ring than the client. A plot's proportions are markup for the same reason
-`curve` is. */
+`curve` is.
+
+**And so it does not reflect**, which is the same argument read forward. No
+selector on either tier asks about it and none can want to: everything the
+thickness decides is arithmetic done here and published as
+`--donut-chart-stroke`, which is a number a rule can do sums with where the
+word is not. Reflected, it wrote a value onto every host a script had set
+it on for nothing to read. `sweep` beside it is the converse and reflects,
+because three rules select on it. */
   hole?: (HelixHeadlessDonutChart["hole"]) | undefined;
   /** How much of the circle the whole occupies.
 
@@ -4122,7 +4144,20 @@ export type HelixHeadlessLegendVueProps = {
   /** Which way to read the table.
 
 Absent is `series`, one entry per data column. `categories` reads one entry
-per body row instead, for a donut, whose slices are the rows. */
+per body row instead, for a donut, whose slices are the rows.
+
+**`measures` is `series` without the first column, and it is for a
+scatter.** That chart reads its first numeric column as the measure
+*across*, so its first plotted series is the table's second and everything
+a legend beside it named was one color out: the across column wearing the
+color of the first series drawn, and each real series wearing the next
+one's. The across gets no entry rather than a shifted one, because it is an
+axis and a scatter already writes its name at the end of the scale under
+the plot.
+
+A legend cannot ask the chart which of these it is, `for` naming the table
+they share and not each other, so the consumer says it. That is the same
+shape `categories` already has. */
   entries?: (HelixHeadlessLegend["entries"]) | undefined;
   /** The id of the table to take the names from.
 
@@ -4197,9 +4232,20 @@ useful thing: it is where a reader looks for "and what is it now", which is
 the question a sparkline's single mark answers too.
 
 `none` lets the lines stop on their own, which suits a chart read for its
-shape rather than for where it finished. The shapes come from
+shape rather than for where it finished. `square` is the same mark with its
+corners, for a drawing whose neighbors are square, the columns of a table
+beside it for instance. `ring` lets the ground through, for a chart drawn
+over something busy. `triangle` points along the axis and reads as "and
+onward" rather than as a second claim about the data.
+
+The shapes come from
 `helix/styled/src/shared/chart/terminus.css`, the same sheet `Sparkline` takes, so
-the set is identical wherever one appears.
+the set is identical wherever one appears. **Which is why every value is
+named here.** `Sparkline` shipped `square` implemented, drawn, asserted and
+undocumented until the cohort before this one; this family reads the same
+four out of the same sheet and had left two of them unwritten, so the
+finding arrived twice. A shared vocabulary wants naming at each door into
+it, because a reader arrives at one door and not at the set.
 
 `ring` is the one that asks something of the drawing. It leaves a hole and a
 line ends at the reading, which is the hole's center, so the `<svg>` is
@@ -8780,7 +8826,7 @@ one-line rows should leave this alone. */
 export type HelixHeadlessVirtualListVueEvents = {};
 
 export type CustomCssProperties = {
-  /** The color of a single-series axis, taken from that series. */
+  /** How wide an axis column is drawn, in `ch`, from the widest number on it. Written on the axis itself, and only where the categories run along the bottom: turned sideways an axis is a row and takes a line's height instead. */
   "--bar-chart-axis"?: (string) | undefined;
   /** The color of the secondary axis when one series owns it. It resolves a `--helix-color-series-*` token, so on the headless tier alone it names something that is not there. #138. */
   "--bar-chart-secondary"?: (string) | undefined;
@@ -8848,6 +8894,10 @@ export type CustomCssProperties = {
   "--heatmap-tone-success"?: (string) | undefined;
   /** What `warning` is worth. */
   "--heatmap-tone-warning"?: (string) | undefined;
+  /** Where a series' last reading sits horizontally, as a percentage. Written by the component. */
+  "--chart-terminus-x"?: (string) | undefined;
+  /** Where a series' last reading sits vertically, as a percentage. Written by the component. */
+  "--chart-terminus-y"?: (string) | undefined;
   /** Where the panel starts, measured from the bar above it. */
   "--megamenu-top"?: (string) | undefined;
   /** Where a bound sits on the arc, as a length along it. */
@@ -8884,10 +8934,6 @@ export type CustomCssProperties = {
   "--slider-marker-at"?: (string) | undefined;
   /** Where the filled span ends, as a percentage of the track. */
   "--slider-to"?: (string) | undefined;
-  /** Where the last point sits horizontally, as a percentage. */
-  "--chart-terminus-x"?: (string) | undefined;
-  /** Where the last point sits vertically, as a percentage. */
-  "--chart-terminus-y"?: (string) | undefined;
   /** Where a nested splitter crosses this one, as a percentage. */
   "--splitter-corner-at"?: (string) | undefined;
   /** Where the divider sits, as a percentage of the box. */
@@ -8938,7 +8984,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessAppHeaderVueProps,
     HelixHeadlessAppHeaderVueEvents
   >;
-  /** The chart for a composition: every column of the table is a part, the parts sum to the whole at each reading, and the top edge is that whole. What a line chart of the same table cannot show is the share, which here is the thickness of a band.  **Not 'Line Chart' with 'area'.** That washes each series from the floor on its own, so the series overlap; this adds them. Reach for 'Line Chart' when the question is how each series moved, and for this when it is how the whole is made up.  **It measures from zero, always**, which is 'BarChart''s rule and for the same reason: a band's thickness *is* its value, so a range that starts anywhere else draws every part in proportion to nothing. 'LineChart' measures from its own range because a line claims a position; a band claims an amount.  **Straight between readings unless asked otherwise.** A band's top edge is a sum, and a curve fitted through one sum can pass under the curve fitted through the sum beneath it, so a smoothed stack can draw a part as less than nothing between two readings. Straight segments between ordered points stay ordered. 'curve="smooth"' is there for a stack that is read as a shape.  **'share' draws each reading as a hundred percent**, so the bands are the parts' shares and the top edge is flat. It answers "which part grew" where the default answers "did the whole grow".  **What a reader without the picture is told is the total and the share**, not every band in turn. The table beside the chart already reads out every number; what the drawing adds is the composition, so the summary says the latest reading's total and each part's share of it. The drawing itself is 'aria-hidden'.  Every numeric column is a part. A table that carries its own total column would count it twice, so leave it out of the table the chart reads. A negative reading is drawn as none: a part of a whole cannot be less than nothing, and a band that folded under its neighbor would say it was. */
+  /** The chart for a composition: every column of the table is a part, the parts sum to the whole at each reading, and the top edge is that whole. What a line chart of the same table cannot show is the share, which here is the thickness of a band.  **Not 'Line Chart' with 'area'.** That washes each series from the floor on its own, so the series overlap; this adds them. Reach for 'Line Chart' when the question is how each series moved, and for this when it is how the whole is made up.  **It measures from zero, always**, which is 'BarChart''s rule and for the same reason: a band's thickness *is* its value, so a range that starts anywhere else draws every part in proportion to nothing. 'LineChart' measures from its own range because a line claims a position; a band claims an amount.  **And so it is not a streamgraph**, which is the near neighbor to name. A streamgraph moves its baseline to center the bands and reads as a river; it is a real form and it is the one thing the rule above refuses, so this carries no alias for it. What it has instead is 'share', which answers the question a streamgraph is usually reached for, how the composition changed, without giving up a floor a reader can measure against.  **Straight between readings unless asked otherwise.** A band's top edge is a sum, and a curve fitted through one sum can pass under the curve fitted through the sum beneath it, so a smoothed stack can draw a part as less than nothing between two readings. Straight segments between ordered points stay ordered. 'curve="smooth"' is there for a stack that is read as a shape.  'curve="step"' falls on the safe side of that argument rather than being unanswered by it, and it is worth saying which side because a reader cannot tell from the argument alone. A step takes no value the readings do not have: it holds one, jumps at the midpoint, and holds the next. So two stepped edges that are ordered at every reading are ordered everywhere between them, which is what 'straight' is chosen for. It is the curve for a quantity that changes at a moment rather than across an interval, a headcount or a price, where a sloped edge claims a gradual change nothing measured.  **'share' draws each reading as a hundred percent**, so the bands are the parts' shares and the top edge is flat. It answers "which part grew" where the default answers "did the whole grow".  **What a reader without the picture is told is the total and the share**, not every band in turn. The table beside the chart already reads out every number; what the drawing adds is the composition, so the summary says the latest reading's total and each part's share of it. The drawing itself is 'aria-hidden'.  Every numeric column is a part. A table that carries its own total column would count it twice, so leave it out of the table the chart reads. A negative reading is drawn as none: a part of a whole cannot be less than nothing, and a band that folded under its neighbor would say it was. */
   "helix-headless-area-chart": DefineCustomElement<
     HelixHeadlessAreaChart,
     HelixHeadlessAreaChartVueProps,
@@ -9238,7 +9284,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessKbdVueProps,
     HelixHeadlessKbdVueEvents
   >;
-  /** A legend is a list, so it is a list: not part of a chart, and shared by whichever of them needs one. It takes its entries from the same table the chart reads, through 'for', so the two cannot disagree.  'entries' picks which way to read that table. 'series' is one entry per data column, named by the header row, which is a line or a bar chart. 'categories' is one entry per body row, which is a donut: its slices are the rows and it has no axis to write their names along.  **The table is resolved on the client and there is no server pass.** */
+  /** A legend is a list, so it is a list: not part of a chart, and shared by whichever of them needs one. It takes its entries from the same table the chart reads, through 'for', so the two cannot disagree.  'entries' picks which way to read that table. 'series' is one entry per data column, named by the header row, which is a line or a bar chart. 'categories' is one entry per body row, which is a donut: its slices are the rows and it has no axis to write their names along. 'measures' drops the first data column, which is a scatter.  **The table is resolved on the client and there is no server pass.** */
   "helix-headless-legend": DefineCustomElement<
     HelixHeadlessLegend,
     HelixHeadlessLegendVueProps,