@fusion.dev/helix 0.39.0 → 0.41.0

package/types/vue.d.ts

@@ -138,8 +138,8 @@ import type {
   HelixVideoPlaylist,
   HelixVideo,
   HelixVirtualList,
-  HelixBeforeOpenEvent,
   HelixBeforeCloseEvent,
+  HelixBeforeOpenEvent,
   HelixDismissEvent,
   HelixScrolledEvent,
   HelixSelectEvent,
@@ -218,12 +218,12 @@ export type HelixAccordionItemElementEvent<E = Event> = TypedEvent<
   HelixAccordionItem,
   E
 >;
-/** `helix-before-open` event type */
-export type HelixAccordionItemHelixBeforeOpenElementEvent =
-  HelixAccordionItemElementEvent<HelixBeforeOpenEvent>;
 /** `helix-before-close` event type */
 export type HelixAccordionItemHelixBeforeCloseElementEvent =
   HelixAccordionItemElementEvent<HelixBeforeCloseEvent>;
+/** `helix-before-open` event type */
+export type HelixAccordionItemHelixBeforeOpenElementEvent =
+  HelixAccordionItemElementEvent<HelixBeforeOpenEvent>;
 
 export type HelixAccordionItemVueProps = {
   /** Whether the element is open.
@@ -282,10 +282,10 @@ absence. Caught by `hydration.dom.spec.ts`. */
 };
 
 export type HelixAccordionItemVueEvents = {
-  /** Fired before the item opens or closes. Cancelable: refusing it takes the decision and nothing moves. */
-  "helix-before-open": HelixAccordionItemHelixBeforeOpenElementEvent;
   /** Fired before the section closes, and cancelable. */
   "helix-before-close": HelixAccordionItemHelixBeforeCloseElementEvent;
+  /** Fired before the section opens. Cancelable: refusing it takes the decision and nothing moves. */
+  "helix-before-open": HelixAccordionItemHelixBeforeOpenElementEvent;
   /** Says the state moved, carrying `newState` and `oldState`. */
   toggle: HelixAccordionItemElementEvent;
 };
@@ -508,9 +508,13 @@ words and is already written. */
   label?: (HelixAreaChart["label"]) | undefined;
   /** 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?: (HelixAreaChart["curve"]) | undefined;
   /** Which rules are drawn across the plot, if any.
 
@@ -740,6 +744,12 @@ The chart's treatment, which every series takes unless `outlined` or
 of the series color with that edge on it, and absent is the filled column,
 per the rule that a reflected property takes no default.
 
+`solid` is that filled column written out. It matches no rule in the sheet
+and lands on the base one, which is what the resting value of every axis in
+the registry does, and it is worth having so a consumer switching a chart
+between treatments has a word for the one it started at rather than having
+to remove the attribute.
+
 **It composes with `material` rather than competing with it.** Emphasis
 decides what is drawn and material decides how much of it comes through, so
 `glass` thins whatever emphasis put there: the fill on a solid column, the
@@ -796,10 +806,15 @@ having the datum rather than by painting it invisibly. */
   material?: (HelixBarChart["material"]) | undefined;
   /** Which series are drawn as an outline rather than a fill, by name.
 
-Space separated and matched against the column headings the table gives,
-the way `lines` and `secondary` are, so a chart says `outlined="Forecast"`
-rather than counting columns. Names because they are what the table already
-carries and what the legend already shows.
+Separated by whitespace or commas and matched against the column headings
+the table gives, the way `lines` and `secondary` are, so a chart says
+`outlined="Forecast"` rather than counting columns. Names because they are
+what the table already carries and what the legend already shows.
+
+All five read one splitter, `seriesNames` in `core`, because the sentence
+above was true of the matching and false of the splitting: these three took
+a comma and those two did not, so `lines="Gateway, Billing"` drew no line
+and said nothing.
 
 **The case this exists for is a series that is not a measurement.** A
 forecast, a target, a budget: something drawn on the same axis as the
@@ -868,28 +883,38 @@ and reach no reader through the table. */
   gridlines?: (HelixBarChart["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?: (HelixBarChart["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
@@ -3532,7 +3557,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?: (HelixDonutChart["hole"]) | undefined;
   /** How much of the circle the whole occupies.
 
@@ -4908,7 +4941,20 @@ Matched as `outlined` is. */
   /** 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?: (HelixLegend["entries"]) | undefined;
   /** The id of the table to take the names from.
 
@@ -5037,9 +5083,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
@@ -10243,6 +10300,8 @@ export type CustomCssProperties = {
   "--area-chart-gridline-color"?: (string) | undefined;
   /** Thickness of a band's top edge, over `--chart-stroke`. */
   "--area-chart-width"?: (string) | undefined;
+  /** Thickness of a band's top edge, one name across this family, Line Chart and Bar Chart's `lines`, since the three read one shared rule. `--area-chart-width` overrides it here. */
+  "--chart-stroke"?: (string) | undefined;
   /** How far each avatar sits over the one before it. */
   "--avatar-group-overlap"?: (string) | undefined;
   /** The separation drawn between one avatar and the next. */
@@ -10273,7 +10332,7 @@ export type CustomCssProperties = {
   "--bar-chart-line-color"?: (string) | undefined;
   /** Thickness of a `lines` series, over `--chart-stroke`. */
   "--bar-chart-line-width"?: (string) | undefined;
-  /** 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;
@@ -10685,8 +10744,10 @@ export type CustomCssProperties = {
   "--legend-swatch-size"?: (string) | undefined;
   /** Width of the edge an `outlined` or `subtle` swatch is drawn with. */
   "--legend-swatch-stroke"?: (string) | undefined;
-  /** Thickness of a series drawn as a line, here and on Area Chart's top edge and Bar Chart's `lines`. Each family's own width hook overrides it. */
-  "--chart-stroke"?: (string) | undefined;
+  /** A fill for the middle of a `ring` terminus, which is otherwise open. One name across this family and Sparkline, the two reading one shared sheet. */
+  "--chart-terminus-hole"?: (string) | undefined;
+  /** Size of the mark on each series' last reading. One name across this family and Sparkline, the two reading one shared sheet. */
+  "--chart-terminus-size"?: (string) | undefined;
   /** How much of a line's color its wash takes. */
   "--line-chart-area-opacity"?: (string) | undefined;
   /** The slot the pointer is resting in. */
@@ -10699,6 +10760,10 @@ export type CustomCssProperties = {
   "--line-chart-gridline-color"?: (string) | undefined;
   /** Thickness of a line, over `--chart-stroke`. */
   "--line-chart-width"?: (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;
   /** Padding inside the row. */
   "--list-item-padding"?: (string) | undefined;
   /** What the rail cell shows. Written by the list. */
@@ -11031,10 +11096,6 @@ export type CustomCssProperties = {
   "--slider-marker-at"?: (string) | undefined;
   /** Where the filled span ends, as a percentage of the track. */
   "--slider-to"?: (string) | undefined;
-  /** A fill for the middle of a `ring` terminus, which is otherwise open. */
-  "--chart-terminus-hole"?: (string) | undefined;
-  /** Size of the mark on the last reading. */
-  "--chart-terminus-size"?: (string) | undefined;
   /** How much of the line's color the wash takes where it meets the line. */
   "--sparkline-area-opacity"?: (string) | undefined;
   /** Corner radius on a column, under `plot="bar"`. */
@@ -11049,10 +11110,6 @@ export type CustomCssProperties = {
   "--sparkline-inline-size"?: (string) | undefined;
   /** Thickness of the line, overriding `weight`. */
   "--sparkline-width"?: (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;
   /** Edge length of the mark. */
   "--speed-dial-item-size"?: (string) | undefined;
   /** Space between the actions. */
@@ -11269,7 +11326,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixAppHeaderVueProps,
     HelixAppHeaderVueEvents
   >;
-  /** The bands take the series palette in order, the first column at the bottom, so a legend beside the chart names them in the order they are stacked.  Each band is a pale fill with its top edge drawn at the series' full color. The fills are mixed toward the page rather than made translucent, because the bands overlap where they are drawn and a translucent one would show the others through it. */
+  /** The bands take the series palette in order, the first column at the bottom, so a legend beside the chart names them in the order they are stacked.  Each band is a pale fill with its top edge drawn at the series' full color. The fills are mixed toward the page rather than made translucent, because the bands overlap where they are drawn and a translucent one would show the others through it.  **No visual axis applies here, and that is the answer rather than a gap.** Both refusals are geometric and both were argued in the stylesheet before they were argued anywhere a reader looks.  'emphasis' is which of a family's two marks carries the reading, and here neither can give way. The fill is the value, a band's thickness being its amount, and the edge is the boundary, which is why it is drawn at full color over a pale fill rather than left to two pale fills meeting. Every point on the axis moves one at the other's expense: 'outlined' thins the fill until the chart is a set of cumulative lines, which is 'LineChart' and is the form this one exists because a reader cannot read shares off; 'solid' takes the fill to the series' own color, which is the edge's color, so the boundary disappears into the band it bounds. 'LineChart' can take the axis because its wash is optional there, 'area' deciding whether one is drawn at all.  'material' is what reads through a mark, and a band cannot let anything through. Each is drawn as everything under its top edge with the next one down covering the rest, so a translucent band shows the bands behind it and reads as a third color that is in no palette. That is 'LineChart''s recorded reason for refusing 'wash', met here from the other side. The strength of a fill is still adjustable and is '--area-chart-fill-strength', which is a continuum rather than an axis and is a theme's business rather than a reader's. */
   "helix-area-chart": DefineCustomElement<
     HelixAreaChart,
     HelixAreaChartVueProps,
@@ -11593,7 +11650,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixLegendVueProps,
     HelixLegendVueEvents
   >;
-  /** The lines take the series palette in order, so a chart of one is series one and a chart of four is the first four, and a legend beside it maps the same twenty-four.  The stroke does not scale with the box. 'preserveAspectRatio="none"' is what lets one drawing fill a narrow card and a wide panel, and without 'vector-effect: non-scaling-stroke' the same line comes out hairline in the first and heavy in the second. It rescues strokes and not geometry, which is why the readings are joined by lines and marked by nothing: a circle in a stretched coordinate space is an ellipse, and there is no vector-effect that answers for a shape. */
+  /** The lines take the series palette in order, so a chart of one is series one and a chart of four is the first four, and a legend beside it maps the same twenty-four.  The stroke does not scale with the box. 'preserveAspectRatio="none"' is what lets one drawing fill a narrow card and a wide panel, and without 'vector-effect: non-scaling-stroke' the same line comes out hairline in the first and heavy in the second. It rescues strokes and not geometry, which is why nothing inside the drawing marks a reading: a circle in a stretched coordinate space is an ellipse, and there is no vector-effect that answers for a shape.  **The last reading of each series is marked, and that is the same rule rather than an exception to it.** 'terminus' draws an HTML element placed over the plot by percentage instead of a shape inside it, so it keeps its shape at any width. It is on by default, as a dot, because the column of marks at the far edge is where a reader looks for "and what is it now". */
   "helix-line-chart": DefineCustomElement<
     HelixLineChart,
     HelixLineChartVueProps,
@@ -11629,7 +11686,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixMegamenuVueProps,
     HelixMegamenuVueEvents
   >;
-  /** The tick and the arrow hold their space whether or not they are showing, so the labels in a menu start at one place and the rows read as a column rather than as a ragged list. */
+  /** A row draws a column beside its label only where it has something to put in one, and the width is the menu's rather than the row's: the page reserves a leading or a trailing track as soon as any row on it fills one, so every label on that page starts at the same edge and a page that fills neither pays for neither. A row knows about its own slots and nothing about its neighbors, which is why the reservation is not made here. */
   "helix-menu-item": DefineCustomElement<
     HelixMenuItem,
     HelixMenuItemVueProps,
@@ -11809,7 +11866,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixSandboxToolbarVueProps,
     HelixSandboxToolbarVueEvents
   >;
-  /** The points take the series palette in order, so a table with one column measured up is series one and a table with three is the first three.  Each point has a ring of the page around it and stops short of opaque, so a dense cluster reads as dense rather than as one blot, and two points that overlap each keep their edge. */
+  /** The points take the series palette in order, so a table with one column measured up is series one and a table with three is the first three.  Each point has a ring of the page around it and stops short of opaque, so a dense cluster reads as dense rather than as one blot, and two points that overlap each keep their edge.  **No visual axis applies here, and that is the answer rather than a gap.** Both refusals come out of that sentence, and both were argued in the stylesheet before they were argued anywhere a reader looks.  'emphasis' is how much ink a mark claims, and on a scatter that channel is already carrying data. The points rest at 0.8 so that where they pile up they compound: how dark a region is *is* how many rows are in it, which is most of what a reader is looking at a scatter to see and is the one thing a table of the same numbers hides. 'solid' flattens a dense cluster and a sparse one into the same picture; 'outlined' replaces the pile with overlapping rings, which reads as texture rather than as count. An axis whose two ends each cost the drawing its density is not a treatment, it is a second meaning for a property the chart already spends.  'material' is the same refusal said once more. Translucency is the density channel here, so 'glass' and 'frosted' are two more named stops on a scale the data is using, and a point admitting the page through is a point that counts for less than one.  What stays adjustable is '--scatter-chart-point-opacity', and it is a continuum rather than an axis: a chart drawn over a busier ground wants a different resting density, and that is a fact about the ground rather than a claim about the points. */
   "helix-scatter-chart": DefineCustomElement<
     HelixScatterChart,
     HelixScatterChartVueProps,
@@ -11928,7 +11985,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixTabPanelVueProps,
     HelixTabPanelVueEvents
   >;
-  /** Selection is marked with a rule under the active tab rather than a filled pill, which keeps the row flat and lets the underline animate between tabs as a movement instead of two separate fills. */
+  /** One mark travels between the tabs rather than each of them filling and emptying in turn. A fill that swaps is two things changing at once and reads as a flicker; one that moves is a single object the eye follows, and it says where the current tab was as well as where it is. 'Navigation' marks its destinations the same way and for the same reason.  What the mark is depends on 'variant': unset it is a raised pill on the selected tab with nothing behind the row, 'underlined' makes it a bar along the bottom of the strip on a rule, and 'segmented' grows it to the tab's own box inside a sunken track. */
   "helix-tabs": DefineCustomElement<
     HelixTabs,
     HelixTabsVueProps,