@fusion.dev/helix-headless 0.47.1 → 0.49.0

package/types/jsx.d.ts

@@ -18,6 +18,7 @@ import type {
   HelixDismissEvent,
   HelixFacetEvent,
   HelixFilterEvent,
+  HelixFormElement,
   HelixHeadlessAccordion,
   HelixHeadlessAccordionItem,
   HelixHeadlessAnnouncement,
@@ -3154,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. */
@@ -3274,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. */
@@ -11901,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.
 
@@ -12024,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.
 
@@ -20671,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.
@@ -20748,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
@@ -29361,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,
@@ -29518,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.
@@ -32726,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.
@@ -38489,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.
@@ -38566,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
@@ -47303,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,
@@ -47460,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.
@@ -50738,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.
@@ -53342,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;

package/types/vue.d.ts

@@ -1664,6 +1664,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. */
@@ -6105,7 +6166,41 @@ export type HelixHeadlessRatingVueProps = {
 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.
 
@@ -9038,9 +9133,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;
@@ -9734,7 +9829,7 @@ export interface WcToolkitVueGlobalComponents {
     HelixHeadlessTimeInputVueProps,
     HelixHeadlessTimeInputVueEvents
   >;
-  /** **A list rather than three wheels**, and the reason is what a list already is. 'helix-listbox' brings the keyboard, the typeahead, the scroll into view and the announcement of a set of options, and a time at a step is a set of options. Three little wheels for hours, minutes and a meridiem are three controls to build, three to test, and a tab stop each for something a reader answers once.  **A step is what makes it a list at all.** Fifteen minutes is ninety-six rows, which a reader scrolls or types into; one minute is one thousand four hundred and forty, which is a listbox in name only. So the list is for the times a product actually offers, and arbitrary times are the field's job in Input Time, the same division Date Input draws between typing a date and using the calendar.  **The value is 'HH:mm' on a twenty-four hour clock, always.** That is what a form submits and what 'min' and 'max' compare against, and it sorts as a string, which is the whole reason the shape is that one. What each row *says* is the reader's own convention, from 'Intl'. */
+  /** **A list rather than three wheels**, and the reason is what a list already is. 'helix-listbox' brings the keyboard, the typeahead, the scroll into view and the announcement of a set of options, and a time at a step is a set of options. Three little wheels for hours, minutes and a meridiem are three controls to build, three to test, and a tab stop each for something a reader answers once.  **A step is what makes it a list at all.** Fifteen minutes is ninety-six rows, which a reader scrolls or types into; one minute is one thousand four hundred and forty, which is a listbox in name only. So the list is for the times a product actually offers, and arbitrary times are the field's job in Input Time, the same division Date Input draws between typing a date and using the calendar.  **The value is 'HH:mm' on a twenty-four hour clock, always.** That is what a form submits and what 'min' and 'max' compare against, and it sorts as a 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. */
   "helix-headless-time-picker": DefineCustomElement<
     HelixHeadlessTimePicker,
     HelixHeadlessTimePickerVueProps,