@fusion.dev/helix 0.47.0 → 0.48.0

package/types/vue.d.ts

@@ -612,17 +612,23 @@ 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 four of the eleven shapes, the ones made of many similar things,
+Read by six 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. */
+motes draw a size, a brightness and a wander; `rays` and `aurora`, whose
+fan, bundles and folds widen or even out; `caustics`, whose three depths of
+fold close on one scale and one weight while the pool over them flattens to
+an even wash; and `fracture`, whose sites come home to their own cell
+centers, leaving equal territories and no border more contested than
+another.
+
+Inert on the other five, and every one of them a refusal. `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: `threads` gives
+its seven one amplitude, one thickness, one weight and one frequency on
+the argument that alike is what makes a weave read as woven, and a lattice
+whose cells differed would be a scatter with straight lines in it. */
   variance?: (HelixAura["variance"]) | undefined;
   /** Which form the light takes. Absent is `braid`.
 
@@ -1534,6 +1540,27 @@ clamps to the last *slide*, so three of the six indicators point at an
 offset the track has already reached: pressing next walks the dots to the
 end while the slides stop moving a third of the way through.
 
+**The number is published to the styles rather than enumerated by them**,
+as `--carousel-per-view` on the track, which is what keeps a width and a
+count from disagreeing. A sheet can only name a value it wrote a rule for,
+so the styled tier enumerated `per-view="2"` through `5` and called five a
+judgment; above it the pane fell back to one across while this file went on
+counting positions. Measured in Chromium over eight slides, six across gave
+three dots, a pane taking the whole track and five slides reachable only by
+dragging. Written from here there is no ceiling to exceed, and a consumer's
+own sheet reads the same declaration the styled one does. `runEnd` publishes
+its correction the same way and for the same reason.
+
+**On the track and not on the host.** A custom property on the host is a
+reflected attribute by another name: it would arrive on upgrade, and a
+consumer's server markup never had it. Inside the component's own shadow
+root it serializes with the rest of the template on the server, and the
+track's own declaration beats anything a consumer inherits in, so the
+attribute is the one answer to how wide a pane is.
+
+A value the track cannot honor is taken to the nearest one it can, by
+`across`, and both tiers read that rather than this.
+
 No default, because it reflects. A reflected property with a value writes
 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
@@ -1550,6 +1577,27 @@ clamps to the last *slide*, so three of the six indicators point at an
 offset the track has already reached: pressing next walks the dots to the
 end while the slides stop moving a third of the way through.
 
+**The number is published to the styles rather than enumerated by them**,
+as `--carousel-per-view` on the track, which is what keeps a width and a
+count from disagreeing. A sheet can only name a value it wrote a rule for,
+so the styled tier enumerated `per-view="2"` through `5` and called five a
+judgment; above it the pane fell back to one across while this file went on
+counting positions. Measured in Chromium over eight slides, six across gave
+three dots, a pane taking the whole track and five slides reachable only by
+dragging. Written from here there is no ceiling to exceed, and a consumer's
+own sheet reads the same declaration the styled one does. `runEnd` publishes
+its correction the same way and for the same reason.
+
+**On the track and not on the host.** A custom property on the host is a
+reflected attribute by another name: it would arrive on upgrade, and a
+consumer's server markup never had it. Inside the component's own shadow
+root it serializes with the rest of the template on the server, and the
+track's own declaration beats anything a consumer inherits in, so the
+attribute is the one answer to how wide a pane is.
+
+A value the track cannot honor is taken to the nearest one it can, by
+`across`, and both tiers read that rather than this.
+
 No default, because it reflects. A reflected property with a value writes
 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
@@ -2210,6 +2258,67 @@ answer to which one is authoritative or which has the caret. Do not close it
 the other way round, with Color Input dropping its own field: the value
 would then be unreadable and unpasteable without opening a panel. */
   noValue?: (HelixColorPicker["noValue"]) | undefined;
+  /** Whether the control refuses changes while still submitting its value.
+
+**Enforced by refusing every request in one place**, which is the seam this
+component already has: `requestValue` is what every path here comes through,
+and gating it once is what stops the next call site from being written
+without the check.
+
+Not `disabled`, which is the confusion worth naming: a disabled control
+submits nothing and leaves the tab order, and a read-only one submits its
+value and stays reachable, which is what a form showing a color somebody
+else set needs.
+
+**One gate is not enough here, and the second is `move`.** This picker
+holds a model beside its value, which Date Picker and Time Picker do not:
+`moved` is the HSB the square is drawn from, and it is written before the
+value is requested. Gating only the request would leave the square under
+the reader's pointer and the value where it was, which is a control that
+refuses and looks like it accepted. */
+  readonly?: (HelixColorPicker["readOnly"]) | undefined;
+  /** Whether the control refuses changes while still submitting its value.
+
+**Enforced by refusing every request in one place**, which is the seam this
+component already has: `requestValue` is what every path here comes through,
+and gating it once is what stops the next call site from being written
+without the check.
+
+Not `disabled`, which is the confusion worth naming: a disabled control
+submits nothing and leaves the tab order, and a read-only one submits its
+value and stays reachable, which is what a form showing a color somebody
+else set needs.
+
+**One gate is not enough here, and the second is `move`.** This picker
+holds a model beside its value, which Date Picker and Time Picker do not:
+`moved` is the HSB the square is drawn from, and it is written before the
+value is requested. Gating only the request would leave the square under
+the reader's pointer and the value where it was, which is a control that
+refuses and looks like it accepted. */
+  readOnly?: (HelixColorPicker["readOnly"]) | undefined;
+  /** Whether the form refuses to submit while no color is chosen.
+
+**A color is exactly as requirable as a date**, which is the comparison
+that settles it: this element extends `HelixFormElement`, carries `name`
+and reports its value, so a consumer writing
+`<helix-color-picker name="brand" required>` inside a form has every reason
+to expect the form to refuse an empty one. Its two siblings in the same
+composition position, Date Picker and Time Picker, both check it.
+
+Written out rather than taken from `MixinField`, for the reason those two
+record: the mixin brings a label, a hint and a feedback region, and this is
+a panel composed *into* a field that already has all three, so taking it
+would give one control two of each. What is left is the validity call and
+the anchor the browser points its bubble at.
+
+**Emptiness is the only fault reported, and bad input deliberately is
+not.** The value row is typed into a character at a time and every
+keystroke reaches `requestValue`, so `#0`, `#00` and `#00f` would each be a
+reported fault on the way to `#00ff00`. Date Picker and Time Picker can
+report bad input because their value moves only on a commit. Color Input
+reports it for this family instead, once, against the field the reader
+typed into. */
+  required?: (HelixColorPicker["required"]) | undefined;
   /** Colors offered under the picker, as a comma-separated list. */
   swatches?: (HelixColorPicker["swatches"]) | undefined;
   /** Whether the control is non-interactive.
@@ -7104,7 +7213,41 @@ a reset should return to. */
 Zero rather than one, because "no rating" and "the worst rating" are
 different answers and a control that cannot express the first has to
 pretend the second. A survey that requires an answer says so with
