@fusion.dev/helix 0.41.1 → 0.43.0

package/types/vue.d.ts

@@ -612,13 +612,17 @@ are interpolations, so a larger number extrapolates rather than
 exaggerating, and a streak whose length has passed through zero is drawn
 as a bar across the whole frame.
 
-Read by the shapes made of many similar things, whether those are counted
-or continuous: `streaks`, whose lanes draw a speed, a length, a width, a
-spacing and a weight apiece; `particles`, whose motes draw a size, a
-brightness and a wander; and `rays` and `aurora`, whose fan, bundles and
-folds widen or even out. `braid`, `waves` and `flow` have a
-single subject and nothing to vary, and `threads` is even on purpose, so on
-those four this is inert. */
+Read by four of the eleven shapes, the ones made of many similar things,
+whether those are counted or continuous: `streaks`, whose lanes draw a
+speed, a length, a width, a spacing and a weight apiece; `particles`, whose
+motes draw a size, a brightness and a wander; and `rays` and `aurora`, whose
+fan, bundles and folds widen or even out.
+
+Inert on the other seven, for three different reasons. `braid`, `waves` and
+`flow` have a single subject and nothing to vary. `threads` and `lattice`
+are even on purpose, a scatter of strands and a regular structure each being
+what it is because its members do not differ. `caustics` and `fracture` are
+populations this does not reach, which is a gap rather than a refusal. */
   variance?: (HelixAura["variance"]) | undefined;
   /** Which form the light takes. Absent is `braid`.
 
@@ -982,7 +986,15 @@ export type HelixBreadcrumbsVueProps = {};
 export type HelixBreadcrumbsVueEvents = {};
 
 export type HelixButtonGroupVueProps = {
-  /** Whether the buttons are one bar or a spaced row. */
+  /** Whether the buttons are one bar or a spaced row.
+
+Joined by default: one control made of parts, sharing borders, reading as a
+segmented bar.
+
+`spaced` is the same set with air between them, for a row of related but
+separate actions. The semantics and the joining are separate questions:
+`role="group"` and a shared name are what make a set of buttons a set, and
+`helix-flex` gives the spacing without the group. */
   variant?: (HelixButtonGroup["variant"]) | undefined;
   /** Accessible name for the group.
 
@@ -1546,7 +1558,7 @@ case is the absent attribute, and the styles read it that way. */
 };
 
 export type HelixCarouselVueEvents = {
-  /** Fired when the slide in view changes, with its index. Cancelable: refusing it takes the decision and nothing moves. */
+  /** Fired when the slide in view changes, with its index. Cancelable where the carousel is about to move: refusing a control or an indicator takes the decision and nothing moves. A drag has already moved the track, so that one announces after the fact and refusing it does nothing. See `handleScroll`. */
   "helix-select": HelixCarouselHelixSelectElementEvent;
 };
 
