@kubex/zinc 1.1.77 → 1.1.79

package/docs/pages/components/rating.md

@@ -74,6 +74,29 @@ Use the `disabled` attribute to disable the rating component.
 <zn-rating value="3" disabled label="Rating disabled with value"></zn-rating>
 ```
 
+### Help Text
+
+Add descriptive help text to a rating with the `help-text` attribute. For help text that contains HTML, use the
+`help-text` slot instead.
+
+```html:preview
+<zn-rating label="Rate this product" help-text="Select a star to rate this product."></zn-rating>
+<br />
+<zn-rating value="3" precision="0.5" label="Overall rating">
+  <div slot="help-text">Ratings are <strong>public</strong> and can be changed at any time.</div>
+</zn-rating>
+```
+
+Help text is styled to match [Input](/components/input) and follows the `size` attribute.
+
+```html:preview
+<zn-rating size="small" value="3" help-text="Small help text"></zn-rating>
+<br />
+<zn-rating size="medium" value="3" help-text="Medium help text"></zn-rating>
+<br />
+<zn-rating size="large" value="3" help-text="Large help text"></zn-rating>
+```
+
 ### Sizes
 
 Use the `size` attribute to change the rating size. Available sizes are `small`, `medium` (default), and `large`.
@@ -116,6 +139,40 @@ The rating component displays hover effects by default, scaling the hovered star
 **Usage:** Hover effects provide visual feedback to help users understand which rating they will select. The hover effect is automatically disabled for `readonly` and `disabled` ratings.
 :::
 
+### Preview
+
+Use the `preview` attribute to show the value next to the symbols. While the pointer moves across the symbols the
+preview follows it, so the value being selected is visible before it is committed. Once the pointer leaves, the preview
+falls back to the selected value.
+
+```html:preview
+<zn-rating preview label="Rate this product"></zn-rating>
+<br />
+<zn-rating preview value="2.5" precision="0.5" label="Half star precision"></zn-rating>
+<br />
+<zn-rating preview value="3.75" precision="0.25" max="10" size="large" label="Quarter star precision"></zn-rating>
+```
+
+The preview is formatted to match `precision`, so a rating with `precision="0.5"` previews `4.5` rather than `4`.
+It also works with `readonly` and `disabled` ratings, where it simply displays the current value.
+
+```html:preview
+<zn-rating preview value="4.5" precision="0.5" readonly label="Average rating"></zn-rating>
+<br />
+<zn-rating preview value="3" disabled label="Rating disabled"></zn-rating>
+```
+
+Style the preview with the `--preview-color` and `--preview-size` custom properties, or the `preview` part.
+
+```html:preview
+<zn-rating
+  preview
+  value="4"
+  label="Custom preview styling"
+  style="--preview-color: #3B82F6; --preview-size: 1.25rem;"
+></zn-rating>
+```
+
 ### Form Integration
 
 Ratings work seamlessly with forms and will be submitted with form data using the `name` attribute.
@@ -271,7 +328,10 @@ Available CSS custom properties:
 - `--symbol-color` - Color of unfilled symbols
 - `--symbol-color-active` - Color of filled/active symbols
 - `--symbol-size` - Size of the symbols
-- `--symbol-spacing` - Spacing between symbols
+- `--symbol-spacing` - Gap between symbols. The rating adds no padding of its own, so the first symbol sits flush with
+  the component's edge and lines up with other form controls.
+- `--preview-color` - Color of the preview value (see [Preview](#preview))
+- `--preview-size` - Font size of the preview value
 
 ### Complete Example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.1.77",
+  "version": "1.1.79",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",

package/src/components/rating/rating.component.ts

@@ -1,6 +1,7 @@
 import {classMap} from "lit/directives/class-map.js";
 import {type CSSResultGroup, html, unsafeCSS} from 'lit';
 import {FormControlController, validValidityState} from "../../internal/form";
+import {HasSlotController} from "../../internal/slot";
 import {property, query, state} from 'lit/decorators.js';
 import {styleMap} from 'lit/directives/style-map.js';
 import {unsafeHTML} from "lit/directives/unsafe-html.js";
@@ -22,10 +23,16 @@ import styles from './rating.scss';
  *
  * @slot - The default slot.
  * @slot example - An example slot.
+ * @slot help-text - Text that describes how to use the rating. Alternatively, you can use the `help-text` attribute.
  *
+ * @csspart form-control - The form control that wraps the symbols and help text.
+ * @csspart form-control-help-text - The help text's wrapper.
  * @csspart base - The component's base wrapper.
+ * @csspart preview - The value shown next to the symbols when `preview` is enabled.
  *
  * @cssproperty --example - An example CSS custom property.
+ * @cssproperty --preview-color - The color of the preview value.
+ * @cssproperty --preview-size - The font size of the preview value.
  */
 export default class ZnRating extends ZincElement implements ZincFormControl {
   static styles: CSSResultGroup = unsafeCSS(styles);
@@ -34,14 +41,21 @@ export default class ZnRating extends ZincElement implements ZincFormControl {
     assumeInteractionOn: ['zn-blur', 'zn-input']
   });
 
+  private readonly hasSlotController = new HasSlotController(this, 'help-text');
+
   @query('.rating') rating: HTMLElement;
 
+  @query('.rating__symbols') symbols: HTMLElement;
+
   @state() private hoverValue: number = 0;
 
   @state() private isHovering: boolean = false;
 
   @property() label: string;
 
+  /** The rating's help text. If you need to display HTML, use the `help-text` slot instead. */
+  @property({attribute: 'help-text'}) helpText: string = '';
+
   @property() name: string;
 
   @property({type: Number}) value: number = 0;
@@ -54,6 +68,9 @@ export default class ZnRating extends ZincElement implements ZincFormControl {
 
   @property({type: Boolean}) disabled: boolean = false;
 
+  /** Displays the value alongside the symbols, updating live as the pointer moves across them. */
+  @property({type: Boolean}) preview: boolean = false;
+
   @property({}) size: 'small' | 'medium' | 'large' = 'medium';
 
   @property() getSymbol: (value: number) => string = () => '<zn-icon src="star" library="material"></zn-icon>';
@@ -94,12 +111,26 @@ export default class ZnRating extends ZincElement implements ZincFormControl {
   }
 
   private _getValueFromXCoordinate(coordinate: number): number {
-    const {left, width} = this.rating.getBoundingClientRect();
-    const value = this._roundToPrecision(((coordinate - left) / width) * this.max, this.precision);
+    const {left, width} = this.symbols.getBoundingClientRect();
+    // Symbols are spaced with a gap rather than padding, so the symbols only cover part of the
+    // container and a plain width-to-value ratio would skew fractions within each symbol.
+    const gap = parseFloat(getComputedStyle(this.symbols).columnGap) || 0;
+    const symbolWidth = (width - gap * (this.max - 1)) / this.max;
+    const stride = symbolWidth + gap;
+    const position = Math.min(Math.max(coordinate - left, 0), width);
+    const index = Math.min(Math.floor(position / stride), this.max - 1);
+    // Landing in a gap reads as the preceding symbol being complete.
+    const fraction = Math.min((position - index * stride) / symbolWidth, 1);
+    const value = this._roundToPrecision(index + fraction, this.precision);
 
     return Math.min(Math.max(value, 0), this.max);
   }
 
+  private _formatValue(value: number): string {
+    const decimals = String(this.precision).split('.')[1]?.length ?? 0;
+    return value.toFixed(decimals);
+  }
+
   private _getValueFromMousePosition(event: MouseEvent): number {
     return this._getValueFromXCoordinate(event.clientX);
   }
@@ -150,13 +181,15 @@ export default class ZnRating extends ZincElement implements ZincFormControl {
 
   private _handleTouchEnd(event: TouchEvent) {
     this.isHovering = false;
-    this._setValue(this._getValueFromTouchPosition(event));
+    // `touches` is empty once the finger lifts, so the final position lives in `changedTouches`.
+    this._setValue(this._getValueFromXCoordinate(event.changedTouches[0].clientX));
 
     event.preventDefault();
   }
 
   render() {
     const counter = Array.from(Array(this.max).keys());
+    const hasHelpText = this.helpText ? true : this.hasSlotController.test('help-text');
     let displayValue = 0;
 
     if (this.disabled || this.readonly) {
@@ -167,69 +200,102 @@ export default class ZnRating extends ZincElement implements ZincFormControl {
 
     return html`
       <div
