@vialiq/web-components 0.1.2 → 0.2.0

package/base/focus-trap-mixin.d.ts

@@ -0,0 +1,121 @@
+import { LitElement } from 'lit';
+type Constructor<T = object> = new (...args: any[]) => T;
+/**
+ * Type-only declaration of the shape FocusTrapMixin adds to a class.
+ * `declare class` emits no runtime code — it is a TS-only contract.
+ */
+export declare class FocusTrapInterface {
+    /**
+     * Activates the focus trap.
+     * Queries all focusable elements in the shadow root (and slotted content),
+     * focuses the first one (or a provided initial target), and begins
+     * intercepting Tab / Shift+Tab to cycle focus within the component.
+     *
+     * @param initialFocus - Optional element to focus first. Defaults to the
+     *   first focusable element found in the shadow root.
+     */
+    protected _activateFocusTrap(initialFocus?: HTMLElement): void;
+    /**
+     * Deactivates the focus trap.
+     * Removes the Tab intercept and restores focus to the element that was
+     * focused immediately before `_activateFocusTrap()` was called.
+     */
+    protected _deactivateFocusTrap(): void;
+}
+/**
+ * FocusTrapMixin
+ *
+ * Traps keyboard focus within a component's shadow root.
+ * Intended for overlay components: vi-modal, vi-dialog, vi-drawer.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * HOW IT WORKS
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   activate  → snapshot pre-trap focus → focus initial element → listen Tab
+ *   Tab       → if on last focusable → wrap to first
+ *   Shift+Tab → if on first focusable → wrap to last
+ *   deactivate→ remove listener → restore pre-trap focus
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * CRITICAL: shadowRoot.activeElement vs document.activeElement
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   Inside a shadow root, `document.activeElement` returns the HOST element
+ *   (e.g. the `<vi-modal>` tag), NOT the inner focused element.
+ *   To correctly identify which inner element is focused, ALWAYS use:
+ *
+ *     this.shadowRoot!.activeElement
+ *
+ *   This is the deepest focused element within the shadow boundary.
+ *   For slotted content (light DOM children), `shadowRoot.activeElement`
+ *   returns the `<slot>` element, not the focused child — in that case,
+ *   use `document.activeElement` to get the actual slotted focused element.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * FOCUSABLE ELEMENT COLLECTION
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   Two sources are queried and merged:
+ *
+ *   1. Shadow DOM: shadowRoot.querySelectorAll(FOCUSABLE_SELECTOR)
+ *      Covers native elements (<button>, <input>, etc.) and vi-* host elements
+ *      that use FocusableMixin (vi-button, vi-input, etc.).
+ *
+ *   2. Slotted content: each <slot>.assignedElements({ flatten: true })
+ *      filtered by FOCUSABLE_SELECTOR.
+ *      Covers focusable light-DOM children slotted into the component.
+ *      Example: a <vi-button> slotted into <vi-modal>'s footer slot.
+ *
+ *   Both lists are combined and deduplicated into a single ordered array.
+ *   DOM order is preserved (querySelector returns elements in tree order).
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * USAGE
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   class ViModal extends FocusTrapMixin(ViElement) {
+ *     @property({ type: Boolean, reflect: true }) accessor open = false;
+ *
+ *     override updated(changed: PropertyValues): void {
+ *       super.updated(changed);
+ *       if (changed.has('open')) {
+ *         if (this.open) {
+ *           // Optional: pass a specific element to focus first.
+ *           // If omitted, the first focusable in the shadow root is used.
+ *           this._activateFocusTrap();
+ *         } else {
+ *           this._deactivateFocusTrap();
+ *         }
+ *       }
+ *     }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * ACCESSIBILITY CONTRACT
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   - The trapping component MUST have role="dialog" (or "alertdialog") and
+ *     aria-modal="true" so screen readers also confine their virtual cursor.
+ *   - Escape key handling is NOT part of this mixin — the component owns that
+ *     (it is component-specific: vi-modal may close on Escape, vi-drawer may not).
+ *   - The trap does NOT prevent focus from moving to the browser chrome (URL bar,
+ *     tab bar) — that is intentional and required by WCAG 2.1 SC 2.1.2.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * COMPOSITION ORDER
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   FocusTrapMixin does NOT require FocusableMixin. Most overlay components
+ *   (vi-modal, vi-drawer) are NOT themselves focusable tab stops — they are
+ *   focus containers. Use independently:
+ *
+ *     class ViModal extends FocusTrapMixin(ViElement) { ... }
+ *
+ *   If you need both (unusual — a container that is also a tab stop):
+ *
+ *     class ViPanel extends FocusTrapMixin(FocusableMixin(ViElement)) { ... }
+ */
+export declare function FocusTrapMixin<T extends Constructor<LitElement>>(Base: T): T & Constructor<FocusTrapInterface>;
+export {};
+//# sourceMappingURL=focus-trap-mixin.d.ts.map

