@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-ripple.js

@@ -14,118 +14,118 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } 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.
  */
 let MoniRipple = class MoniRipple extends MoniElement {
     constructor() {
         super(...arguments);
         /**
-         * 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
          */
         this.x = 50;
         /**
-         * 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
          */
         this.y = 50;
         /**
-         * 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
          */
         this.active = false;
         /**
-         * 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'
          */
         this.speed = 'normal';
         /**
-         * 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'
          */
         this.color = 'primary';
         /**
-         * 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`.
          */
         this._target = null;
         /**
-         * 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).
          */
         this._timeoutId = null;
         /**
-         * 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.
          */
         this._onPointerDown = (e) => {
             if (!this._target)
@@ -150,12 +150,12 @@ let MoniRipple = class MoniRipple extends MoniElement {
         };
     }
     /**
-     * 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() {
         super.connectedCallback();
@@ -169,10 +169,10 @@ let MoniRipple = class MoniRipple extends MoniElement {
         }
     }
     /**
-     * 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() {
         if (this._target) {
@@ -237,6 +237,21 @@ let MoniRipple = class MoniRipple extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * 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() {
         return html `<span
 			class="ripple"

package/dist/components/moni-segmented-button.d.ts

@@ -6,61 +6,136 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Material Design 3 Segmented Button component (Legacy).
+ * Componente Material Design 3 Segmented Button (Botón Segmentado) (Heredado).
  *
- * A form-associated group of selectable segmented buttons.
+ * Un grupo de botones segmentados seleccionables asociado a formularios.
  *
- * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
- * has updated the segmented button pattern. The bespoke segments have been
- * replaced with standard `<moni-button>` elements grouped inside a
+ * **Aviso de obsolescencia (Deprecation Notice):** La especificación M3 (`m3-docs/components/segmented-buttons/overview.md`)
+ * ha actualizado el patrón de botones segmentados. Los segmentos a medida han sido
+ * reemplazados por elementos estándar `<moni-button>` agrupados dentro de un
  * `<moni-button-group variant="connected">`.
  *
- * This component continues to work for backward compatibility but will be
- * removed in v1.0. A deprecation warning is logged to the console when the
- * element is connected to the DOM.
+ * Este componente sigue funcionando para mantener la compatibilidad con versiones anteriores, pero será
+ * eliminado en la v1.0. Se registra una advertencia de obsolescencia en la consola cuando el
+ * elemento se conecta al DOM.
  *
- * @deprecated Use `<moni-button-group variant="connected">` instead.
+ * @deprecated Usa `<moni-button-group variant="connected">` en su lugar.
  *
  * @example
  * ```html
- * <!-- Legacy usage (not recommended) -->
+ * <!-- Uso heredado (no recomendado) -->
  * <moni-segmented-button name="view" multi>
- *   <moni-button-segment value="day">Day</moni-button-segment>
- *   <moni-button-segment value="week">Week</moni-button-segment>
+ *   <moni-button-segment value="day">Día</moni-button-segment>
+ *   <moni-button-segment value="week">Semana</moni-button-segment>
  * </moni-segmented-button>
  *
- * <!-- Modern M3 equivalent -->
+ * <!-- Equivalente M3 moderno -->
  * <moni-button-group variant="connected">
- *   <moni-button>Day</moni-button>
- *   <moni-button>Week</moni-button>
+ *   <moni-button>Día</moni-button>
+ *   <moni-button>Semana</moni-button>
  * </moni-button-group>
  * ```
  *
- * @slot default - `<moni-button-segment>` elements.
+ * @slot default - elementos `<moni-button-segment>`.
  */
 export declare class MoniSegmentedButton extends MoniElement {
     static formAssociated: boolean;
     private static _deprecationWarned;
+    /**
+     * Nombre del botón segmentado, usado para el envío del formulario.
+     * @type {string}
+     */
     name: string;
+    /**
+     * Permite seleccionar múltiples segmentos simultáneamente.
+     * @type {boolean}
+     */
     multi: boolean;
+    /**
+     * Tamaño de los segmentos del botón.
+     * @type {'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'extra'}
+     * @default 'medium'
+     */
     size: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'extra';
+    /**
+     * Oculta el icono de marca de verificación principal (leading checkmark) cuando se selecciona un segmento.
+     * @type {boolean}
+     */
     hideCheck: boolean;
+    /**
+     * Define un espaciado personalizado entre segmentos.
+     * @type {string}
+     */
     gap: string;
     private slottedSegments;
     private internals;
+    /**
+     * Constructor del componente.
+     * Inicializa ElementInternals (`attachInternals`) para integrar el custom element
+     * nativamente en formularios HTML, permitiéndole participar en validaciones y envíos de datos.
+     */
     constructor();
     connectedCallback(): void;
+    /**
+     * Expone el formulario anfitrión al que pertenece este componente,
+     * derivado de la API de ElementInternals.
+     */
     get form(): HTMLFormElement | null;
+    /**
+     * Define el tipo semántico del control de formulario.
+     */
     get type(): string;
     get value(): string;
     private get segments();
     static styles: import("lit").CSSResult[];
+    /**
+     * Hook del ciclo de vida reactivo (Lit).
+     * Enlaza propiedades estructurales (como el gap o la visibilidad de los checks)
+     * desde el contenedor padre hacia los segmentos hijos y comunica el nuevo valor
+     * consolidado al formulario subyacente cada vez que el estado cambia.
+     */
     protected updated(changedProperties: Map<string | number | symbol, unknown>): void;
+    /**
+     * Manejador del Slot Change.
+     * Re-evalúa jerárquicamente a los hijos proyectados si el DOM muta,
+     * reactualizando su topología visual (`border-radius`) y su valor en el form.
+     */
     private handleSlotChange;
     private getGapValue;
+    /**
+     * Patrón "Top-Down" para inyectar configuración visual y de posición a los segmentos hijos.
+     * Dado que CSS no puede pasar atributos reactivos fácilmente a hijos proyectados (<slot>),
+     * JS itera los hijos y les asigna si son 'first', 'middle' o 'last' para manejar
+     * el `border-radius` continuo.
+     */
     private updateChildren;
+    /**
+     * Sincroniza el valor interno del componente (`this.value`) con
+     * la estructura nativa del formulario utilizando la API de `ElementInternals.setFormValue`.
+     * Permite que los datos viajen de forma natural al hacer submit.
+     */
     private updateFormValue;
+    /**
+     * Delegación de eventos (Event Delegation) capturando el click en el contenedor padre.
+     * Maneja la lógica de exclusión mutua (single selection) estilo Radio Button
+     * o la selección aditiva estilo Checkbox cuando `multi` es true.
+     */
     private handleClick;
+    /**
+     * Renderiza el contenedor del botón segmentado con un `role="group"` y su superposición de indicador GSAP.
+     *
+     * **Indicador deslizante:**
+     * Un `<div>` `.indicator` se posiciona de forma absoluta dentro del contenedor del grupo.
+     * GSAP anima su `left` y `width` para deslizarse de un segmento a otro
+     * cuando la selección cambia (resaltado del segmento seleccionado del Segmented Button M3).
+     * En el primer renderizado, el indicador se posiciona instantáneamente (sin transición); los cambios
+     * posteriores usan `gsap.to()` con la curva de animación (easing) `_speed2` para un deslizamiento suave.
+     *
+     * **Sincronización `@slotchange`:**
+     * Cuando los segmentos se agregan/eliminan en tiempo de ejecución, `_syncSegments()` vuelve a leer
+     * los elementos asignados a la ranura (slot) y actualiza los atributos `first` / `last` de cada segmento
+     * para controlar el border-radius en los segmentos terminales.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-segmented-button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-segmented-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-segmented-button.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,mBAAoB,SAAQ,WAAW;IACnD,MAAM,CAAC,cAAc,UAAQ;IAE7B,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAG1C,IAAI,SAAM;IAGV,KAAK,UAAS;IAGd,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAG9E,SAAS,UAAS;IAGlB,GAAG,SAAM;IAGT,OAAO,CAAC,eAAe,CAAiB;IAExC,OAAO,CAAC,SAAS,CAAmB;;IAO3B,iBAAiB,IAAI,IAAI;IAelC,IAAI,IAAI,2BAEP;IAED,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,IAAI,MAAM,CAKlB;IAED,OAAO,KAAK,QAAQ,GAInB;IAED,OAAgB,MAAM,4BAoBpB;cAEiB,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAQpF,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,WAAW;IAWnB,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAqCV,MAAM;CAWf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,uBAAuB,EAAE,mBAAmB,CAAC;KAC7C;CACD;AAED,eAAe,mBAAmB,CAAC"}
+{"version":3,"file":"moni-segmented-button.d.ts","sourceRoot":"","sources":["../../src/components/moni-segmented-button.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBACa,mBAAoB,SAAQ,WAAW;IACnD,MAAM,CAAC,cAAc,UAAQ;IAE7B,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAS;IAE1C;;;OAGG;IAEH,IAAI,SAAM;IAEV;;;OAGG;IAEH,KAAK,UAAS;IAEd;;;;OAIG;IAEH,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9E;;;OAGG;IAEH,SAAS,UAAS;IAElB;;;OAGG;IAEH,GAAG,SAAM;IAGT,OAAO,CAAC,eAAe,CAAiB;IAExC,OAAO,CAAC,SAAS,CAAmB;IAEpC;;;;OAIG;;IAMM,iBAAiB,IAAI,IAAI;IAelC;;;OAGG;IACH,IAAI,IAAI,2BAEP;IAED;;OAEG;IACH,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,IAAI,MAAM,CAKlB;IAED,OAAO,KAAK,QAAQ,GAInB;IAED,OAAgB,MAAM,4BAoBpB;IAEF;;;;;OAKG;cACgB,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAQpF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,WAAW;IAWnB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAoBtB;;;;OAIG;IACH,OAAO,CAAC,eAAe;IAMvB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAuCnB;;;;;;;;;;;;;;OAcG;IACM,MAAM;CAWf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,uBAAuB,EAAE,mBAAmB,CAAC;KAC7C;CACD;AAED,eAAe,mBAAmB,CAAC"}

package/dist/components/moni-segmented-button.js

@@ -15,48 +15,74 @@ import { html, css } from 'lit';
 import { customElement, property, queryAssignedElements } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material Design 3 Segmented Button component (Legacy).
+ * Componente Material Design 3 Segmented Button (Botón Segmentado) (Heredado).
  *
- * A form-associated group of selectable segmented buttons.
+ * Un grupo de botones segmentados seleccionables asociado a formularios.
  *
- * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
- * has updated the segmented button pattern. The bespoke segments have been
- * replaced with standard `<moni-button>` elements grouped inside a
+ * **Aviso de obsolescencia (Deprecation Notice):** La especificación M3 (`m3-docs/components/segmented-buttons/overview.md`)
+ * ha actualizado el patrón de botones segmentados. Los segmentos a medida han sido
+ * reemplazados por elementos estándar `<moni-button>` agrupados dentro de un
  * `<moni-button-group variant="connected">`.
  *
- * This component continues to work for backward compatibility but will be
- * removed in v1.0. A deprecation warning is logged to the console when the
- * element is connected to the DOM.
+ * Este componente sigue funcionando para mantener la compatibilidad con versiones anteriores, pero será
+ * eliminado en la v1.0. Se registra una advertencia de obsolescencia en la consola cuando el
+ * elemento se conecta al DOM.
  *
- * @deprecated Use `<moni-button-group variant="connected">` instead.
+ * @deprecated Usa `<moni-button-group variant="connected">` en su lugar.
  *
  * @example
  * ```html
- * <!-- Legacy usage (not recommended) -->
+ * <!-- Uso heredado (no recomendado) -->
  * <moni-segmented-button name="view" multi>
- *   <moni-button-segment value="day">Day</moni-button-segment>
- *   <moni-button-segment value="week">Week</moni-button-segment>
+ *   <moni-button-segment value="day">Día</moni-button-segment>
+ *   <moni-button-segment value="week">Semana</moni-button-segment>
  * </moni-segmented-button>
  *
- * <!-- Modern M3 equivalent -->
+ * <!-- Equivalente M3 moderno -->
  * <moni-button-group variant="connected">
- *   <moni-button>Day</moni-button>
- *   <moni-button>Week</moni-button>
+ *   <moni-button>Día</moni-button>
+ *   <moni-button>Semana</moni-button>
  * </moni-button-group>
  * ```
  *
- * @slot default - `<moni-button-segment>` elements.
+ * @slot default - elementos `<moni-button-segment>`.
  */
 let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
     static { MoniSegmentedButton_1 = this; }
     static { this.formAssociated = true; }
     static { this._deprecationWarned = false; }
+    /**
+     * Constructor del componente.
+     * Inicializa ElementInternals (`attachInternals`) para integrar el custom element
+     * nativamente en formularios HTML, permitiéndole participar en validaciones y envíos de datos.
+     */
     constructor() {
         super();
+        /**
+         * Nombre del botón segmentado, usado para el envío del formulario.
+         * @type {string}
+         */
         this.name = '';
+        /**
+         * Permite seleccionar múltiples segmentos simultáneamente.
+         * @type {boolean}
+         */
         this.multi = false;
+        /**
+         * Tamaño de los segmentos del botón.
+         * @type {'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'extra'}
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * Oculta el icono de marca de verificación principal (leading checkmark) cuando se selecciona un segmento.
+         * @type {boolean}
+         */
         this.hideCheck = false;
+        /**
+         * Define un espaciado personalizado entre segmentos.
+         * @type {string}
+         */
         this.gap = '';
         this.internals = this.attachInternals();
     }
@@ -72,9 +98,16 @@ let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
                 'See m3-docs/components/segmented-buttons/overview.md § M3 Expressive update.');
         }
     }
