@kubex/zinc 1.1.76 → 1.1.78

package/docs/pages/components/preview-frame.md

@@ -56,7 +56,13 @@ handlers can't be cancelled from out here — blocking pointer input is the only
 way to stop them, and hover goes with it. Scrolling doesn't: an overflowing page
 is scrolled by the panel instead, as below.
 
-Set `interactive` when the embed is meant to be used rather than looked at.
+Set `interactive` when the embed is meant to be used rather than looked at. The
+frame then behaves as a viewport: it stays the panel's own height and the embed
+scrolls itself, so there's a single scrollbar and the embed's `100vh`,
+`position: fixed` and sticky content size to what's actually on screen. The
+[reported content height](#overflowing-content) is ignored while `interactive`
+is set — it exists to make an *inert* frame's overflow reachable, which an
+interactive one does for itself.
 
 ```html:preview
 <zn-preview-frame
@@ -73,11 +79,13 @@ Set `interactive` when the embed is meant to be used rather than looked at.
 
 ## Overflowing Content
 
-A page taller than the panel is scrolled by the panel, not inside the frame. The
-frame can't do it itself: a cross-origin document can't be scrolled from the host
-(`contentWindow.scrollTo` is blocked), and with pointer input off the wheel never
-reaches it anyway. So the frame is instead laid out at its full content height —
-nothing scrolls inside it — and the panel scrolls that.
+An inert page taller than the panel is scrolled by the panel, not inside the
+frame. The frame can't do it itself: a cross-origin document can't be scrolled
+from the host (`contentWindow.scrollTo` is blocked), and with pointer input off
+the wheel never reaches it anyway. So the frame is instead laid out at its full
+content height — nothing scrolls inside it — and the panel scrolls that. An
+[`interactive`](#interactivity) frame doesn't need any of this and opts out of
+it: it keeps the panel's height and the embed scrolls itself.
 
 For the frame to be sized that way, the embed reports its height alongside
 `hp-preview:rendered`:

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.
@@ -272,6 +329,8 @@ Available CSS custom properties:
 - `--symbol-color-active` - Color of filled/active symbols
 - `--symbol-size` - Size of the symbols
 - `--symbol-spacing` - Spacing between symbols
+- `--preview-color` - Color of the preview value (see [Preview](#preview))
+- `--preview-size` - Font size of the preview value
 
 ### Complete Example
 

package/docs/pages/components/theme-editor.md

@@ -24,6 +24,10 @@ Set `controls-caption` and `preview-caption` to label each column's header
 row — both are empty by default, rendering no text (the controls column's
 header row still renders either way, so the two columns stay aligned).
 
+The preview is [interactive](/components/preview-frame/#interactivity): the
+embedded page can be clicked and hovered, and it scrolls itself, so the preview
+column never adds a second scrollbar beside the embed's own.
+
 The preview always fills its column, leaving no dead space beneath it.
 `min-height` (default `480`) is a floor for that column, not a fixed height —
 it's still forwarded to the [preview frame](/components/preview-frame/), which

package/package.json

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

package/src/components/preview-frame/preview-frame.component.ts

@@ -111,6 +111,12 @@ export default class ZnPreviewFrame extends ZincElement {
    * be reached from here to cancel its own handlers, so this blocks pointer
    * input entirely — hover goes with it. Scrolling doesn't: an overflowing
    * page is scrolled by the panel rather than by the frame (see _contentHeight).
+   *
+   * Set, the frame becomes a real viewport instead: it stays the panel's own
+   * height and the embed scrolls itself, so there is one scrollbar rather than
+   * a panel scrolling an oversized frame, and the embed's viewport-relative
+   * layout (`100vh`, `position: fixed`, sticky headers) sizes to what's on
+   * screen. _contentHeight is ignored while this is set.
    */
   @property({type: Boolean, reflect: true}) interactive = false;
 
@@ -125,7 +131,8 @@ export default class ZnPreviewFrame extends ZincElement {
    * height rather than the panel's, so the page never scrolls inside the frame
    * — the panel scrolls instead, which is what makes an overflowing preview
    * reachable while pointer input to the frame is blocked. 0 = unknown, and the
-   * frame falls back to filling the panel.
+   * frame falls back to filling the panel. Kept up to date either way, but only
+   * laid out when the frame is inert: an `interactive` frame scrolls itself.
    */
   @state() private _contentHeight = 0;
 
@@ -396,7 +403,10 @@ export default class ZnPreviewFrame extends ZincElement {
     // transformed back down, so the frame fills the panel while the content
     // renders smaller and more of the page is visible. Percentage width means
     // nothing is measured — no layout feedback loop.
-    const content = this.error ? 0 : this._contentHeight;
+    // Growing the frame past the panel is the workaround for an inert frame not
+    // being scrollable; interactive, that trades one scrollbar for two and hands
+    // the embed a viewport taller than the panel it's shown in.
+    const content = this.error || this.interactive ? 0 : this._contentHeight;
     const iframeStyles = this.fill
       ? {width: '100%', height: content ? `max(${content}px, 100%)` : '100%'}
       : {

package/src/components/preview-frame/preview-frame.test.ts

@@ -683,6 +683,44 @@ describe('<zn-preview-frame>', () => {
       const stage = el.shadowRoot!.querySelector<HTMLDivElement>('.preview__stage')!;
       expect(stage.style.height).to.equal('max(1500px, 100%)');
     });
+
+    it('leaves an interactive frame at the panel height, so the embed scrolls itself', async () => {
+      const el = await fixture(html`
+        <zn-preview-frame
+          src="about:blank"
+          frame-origin="https://site.example"
+          data-uri="/payload"
+          fill
+          interactive></zn-preview-frame>`);
+
+      const iframe = el.shadowRoot!.querySelector('iframe')!;
+      const panel = el.shadowRoot!.querySelector<HTMLDivElement>('.preview')!;
+      const stage = el.shadowRoot!.querySelector<HTMLDivElement>('.preview__stage')!;
+
+      reportHeight(el, 1500);
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      expect(iframe.style.height).to.equal('100%');
+      expect(stage.style.height).to.equal('');
+      expect(panel.scrollHeight).to.equal(panel.clientHeight);
+    });
+
+    it('inflates the frame again when interactive is turned off', async () => {
+      const el = await fixture(html`
+        <zn-preview-frame
+          src="about:blank"
+          frame-origin="https://site.example"
+          data-uri="/payload"
+          interactive></zn-preview-frame>`) as HTMLElement & {interactive: boolean};
+      const iframe = el.shadowRoot!.querySelector('iframe')!;
+
+      reportHeight(el, 1400);
+      await new Promise(resolve => setTimeout(resolve, 50));
+      expect(iframe.style.height).to.equal('480px');
+
+      el.interactive = false;
+      await waitUntil(() => iframe.style.height === '1400px', 'kept the reported height unused');
+    });
   });
 
   it('skips the config fetch when data-uri is empty', async () => {

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,17 @@ export default class ZnRating extends ZincElement implements ZincFormControl {
   }
 
   private _getValueFromXCoordinate(coordinate: number): number {
-    const {left, width} = this.rating.getBoundingClientRect();
+    const {left, width} = this.symbols.getBoundingClientRect();
     const value = this._roundToPrecision(((coordinate - left) / width) * this.max, 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 +172,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 +191,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;
+  --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;
 
@@ -62,6 +66,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 +91,11 @@
     scale: none;
   }
 
+  &--disabled &__preview--hover,
+  &--readonly &__preview--hover {
+    color: var(--preview-color);
+  }
+
   &--disabled {
     opacity: 0.5;
   }

package/src/components/theme-editor/theme-editor.component.ts

@@ -840,12 +840,14 @@ export default class ZnThemeEditor extends ZincElement {
                 <slot @slotchange="${this._onSlotChange}"></slot>
                 ${this._hasNestedGroups()
                   ? this._renderTabs(section => html`
-                      ${this._hasAssignedControls(section.name) ? html`
-                        <slot name="${section.name}" class="editor__section-slot" @slotchange="${this._onSlotChange}"></slot>` : nothing}
-                      ${this._renderGroups(section)}`)
+                    ${this._hasAssignedControls(section.name) ? html`
+                      <slot name="${section.name}" class="editor__section-slot"
+                            @slotchange="${this._onSlotChange}"></slot>` : nothing}
+                    ${this._renderGroups(section)}`)
                   : this.sectionLayout === 'tabs'
                     ? this._renderTabs(section => html`
-                        <slot name="${section.name}" class="editor__section-slot" @slotchange="${this._onSlotChange}"></slot>`)
+                      <slot name="${section.name}" class="editor__section-slot"
+                            @slotchange="${this._onSlotChange}"></slot>`)
                     : this._renderSections()}
               </div>
               ${this.hasSlotController.test('footer') ? html`
