@fusion.dev/helix 0.47.1 → 0.49.0

package/custom-elements.json

@@ -24904,6 +24904,36 @@
                 "module": "src/color-picker/root/color-picker-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "readOnly",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the control refuses changes while still submitting its value.\n\n**Enforced by refusing every request in one place**, which is the seam this\ncomponent already has: `requestValue` is what every path here comes through,\nand gating it once is what stops the next call site from being written\nwithout the check.\n\nNot `disabled`, which is the confusion worth naming: a disabled control\nsubmits nothing and leaves the tab order, and a read-only one submits its\nvalue and stays reachable, which is what a form showing a color somebody\nelse set needs.\n\n**One gate is not enough here, and the second is `move`.** This picker\nholds a model beside its value, which Date Picker and Time Picker do not:\n`moved` is the HSB the square is drawn from, and it is written before the\nvalue is requested. Gating only the request would leave the square under\nthe reader's pointer and the value where it was, which is a control that\nrefuses and looks like it accepted.",
+              "attribute": "readonly",
+              "reflects": true,
+              "inheritedFrom": {
+                "name": "HelixHeadlessColorPicker",
+                "module": "src/color-picker/root/color-picker-root.ts"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "required",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the form refuses to submit while no color is chosen.\n\n**A color is exactly as requirable as a date**, which is the comparison\nthat settles it: this element extends `HelixFormElement`, carries `name`\nand reports its value, so a consumer writing\n`<helix-color-picker name=\"brand\" required>` inside a form has every reason\nto expect the form to refuse an empty one. Its two siblings in the same\ncomposition position, Date Picker and Time Picker, both check it.\n\nWritten out rather than taken from `MixinField`, for the reason those two\nrecord: the mixin brings a label, a hint and a feedback region, and this is\na panel composed *into* a field that already has all three, so taking it\nwould give one control two of each. What is left is the validity call and\nthe anchor the browser points its bubble at.\n\n**Emptiness is the only fault reported, and bad input deliberately is\nnot.** The value row is typed into a character at a time and every\nkeystroke reaches `requestValue`, so `#0`, `#00` and `#00f` would each be a\nreported fault on the way to `#00ff00`. Date Picker and Time Picker can\nreport bad input because their value moves only on a commit. Color Input\nreports it for this family instead, once, against the field the reader\ntyped into.",
+              "attribute": "required",
+              "reflects": true,
+              "inheritedFrom": {
+                "name": "HelixHeadlessColorPicker",
+                "module": "src/color-picker/root/color-picker-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "swatches",
@@ -25101,7 +25131,22 @@
                   "text": "void"
                 }
               },
-              "description": "Reports the color to the form.\n\n**The one thing a form-associated element owes, and this element owed it\nfrom the start without paying.** It extends `HelixFormElement`, takes\n`MixinControllerValue` and carries `name`, so a consumer writing\n`<helix-color-picker name=\"brand\">` inside a form has every reason to\nexpect an entry, and the form carried none: no error, nothing in the\nmarkup to look at, and a field silently missing from the submission. Its\ntwo siblings in the same composition position, Color Input and Slider,\nboth report.\n\n`null` rather than an empty string where there is no color, which is the\ndifference between a control that submits nothing and one that submits a\nblank. There is no `setValidity` beside it: this element does not take\n`MixinField`, and every validity member of `ElementInternals` is the\nconsumer's to reach through the field that wraps it.",
+              "description": "Reports the color to the form.\n\n**The one thing a form-associated element owes, and this element owed it\nfrom the start without paying.** It extends `HelixFormElement`, takes\n`MixinControllerValue` and carries `name`, so a consumer writing\n`<helix-color-picker name=\"brand\">` inside a form has every reason to\nexpect an entry, and the form carried none: no error, nothing in the\nmarkup to look at, and a field silently missing from the submission. Its\ntwo siblings in the same composition position, Color Input and Slider,\nboth report.\n\n`null` rather than an empty string where there is no color, which is the\ndifference between a control that submits nothing and one that submits a\nblank.\n\nThe verdict goes beside it, because `required` is this element's own claim\nand nothing else can answer it: a picker standing on a page has no field\naround it to check on its behalf. What it is *not* is a second opinion on\neverything else, which is why bad input is left to Color Input. See\n`required`.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessColorPicker",
+                "module": "src/color-picker/root/color-picker-root.ts"
+              }
+            },
+            {
+              "kind": "method",
+              "name": "reportRequired",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Reports \"required and empty\", or clears it.\n\nAnchored on the square, which is where a reader would go to answer: it is\nthe first control in the panel and the one `focus` puts the keyboard on, so\nthe browser's bubble points at the thing to do rather than at the row that\nstates the result.",
               "inheritedFrom": {
                 "name": "HelixHeadlessColorPicker",
                 "module": "src/color-picker/root/color-picker-root.ts"
@@ -25203,6 +25248,35 @@
                 "module": "src/color-picker/root/color-picker-root.ts"
               }
             },