@@ -3386,9 +3398,36 @@ export type HelixDialogHelixBeforeOpenElementEvent =
   HelixDialogElementEvent<HelixBeforeOpenEvent>;
 
 export type HelixDialogVueProps = {
-  /** Whether the panel's contents run from the start or center on it. */
+  /** Which way the panel's contents read.
+
+One property for the whole panel rather than one per region. The regions are
+never mixed in practice: a dialog that asks a short question centers its
+mark, its title, its sentence and its buttons together, and a dialog holding
+a form runs all four from the start. Three properties would be three ways to
+write the same two arrangements, and a fourth way to get one of them wrong.
+
+Unset is `start` and stays unset, so a reflected default cannot appear on a
+host whose server output never had it. */
   align?: (HelixDialog["align"]) | undefined;
-  /** How wide the panel is allowed to be. */
+  /** How wide the panel is allowed to be.
+
+Steps rather than a number, because a dialog's width is a fact about what is
+in it: a confirmation is narrow, a form is not, and picking pixels per
+dialog is how a product ends up with nine of them. `full` takes the viewport
+less the same inset every step already stops short by, so a takeover is one
+more rung and not a second property.
+
+Unset is `md`, read as `:host(:not([size]))` beside `:host([size="md"])`
+rather than assigned here, for the reason `Drawer.placement` gives: this
+reflects, and a default would put `size="md"` into markup no consumer wrote.
+
+`size` is right despite the rule that controls have no size, because that
+rule's own test is whether two of them sitting together could legitimately
+differ, and it is answering "a ragged row is unwritable". Two dialogs never
+sit together. One is on screen at a time, in the top layer, and it is the
+region rather than a control in one, which is the same reason `Avatar` and
+`Spinner` keep theirs. Not `appearance`, which says how a thing reads
+rather than how wide it is. */
   size?: (HelixDialog["size"]) | undefined;
   /** Whether the element is open.
 
@@ -6194,15 +6233,27 @@ Written by the listbox. */
 
 `<option selected>` reflects to `defaultSelected` and `option.selected` is
 live state that does not reflect, and those are two different facts. This
-element has one `selected` doing both jobs, so what is captured here is what
-the markup said at upgrade, before anything could overwrite it: read the
-attribute later and the listbox's own writes answer instead.
-
-**The deeper half is 302 and is not this.** State reflecting under the
-declaration's name is the fault `TreeItem` already avoids by mirroring to
-`data-selected`, and four families here still write `selected` back into a
-consumer's markup. Splitting them means moving what every stylesheet selects
-on, which is a change of its own rather than a property being added. */
+element has one `selected` doing both jobs, so the declaration is the
+attribute and the state is the property.
+
+**The attribute, read when it is asked for, and never a snapshot taken in
+the constructor.** A field initializer runs there, and an element the HTML
+parser created has none of its attributes yet at that moment: measured on
+this element, on `Radio` and on `Toggle`, `<helix-option value="a"
+selected>` reported `defaultSelected` as `false` both from parsed markup
+and from `createElement` followed by `setAttribute`, which is every way a
+consumer writes one. The snapshot could only ever be true for an element
+already in the document when `customElements.define` ran.
+
+Nothing overwrites it either, which is what makes reading it late correct
+rather than merely later: `selected` does not reflect, for the reason
+`willUpdate` records, so the listbox's writes never reach the attribute and
+what it says is what the markup said.
+
+**The deeper half is not this.** State reflecting under the declaration's
+name is the fault `TreeItem` avoids by mirroring to `data-selected`.
+Splitting them means moving what every stylesheet selects on, which is a
+change of its own rather than a property being added. */
   defaultSelected?: (HelixOption["defaultSelected"]) | undefined;
 };
 
@@ -6956,9 +7007,22 @@ Written by the group. */
 
 `<option selected>` reflects to `defaultSelected` and `option.selected` is
 live state that does not reflect, and those are two different facts. This
-element has one `selected` doing both jobs, so what is captured here is what
-the markup said at upgrade, before anything could overwrite it: read the
-attribute later and the listbox's own writes answer instead.
+element has one `selected` doing both jobs, so the declaration is the
+attribute and the state is the property.
+
+**The attribute, read when it is asked for, and never a snapshot taken in
+the constructor.** A field initializer runs there, and an element the HTML
+parser created has none of its attributes yet at that moment: measured on
+this element, on `Option` and on `Toggle`, `<helix-radio value="a"
+selected>` reported `defaultSelected` as `false` both from parsed markup
+and from `createElement` followed by `setAttribute`, which is every way a
+consumer writes one. The snapshot could only ever be true for an element
+already in the document when `customElements.define` ran.
+
+Nothing overwrites it either, which is what makes reading it late correct
+rather than merely later: `selected` does not reflect, for the reason
+`willUpdate` records, so the group's writes never reach the attribute and
+what it says is what the markup said.
 
 **The deeper half is not this.** State reflecting under the declaration's
 name is the fault `TreeItem` avoids by mirroring to `data-selected`.
