@fusion.dev/helix-headless 0.47.0 → 0.48.0

package/types/jsx.d.ts

@@ -18,6 +18,7 @@ import type {
   HelixDismissEvent,
   HelixFacetEvent,
   HelixFilterEvent,
+  HelixFormElement,
   HelixHeadlessAccordion,
   HelixHeadlessAccordionItem,
   HelixHeadlessAnnouncement,
@@ -1839,6 +1840,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
@@ -1855,6 +1877,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
@@ -1940,6 +1983,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
@@ -1956,6 +2020,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
@@ -3070,6 +3155,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?: (HelixHeadlessColorPicker["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?: (HelixHeadlessColorPicker["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?: (HelixHeadlessColorPicker["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?: (HelixHeadlessColorPicker["required"]) | undefined;
   /** Colors offered under the picker, as a comma-separated list. */
   swatches?: (HelixHeadlessColorPicker["swatches"]) | undefined;
   /** The value the markup declared, which is where a reset returns to. */
@@ -3190,6 +3336,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. */
   "prop:noValue"?: (HelixHeadlessColorPicker["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. */
+  "bool:readonly"?: (HelixHeadlessColorPicker["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. */
+  "prop:readOnly"?: (HelixHeadlessColorPicker["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. */
+  "prop:required"?: (HelixHeadlessColorPicker["required"]) | undefined;
   /** Colors offered under the picker, as a comma-separated list. */
   "prop:swatches"?: (HelixHeadlessColorPicker["swatches"]) | undefined;
   /** The value the markup declared, which is where a reset returns to. */
@@ -11817,7 +12024,41 @@ export type HelixHeadlessRatingProps = {
 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?: (HelixHeadlessRating["min"]) | undefined;
   /** Whether this shows a score rather than asks for one.
 
@@ -11940,7 +12181,41 @@ export type HelixHeadlessRatingSolidJsProps = {
 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. */
   "prop:min"?: (HelixHeadlessRating["min"]) | undefined;
   /** Whether this shows a score rather than asks for one.
 
@@ -19196,6 +19471,27 @@ export type CustomElements = {
    * 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
@@ -19252,6 +19548,7 @@ export type CustomElements = {
    *
    * - `--carousel-gap`: Space between slides. A sheet sets it and the component measures the run with it. (default: `undefined`)
    * - `--carousel-pane`: The size one pane is laid out at. A sheet sets it and the component measures the run with it. (default: `undefined`)
+   * - `--carousel-per-view`: 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`. (default: `undefined`)
    * - `--carousel-run-end`: 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`. (default: `undefined`)
    *
    * ## CSS Parts
@@ -20565,6 +20862,46 @@ export type CustomElements = {
    * 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.
+   * - `readonly`/`readOnly`: 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.
+   * - `required`: 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.
    * - `swatches`: Colors offered under the picker, as a comma-separated list.
    * - `default-value`/`defaultValue`: The value the markup declared, which is where a reset returns to.
    * - `value`: What the control holds now, and what its form submits.
@@ -20642,14 +20979,8 @@ export type CustomElements = {
    *
    * Methods that can be called to access component functionality.
    *
+   * - `requestValue(next: string) => boolean`: Refuses every change while read-only. See `readOnly`.
    * - `focus(options?: FocusOptions) => void`: Puts the keyboard on the square, which is the control a reader wants.
-   * - `requestValue(next: string) => boolean`: Requests a new value, and reports whether the request stood.
-   *
-   * Announces before it acts, so `preventDefault()` on the `helix-before-change` is
-   * a refusal and nothing moves. Nobody refusing means the control updates
-   * itself, whether or not a consumer declared `value`: a declared property
-   * is a seed and a correction, the way `<input value>` is, and a consumer
-   * who wants the change for themselves refuses it and assigns their own.
    * - `formResetCallback() => void`: Returns the control to the value its markup declared.
    *
    * Both halves are dropped, the consumer's and the control's, because a
@@ -29255,6 +29586,40 @@ export type CustomElements = {
    * 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.
+   *
+   * **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.
    * - `readonly`/`readOnly`: Whether this shows a score rather than asks for one.
    *
    * A readout is not a control that has been switched off. It takes no focus,
@@ -29412,14 +29777,15 @@ export type CustomElements = {
    *
    * - `--rating-full`: How many marks are wholly filled. (default: `undefined`)
    * - `--rating-part`: How much of the next mark is filled, 0 to 1. (default: `undefined`)
-   * - `--rating-step`: The width of one step, as a fraction of a mark. (default: `undefined`)
-   * - `--rating-steps`: How many steps one mark is divided into. (default: `undefined`)
+   * - `--rating-step`: Which step along the row a target is, counting from one, whatever `min` leaves open. (default: `undefined`)
+   * - `--rating-steps`: How many steps the whole row holds, which is `max` over `step`. (default: `undefined`)
    *
    * ## CSS Parts
    *
    * Custom selectors for styling elements within the component.
    *
    * - `feedback`: What is wrong with it.
+   * - `field`: The row: the marks, and the score beside them.
    * - `fill`: The filled marks, clipped to the score.
    * - `hint`: Help under the marks, while nothing is wrong.
    * - `label`: The question, over the marks.
@@ -32620,6 +32986,19 @@ export type CustomElements = {
    * string, which is the whole reason the shape is that one. What each row *says*
    * is the reader's own convention, from `Intl`.
    *
+   * **The chosen row is marked in the markup, not worked out on upgrade.** The
+   * listbox is handed the answer as `.value`, and lit-ssr serializes no property
+   * binding, so a served `value="09:30"` shipped ninety-six rows with nothing on
+   * any of them saying which one it was: the mark arrived when the listbox
+   * upgraded and ran `place`. So each option is given `selected` as well, which
+   * is an attribute binding and does serve, and which the listbox then agrees
+   * with rather than fights, `place` writing the same answer from the same value.
+   * `selected` is the declaration a consumer writes on `Option` anywhere else in
+   * the library, and Date Picker expresses its own choice as markup for the same
+   * reason: a picker whose answer is invisible until a script runs is a picker
+   * whose answer is not served at all. Both readings do it, the list and the
+   * wheels, a wheel being a listbox like the list is.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
@@ -36973,6 +37352,27 @@ export type CustomElementsSolidJs = {
    * 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
@@ -37029,6 +37429,7 @@ export type CustomElementsSolidJs = {
    *
    * - `--carousel-gap`: Space between slides. A sheet sets it and the component measures the run with it. (default: `undefined`)
    * - `--carousel-pane`: The size one pane is laid out at. A sheet sets it and the component measures the run with it. (default: `undefined`)
+   * - `--carousel-per-view`: 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`. (default: `undefined`)
    * - `--carousel-run-end`: 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`. (default: `undefined`)
    *
    * ## CSS Parts
@@ -38361,6 +38762,46 @@ export type CustomElementsSolidJs = {
    * 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.
+   * - `readonly`/`readOnly`: 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.
+   * - `required`: 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.
    * - `swatches`: Colors offered under the picker, as a comma-separated list.
    * - `default-value`/`defaultValue`: The value the markup declared, which is where a reset returns to.
    * - `value`: What the control holds now, and what its form submits.
@@ -38438,14 +38879,8 @@ export type CustomElementsSolidJs = {
    *
    * Methods that can be called to access component functionality.
    *
+   * - `requestValue(next: string) => boolean`: Refuses every change while read-only. See `readOnly`.
    * - `focus(options?: FocusOptions) => void`: Puts the keyboard on the square, which is the control a reader wants.
-   * - `requestValue(next: string) => boolean`: Requests a new value, and reports whether the request stood.
-   *
-   * Announces before it acts, so `preventDefault()` on the `helix-before-change` is
-   * a refusal and nothing moves. Nobody refusing means the control updates
-   * itself, whether or not a consumer declared `value`: a declared property
-   * is a seed and a correction, the way `<input value>` is, and a consumer
-   * who wants the change for themselves refuses it and assigns their own.
    * - `formResetCallback() => void`: Returns the control to the value its markup declared.
    *
    * Both halves are dropped, the consumer's and the control's, because a
@@ -47175,6 +47610,40 @@ export type CustomElementsSolidJs = {
    * 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.
+   *
+   * **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.
    * - `readonly`/`readOnly`: Whether this shows a score rather than asks for one.
    *
    * A readout is not a control that has been switched off. It takes no focus,
@@ -47332,14 +47801,15 @@ export type CustomElementsSolidJs = {
    *
    * - `--rating-full`: How many marks are wholly filled. (default: `undefined`)
    * - `--rating-part`: How much of the next mark is filled, 0 to 1. (default: `undefined`)
-   * - `--rating-step`: The width of one step, as a fraction of a mark. (default: `undefined`)
-   * - `--rating-steps`: How many steps one mark is divided into. (default: `undefined`)
+   * - `--rating-step`: Which step along the row a target is, counting from one, whatever `min` leaves open. (default: `undefined`)
+   * - `--rating-steps`: How many steps the whole row holds, which is `max` over `step`. (default: `undefined`)
    *
    * ## CSS Parts
    *
    * Custom selectors for styling elements within the component.
    *
    * - `feedback`: What is wrong with it.
+   * - `field`: The row: the marks, and the score beside them.
    * - `fill`: The filled marks, clipped to the score.
    * - `hint`: Help under the marks, while nothing is wrong.
    * - `label`: The question, over the marks.
@@ -50610,6 +51080,19 @@ export type CustomElementsSolidJs = {
    * string, which is the whole reason the shape is that one. What each row *says*
    * is the reader's own convention, from `Intl`.
    *
+   * **The chosen row is marked in the markup, not worked out on upgrade.** The
+   * listbox is handed the answer as `.value`, and lit-ssr serializes no property
+   * binding, so a served `value="09:30"` shipped ninety-six rows with nothing on
+   * any of them saying which one it was: the mark arrived when the listbox
+   * upgraded and ran `place`. So each option is given `selected` as well, which
+   * is an attribute binding and does serve, and which the listbox then agrees
+   * with rather than fights, `place` writing the same answer from the same value.
+   * `selected` is the declaration a consumer writes on `Option` anywhere else in
+   * the library, and Date Picker expresses its own choice as markup for the same
+   * reason: a picker whose answer is invisible until a script runs is a picker
+   * whose answer is not served at all. Both readings do it, the list and the
+   * wheels, a wheel being a listbox like the list is.
+   *
    * ## Attributes & Properties
    *
    * Component attributes and properties that can be applied to the element or by using JavaScript.
@@ -53132,6 +53615,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;
   /** The chosen color, to paint over the transparency check. */
@@ -53212,9 +53697,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;
   /** Where a point sits across, as a percentage. Written by the component. */
   "--chart-point-x"?: (string) | undefined;