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

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

@@ -0,0 +1,349 @@
+import { LitElement, PropertyValues, TemplateResult } from "lit";
+import { DisabledMixinInterface } from "../../../mixins/disabled.mixin.js";
+import { ReadonlyMixinInterface } from "../../../mixins/readonly.mixin.js";
+import { ValidatorsMixinInterface } from "../../../mixins/validators.mixin.js";
+import { FormMixinInterface } from "../../../mixins/form.mixin.js";
+import { FormLabelMixinInterface } from "../../../mixins/form-label.mixin.js";
+import { LocalizableMixinInterface } from "../../../mixins/localizable.mixin.js";
+import { EunomiaIconName } from "../../content/icon/icon.type.js";
+import { Constructor } from "../../../utils/constructor.type.js";
+/**
+ * Tag name of the rating component.
+ */
+export declare const EunomiaRatingTagName = "eun-rating";
+/**
+ * The granularity a rating can be picked at: whole icons, or halves.
+ */
+export type EunomiaRatingStep = 1 | 0.5;
+/**
+ * Type of the rating base used to declare every necessary Mixin interface elements.
+ * @internal
+ */
+type EunomiaRatingBase = LitElement & DisabledMixinInterface & ReadonlyMixinInterface & ValidatorsMixinInterface<number | undefined> & FormMixinInterface<number | undefined> & FormLabelMixinInterface & LocalizableMixinInterface;
+declare const EunomiaRatingMixinBase: Constructor<EunomiaRatingBase>;
+/**
+ * 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
+ */
+export declare class EunomiaRating extends EunomiaRatingMixinBase {
+    /**
+     * Styles to import to the component.
+     *
+     * @static
+     * @internal
+     * @readonly
+     */
+    static readonly styles: import("lit").CSSResult[];
+    /**
+     * Every change is a complete choice, so its error shows right away.
+     * @internal
+     */
+    errorOnChange: boolean;
+    /**
+     * The number of icons, which is also the highest rating.
+     * @default 5
+     */
+    max: number;
+    /**
+     * Whether a rating is picked by whole icons or by halves. Any other value
+     * falls back to `1`.
+     * @default 1
+     */
+    step: EunomiaRatingStep;
+    /**
+     * 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
+     */
+    displayOnly: boolean;
+    /**
+     * Shows a button that removes the rating, once one is picked.
+     * @default false
+     */
+    clearable: boolean;
+    /**
+     * The accessible label of the clear button. Defaults to the localized
+     * string for the current locale.
+     */
+    clearLabel?: string;
+    /**
+     * The icon drawn for the filled part of the rating.
+     * @default star
+     */
+    icon: EunomiaIconName;
+    /**
+     * 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
+     */
+    emptyIcon: EunomiaIconName;
+    /**
+     * The rating previewed while a mouse hovers the icons.
+     * @internal
+     */
+    private hoverValue?;
+    /**
+     * 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(): number | undefined;
+    set value(value: number | undefined);
+    /**
+     * The rating applied on connection and form reset. Overrides the accessor
+     * inherited from `FormMixin` for the same reason as {@link value}.
+     */
+    get defaultValue(): number | undefined;
+    set defaultValue(value: number | undefined);
+    /**
+     * The radio group element.
+     * @internal
+     */
+    private readonly itemsEl?;
+    /**
+     * The number of icons drawn, `max` rounded to a whole number of at least
+     * one.
+     * @private
+     */
+    private get count();
+    /**
+     * The step actually applied, `step` restricted to `1` or `0.5`.
+     * @private
+     */
+    private get resolvedStep();
+    /**
+     * 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
+     */
+    private clamp;
+    /**
+     * 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
+     */
+    private snap;
+    /**
+     * Formats a number in the current locale, such as `4,5` in French.
+     *
+     * @param value the number to format.
+     * @returns the formatted number.
+     * @private
+     */
+    private format;
+    /**
+     * The accessible text of a value, such as "3 out of 5".
+     *
+     * @param value the value to describe.
+     * @returns the localized text.
+     * @private
+     */
+    private valueText;
+    /**
+     * The radio input matching a value, if rendered.
+     *
+     * @param value the value to look for.
+     * @returns the matching radio input.
+     * @private
+     */
+    private radioFor;
+    /**
+     * The value of the group's single tab stop: the current rating, or the
+     * lowest one while nothing is picked.
+     * @private
+     */
+    private get tabStopValue();
+    /**
+     * 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.
+     */
+    protected get hostTabStop(): boolean;
+    /**
+     * Returns the radio to focus on validation errors.
+     *
+     * @returns the group's tab stop, if rendered.
+     */
+    getFocusAnchor(): HTMLElement | undefined;
+    /**
+     * Focuses the group's tab stop.
+     */
+    focus(options?: FocusOptions): void;
+    /**
+     * 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
+     */
+    private pick;
+    /**
+     * Whether the user can't change the rating right now.
+     * @private
+     */
+    private get locked();
+    /**
+     * 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
+     */
+    private valueAtPointer;
+    /**
+     * 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
+     */
+    private readonly handleClick;
+    /**
+     * Previews the value under a mouse pointer.
+     *
+     * @param event the pointer event.
+     * @private
+     */
+    private readonly handlePointerMove;
+    /**
+     * Ends the hover preview.
+     * @private
+     */
+    private readonly handlePointerLeave;
+    /**
+     * Applies a radio checked natively, by Space or by assistive technology.
+     *
+     * @param event the native change event.
+     * @private
+     */
+    private readonly handleChange;
+    /**
+     * 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
+     */
+    private readonly handleRadioClick;
+    /**
+     * 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
+     */
+    private readonly handleKeydown;
+    /**
+     * Removes the rating, then moves focus to the group, since the clear
+     * button disappears with it.
+     * @private
+     */
+    private readonly handleClear;
+    /**
+     * 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.
+     */
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * 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
+     */
+    private renderIcon;
+    /**
+     * 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
+     */
+    private renderRadio;
+    /**
+     * Renders the rating as a single image, its accessible name reading the
+     * score.
+     * @private
+     */
+    private renderDisplay;
+    /**
+     * Renders the clear button, once a rating is picked and can be changed.
+     * @private
+     */
+    private renderClear;
+    /**
+     * Renders the rating template.
+     * @returns The rendered HTML template
+     */
+    render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        [EunomiaRatingTagName]: EunomiaRating;
+    }
+}
+export {};