@@ -910,6 +912,7 @@ export default class ZnThemeEditor extends ZincElement {
               device="${this.device}"
               min-height="${this.minHeight}"
               fill
+              interactive
               backdrop="${this.standalone ? 'panel' : 'dots'}"
               exportparts="base:preview__base,stage:preview__stage,iframe:preview__iframe,error:preview__error"
               @zn-error="${this._onFrameError}"></zn-preview-frame>

package/src/components/theme-editor/theme-editor.scss

@@ -180,9 +180,11 @@
   margin-top: auto;
 }
 
-// The preview's scroll region: the toolbar above stays put.
+// Holds the preview below the toolbar, and never scrolls: the frame is its own
+// scroll region (interactive, the embed is), so a scroller here would only ever
+// be a second scrollbar beside that one.
 .editor__preview {
-  overflow: auto;
+  overflow: hidden;
   flex: 1 1 auto;
   min-width: 0;
   min-height: 0;

package/src/components/theme-editor/theme-editor.test.ts

@@ -729,6 +729,22 @@ describe('<zn-theme-editor>', () => {
       expect(controlsHeader).to.exist;
       expect(controlsHeader!.textContent?.trim()).to.equal('');
     });
+
+    it('gives the preview an interactive frame that scrolls itself, so the column never adds a second scrollbar', async () => {
+      const el = await fixture(FIXTURE);
+      await (el as HTMLElement & {updateComplete: Promise<unknown>}).updateComplete;
+
+      const preview = el.shadowRoot!.querySelector<HTMLElement>('[part="preview"]')!;
+      const frame = el.shadowRoot!.querySelector<HTMLElement>('zn-preview-frame')!;
+      await (frame as HTMLElement & {updateComplete: Promise<unknown>}).updateComplete;
+
+      expect(frame.hasAttribute('interactive')).to.equal(true);
+      expect(getComputedStyle(preview).overflowY).to.equal('hidden');
+      expect(preview.scrollHeight).to.equal(preview.clientHeight);
+
+      const iframe = frame.shadowRoot!.querySelector('iframe')!;
+      expect(getComputedStyle(iframe).pointerEvents).to.equal('auto');
+    });
   });
 
   describe('tabbed sections (section-layout="tabs")', () => {