package/base/focus-trap-mixin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-trap-mixin.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/base/focus-trap-mixin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAKjC,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEzD;;;GAGG;AACH,MAAM,CAAC,OAAO,OAAO,kBAAkB;IACrC;;;;;;;;OAQG;IACH,SAAS,CAAC,kBAAkB,CAAC,YAAY,CAAC,EAAE,WAAW,GAAG,IAAI;IAE9D;;;;OAIG;IACH,SAAS,CAAC,oBAAoB,IAAI,IAAI;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6FG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,WAAW,CAAC,UAAU,CAAC,EAC9D,IAAI,EAAE,CAAC,GACN,CAAC,GAAG,WAAW,CAAC,kBAAkB,CAAC,CA2KrC"}

package/base/focusable-mixin.d.ts

@@ -0,0 +1,82 @@
+import { LitElement } from 'lit';
+type Constructor<T = object> = new (...args: any[]) => T;
+/**
+ * Type-only declaration of the shape FocusableMixin adds to a class.
+ * Using `declare class` emits no runtime code — it exists solely to give
+ * TypeScript a concrete type to work with when extending the mixin result.
+ * This avoids the "anonymous class private member" errors that occur when
+ * TypeScript tries to inline LitElement's private fields into the return type.
+ */
+export declare class FocusableInterface {
+    protected get _focusableElement(): HTMLElement | null;
+    focus(options?: FocusOptions): void;
+    /**
+     * Enables or disables host focus participation.
+     * Call this whenever the component's `disabled` state changes so the
+     * tabIndex policy stays centralized in the mixin rather than scattered
+     * across component `updated()` hooks.
+     *
+     *   override updated(changed: PropertyValues): void {
+     *     super.updated(changed);
+     *     if (changed.has('disabled')) this._setHostFocusable(!this.disabled);
+     *   }
+     */
+    protected _setHostFocusable(enabled: boolean): void;
+}
+/**
+ * FocusableMixin
+ *
+ * Applies to all interactive Vi components. Provides:
+ *
+ *  1. `delegatesFocus: true` on the shadow root — when the host is Tab-focused
+ *     or `.focus()` is called on it, the browser routes focus to the inner
+ *     native control. Also activates `:focus` and `:focus-within` on the host.
+ *
+ *  2. A `focus()` override that delegates to `_focusableElement` so callers
+ *     can do `myInput.focus()` and it Just Works without knowing shadow internals.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * ARCHITECTURE: host is the tab stop
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   Host:          tabIndex = 0   ← consumer-visible light-DOM tab stop
+ *   Inner element: tabindex="0"   ← participates in shadow root's own tab
+ *                                   order so :focus-visible fires reliably
+ *   delegatesFocus: true          ← routes host focus → inner element
+ *
+ * This means:
+ *   - Tab → lands on host → delegatesFocus → inner element gets visual focus
+ *   - `:host(:focus)` and `:host(:focus-within)` both activate correctly
+ *   - `:focus-visible` on the inner element fires reliably for all browsers
+ *     (keyboard vs mouse distinction works without browser-specific hacks)
+ *   - `element.focus()` calls our override → inner element focused explicitly
+ *   - Consumer sets tabindex="-1" on host to remove from tab order entirely
+ *   - Consumer sets tabindex="2" for explicit ordering — just works
+ *
+ * NOTE: tabindex="0" on the inner element does NOT create a second light-DOM
+ * tab stop. Shadow DOM children only participate in the shadow root's local
+ * tab order; the host remains the single entry point from the outer document.
+ * The difference from tabindex="-1" is that :focus-visible propagation through
+ * delegatesFocus is more consistent when the delegated target is a proper
+ * sequential-focus participant.
+ *
+ * DISABLED: When the `disabled` prop changes, the component MUST sync the
+ * host's tabIndex:
+ *
+ *   override updated(changed: PropertyValues) {
+ *     super.updated(changed);
+ *     if (changed.has('disabled')) {
+ *       this.tabIndex = this.disabled ? -1 : (previous tabIndex value or 0);
+ *     }
+ *   }
+ *
+ * Usage:
+ *   class ViInput extends FocusableMixin(ViElement) {
+ *     protected override get _focusableElement() {
+ *       return this.shadowRoot?.querySelector('input') ?? null;
+ *     }
+ *   }
+ */
+export declare function FocusableMixin<T extends Constructor<LitElement>>(Base: T): T & Constructor<FocusableInterface>;
+export {};
+//# sourceMappingURL=focusable-mixin.d.ts.map

