@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-radio.js

@@ -17,71 +17,73 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { live } from 'lit/directives/live.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material Design 3 Radio Button component.
+ * Componente Material Design 3 Radio Button (Botón de Opción).
  *
- * Radio buttons allow users to select exactly one item from a set of mutually
- * exclusive options. They share the same visual architecture as
- * `<moni-checkbox>` but use `type="radio"` and implement group deselection.
+ * Los botones de opción permiten a los usuarios seleccionar exactamente un elemento de un conjunto de opciones
+ * mutuamente excluyentes. Comparten la misma arquitectura visual que
+ * `<moni-checkbox>` pero usan `type="radio"` e implementan la deselección de grupo.
  *
- * **M3 spec reference:** `m3-docs/components/radio/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/radio/specs.md`
  *
- * **Visual architecture (BeerCSS pattern):**
- * Identical to the checkbox pattern: the native `<input type="radio">` occupies
- * real layout space at `--_size` × `--_size` but is hidden via `opacity: 0`.
- * A sibling `<span>` renders:
- * - `::before` — the radio icon (`radio_button_unchecked` / `radio_button_checked`).
- * - `::after`  — the hover/focus ripple ring.
+ * **Arquitectura visual (Patrón BeerCSS):**
+ * Idéntico al patrón de checkbox: el `<input type="radio">` nativo ocupa
+ * espacio de diseño real a `--_size` × `--_size` pero se oculta mediante `opacity: 0`.
+ * Un `<span>` hermano renderiza:
+ * - `::before` — el icono de radio (`radio_button_unchecked` / `radio_button_checked`).
+ * - `::after`  — el anillo de onda (ripple) de hover/foco.
  *
- * **Group deselection:**
- * When a radio is checked, `_onChange` queries the component's `getRootNode()`
- * for all `moni-radio` elements sharing the same `name` attribute and sets
- * their `checked` property to `false`. This mirrors native browser behavior
- * for radio groups across shadow DOM boundaries where `name` grouping does
- * not work natively.
+ * **Deselección de grupo:**
+ * Cuando se marca un radio, `_onChange` consulta el `getRootNode()` del componente
+ * para encontrar todos los elementos `moni-radio` que comparten el mismo atributo `name` y establece
+ * su propiedad `checked` en `false`. Esto refleja el comportamiento nativo del navegador
+ * para grupos de radio a través de los límites del shadow DOM, donde la agrupación por `name` no
+ * funciona de forma nativa.
  *
- * @fires change - Bubbles and is composed. Fired when this radio is selected.
- *                 Read `element.checked` for the new state.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando este radio es seleccionado.
+ *                 Lee `element.checked` para obtener el nuevo estado.
  *
  * @example
  * ```html
- * <moni-radio name="color" value="red"   label="Red"></moni-radio>
- * <moni-radio name="color" value="green" label="Green"></moni-radio>
- * <moni-radio name="color" value="blue"  label="Blue" checked></moni-radio>
+ * <moni-radio name="color" value="red"   label="Rojo"></moni-radio>
+ * <moni-radio name="color" value="green" label="Verde"></moni-radio>
+ * <moni-radio name="color" value="blue"  label="Azul" checked></moni-radio>
  * ```
  *