+    /**
+     * Expone el formulario anfitrión al que pertenece este componente,
+     * derivado de la API de ElementInternals.
+     */
     get form() {
         return this.internals.form;
     }
+    /**
+     * Define el tipo semántico del control de formulario.
+     */
     get type() {
         return 'segmented-button';
     }
@@ -108,6 +141,12 @@ let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Hook del ciclo de vida reactivo (Lit).
+     * Enlaza propiedades estructurales (como el gap o la visibilidad de los checks)
+     * desde el contenedor padre hacia los segmentos hijos y comunica el nuevo valor
+     * consolidado al formulario subyacente cada vez que el estado cambia.
+     */
     updated(changedProperties) {
         super.updated(changedProperties);
         if (changedProperties.has('hideCheck') || changedProperties.has('size') || changedProperties.has('gap')) {
@@ -115,6 +154,11 @@ let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
         }
         this.updateFormValue();
     }
+    /**
+     * Manejador del Slot Change.
+     * Re-evalúa jerárquicamente a los hijos proyectados si el DOM muta,
+     * reactualizando su topología visual (`border-radius`) y su valor en el form.
+     */
     handleSlotChange() {
         this.updateChildren();
         this.updateFormValue();
@@ -135,6 +179,12 @@ let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
             return '0.5rem';
         return gap;
     }
