@moni-labs/moni-ui 0.3.1 → 0.3.2

package/dist/components/moni-text-field.js

@@ -15,90 +15,214 @@ import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
+import { emitMoniEvent } from '../utils/event-emitter.js';
 import './moni-icon.js';
 import './moni-progress.js';
 /**
- * Material Design 3 Text Field component.
+ * Componente Material Design 3 Text Field (Campo de texto).
  *
- * A full-featured input field that wraps a native `<input>` inside the M3
- * field shell (`.field` class from `fieldStyles`). Supports floating labels,
- * filled and outlined variants, leading/trailing icons, helper text, and
- * error states.
+ * Un campo de entrada con todas las funciones que envuelve un `<input>` nativo dentro de la
+ * estructura de campo M3 (clase `.field` de `fieldStyles`). Soporta etiquetas flotantes,
+ * variantes llenas (filled) y contorneadas (outlined), iconos iniciales/finales (leading/trailing),
+ * texto de ayuda y estados de error.
  *
- * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/text-fields/specs.md`
  *
- * **Visual architecture:**
- * Uses `fieldStyles` for the complete CSS field shell. The field container
- * is a `<div class="field [modifiers]">` wrapping:
- * 1. Optional leading icon.
- * 2. Native `<input>` element.
- * 3. Floating `<label>` (when `label` is set).
- * 4. Optional trailing icon or loading spinner.
- * 5. `<output>` for helper/error text.
+ * **Arquitectura visual:**
+ * Utiliza `fieldStyles` para toda la estructura CSS del campo. El contenedor del campo
+ * es un `<div class="field [modifiers]">` que envuelve:
+ * 1. Icono inicial (leading) opcional.
+ * 2. Elemento `<input>` nativo.
+ * 3. `<label>` flotante (cuando se establece `label`).
+ * 4. Icono final (trailing) opcional o indicador de carga (spinner).
+ * 5. `<output>` para texto de ayuda/error.
  *
- * **Visual-only contract:**
- * This component does **not** listen to `@input` events to sync the `value`
- * attribute back from the underlying `<input>`. Consumers must either:
- * - Submit the native form (the `<input name>` participates in form submission).
- * - Listen to `change` or `input` events via standard DOM event handling.
- * - Use a framework binding (e.g. `bind:value` in Svelte, `v-model` in Vue).
+ * **Sincronización de eventos:**
+ * Emite `moni-input` en cada tipeo y `moni-change` al consolidar el valor (blur/enter).
+ * El valor interno del componente (`this.value`) se mantiene sincronizado automáticamente.
  *
  * @example
  * ```html
  * <moni-text-field
- *   label="Email address"
+ *   label="Dirección de correo"
  *   type="email"
  *   name="email"
  *   icon="mail"
  *   variant="outlined"
- *   helper="We'll never share your email."
+ *   helper="Nunca compartiremos tu correo."
  * ></moni-text-field>
  *
  * <moni-text-field
- *   label="Amount"
+ *   label="Monto"
  *   type="number"
  *   prefix="$"
  *   error
- *   error-text="Value must be positive"
+ *   error-text="El valor debe ser positivo"
  * ></moni-text-field>
  * ```
  *
- * @csspart field         - The outer `.field` div container.
- * @csspart input         - The native `<input>` element.
- * @csspart label         - The floating `<label>` element.
- * @csspart helper        - The helper `<output>` element.
- * @csspart error-output  - The error `<output>` element.
+ * @csspart field         - El contenedor div `.field` exterior.
+ * @csspart input         - El elemento `<input>` nativo.
+ * @csspart label         - El elemento `<label>` flotante.
+ * @csspart helper        - El elemento `<output>` de ayuda.
+ * @csspart error-output  - El elemento `<output>` de error.
  */
 let MoniTextField = class MoniTextField extends MoniElement {
+    static { this.formAssociated = true; }
     constructor() {
-        super(...arguments);
+        super();
+        /**
+         * El nombre del input, enviado con los datos del formulario.
+         * @type {string}
+         */
         this.name = '';
+        /**
+         * El texto de la etiqueta flotante.
+         * @type {string}
+         */
         this.label = '';
+        /**
+         * Variante visual del campo de texto.
+         * @type {'filled' | 'outlined'}
+         * @default 'filled'
+         */
         this.variant = 'filled';
+        /**
+         * Define las dimensiones del campo de texto.
+         * @type {'small' | 'medium' | 'large' | 'extra'}
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * Forma del radio del borde (border-radius) del campo.
+         * @type {'round' | 'square' | 'no-round'}
+         * @default 'no-round'
+         */
         this.shape = 'no-round';
+        /**
+         * El tipo de input HTML nativo.
+         * @type {'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search'}
+         * @default 'text'
+         */
         this.type = 'text';
+        /**
+         * Nombre del icono inicial (leading) (Material Symbols).
+         * @type {string}
+         */
         this.icon = '';
+        /**
+         * Nombre del icono final (trailing) (Material Symbols).
+         * @type {string}
+         */
         this.trailingIcon = '';
+        /**
+         * Prefijo de texto corto mostrado antes del valor del input.
+         * @type {string}
+         */
         this.prefix = '';
+        /**
+         * Sufijo de texto corto mostrado después del valor del input.
+         * @type {string}
+         */
         this.suffix = '';
+        /**
+         * Texto de ayuda mostrado debajo del campo.
+         * @type {string}
+         */
         this.helper = '';
+        /**
+         * Texto de error mostrado debajo del campo cuando `error` es true.
+         * Sobrescribe el texto de ayuda.
+         * @type {string}
+         */
         this.errorText = '';
+        /**
+         * Si es true, establece el campo en un estado de error.
+         * @type {boolean}
+         */
         this.error = false;
+        /**
+         * Si es true, muestra un indicador de carga (progreso lineal/circular) al final.
+         * @type {boolean}
+         */
         this.loading = false;
+        /**
+         * Deshabilita el campo de texto.
+         * @type {boolean}
+         */
         this.disabled = false;
+        /**
+         * El valor actual del input.
+         * @type {string}
+         */
         this.value = '';
+        /**
+         * Texto de marcador de posición (placeholder) mostrado cuando el input está vacío y la etiqueta es flotante.
+         * @type {string}
+         */
         this.placeholder = '';
+        this._internals = this.attachInternals();
     }
+    /**
+     * Sincroniza imperativamente las propiedades DOM del `<input>` nativo después de cada actualización reactiva.
+     *
+     * Las vinculaciones `?value` y `?disabled` de Lit establecen *atributos* HTML, no *propiedades* DOM.
+     * Para un `<input>`, el atributo `value` solo establece el valor *inicial*; la propiedad DOM
+     * `input.value` refleja el valor actual tecleado por el usuario. Después de una actualización reactiva que
+     * cambia `this.value` (ej. reinicio programático), debemos escribir directamente a la propiedad
+     * DOM para sobrescribir lo que el usuario ha tecleado. Esto también es crítico para los consumidores
+     * de React y Vue que mutan la propiedad del Custom Element directamente, omitiendo el flujo
+     * de atributos de Lit.
+     *
+     * @param changed - Mapa de los nombres de propiedades a sus valores anteriores que causaron esta actualización.
+     */
     updated(changed) {
         if (this._input) {
-            if (changed.has('value'))
+            if (changed.has('value')) {
                 this._input.value = this.value;
+                this._internals?.setFormValue?.(this.value);
+            }
             if (changed.has('disabled'))
                 this._input.disabled = this.disabled;
         }
     }
+    _handleInput(e) {
+        const target = e.target;
+        this.value = target.value;
+        emitMoniEvent(this, 'moni-input', {
+            detail: { value: this.value, originalEvent: e }
+        });
+    }
+    _handleChange(e) {
+        const target = e.target;
+        this.value = target.value;
+        emitMoniEvent(this, 'moni-change', {
+            detail: { value: this.value, originalEvent: e }
+        });
+    }
     static { this.styles = [sharedStyles, fieldStyles]; }
+    /**
+     * Renderiza el campo de texto con animación de etiqueta flotante, iconos iniciales/finales, y texto de ayuda.
+     *
+     * **Composición de `fieldClasses`:**
+     * - `field` — siempre presente; diseño base del campo.
+     * - `label` — habilita el comportamiento de la etiqueta flotante vía CSS.
+     * - `fill` / `border` — variante filled vs outlined.
+     * - `small` / `large` / `extra` — modificador de tamaño.
+     * - `prefix` — desplaza la etiqueta cuando hay un icono inicial (leading) presente.
+     * - `suffix` — reserva espacio final (trailing) para el icono/texto de sufijo.
+     * - `invalid` — aplica colores de error cuando `error=true` o falla la validación nativa.
+     *
+     * **Flotación de la etiqueta (Label float):**
+     * `isActive` es true cuando `value` no está vacío o se establece un `placeholder`.
+     * Los selectores CSS `.field.label input:focus ~ label`, `.field.label.active label`
+     * flotan la etiqueta a la parte superior del borde del campo. Este componente
+     * establece `isActive` para evitar que la etiqueta colapse cuando un valor está preestablecido.
+     *
+     * **Zonas inicial / final (Leading / trailing):**
+     * `hasLeading` y `hasTrailing` añaden condicionalmente las clases CSS `prefix`/`suffix`
+     * y renderizan el icono o los elementos de texto de prefijo/sufijo.
+     */
     render() {
         const hasLeading = Boolean(this.icon) || Boolean(this.prefix);
         const hasTrailing = Boolean(this.trailingIcon) || Boolean(this.suffix);
@@ -155,6 +279,8 @@ let MoniTextField = class MoniTextField extends MoniElement {
 				.value=${this.value}
 				name=${ifDefined(this.name || undefined)}
 				class=${isActive ? 'active' : ''}
+				@input=${this._handleInput}
+				@change=${this._handleChange}
 			/>
 			${this.label
             ? html `<label

package/dist/components/moni-textarea.d.ts

@@ -8,74 +8,172 @@ import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 import './moni-progress.js';
 /**
- * Material Design 3 Textarea component.
+ * Componente Material Design 3 Textarea (Área de texto).
  *
- * A multi-line text input field designed for collecting longer amounts of text,
- * such as comments, descriptions, or messages.
+ * Un campo de entrada de texto multilínea diseñado para recolectar cantidades mayores de texto,
+ * como comentarios, descripciones o mensajes.
  *
- * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/text-fields/specs.md`
  *
- * **Visual architecture:**
- * It shares the exact same `.field` shell and styling engine as
- * `<moni-text-field>`, but internally renders a native `<textarea>` instead
- * of an `<input>`. This ensures visual consistency across all form elements
- * regarding floating labels, helper text, error states, and icons.
+ * **Arquitectura visual:**
+ * Comparte exactamente el mismo contenedor `.field` y motor de estilos que
+ * `<moni-text-field>`, pero internamente renderiza un `<textarea>` nativo en lugar
+ * de un `<input>`. Esto asegura la consistencia visual en todos los elementos del formulario
+ * en cuanto a etiquetas flotantes, texto de ayuda, estados de error e iconos.
  *
- * **Character Counter:**
- * If the `maxlength` attribute is set, the textarea automatically displays
- * a character counter (`{current length} / {maxlength}`) positioned at the
- * trailing edge of the supporting text area (bottom right). This can be
- * suppressed by setting the `no-counter` attribute.
+ * **Contador de caracteres:**
+ * Si se establece el atributo `maxlength`, el área de texto muestra automáticamente
+ * un contador de caracteres (`{longitud actual} / {maxlength}`) ubicado en el
+ * borde final (trailing) del área de texto de soporte (abajo a la derecha). Esto puede
+ * suprimirse estableciendo el atributo `no-counter`.
  *
- * **State management:**
- * This component is purely visual and presentational. It reflects attributes
- * down to the native textarea, but it does NOT attach internal `@input` or
- * `@change` listeners. Consumers should attach standard DOM listeners directly
- * to this element to capture user input, just as they would with a native
- * textarea.
+ * **Gestión del estado:**
+ * Este componente es puramente visual y representacional. Refleja los atributos
+ * hacia el textarea nativo, pero NO adjunta listeners internos para `@input` o
+ * `@change`. Los consumidores deben adjuntar listeners estándar del DOM directamente
+ * a este elemento para capturar la entrada del usuario, tal como lo harían con un
+ * textarea nativo.
  *
  * @example
  * ```html
- * <!-- Standard filled textarea -->
- * <moni-textarea label="Description" rows="4"></moni-textarea>
+ * <!-- Textarea llenado (filled) estándar -->
+ * <moni-textarea label="Descripción" rows="4"></moni-textarea>
  *
- * <!-- Outlined textarea with character counter -->
+ * <!-- Textarea contorneado (outlined) con contador de caracteres -->
  * <moni-textarea
  *   variant="outlined"
- *   label="Bio"
+ *   label="Biografía"
  *   maxlength="160"
  * ></moni-textarea>
  * ```
  *
- * @csspart field     - The outer `.field` div container.
- * @csspart input     - The native `<textarea>` element.
- * @csspart label     - The floating `<label>` element.
- * @csspart helper    - The helper/error text area.
- * @csspart counter   - The character counter element.
+ * @csspart field     - El contenedor div `.field` exterior.
+ * @csspart input     - El elemento `<textarea>` nativo.
+ * @csspart label     - El elemento `<label>` flotante.
+ * @csspart helper    - El área de texto de ayuda/error.
+ * @csspart counter   - El elemento contador de caracteres.
  */
 export declare class MoniTextarea extends MoniElement {
+    static formAssociated: boolean;
+    private _internals;
+    constructor();
+    /**
+     * El nombre del textarea, enviado con los datos del formulario.
+     * @type {string}
+     */
     name: string;
+    /**
+     * El texto de la etiqueta flotante.
+     * @type {string}
+     */
     label: string;
+    /**
+     * Variante visual del área de texto.
+     * @type {'filled' | 'outlined'}
+     * @default 'filled'
+     */
     variant: 'filled' | 'outlined';
+    /**
+     * Define las dimensiones del área de texto.
+     * @type {'small' | 'medium' | 'large' | 'extra'}
+     * @default 'medium'
+     */
     size: 'small' | 'medium' | 'large' | 'extra';
+    /**
+     * Forma del radio del borde (border-radius) del campo.
+     * @type {'round' | 'square' | 'no-round'}
+     * @default 'no-round'
+     */
     shape: 'round' | 'square' | 'no-round';
+    /**
+     * Nombre del icono inicial (leading) (Material Symbols).
+     * @type {string}
+     */
     icon: string;
+    /**
+     * Nombre del icono final (trailing) (Material Symbols).
+     * @type {string}
+     */
     trailingIcon: string;
+    /**
+     * Prefijo de texto corto mostrado antes del valor del input.
+     * @type {string}
+     */
     prefix: string;
+    /**
+     * Sufijo de texto corto mostrado después del valor del input.
+     * @type {string}
+     */
     suffix: string;
+    /**
+     * Número por defecto de líneas de texto visibles.
+     * @type {number}
+     * @default 3
+     */
     rows: number;
+    /**
+     * Número máximo de caracteres permitidos en el área de texto.
+     * También habilita la visualización del contador de caracteres a menos que `noCounter` sea true.
+     * @type {number | null}
+     */
     maxlength: number | null;
+    /**
+     * Oculta la visualización del contador de caracteres cuando se establece `maxlength`.
+     * @type {boolean}
+     */
     noCounter: boolean;
+    /**
+     * Si es true, muestra un indicador de carga (progreso circular) al final.
+     * @type {boolean}
+     */
     loading: boolean;
+    /**
+     * Deshabilita el área de texto.
+     * @type {boolean}
+     */
     disabled: boolean;
+    /**
+     * Texto de ayuda mostrado debajo del campo.
+     * @type {string}
+     */
     helper: string;
+    /**
+     * Texto de error mostrado debajo del campo cuando `error` es true.
+     * Sobrescribe el texto de ayuda.
+     * @type {string}
+     */
     errorText: string;
+    /**
+     * Si es true, establece el campo en un estado de error.
+     * @type {boolean}
+     */
     error: boolean;
+    /**
+     * El valor actual del área de texto.
+     * @type {string}
+     */
     value: string;
+    /**
+     * Texto de marcador de posición (placeholder) mostrado cuando el textarea está vacío y la etiqueta es flotante.
+     * @type {string}
+     */
     placeholder: string;
     private _input;
     updated(changed: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderiza el campo del área de texto con etiqueta, iconos de prefijo/sufijo y contador de caracteres.
+     *
+     * **Composición de `fieldClasses`:**
+     * Sigue la convención de nomenclatura field-styles. `prefix` se añade
+     * cuando el texto de `icon` o `prefix` está presente (desplaza el inicio en línea de la etiqueta).
+     * `suffix` se añade cuando `trailingIcon`, el texto `suffix` o `loading` es true.
+     *
+     * **Contador de caracteres:**
+     * `showCounter` es true cuando `maxlength > 0` y `noCounter` no está configurado.
+     * El contador muestra `${this.value.length} / ${this.maxlength}` y puede volverse rojo
+     * (vía CSS `invalid`) dependiendo de la validación.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-textarea.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-textarea.d.ts","sourceRoot":"","sources":["../../src/components/moni-textarea.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBACa,YAAa,SAAQ,WAAW;IACf,IAAI,SAAM;IACV,KAAK,SAAM;IACX,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAY;IAEvE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IACvB,IAAI,SAAM;IACkB,YAAY,SAAM;IAC9C,MAAM,SAAM;IACZ,MAAM,SAAM;IACE,IAAI,SAAK;IACT,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE3E,SAAS,UAAS;IAC0B,OAAO,UAAS;IAChB,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAM;IACX,WAAW,SAAM;IAE3B,OAAO,CAAC,MAAM,CAAuB;IAE/C,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAU9C,OAAgB,MAAM,4BAA+B;IAE5C,MAAM;CAkGf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}
+{"version":3,"file":"moni-textarea.d.ts","sourceRoot":"","sources":["../../src/components/moni-textarea.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAE5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBACa,YAAa,SAAQ,WAAW;IAC5C,MAAM,CAAC,cAAc,UAAQ;IAC7B,OAAO,CAAC,UAAU,CAAmB;;IAOrC;;;OAGG;IAC0B,IAAI,SAAM;IAEvC;;;OAGG;IAC0B,KAAK,SAAM;IAExC;;;;OAIG;IAC0B,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAY;IAEvE;;;;OAIG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD;;;;OAIG;IAEH,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IAEpD;;;OAGG;IAC0B,IAAI,SAAM;IAEvC;;;OAGG;IACsD,YAAY,SAAM;IAE3E;;;OAGG;IAC0B,MAAM,SAAM;IAEzC;;;OAGG;IAC0B,MAAM,SAAM;IAEzC;;;;OAIG;IACwC,IAAI,SAAK;IAEpD;;;;OAIG;IACwC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAQ;IAE3E;;;OAGG;IAEH,SAAS,UAAS;IAElB;;;OAGG;IACyC,OAAO,UAAS;IAE5D;;;OAGG;IACyC,QAAQ,UAAS;IAE7D;;;OAGG;IAC0B,MAAM,SAAM;IAEzC;;;;OAIG;IACmD,SAAS,SAAM;IAErE;;;OAGG;IACyC,KAAK,UAAS;IAE1D;;;OAGG;IAC0B,KAAK,SAAM;IAExC;;;OAGG;IAC0B,WAAW,SAAM;IAE3B,OAAO,CAAC,MAAM,CAAuB;IAE/C,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAa9C,OAAgB,MAAM,4BAA+B;IAErD;;;;;;;;;;;;OAYG;IACM,MAAM;CAkGf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD;AAED,eAAe,YAAY,CAAC"}