@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-progress.js

@@ -14,119 +14,122 @@ import { html, css, svg, nothing } from 'lit';
 import { customElement, property, state } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material Design 3 Progress Indicator component.
+ * Componente Material Design 3 Progress Indicator (Indicador de Progreso).
  *
- * Progress indicators express an unspecified wait time or display the length
- * of a process. They inform users about the status of ongoing processes such
- * as loading an app, submitting a form, or saving updates.
+ * Los indicadores de progreso expresan un tiempo de espera no especificado o muestran la duración
+ * de un proceso. Informan a los usuarios sobre el estado de procesos en curso, como
+ * cargar una aplicación, enviar un formulario o guardar actualizaciones.
  *
- * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/progress-indicators/specs.md`
  *
- * **Variants:**
- * - `linear` (default) — A horizontal bar that fills left-to-right.
- * - `circular` — A circular SVG stroke indicator.
- * - `wavy` — An animated wave bar (Moni extension; not in M3 spec).
- * - `circular-wavy` — Circular + wave combo (Moni extension).
+ * **Variantes:**
+ * - `linear` (por defecto) — Una barra horizontal que se llena de izquierda a derecha.
+ * - `circular` — Un indicador circular SVG de trazo (stroke).
+ * - `wavy` — Una barra de ondas animada (extensión de Moni; no en la especificación M3).
+ * - `circular-wavy` — Combinación de circular + ondas (extensión de Moni).
  *
- * **Shadow DOM compatibility note:**
- * BeerCSS's progress uses native `<progress>` pseudo-elements (`::before`,
- * `::after`, `::webkit-progress-value`) and `mask-image`, which are blocked
- * by the UA shadow root in Chrome/Firefox. This component uses a plain `<div>`
- * wrapper that replicates the visual rules exactly, and an `<svg>` element
- * for the circular variant using SVG stroke-dashoffset animation for superior
- * cross-browser support compared to `conic-gradient`.
+ * **Nota de compatibilidad con Shadow DOM:**
+ * El progreso de BeerCSS usa pseudo-elementos `<progress>` nativos (`::before`,
+ * `::after`, `::webkit-progress-value`) y `mask-image`, que son bloqueados
+ * por la raíz shadow del User Agent en Chrome/Firefox. Este componente usa un envoltorio
+ * `<div>` simple que replica las reglas visuales exactamente, y un elemento `<svg>`
+ * para la variante circular usando animación SVG stroke-dashoffset para un soporte
+ * superior entre navegadores comparado con `conic-gradient`.
  *
- * **Percentage computation:**
- * `_pct` is computed in `willUpdate()` as `(value / max) * 100`, clamped to
- * `[0, 100]`. When `indeterminate` is set, `_pct` is fixed at `50` to drive
- * the infinite loop animation.
+ * **Cálculo de porcentaje:**
+ * `_pct` se calcula en `willUpdate()` como `(value / max) * 100`, restringido a
+ * `[0, 100]`. Cuando `indeterminate` está establecido, `_pct` se fija en `50` para impulsar
+ * la animación de bucle infinito.
  *
  * @example
  * ```html
- * <!-- Determinate linear progress -->
+ * <!-- Progreso lineal determinado -->
  * <moni-progress value="65" max="100"></moni-progress>
  *
