@fusion.dev/helix 0.41.1 → 0.42.0

package/types/jsx.d.ts

@@ -1087,13 +1087,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`.
 
@@ -1185,13 +1189,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. */
   "prop:variance"?: (HelixAura["variance"]) | undefined;
   /** Which form the light takes. Absent is `braid`.
 
@@ -1906,7 +1914,15 @@ export type HelixBreadcrumbsSolidJsProps = {
 };
 
 export type HelixButtonGroupProps = {
-  /** 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.
 
@@ -1934,7 +1950,15 @@ column. */
 };
 
 export type HelixButtonGroupSolidJsProps = {
-  /** 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. */
   "prop:variant"?: (HelixButtonGroup["variant"]) | undefined;
   /** Accessible name for the group.
 
@@ -2802,7 +2826,7 @@ server markup never had, which React reports as a mismatch. The one-across
 case is the absent attribute, and the styles read it that way. */
   perView?: (HelixCarousel["perView"]) | undefined;
 
-  /** 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`. */
   "onhelix-select"?: ((e: HelixCarouselHelixSelectElementEvent) => void) | undefined;
 };
 
@@ -3032,7 +3056,7 @@ its attribute on upgrade, and the host then carries something a consumer's
 server markup never had, which React reports as a mismatch. The one-across
 case is the absent attribute, and the styles read it that way. */
   "prop:perView"?: (HelixCarousel["perView"]) | undefined;
-  /** 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`. */
   "on:helix-select"?: ((e: HelixCarouselHelixSelectElementEvent) => void) | undefined;
 
   /** Set the innerHTML of the element */
@@ -6604,9 +6628,36 @@ export type HelixDialogHelixBeforeOpenElementEvent =
   HelixDialogElementEvent<HelixBeforeOpenEvent>;
 
 export type HelixDialogProps = {
-  /** 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.
 
@@ -6682,9 +6733,36 @@ survives to it and a consumer reading one back gets what they wrote. */
 };
 
 export type HelixDialogSolidJsProps = {
-  /** 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. */
   "prop: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. */
   "prop:size"?: (HelixDialog["size"]) | undefined;
   /** Whether the element is open.
 
@@ -19462,7 +19540,35 @@ export type HelixVideoHelixPreviousElementEvent =
   HelixVideoElementEvent<HelixPreviousEvent>;
 
 export type HelixVideoProps = {
-  /** 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.
 
@@ -19711,7 +19817,35 @@ past the end is the one write the platform answers with an exception. */
 };
 
 export type HelixVideoSolidJsProps = {
-  /** 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. */
   "prop:separation"?: (HelixVideo["separation"]) | undefined;
   /** Whether it starts on its own, which a browser only allows while silent.
 
@@ -20779,13 +20913,17 @@ export type CustomElements = {
    * 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.
    * - `variant`: Which form the light takes. Absent is `braid`.
    *
    * Reflected because the fallback gradient selects on it, and given no default
@@ -21656,6 +21794,14 @@ export type CustomElements = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `variant`: 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.
    * - `label`: Accessible name for the group.
    *
    * On the host through internals, so an author's `aria-label` still overrides
@@ -22372,7 +22518,7 @@ export type CustomElements = {
    *
    * Events that will be emitted by the component.
    *
-   * - `helix-select`: Fired when the slide in view changes, with its index. Cancelable: refusing it takes the decision and nothing moves.
+   * - `helix-select`: 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`.
    *
    * ## Slots
    *
@@ -25542,8 +25688,35 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `align`: Whether the panel's contents run from the start or center on it.
+   * - `align`: 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.
    * - `size`: 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.
    * - `open`: Whether the element is open.
    *
    * One property, not two, so `dialog.open` answers the question anyone
@@ -38774,7 +38947,35 @@ export type CustomElements = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `separation`: Whether the bar floats on the picture or sits on its own ground.
+   * - `separation`: 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.
    * - `autoplay`: Whether it starts on its own, which a browser only allows while silent.
    *
    * Forwarded rather than acted on. Whether an unprompted play is permitted is
@@ -39899,13 +40100,17 @@ export type CustomElementsSolidJs = {
    * 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.
    * - `variant`: Which form the light takes. Absent is `braid`.
    *
    * Reflected because the fallback gradient selects on it, and given no default
@@ -40801,6 +41006,14 @@ export type CustomElementsSolidJs = {
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
    * - `variant`: 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.
    * - `label`: Accessible name for the group.
    *
    * On the host through internals, so an author's `aria-label` still overrides
@@ -41528,7 +41741,7 @@ export type CustomElementsSolidJs = {
    *
    * Events that will be emitted by the component.
    *
-   * - `helix-select`: Fired when the slide in view changes, with its index. Cancelable: refusing it takes the decision and nothing moves.
+   * - `helix-select`: 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`.
    *
    * ## Slots
    *
@@ -44748,8 +44961,35 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `align`: Whether the panel's contents run from the start or center on it.
+   * - `align`: 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.
    * - `size`: 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.
    * - `open`: Whether the element is open.
    *
    * One property, not two, so `dialog.open` answers the question anyone
@@ -58291,7 +58531,35 @@ export type CustomElementsSolidJs = {
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
    *
-   * - `separation`: Whether the bar floats on the picture or sits on its own ground.
+   * - `separation`: 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.
    * - `autoplay`: Whether it starts on its own, which a browser only allows while silent.
    *
    * Forwarded rather than acted on. Whether an unprompted play is permitted is

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.
 
@@ -9993,7 +10032,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.