package/base/focusable-mixin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusable-mixin.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/base/focusable-mixin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAIjC,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEzD;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,kBAAkB;IACrC,SAAS,KAAK,iBAAiB,IAAI,WAAW,GAAG,IAAI,CAAC;IACtD,KAAK,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,IAAI;IACnC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;CACpD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,WAAW,CAAC,UAAU,CAAC,EAC9D,IAAI,EAAE,CAAC,GACN,CAAC,GAAG,WAAW,CAAC,kBAAkB,CAAC,CA8GrC"}

package/base/focusable-selector.d.ts

@@ -0,0 +1,80 @@
+/**
+ * FOCUSABLE_SELECTOR
+ *
+ * A CSS selector that matches all tabbable elements within a container.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * WHY CUSTOM ELEMENTS MUST BE LISTED EXPLICITLY
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * CSS cannot see through a shadow root. A generic `[tabindex]:not([tabindex="-1"])`
+ * will NOT match a `<vi-button>` even though vi-button has tabIndex=-1 on its
+ * host and tabIndex=0 on its inner <button>. The inner <button> is inside the
+ * shadow root and is invisible to an external querySelector.
+ *
+ * Each `vi-*` element listed here uses FocusableMixin, which means:
+ *   - The host has tabIndex=-1 (not a sequential tab stop itself)
+ *   - `delegatesFocus: true` routes clicks inward
+ *   - Calling `.focus()` on the host delegates to the inner control
+ *
+ * So treating the host as the focusable unit is correct — the browser's
+ * tab sequence reaches the inner control via the host, and programmatic
+ * `.focus()` on the host works because of FocusableMixin.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * MAINTENANCE RULE
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Update this file whenever a new focusable vi-* component ships.
+ * This is the SINGLE source of truth. FocusTrapMixin, any roving-tabindex
+ * manager, and a11y tests all import from here — do not duplicate this list.
+ *
+ * When adding a new component:
+ *   1. Add its tag to PHASE_1_VI_COMPONENTS or PHASE_2_VI_COMPONENTS below.
+ *   2. Uncomment it in the exported FOCUSABLE_SELECTOR when the component ships.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * USAGE
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   import { FOCUSABLE_SELECTOR } from '../base/focusable-selector.js';
+ *
+ *   // All focusables in a shadow root (native + vi-* hosts):
+ *   const focusable = [
+ *     ...this.shadowRoot!.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
+ *   ];
+ *
+ *   // Include slotted content too (for components that slot focusable children):
+ *   this.shadowRoot!.querySelectorAll('slot').forEach((slotEl) => {
+ *     (slotEl as HTMLSlotElement)
+ *       .assignedElements({ flatten: true })
+ *       .forEach((el) => {
+ *         if (el.matches(FOCUSABLE_SELECTOR)) {
+ *           focusable.push(el as HTMLElement);
+ *         }
+ *       });
+ *   });
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * DISABLED EXCLUSION RULES
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ * Native elements: :not([disabled]) excludes them from the selector.
+ * vi-* elements: :not([disabled]) excludes the host — works because vi-*
+ *   components reflect `disabled` as an attribute via @property({ reflect: true }).
+ *
+ * tabindex="-1" exclusion: intentionally NOT in this selector.
+ * Rationale: elements with tabindex="-1" are programmatically focusable
+ * but not in the sequential tab order. Whether to include them in a trap
+ * is a caller decision (FocusTrapMixin excludes them via :not([tabindex="-1"])).
+ */
+/**
+ * A CSS selector matching all tabbable elements:
+ *   - Native HTML controls (button, input, select, textarea, a, area)
+ *   - Elements with an explicit non-negative tabindex
+ *   - All focusable vi-* components (listed explicitly — see above)
+ *
+ * Disabled elements and elements with tabindex="-1" are excluded.
+ */
+export declare const FOCUSABLE_SELECTOR: string;
+//# sourceMappingURL=focusable-selector.d.ts.map

