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

package/dist/mixins/form.mixin.d.ts

@@ -1,4 +1,4 @@
-import { LitElement, nothing, TemplateResult } from "lit";
+import { LitElement, nothing, PropertyValues, TemplateResult } from "lit";
 import { DisabledMixinInterface } from "./disabled.mixin.js";
 import { ValidatorsMixinInterface } from "./validators.mixin.js";
 import { Constructor } from "../utils/constructor.type.js";
@@ -17,16 +17,36 @@ export declare class FormMixinInterface<T> {
     description?: string | string[] | undefined;
     valueState?: T;
     hideError?: boolean;
+    invalid: boolean;
     form: HTMLFormElement | null;
     dirty: boolean;
     touched: boolean;
+    validationRequested: boolean;
     controlled: boolean;
+    descriptionOnHost: boolean;
+    errorOnChange: boolean;
+    get showError(): boolean;
+    get showErrorMessages(): boolean;
     get pristine(): boolean;
     get untouched(): boolean;
     get value(): T;
     set value(value: T);
     get defaultValue(): T | undefined;
 }
+/**
+ * Every property {@link FormMixinInterface.showError} depends on, for
+ * components mirroring it outside their template (e.g. onto the host's
+ * `aria-invalid`).
+ */
+export declare const ERROR_DISPLAY_PROPERTIES: string[];
+/**
+ * Whether any property {@link FormMixinInterface.showError} depends on
+ * changed in this update.
+ *
+ * @param changed - The changed properties of the update.
+ * @returns true when the error display may have changed.
+ */
+export declare const hasErrorDisplayChange: (changed: PropertyValues) => boolean;
 /**
  * Mixin that adds form-related behavior and value management.
  *

package/dist/mixins/form.mixin.js

@@ -13,17 +13,47 @@ import { html, nothing } from "lit";
 import { property, state } from "lit/decorators.js";
 import { when } from "lit/directives/when.js";
 import { ChangeEvent } from "../events/change.event.js";
+/**
+ * Every property {@link FormMixinInterface.showError} depends on, for
+ * components mirroring it outside their template (e.g. onto the host's
+ * `aria-invalid`).
+ */
+export const ERROR_DISPLAY_PROPERTIES = [
+    "valid",
+    "hideError",
+    "invalid",
+    "disabled",
+    "touched",
+    "dirty",
+    "validationRequested",
+    "error",
+];
+/**
+ * Whether any property {@link FormMixinInterface.showError} depends on
+ * changed in this update.
+ *
+ * @param changed - The changed properties of the update.
+ * @returns true when the error display may have changed.
+ */
+export const hasErrorDisplayChange = (changed) => ERROR_DISPLAY_PROPERTIES.some((name) => changed.has(name));
 export const FormMixin = (superClass) => {
-    var _FormMixinClass_markDirty, _FormMixinClass_markTouched;
+    var _FormMixinClass_markDirty, _FormMixinClass_markTouched, _FormMixinClass_markValidationRequested;
     class FormMixinClass extends superClass {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
         constructor(...args) {
             super(...args);
             /**
-             * When true, validation error messages are hidden.
+             * When true, validation error messages are hidden. The hint stays visible.
              * @default false
              */
             this.hideError = false;
+            /**
+             * When true, the field is shown as invalid (error styling and
+             * `aria-invalid`) without any message, for an error whose message is
+             * displayed elsewhere. Does not change the field's validity.
+             * @default false
+             */
+            this.invalid = false;
             /**
              * Whether this field behaves like a checkbox/radio (checkable).
              * @default false
@@ -53,6 +83,13 @@ export const FormMixin = (superClass) => {
              * @default false
              */
             this.touched = false;
+            /**
+             * Whether the form asked for this field's validity, on a submit attempt
+             * or a `reportValidity()` call, since it connected (or since the last
+             * reset). Reveals errors on a field the user never reached.
+             * @default false
+             */
+            this.validationRequested = false;
             /**
              * Opts this field out of the native reset algorithm's value wipe: when
              * `true`, `formResetCallback` leaves `value`/`checked` untouched.
@@ -70,6 +107,25 @@ export const FormMixin = (superClass) => {
              * @default false
              */
             this.controlled = false;
+            /**
+             * Whether the hint or error is exposed through the host's own
+             * `aria-description`, for a component whose host is the control itself
+             * (a checkbox, a radio, a switch). The rendered message is then hidden
+             * from assistive technology, so it isn't read again as part of the
+             * control's name, which is computed from the host's content.
+             * @default false
+             * @internal
+             */
+            this.descriptionOnHost = false;
+            /**
+             * Whether a change alone reveals the error, without waiting for focus
+             * to leave the field, for a field whose every change is a complete
+             * choice (a checkbox, a radio, a select) rather than an entry still
+             * being typed.
+             * @default false
+             * @internal
+             */
+            this.errorOnChange = false;
             /**
              * Marks the field dirty on its own `eunchange` — dispatched only from a
              * genuine user-interaction handler, never from the `value`/`checked`
@@ -89,10 +145,42 @@ export const FormMixin = (superClass) => {
                     this.touched = true;
                 }
             });
+            /**
+             * Marks validation as requested when the form checks this field, which
+             * fires `invalid` on it.
+             */
+            _FormMixinClass_markValidationRequested.set(this, () => {
+                this.validationRequested = true;
+            });
             if (!this.internals) {
                 this.internals = this.attachInternals();
             }
         }
+        /**
+         * Whether the field currently shows its error state (styling and
+         * `aria-invalid`): not disabled, and either forced by {@link invalid} or
+         * showing its error messages.
+         */
+        get showError() {
+            return (this.invalid && !this.disabled) || this.showErrorMessages;
+        }
+        /**
+         * Whether the field currently shows its error messages : invalid, not
+         * disabled, not `hideError`, and either left once (`touched`), changed
+         * while {@link errorOnChange} is set (`dirty`), checked by its form, or
+         * given an external `error`. Typing alone never reveals an error, so an
+         * unfinished entry isn't reported as invalid; once shown, the error
+         * follows the value live.
+         */
+        get showErrorMessages() {
+            return (!this.valid &&
+                !this.hideError &&
+                !this.disabled &&
+                (this.touched ||
+                    (this.dirty && this.errorOnChange) ||
+                    this.validationRequested ||
+                    !!this.error));
+        }
         /**
          * Whether the value hasn't changed since the field connected (or since
          * the last reset). The inverse of {@link dirty}.
@@ -150,14 +238,14 @@ export const FormMixin = (superClass) => {
             this.setFormValue(value);
         }
         /**
-         * Gets the current description or validation errors.
-         * Returns undefined if errors are hidden.
+         * Gets the validation errors while {@link showErrorMessages} is true, the
+         * hint otherwise.
          *
-         * @returns Error message string, array of messages, or undefined.
+         * @returns Error message string, array of messages, or the hint.
          */
         get description() {
-            if (this.hideError) {
-                return undefined;
+            if (!this.showErrorMessages) {
+                return this.hint;
             }
             if (this.errorMessages.length) {
                 return this.errorMessages;
@@ -179,6 +267,15 @@ export const FormMixin = (superClass) => {
         get type() {
             return this.localName;
         }
+        /**
+         * Validates `checked` rather than `value` for a checkable field.
+         *
+         * @returns the value {@link checkValidity} validates by default.
+         */
+        getValueToValidate() {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return (this.checkable ? this.checked : this.value);
+        }
         /**
          * Lifecycle callback called when element is connected to the DOM.
          * Initializes the form value depending on state.
@@ -196,6 +293,7 @@ export const FormMixin = (superClass) => {
             this.checkValidity(this.value);
             this.addEventListener(ChangeEvent.eventName, __classPrivateFieldGet(this, _FormMixinClass_markDirty, "f"));
             this.addEventListener("focusout", __classPrivateFieldGet(this, _FormMixinClass_markTouched, "f"));
+            this.addEventListener("invalid", __classPrivateFieldGet(this, _FormMixinClass_markValidationRequested, "f"));
         }
         /**
          * Lifecycle callback called when element is disconnected from the DOM.
@@ -204,6 +302,7 @@ export const FormMixin = (superClass) => {
         disconnectedCallback() {
             this.removeEventListener(ChangeEvent.eventName, __classPrivateFieldGet(this, _FormMixinClass_markDirty, "f"));
             this.removeEventListener("focusout", __classPrivateFieldGet(this, _FormMixinClass_markTouched, "f"));
+            this.removeEventListener("invalid", __classPrivateFieldGet(this, _FormMixinClass_markValidationRequested, "f"));
             super.disconnectedCallback?.();
         }
         /**
@@ -217,13 +316,35 @@ export const FormMixin = (superClass) => {
                 changedProperties.has("valueState") ||
                 changedProperties.has("checked") ||
                 changedProperties.has("validators") ||
-                changedProperties.has("required")) {
-                const valToCheck = this.checkable ? this.checked : this.value;
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                this.checkValidity(valToCheck);
+                changedProperties.has("required") ||
+                changedProperties.has("error")) {
+                this.checkValidity();
             }
             super.willUpdate(changedProperties);
         }
+        /**
+         * LitElement lifecycle method called after update. Mirrors the hint or
+         * error onto the host's `aria-description` while
+         * {@link descriptionOnHost} is set.
+         *
+         * @param changedProperties - Map of changed properties and their old values.
+         */
+        updated(changedProperties) {
+            super.updated(changedProperties);
+            if (!this.descriptionOnHost) {
+                return;
+            }
+            const { description } = this;
+            const text = Array.isArray(description)
+                ? description.join(" ")
+                : description;
+            if (text) {
+                this.setAttribute("aria-description", text);
+            }
+            else {
+                this.removeAttribute("aria-description");
+            }
+        }
         /**
          * Syncs the field value with the form submission internals.
          * If disabled or unchecked (for checkable), sets empty form data.
@@ -282,6 +403,7 @@ export const FormMixin = (superClass) => {
             }
             this.dirty = false;
             this.touched = false;
+            this.validationRequested = false;
         }
         /**
          * Renders the description or error messages.
@@ -292,38 +414,39 @@ export const FormMixin = (superClass) => {
             return this.renderError();
         }
         /**
-         * Renders the error messages if the field is invalid and errors are visible.
-         * If no error messages are retrived but an hint has been set, the hint will be returned.
+         * Renders the error messages while {@link showErrorMessages} is true, the
+         * hint otherwise.
          *
          * @returns Template result with error messages, hint or nothing.
          */
         renderError() {
             const { description } = this;
-            const isHint = description &&
-                description.length &&
-                !(this.errorMessages && this.errorMessages.length) &&
-                !(this.validationMessage || this.validationMessage.length);
-            if (isHint) {
+            if (!description?.length) {
+                return nothing;
+            }
+            if (!this.showErrorMessages) {
                 return html `
-          <p id="description" class="hint-messages">
+          <p
+            id="description"
+            class="hint-messages"
+            aria-hidden=${this.descriptionOnHost ? "true" : nothing}
+          >
             <span>${description}</span>
           </p>
         `;
             }
-            if (this.valid ||
-                this.hideError ||
-                this.disabled ||
-                !description?.length) {
-                return nothing;
-            }
             return html `
-        <p id="description" class="error-messages">
+        <p
+          id="description"
+          class="error-messages"
+          aria-hidden=${this.descriptionOnHost ? "true" : nothing}
+        >
           ${when(Array.isArray(description), () => description.map((msg) => html `<span>${msg}</span>`), () => html `<span>${description}</span>`)}
         </p>
       `;
         }
     }
-    _FormMixinClass_markDirty = new WeakMap(), _FormMixinClass_markTouched = new WeakMap();
+    _FormMixinClass_markDirty = new WeakMap(), _FormMixinClass_markTouched = new WeakMap(), _FormMixinClass_markValidationRequested = new WeakMap();
     FormMixinClass.formAssociated = true;
     __decorate([
         property({ reflect: true })
@@ -334,6 +457,9 @@ export const FormMixin = (superClass) => {
     __decorate([
         property({ type: Boolean, attribute: "hide-error" })
     ], FormMixinClass.prototype, "hideError", void 0);
+    __decorate([
+        property({ type: Boolean })
+    ], FormMixinClass.prototype, "invalid", void 0);
     __decorate([
         state()
     ], FormMixinClass.prototype, "valueState", void 0);
@@ -343,6 +469,9 @@ export const FormMixin = (superClass) => {
     __decorate([
         state()
     ], FormMixinClass.prototype, "touched", void 0);
+    __decorate([
+        state()
+    ], FormMixinClass.prototype, "validationRequested", void 0);
     __decorate([
         property({ type: Boolean })
     ], FormMixinClass.prototype, "controlled", void 0);

package/dist/mixins/localizable.mixin.d.ts

@@ -14,7 +14,7 @@ export declare class LocalizableMixinInterface {
  * it: user-facing strings with no dedicated override property at all
  * (navigation button labels, ARIA group names, and the like), and
  * strings that *do* have their own override property (e.g. `eun-chip`'s
- * `ariaLabelRemove`) but fall back to `this.dictionary` — instead of a
+ * `removeLabel`) but fall back to `this.dictionary` — instead of a
  * hardcoded English literal — when that property is left unset, so the
  * default follows `locale` while an explicit override still wins.
  *

package/dist/mixins/localizable.mixin.js

@@ -12,7 +12,7 @@ import { dictionaries, getDefaultLocale } from "../i18n/index.js";
  * it: user-facing strings with no dedicated override property at all
  * (navigation button labels, ARIA group names, and the like), and
  * strings that *do* have their own override property (e.g. `eun-chip`'s
- * `ariaLabelRemove`) but fall back to `this.dictionary` — instead of a
+ * `removeLabel`) but fall back to `this.dictionary` — instead of a
  * hardcoded English literal — when that property is left unset, so the
  * default follows `locale` while an explicit override still wins.
  *

package/dist/mixins/radio.mixin.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { property } from "lit/decorators.js";
+import { hasErrorDisplayChange } from "./form.mixin.js";
 import { ChangeEvent } from "../events/change.event.js";
 /**
  * Mixin adding "radio selectable" behavior to a component.
@@ -36,6 +37,17 @@ export const RadioMixin = (superClass) => {
              * @default true
              */
             this.checkable = true;
+            /**
+             * The host is the control, so its hint or error goes on its own
+             * `aria-description`.
+             * @internal
+             */
+            this.descriptionOnHost = true;
+            /**
+             * Every change is a complete choice, so its error shows right away.
+             * @internal
+             */
+            this.errorOnChange = true;
             /**
              * Overrides `ValidatorsMixin`'s own `required` check, which validates
              * emptiness of `this.value` — meaningless here, since a radio's `value`
@@ -54,7 +66,7 @@ export const RadioMixin = (superClass) => {
                 if (this.required && !this.checked) {
                     return {
                         validity: { valueMissing: true },
-                        message: "Field value is missing",
+                        message: this.validationDictionary.validation.valueMissing,
                     };
                 }
                 return { validity: {} };
@@ -105,10 +117,8 @@ export const RadioMixin = (superClass) => {
                 this.setAttribute("aria-checked", String(this.checked));
                 this.updateInternals();
             }
-            if (_changedProperties.has("valid") ||
-                _changedProperties.has("hideError") ||
-                _changedProperties.has("disabled")) {
-                this.setAttribute("aria-invalid", String(!this.hideError && !this.disabled && !this.valid));
+            if (hasErrorDisplayChange(_changedProperties)) {
+                this.setAttribute("aria-invalid", String(this.showError));
             }
         }
         /**
@@ -125,7 +135,6 @@ export const RadioMixin = (superClass) => {
          * - Prevents propagation.
          * - Ignores action if `disabled` or `readonly`.
          * - Sets `checked` to `true` ; never unchecks (see the class doc).
-         * - Updates ARIA attributes (`aria-description`).
          * - Dispatches a custom `ChangeEvent`.
          *
          * @param event The triggered mouse or keyboard event
@@ -142,15 +151,6 @@ export const RadioMixin = (superClass) => {
             this.checked = true;
             this.updateInternals();
             this.checkValidity(this.checked);
-            if (this.description) {
-                const attribute = this.description instanceof Array
-                    ? this.description.join(",")
-                    : this.description;
-                this.setAttribute("aria-description", attribute);
-            }
-            else {
-                this.removeAttribute("aria-description");
-            }
             this.dispatchEvent(new ChangeEvent(this.checked));
         }
         /**

package/dist/mixins/readonly.mixin.d.ts

@@ -10,7 +10,8 @@ export declare class ReadonlyMixinInterface {
  * A mixin that adds a `readonly` property to a LitElement component.
  *
  * When the `readonly` state changes, it automatically updates the `aria-readonly` attribute
- * for accessibility compliance.
+ * for accessibility compliance. The attribute is only present while readonly, so an SSR
+ * framework hydrating a non-readonly field doesn't see an attribute it never rendered.
  *
  * @param superClass - The base LitElement class to extend.
  * @returns A class extending the base class with `readonly` functionality.

package/dist/mixins/readonly.mixin.js

@@ -9,7 +9,8 @@ import { property } from "lit/decorators.js";
  * A mixin that adds a `readonly` property to a LitElement component.
  *
  * When the `readonly` state changes, it automatically updates the `aria-readonly` attribute
- * for accessibility compliance.
+ * for accessibility compliance. The attribute is only present while readonly, so an SSR
+ * framework hydrating a non-readonly field doesn't see an attribute it never rendered.
  *
  * @param superClass - The base LitElement class to extend.
  * @returns A class extending the base class with `readonly` functionality.
@@ -28,12 +29,18 @@ export const ReadonlyMixin = (superClass) => {
          * LitElement lifecycle method.
          * Called when reactive properties are updated.
          *
-         * Updates `aria-readonly` whenever `readonly` changes.
+         * Updates `aria-readonly` whenever `readonly` changes. Removed rather
+         * than set to "false", which means the same.
          */
         updated(_changedProperties) {
             super.updated(_changedProperties);
             if (_changedProperties.has("readonly")) {
-                this.setAttribute("aria-readonly", String(this.readonly));
+                if (this.readonly) {
+                    this.setAttribute("aria-readonly", "true");
+                }
+                else {
+                    this.removeAttribute("aria-readonly");
+                }
             }
         }
     }

package/dist/mixins/validators.mixin.d.ts

@@ -1,6 +1,7 @@
 import { LitElement } from "lit";
 import { Mutable, Validators } from "../types/form-validators.type.js";
 import { Constructor } from "../utils/constructor.type.js";
+import { Dictionary } from "../i18n/index.js";
 /**
  * Defines a Validity object.
  */
@@ -20,10 +21,15 @@ export interface Validity {
 export declare class ValidatorsMixinInterface<U = unknown> {
     checkLocalValidators: () => Validity;
     buildCommonValidators: () => Validity;
-    checkValidity: (dataToCheck: any) => boolean;
+    checkValidity: (dataToCheck?: any) => boolean;
+    reportValidity: (valToCheck?: any) => boolean;
+    get validity(): ValidityState;
+    get willValidate(): boolean;
     internals: globalThis.ElementInternals;
     valid: boolean;
     required: boolean;
+    error?: string;
+    get validationDictionary(): Dictionary;
     errorMessages: string[];
     validationMessage: string | string[];
     validators?: Validators<U>[];

package/dist/mixins/validators.mixin.js

@@ -5,6 +5,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { property, state } from "lit/decorators.js";
+import { dictionaries, getDefaultLocale } from "../i18n/index.js";
 /**
  * Mixin that adds validation capabilities to a LitElement.
  *
@@ -13,6 +14,15 @@ import { property, state } from "lit/decorators.js";
  */
 export const ValidatorsMixin = (superClass) => {
     class ValidatorsMixinClass extends superClass {
+        /**
+         * The dictionary built-in validation messages are read from: the field's
+         * own `locale` when it has one, the shared default locale otherwise.
+         */
+        get validationDictionary() {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const locale = this.locale;
+            return dictionaries[locale ?? getDefaultLocale()] ?? dictionaries.en;
+        }
         /**
          * Current validity state of the element.
          */
@@ -79,18 +89,18 @@ export const ValidatorsMixin = (superClass) => {
                 (value instanceof Array && !value.length);
             if (this.required && isEmpty) {
                 validity.valueMissing = true;
-                message = "Field value is missing";
+                message = this.validationDictionary.validation.valueMissing;
             }
             return { validity, message };
         }
         /**
          * Runs all validation rules and updates internal validity.
          *
-         * @param dataToCheck The value to validate.
+         * @param dataToCheck The value to validate, the field's own one when omitted.
          * @returns true if valid, false otherwise.
          * @throws Error if any async validator is passed (only sync supported).
          */
-        checkValidity(dataToCheck) {
+        checkValidity(dataToCheck = this.getValueToValidate()) {
             const localResult = this.checkLocalValidators();
             const commonResult = this.buildCommonValidators();
             const combinedValidity = {
@@ -98,16 +108,12 @@ export const ValidatorsMixin = (superClass) => {
                 ...commonResult.validity,
             };
             let message = commonResult.message || localResult.message;
-            if (this.validators && this.validators?.length) {
-                const errorMessages = this.validators.reduce((messages, validator) => this.collectErrors(messages, validator, dataToCheck), []);
-                this.errorMessages = errorMessages;
-                if (errorMessages.length > 0) {
-                    combinedValidity.customError = true;
-                    message = errorMessages.join(" ; ");
-                }
-            }
-            else {
-                this.errorMessages = [];
+            const errorMessages = this.error ? [this.error] : [];
+            this.validators?.forEach((validator) => this.collectErrors(errorMessages, validator, dataToCheck));
+            this.errorMessages = errorMessages;
+            if (errorMessages.length > 0) {
+                combinedValidity.customError = true;
+                message = errorMessages.join(" ; ");
             }
             this.valid = !Object.values(combinedValidity).some(Boolean);
             const anchor = this.getFocusAnchor?.();
@@ -115,17 +121,17 @@ export const ValidatorsMixin = (superClass) => {
                 this.setValidity(combinedValidity, message, anchor);
             }
             else {
-                this.updateComplete.then(() => this.setValidity(combinedValidity, message, anchor));
+                void this.updateComplete.then(() => this.setValidity(combinedValidity, message, anchor));
             }
-            return this.internals.checkValidity();
+            return this.valid;
         }
         /**
          * Reports validity and shows native validation UI.
          *
-         * @param valToCheck Value to validate and report.
+         * @param valToCheck Value to validate and report, the field's own one when omitted.
          * @returns true if valid, false otherwise.
          */
-        reportValidity(valToCheck) {
+        reportValidity(valToCheck = this.getValueToValidate()) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.checkValidity(valToCheck);
             return this.internals.reportValidity();
@@ -180,6 +186,16 @@ export const ValidatorsMixin = (superClass) => {
                 this.requestUpdate("valid");
             }
         }
+        /**
+         * The value {@link checkValidity} validates when called without one.
+         * `FormMixin` overrides it to return `checked` for a checkable field.
+         *
+         * @returns the field's current value.
+         */
+        getValueToValidate() {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            return this.value;
+        }
         /**
          * Provides extra data to validators if needed.
          * Override in subclass.
@@ -194,6 +210,9 @@ export const ValidatorsMixin = (superClass) => {
     __decorate([
         property({ type: Boolean })
     ], ValidatorsMixinClass.prototype, "required", void 0);
+    __decorate([
+        property()
+    ], ValidatorsMixinClass.prototype, "error", void 0);
     __decorate([
         state()
     ], ValidatorsMixinClass.prototype, "valid", void 0);