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

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

@@ -1,5 +1,5 @@
-import { LitElement } from 'lit';
-import { Constructor } from '../utils/constructor.type.js';
+import { LitElement } from "lit";
+import { Constructor } from "../utils/constructor.type.js";
 /**
  * Interface defining the contract for components using DisabledMixin.
  */
@@ -11,7 +11,7 @@ export declare class DisabledMixinInterface {
  *
  * When the `disabled` property changes, it automatically updates:
  * - `tabindex` (to prevent focus when disabled),
- * - `aria-disabled` for accessibility.
+ * - `aria-disabled` for accessibility, only present while disabled.
  *
  * @param superClass - The base class to extend.
  * @returns A new class extending the base with `disabled` behavior.

package/dist/mixins/disabled.mixin.js

@@ -4,13 +4,13 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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 { property } from 'lit/decorators.js';
+import { property } from "lit/decorators.js";
 /**
  * A mixin that adds a `disabled` property to a LitElement component.
  *
  * When the `disabled` property changes, it automatically updates:
  * - `tabindex` (to prevent focus when disabled),
- * - `aria-disabled` for accessibility.
+ * - `aria-disabled` for accessibility, only present while disabled.
  *
  * @param superClass - The base class to extend.
  * @returns A new class extending the base with `disabled` behavior.
@@ -34,9 +34,14 @@ export const DisabledMixin = (superClass) => {
          */
         updated(_changedProperties) {
             super.updated(_changedProperties);
-            if (_changedProperties.has('disabled')) {
-                this.setAttribute('tabindex', this.disabled ? '-1' : '0');
-                this.setAttribute('aria-disabled', String(this.disabled));
+            if (_changedProperties.has("disabled")) {
+                this.setAttribute("tabindex", this.disabled ? "-1" : "0");
+                if (this.disabled) {
+                    this.setAttribute("aria-disabled", "true");
+                }
+                else {
+                    this.removeAttribute("aria-disabled");
+                }
             }
         }
     }

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

@@ -29,4 +29,4 @@ export declare class EditableMixinInterface {
  * shape (e.g. `string` for a single-value field, `string[]` for a multi-value one).
  * @returns A class extending the provided superclass with editable behavior.
  */
-export declare const EditableMixin: <U, T extends Constructor<LitElement & DisabledMixinInterface & ValidatorsMixinInterface & FormMixinInterface<U>>>(superClass: T) => Constructor<EditableMixinInterface> & T;
+export declare const EditableMixin: <U, T extends Constructor<LitElement & DisabledMixinInterface & ValidatorsMixinInterface<unknown> & FormMixinInterface<U>>>(superClass: T) => Constructor<EditableMixinInterface> & T;

package/dist/mixins/field-appearance.mixin.d.ts

@@ -0,0 +1,19 @@
+import { LitElement } from "lit";
+import { Constructor } from "../utils/constructor.type.js";
+import { EunomiaFieldAppearance } from "../types/variant.type.js";
+/**
+ * Interface defining the contract for components using FieldAppearanceMixin.
+ */
+export declare class FieldAppearanceMixinInterface {
+    appearance?: EunomiaFieldAppearance;
+}
+/**
+ * A mixin that adds an `appearance` property to a text-like form field
+ * component, controlling how its surface is drawn: bordered box
+ * (`outline`, default), muted background with no border (`flat`), or a
+ * bottom-only border (`underline`).
+ *
+ * @param superClass - The base class to extend.
+ * @returns A new class extending the base with `appearance` behavior.
+ */
+export declare const FieldAppearanceMixin: <T extends Constructor<LitElement>>(superClass: T) => Constructor<FieldAppearanceMixinInterface> & T;

package/dist/mixins/{field-variant.mixin.js → field-appearance.mixin.js}

@@ -6,27 +6,27 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { property } from "lit/decorators.js";
 /**
- * A mixin that adds a `variant` property to a text-like form field
- * component, controlling its visual style: bordered box (`outline`,
- * default), filled background with no border (`fill`), or a bottom-only
- * border (`underline`).
+ * A mixin that adds an `appearance` property to a text-like form field
+ * component, controlling how its surface is drawn: bordered box
+ * (`outline`, default), muted background with no border (`flat`), or a
+ * bottom-only border (`underline`).
  *
  * @param superClass - The base class to extend.
- * @returns A new class extending the base with `variant` behavior.
+ * @returns A new class extending the base with `appearance` behavior.
  */
-export const FieldVariantMixin = (superClass) => {
-    class FieldVariantMixinClass extends superClass {
+export const FieldAppearanceMixin = (superClass) => {
+    class FieldAppearanceMixinClass extends superClass {
         constructor() {
             super(...arguments);
             /**
-             * The visual variant to apply to the field.
+             * How the field's surface is drawn.
              * By default, set to "outline".
              */
-            this.variant = "outline";
+            this.appearance = "outline";
         }
     }
     __decorate([
         property({ reflect: true })
-    ], FieldVariantMixinClass.prototype, "variant", void 0);
-    return FieldVariantMixinClass;
+    ], FieldAppearanceMixinClass.prototype, "appearance", void 0);
+    return FieldAppearanceMixinClass;
 };

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

@@ -13,12 +13,14 @@ export declare class FormMixinInterface<T> {
     setFormValue(value?: T): void;
     renderDescription(): typeof nothing | TemplateResult;
     name?: string;
+    hint?: string;
     description?: string | string[] | undefined;
     valueState?: T;
     hideError?: boolean;
     form: HTMLFormElement | null;
     dirty: boolean;
     touched: boolean;
+    controlled: boolean;
     get pristine(): boolean;
     get untouched(): boolean;
     get value(): T;
@@ -32,4 +34,6 @@ export declare class FormMixinInterface<T> {
  * @param superClass - Base class to extend.
  * @returns A class extending the provided base with form capabilities.
  */
-export declare const FormMixin: <T extends Constructor<LitElement & ValidatorsMixinInterface & DisabledMixinInterface>, U>(superClass: T) => Constructor<FormMixinInterface<U>> & T;
+type ValidatorsMixinShape = Omit<ValidatorsMixinInterface, "validators">;
+export declare const FormMixin: <T extends Constructor<LitElement & ValidatorsMixinShape & DisabledMixinInterface>, U>(superClass: T) => Constructor<FormMixinInterface<U>> & T;
+export {};

package/dist/mixins/form.mixin.js

@@ -13,13 +13,6 @@ 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";
-/**
- * Mixin that adds form-related behavior and value management.
- *
- * @template U - Type of the form field value.
- * @param superClass - Base class to extend.
- * @returns A class extending the provided base with form capabilities.
- */
 export const FormMixin = (superClass) => {
     var _FormMixinClass_markDirty, _FormMixinClass_markTouched;
     class FormMixinClass extends superClass {
@@ -60,6 +53,23 @@ export const FormMixin = (superClass) => {
              * @default false
              */
             this.touched = false;
+            /**
+             * Opts this field out of the native reset algorithm's value wipe: when
+             * `true`, `formResetCallback` leaves `value`/`checked` untouched.
+             *
+             * Exists for consumers who drive `value` as a controlled React prop
+             * (or equivalent in another framework): a browser-native `form.reset()`
+             * cannot be observed by React's reconciler unless a prop actually
+             * changes, so a native input only "survives" a stray reset (e.g. the
+             * unconditional one `useActionState` triggers via `requestFormReset` on
+             * every `<form action={fn}>` submission, success or not) because
+             * react-dom force-resyncs its `.value` on every commit — a defense
+             * custom elements don't get. Setting `controlled` makes the field's own
+             * app state the sole source of truth for `value`: the app decides when
+             * to clear it, the same way it already decides what to display it as.
+             * @default false
+             */
+            this.controlled = false;
             /**
              * Marks the field dirty on its own `eunchange` — dispatched only from a
              * genuine user-interaction handler, never from the `value`/`checked`
@@ -255,13 +265,20 @@ export const FormMixin = (superClass) => {
          * `value` attribute. Skipping the assignment there (as an earlier
          * version of this method did) left a typed-in value stuck after
          * `form.reset()`.
+         *
+         * Skips that assignment entirely when {@link controlled} is set: the
+         * consuming app owns `value` in that mode, so this callback only clears
+         * {@link dirty}/{@link touched}, leaving the value itself for the app
+         * to update (or not) on its own terms.
          */
         formResetCallback() {
-            if (this.checkable) {
-                this.checked = false;
-            }
-            else {
-                this.value = this.defaultValue;
+            if (!this.controlled) {
+                if (this.checkable) {
+                    this.checked = false;
+                }
+                else {
+                    this.value = this.defaultValue;
+                }
             }
             this.dirty = false;
             this.touched = false;
@@ -326,6 +343,9 @@ export const FormMixin = (superClass) => {
     __decorate([
         state()
     ], FormMixinClass.prototype, "touched", void 0);
+    __decorate([
+        property({ type: Boolean })
+    ], FormMixinClass.prototype, "controlled", void 0);
     __decorate([
         property({
             attribute: "default-value",

package/dist/mixins/overflow-navigation.mixin.js

@@ -77,9 +77,10 @@ export const NavigationOverflowMixin = (superClass) => {
         }
         /**
          * Determines if the scrollable element is currently overflowing.
+         * Overridable, for content that isn't all in the `navigation` slot.
          *
          * @returns true if on overflow, false otherwise.
-         * @private
+         * @protected
          */
         isOnOverflow() {
             const slot = this.shadowRoot?.querySelector('slot[name="navigation"]');

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

@@ -28,4 +28,4 @@ export declare class RadioMixinInterface {
  * @template T A LitElement class extended with other mixins (Disabled, Readonly, Validators, Form).
  * @returns A class extending the provided superclass with radio behavior.
  */
-export declare const RadioMixin: <T extends Constructor<LitElement & DisabledMixinInterface & ReadonlyMixinInterface & ValidatorsMixinInterface & FormMixinInterface<string>>>(superClass: T) => Constructor<RadioMixinInterface> & T;
+export declare const RadioMixin: <T extends Constructor<LitElement & DisabledMixinInterface & ReadonlyMixinInterface & ValidatorsMixinInterface<unknown> & FormMixinInterface<string>>>(superClass: T) => Constructor<RadioMixinInterface> & T;

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

@@ -1,5 +1,5 @@
 import { LitElement } from "lit";
-import { Mutable } from "../types/form-validators.type.js";
+import { Mutable, Validators } from "../types/form-validators.type.js";
 import { Constructor } from "../utils/constructor.type.js";
 /**
  * Defines a Validity object.
@@ -11,8 +11,13 @@ export interface Validity {
 /**
  * Interface defining the contract for components using `ValidatorsMixin`.
  * Provides integration with the native form lifecycle,
+ *
+ * @template U Type of value being validated — same as the type parameter
+ * passed to `ValidatorsMixin` itself, kept in sync by hand at each call
+ * site since it can't be inferred from `ValidatorsMixin(superClass)`'s own
+ * single argument.
  */
-export declare class ValidatorsMixinInterface {
+export declare class ValidatorsMixinInterface<U = unknown> {
     checkLocalValidators: () => Validity;
     buildCommonValidators: () => Validity;
     checkValidity: (dataToCheck: any) => boolean;
@@ -21,6 +26,7 @@ export declare class ValidatorsMixinInterface {
     required: boolean;
     errorMessages: string[];
     validationMessage: string | string[];
+    validators?: Validators<U>[];
 }
 /**
  * Mixin that adds validation capabilities to a LitElement.
@@ -28,4 +34,4 @@ export declare class ValidatorsMixinInterface {
  * @template U Type of value being validated.
  * @param superClass Base class to extend.
  */
-export declare const ValidatorsMixin: <T extends Constructor<LitElement>, U>(superClass: T) => Constructor<ValidatorsMixinInterface> & T;
+export declare const ValidatorsMixin: <T extends Constructor<LitElement>, U>(superClass: T) => Constructor<ValidatorsMixinInterface<U>> & T;

package/dist/ssr/animate-ssr.css

@@ -1,84 +1,38 @@
-/**
- * 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[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 (max-width: 768px) {
   eun-animate[tablet-animation="none"]:not(:defined) {
     opacity: 1;
     transform: none;
@@ -113,7 +67,7 @@ eun-animate[animation="faded-scroll-bottom"]:not(:defined) {
   }
 }
 
-@media (max-width: 600px) {
+@media (scripting: enabled) and (max-width: 600px) {
   eun-animate[mobile-animation="none"]:not(:defined) {
     opacity: 1;
     transform: none;

package/dist/ssr/links-ssr.css

@@ -0,0 +1,35 @@
+:is(eun-link, eun-button, eun-card):not(:defined) > a {
+  color: inherit;
+  text-decoration: none;
+}
+
+.eun-new-tab-hint {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+:is(eun-link, eun-button):not(:defined) > a[target="_blank"]::after {
+  content: "";
+  display: inline-block;
+  width: 14px;
+  height: 14px;
+  margin-inline-start: 4px;
+  vertical-align: middle;
+  background: currentColor;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M5 13h11.17l-4.88 4.88c-.39.39-.39 1.03 0 1.42.39.39 1.02.39 1.41 0l6.59-6.59c.39-.39.39-1.02 0-1.41l-6.58-6.6c-.39-.39-1.02-.39-1.41 0-.39.39-.39 1.02 0 1.41L16.17 11H5c-.55 0-1 .45-1 1s.45 1 1 1z'/%3E%3C/svg%3E")
+    center / contain no-repeat;
+  rotate: -45deg;
+}
+
+eun-button:not(:defined) > a[target="_blank"]::after {
+  width: 12px;
+  height: 12px;
+  margin-inline-start: 8px;
+}

package/dist/ssr/overlay-ssr.css

@@ -1,44 +1,3 @@
-/**
- * Optional light-DOM stylesheet for server-rendered pages (Next.js, or
- * any framework/setup without Declarative Shadow DOM for Lit
- * components), covering every closed-by-default overlay/disclosure
- * component in one file : `eun-collapse`, `eun-drawer`, `eun-modal`,
- * `eun-dropdown-button`, and `eun-tooltip`. Each hides its own slotted
- * content only through its own Shadow DOM (a `grid-template-rows: 0fr`
- * panel for collapse, a `popover="manual"`/`popover="auto"` surface for
- * the rest), which doesn't exist yet in server-rendered HTML. That
- * content renders as plain, unstyled light-DOM children instead, on top
- * of everything else on the page, until the element upgrades — the same
- * SSR flash `animate-ssr.css`/`toolbar-ssr.css`/`sidebar-ssr.css`
- * document for their own components, just for content that's meant to
- * stay hidden until something opens it, rather than a starting animation
- * state or a persistent, always-visible layout piece.
- *
- * This stylesheet lives in the host document instead, hiding that exact
- * content through `:not(:defined)`, which is true from first paint and
- * stops matching permanently the moment the browser upgrades the
- * element — handing off to each component's own Shadow DOM at exactly
- * the point it takes over, with no gap.
- *
- * Usage — link it in the page `<head>`, alongside (not instead of)
- * importing whichever of these components the page actually uses :
- *
- *   <link
- *     rel="stylesheet"
- *     href="node_modules/@eunomia/elements/dist/ssr/overlay-ssr.css"
- *   />
- *
- * `eun-drawer`/`eun-modal` are skipped whenever `open` is written
- * explicitly in the server-rendered markup, so a dialog meant to be
- * visible on first paint (a startup announcement, for instance) still
- * renders — see the `open` attribute on the component's own doc page for
- * the same requirement `animate-ssr.css` documents for `animation`, and
- * `eun-collapse`'s own `open` attribute for the same reasoning there.
- * `eun-dropdown-button`'s own trigger label (its default slot) and
- * `eun-tooltip`'s own trigger (`slot="anchor"`) are never hidden, only
- * their menu/panel content is.
- */
-
 eun-collapse:not(:defined):not([open]) > :not([slot]) {
   display: none;
 }

package/dist/ssr/rich-text.css

@@ -0,0 +1,38 @@
+.eun-rich-text p,
+.eun-rich-text ul {
+  margin-block: 1em;
+}
+
+.eun-rich-text ul {
+  padding-inline-start: 40px;
+  list-style: disc;
+}
+
+.eun-rich-text li {
+  display: list-item;
+}
+
+.eun-rich-text :first-child {
+  margin-block-start: 0;
+}
+
+.eun-rich-text :last-child {
+  margin-block-end: 0;
+}
+
+.eun-rich-text strong {
+  font-weight: bold;
+}
+
+.eun-rich-text em {
+  font-style: italic;
+}
+
+.eun-rich-text u {
+  text-decoration: underline;
+}
+
+.eun-rich-text a {
+  color: var(--rich-text-link-color, var(--eun-color-primary-500, #3d6fff));
+  text-decoration: underline;
+}

package/dist/ssr/sidebar-ssr.css

@@ -1,41 +1,3 @@
-/**
- * Optional light-DOM stylesheet for `<eun-sidebar>` in server-rendered
- * pages (Next.js, or any framework/setup without Declarative Shadow DOM
- * for Lit components). Closes the same SSR flash described in
- * eun-toolbar's own SSR notes (see `toolbar-ssr.css`), but here it hits
- * every instance, not just a mobile-only panel : `display: flex` and the
- * sidebar's own width live in eun-sidebar's Shadow DOM, which doesn't
- * exist yet in server-rendered HTML. An unregistered custom element
- * defaults to `display: inline` with no layout of its own, so a
- * server-rendered sidebar renders as a plain run of unstyled inline
- * content (header, body, footer flowing one after another) first, then
- * snaps into a proper flex column the instant the element upgrades. A
- * sidebar meant to start `collapsed` (mini or fully hidden) makes this
- * worse : that state lives in the same Shadow DOM too, so it renders at
- * full width first, then shrinks down on upgrade instead of the other
- * way around.
- *
- * This stylesheet lives in the host document instead, mirroring
- * eun-sidebar's own resting layout through `:not(:defined)`, which is
- * true from first paint and stops matching permanently the moment the
- * browser upgrades the element — handing off to eun-sidebar's own Shadow
- * DOM styles at exactly the point they take over, with no gap.
- *
- * Usage — link it in the page `<head>`, alongside (not instead of)
- * importing "@eunomia/elements/sidebar.js" :
- *
- *   <link
- *     rel="stylesheet"
- *     href="node_modules/@eunomia/elements/dist/ssr/sidebar-ssr.css"
- *   />
- *
- * `collapsed`/`collapse-mode`/`dragged-hidden` only take effect here when
- * written explicitly in the server-rendered markup, same requirement
- * `animate-ssr.css` documents for `animation` :
- *
- *   <eun-sidebar collapsed collapse-mode="mini">...</eun-sidebar>
- */
-
 eun-sidebar:not(:defined) {
   display: flex;
   position: sticky;