package/base/focusable-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focusable-selector.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/base/focusable-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AAiCH;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,QAInB,CAAC"}

package/base/if-non-empty.d.ts

@@ -0,0 +1,62 @@
+/**
+ * ifNonEmpty — conditional attribute directive
+ *
+ * A wrapper around Lit's `ifDefined` that additionally removes the attribute
+ * when the value is an empty string. Use this for every optional string
+ * attribute on inner native elements where `""` and "absent" have different
+ * meaning for browsers and screen readers.
+ *
+ * Problem with raw `ifDefined`:
+ *   - `ifDefined(undefined)` → removes the attribute          ✅
+ *   - `ifDefined(null)`      → removes the attribute          ✅
+ *   - `ifDefined('')`        → sets attribute to ""            ❌
+ *
+ * With `ifNonEmpty`:
+ *   - `ifNonEmpty(undefined)` → removes the attribute         ✅
+ *   - `ifNonEmpty(null)`      → removes the attribute         ✅
+ *   - `ifNonEmpty('')`        → removes the attribute         ✅
+ *   - `ifNonEmpty('hello')`   → sets attribute to "hello"     ✅
+ *
+ * Why it matters — real screen reader / browser bugs caused by `=""`:
+ *   - `placeholder=""`   → JAWS/NVDA still announce it as an empty placeholder
+ *   - `aria-label=""`    → NVDA reads "blank" instead of deriving the name elsewhere
+ *   - `aria-describedby=""`→ browsers may still look for id="" element
+ *   - `title=""`         → browsers show an empty tooltip on hover in some engines
+ *
+ * ---
+ *
+ * USAGE
+ *
+ * Import in any shadow template that has optional string attributes:
+ *
+ *   import { ifNonEmpty } from '../base/if-non-empty.js';
+ *
+ * In the template:
+ *
+ *   // ✅ Use ifNonEmpty for optional string attributes on inner native elements
+ *   <input
+ *     placeholder=${ifNonEmpty(this.placeholder)}
+ *     aria-label=${ifNonEmpty(this.label)}
+ *     aria-describedby=${ifNonEmpty(this._descriptionId)}
+ *   />
+ *
+ *   // ❌ Do NOT use for boolean attributes — Lit has ?attr=${bool} for that
+ *   // ❌ Do NOT use for property bindings — Lit has .prop=${val} for that
+ *   // ❌ Do NOT use for event bindings — Lit has @event=${handler} for that
+ *
+ * ---
+ *
+ * WHEN TO USE vs NOT USE
+ *
+ *   Use ifNonEmpty when:
+ *     - The attribute is optional (component has a prop that defaults to '')
+ *     - The inner native element is a standard HTML element (input, button, a, etc.)
+ *     - The attribute has accessibility or UI meaning when absent vs present
+ *
+ *   Skip ifNonEmpty when:
+ *     - The attribute is always required (e.g. type="button" is never absent)
+ *     - You need the attribute to literally be "" (rare, document when intentional)
+ *     - The binding is to a custom element property — use .prop=${val} instead
+ */
+export declare const ifNonEmpty: (value: string | null | undefined) => string | typeof import("lit-html").nothing;
+//# sourceMappingURL=if-non-empty.d.ts.map

