@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-textarea.js

@@ -18,78 +18,164 @@ import { MoniElement, sharedStyles, fieldStyles } 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.
  */
 let MoniTextarea = class MoniTextarea extends MoniElement {
+    static { this.formAssociated = true; }
     constructor() {
-        super(...arguments);
+        super();
+        /**
+         * El nombre del textarea, enviado con los datos del formulario.
+         * @type {string}
+         */
         this.name = '';
+        /**
+         * El texto de la etiqueta flotante.
+         * @type {string}
+         */
         this.label = '';
+        /**
+         * Variante visual del área de texto.
+         * @type {'filled' | 'outlined'}
+         * @default 'filled'
+         */
         this.variant = 'filled';
+        /**
+         * Define las dimensiones del área 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';
+        /**
+         * 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 = '';
+        /**
+         * Número por defecto de líneas de texto visibles.
+         * @type {number}
+         * @default 3
+         */
         this.rows = 3;
+        /**
+         * 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}
+         */
         this.maxlength = null;
+        /**
+         * Oculta la visualización del contador de caracteres cuando se establece `maxlength`.
+         * @type {boolean}
+         */
         this.noCounter = false;
+        /**
+         * Si es true, muestra un indicador de carga (progreso circular) al final.
+         * @type {boolean}
+         */
         this.loading = false;
+        /**
+         * Deshabilita el área de texto.
+         * @type {boolean}
+         */
         this.disabled = false;
+        /**
+         * 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;
+        /**
+         * El valor actual del área de texto.
+         * @type {string}
+         */
         this.value = '';
+        /**
+         * Texto de marcador de posición (placeholder) mostrado cuando el textarea está vacío y la etiqueta es flotante.
+         * @type {string}
+         */
         this.placeholder = '';
+        this._internals = this.attachInternals();
     }
     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;
             if (changed.has('maxlength') && this.maxlength != null) {
@@ -98,6 +184,19 @@ let MoniTextarea = class MoniTextarea extends MoniElement {
         }
     }
     static { this.styles = [sharedStyles, fieldStyles]; }
+    /**
+     * 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() {
         const hasLeading = Boolean(this.icon) || Boolean(this.prefix);
         const hasTrailing = Boolean(this.trailingIcon) ||
@@ -147,7 +246,7 @@ let MoniTextarea = class MoniTextarea extends MoniElement {
 							>${this.suffix}</span
 						>`
                     : nothing;
-        // M3 spec: supporting text on the left, character counter on the right.
+        // Especificación M3: texto de soporte a la izquierda, contador de caracteres a la derecha.
         const counter = showCounter
             ? html `<output part="counter" class="counter"
 						>${this.value.length} / ${this.maxlength}</output

package/dist/components/moni-time-picker.d.ts

@@ -9,40 +9,40 @@ import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 import './moni-button.js';
 /**
- * Material Design 3 Time Picker component.
+ * Componente Material Design 3 Time Picker (Selector de hora).
  *
- * A highly interactive control that allows users to select a specific time.
- * It provides two distinct input modes:
- * 1. **Dial mode:** An interactive clock face where users can drag or click
- *    to select hours and minutes.
- * 2. **Input mode:** Standard text inputs for precise keyboard entry.
+ * Un control altamente interactivo que permite a los usuarios seleccionar una hora específica.
+ * Proporciona dos modos de entrada distintos:
+ * 1. **Modo dial (analógico):** Una carátula de reloj interactiva donde los usuarios pueden arrastrar o hacer clic
+ *    para seleccionar horas y minutos.
+ * 2. **Modo input (texto):** Entradas de texto estándar para una introducción precisa por teclado.
  *
- * **M3 spec reference:** `m3-docs/components/time-pickers/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/time-pickers/specs.md`
  *
- * **Time formats & modes:**
- * - The `value` property expects and always outputs a 24-hour formatted string
- *   (`HH:MM`, e.g., `"14:30"`).
- * - Setting `use-24-hour` configures the visual presentation to use a 24-hour
- *   clock dial (inner and outer rings) and removes the AM/PM toggle. Otherwise,
- *   it uses a standard 12-hour dial with an AM/PM toggle.
+ * **Formatos de hora y modos:**
+ * - La propiedad `value` espera y siempre emite un string en formato de 24 horas
+ *   (`HH:MM`, ej. `"14:30"`).
+ * - Establecer `use-24-hour` configura la presentación visual para usar un
+ *   reloj de 24 horas (anillos interior y exterior) y elimina el selector AM/PM. De lo contrario,
+ *   utiliza un dial estándar de 12 horas con un selector AM/PM.
  *
- * **Responsive design:**
- * The `orientation` attribute configures the layout. `vertical` stacks the
- * time display above the clock face, `horizontal` places them side-by-side,
- * and `auto` responds to the container/viewport width automatically.
+ * **Diseño responsivo:**
+ * El atributo `orientation` configura el diseño. `vertical` apila la
+ * visualización de la hora sobre la carátula del reloj, `horizontal` los coloca lado a lado,
+ * y `auto` responde automáticamente al ancho del contenedor/viewport.
  *
- * @fires change - Fired when the selected time changes interactively. The
- *                 `detail.value` contains the new time in `HH:MM` format.
- * @fires cancel - Fired when the 'Cancel' button is clicked.
- * @fires ok     - Fired when the 'OK' button is clicked. The `detail.value`
- *                 contains the final confirmed time.
+ * @fires change - Se dispara cuando la hora seleccionada cambia interactivamente. El
+ *                 `detail.value` contiene la nueva hora en formato `HH:MM`.
+ * @fires cancel - Se dispara cuando se hace clic en el botón 'Cancelar'.
+ * @fires ok     - Se dispara cuando se hace clic en el botón 'OK'. El `detail.value`
+ *                 contiene la hora final confirmada.
  *
  * @example
  * ```html
- * <!-- 12-hour format (AM/PM) -->
+ * <!-- Formato 12 horas (AM/PM) -->
  * <moni-time-picker value="14:30"></moni-time-picker>
  *
- * <!-- 24-hour format -->
+ * <!-- Formato 24 horas -->
  * <moni-time-picker use-24-hour value="14:30"></moni-time-picker>
  * ```
  */
@@ -57,19 +57,109 @@ export declare class MoniTimePicker extends MoniElement {
     private currentMinute;
     private clockFaceEl?;
     private isDragging;
+    /**
+     * Hook del ciclo de vida (Lit) previo al renderizado.
+     *
+     * Si la propiedad externa `value` o el modo `use24Hour` cambian (vía binding o atributo HTML),
+     * dispara el `parseValue()` de inmediato para mantener sincronizado el estado interno de
+     * horas y minutos (y recalcular AM/PM) antes de mutar el DOM real.
+     */
     protected willUpdate(changedProperties: PropertyValues): void;
+    /**
+     * Interpreta el string `value` (formato "HH:MM") y lo descompone en enteros para
+     * el estado interno. Automáticamente corrige valores fuera de rango y determina
+     * si estamos en AM o PM (cuando no se usa formato de 24 horas).
+     */
     private parseValue;
+    /**
+     * Reconstruye el string `value` a partir del estado interno (`currentHour`, `currentMinute`).
+     * Formatea con ceros a la izquierda e incluye la lógica de conversión AM/PM a 24hrs
+     * para garantizar que el valor expuesto hacia afuera sea siempre un estándar ISO ("14:30").
+     */
     private updateValue;
+    /**
+     * Alterna el modo de interacción visual entre el Reloj Analógico (dial)
+     * y el modo de Entrada de Texto manual (input).
+     */
     private toggleMode;
+    /**
+     * Define el nivel de selección activo ('hour' o 'minute').
+     * Cambia dinámicamente qué anillo o qué matemáticas (12 vs 60 items)
+     * utilizará el componente principal y el reloj.
+     */
     private setSelection;
+    /**
+     * Cambia forzosamente el periodo del día ('AM' o 'PM') cuando el usuario
+     * presiona los conmutadores laterales (sólo visible en formato 12h).
+     * Inmediatamente propaga el cambio hacia `updateValue()` para recalcular
+     * y despachar la hora formateada.
+     */
     private setPeriod;
+    /**
+     * Inicia el proceso de arrastre en la carátula del reloj (Pointer Down).
+     * Utiliza `setPointerCapture` nativo para asegurar que el movimiento (drag) siga
+     * siendo rastreado aunque el puntero del usuario salga físicamente del contenedor,
+     * garantizando una interacción "Touch" a prueba de errores.
+     */
     private handleClockPointerDown;
+    /**
+     * Corazón matemático del reloj radial (Time Picker analógico).
+     * Convierte las coordenadas cartesianas del ratón/dedo en un ángulo polar (0-360º),
+     * y dependiendo si medimos horas o minutos, lo mapea al número correspondiente.
+     */
     private handleClockPointerMove;
+    /**
+     * Finaliza la interacción de arrastre en la carátula del reloj (Pointer Up).
+     *
+     * Como heurística de usabilidad, si el usuario acaba de seleccionar la Hora,
+     * el componente espera 300ms y automáticamente transiciona a la vista de Minutos.
+     * Esto reduce los clics necesarios en interacciones de Time Pickers de un solo toque.
+     */
     private handleClockPointerUp;
+    /**
+     * Handler para entradas directas desde el `<input>` de horas (Modo 'input' texto).
+     * Implementa clamping (límites mínimos y máximos) para asegurar que el usuario
+     * nunca pueda introducir valores erróneos mayores a 23h o menores a 0h.
+     */
     private handleHourInputChange;
+    /**
+     * Handler para entradas directas desde el `<input>` de minutos (Modo 'input' texto).
+     * Trunca cualquier input alfanumérico a enteros y realiza un clamp a 0-59.
+     */
     private handleMinuteInputChange;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderizador de la carátula circular (Dial Face).
+     *
+     * Utiliza trigonometría básica (`sin` y `cos`) para distribuir los números equitativamente
+     * a lo largo del perímetro del círculo en CSS absoluto. En formato 24h, renderiza
+     * dos anillos concéntricos manipulando el radio relativo (`50%` vs `32%`).
+     */
     private renderDialClockFace;
+    /**
+     * Renderiza el selector de hora (time picker) en modo `dial` o `input`.
+     *
+     * **Visualización 12 vs 24 horas:**
+     * `hourVal` convierte `currentHour` (0–23) al formato de visualización:
+     * - Modo 24 horas: string con ceros a la izquierda (ej. `'09'`, `'14'`).
+     * - Modo 12 horas: `0` → `12`, `13` → `1`, preservando la visualización AM/PM.
+     * `minuteVal` siempre tiene ceros a la izquierda para tener 2 dígitos.
+     *
+     * **Modo dial:**
+     * Renderiza una carátula de reloj DOM (HTML/CSS) con números distribuidos
+     * circularmente para cada hora/minuto. El sub-método `renderDialClockFace()`
+     * maneja la geometría y estilos que mueven la manecilla selectora mientras
+     * el usuario arrastra.
+     *
+     * **Modo input:**
+     * Renderiza dos elementos `<input type="number">` para la hora y el minuto con
+     * un selector AM/PM. El modo input es la alternativa (fallback) para accesibilidad
+     * y entornos no táctiles.
+     *
+     * **Alternador de modo:**
+     * Un icono de teclado cambia de modo `dial` a `input`; un icono de reloj
+     * cambia de vuelta.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-time-picker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-time-picker.d.ts","sourceRoot":"","sources":["../../src/components/moni-time-picker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,cAAc,EAAE,MAAM,KAAK,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,cAAe,SAAQ,WAAW;IACjB,KAAK,SAAW;IACyB,SAAS,UAAS;IAC3D,IAAI,EAAE,MAAM,GAAG,OAAO,CAAU;IAChC,WAAW,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAU;IAE7E,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAEb,OAAO,CAAC,WAAW,CAAC,CAAiB;IAE3D,OAAO,CAAC,UAAU,CAAS;cAER,UAAU,CAAC,iBAAiB,EAAE,cAAc;IAM/D,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,WAAW;IAwBnB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,sBAAsB;IA2C9B,OAAO,CAAC,oBAAoB;IAa5B,OAAO,CAAC,qBAAqB;IAiB7B,OAAO,CAAC,uBAAuB;IAY/B,OAAgB,MAAM,4BAqXpB;IAEF,OAAO,CAAC,mBAAmB;IAwIlB,MAAM;CAsFf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"moni-time-picker.d.ts","sourceRoot":"","sources":["../../src/components/moni-time-picker.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,cAAc,EAAE,MAAM,KAAK,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,cAAe,SAAQ,WAAW;IACjB,KAAK,SAAW;IACyB,SAAS,UAAS;IAC3D,IAAI,EAAE,MAAM,GAAG,OAAO,CAAU;IAChC,WAAW,EAAE,UAAU,GAAG,YAAY,GAAG,MAAM,CAAU;IAE7E,OAAO,CAAC,eAAe,CAA6B;IACpD,OAAO,CAAC,MAAM,CAAqB;IAEnC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAEb,OAAO,CAAC,WAAW,CAAC,CAAiB;IAE3D,OAAO,CAAC,UAAU,CAAS;IAE3B;;;;;;OAMG;cACgB,UAAU,CAAC,iBAAiB,EAAE,cAAc;IAM/D;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAoBlB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAwBnB;;;OAGG;IACH,OAAO,CAAC,UAAU;IAIlB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAMjB;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAQ9B;;;;OAIG;IACH,OAAO,CAAC,sBAAsB;IAgD9B;;;;;;OAMG;IACH,OAAO,CAAC,oBAAoB;IAa5B;;;;OAIG;IACH,OAAO,CAAC,qBAAqB;IAiB7B;;;OAGG;IACH,OAAO,CAAC,uBAAuB;IAY/B,OAAgB,MAAM,4BAqXpB;IAEF;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IAwI3B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACM,MAAM;CAsFf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}