- * <!-- Indeterminate circular progress (loading spinner) -->
+ * <!-- Progreso circular indeterminado (spinner de carga) -->
  * <moni-progress variant="circular" indeterminate></moni-progress>
  * ```
  *
- * @csspart bar      - The outer container div.
- * @csspart fill     - The inner fill element (linear variant).
- * @csspart svg      - The SVG element (circular variant).
+ * @csspart bar      - El div contenedor exterior.
+ * @csspart fill     - El elemento de llenado interior (variante lineal).
+ * @csspart svg      - El elemento SVG (variante circular).
  */
 let MoniProgress = class MoniProgress extends MoniElement {
     constructor() {
         super(...arguments);
         /**
-         * Current progress value.
+         * Valor de progreso actual.
          *
-         * Must be in the range `[0, max]`. Values outside this range are clamped
-         * during percentage computation in `willUpdate()`. Ignored when
-         * `indeterminate` is set.
+         * Debe estar en el rango `[0, max]`. Los valores fuera de este rango se restringen
+         * durante el cálculo del porcentaje en `willUpdate()`. Se ignora cuando
+         * `indeterminate` está establecido.
          *
          * @default 0
          */
         this.value = 0;
         /**
-         * Maximum value of the progress range.
+         * Valor máximo del rango de progreso.
          *
-         * Defaults to `100` so `value` can be set as a percentage directly.
-         * For non-percentage ranges (e.g. steps), set `max` to the total step count
-         * and `value` to the current step.
+         * Por defecto es `100` para que el `value` pueda establecerse como porcentaje directamente.
+         * Para rangos que no son porcentajes (ej. pasos), establece `max` al recuento total de pasos
+         * y `value` al paso actual.
          *
          * @default 100
          */
         this.max = 100;
         /**
-         * Visual variant of the progress indicator.
+         * Variante visual del indicador de progreso.
          *
-         * - `'linear'` (default) — Horizontal fill bar.
-         * - `'circular'` — SVG circle with stroke-dashoffset animation.
-         * - `'wavy'` — Animated wave bar.
-         * - `'circular-wavy'` — Combination of circular and wave.
+         * - `'linear'` (por defecto) — Barra de llenado horizontal.
+         * - `'circular'` — Círculo SVG con animación stroke-dashoffset.
+         * - `'wavy'` — Barra de ondas animada.
+         * - `'circular-wavy'` — Combinación de circular y ondas.
          *
          * @default 'linear'
          */
         this.variant = 'linear';
         /**
-         * Visual size of the progress indicator.
+         * Tamaño visual del indicador de progreso.
          *
-         * - `'small'`  — Compact; suitable for inline or tight layouts.
-         * - `'medium'` — Standard M3 size (default).
-         * - `'large'`  — Prominent; for full-page loading states.
+         * - `'small'`  — Compacto; adecuado para diseños en línea o ajustados.
+         * - `'medium'` — Tamaño estándar M3 (por defecto).
+         * - `'large'`  — Prominente; para estados de carga a pantalla completa.
          *
          * @default 'medium'
          */
         this.size = 'medium';
         /**
-         * When `true`, the indicator animates in an infinite loop regardless of `value`.
+         * Cuando es `true`, el indicador se anima en un bucle infinito independientemente del `value`.
          *
-         * Use for operations where the completion percentage is unknown
-         * (e.g. network requests, file processing). When `indeterminate` is set,
-         * `_pct` is fixed at `50` to drive a continuous sweep animation.
+         * Úsalo para operaciones donde el porcentaje de finalización es desconocido
+         * (ej. peticiones de red, procesamiento de archivos). Cuando `indeterminate` está establecido,
+         * `_pct` se fija en `50` para impulsar una animación de barrido continuo.
          *
          * @default false
          */
         this.indeterminate = false;
         /**
-         * Computed fill percentage in the range `[0, 100]`.
+         * Porcentaje de llenado calculado en el rango `[0, 100]`.
          *
-         * Updated in `willUpdate()` whenever `value`, `max`, or `indeterminate` changes.
-         * Used directly in CSS custom property bindings and SVG stroke attributes.
+         * Actualizado en `willUpdate()` cada vez que cambia `value`, `max` o `indeterminate`.
+         * Usado directamente en vinculaciones de propiedades personalizadas de CSS y atributos de trazo (stroke) SVG.
          *
          * @internal
          */
         this._pct = 0;
-        /** Unique ID per instance for SVG clipPath IDs */
+        /** ID único por instancia para los IDs de SVG clipPath */
         this._instanceId = Math.random().toString(36).slice(2, 8);
     }
     /**
-     * Computes the fill percentage before each render.
+     * Hook de ciclo de vida de Lit. Calcula la fracción de llenado antes de pintar.
      *
-     * Recalculates `_pct` whenever `value`, `max`, or `indeterminate` changes.
-     * The `Math.max(1, max)` guard prevents division-by-zero when `max` is 0.
+     * A diferencia de los componentes nativos, necesitamos computar explícitamente el
+     * progreso como un número de 0 a 100 para inyectarlo en variables CSS (Lineal)
+     * o calcular el `stroke-dashoffset` (Circular).
      *
-     * @param changed - Map of property names to their previous values.
+     * Se usa `Math.max(1, this.max)` para evitar un NaN / Infinity por división entre cero.
+     *
+     * @param changed - Mapa de propiedades reactivas que detonaron la actualización.
      */
     willUpdate(changed) {
         if (changed.has('value') || changed.has('max') || changed.has('indeterminate')) {
@@ -261,6 +264,13 @@ let MoniProgress = class MoniProgress extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Motor de Renderizado: Linear Progress Bar.
+     *
+     * Renderiza un contenedor horizontal clásico. Pasa el porcentaje computado
+     * como variable CSS `--_p` para que el navegador lo interpole usando `transform: scaleX`.
+     * Expone los atributos ARIA completos para lectores de pantalla.
+     */
     _renderLinear() {
         const isIndet = this.indeterminate;
         return html `
@@ -277,6 +287,13 @@ let MoniProgress = class MoniProgress extends MoniElement {
 			</div>
 		`;
     }
+    /**
+     * Motor de Renderizado: Wavy Progress Bar (Estilo BeerCSS/Material You).
+     *
+     * Utiliza un `<svg>` con una animación de `clip-path` y ondas sinusoidales
+     * inyectadas directamente. Ajusta matemáticamente el ancho y la posición de la onda
+     * dependiendo de si está en modo indeterminado (infinito) o con un progreso específico (`_pct`).
+     */
     _renderWavy() {
         // BeerCSS wavy uses an SVG mask. We replicate with an SVG clipPath wave.
         const isIndet = this.indeterminate;
@@ -333,6 +350,15 @@ let MoniProgress = class MoniProgress extends MoniElement {
 			</div>
 		`;
     }