-        part="base"
+        part="form-control"
         class="${classMap({
-          rating: true,
-          'rating--readonly': this.readonly,
-          'rating--disabled': this.disabled,
-          'rating--small': this.size === 'small',
-          'rating--medium': this.size === 'medium',
-          'rating--large': this.size === 'large'
-        })}"
-        role="slider"
-        aria-label="${this.label}"
-        aria-disabled="${this.disabled ? 'true' : 'false'}"
-        aria-readonly="${this.readonly ? 'true' : 'false'}"
-        aria-valuenow="${this.value}"
-        aria-valuemin="0"
-        aria-valuemax="${this.max}"
-        @click="${this._handleClick}"
-        @mouseenter="${this._handleMouseEnter}"
-        @mousemove="${this._handleMouseMove}"
-        @mouseleave="${this._handleMouseLeave}"
-        @touchstart="${this._handleTouchStart}"
-        @touchmove="${this._handleTouchMove}"
-        @touceend="${this._handleTouchEnd}"
-      >
-        <span class="rating__symbols">
-          ${counter.map(index => {
-            if (displayValue > index && displayValue < index + 1) {
+          'form-control': true,
+          'form-control--small': this.size === 'small',
+          'form-control--medium': this.size === 'medium',
+          'form-control--large': this.size === 'large',
+          'form-control--has-help-text': hasHelpText
+        })}">
+        <div
+          part="base"
+          class="${classMap({
+            rating: true,
+            'rating--readonly': this.readonly,
+            'rating--disabled': this.disabled,
+            'rating--small': this.size === 'small',
+            'rating--medium': this.size === 'medium',
+            'rating--large': this.size === 'large'
+          })}"
+          role="slider"
+          aria-label="${this.label}"
+          aria-describedby="help-text"
+          aria-disabled="${this.disabled ? 'true' : 'false'}"
+          aria-readonly="${this.readonly ? 'true' : 'false'}"
+          aria-valuenow="${this.value}"
+          aria-valuemin="0"
+          aria-valuemax="${this.max}"
+        >
+          <span
+            class="rating__symbols"
+            @click="${this._handleClick}"
+            @mouseenter="${this._handleMouseEnter}"
+            @mousemove="${this._handleMouseMove}"
+            @mouseleave="${this._handleMouseLeave}"
+            @touchstart="${this._handleTouchStart}"
+            @touchmove="${this._handleTouchMove}"
+            @touchend="${this._handleTouchEnd}"
+          >
+            ${counter.map(index => {
+              if (displayValue > index && displayValue < index + 1) {
+                return html`
+                  <span
+                    class=${classMap({
+                      rating__symbol: true,
+                      'rating__partial-symbol-container': true,
+                      'rating__symbol--hover': this.isHovering && Math.ceil(displayValue) === index + 1
+                    })}
+                    role="presentation">
+                    <div
+                      style=${styleMap({
+                        clipPath: `inset(0 0 0 ${(displayValue - index) * 100}%)`
+                      })}>
+                      ${unsafeHTML(this.getSymbol(index + 1))}
+                    </div>
+                    <div
+                      class="rating__partial--filled"
+                      style=${styleMap({
+                        clipPath: `inset(0 ${100 - (displayValue - index) * 100}% 0 0)`
+                      })}>
+                      ${unsafeHTML(this.getSymbol(index + 1))}
+                    </div>
+                  </span>
+                `;
+              }
               return html`
                 <span
                   class=${classMap({
                     rating__symbol: true,
-                    'rating__partial-symbol-container': true,
-                    'rating__symbol--hover': this.isHovering && Math.ceil(displayValue) === index + 1
+                    'rating__symbol--hover': this.isHovering && Math.ceil(displayValue) === index + 1,
+                    'rating__symbol--active': displayValue >= index + 1
                   })}
                   role="presentation">
-                  <div
-                    style=${styleMap({
-                      clipPath: `inset(0 0 0 ${(displayValue - index) * 100}%)`
-                    })}>
-                    ${unsafeHTML(this.getSymbol(index + 1))}
-                  </div>
-                  <div
-                    class="rating__partial--filled"
-                    style=${styleMap({
-                      clipPath: `inset(0 ${100 - (displayValue - index) * 100}% 0 0)`
-                    })}>
-                    ${unsafeHTML(this.getSymbol(index + 1))}
-                  </div>
-                </span>
-              `;
-            }
-            return html`
+                  ${unsafeHTML(this.getSymbol(index + 1))}
+                </span>`;
+            })}
+          </span>
+          ${this.preview
+            ? html`
               <span
+                part="preview"
                 class=${classMap({
-                  rating__symbol: true,
-                  'rating__symbol--hover': this.isHovering && Math.ceil(displayValue) === index + 1,
-                  'rating__symbol--active': displayValue >= index + 1
+                  rating__preview: true,
+                  'rating__preview--hover': this.isHovering
                 })}
-                role="presentation">
-                ${unsafeHTML(this.getSymbol(index + 1))}
-              </span>`;
-          })}
-        </span>
+                aria-hidden="true">
+                ${this._formatValue(displayValue)}
+              </span>`
+            : ''}
+        </div>
+
+        <div
+          part="form-control-help-text"
+          id="help-text"
+          class="form-control__help-text"
+          aria-hidden=${hasHelpText ? 'false' : 'true'}>
+          <slot name="help-text">${this.helpText}</slot>
+        </div>
       </div>
     `;
   }

