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

package/dist/mixins/form.mixin.js

@@ -13,14 +13,36 @@ 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",
+    "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;
@@ -53,6 +75,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.
@@ -89,10 +118,29 @@ 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 : invalid, not disabled,
+         * not `hideError`, and either interacted with (`touched`, `dirty`),
+         * checked by its form, or given an external `error`. A required field
+         * left empty stays quiet until then.
+         */
+        get showError() {
+            return (!this.valid &&
+                !this.hideError &&
+                !this.disabled &&
+                (this.touched || this.dirty || 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 +198,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 showError} 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.showError) {
+                return this.hint;
             }
             if (this.errorMessages.length) {
                 return this.errorMessages;
@@ -179,6 +227,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 +253,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 +262,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,10 +276,9 @@ 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);
         }
@@ -282,6 +340,7 @@ export const FormMixin = (superClass) => {
             }
             this.dirty = false;
             this.touched = false;
+            this.validationRequested = false;
         }
         /**
          * Renders the description or error messages.
@@ -292,30 +351,23 @@ 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 showError} 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.showError) {
                 return html `
           <p id="description" class="hint-messages">
             <span>${description}</span>
           </p>
         `;
             }
-            if (this.valid ||
-                this.hideError ||
-                this.disabled ||
-                !description?.length) {
-                return nothing;
-            }
             return html `
         <p id="description" class="error-messages">
           ${when(Array.isArray(description), () => description.map((msg) => html `<span>${msg}</span>`), () => html `<span>${description}</span>`)}
@@ -323,7 +375,7 @@ export const FormMixin = (superClass) => {
       `;
         }
     }
-    _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 })
@@ -343,6 +395,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/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.
@@ -54,7 +55,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 +106,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));
             }
         }
         /**

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);

package/dist/ssr/animate-ssr.css

@@ -1,84 +1,39 @@
-/**
- * Optional light-DOM stylesheet for `<eun-animate>` in server-rendered
- * pages (Next.js, or any framework/setup without Declarative Shadow DOM
- * for Lit components). It closes the SSR flash described in the eun-animate
- * documentation's Accessibility/SSR notes : server HTML has no Shadow DOM
- * yet, so `<eun-animate>`'s own `:host([animation="fade"]) { opacity: 0 }`
- * (and the other animation variants) can't apply until the element is
- * upgraded client-side, meaning content renders visible first, then snaps
- * hidden the instant the custom element registers, then fades back in.
- *
- * This stylesheet lives in the host document instead, applying the exact
- * same starting state through `:not(:defined)`, which is true from first
- * paint and stops matching permanently the moment the browser upgrades the
- * element — handing off to the component's own Shadow DOM styles at
- * exactly the point they take over, with no gap and no double transition.
- *
- * Usage — link it in the page `<head>`, alongside (not instead of)
- * importing "@eunomia/elements/animate.js" :
- *
- *   <link
- *     rel="stylesheet"
- *     href="node_modules/@eunomia/elements/dist/ssr/animate-ssr.css"
- *   />
- *
- * Requires every server-rendered `<eun-animate>` to write its `animation`
- * attribute explicitly (even when it's the "fade" default), since that
- * default only ever becomes an attribute once Lit initializes the
- * property client-side — invisible to this stylesheet, or any plain CSS,
- * before then :
- *
- *   <eun-animate animation="fade">...</eun-animate>
- */
-
 eun-animate:not(:defined) {
   --_distance: var(--animate-distance, 80px);
 }
 
-eun-animate[animation="fade"]:not(:defined),
-eun-animate[animation="faded-scroll-right"]:not(:defined),
-eun-animate[animation="faded-scroll-left"]:not(:defined),
-eun-animate[animation="faded-scroll-top"]:not(:defined),
-eun-animate[animation="faded-scroll-bottom"]:not(:defined) {
-  opacity: 0;
-}
+@media (scripting: enabled) {
+  eun-animate:not([animation]):not(:defined),
+  eun-animate[animation="fade"]:not(:defined),
+  eun-animate[animation="faded-scroll-right"]:not(:defined),
+  eun-animate[animation="faded-scroll-left"]:not(:defined),
+  eun-animate[animation="faded-scroll-top"]:not(:defined),
+  eun-animate[animation="faded-scroll-bottom"]:not(:defined) {
+    opacity: 0;
+  }
 
-eun-animate[animation="scroll-right"]:not(:defined),
-eun-animate[animation="faded-scroll-right"]:not(:defined) {
-  transform: translateX(calc(-1 * var(--_distance)));
-}
+  eun-animate[animation="scroll-right"]:not(:defined),
+  eun-animate[animation="faded-scroll-right"]:not(:defined) {
+    transform: translateX(calc(-1 * var(--_distance)));
+  }
 
-eun-animate[animation="scroll-left"]:not(:defined),
-eun-animate[animation="faded-scroll-left"]:not(:defined) {
-  transform: translateX(var(--_distance));
-}
+  eun-animate[animation="scroll-left"]:not(:defined),
+  eun-animate[animation="faded-scroll-left"]:not(:defined) {
+    transform: translateX(var(--_distance));
+  }
 
-eun-animate[animation="scroll-top"]:not(:defined),
-eun-animate[animation="faded-scroll-top"]:not(:defined) {
-  transform: translateY(var(--_distance));
-}
+  eun-animate[animation="scroll-top"]:not(:defined),
+  eun-animate[animation="faded-scroll-top"]:not(:defined) {
+    transform: translateY(var(--_distance));
+  }
 
-eun-animate[animation="scroll-bottom"]:not(:defined),
-eun-animate[animation="faded-scroll-bottom"]:not(:defined) {
-  transform: translateY(calc(-1 * var(--_distance)));
+  eun-animate[animation="scroll-bottom"]:not(:defined),
+  eun-animate[animation="faded-scroll-bottom"]:not(:defined) {
+    transform: translateY(calc(-1 * var(--_distance)));
+  }
 }
 
-/**
- * `tablet-animation`/`mobile-animation` overrides, mirroring the rules
- * above and the same-named `@media` blocks in the component's own
- * `animate.styles.ts` — kept in sync by hand, since this file has to
- * duplicate the shadow DOM's styles for the light-DOM pre-hydration
- * window regardless. Placed after the unscoped rules above so an
- * equal-specificity tie (e.g. both `animation="fade"` and
- * `tablet-animation="none"` set at once) resolves in the narrower
- * breakpoint's favor, once its `@media` condition is true — same
- * source-order reasoning as `animate.styles.ts`.
- *
- * `max-width` values match `EUNOMIA_BREAKPOINTS.tablet`/`.mobile`
- * (`breakpoints.ts`) — hardcoded here since plain CSS can't read a JS
- * constant.
- */
-@media (max-width: 768px) {
+@media (scripting: enabled) and (width < 768px) {
   eun-animate[tablet-animation="none"]:not(:defined) {
     opacity: 1;
     transform: none;
@@ -113,7 +68,7 @@ eun-animate[animation="faded-scroll-bottom"]:not(:defined) {
   }
 }
 
-@media (max-width: 600px) {
+@media (scripting: enabled) and (width < 600px) {
   eun-animate[mobile-animation="none"]:not(:defined) {
     opacity: 1;
     transform: none;