+    /**
+     * Algoritmo de renderizado para el spinner circular.
+     * Utiliza la técnica de SVG `stroke-dasharray` y `stroke-dashoffset` para animar o
+     * fijar el arco de progreso sin utilizar gradientes CSS cónicos (mejor compatibilidad).
+     *
+     * Matemáticas del círculo:
+     * Perímetro = 2 * π * radio.
+     * Para r=20, Perímetro ≈ 125.66. El porcentaje vacío se resta para desplazar (offset) el trazo.
+     */
     _renderCircular(withWavy = false) {
         const isIndet = this.indeterminate;
         // SVG circle math: r=20, circumference = 2π*20 ≈ 125.66
@@ -383,6 +409,24 @@ let MoniProgress = class MoniProgress extends MoniElement {
 			</div>
 		`;
     }
+    /**
+     * Despacha el renderizado al sub-renderizador privado apropiado basado en `variant`.
+     *
+     * **¿Por qué sub-renderizadores separados?**
+     * Cada variante de progreso tiene una estructura DOM fundamentalmente diferente:
+     * - Lineal: un `<div>` con un `<div>` de llenado escalado por una propiedad personalizada CSS.
+     * - Wavy (Ondulado): un `<svg>` con un `<clipPath>` animado para la máscara de onda sinusoidal.
+     * - Circular: un `<svg>` con `stroke-dasharray`/`stroke-dashoffset` para el arco.
+     *
+     * Fusionar los tres en una sola plantilla crearía un marcado profundamente condicional;
+     * dividir en `_renderLinear()`, `_renderWavy()` y `_renderCircular()` mantiene
+     * cada variante auto-contenida y permite una exposición específica de `@csspart` por variante.
+     *
+     * **`_instanceId`:**
+     * Los IDs de `<clipPath>` SVG deben ser únicos por documento; `_instanceId` es un
+     * sufijo aleatorio generado una vez en el momento de la instanciación para evitar colisiones de IDs cuando
+     * hay múltiples elementos `<moni-progress>` en la misma página.
+     */
     render() {
         switch (this.variant) {
             case 'circular':

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

@@ -6,69 +6,72 @@
  */
 import { MoniElement } 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.
  */
 export declare class MoniRadio extends MoniElement {
+    static formAssociated: boolean;
+    private _internals;
+    constructor();
     /**
-     * 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 ''
      */
     label: string;
     /**
-     * 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
      */
     checked: boolean;
     /**
-     * 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
      */
     disabled: boolean;
     /**
-     * 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    |
@@ -79,46 +82,55 @@ export declare class MoniRadio extends MoniElement {
      */
     size: 'small' | 'medium' | 'large' | 'extra';
     /**
-     * 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 ''
      */
     name: string;
     /**
-     * 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 ''
      */
     value: string;
-    /** Direct reference to the native input element for programmatic access. */
+    /** Referencia directa al elemento input nativo para acceso programático. */
     private _input;
     /**
-     * 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: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
     /**
-     * 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.
      */
     private _onChange;
+    /**
+     * 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(): import("lit").TemplateResult<1>;
 }
 declare global {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-radio.d.ts","sourceRoot":"","sources":["../../src/components/moni-radio.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBACa,SAAU,SAAQ,WAAW;IACzC;;;;;;;OAOG;IAC0B,KAAK,SAAM;IAExC;;;;;;;OAOG;IACyC,OAAO,UAAS;IAE5D;;;;OAIG;IACyC,QAAQ,UAAS;IAE7D;;;;;;;;;;;OAWG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD;;;;;;;;;OASG;IAC0B,IAAI,SAAM;IAEvC;;;;;OAKG;IAC0B,KAAK,SAAM;IAExC,4EAA4E;IAC5D,OAAO,CAAC,MAAM,CAAoB;IAElD;;;;OAIG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BA8GpB;IAEF;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;IAgBR,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,YAAY,EAAE,SAAS,CAAC;KACxB;CACD;AAED,eAAe,SAAS,CAAC"}
+{"version":3,"file":"moni-radio.d.ts","sourceRoot":"","sources":["../../src/components/moni-radio.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,qBACa,SAAU,SAAQ,WAAW;IACzC,MAAM,CAAC,cAAc,UAAQ;IAC7B,OAAO,CAAC,UAAU,CAAmB;;IAOrC;;;;;;;OAOG;IAC0B,KAAK,SAAM;IAExC;;;;;;;OAOG;IACyC,OAAO,UAAS;IAE5D;;;;OAIG;IACyC,QAAQ,UAAS;IAE7D;;;;;;;;;;;OAWG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD;;;;;;;;;OASG;IAC0B,IAAI,SAAM;IAEvC;;;;;OAKG;IAC0B,KAAK,SAAM;IAExC,4EAA4E;IAC5D,OAAO,CAAC,MAAM,CAAoB;IAElD;;;;OAIG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAU9C,OAAgB,MAAM,4BA8GpB;IAEF;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,SAAS;IAgBjB;;;;;;;;OAQG;IACM,MAAM;CAiBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,YAAY,EAAE,SAAS,CAAC;KACxB;CACD;AAED,eAAe,SAAS,CAAC"}