@@ -9351,9 +9415,22 @@ export type HelixToggleVueProps = {
 
 `<option selected>` reflects to `defaultSelected` and `option.selected` is
 live state that does not reflect, and those are two different facts. This
-element has one `selected` doing both jobs, so what is captured here is what
-the markup said at upgrade, before anything could overwrite it: read the
-attribute later and the listbox's own writes answer instead.
+element has one `selected` doing both jobs, so the declaration is the
+attribute and the state is the property.
+
+**The attribute, read when it is asked for, and never a snapshot taken in
+the constructor.** A field initializer runs there, and an element the HTML
+parser created has none of its attributes yet at that moment: measured on
+this element, on `Option` and on `Radio`, `<helix-toggle value="light"
+selected>` reported `defaultSelected` as `false` both from parsed markup
+and from `createElement` followed by `setAttribute`, which is every way a
+consumer writes one. The snapshot could only ever be true for an element
+already in the document when `customElements.define` ran.
+
+Nothing overwrites it either, which is what makes reading it late correct
+rather than merely later: `selected` does not reflect, for the reason
+`willUpdate` records, so the group's writes never reach the attribute and
+what it says is what the markup said.
 
 **The deeper half is not this.** State reflecting under the declaration's
 name is the fault `TreeItem` avoids by mirroring to `data-selected`.
@@ -9993,7 +10070,35 @@ export type HelixVideoHelixPreviousElementEvent =
   HelixVideoElementEvent<HelixPreviousEvent>;
 
 export type HelixVideoVueProps = {
-  /** Whether the bar floats on the picture or sits on its own ground. */
+  /** How the control bar sits on the picture.
+
+`separation` and not `emphasis`: all three states say what the bar sits on,
+which is where it separates from the picture, rather than how loud it is.
+
+Absent is the default and is what a player looks like, and what the
+platform's own controls do: they float on a gradient that fades up into the
+picture, dark enough to read them against a bright frame and gone entirely
+a little higher up. The picture runs edge to edge behind them. It has no
+name because it is the resting treatment.
+
+`filled` gives the controls a bar of their own, which is what a video
+embedded in a document usually wants, where the player is a component on a
+page rather than the page itself. It stays put rather than fading, because
+a bar that is part of the frame would leave a strip of the well behind it.
+
+`plain` is neither: the controls sit straight on the picture with nothing
+behind them. For a consumer who knows their footage, or who is putting
+their own ground there.
+
+A presentation property, so it lives on this tier. The headless element renders
+the same bar for all three.
+
+**Optional rather than defaulted, which is not a style preference.** A
+reflecting property with a default writes its attribute onto every host the
+moment the element upgrades, including the ones a consumer rendered and did
+not touch, and React reads that as a hydration mismatch. The absent
+attribute *is* the shadow, which the stylesheet reads as the base rule, so
+only the departure has to be named. */
   separation?: (HelixVideo["separation"]) | undefined;
   /** Whether it starts on its own, which a browser only allows while silent.
 
@@ -11090,11 +11195,11 @@ export type CustomCssProperties = {
   "--slider-track-size"?: (string) | undefined;
   /** The value as a fraction of the range, 0 to 1. */
   "--slider-fraction"?: (string) | undefined;
-  /** Where the filled span starts, as a percentage of the track. */
+  /** Where a range's filled span starts, as a fraction of the track, 0 to 1. */
   "--slider-from"?: (string) | undefined;
   /** Where one marker sits, as a percentage of the track. */
   "--slider-marker-at"?: (string) | undefined;
-  /** Where the filled span ends, as a percentage of the track. */
+  /** Where a range's filled span ends, as a fraction of the track, 0 to 1. */
   "--slider-to"?: (string) | undefined;
   /** How much of the line's color the wash takes where it meets the line. */
   "--sparkline-area-opacity"?: (string) | undefined;
@@ -11494,7 +11599,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixDateInputVueProps,
     HelixDateInputVueEvents
   >;
-  /** Six week rows always, so the grid keeps one height and a month change does not move whatever sits beneath it.  The column track is wider than the day, and the day is centered in it. The difference is the space between days, which belongs to the track rather than to a 'gap', so a range can paint across the whole track and stay continuous.  Days from the neighboring months stay in place and stay selectable, marked quieter rather than hidden, so the first and last weeks are whole and the grid reads as a continuous run of dates. */
+  /** Six week rows always, so the grid keeps one height and a month change does not move whatever sits beneath it.  The column track is wider than the day, and the day is centered in it. The difference is the space between days, which belongs to the track rather than to a 'gap', so a range can paint across the whole track and stay continuous.  Days from the neighboring months stay in place, marked quieter rather than hidden, so the first and last weeks are whole rows rather than ragged ones. They are filler and take no click, which the pointer says: no hover, and the cursor a box that does nothing has. At 'months="2"' the same date is a trailing cell in one grid and a real one in the next, so a filler day that could be chosen would put one answer on the page twice. */
   "helix-date-picker": DefineCustomElement<
     HelixDatePicker,
     HelixDatePickerVueProps,