@moni-labs/moni-ui 0.3.0 → 0.3.2

package/src/components/moni-checkbox.test.ts

@@ -14,7 +14,7 @@ describe('moni-checkbox', () => {
 		el.remove();
 	});
 
-	it('renders an input and a visual span', async () => {
+	it('renderiza un input y un span visual', async () => {
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector('input');
 		const span = el.shadowRoot?.querySelector('span');
@@ -22,7 +22,7 @@ describe('moni-checkbox', () => {
 		expect(span).toBeTruthy();
 	});
 
-	it('forwards checked state to the input', async () => {
+	it('reenvía el estado checked al input', async () => {
 		el.checked = true;
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
@@ -35,7 +35,7 @@ describe('moni-checkbox', () => {
 		expect(input.checked).toBe(false);
 	});
 
-	it('input is contained in the label (for click handling)', async () => {
+	it('el input está contenido en el label (para el manejo de clics)', async () => {
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
 			'input'
@@ -44,14 +44,14 @@ describe('moni-checkbox', () => {
 		expect(label?.contains(input)).toBe(true);
 	});
 
-	it('renders a label span when label attribute is set', async () => {
+	it('renderiza un label span cuando se establece el atributo label', async () => {
 		el.label = 'Accept terms';
 		await el.updateComplete;
 		const span = el.shadowRoot?.querySelector('span');
 		expect(span?.textContent?.trim()).toBe('Accept terms');
 	});
 
-	it('forwards disabled to the input', async () => {
+	it('reenvía disabled al input', async () => {
 		el.disabled = true;
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
@@ -60,7 +60,7 @@ describe('moni-checkbox', () => {
 		expect(input.disabled).toBe(true);
 	});
 
-	it('reflects the checked attribute', async () => {
+	it('refleja el atributo checked', async () => {
 		el.checked = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('checked')).toBe(true);
@@ -70,7 +70,7 @@ describe('moni-checkbox', () => {
 		expect(el.hasAttribute('checked')).toBe(false);
 	});
 
-	it('reflects the disabled attribute', async () => {
+	it('refleja el atributo disabled', async () => {
 		el.disabled = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('disabled')).toBe(true);

package/src/components/moni-checkbox.ts

@@ -10,84 +10,93 @@ import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { live } from 'lit/directives/live.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
+import { emitMoniEvent } from '../utils/event-emitter.js';
 
 /**
- * Material Design 3 Checkbox component.
+ * Componente Material Design 3 Checkbox.
  *
- * Checkboxes allow users to select one or more items from a set, or toggle
- * a single binary option. They are visual-only shells — the consumer is
- * responsible for wiring up form submission and validation logic.
+ * Los checkboxes permiten a los usuarios seleccionar uno o más elementos de un conjunto, o alternar
+ * una sola opción binaria. Son envolturas solo visuales — el consumidor es
+ * responsable de conectar la lógica de envío y validación del formulario.
  *
- * **Visual architecture (BeerCSS pattern):**
- * The native `<input type="checkbox">` occupies real layout space (16×16 minimum)
- * but is visually hidden via `opacity: 0`. A `<span>` sibling rendered after
- * the input holds two pseudo-elements:
- * - `::before` — the visible checkbox icon (Material Symbols ligature).
- * - `::after`  — the hover/focus state layer ripple ring.
+ * **Arquitectura visual (Patrón BeerCSS):**
+ * El `<input type="checkbox">` nativo ocupa espacio real en el diseño (mínimo 16×16)
+ * pero está oculto visualmente con `opacity: 0`. Un hermano `<span>` renderizado después
+ * del input contiene dos pseudo-elementos:
+ * - `::before` — el icono visible del checkbox (ligadura de Material Symbols).
+ * - `::after`  — el anillo de onda (ripple) de la capa de estado hover/focus.
  *
- * The `::before` content switches between:
- * - `'check_box_outline_blank'` (unchecked)
- * - `'check_box'` (checked)
- * - `'indeterminate_check_box'` (native indeterminate state)
+ * El contenido de `::before` cambia entre:
+ * - `'check_box_outline_blank'` (desmarcado)
+ * - `'check_box'` (marcado)
+ * - `'indeterminate_check_box'` (estado nativo indeterminado)
  *
- * **Form integration:**
- * Setting `name` and `value` passes them to the native `<input>` element,
- * enabling participation in HTML form submissions.
+ * **Integración de formulario:**
+ * Establecer `name` y `value` los pasa al elemento `<input>` nativo,
+ * permitiendo la participación en envíos de formularios HTML.
  *
- * @fires change - Bubbles and is composed. Fired when the checkbox is toggled.
- *                 The consumer can read `element.checked` for the new state.
+ * @fires moni-change - Burbujea y está compuesto. Se dispara cuando se alterna el checkbox.
+ *                      El consumidor puede leer `element.checked` para el nuevo estado.
  *
  * @example
  * ```html
- * <moni-checkbox label="Accept terms" name="terms" value="yes"></moni-checkbox>
+ * <moni-checkbox label="Aceptar términos" name="terms" value="yes"></moni-checkbox>
  *
  * <script>
- *   document.querySelector('moni-checkbox').addEventListener('change', (e) => {
+ *   document.querySelector('moni-checkbox').addEventListener('moni-change', (e) => {
  *     console.log('checked:', e.target.checked);
  *   });
  * </script>
  * ```
  *
- * @csspart checkbox - The outer `<label>` element.
+ * @csspart checkbox - El elemento exterior `<label>`.
  */
 @customElement('moni-checkbox')
 export class MoniCheckbox extends MoniElement {
+	static formAssociated = true;
+	private _internals: ElementInternals;
+
+	constructor() {
+		super();
+		this._internals = this.attachInternals();
+	}
+
 	/**
-	 * Text label displayed to the right of the checkbox icon.
+	 * Texto de la etiqueta mostrado a la derecha del icono del checkbox.
 	 *
-	 * When non-empty, the label is rendered as a text node inside the `<span>`.
-	 * When empty, the default slot is rendered instead, allowing slotted HTML.
+	 * Cuando no está vacío, la etiqueta se renderiza como un nodo de texto dentro del `<span>`.
+	 * Cuando está vacío, el slot por defecto se renderiza en su lugar, permitiendo HTML en el slot.
 	 *
 	 * @default ''
 	 */
 	@property({ reflect: true }) label = '';
 
 	/**
-	 * Whether the checkbox is currently checked.
+	 * Si el checkbox está actualmente marcado.
 	 *
-	 * Reflected as an attribute so CSS attribute selectors and external state
-	 * readers can observe the checked state without accessing the JS property.
-	 * Synced to the native input via `updated()`.
+	 * Reflejado como un atributo para que los selectores de atributos CSS y los lectores
+	 * de estado externos puedan observar el estado marcado sin acceder a la propiedad JS.
+	 * Sincronizado con el input nativo a través de `updated()`.
 	 *
 	 * @default false
 	 */
 	@property({ type: Boolean, reflect: true }) checked = false;
 
 	/**
-	 * When `true`, the native input is disabled: the checkbox is not interactive
-	 * and renders at 50% opacity.
+	 * Cuando es `true`, el input nativo se deshabilita: el checkbox no es interactivo
+	 * y se renderiza con opacidad del 50%.
 	 *
 	 * @default false
 	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
 
 	/**
-	 * Visual size of the checkbox icon.
+	 * Tamaño visual del icono del checkbox.
 	 *
-	 * Maps to the `--_size` custom property which controls both the invisible
-	 * input's hit area and the visible `::before` icon size.
+	 * Se mapea a la propiedad personalizada `--_size` que controla tanto el área de impacto
+	 * del input invisible como el tamaño del icono visible `::before`.
 	 *
-	 * | Value      | `--_size` |
+	 * | Valor      | `--_size` |
 	 * |------------|-----------|
 	 * | `'small'`  | 1rem      |
 	 * | `'medium'` | 1.5rem    |
@@ -100,37 +109,40 @@ export class MoniCheckbox extends MoniElement {
 	size: 'small' | 'medium' | 'large' | 'extra' = 'medium';
 
 	/**
-	 * Forwarded to the native `<input name>` attribute.
-	 * Required for grouping checkboxes within a form.
+	 * Reenviado al atributo `<input name>` nativo.
+	 * Requerido para agrupar checkboxes dentro de un formulario.
 	 *
 	 * @default ''
 	 */
 	@property({ reflect: true }) name = '';
 
 	/**
-	 * Forwarded to the native `<input value>` attribute.
-	 * The value submitted in a form when this checkbox is checked.
+	 * Reenviado al atributo `<input value>` nativo.
+	 * El valor enviado en un formulario cuando este checkbox está marcado.
 	 *
 	 * @default ''
 	 */
 	@property({ reflect: true }) value = '';
 
-	/** Direct reference to the native input element for programmatic access. */
+	/** Referencia directa al elemento input nativo para acceso programático. */
 	@query('input') private _input!: HTMLInputElement;
 
 	/**
-	 * Syncs `checked` and `disabled` back to the native input element after
-	 * Lit's render cycle, ensuring the DOM stays in sync with component state.
+	 * Sincroniza `checked` y `disabled` de vuelta al elemento input nativo después
+	 * del ciclo de renderizado de Lit, asegurando que el DOM se mantenga sincronizado con el estado del componente.
 	 *
-	 * This is necessary because Lit's `.property=${value}` binding updates the
-	 * DOM property, but the `live()` directive and direct property assignment
-	 * are more reliable for boolean inputs across browser implementations.
+	 * Esto es necesario porque el enlace `.property=${value}` de Lit actualiza la
+	 * propiedad DOM, pero la directiva `live()` y la asignación directa de propiedad
+	 * son más fiables para entradas booleanas en diferentes implementaciones de navegadores.
 	 *
-	 * @param changed - Map of changed property names to their previous values.
+	 * @param changed - Mapa de nombres de propiedades cambiadas a sus valores anteriores.
 	 */
 	override updated(changed: Map<string, unknown>) {
 		if (this._input) {
-			if (changed.has('checked')) this._input.checked = this.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;
 		}
 	}
@@ -264,7 +276,9 @@ export class MoniCheckbox extends MoniElement {
 	 */
 	private _onChange(e: Event) {
 		this.checked = (e.target as HTMLInputElement).checked;
-		this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+		emitMoniEvent(this, 'moni-change', {
+			detail: { value: this.checked, originalEvent: e }
+		});
 	}
 
 	/**

package/src/components/moni-chip.test.ts

@@ -14,21 +14,21 @@ describe('moni-chip', () => {
 		el.remove();
 	});
 
-	it('renders a native <button>', async () => {
+	it('renderiza un <button> nativo', async () => {
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector('button');
 		expect(button).toBeTruthy();
 		expect(button?.getAttribute('type')).toBe('button');
 	});
 
-	it('defaults to variant=assist and size=small (M3 spec)', async () => {
+	it('por defecto es variant=assist y size=small (especificación M3)', async () => {
 		await el.updateComplete;
 		expect(el.variant).toBe('assist');
 		expect(el.size).toBe('small');
 		expect(el.getAttribute('variant')).toBe('assist');
 	});
 
-	it('accepts all 4 M3 variants (assist, filter, input, suggestion)', async () => {
+	it('acepta las 4 variantes M3 (assist, filter, input, suggestion)', async () => {
 		const variants: Array<'assist' | 'filter' | 'input' | 'suggestion'> = [
 			'assist',
 			'filter',
@@ -44,7 +44,7 @@ describe('moni-chip', () => {
 		}
 	});
 
-	it('aliases outlined → assist for backward compat', async () => {
+	it('crea un alias de outlined → assist para compatibilidad con versiones anteriores', async () => {
 		el.variant = 'outlined';
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector('button');
@@ -52,7 +52,7 @@ describe('moni-chip', () => {
 		expect(button?.classList.contains('outlined')).toBe(false);
 	});
 
-	it('aliases fill → filter for backward compat', async () => {
+	it('crea un alias de fill → filter para compatibilidad con versiones anteriores', async () => {
 		el.variant = 'fill';
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector('button');
@@ -60,14 +60,14 @@ describe('moni-chip', () => {
 		expect(button?.classList.contains('fill')).toBe(false);
 	});
 
-	it('selected chip applies the selected class', async () => {
+	it('el chip seleccionado aplica la clase selected', async () => {
 		el.selected = true;
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector('button');
 		expect(button?.classList.contains('selected')).toBe(true);
 	});
 
-	it('input variant always shows the trailing remove icon (M3 spec)', async () => {
+	it('la variante input siempre muestra el icono trailing de eliminar (especificación M3)', async () => {
 		el.variant = 'input';
 		el.textContent = 'Tag';
 		await el.updateComplete;
@@ -75,7 +75,7 @@ describe('moni-chip', () => {
 		expect(remove).toBeTruthy();
 	});
 
-	it('removable=true forces the trailing remove icon on any variant', async () => {
+	it('removable=true fuerza el icono trailing de eliminar en cualquier variante', async () => {
 		el.variant = 'assist';
 		el.removable = true;
 		el.textContent = 'Tag';
@@ -84,7 +84,7 @@ describe('moni-chip', () => {
 		expect(remove).toBeTruthy();
 	});
 
-	it('assist and suggestion chips do NOT show remove icon by default', async () => {
+	it('los chips assist y suggestion NO muestran el icono de eliminar por defecto', async () => {
 		for (const v of ['assist', 'suggestion'] as const) {
 			el.variant = v;
 			el.removable = false;
@@ -95,7 +95,7 @@ describe('moni-chip', () => {
 		}
 	});
 
-	it('icon attribute renders a leading moni-icon', async () => {
+	it('el atributo icon renderiza un moni-icon leading', async () => {
 		el.icon = 'add';
 		el.textContent = 'Add';
 		await el.updateComplete;
@@ -104,28 +104,28 @@ describe('moni-chip', () => {
 		expect(icon?.getAttribute('name')).toBe('add');
 	});
 
-	it('size=medium sets medium class on the button', async () => {
+	it('size=medium establece la clase medium en el botón', async () => {
 		el.size = 'medium';
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector('button');
 		expect(button?.classList.contains('medium')).toBe(true);
 	});
 
-	it('size=large sets large class on the button', async () => {
+	it('size=large establece la clase large en el botón', async () => {
 		el.size = 'large';
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector('button');
 		expect(button?.classList.contains('large')).toBe(true);
 	});
 
-	it('shape=square sets square class (M3 button morph target)', async () => {
+	it('shape=square establece la clase square (objetivo de transformación de botón M3)', async () => {
 		el.shape = 'square';
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector('button');
 		expect(button?.classList.contains('square')).toBe(true);
 	});
 
-	it('disabled disables the inner button', async () => {
+	it('disabled deshabilita el botón interno', async () => {
 		el.disabled = true;
 		await el.updateComplete;
 		const button = el.shadowRoot?.querySelector(
@@ -134,7 +134,7 @@ describe('moni-chip', () => {
 		expect(button.disabled).toBe(true);
 	});
 
-	it('loading shows moni-progress and sets aria-busy', async () => {
+	it('loading muestra moni-progress y establece aria-busy', async () => {
 		el.loading = true;
 		await el.updateComplete;
 		const progress = el.shadowRoot?.querySelector('moni-progress');
@@ -143,7 +143,7 @@ describe('moni-chip', () => {
 		expect(button?.getAttribute('aria-busy')).toBe('true');
 	});
 
-	it('renders the default slot content inside [part=label]', async () => {
+	it('renderiza el contenido del slot por defecto dentro de [part=label]', async () => {
 		el.textContent = 'Hello chip';
 		await el.updateComplete;
 		const label = el.shadowRoot?.querySelector('[part="label"]');
@@ -154,7 +154,7 @@ describe('moni-chip', () => {
 		expect(text).toBe('Hello chip');
 	});
 
-	it('applies has-icon class only when a leading icon is present', async () => {
+	it('aplica la clase has-icon solo cuando hay un icono leading presente', async () => {
 		el.textContent = 'Filter';
 		await el.updateComplete;
 		let button = el.shadowRoot?.querySelector('button');

package/src/components/moni-chip.ts

@@ -12,58 +12,63 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Material Design 3 Chip component.
+ * Componente Material Design 3 Chip.
  *
- * Chips are compact, interactive elements that represent actions, filters,
- * attributes, or user inputs. They are visual-only shells — the consumer
- * owns all state management (selection, removal, active filter state).
+ * Los chips (fichas) son elementos compactos e interactivos que representan acciones, filtros,
+ * atributos o entradas de usuario. Son contenedores solo visuales — el consumidor
+ * es dueño de todo el manejo del estado (selección, eliminación, estado de filtro activo).
  *
- * **M3 spec reference:** `m3-docs/components/chips/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/chips/specs.md`
  *
- * **Variants:**
- * - `assist` (default) — Smart or suggested actions. Uses `var(--outline)` border
- *   to ensure 3:1 contrast per the M3 accessibility spec. Alias: `outlined`.
- * - `filter` — Filters for a content collection. Shows a leading checkmark when
- *   `selected`. Alias: `fill`.
- * - `input` — Represents discrete user input (tags, tokens). Adds a trailing
- *   remove icon when `removable`.
- * - `suggestion` — Product-generated suggestions. Outlined, no icons.
+ * **Variantes:**
+ * - `assist` (por defecto) — Acciones inteligentes o sugeridas. Usa borde `var(--outline)`
+ *   para asegurar un contraste de 3:1 según la especificación de accesibilidad de M3. Alias: `outlined`.
+ * - `filter` — Filtros para una colección de contenido. Muestra una marca de verificación al principio cuando
+ *   está `selected`. Alias: `fill`.
+ * - `input` — Representa una entrada de usuario discreta (etiquetas, tokens). Añade un icono de
+ *   eliminación al final cuando es `removable`.
+ * - `suggestion` — Sugerencias generadas por el producto. Con contorno, sin iconos.
  *
- * **M3 measurements:**
- * - Default height: 32dp (`small` size = M3 spec baseline).
- * - Corner radius: 8dp.
- * - Icon size: 18dp.
- * - `medium` and `large` sizes are Moni extensions with larger touch targets.
+ * **Medidas M3:**
+ * - Altura por defecto: 32dp (tamaño `small` = línea base de la especificación M3).
+ * - Radio de esquina: 8dp.
+ * - Tamaño de icono: 18dp.
+ * - Los tamaños `medium` y `large` son extensiones de Moni con áreas táctiles más grandes.
  *
- * **Accessibility:**
- * `assist` and `suggestion` chips use `var(--outline)` for their stroke to
- * guarantee 3:1 contrast against the surface background at rest.
- * `filter` and `input` use `outline-variant` at rest but achieve contrast
- * through the `secondary-container` fill when selected.
+ * **Accesibilidad:**
+ * Los chips `assist` y `suggestion` usan `var(--outline)` para su trazo para
+ * garantizar un contraste de 3:1 contra el fondo de la superficie en reposo.
+ * `filter` e `input` usan `outline-variant` en reposo pero logran contraste
+ * a través del relleno `secondary-container` cuando se seleccionan.
  *
- * @fires remove - Bubbles and is composed. Fired when the trailing remove
- *                 icon is clicked on an `input` chip with `removable`.
+ * @fires remove - Burbujea y está compuesto. Se dispara cuando el icono de eliminación
+ *                 final se hace clic en un chip `input` con `removable`.
  *
  * @example
  * ```html
- * <!-- Filter chip with selected state -->
+ * <!-- Chip de filtro con estado seleccionado -->
  * <moni-chip variant="filter" selected>Technology</moni-chip>
  *
- * <!-- Input chip (tag/token) -->
+ * <!-- Chip de entrada (etiqueta/token) -->
  * <moni-chip variant="input" removable icon="label">TypeScript</moni-chip>
  *
- * <!-- Assist chip with icon -->
+ * <!-- Chip de asistencia con icono -->
  * <moni-chip icon="directions_car">Get directions</moni-chip>
  * ```
  *
- * @slot default   - The chip label text.
- * @slot icon      - Override for the leading icon (alternative to the `icon` attribute).
+ * @slot default   - El texto de la etiqueta del chip.
+ * @slot icon      - Anula el icono inicial (alternativa al atributo `icon`).
  *
- * @csspart chip   - The inner `<button>` element.
- * @csspart label  - The label `<span>` element.
+ * @csspart chip   - El elemento interno `<button>`.
+ * @csspart label  - El elemento `<span>` de la etiqueta.
  */
 @customElement('moni-chip')
 export class MoniChip extends MoniElement {
+	/**
+	 * Variante visual del chip.
+	 * @type {'assist' | 'filter' | 'input' | 'suggestion' | 'outlined' | 'fill'}
+	 * @default 'assist'
+	 */
 	@property({ reflect: true })
 	variant:
 		| 'assist'
@@ -72,8 +77,20 @@ export class MoniChip extends MoniElement {
 		| 'suggestion'
 		| 'outlined'
 		| 'fill' = 'assist';
+
+	/**
+	 * Define las dimensiones del chip.
+	 * @type {'small' | 'medium' | 'large'}
+	 * @default 'small'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' = 'small';
+
+	/**
+	 * Forma del radio del borde del chip.
+	 * @type {'round' | 'no-round' | 'square' | 'circle' | 'left-round' | 'right-round' | 'top-round' | 'bottom-round'}
+	 * @default 'round'
+	 */
 	@property({ reflect: true })
 	shape:
 		| 'round'
@@ -84,21 +101,61 @@ export class MoniChip extends MoniElement {
 		| 'right-round'
 		| 'top-round'
 		| 'bottom-round' = 'round';
+
+	/**
+	 * Si es true, marca el chip como seleccionado (útil para chips de filtro).
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) selected = false;
+
+	/**
+	 * Si es true, muestra un icono de cierre al final para permitir la eliminación.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) removable = false;
+
+	/**
+	 * Deshabilita el chip.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * Si es true, muestra un indicador de carga dentro del chip.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) loading = false;
+
+	/**
+	 * Nombre del icono inicial (Material Symbols).
+	 * @type {string}
+	 */
 	@property({ reflect: true }) icon = '';
 
 	@state()
 	private _hasSlottedIcon = false;
 
+	/**
+	 * Manejador del slot interno de icono (Slot Change).
+	 * Determina si el desarrollador proporcionó un icono dinámicamente vía Light DOM
+	 * (`<moni-icon slot="icon">`), permitiendo que el componente ajuste 
+	 * sus márgenes internos (`padding`) y espaciados dinámicamente.
+	 */
 	private _handleSlotChange(e: Event) {
 		const slot = e.target as HTMLSlotElement;
 		this._hasSlottedIcon = slot.assignedNodes({ flatten: true }).length > 0;
 	}
 
-	/** Normalize legacy variant names to M3 spec. */
+	/**
+	 * Manejador de clics en el icono de remover.
+	 * Detiene la propagación para no disparar el clic del chip y emite un evento custom 'remove'.
+	 */
+	private _handleRemoveClick(e: Event) {
+		e.stopPropagation();
+		this.dispatchEvent(new CustomEvent('remove', { bubbles: true, composed: true }));
+	}
+
+	/** Normaliza los nombres de variantes heredadas a la especificación M3. */
 	private get _variant(): 'assist' | 'filter' | 'input' | 'suggestion' {
 		if (this.variant === 'outlined') return 'assist';
 		if (this.variant === 'fill') return 'filter';
@@ -288,6 +345,27 @@ export class MoniChip extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el elemento `<button>` del chip con su lista de clases calculada.
+	 *
+	 * **Normalización de variantes:**
+	 * `_variant` mapea nombres de alias heredados (`'outlined'` → `'assist'`, `'fill'` → `'filter'`)
+	 * a nombres de variantes canónicas de M3 antes de inyectarlos como clases CSS.
+	 *
+	 * **Ruta rápida de carga:**
+	 * Cuando `loading=true`, se devuelve temprano un botón mínimo con solo un indicador de carga
+	 * (sin slot de icono, sin etiqueta, sin botón de eliminación) con `aria-busy="true"`.
+	 *
+	 * **Lógica del botón de eliminación:**
+	 * `showRemove` es `true` cuando:
+	 * - `variant='input'` (Especificación M3: los chips de entrada siempre tienen un icono de cierre al final), o
+	 * - `removable=true` se establece explícitamente.
+	 *
+	 * **Resolución de icono:**
+	 * Si se establece el atributo `icon`, se renderiza un `<moni-icon>`. De lo contrario, se usa el
+	 * slot nombrado `icon`, con `_hasSlottedIcon` rastreando si se proyectó contenido en el slot
+	 * (usado para añadir condicionalmente los ajustes de relleno `has-icon`).
+	 */
 	override render() {
 		const variant = this._variant;
 		const hasIcon = Boolean(this.icon) || this._hasSlottedIcon;
@@ -335,7 +413,7 @@ export class MoniChip extends MoniElement {
 				></slot>`;
 
 		const removeEl = showRemove
-			? html`<span class="remove" part="remove" aria-hidden="true"
+			? html`<span class="remove" part="remove" aria-hidden="true" @click=${this._handleRemoveClick}
 					><moni-icon name="close"></moni-icon
 				></span>`
 			: nothing;