+    /**
+     * Patrón "Top-Down" para inyectar configuración visual y de posición a los segmentos hijos.
+     * Dado que CSS no puede pasar atributos reactivos fácilmente a hijos proyectados (<slot>),
+     * JS itera los hijos y les asigna si son 'first', 'middle' o 'last' para manejar
+     * el `border-radius` continuo.
+     */
     updateChildren() {
         const segments = this.segments;
         const len = segments.length;
@@ -155,11 +205,21 @@ let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
             }
         });
     }
+    /**
+     * Sincroniza el valor interno del componente (`this.value`) con
+     * la estructura nativa del formulario utilizando la API de `ElementInternals.setFormValue`.
+     * Permite que los datos viajen de forma natural al hacer submit.
+     */
     updateFormValue() {
         if (typeof this.internals.setFormValue === 'function') {
             this.internals.setFormValue(this.value);
         }
     }
+    /**
+     * Delegación de eventos (Event Delegation) capturando el click en el contenedor padre.
+     * Maneja la lógica de exclusión mutua (single selection) estilo Radio Button
+     * o la selección aditiva estilo Checkbox cuando `multi` es true.
+     */
     handleClick(e) {
         const target = e.target;
         const clickedSegment = target.closest('moni-button-segment');
@@ -168,12 +228,14 @@ let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
         }
         const segments = this.segments;
         if (this.multi) {
+            // Toggle independiente
             clickedSegment.checked = !clickedSegment.checked;
         }
         else {
+            // Comportamiento de grupo radio: deseleccionar hermanos
             segments.forEach((seg) => {
                 if (seg === clickedSegment) {
-                    seg.checked = !seg.checked;
+                    seg.checked = !seg.checked; // Permite toggle off incluso en single mode (comportamiento M3)
                 }
                 else {
                     seg.checked = false;
@@ -191,6 +253,21 @@ let MoniSegmentedButton = class MoniSegmentedButton extends MoniElement {
             }
         }));
     }
+    /**
+     * Renderiza el contenedor del botón segmentado con un `role="group"` y su superposición de indicador GSAP.
+     *
+     * **Indicador deslizante:**
+     * Un `<div>` `.indicator` se posiciona de forma absoluta dentro del contenedor del grupo.
+     * GSAP anima su `left` y `width` para deslizarse de un segmento a otro
+     * cuando la selección cambia (resaltado del segmento seleccionado del Segmented Button M3).
+     * En el primer renderizado, el indicador se posiciona instantáneamente (sin transición); los cambios
+     * posteriores usan `gsap.to()` con la curva de animación (easing) `_speed2` para un deslizamiento suave.
+     *
+     * **Sincronización `@slotchange`:**
+     * Cuando los segmentos se agregan/eliminan en tiempo de ejecución, `_syncSegments()` vuelve a leer
+     * los elementos asignados a la ranura (slot) y actualiza los atributos `first` / `last` de cada segmento
+     * para controlar el border-radius en los segmentos terminales.
+     */
     render() {
         const resolvedGap = this.getGapValue(this.gap);
         const inlineStyles = resolvedGap