+            {
+              "kind": "method",
+              "name": "putBack",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "control",
+                  "type": {
+                    "text": "{ value: string }"
+                  }
+                },
+                {
+                  "name": "at",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ],
+              "description": "Returns a control that moved itself to what the model still holds.\n\n**A refusal has to undo something, and here it is a handle.** Every other\ncontrol in this picker is drawn from the model, so refusing the change\nleaves the picture right on its own. The two area ranges and the two\nchannel sliders are not: each moved before it announced, and each is bound\nwith `.value`, which lit dirty-checks against the value it last committed.\nThe model never changed, so that binding writes nothing and the handle\nstays where the reader dragged it, on a control that refused. Carousel\nsettles the same question the same way: a refusal puts the track back on\nthe slide the index still holds.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessColorPicker",
+                "module": "src/color-picker/root/color-picker-root.ts"
+              }
+            },
             {
               "kind": "method",
               "name": "takeChannel",
@@ -25888,6 +25962,32 @@
                 "module": "src/color-picker/root/color-picker-root.ts"
               }
             },
+            {
+              "name": "readonly",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the control refuses changes while still submitting its value.\n\n**Enforced by refusing every request in one place**, which is the seam this\ncomponent already has: `requestValue` is what every path here comes through,\nand gating it once is what stops the next call site from being written\nwithout the check.\n\nNot `disabled`, which is the confusion worth naming: a disabled control\nsubmits nothing and leaves the tab order, and a read-only one submits its\nvalue and stays reachable, which is what a form showing a color somebody\nelse set needs.\n\n**One gate is not enough here, and the second is `move`.** This picker\nholds a model beside its value, which Date Picker and Time Picker do not:\n`moved` is the HSB the square is drawn from, and it is written before the\nvalue is requested. Gating only the request would leave the square under\nthe reader's pointer and the value where it was, which is a control that\nrefuses and looks like it accepted.",
+              "fieldName": "readOnly",
+              "inheritedFrom": {
+                "name": "HelixHeadlessColorPicker",
+                "module": "src/color-picker/root/color-picker-root.ts"
+              }
+            },
+            {
+              "name": "required",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the form refuses to submit while no color is chosen.\n\n**A color is exactly as requirable as a date**, which is the comparison\nthat settles it: this element extends `HelixFormElement`, carries `name`\nand reports its value, so a consumer writing\n`<helix-color-picker name=\"brand\" required>` inside a form has every reason\nto expect the form to refuse an empty one. Its two siblings in the same\ncomposition position, Date Picker and Time Picker, both check it.\n\nWritten out rather than taken from `MixinField`, for the reason those two\nrecord: the mixin brings a label, a hint and a feedback region, and this is\na panel composed *into* a field that already has all three, so taking it\nwould give one control two of each. What is left is the validity call and\nthe anchor the browser points its bubble at.\n\n**Emptiness is the only fault reported, and bad input deliberately is\nnot.** The value row is typed into a character at a time and every\nkeystroke reaches `requestValue`, so `#0`, `#00` and `#00f` would each be a\nreported fault on the way to `#00ff00`. Date Picker and Time Picker can\nreport bad input because their value moves only on a commit. Color Input\nreports it for this family instead, once, against the field the reader\ntyped into.",
+              "fieldName": "required",
+              "inheritedFrom": {
+                "name": "HelixHeadlessColorPicker",
+                "module": "src/color-picker/root/color-picker-root.ts"
+              }
+            },
             {
               "name": "swatches",
               "type": {
@@ -81291,7 +81391,7 @@
           "helix": {
             "category": "navigation",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/outline",
             "aliases": [
               "Table of contents",
@@ -90846,7 +90946,7 @@
               }
             },
             {
-              "description": "The width of one step, as a fraction of a mark.",
+              "description": "Which step along the row a target is, counting from one, whatever `min` leaves open.",
               "name": "--rating-step",
               "inheritedFrom": {
                 "name": "HelixHeadlessRating",
@@ -90854,7 +90954,7 @@
               }
             },
             {
-              "description": "How many steps one mark is divided into.",
+              "description": "How many steps the whole row holds, which is `max` over `step`.",
               "name": "--rating-steps",
               "inheritedFrom": {
                 "name": "HelixHeadlessRating",
@@ -91262,7 +91362,7 @@
                 "text": "number"
               },
               "default": "0",
-              "description": "The lowest score a reader can give, which is what clearing returns to.\n\nZero rather than one, because \"no rating\" and \"the worst rating\" are\ndifferent answers and a control that cannot express the first has to\npretend the second. A survey that requires an answer says so with\n`required`, not by making one unreachable.",
+              "description": "The lowest score a reader can give, which is what clearing returns to.\n\nZero rather than one, because \"no rating\" and \"the worst rating\" are\ndifferent answers and a control that cannot express the first has to\npretend the second. A survey that requires an answer says so with\n`required`, not by making one unreachable.\n\n**It is the floor of the scale, and every edge follows from that.**\n\n*Clearing* returns the row to it. An empty rating, a value nothing can\nparse, and a form reset with nothing declared are all the same situation,\nand all three draw `min` filled: at the default of zero that is the empty\nrow this always drew, and at `min=\"2\"` it is two marks, the way an empty\n`Slider` sits at its own minimum rather than at zero. The value is still\n`\"\"` through all of it, so `required` still refuses it and `valueAsNumber`\nis still `NaN`: what the row shows is the bottom of the scale, not an\nanswer somebody gave.\n\n*The steps* are the scores from `step` up to `max` that are not below it,\nso `min=\"2\"` on five marks offers 2 to 5 and leaves the first two marks\nfilled and unpressable. At zero nothing is dropped, which is why the\ndefault row is unchanged.\n\n*The keyboard* moves through those steps and no others. `wrap` is already\nfalse here, so arrowing down from the lowest one holds its ground rather\nthan reaching a score this property forbids, and the tab stop an unrated\nrating carries sits on the lowest score offered rather than on the first\nmark.\n\n*A `min` between two steps* is a floor and not a step: `min=\"1.5\"` with\nwhole marks clamps the value at 1.5 and offers 2 upward, since 1.5 is not\nsomewhere the row can be pressed. That is a real thing to ask for and is\nleft to mean what it says.\n\n*A `min` outside the marks is refused rather than obeyed*, and says so\nonce on the console. Below zero and anything that is not a number are read\nas zero, there being no mark to draw for a negative score; above `max` is\nread as `max`, which collapses the scale to its top score rather than\nleaving a rating with nothing to press. A property that silently accepts\nnonsense is the fault this pays off, so neither case is quietly ignored.",
               "attribute": "min",
               "inheritedFrom": {
                 "name": "HelixHeadlessRating",
@@ -91380,6 +91480,20 @@
                 "module": "src/rating/root/rating-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "floor",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "private",
+              "description": "The floor the row actually uses, which is `min` where `min` is one.\n\nBetween zero and `max`, and zero for anything that is not a number, per\nthe note on `min`. Derived on read rather than corrected into the property,\nso `rating.min` still reports what the consumer set and the warning below\ncan tell the two apart.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixHeadlessRating",
+                "module": "src/rating/root/rating-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "score",
@@ -91393,6 +91507,20 @@
                 "module": "src/rating/root/rating-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "positions",
+              "type": {
+                "text": "number[]"
+              },
+              "privacy": "private",
+              "description": "Every score the marks can show, which is `max / step` of them.\n\nThe whole row rather than the part `min` leaves open, because this is what\nthe stylesheet lays the targets out against: `--rating-steps` is the pitch\nand a step's own place in this list is where it sits along the row. Counted\nfrom the part a reader can press instead, a floor above zero would widen\nevery target and slide the row left.",
+              "readonly": true,
+              "inheritedFrom": {
+                "name": "HelixHeadlessRating",
+                "module": "src/rating/root/rating-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "steps",
@@ -91400,7 +91528,7 @@
                 "text": "number[]"
               },
               "privacy": "private",
-              "description": "Every score a reader can choose, which is `max / step` of them.",
+              "description": "Every score a reader can choose, which is the positions `min` leaves open.",
               "readonly": true,
               "inheritedFrom": {
                 "name": "HelixHeadlessRating",
@@ -91559,7 +91687,7 @@
                   "text": "void"
                 }
               },
-              "description": "Reports the value, and whether the form may go without one.\n\n**`required` arrives from the mixin, so it prints on the reference page\nwhether or not anything here enforces it.** Without a `setValidity` call a\nform holding an unrated required rating submits, `:valid` true and the\nentry present but empty. `reportRequired` is what makes the property real.\n\n**Empty is `value === ''` rather than a score of zero**, because zero is a\nrating a reader can deliberately give when `min` allows it, and refusing to\nsubmit it would be the control disagreeing with the property that permits\nit. What `required` asks is whether they answered at all.\n\n`Slider` is deliberately not given the same treatment: a native\n`<input type=\"range\" required>` is always valid, because a range always\nholds a number, and matching the platform there is the point.",
+              "description": "Reports the value, and whether the form may go without one.\n\n**`required` arrives from the mixin, so it prints on the reference page\nwhether or not anything here enforces it.** Without a `setValidity` call a\nform holding an unrated required rating submits, `:valid` true and the\nentry present but empty. `reportRequired` is what makes the property real.\n\n**Empty is `value === ''` rather than a score at the floor**, and the two\nare not the same thing: an unanswered row draws `min`, per the note on that\nproperty, so a control that read its own picture would call every rating\nwith `min=\"2\"` answered the moment it rendered. What `required` asks is\nwhether the reader answered at all, which only the value knows. A consumer\nwho writes `value=\"0\"` has answered, and is not refused.\n\n`Slider` is deliberately not given the same treatment: a native\n`<input type=\"range\" required>` is always valid, because a range always\nholds a number, and matching the platform there is the point.",
               "inheritedFrom": {
                 "name": "HelixHeadlessRating",
                 "module": "src/rating/root/rating-root.ts"
@@ -91595,6 +91723,20 @@
                 "module": "src/rating/root/rating-root.ts"
               }
             },
+            {
+              "kind": "field",
+              "name": "warned",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the console has already been told about a `min` off the scale.",
+              "inheritedFrom": {
+                "name": "HelixHeadlessRating",
+                "module": "src/rating/root/rating-root.ts"
+              }
+            },
             {
               "kind": "field",
               "name": "valueAsNumber",
@@ -92193,7 +92335,7 @@
                 "text": "number"
               },
               "default": "0",
-              "description": "The lowest score a reader can give, which is what clearing returns to.\n\nZero rather than one, because \"no rating\" and \"the worst rating\" are\ndifferent answers and a control that cannot express the first has to\npretend the second. A survey that requires an answer says so with\n`required`, not by making one unreachable.",
+              "description": "The lowest score a reader can give, which is what clearing returns to.\n\nZero rather than one, because \"no rating\" and \"the worst rating\" are\ndifferent answers and a control that cannot express the first has to\npretend the second. A survey that requires an answer says so with\n`required`, not by making one unreachable.\n\n**It is the floor of the scale, and every edge follows from that.**\n\n*Clearing* returns the row to it. An empty rating, a value nothing can\nparse, and a form reset with nothing declared are all the same situation,\nand all three draw `min` filled: at the default of zero that is the empty\nrow this always drew, and at `min=\"2\"` it is two marks, the way an empty\n`Slider` sits at its own minimum rather than at zero. The value is still\n`\"\"` through all of it, so `required` still refuses it and `valueAsNumber`\nis still `NaN`: what the row shows is the bottom of the scale, not an\nanswer somebody gave.\n\n*The steps* are the scores from `step` up to `max` that are not below it,\nso `min=\"2\"` on five marks offers 2 to 5 and leaves the first two marks\nfilled and unpressable. At zero nothing is dropped, which is why the\ndefault row is unchanged.\n\n*The keyboard* moves through those steps and no others. `wrap` is already\nfalse here, so arrowing down from the lowest one holds its ground rather\nthan reaching a score this property forbids, and the tab stop an unrated\nrating carries sits on the lowest score offered rather than on the first\nmark.\n\n*A `min` between two steps* is a floor and not a step: `min=\"1.5\"` with\nwhole marks clamps the value at 1.5 and offers 2 upward, since 1.5 is not\nsomewhere the row can be pressed. That is a real thing to ask for and is\nleft to mean what it says.\n\n*A `min` outside the marks is refused rather than obeyed*, and says so\nonce on the console. Below zero and anything that is not a number are read\nas zero, there being no mark to draw for a negative score; above `max` is\nread as `max`, which collapses the scale to its top score rather than\nleaving a rating with nothing to press. A property that silently accepts\nnonsense is the fault this pays off, so neither case is quietly ignored.",
               "fieldName": "min",
               "inheritedFrom": {
                 "name": "HelixHeadlessRating",
@@ -92348,6 +92490,14 @@
                 "module": "src/rating/root/rating-root.ts"
               }
             },
+            {
+              "description": "The row: the marks, and the score beside them.",
+              "name": "field",
+              "inheritedFrom": {
+                "name": "HelixHeadlessRating",
+                "module": "src/rating/root/rating-root.ts"
+              }
+            },
             {
               "description": "The filled marks, clipped to the score.",
               "name": "fill",
@@ -113658,7 +113808,7 @@
           "summary": "The content shown for one tab.",
           "helix": {
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/tabs",
             "tier": "styled",
             "group": "Tabs",
@@ -114380,7 +114530,7 @@
           "helix": {
             "category": "navigation",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/tabs",
             "tier": "styled",
             "group": "Tabs",
@@ -115009,7 +115159,7 @@
           "summary": "One tab in a tab list.",
           "helix": {
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/tabs",
             "tier": "styled",
             "group": "Tabs",
@@ -129061,7 +129211,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The styled tier of `BaseTour`. It draws the light and nothing else.",
+          "description": "It draws the light and nothing else: the scrim's color and the lit box's\ncorners are this tier's, and the order, the stops and the measuring stay\nbelow.",
           "name": "HelixTour",
           "cssProperties": [
             {
@@ -129810,7 +129960,7 @@
           "helix": {
             "category": "overlays",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/tour",
             "tier": "styled",
             "group": "Tour",
@@ -130090,7 +130240,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The styled tier of `BaseTourStop`. The panel is `Popover`'s panel by another\nname, on purpose.",
+          "description": "The panel is `Popover`'s panel by another name, on purpose: a surface, an\ninset and a lift, so a stop and a flyout on the same page are the same\nobject. What this tier adds beyond that is the point, which no other surface\nhere draws.",
           "name": "HelixTourStop",
           "cssProperties": [
             {
@@ -130656,7 +130806,7 @@
           "helix": {
             "category": "overlays",
             "since": "0.1.0",
-            "status": "experimental",
+            "status": "stable",
             "documentation": "https://fusion.dev/helix/components/tour",
             "tier": "styled",
             "group": "Tour",

package/dist/color-picker/root/color-picker-root.css.js

@@ -275,6 +275,11 @@ cursor: not-allowed;
 opacity: 0.5;
 }
 
+:host([readonly]) [part="grid"],
+:host([readonly]) [part="swatch"] {
+cursor: default;
+}
+
 @media print {
 :host {
 box-shadow: none;

package/dist/outline/root/outline-root.d.ts

@@ -15,7 +15,7 @@ import type { CSSResultGroup } from 'lit';
  * and the document is not always where the headings are.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category navigation
  * @aliases Table of contents, On this page, Outline
  * @documentation https://fusion.dev/helix/components/outline

package/dist/rating/root/rating-root.css.js

@@ -4,6 +4,12 @@ export const styles = createSheet(`:host {
 --_rating-mark-size: var(--rating-size, var(--helix-size-icon-md));
 --_rating-mark-gap: var(--rating-gap, var(--helix-space-2xs));
 
+display: inline-flex;
+flex-direction: column;
+gap: var(--helix-space-2xs);
+}
+
+[part="field"] {
 align-items: center;
 display: inline-flex;
 gap: var(--rating-gap, var(--helix-space-xs));

package/dist/rating/root/rating-root.js

@@ -7,9 +7,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement } from '@fusion.dev/helix-core';
 import { HelixHeadlessRating } from '@fusion.dev/helix-headless/rating';
 import { property } from 'lit/decorators.js';
+import { styles as fieldStyles } from '../../shared/field/field.css.js';
+import { styles as fieldStackedStyles } from '../../shared/field/field-stacked.css.js';
 import { styles } from './rating-root.css.js';
 let HelixRating = class HelixRating extends HelixHeadlessRating {
-    static { this.styles = styles; }
+    static { this.styles = [fieldStyles, fieldStackedStyles, styles]; }
 };
 __decorate([
     property({ reflect: true })

package/dist/tabs/panel/tab-panel.d.ts

@@ -9,7 +9,7 @@ import type { CSSResultGroup } from 'lit';
  * quarter of it.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @documentation https://fusion.dev/helix/components/tabs
  *
  * @slot - The panel's content.

package/dist/tabs/root/tabs-root.d.ts

@@ -16,7 +16,7 @@ import type { CSSResultGroup } from 'lit';
  * box inside a sunken track.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category navigation
  * @documentation https://fusion.dev/helix/components/tabs
  *

package/dist/tabs/tab/tab.d.ts

@@ -10,7 +10,7 @@ import type { CSSResultGroup } from 'lit';
  * when it becomes current.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @documentation https://fusion.dev/helix/components/tabs
  *
  * @slot - The tab's label.

package/dist/tour/root/tour-root.d.ts

@@ -4,10 +4,12 @@ import type { CSSResultGroup } from 'lit';
  * @summary A guided run through an interface, one stop at a time.
  *
  * @description
- * The styled tier of `BaseTour`. It draws the light and nothing else.
+ * It draws the light and nothing else: the scrim's color and the lit box's
+ * corners are this tier's, and the order, the stops and the measuring stay
+ * below.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category overlays
  * @documentation https://fusion.dev/helix/components/tour
  *

package/dist/tour/stop/tour-stop.d.ts

@@ -5,11 +5,13 @@ import '../../button/index.js';
  * @summary One stop on a tour: what it points at, and a panel to say it in.
  *
  * @description
- * The styled tier of `BaseTourStop`. The panel is `Popover`'s panel by another
- * name, on purpose.
+ * The panel is `Popover`'s panel by another name, on purpose: a surface, an
+ * inset and a lift, so a stop and a flyout on the same page are the same
+ * object. What this tier adds beyond that is the point, which no other surface
+ * here draws.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category overlays
  * @documentation https://fusion.dev/helix/components/tour
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.47.1",
+  "version": "0.49.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -47,14 +47,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.47.1",
-    "@fusion.dev/helix-headless": "0.47.1",
-    "@fusion.dev/helix-styles": "0.47.1"
+    "@fusion.dev/helix-core": "0.49.0",
+    "@fusion.dev/helix-headless": "0.49.0",
+    "@fusion.dev/helix-styles": "0.49.0"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
-    "@fusion.dev/helix-cem": "0.47.1",
-    "@fusion.dev/helix-testing": "0.47.1",
+    "@fusion.dev/helix-cem": "0.49.0",
+    "@fusion.dev/helix-testing": "0.49.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",

package/types/jsx.d.ts

@@ -69,6 +69,7 @@ import type {
   HelixFilterMenu,
   HelixFilterOperator,
   HelixFlex,
+  HelixFormElement,
   HelixFormatDate,
   HelixGrid,
   HelixHeadlessFilterField,
@@ -4330,6 +4331,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.
@@ -4450,6 +4512,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"?: (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. */
+  "bool: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. */
+  "prop: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. */
+  "prop:required"?: (HelixColorPicker["required"]) | undefined;
   /** Colors offered under the picker, as a comma-separated list. */
   "prop:swatches"?: (HelixColorPicker["swatches"]) | undefined;
   /** Whether the control is non-interactive.
@@ -13917,7 +14040,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.
 
@@ -14057,7 +14214,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. */
   "prop:min"?: (HelixRating["min"]) | undefined;
   /** Whether this shows a score rather than asks for one.
 
@@ -24176,6 +24367,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.
    * - `disabled`: Whether the control is non-interactive.
    *
@@ -33211,6 +33442,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,
@@ -33368,14 +33633,15 @@ export type CustomElements = {
    * - `--rating-size`: How big one mark is. (default: `undefined`)
    * - `--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.
@@ -38466,7 +38732,9 @@ export type CustomElements = {
   >;
 
   /**
-   * The styled tier of `BaseTour`. It draws the light and nothing else.
+   * It draws the light and nothing else: the scrim's color and the lit box's
+   * corners are this tier's, and the order, the stops and the measuring stay
+   * below.
    *
    * ## Attributes & Properties
    *
@@ -38562,8 +38830,10 @@ export type CustomElements = {
   "helix-tour": Partial<HelixTourProps & BaseProps<HelixTour> & BaseEvents<HelixTour>>;
 
   /**
-   * The styled tier of `BaseTourStop`. The panel is `Popover`'s panel by another
-   * name, on purpose.
+   * The panel is `Popover`'s panel by another name, on purpose: a surface, an
+   * inset and a lift, so a stop and a flyout on the same page are the same
+   * object. What this tier adds beyond that is the point, which no other surface
+   * here draws.
    *
    * ## Attributes & Properties
    *
@@ -43564,6 +43834,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.
    * - `disabled`: Whether the control is non-interactive.
    *
@@ -52785,6 +53095,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,
@@ -52942,14 +53286,15 @@ export type CustomElementsSolidJs = {
    * - `--rating-size`: How big one mark is. (default: `undefined`)
    * - `--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.
@@ -58166,7 +58511,9 @@ export type CustomElementsSolidJs = {
   >;
 
   /**
-   * The styled tier of `BaseTour`. It draws the light and nothing else.
+   * It draws the light and nothing else: the scrim's color and the lit box's
+   * corners are this tier's, and the order, the stops and the measuring stay
+   * below.
    *
    * ## Attributes & Properties
    *
@@ -58264,8 +58611,10 @@ export type CustomElementsSolidJs = {
   >;
 
   /**
-   * The styled tier of `BaseTourStop`. The panel is `Popover`'s panel by another
-   * name, on purpose.
+   * The panel is `Popover`'s panel by another name, on purpose: a surface, an
+   * inset and a lift, so a stop and a flyout on the same page are the same
+   * object. What this tier adds beyond that is the point, which no other surface
+   * here draws.
    *
    * ## Attributes & Properties
    *
@@ -60207,9 +60556,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;

package/types/vue.d.ts

@@ -2258,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.
@@ -7152,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.
 
@@ -11207,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;
@@ -12290,13 +12385,13 @@ export interface WcToolkitVueGlobalComponents {
     HelixTooltipVueProps,
     HelixTooltipVueEvents
   >;
-  /** The styled tier of 'BaseTour'. It draws the light and nothing else. */
+  /** It draws the light and nothing else: the scrim's color and the lit box's corners are this tier's, and the order, the stops and the measuring stay below. */
   "helix-tour": DefineCustomElement<
     HelixTour,
     HelixTourVueProps,
     HelixTourVueEvents
   >;
-  /** The styled tier of 'BaseTourStop'. The panel is 'Popover''s panel by another name, on purpose. */
+  /** The panel is 'Popover''s panel by another name, on purpose: a surface, an inset and a lift, so a stop and a flyout on the same page are the same object. What this tier adds beyond that is the point, which no other surface here draws. */
   "helix-tour-stop": DefineCustomElement<
     HelixTourStop,
     HelixTourStopVueProps,