-`required`, not by making one unreachable. */
+`required`, not by making one unreachable.
+
+**It is the floor of the scale, and every edge follows from that.**
+
+*Clearing* returns the row to it. An empty rating, a value nothing can
+parse, and a form reset with nothing declared are all the same situation,
+and all three draw `min` filled: at the default of zero that is the empty
+row this always drew, and at `min="2"` it is two marks, the way an empty
+`Slider` sits at its own minimum rather than at zero. The value is still
+`""` through all of it, so `required` still refuses it and `valueAsNumber`
+is still `NaN`: what the row shows is the bottom of the scale, not an
+answer somebody gave.
+
+*The steps* are the scores from `step` up to `max` that are not below it,
+so `min="2"` on five marks offers 2 to 5 and leaves the first two marks
+filled and unpressable. At zero nothing is dropped, which is why the
+default row is unchanged.
+
+*The keyboard* moves through those steps and no others. `wrap` is already
+false here, so arrowing down from the lowest one holds its ground rather
+than reaching a score this property forbids, and the tab stop an unrated
+rating carries sits on the lowest score offered rather than on the first
+mark.
+
+*A `min` between two steps* is a floor and not a step: `min="1.5"` with
+whole marks clamps the value at 1.5 and offers 2 upward, since 1.5 is not
+somewhere the row can be pressed. That is a real thing to ask for and is
+left to mean what it says.
+
+*A `min` outside the marks is refused rather than obeyed*, and says so
+once on the console. Below zero and anything that is not a number are read
+as zero, there being no mark to draw for a negative score; above `max` is
+read as `max`, which collapses the scale to its top score rather than
+leaving a rating with nothing to press. A property that silently accepts
+nonsense is the fault this pays off, so neither case is quietly ignored. */
   min?: (HelixRating["min"]) | undefined;
   /** Whether this shows a score rather than asks for one.
 
@@ -10577,6 +10720,8 @@ export type CustomCssProperties = {
   "--carousel-gap"?: (string) | undefined;
   /** The size one pane is laid out at. A sheet sets it and the component measures the run with it. */
   "--carousel-pane"?: (string) | undefined;
+  /** How many slides go across, written onto the track by the component so a sheet divides the track by the same number the positions are counted from. Read it rather than selecting on `per-view`, which cannot be enumerated without a ceiling. See `perView`. */
+  "--carousel-per-view"?: (string) | undefined;
   /** How far short of a whole pixel the run ends, on the last slide alone, for a sheet to take up as `margin-inline-end`. See `runEnd`. */
   "--carousel-run-end"?: (string) | undefined;
   /** Fill behind the composer. */
@@ -11157,9 +11302,9 @@ export type CustomCssProperties = {
   "--rating-full"?: (string) | undefined;
   /** How much of the next mark is filled, 0 to 1. */
   "--rating-part"?: (string) | undefined;
-  /** The width of one step, as a fraction of a mark. */
+  /** Which step along the row a target is, counting from one, whatever `min` leaves open. */
   "--rating-step"?: (string) | undefined;
-  /** How many steps one mark is divided into. */
+  /** How many steps the whole row holds, which is `max` over `step`. */
   "--rating-steps"?: (string) | undefined;
   /** The invisible width of a divider's drag target. */
   "--sandbox-grab"?: (string) | undefined;
@@ -11569,7 +11714,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixCardVueProps,
     HelixCardVueEvents
   >;
-  /** The track scroll-snaps, so a drag and a trackpad swipe move it with the browser's own momentum and the controls only have to scroll.  Slides take the full track by default. 'per-view' fits more than one across, up to five, and is declared on the tier below because it decides how many positions the track has rather than only how wide a slide is, which is what a run of cards wants rather than a run of full-width panels. */
+  /** The track scroll-snaps, so a drag and a trackpad swipe move it with the browser's own momentum and the controls only have to scroll.  Slides take the full track by default. 'per-view' fits more than one across, at any count, and is declared on the tier below because it decides how many positions the track has rather than only how wide a slide is, which is what a run of cards wants rather than a run of full-width panels. This sheet divides the track by the number that tier publishes rather than enumerating the values it will answer for, so there is no count it silently draws one across. */
   "helix-carousel": DefineCustomElement<
     HelixCarousel,
     HelixCarouselVueProps,