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

package/dist/components/form/radio/radio-list.js

@@ -5,8 +5,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { customElement, property, query } from "lit/decorators.js";
-import { html, LitElement } from "lit";
+import { html, LitElement, nothing } from "lit";
 import { classMap } from "lit/directives/class-map.js";
+import { ifDefined } from "lit/directives/if-defined.js";
 import { FormLabelMixin } from "../../../mixins/form-label.mixin.js";
 import { FormMixin, hasErrorDisplayChange, } from "../../../mixins/form.mixin.js";
 import { DisabledMixin } from "../../../mixins/disabled.mixin.js";
@@ -81,6 +82,7 @@ const Base = DisabledMixin(ValidatorsMixin(LitElement));
  * @prop {string} [defaultValue] - The value reselected when the list connects, and restored on form reset
  * @attr {string} [default-value] - The value reselected when the list connects, and restored on form reset
  * @prop {boolean} [hideError=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
  * @attr {boolean} [hide-error=false] - Whether the errors are hidden. The hint stays visible
  * @prop {Array<import('../../../types/form-validators.type.js').Validators<string | undefined>>} validators - A list of validation rules applied to the group's selected value
@@ -95,6 +97,11 @@ const Base = DisabledMixin(ValidatorsMixin(LitElement));
 let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMixin(FormMixin(Base))) {
     constructor() {
         super(...arguments);
+        /**
+         * Every change is a complete choice, so its error shows right away.
+         * @internal
+         */
+        this.errorOnChange = true;
         /**
          * Indicates whether the elements into the list should be displayed inline.
          * @default false
@@ -169,8 +176,7 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
      * Assigns `name`/`id` to every child, applies a `default-value` selection
      * once the slotted children actually exist (see `handleSlotChange` for
      * why this can't rely on `FormMixin`'s own `defaultValue` setter alone),
-     * restores `aria-activedescendant` for a child checked directly in
-     * markup, and sets up the initial roving `tabindex`.
+     * and sets up the initial roving `tabindex`.
      *
      * The roving `tabindex` is applied only once every child's own first
      * update has settled — each `eun-radio` is itself a `DisabledMixin` user,
@@ -192,9 +198,6 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
             this.sendChangeEvent();
         }
         void Promise.all(this.fields.map((field) => field.updateComplete)).then(() => {
-            if (this.active && this.optionsList) {
-                this.optionsList.setAttribute("aria-activedescendant", this.active.id);
-            }
             this.setFocus();
             this.checkValidity(this.value);
         });
@@ -218,19 +221,32 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
         this.removeEventListener("keydown", this.handleKeydown);
         super.disconnectedCallback?.();
     }
+    /**
+     * Whether the group's own `disabled`/`readonly` changed in a way to pass
+     * on to every child : always once set, but not for the initial `false`,
+     * which would otherwise re-enable a child disabled on its own.
+     *
+     * @param changed - The changed properties of the update.
+     * @param name - The property to check.
+     * @returns true when the children should take the group's value.
+     * @private
+     */
+    isGroupChange(changed, name) {
+        return changed.has(name) && (this[name] || changed.get(name) !== undefined);
+    }
     /**
      * Lifecycle hook called whenever reactive properties change.
      * @param _changedProperties - Map of changed properties
      */
     updated(_changedProperties) {
         super.updated(_changedProperties);
-        if (_changedProperties.has("disabled")) {
+        if (this.isGroupChange(_changedProperties, "disabled")) {
             this.fields.forEach((field) => {
                 field.disabled = this.disabled;
             });
             this.setFocus();
         }
-        if (_changedProperties.has("readonly")) {
+        if (this.isGroupChange(_changedProperties, "readonly")) {
             this.fields.forEach((field) => {
                 field.readonly = this.readonly;
             });
@@ -243,9 +259,6 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
                 field.validationRequested = showError;
             });
         }
-        if (_changedProperties.has("label") && !this.hasAttribute("aria-label")) {
-            this.setAttribute("aria-label", `${this.label}. ${this.instructions ?? ""}`);
-        }
         if (_changedProperties.has("name")) {
             this.fields.forEach((field) => {
                 field.name = this.name;
@@ -313,8 +326,8 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
         this.setActive(enabled[activeIndex], true);
     }
     /**
-     * Applies the roving `tabindex` : the checked child (or the first one, if
-     * none is checked yet) is the group's single tab stop, matching a native
+     * Applies the roving `tabindex` : the checked child (or the first enabled
+     * one, if none is checked yet) is the group's single tab stop, matching a native
      * `radiogroup`'s "one tab stop, arrows move focus" behavior.
      * @private
      */
@@ -328,14 +341,15 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
         if (this.readonly || this.disabled) {
             return;
         }
-        const toFocus = this.active ?? this.fields[0];
+        const toFocus = this.active ??
+            this.fields.find((field) => !field.disabled && !field.readonly);
         if (toFocus && !toFocus.disabled && !toFocus.readonly) {
             toFocus.setAttribute("tabindex", "0");
         }
     }
     /**
      * Checks the given child, unchecking every other one, updates the roving
-     * `tabindex`/`aria-activedescendant`, and re-validates the group.
+     * `tabindex`, and re-validates the group.
      *
      * @param item the child to activate
      * @param focus whether to also move DOM focus onto it (arrow-key navigation)
@@ -345,7 +359,6 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
         if (this.disabled || this.readonly || !item || !this.optionsList) {
             return;
         }
-        this.optionsList.setAttribute("aria-activedescendant", item.id);
         if (focus) {
             item.focus();
         }
@@ -378,8 +391,8 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
     }
     /**
      * Handler called when slot content changes.
-     * Propagates the group `name` and assigns a stable `id` (needed for
-     * `aria-activedescendant`) to every child radio.
+     * Propagates the group `name` and assigns a stable `id` to every child
+     * radio.
      *
      * @private
      */
@@ -394,17 +407,29 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
      * @returns The rendered template
      */
     render() {
+        const description = this.renderDescription();
+        const describedBy = [
+            this.instructions ? "group-instructions" : "",
+            description === nothing ? "" : "description",
+        ]
+            .filter(Boolean)
+            .join(" ") || undefined;
         return html `
-      <fieldset id="fieldset">
+      <fieldset id="fieldset" role="presentation">
         <div id="legend">${this.renderFormLabels("options")}</div>
+        ${this.instructions
+            ? html `<span id="group-instructions" hidden
+              >${this.instructions}</span
+            >`
+            : nothing}
         <div
           id="options"
           part="options"
           role="radiogroup"
           class=${classMap({ inline: this.inline })}
           ?disabled=${this.disabled}
-          aria-labelledby="legend"
-          aria-describedby="messages"
+          aria-label=${ifDefined(this.label)}
+          aria-describedby=${ifDefined(describedBy)}
           aria-disabled=${this.disabled ? "true" : "false"}
           aria-readonly=${this.readonly ? "true" : "false"}
           aria-required=${this.required ? "true" : "false"}
@@ -412,7 +437,7 @@ let EunomiaRadioList = class EunomiaRadioList extends FormLabelMixin(ReadonlyMix
         >
           <slot @slotchange=${this.handleSlotChange}></slot>
         </div>
-        ${this.renderDescription()}
+        ${description}
       </fieldset>
     `;
     }

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

@@ -34,6 +34,7 @@ declare const EunomiaRadioMixinBase: Constructor<EunomiaRadioBase>;
  * @prop {boolean} [disabled=false] - Whether the radio is disabled
  * @prop {boolean} [readonly=false] - Whether the radio is read only
  * @prop {boolean} [hideError=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
  * @attr {boolean} [hide-error=false] - Whether the error message is hidden. The hint stays visible
  * @prop {boolean} [required=false] - Whether a selection is required

package/dist/components/form/radio/radio.js

@@ -37,6 +37,7 @@ const EunomiaRadioMixinBase = RadioMixin(ReadonlyMixin(FormMixin(DisabledMixin(V
  * @prop {boolean} [disabled=false] - Whether the radio is disabled
  * @prop {boolean} [readonly=false] - Whether the radio is read only
  * @prop {boolean} [hideError=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
  * @attr {boolean} [hide-error=false] - Whether the error message is hidden. The hint stays visible
  * @prop {boolean} [required=false] - Whether a selection is required

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 {};