- * @csspart radio - The outer `<label>` element.
+ * @csspart radio - El elemento `<label>` exterior.
  */
 let MoniRadio = class MoniRadio extends MoniElement {
+    static { MoniRadio_1 = this; }
+    static { this.formAssociated = true; }
     constructor() {
-        super(...arguments);
+        super();
         /**
-         * Text label displayed to the right of the radio icon.
+         * Etiqueta de texto mostrada a la derecha del icono de radio.
          *
-         * When non-empty, renders as a text node. When empty, the default slot
-         * is rendered, allowing slotted HTML content as the label.
+         * Cuando no está vacía, se renderiza como un nodo de texto. Cuando está vacía, se renderiza la ranura (slot)
+         * por defecto, permitiendo contenido HTML en la ranura como etiqueta.
          *
          * @default ''
          */
         this.label = '';
         /**
-         * Whether this radio button is currently selected.
+         * Indica si este botón de opción está actualmente seleccionado.
          *
-         * Reflected as an attribute so CSS selectors can target it. Synced to
-         * the native input via `updated()`.
+         * Se refleja como un atributo para que los selectores CSS puedan apuntarlo. Se sincroniza con
+         * el input nativo a través de `updated()`.
          *
          * @default false
          */
         this.checked = false;
         /**
-         * When `true`, the radio is non-interactive and renders at 50% opacity.
+         * Cuando es `true`, el radio no es interactivo y se renderiza a un 50% de opacidad.
          *
          * @default false
          */
         this.disabled = false;
         /**
-         * Visual size of the radio icon and its invisible hit area.
+         * Tamaño visual del icono de radio y su área de interacción (hit area) invisible.
          *
-         * | Value      | `--_size` |
+         * | Valor      | `--_size` |
          * |------------|-----------|
          * | `'small'`  | 1rem      |
          * | `'medium'` | 1.5rem    |
@@ -92,34 +94,36 @@ let MoniRadio = class MoniRadio extends MoniElement {
          */
         this.size = 'medium';
         /**
-         * Radio group name. Radios with the same `name` in the same root node
-         * are treated as a mutual-exclusion group by `_onChange`.
+         * Nombre del grupo de radio. Los radios con el mismo `name` en el mismo nodo raíz
+         * se tratan como un grupo de exclusión mutua por `_onChange`.
          *
-         * Note: Native `<input type="radio">` groups only work within the same
-         * document root. Since `moni-radio` uses shadow DOM, the deselection
-         * of siblings is handled imperatively in `_onChange`.
+         * Nota: Los grupos nativos de `<input type="radio">` solo funcionan dentro de la misma
+         * raíz de documento. Dado que `moni-radio` usa shadow DOM, la deselección
+         * de los hermanos se maneja imperativamente en `_onChange`.
          *
          * @default ''
          */
         this.name = '';
         /**
-         * Forwarded to the native `<input value>` attribute.
-         * The value submitted in a form when this radio is selected.
+         * Se retransmite al atributo nativo `<input value>`.
+         * El valor enviado en un formulario cuando este radio es seleccionado.
          *
          * @default ''
          */
         this.value = '';
+        this._internals = this.attachInternals();
     }
-    static { MoniRadio_1 = this; }
     /**
-     * Syncs `checked` and `disabled` to the native input after each render cycle.
+     * Sincroniza `checked` y `disabled` con el input nativo después de cada ciclo de renderizado.
      *
-     * @param changed - Map of changed property names to their previous values.
+     * @param changed - Mapa de los nombres de propiedades modificadas con sus valores anteriores.
      */
     updated(changed) {
         if (this._input) {
-            if (changed.has('checked'))
+            if (changed.has('checked')) {
                 this._input.checked = this.checked;
+                this._internals?.setFormValue?.(this.checked ? (this.value || 'on') : null);
+            }
             if (changed.has('disabled'))
                 this._input.disabled = this.disabled;
         }
@@ -236,17 +240,17 @@ let MoniRadio = class MoniRadio extends MoniElement {
 		`
     ]; }
     /**
-     * Handles the native input `change` event.
+     * Maneja el evento nativo `change` del input.
      *
-     * On selection, deselects all sibling `moni-radio` elements with the same
-     * `name` in the same root node (document or shadow root). This is necessary
-     * because native radio group exclusion only works within the same document
-     * root and does not cross shadow DOM boundaries.
+     * Al seleccionarse, deselecciona todos los elementos `moni-radio` hermanos con el mismo
+     * `name` en el mismo nodo raíz (documento o raíz shadow). Esto es necesario
+     * porque la exclusión de grupo de radio nativa solo funciona dentro de la misma raíz
+     * de documento y no cruza los límites del shadow DOM.
      *
-     * After deselection, dispatches a composed `'change'` event so it is
-     * audible to parent elements in the light DOM.
+     * Después de la deselección, despacha un evento `'change'` compuesto para que sea
+     * audible para los elementos padres en el DOM ligero (light DOM).
      *
-     * @param e - The native `change` event from the hidden `<input>`.
+     * @param e - El evento nativo `change` del `<input>` oculto.
      */
     _onChange(e) {
         this.checked = e.target.checked;
@@ -263,6 +267,15 @@ let MoniRadio = class MoniRadio extends MoniElement {
         }
         this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
     }
+    /**
+     * Renderiza el radio como un `<input type="radio">` oculto + indicador visual `<span>`.
+     *
+     * El input oculto se mantiene en el DOM (opacity: 0) para participar en el envío nativo
+     * de formularios y exclusión de grupo de radios. Los navegadores aplican automáticamente
+     * exclusión mutua entre entradas de radio que comparten el mismo atributo `name`.
+     * El círculo visual es dibujado por los pseudo-elementos `::before` / `::after` en
+     * el `<span>` y animado mediante transiciones CSS de `scale`.
+     */
     render() {
         return html `<label part="radio">
 			<input

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

@@ -6,135 +6,150 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Visual-only ripple decoration component.
+ * Componente de decoración de onda (ripple) puramente visual.
  *
- * Provides a pointer-origin ripple animation — the expanding circle starts
- * at the exact pointer-down coordinates rather than the element's center.
- * This is the full-fidelity M3 ripple; for a simpler CSS-only center-ripple,
- * use the `interactionStyles` `.interactive::after` pseudo-element instead.
+ * Proporciona una animación de onda con origen en el puntero: el círculo expansivo comienza
+ * en las coordenadas exactas donde se pulsó (pointer-down) en lugar de en el centro del elemento.
+ * Esta es la onda M3 de alta fidelidad; para una onda central más simple solo con CSS,
+ * usa el pseudo-elemento `.interactive::after` de `interactionStyles` en su lugar.
  *
- * **Usage:**
- * Drop `<moni-ripple>` as a **child** of any interactive element. The component
- * automatically attaches a `pointerdown` listener to its `parentElement` and
- * calculates the ripple origin in percentage coordinates relative to the parent.
+ * **Uso:**
+ * Coloca `<moni-ripple>` como **hijo** de cualquier elemento interactivo. El componente
+ * adjunta automáticamente un listener de `pointerdown` a su `parentElement` y
+ * calcula el origen de la onda en coordenadas porcentuales relativas al padre.
  *
- * The parent element must NOT have `position: static` (the ripple applies
- * `position: relative` automatically in `connectedCallback`).
+ * El elemento padre NO debe tener `position: static` (la onda aplica
+ * `position: relative` automáticamente en `connectedCallback`).
  *
- * **Timing model:**
- * On `pointerdown`:
- * 1. `active = false` is set (cancels any in-progress ripple).
- * 2. A `requestAnimationFrame` tick ensures the browser has processed the reset.
- * 3. `active = true` triggers the CSS scale animation.
- * 4. A `setTimeout` of `duration` ms (based on `speed`) resets `active = false`.
+ * **Modelo de tiempo:**
+ * En `pointerdown`:
+ * 1. Se establece `active = false` (cancela cualquier onda en progreso).
+ * 2. Un tick de `requestAnimationFrame` asegura que el navegador haya procesado el reinicio.
+ * 3. `active = true` activa la animación de escala CSS.
+ * 4. Un `setTimeout` de duración `duration` ms (basado en `speed`) reinicia `active = false`.
  *
- * The duration matches the CSS transition duration so the opacity fade-out
- * completes before `active` is cleared.
+ * La duración coincide con la duración de la transición CSS para que el desvanecimiento de la opacidad
+ * se complete antes de que se limpie `active`.
  *
- * **Cleanup:**
- * `disconnectedCallback` removes the `pointerdown` listener and clears any
- * pending timeout. Always call `super.disconnectedCallback()` if subclassing.
+ * **Limpieza (Cleanup):**
+ * `disconnectedCallback` elimina el listener de `pointerdown` y borra cualquier
+ * tiempo de espera (timeout) pendiente. Llama siempre a `super.disconnectedCallback()` si usas subclases.
  *
  * @example
  * ```html
- * <!-- Ripple on a custom element -->
+ * <!-- Onda en un elemento personalizado -->
  * <div class="my-button" style="position: relative; overflow: hidden;">
- *   Click me
+ *   Haz clic
  *   <moni-ripple color="primary"></moni-ripple>
  * </div>
  * ```
  *
- * @csspart ripple - The inner `<span>` that performs the scale animation.
+ * @csspart ripple - El `<span>` interno que realiza la animación de escala.
  */
 export declare class MoniRipple extends MoniElement {
     /**
-     * Horizontal origin of the ripple as a percentage of the parent's width.
+     * Origen horizontal de la onda como porcentaje del ancho del padre.
      *
-     * Set automatically by `_onPointerDown` based on the pointer coordinates.
-     * Can be set manually to trigger a ripple at a specific location.
+     * Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero.
+     * Se puede configurar manualmente para activar una onda en una ubicación específica.
      *
      * @default 50
      */
     x: number;
     /**
-     * Vertical origin of the ripple as a percentage of the parent's height.
+     * Origen vertical de la onda como porcentaje de la altura del padre.
      *
-     * Set automatically by `_onPointerDown` based on the pointer coordinates.
+     * Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero.
      *
      * @default 50
      */
     y: number;
     /**
-     * When `true`, the ripple is visible and animating.
+     * Cuando es `true`, la onda es visible y se está animando.
      *
-     * Toggled automatically by `_onPointerDown`. Can be set manually for
-     * programmatically-triggered ripple effects.
+     * Alternado automáticamente por `_onPointerDown`. Se puede configurar manualmente para
+     * efectos de onda disparados programáticamente.
      *
      * @default false
      */
     active: boolean;
     /**
-     * Animation speed of the ripple expand-and-fade sequence.
+     * Velocidad de animación de la secuencia de expansión y desvanecimiento de la onda.
      *
-     * Maps to the `--_dur` CSS custom property:
+     * Se asigna a la propiedad personalizada CSS `--_dur`:
      * - `'fast'`   — 300ms
-     * - `'normal'` — 600ms (default)
+     * - `'normal'` — 600ms (por defecto)
      * - `'slow'`   — 1200ms
      *
      * @default 'normal'
      */
     speed: 'fast' | 'normal' | 'slow';
     /**
-     * Color token for the ripple overlay.
+     * Token de color para la superposición de la onda.
      *
-     * Sets the `color` CSS property on `:host`, which the `.ripple` span
-     * inherits via `background-color: currentColor`.
+     * Establece la propiedad CSS `color` en `:host`, que el span `.ripple`
+     * hereda a través de `background-color: currentColor`.
      *
-     * - `'primary'`   — `--primary` (default)
+     * - `'primary'`   — `--primary` (por defecto)
      * - `'secondary'` — `--secondary`
-     * - `'surface'`   — `--surface-variant` (subtle, for surface containers)
+     * - `'surface'`   — `--surface-variant` (sutil, para contenedores de superficie)
      *
      * @default 'primary'
      */
     color: 'primary' | 'secondary' | 'surface';
     /**
-     * Reference to the parent element that the ripple is anchored to.
-     * Populated in `connectedCallback`, cleared in `disconnectedCallback`.
+     * Referencia al elemento padre al que está anclada la onda.
+     * Poblado en `connectedCallback`, borrado en `disconnectedCallback`.
      */
     private _target;
     /**
-     * ID of the pending `setTimeout` that clears `active` after the animation.
-     * Stored so it can be cancelled if a second pointer event fires before the
-     * first ripple finishes (rapid double-tap prevention).
+     * ID del `setTimeout` pendiente que borra `active` después de la animación.
+     * Almacenado para que pueda cancelarse si se dispara un segundo evento de puntero antes
+     * de que termine la primera onda (prevención de doble toque rápido).
      */
     private _timeoutId;
     /**
-     * Attaches the ripple to its parent element.
+     * Adjunta la onda a su elemento padre.
      *
-     * - Stores a reference to `parentElement` for pointer event listening.
-     * - Ensures the parent has `position: relative` so the ripple's `position: absolute`
-     *   stays within bounds.
-     * - Registers the `_onPointerDown` event listener.
+     * - Almacena una referencia a `parentElement` para la escucha de eventos del puntero.
+     * - Asegura que el padre tenga `position: relative` para que el `position: absolute`
+     *   de la onda se mantenga dentro de los límites.
+     * - Registra el listener de eventos `_onPointerDown`.
      */
     connectedCallback(): void;
     /**
-     * Detaches the ripple from its parent element.
+     * Desvincula la onda de su elemento padre.
      *
-     * Removes the `pointerdown` listener and clears any pending timeout to
-     * prevent the `active` flag from being set after the element is removed.
+     * Elimina el listener de `pointerdown` y borra cualquier timeout pendiente para
+     * evitar que la bandera `active` se establezca después de que se elimine el elemento.
      */
     disconnectedCallback(): void;
     /**
-     * Handles pointer-down events on the parent element.
+     * Maneja los eventos de puntero (pointer-down) en el elemento padre.
      *
-     * Computes the ripple origin as a percentage of the parent's bounding rect,
-     * cancels any in-progress ripple, then triggers a new one after one
-     * animation frame to guarantee the CSS transition fires from the new position.
+     * Calcula el origen de la onda como un porcentaje del rectángulo delimitador (bounding rect) del padre,
+     * cancela cualquier onda en curso y luego activa una nueva después de un
+     * frame de animación para garantizar que la transición CSS se dispare desde la nueva posición.
      *
-     * @param e - The `PointerEvent` from the parent's `pointerdown` listener.
+     * @param e - El `PointerEvent` del listener `pointerdown` del padre.
      */
     private _onPointerDown;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderiza el elemento `<span>` de la onda con las coordenadas de origen actuales.
+     *
+     * Este método de renderizado intencionalmente hace muy poco: la onda es fundamentalmente
+     * una animación CSS (`scale`, `opacity`) impulsada por la clase `.active` que es
+     * alternada por la API de activación de JavaScript (`MoniRipple.activate()`).
+     *
+     * `--_x` y `--_y` inyectan el origen del toque/clic como valores porcentuales:
+     * - `x=0%, y=0%` — la onda se origina desde la esquina superior izquierda.
+     * - `x=50%, y=50%` — origen central (por defecto para activación por teclado).
+     * - `x=clientX%, y=clientY%` — onda con origen en el puntero para una sensación táctil natural.
+     *
+     * La clase CSS `.ripple` maneja la animación de expansión `scale(0)` → `scale(1)`
+     * y el desvanecimiento `opacity 1` → `opacity 0` a través de transiciones CSS en `.active`.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-ripple.d.ts","sourceRoot":"","sources":["../../src/components/moni-ripple.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C;;;;;;;OAOG;IACwC,CAAC,SAAM;IAElD;;;;;;OAMG;IACwC,CAAC,SAAM;IAElD;;;;;;;OAOG;IACyC,MAAM,UAAS;IAE3D;;;;;;;;;OASG;IAEH,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAY;IAE7C;;;;;;;;;;;OAWG;IAEH,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAa;IAEvD;;;OAGG;IACH,OAAO,CAAC,OAAO,CAA4B;IAE3C;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;;;OAOG;IACM,iBAAiB;IAY1B;;;;;OAKG;IACM,oBAAoB;IAU7B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc,CAqBpB;IAEF,OAAgB,MAAM,4BAqDpB;IAEO,MAAM;CAOf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"moni-ripple.d.ts","sourceRoot":"","sources":["../../src/components/moni-ripple.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C;;;;;;;OAOG;IACwC,CAAC,SAAM;IAElD;;;;;;OAMG;IACwC,CAAC,SAAM;IAElD;;;;;;;OAOG;IACyC,MAAM,UAAS;IAE3D;;;;;;;;;OASG;IAEH,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAY;IAE7C;;;;;;;;;;;OAWG;IAEH,KAAK,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAa;IAEvD;;;OAGG;IACH,OAAO,CAAC,OAAO,CAA4B;IAE3C;;;;OAIG;IACH,OAAO,CAAC,UAAU,CAAa;IAE/B;;;;;;;OAOG;IACM,iBAAiB;IAY1B;;;;;OAKG;IACM,oBAAoB;IAU7B;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc,CAqBpB;IAEF,OAAgB,MAAM,4BAqDpB;IAEF;;;;;;;;;;;;;;OAcG;IACM,MAAM;CAOf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}