package/base/if-non-empty.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"if-non-empty.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/base/if-non-empty.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,GAAG,IAAI,GAAG,SAAS,+CACC,CAAC"}

package/base/validity-mixin.d.ts

@@ -0,0 +1,231 @@
+import { LitElement } from 'lit';
+type Constructor<T = object> = new (...args: any[]) => T;
+/**
+ * Tri-state visual status for form controls.
+ *
+ * - `'default'` — no validation styling (neutral / untouched)
+ * - `'invalid'`  — red border, error colours; set by the form when validation fails
+ * - `'valid'`    — green border, success colours; set explicitly by the parent when
+ *                  it wants to confirm a correct value (independent of message)
+ *
+ * Designed to be driven from outside (Angular binding, React prop, plain JS) so
+ * the component never decides on its own that it is "valid" — that is always an
+ * explicit, intentional signal from the consuming code.
+ */
+export type ControlStatus = 'default' | 'valid' | 'invalid';
+/**
+ * Type-only declaration of the shape ValidityMixin adds to a class.
+ * `declare class` emits no runtime code — it is a TS-only contract.
+ *
+ * Properties listed here (invalid, required, validityMessage, value) must be
+ * declared as reactive `@property` accessors on the subclass. The mixin reads
+ * and writes them but cannot create them — they must exist on the concrete class
+ * for Lit's reactivity system to pick them up.
+ *
+ * _internals must be set via `this.attachInternals()` on the subclass.
+ * The class must also declare `static formAssociated = true`.
+ */
+export declare class ValidityInterface {
+    /**
+     * Visual/validation state of the control. Reflects as the `[status]` attribute.
+     * - `'default'` — no validation styling
+     * - `'invalid'`  — red border / error colours
+     * - `'valid'`    — green border / success colours
+     *
+     * Set by the mixin's constraint-validation methods AND by the consuming
+     * code/framework. The parent always controls this — the component never
+     * auto-promotes itself to `'valid'`.
+     */
+    get status(): ControlStatus;
+    set status(value: ControlStatus);
+    /** Whether a value is required. Drives the valueMissing validity flag. */
+    get required(): boolean;
+    set required(value: boolean);
+    /** The human-readable validation message displayed in the component UI. */
+    get validityMessage(): string;
+    set validityMessage(value: string);
+    /** The current component value. Read by _testValidity for required check. */
+    get value(): string;
+    set value(v: string);
+    /**
+     * ElementInternals instance. Subclass MUST declare:
+     *   protected readonly _internals = this.attachInternals();
+     * and set:
+     *   static formAssociated = true;
+     */
+    protected readonly _internals: ElementInternals;
+    /**
+     * Checks if the current value satisfies all constraints.
+     * Fires a cancelable 'invalid' event (bubbles: false) if invalid.
+     * Does NOT show browser validation tooltip.
+     * Returns true if valid.
+     */
+    checkValidity(): boolean;
+    /**
+     * Checks validity AND triggers the browser's built-in validation UI
+     * (tooltip near the field). Delegates to ElementInternals.reportValidity().
+     * Returns true if valid.
+     */
+    reportValidity(): boolean;
+    /**
+     * Sets an arbitrary custom validation message.
+     * Pass an empty string to clear the custom error and restore validity.
+     * Syncs immediately to ElementInternals so native form constraint API works.
+     */
+    setCustomValidity(message: string): void;
+    /**
+     * Returns the set of ValidityStateFlags describing why the value is invalid.
+     * Return {} (empty object) when the value is valid.
+     *
+     * The base implementation returns {} (always valid).
+     * Subclasses override this to add component-specific checks.
+     *
+     * Standard flags (all optional, all boolean):
+     *   valueMissing   — required field has no value
+     *   tooShort       — value is shorter than minlength
+     *   tooLong        — value exceeds maxlength
+     *   rangeUnderflow — numeric value < min
+     *   rangeOverflow  — numeric value > max
+     *   patternMismatch— value doesn't match pattern
+     *   typeMismatch   — value not well-formed for type (email, url, etc.)
+     *   badInput       — user input cannot be converted to a value at all
+     *   customError    — setCustomValidity() was called with a non-empty string
+     *   stepMismatch   — value doesn't conform to step
+     */
+    protected _testValidity(): Partial<ValidityStateFlags>;
+}
+/**
+ * ValidityMixin
+ *
+ * Adds the standard form validation API (`checkValidity`, `reportValidity`,
+ * `setCustomValidity`) to any form-associated Lit element.
+ *
+ * Backed by the native `ElementInternals` API so the component participates
+ * in `HTMLFormElement` constraint validation, `.elements`, and browser
+ * validation UI — exactly like a native `<input>`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * MINIMUM SUBCLASS REQUIREMENTS
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   1. Declare static formAssociated = true;
+ *      Makes the browser register this element as a form participant.
+ *
+ *   2. Attach ElementInternals:
+ *        protected readonly _internals = this.attachInternals();
+ *      Must be a field initializer (runs after super() in the constructor).
+ *
+ *   3. Declare reactive properties (MUST be @property so Lit tracks changes):
+ *        @property({ reflect: true }) accessor status: ControlStatus = 'default';
+ *        @property({ type: Boolean, reflect: true }) accessor required = false;
+ *        @property() accessor validityMessage = '';
+ *        @property() accessor value = '';
+ *
+ *   4. Sync value to internals on every value change:
+ *        override updated(changed: PropertyValues): void {
+ *          super.updated(changed);
+ *          if (changed.has('value')) {
+ *            this._internals.setFormValue(this.value);
+ *          }
+ *        }
+ *
+ *   5. Handle form reset:
+ *        formResetCallback(): void {
+ *          this.value = this.getAttribute('value') ?? '';
+ *          this.status = 'default';
+ *          this.validityMessage = '';
+ *        }
+ *
+ *   6. Handle fieldset/form disable:
+ *        formDisabledCallback(disabled: boolean): void {
+ *          this.disabled = disabled;
+ *        }
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * OVERRIDE _testValidity() FOR CUSTOM CONSTRAINTS
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   protected override _testValidity(): Partial<ValidityStateFlags> {
+ *     if (this.required && !this.value) return { valueMissing: true };
+ *     return {};
+ *   }
+ *
+ *   Chain constraints for components with multiple rules (e.g. vi-input[type="number"]):
+ *
+ *   protected override _testValidity(): Partial<ValidityStateFlags> {
+ *     if (this.required && !this.value)     return { valueMissing: true };
+ *     if (this.minlength && this.value.length < this.minlength)
+ *                                           return { tooShort: true };
+ *     if (this.maxlength && this.value.length > this.maxlength)
+ *                                           return { tooLong: true };
+ *     return {};
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * FULL USAGE EXAMPLE — vi-input
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   import { property } from 'lit/decorators.js';
+ *   import { ValidityMixin } from '../base/validity-mixin.js';
+ *   import { FocusableMixin } from '../base/focusable-mixin.js';
+ *   import { ViElement } from '../base/vi-element.js';
+ *
+ *   @customElement('vi-input')
+ *   export class ViInput extends ValidityMixin(FocusableMixin(ViElement)) {
+ *     static override formAssociated = true;
+ *     protected readonly _internals = this.attachInternals();
+ *
+   *     @property({ reflect: true }) accessor status: ControlStatus = 'default';
+ *     @property({ type: Boolean, reflect: true }) accessor required = false;
+ *     @property() accessor validityMessage = '';
+ *     @property() accessor value = '';
+ *
+ *     protected override _testValidity(): Partial<ValidityStateFlags> {
+ *       if (this.required && !this.value) return { valueMissing: true };
+ *       return {};
+ *     }
+ *
+ *     override updated(changed: PropertyValues): void {
+ *       super.updated(changed);
+ *       if (changed.has('value')) this._internals.setFormValue(this.value);
+ *     }
+ *
+ *     formResetCallback(): void {
+ *       this.value = this.getAttribute('value') ?? '';
+ *       this.status = 'default';
+ *       this.validityMessage = '';
+ *     }
+ *
+ *     formDisabledCallback(disabled: boolean): void {
+ *       this.disabled = disabled;
+ *     }
+ *   }
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * INVALID EVENT BEHAVIOUR
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   checkValidity() fires a cancelable 'invalid' event when validation fails.
+ *   The event does NOT bubble (matches native form element behaviour).
+ *   Consumer can suppress the default UI by calling event.preventDefault().
+ *
+ *   Example:
+ *     myInput.addEventListener('invalid', (e) => {
+ *       e.preventDefault(); // suppress browser tooltip
+ *       showMyCustomError(myInput.validityMessage);
+ *     });
+ *
+ * ─────────────────────────────────────────────────────────────────────────
+ * MIXIN COMPOSITION ORDER
+ * ─────────────────────────────────────────────────────────────────────────
+ *
+ *   ValidityMixin should wrap FocusableMixin (outermost):
+ *     ValidityMixin(FocusableMixin(ViElement))
+ *
+ *   Reason: ValidityMixin only adds methods (checkValidity etc.). It does not
+ *   touch shadowRootOptions or focus delegation, so order has no side-effects.
+ *   Convention is: functionality mixins wrap infrastructure mixins.
+ */
+export declare function ValidityMixin<T extends Constructor<LitElement>>(Base: T): T & Constructor<ValidityInterface>;
+export {};
+//# sourceMappingURL=validity-mixin.d.ts.map

