@eunomia/elements 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/components/form/rating/rating.js

@@ -0,0 +1,665 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, property, query, state } from "lit/decorators.js";
+import { html, LitElement, nothing } from "lit";
+import { classMap } from "lit/directives/class-map.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { live } from "lit/directives/live.js";
+import { styleMap } from "lit/directives/style-map.js";
+import { DisabledMixin, } from "../../../mixins/disabled.mixin.js";
+import { ReadonlyMixin, } from "../../../mixins/readonly.mixin.js";
+import { ValidatorsMixin, } from "../../../mixins/validators.mixin.js";
+import { FormMixin } from "../../../mixins/form.mixin.js";
+import { FormLabelMixin, } from "../../../mixins/form-label.mixin.js";
+import { LocalizableMixin, } from "../../../mixins/localizable.mixin.js";
+import { getDefaultLocale } from "../../../i18n/index.js";
+import { ChangeEvent } from "../../../events/change.event.js";
+import { formLabelsStyles } from "../shared-styles/form-labels.styles.js";
+import { ratingStyles } from "./rating.styles.js";
+/**
+ * Tag name of the rating component.
+ */
+export const EunomiaRatingTagName = "eun-rating";
+/**
+ * Base class with composed mixins used to handle component extends elements type.
+ * @internal
+ */
+const Base = DisabledMixin(ValidatorsMixin(LitElement));
+const EunomiaRatingMixinBase = LocalizableMixin(FormLabelMixin(ReadonlyMixin(FormMixin(Base))));
+/**
+ * A rating shown as a row of icons, stars by default, that someone fills to
+ * give a score, or that simply displays one, such as a product's average
+ * review.
+ *
+ * Picking a score renders one native radio button per possible value,
+ * grouped in a radio group, so assistive technology announces each option
+ * as "3 out of 5", and the field takes part in forms like every other one.
+ * With displayOnly, the icons are rendered as a single image whose
+ * accessible name reads the score, such as "Rating: 4.5 out of 5".
+ *
+ * @slot [label] - Custom label content, falling back to the label property. Not rendered while displayOnly is set
+ * @slot [instructions] - Custom instructions content, falling back to the instructions property. Not rendered while displayOnly is set
+ * @prop {string} label - The title label of the field. While displayOnly is set, it isn't shown and starts the accessible name instead
+ * @prop {string} instructions - Instructions displayed below the label
+ * @prop {string} name - The field name
+ * @prop {number} value - The current rating. Empty when nothing is picked yet
+ * @prop {number} defaultValue - The rating applied when the field connects, and restored on form reset
+ * @attr {number} [default-value] - The rating applied when the field connects, and restored on form reset
+ * @prop {number} [max=5] - The number of icons, which is also the highest rating
+ * @prop {1 | 0.5} [step=1] - Whether a rating is picked by whole icons or by halves
+ * @prop {boolean} [displayOnly=false] - Only displays the rating, which can then be any decimal value, such as an average
+ * @attr {boolean} [display-only=false] - Only displays the rating, which can then be any decimal value, such as an average
+ * @prop {boolean} [clearable=false] - Shows a button that removes the rating, once one is picked
+ * @prop {string} [clearLabel] - The accessible label of the clear button. Defaults to the localized string for the current locale (English: "Clear rating")
+ * @attr {string} [clear-label] - The accessible label of the clear button
+ * @prop {import('../../content/icon/icon.type.js').EunomiaIconName} [icon='star'] - The icon drawn for the filled part of the rating
+ * @prop {import('../../content/icon/icon.type.js').EunomiaIconName} [emptyIcon='star_border'] - The icon drawn for the empty part of the rating. Keep its shape different from icon, so the rating doesn't rely on color alone
+ * @attr {import('../../content/icon/icon.type.js').EunomiaIconName} [empty-icon='star_border'] - The icon drawn for the empty part of the rating
+ * @prop {string} [locale] - The language of the accessible labels and of the decimal separator. Defaults to the shared default locale
+ * @prop {boolean} [disabled=false] - Whether the field is disabled
+ * @prop {boolean} [readonly=false] - Whether the field is read only
+ * @prop {boolean} [required=false] - Whether a rating must be picked
+ * @prop {boolean} [hideError=false] - Whether the errors are hidden. The hint stays visible
+ * @attr {boolean} [hide-error=false] - Whether the errors are hidden. The hint stays visible
+ * @prop {boolean} [invalid=false] - Shows the field as invalid without any message, for an error displayed elsewhere
+ * @prop {string} [error] - An error computed outside the field, by the form or by the server. While set, the field is invalid and shows this message right away
+ * @prop {string} hint - A short message displayed under the field
+ * @prop {Array<import('../../../types/form-validators.type.js').Validators<number | undefined>>} validators - The list of validation rules applied to the rating
+ * @fires {ChangeEvent} eunchange - Fired whenever the rating is picked, changed or cleared
+ * @cssprop [--rating-size] - Sets the width and height of each icon
+ * @cssprop [--rating-gap] - Sets the space between two icons
+ * @cssprop [--rating-color] - Sets the color of the filled icons
+ * @cssprop [--rating-empty-color] - Sets the color of the empty icons
+ * @cssprop [--rating-error-color] - Sets the color of the error message, and of the empty icons while in error
+ * @cssprop [--rating-hint-color] - Sets the color of the hint message
+ * @cssprop [--rating-focus-outline-color] - Sets the color of the focus outline drawn around the focused icon and the clear button
+ * @cssprop [--field-label-font-size] - Sets the font size of the label
+ * @cssprop [--field-message-font-size] - Sets the font size of the hint, error messages and instructions
+ * @element eun-rating
+ */
+let EunomiaRating = class EunomiaRating extends EunomiaRatingMixinBase {
+    constructor() {
+        super(...arguments);
+        /**
+         * Every change is a complete choice, so its error shows right away.
+         * @internal
+         */
+        this.errorOnChange = true;
+        /**
+         * The number of icons, which is also the highest rating.
+         * @default 5
+         */
+        this.max = 5;
+        /**
+         * Whether a rating is picked by whole icons or by halves. Any other value
+         * falls back to `1`.
+         * @default 1
+         */
+        this.step = 1;
+        /**
+         * Only displays the rating, which can then be any decimal value, such as
+         * an average. The field is then neither focusable nor editable.
+         * @default false
+         */
+        this.displayOnly = false;
+        /**
+         * Shows a button that removes the rating, once one is picked.
+         * @default false
+         */
+        this.clearable = false;
+        /**
+         * The icon drawn for the filled part of the rating.
+         * @default star
+         */
+        this.icon = "star";
+        /**
+         * The icon drawn for the empty part of the rating. Its shape differs from
+         * {@link icon} by default, so the rating never relies on color alone.
+         * @default star_border
+         */
+        this.emptyIcon = "star_border";
+        /**
+         * Picks the value under the pointer. The radios themselves ignore the
+         * pointer, so a whole icon stays one target even while `step` is `0.5`.
+         *
+         * @param event the click event.
+         * @private
+         */
+        this.handleClick = (event) => {
+            if (this.locked || event.target instanceof HTMLInputElement) {
+                return;
+            }
+            const value = this.valueAtPointer(event);
+            if (value === undefined) {
+                return;
+            }
+            this.pick(value);
+            this.radioFor(value)?.focus({ preventScroll: true });
+        };
+        /**
+         * Previews the value under a mouse pointer.
+         *
+         * @param event the pointer event.
+         * @private
+         */
+        this.handlePointerMove = (event) => {
+            if (this.locked || event.pointerType !== "mouse") {
+                return;
+            }
+            this.hoverValue = this.valueAtPointer(event);
+        };
+        /**
+         * Ends the hover preview.
+         * @private
+         */
+        this.handlePointerLeave = () => {
+            this.hoverValue = undefined;
+        };
+        /**
+         * Applies a radio checked natively, by Space or by assistive technology.
+         *
+         * @param event the native change event.
+         * @private
+         */
+        this.handleChange = (event) => {
+            if (this.locked) {
+                return;
+            }
+            this.pick(Number(event.target.value));
+        };
+        /**
+         * Keeps a radio from being checked while readonly, since the HTML
+         * `readonly` attribute has no effect on radios.
+         *
+         * @param event the click event dispatched on a radio.
+         * @private
+         */
+        this.handleRadioClick = (event) => {
+            if (this.readonly) {
+                event.preventDefault();
+            }
+        };
+        /**
+         * Moves the rating with the arrow keys, Home and End, without wrapping
+         * around as native radios do, and blocks every change while readonly.
+         *
+         * @param event the keyboard event.
+         * @private
+         */
+        this.handleKeydown = (event) => {
+            if (!(event.target instanceof HTMLInputElement)) {
+                return;
+            }
+            const step = this.resolvedStep;
+            const rtl = getComputedStyle(this).direction === "rtl";
+            const current = this.value ?? 0;
+            let next;
+            switch (event.key) {
+                case "ArrowRight":
+                    next = current + (rtl ? -step : step);
+                    break;
+                case "ArrowLeft":
+                    next = current + (rtl ? step : -step);
+                    break;
+                case "ArrowDown":
+                    next = current + step;
+                    break;
+                case "ArrowUp":
+                    next = current - step;
+                    break;
+                case "Home":
+                    next = step;
+                    break;
+                case "End":
+                    next = this.count;
+                    break;
+                case " ":
+                    if (this.readonly) {
+                        event.preventDefault();
+                    }
+                    return;
+                default:
+                    return;
+            }
+            event.preventDefault();
+            if (this.readonly) {
+                return;
+            }
+            const value = Math.min(this.count, Math.max(step, next));
+            this.pick(value);
+            this.radioFor(value)?.focus();
+        };
+        /**
+         * Removes the rating, then moves focus to the group, since the clear
+         * button disappears with it.
+         * @private
+         */
+        this.handleClear = async () => {
+            this.pick(undefined);
+            await this.updateComplete;
+            this.focus();
+        };
+    }
+    /**
+     * The current rating, `undefined` while nothing is picked. Overrides the
+     * accessor inherited from `FormMixin` to give it a `Number` converter, as
+     * `eun-slider` does, and to clamp every assignment within `0`/`max` : `0`
+     * or less means no rating. Snapping to `step` happens in
+     * {@link willUpdate}, once `displayOnly` is known, since a displayed
+     * average keeps its exact decimals.
+     */
+    get value() {
+        return super.value;
+    }
+    set value(value) {
+        super.value = this.clamp(value);
+    }
+    /**
+     * The rating applied on connection and form reset. Overrides the accessor
+     * inherited from `FormMixin` for the same reason as {@link value}.
+     */
+    get defaultValue() {
+        return super.defaultValue;
+    }
+    set defaultValue(value) {
+        // @ts-expect-error — FormMixin's real setter exists.
+        super.defaultValue = value;
+    }
+    /**
+     * The number of icons drawn, `max` rounded to a whole number of at least
+     * one.
+     * @private
+     */
+    get count() {
+        const count = Math.round(this.max);
+        return Number.isFinite(count) && count >= 1 ? count : 5;
+    }
+    /**
+     * The step actually applied, `step` restricted to `1` or `0.5`.
+     * @private
+     */
+    get resolvedStep() {
+        return Number(this.step) === 0.5 ? 0.5 : 1;
+    }
+    /**
+     * Clamps a value within `0`/`max`, turning anything empty, invalid, or at
+     * `0` or below into `undefined`.
+     *
+     * @param value the value to clamp.
+     * @returns the clamped value.
+     * @private
+     */
+    clamp(value) {
+        if (value === undefined || value === null || value === "") {
+            return undefined;
+        }
+        const number = Number(value);
+        if (!Number.isFinite(number) || number <= 0) {
+            return undefined;
+        }
+        return Math.min(number, this.count);
+    }
+    /**
+     * Clamps a value, then snaps it to the nearest `step` unless the rating
+     * is only displayed.
+     *
+     * @param value the value to normalize.
+     * @returns the normalized value.
+     * @private
+     */
+    snap(value) {
+        const clamped = this.clamp(value);
+        if (clamped === undefined || this.displayOnly) {
+            return clamped;
+        }
+        const step = this.resolvedStep;
+        return Math.min(this.count, Math.max(step, Math.round(clamped / step) * step));
+    }
+    /**
+     * Formats a number in the current locale, such as `4,5` in French.
+     *
+     * @param value the number to format.
+     * @returns the formatted number.
+     * @private
+     */
+    format(value) {
+        const locale = this.locale ?? getDefaultLocale();
+        try {
+            return new Intl.NumberFormat(locale, {
+                maximumFractionDigits: 2,
+            }).format(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    /**
+     * The accessible text of a value, such as "3 out of 5".
+     *
+     * @param value the value to describe.
+     * @returns the localized text.
+     * @private
+     */
+    valueText(value) {
+        return this.dictionary.rating.valueText(this.format(value), this.format(this.count));
+    }
+    /**
+     * The radio input matching a value, if rendered.
+     *
+     * @param value the value to look for.
+     * @returns the matching radio input.
+     * @private
+     */
+    radioFor(value) {
+        const radios = this.itemsEl?.querySelectorAll("input");
+        return (Array.from(radios ?? []).find((radio) => Number(radio.value) === value) ??
+            null);
+    }
+    /**
+     * The value of the group's single tab stop: the current rating, or the
+     * lowest one while nothing is picked.
+     * @private
+     */
+    get tabStopValue() {
+        return this.value ?? this.resolvedStep;
+    }
+    /**
+     * The host is never a tab stop of its own : sequential navigation goes
+     * straight to the radio group inside, in both directions, and
+     * {@link focus} covers a direct call on the host.
+     */
+    get hostTabStop() {
+        return false;
+    }
+    /**
+     * Returns the radio to focus on validation errors.
+     *
+     * @returns the group's tab stop, if rendered.
+     */
+    getFocusAnchor() {
+        return this.radioFor(this.tabStopValue) ?? undefined;
+    }
+    /**
+     * Focuses the group's tab stop.
+     */
+    focus(options) {
+        super.focus?.(options);
+        this.radioFor(this.tabStopValue)?.focus(options);
+    }
+    /**
+     * Applies a value picked by the user, and notifies consumers when it
+     * actually changed.
+     *
+     * @param value the picked value, `undefined` to clear the rating.
+     * @private
+     */
+    pick(value) {
+        if (value === this.value) {
+            return;
+        }
+        this.value = value;
+        this.dispatchEvent(new ChangeEvent(this.value));
+    }
+    /**
+     * Whether the user can't change the rating right now.
+     * @private
+     */
+    get locked() {
+        return this.disabled || this.readonly || this.displayOnly;
+    }
+    /**
+     * The value under the pointer : the whole icon, or its first half while
+     * `step` is `0.5`, mirrored in a right-to-left layout. The gap after an
+     * icon counts as that whole icon, so moving across the row never empties
+     * the hover preview between two icons.
+     *
+     * @param event the pointer event.
+     * @returns the value under the pointer, if over or past an icon.
+     * @private
+     */
+    valueAtPointer(event) {
+        const rtl = getComputedStyle(this).direction === "rtl";
+        const hovered = event.target.closest(".item");
+        if (!hovered) {
+            let item;
+            this.itemsEl?.querySelectorAll(".item").forEach((candidate) => {
+                const rect = candidate.getBoundingClientRect();
+                if (rtl ? rect.right >= event.clientX : rect.left <= event.clientX) {
+                    item = candidate;
+                }
+            });
+            return item ? Number(item.dataset.index) : undefined;
+        }
+        const index = Number(hovered.dataset.index);
+        if (this.resolvedStep === 1) {
+            return index;
+        }
+        const rect = hovered.getBoundingClientRect();
+        const ratio = rect.width ? (event.clientX - rect.left) / rect.width : 1;
+        const fromStart = rtl ? 1 - ratio : ratio;
+        return fromStart <= 0.5 ? index - 0.5 : index;
+    }
+    /**
+     * Snaps the value to `step` and keeps it within `max` whenever either of
+     * them, the value, or `displayOnly` changes. Done before render so the
+     * correction lands in the update already in progress, and before
+     * `FormMixin` validates the value.
+     *
+     * @param changed the changed properties.
+     */
+    willUpdate(changed) {
+        if (["value", "valueState", "max", "step", "displayOnly"].some((name) => changed.has(name))) {
+            const normalized = this.snap(this.value);
+            if (normalized !== this.value) {
+                this.value = normalized;
+            }
+        }
+        if (changed.has("disabled") || changed.has("readonly")) {
+            this.hoverValue = undefined;
+        }
+        super.willUpdate(changed);
+    }
+    /**
+     * Renders one icon, its empty shape with the filled one clipped on top.
+     *
+     * @param fill how much of the icon is filled, from `0` to `1`.
+     * @returns the rendered icon.
+     * @private
+     */
+    renderIcon(fill) {
+        return html `
+      <span class="icon" aria-hidden="true">
+        <eun-icon class="empty" name=${this.emptyIcon}></eun-icon>
+        <span class="fill" style=${styleMap({ width: `${fill * 100}%` })}>
+          <eun-icon name=${this.icon}></eun-icon>
+        </span>
+      </span>
+    `;
+    }
+    /**
+     * Renders the radio of one value, with the ring drawn around its area
+     * while it has keyboard focus.
+     *
+     * @param value the value of the radio.
+     * @returns the rendered radio.
+     * @private
+     */
+    renderRadio(value) {
+        const half = !Number.isInteger(value);
+        const area = classMap({
+            half,
+            end: !half && this.resolvedStep === 0.5,
+        });
+        return html `
+      <input
+        type="radio"
+        name="rating"
+        class=${area}
+        .value=${String(value)}
+        .checked=${live(this.value === value)}
+        ?disabled=${this.disabled}
+        tabindex=${value === this.tabStopValue ? "0" : "-1"}
+        aria-label=${this.valueText(value)}
+        @click=${this.handleRadioClick}
+      />
+      <span class="focus-ring ${half ? "half" : ""}" aria-hidden="true"></span>
+    `;
+    }
+    /**
+     * Renders the rating as a single image, its accessible name reading the
+     * score.
+     * @private
+     */
+    renderDisplay() {
+        const { rating } = this.dictionary;
+        const value = this.value;
+        const text = value === undefined ? rating.noValue : this.valueText(value);
+        return html `
+      <div
+        id="items"
+        part="items"
+        role="img"
+        aria-label=${rating.summary(this.label || rating.label, text)}
+      >
+        ${Array.from({ length: this.count }, (_, index) => html `<span class="item">
+              ${this.renderIcon(Math.min(1, Math.max(0, (value ?? 0) - index)))}
+            </span>`)}
+      </div>
+    `;
+    }
+    /**
+     * Renders the clear button, once a rating is picked and can be changed.
+     * @private
+     */
+    renderClear() {
+        if (!this.clearable || this.value === undefined || this.locked) {
+            return nothing;
+        }
+        return html `
+      <button
+        type="button"
+        id="clear"
+        part="clear"
+        aria-label=${this.clearLabel ?? this.dictionary.rating.clear}
+        @click=${this.handleClear}
+      >
+        <eun-icon name="close" aria-hidden="true"></eun-icon>
+      </button>
+    `;
+    }
+    /**
+     * Renders the rating template.
+     * @returns The rendered HTML template
+     */
+    render() {
+        if (this.displayOnly) {
+            return html `<div id="wrapper">${this.renderDisplay()}</div>`;
+        }
+        const description = this.renderDescription();
+        const describedBy = [
+            this.instructions ? "group-instructions" : "",
+            description === nothing ? "" : "description",
+        ]
+            .filter(Boolean)
+            .join(" ") || undefined;
+        const shown = this.hoverValue ?? this.value ?? 0;
+        return html `
+      <div id="wrapper">
+        ${this.renderFormLabels()}
+        ${this.instructions
+            ? html `<span id="group-instructions" hidden
+              >${this.instructions}</span
+            >`
+            : nothing}
+        <div id="control">
+          <div
+            id="items"
+            part="items"
+            role="radiogroup"
+            class=${classMap({ preview: this.hoverValue !== undefined })}
+            aria-label=${this.label || this.dictionary.rating.label}
+            aria-describedby=${ifDefined(describedBy)}
+            aria-required=${this.required ? "true" : nothing}
+            aria-readonly=${this.readonly ? "true" : nothing}
+            aria-disabled=${this.disabled ? "true" : nothing}
+            aria-invalid=${this.showError ? "true" : "false"}
+            @click=${this.handleClick}
+            @change=${this.handleChange}
+            @keydown=${this.handleKeydown}
+            @pointermove=${this.handlePointerMove}
+            @pointerleave=${this.handlePointerLeave}
+          >
+            ${Array.from({ length: this.count }, (_, index) => {
+            const item = index + 1;
+            return html `
+                <span class="item" data-index=${item}>
+                  ${this.renderIcon(Math.min(1, Math.max(0, shown - index)))}
+                  ${this.resolvedStep === 0.5
+                ? this.renderRadio(item - 0.5)
+                : nothing}
+                  ${this.renderRadio(item)}
+                </span>
+              `;
+        })}
+          </div>
+          ${this.renderClear()}
+        </div>
+        ${description}
+      </div>
+    `;
+    }
+};
+/**
+ * Styles to import to the component.
+ *
+ * @static
+ * @internal
+ * @readonly
+ */
+EunomiaRating.styles = [
+    ratingStyles,
+    formLabelsStyles.base,
+    formLabelsStyles.errorMessages,
+    formLabelsStyles.hintMessages,
+];
+__decorate([
+    property({ type: Number })
+], EunomiaRating.prototype, "max", void 0);
+__decorate([
+    property({ type: Number })
+], EunomiaRating.prototype, "step", void 0);
+__decorate([
+    property({ type: Boolean, attribute: "display-only", reflect: true })
+], EunomiaRating.prototype, "displayOnly", void 0);
+__decorate([
+    property({ type: Boolean, reflect: true })
+], EunomiaRating.prototype, "clearable", void 0);
+__decorate([
+    property({ attribute: "clear-label" })
+], EunomiaRating.prototype, "clearLabel", void 0);
+__decorate([
+    property()
+], EunomiaRating.prototype, "icon", void 0);
+__decorate([
+    property({ attribute: "empty-icon" })
+], EunomiaRating.prototype, "emptyIcon", void 0);
+__decorate([
+    state()
+], EunomiaRating.prototype, "hoverValue", void 0);
+__decorate([
+    property({ type: Number })
+], EunomiaRating.prototype, "value", null);
+__decorate([
+    property({ attribute: "default-value", type: Number })
+], EunomiaRating.prototype, "defaultValue", null);
+__decorate([
+    query("#items")
+], EunomiaRating.prototype, "itemsEl", void 0);
+EunomiaRating = __decorate([
+    customElement(EunomiaRatingTagName)
+], EunomiaRating);
+export { EunomiaRating };

package/dist/components/form/rating/rating.styles.d.ts

@@ -0,0 +1 @@
+export declare const ratingStyles: import("lit").CSSResult;