package/src/components/rating/rating.scss

@@ -1,10 +1,13 @@
 @use "../../wc";
+@use "../../form-control";
 
 :host {
   --symbol-color: rgb(var(--zn-border-color));
   --symbol-color-active: var(--zn-color-amber-400);
   --symbol-size: 1.2rem;
-  --symbol-spacing: 4px;
+  --symbol-spacing: var(--zn-spacing-x-small);
+  --preview-color: rgb(var(--zn-text));
+  --preview-size: 0.875rem;
 
   display: block;
 }
@@ -12,6 +15,7 @@
 .rating {
   position: relative;
   display: inline-flex;
+  align-items: center;
   border-radius: var(--zn-border-radius);
   vertical-align: middle;
 
@@ -27,15 +31,12 @@
   &__symbols {
     display: inline-flex;
     position: relative;
+    gap: var(--symbol-spacing);
     font-size: var(--symbol-size);
     line-height: 0;
     color: var(--symbol-color);
     white-space: nowrap;
     cursor: pointer;
-
-    > * {
-      padding: var(--symbol-spacing);
-    }
   }
 
   &__symbol--active,
@@ -49,8 +50,8 @@
 
   &__partial--filled {
     position: absolute;
-    top: var(--symbol-spacing);
-    left: var(--symbol-spacing);
+    top: 0;
+    left: 0;
   }
 
   &__symbol {
@@ -62,6 +63,21 @@
     }
   }
 
+  &__preview {
+    margin-left: var(--symbol-spacing);
+    font-size: var(--preview-size);
+    font-weight: var(--zn-font-weight-semibold);
+    line-height: 1;
+    color: var(--preview-color);
+    font-variant-numeric: tabular-nums;
+    pointer-events: none;
+    user-select: none;
+
+    &--hover {
+      color: var(--symbol-color-active);
+    }
+  }
+
   &--disabled &__symbols,
   &--readonly &__symbols {
     cursor: default;
@@ -72,6 +88,11 @@
     scale: none;
   }
 
+  &--disabled &__preview--hover,
+  &--readonly &__preview--hover {
+    color: var(--preview-color);
+  }
+
   &--disabled {
     opacity: 0.5;
   }
@@ -82,7 +103,7 @@
 
   &--small {
     --symbol-size: 1rem;
-    --symbol-spacing: 2px;
+    --symbol-spacing: var(--zn-spacing-2x-small);
   }
 
   &--medium {
@@ -91,6 +112,6 @@
 
   &--large {
     --symbol-size: 1.5rem;
-    --symbol-spacing: 6px;
+    --symbol-spacing: 12px;
   }
 }