package/base/validity-mixin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validity-mixin.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/base/validity-mixin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAIjC,KAAK,WAAW,CAAC,CAAC,GAAG,MAAM,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,iBAAiB;IAOpC;;;;;;;;;OASG;IACH,IAAI,MAAM,IAAI,aAAa,CAAC;IAC5B,IAAI,MAAM,CAAC,KAAK,EAAE,aAAa,EAAE;IAEjC,0EAA0E;IAC1E,IAAI,QAAQ,IAAI,OAAO,CAAC;IACxB,IAAI,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE;IAE7B,2EAA2E;IAC3E,IAAI,eAAe,IAAI,MAAM,CAAC;IAC9B,IAAI,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE;IAEnC,6EAA6E;IAC7E,IAAI,KAAK,IAAI,MAAM,CAAC;IACpB,IAAI,KAAK,CAAC,CAAC,EAAE,MAAM,EAAE;IAIrB;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IAIhD;;;;;OAKG;IACH,aAAa,IAAI,OAAO;IAExB;;;;OAIG;IACH,cAAc,IAAI,OAAO;IAEzB;;;;OAIG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIxC;;;;;;;;;;;;;;;;;;OAkBG;IAKH,SAAS,CAAC,aAAa,IAAI,OAAO,CAAC,kBAAkB,CAAC;CACvD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmIG;AACH,wBAAgB,aAAa,CAAC,CAAC,SAAS,WAAW,CAAC,UAAU,CAAC,EAC7D,IAAI,EAAE,CAAC,GACN,CAAC,GAAG,WAAW,CAAC,iBAAiB,CAAC,CA0FpC"}

package/base/vi-element.d.ts

@@ -0,0 +1,12 @@
+import { LitElement } from 'lit';
+/**
+ * Shared base class for Vi web components.
+ * Keep this thin — behaviour is added via mixins (FocusableMixin, FocusTrapMixin).
+ */
+export declare class ViElement extends LitElement {
+}
+/** Component size scale */
+export type ViSize = 'sm' | 'md' | 'lg';
+/** Semantic status — maps to colour tokens (success, warning, danger, info, neutral) */
+export type ViStatus = 'neutral' | 'success' | 'warning' | 'danger' | 'info';
+//# sourceMappingURL=vi-element.d.ts.map

package/base/vi-element.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vi-element.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/base/vi-element.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,KAAK,CAAC;AAEjC;;;GAGG;AACH,qBAAa,SAAU,SAAQ,UAAU;CAAG;AAE5C,2BAA2B;AAC3B,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAExC,wFAAwF;AACxF,MAAM,MAAM,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC"}

package/button/index.d.ts

@@ -0,0 +1,2 @@
+export { ViButton } from './vi-button.js';
+//# sourceMappingURL=index.d.ts.map

package/button/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../libs/web-components/src/button/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC"}