@fusion.dev/helix-headless 0.47.1 → 0.49.0

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

@@ -29,6 +29,7 @@ declare const HelixHeadlessRating_base: (new (...args: any[]) => import("@fusion
  * @event {Event} input - Announced once the value has moved.
  *
  * @csspart feedback - What is wrong with it.
+ * @csspart field - The row: the marks, and the score beside them.
  * @csspart fill - The filled marks, clipped to the score.
  * @csspart hint - Help under the marks, while nothing is wrong.
  * @csspart label - The question, over the marks.
@@ -40,8 +41,8 @@ declare const HelixHeadlessRating_base: (new (...args: any[]) => import("@fusion
  *
  * @cssproperty --rating-full - How many marks are wholly filled.
  * @cssproperty --rating-part - How much of the next mark is filled, 0 to 1.
- * @cssproperty --rating-step - The width of one step, as a fraction of a mark.
- * @cssproperty --rating-steps - How many steps one mark is divided into.
+ * @cssproperty --rating-step - Which step along the row a target is, counting from one, whatever `min` leaves open.
+ * @cssproperty --rating-steps - How many steps the whole row holds, which is `max` over `step`.
  *
  * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
  */
@@ -58,6 +59,40 @@ export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
      * 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.
      */
     min: number;
     /**
@@ -120,9 +155,28 @@ export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
      */
     private previewing;
     protected readonly keys: KeyboardNavigationController;
+    /**
+     * The floor the row actually uses, which is `min` where `min` is one.
+     *
+     * Between zero and `max`, and zero for anything that is not a number, per
+     * the note on `min`. Derived on read rather than corrected into the property,
+     * so `rating.min` still reports what the consumer set and the warning below
+     * can tell the two apart.
+     */
+    private get floor();
     /** The score, as a number, clamped to what the marks can show. */
     get score(): number;
-    /** Every score a reader can choose, which is `max / step` of them. */
+    /**
+     * Every score the marks can show, which is `max / step` of them.
+     *
+     * The whole row rather than the part `min` leaves open, because this is what
+     * the stylesheet lays the targets out against: `--rating-steps` is the pitch
+     * and a step's own place in this list is where it sits along the row. Counted
+     * from the part a reader can press instead, a floor above zero would widen
+     * every target and slide the row left.
+     */
+    private get positions();
+    /** Every score a reader can choose, which is the positions `min` leaves open. */
     private get steps();
     /**
      * The options, as the shared controller wants them.
@@ -182,10 +236,12 @@ export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
      * form holding an unrated required rating submits, `:valid` true and the
      * entry present but empty. `reportRequired` is what makes the property real.
      *
-     * **Empty is `value === ''` rather than a score of zero**, because zero is a
-     * rating a reader can deliberately give when `min` allows it, and refusing to
-     * submit it would be the control disagreeing with the property that permits
-     * it. What `required` asks is whether they answered at all.
+     * **Empty is `value === ''` rather than a score at the floor**, and the two
+     * are not the same thing: an unanswered row draws `min`, per the note on that
+     * property, so a control that read its own picture would call every rating
+     * with `min="2"` answered the moment it rendered. What `required` asks is
+     * whether the reader answered at all, which only the value knows. A consumer
+     * who writes `value="0"` has answered, and is not refused.
      *
      * `Slider` is deliberately not given the same treatment: a native
      * `<input type="range" required>` is always valid, because a range always
@@ -197,6 +253,8 @@ export declare class HelixHeadlessRating extends HelixHeadlessRating_base {
     private readonly handleLeave;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** Whether the console has already been told about a `min` off the scale. */
+    private warned;
     protected updated(changed: PropertyValues): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;

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

@@ -89,18 +89,28 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
         this.handleLeave = () => {
             this.previewing = undefined;
         };
+        this.warned = false;
+    }
+    get floor() {
+        if (!Number.isFinite(this.min)) {
+            return 0;
+        }
+        return Math.min(Math.max(this.min, 0), Math.max(this.max, 0));
     }
     get score() {
         const parsed = Number.parseFloat(this.value);
         if (!Number.isFinite(parsed)) {
-            return 0;
+            return this.floor;
         }
-        return Math.min(Math.max(parsed, 0), this.max);
+        return Math.min(Math.max(parsed, this.floor), this.max);
     }
-    get steps() {
+    get positions() {
         const count = Math.max(1, Math.round(this.max / this.step));
         return Array.from({ length: count }, (_, index) => Number(((index + 1) * this.step).toFixed(2)));
     }
+    get steps() {
+        return this.positions.filter((score) => score >= this.floor);
+    }
     get options() {
         const found = [...(this.renderRoot?.querySelectorAll('[part="option"]') ?? [])];
         return found.map((element) => ({
@@ -157,6 +167,12 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
     updated(changed) {
         super.updated?.(changed);
         this.sync();
+        if (this.floor !== this.min && !this.warned) {
+            this.warned = true;
+            console.warn(`<${this.localName}> has min="${this.min}", which is not a score between 0 and its max of ` +
+                `${this.max}, so the lowest score it offers is ${this.floor}. Put min inside the marks, ` +
+                'or move max.');
+        }
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -177,12 +193,16 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
         const first = this.steps[0];
         const mark = (layer, index) => html `<span part="mark">${this.markFor(layer, index)}</span>`;
         const marksIn = (layer) => Array.from({ length: count }, (_, index) => mark(layer, index));
-        return html `<div
+        return html `${this.renderGroupLabel()}
+    <div part="field">
+    <div
       part="marks"
       role=${this.readOnly ? 'img' : 'radiogroup'}
       aria-label=${this.readOnly ? said : this.label || nothing}
+      aria-describedby=${this.describedBy ?? nothing}
+      aria-required=${this.required && !this.readOnly ? 'true' : nothing}
       data-slotted=${this.markSource ? '' : nothing}
-      style=${`--rating-full: ${Math.floor(showing)}; --rating-part: ${showing - Math.floor(showing)}; --rating-steps: ${this.steps.length}`}
+      style=${`--rating-full: ${Math.floor(showing)}; --rating-part: ${showing - Math.floor(showing)}; --rating-steps: ${this.positions.length}`}
       @pointercancel=${this.handleDragCancel}
       @pointerdown=${this.handleDragStart}
       @pointermove=${this.handleDragMove}
@@ -207,7 +227,10 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
       >
       ${this.readOnly
             ? nothing
-            : this.steps.map((score, index) => html `<button
+            :
+                this.positions.map((score, index) => score < this.floor
+                    ? nothing
+                    : html `<button
                 part="option"
                 role="radio"
                 type="button"
@@ -216,7 +239,9 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
                 data-score=${String(score)}
                 style=${`--rating-step: ${index + 1}`}
                 ?disabled=${this.isDisabled}
-                tabindex=${this.score === score || (this.score === 0 && score === first) ? '0' : '-1'}
+                tabindex=${this.score === score || (this.score === this.floor && score === first)
+                        ? '0'
+                        : '-1'}
                 @click=${this.handleOptionClick}
                 @pointerenter=${this.handleOptionEnter}
               ></button>`)}
@@ -227,7 +252,9 @@ let HelixHeadlessRating = class HelixHeadlessRating extends MixinControllerValue
           aria-hidden="true"
           >${showing}</span
         >`
-            : nothing}`;
+            : nothing}
+    </div>
+    ${this.renderHint()}${this.renderFeedback()}`;
     }
     get valueAsNumber() {
         return asNumber(this.value);

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

@@ -9,7 +9,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * server's markup for a crawler regardless of which tab is open.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @aliases TabPanel
  * @documentation https://fusion.dev/helix/components/tabs
  *

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

@@ -16,7 +16,7 @@ declare const HelixHeadlessTabs_base: (new (...args: any[]) => import("@fusion.d
  * showing a panel is cheap; a set where it is not should use `manual`.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category navigation
  * @aliases TabList, Segmented control
  * @documentation https://fusion.dev/helix/components/tabs

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

@@ -12,7 +12,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * `aria-controls` pointing at nothing is worse than not being there.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @aliases Tab
  * @documentation https://fusion.dev/helix/components/tabs
  *

package/dist/time-picker/root/time-picker-root.d.ts

@@ -43,6 +43,19 @@ declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fu
  * 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.
+ *
  * @since 0.1.0
  * @status experimental
  * @category forms

package/dist/time-picker/root/time-picker-root.js

@@ -248,6 +248,7 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
               label: option-label, text: option-text"
             value=${one}
             ?disabled=${barred(one)}
+            ?selected=${one === value}
             >${written(one)}</${this.tag('option')}
           >`)}
     </${this.tag('listbox')}>`;
@@ -291,6 +292,7 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
             label: option-label, text: option-text"
           value=${at}
           ?disabled=${this.barred(at)}
+          ?selected=${this.held.includes(at)}
           data-between=${between ? '' : nothing}
           >${writeTime(at, this.locale)}</${this.tag('option')}
         >`;

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

@@ -20,7 +20,7 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  * nothing needs to be: a tour starts when a reader asks for it.
  *
  * @since 0.1.0
- * @status experimental
+ * @status stable
  * @category overlays
  * @aliases Coachmark, Product tour, Walkthrough, Onboarding
  * @documentation https://fusion.dev/helix/components/tour

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

@@ -35,7 +35,7 @@ import '../../button/index.js';
  * tree points at a target in that tree.
  *
  * @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-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.47.1",
+  "version": "0.49.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,14 +46,14 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.47.1",
-    "@fusion.dev/helix-icons": "0.47.1",
+    "@fusion.dev/helix-core": "0.49.0",
+    "@fusion.dev/helix-icons": "0.49.0",
     "uqr": "^0.1.3"
   },
   "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",