@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-chip.js

@@ -16,74 +16,123 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 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.
  */
 let MoniChip = class MoniChip extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Variante visual del chip.
+         * @type {'assist' | 'filter' | 'input' | 'suggestion' | 'outlined' | 'fill'}
+         * @default 'assist'
+         */
         this.variant = 'assist';
+        /**
+         * Define las dimensiones del chip.
+         * @type {'small' | 'medium' | 'large'}
+         * @default 'small'
+         */
         this.size = 'small';
+        /**
+         * Forma del radio del borde del chip.
+         * @type {'round' | 'no-round' | 'square' | 'circle' | 'left-round' | 'right-round' | 'top-round' | 'bottom-round'}
+         * @default 'round'
+         */
         this.shape = 'round';
+        /**
+         * Si es true, marca el chip como seleccionado (útil para chips de filtro).
+         * @type {boolean}
+         */
         this.selected = false;
+        /**
+         * Si es true, muestra un icono de cierre al final para permitir la eliminación.
+         * @type {boolean}
+         */
         this.removable = false;
+        /**
+         * Deshabilita el chip.
+         * @type {boolean}
+         */
         this.disabled = false;
+        /**
+         * Si es true, muestra un indicador de carga dentro del chip.
+         * @type {boolean}
+         */
         this.loading = false;
+        /**
+         * Nombre del icono inicial (Material Symbols).
+         * @type {string}
+         */
         this.icon = '';
         this._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.
+     */
     _handleSlotChange(e) {
         const slot = e.target;
         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'.
+     */
+    _handleRemoveClick(e) {
+        e.stopPropagation();
+        this.dispatchEvent(new CustomEvent('remove', { bubbles: true, composed: true }));
+    }
+    /** Normaliza los nombres de variantes heredadas a la especificación M3. */
     get _variant() {
         if (this.variant === 'outlined')
             return 'assist';
@@ -273,6 +322,27 @@ let MoniChip = 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`).
+     */
     render() {
         const variant = this._variant;
         const hasIcon = Boolean(this.icon) || this._hasSlottedIcon;
@@ -316,7 +386,7 @@ let MoniChip = class MoniChip extends MoniElement {
 					@slotchange=${this._handleSlotChange}
 				></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;

package/dist/components/moni-color-field.d.ts

@@ -6,60 +6,135 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Material Design 3 Color Field component.
+ * Componente Material Design 3 Color Field (Campo de Color).
  *
- * A specialized text field for color input that combines a native
- * `<input type="color">` with a read-only text display of the selected
- * hex value, wrapped in the standard M3 field shell.
+ * Un campo de texto especializado para la entrada de color que combina un
+ * `<input type="color">` nativo con una visualización de texto de solo lectura del
+ * valor hexadecimal seleccionado, envuelto en la carcasa estándar de campo M3.
  *
- * **Visual architecture:**
- * Extends the field styling pattern used by `<moni-text-field>`. The
- * leading icon slot is replaced by a circular color swatch (`.swatch`)
- * which is absolutely positioned over an invisible native color input.
- * Clicking the swatch opens the system color picker. The text input portion
- * displays the selected hex code and is strictly `readOnly`.
+ * **Arquitectura visual:**
+ * Extiende el patrón de estilo de campo usado por `<moni-text-field>`. El
+ * slot de icono inicial se reemplaza por una muestra de color circular (`.swatch`)
+ * que se posiciona absolutamente sobre una entrada de color nativa invisible.
+ * Al hacer clic en la muestra se abre el selector de color del sistema. La parte de entrada de texto
+ * muestra el código hexadecimal seleccionado y es estrictamente `readOnly`.
  *
- * **State syncing:**
- * The component listens to the native `change` event on the color input,
- * updates the `value` property, and re-dispatches a composed `'change'` event.
- * It does not listen to `input` (continuous drag in the color picker) to avoid
- * excessive event firing, but consumers can attach their own `input` listeners
- * directly to the element if live preview is needed.
+ * **Sincronización de estado:**
+ * El componente escucha el evento nativo `change` en la entrada de color,
+ * actualiza la propiedad `value`, y re-despacha un evento compuesto `'change'`.
+ * No escucha `input` (arrastre continuo en el selector de color) para evitar
+ * el disparo excesivo de eventos, pero los consumidores pueden adjuntar sus propios
+ * escuchas de `input` directamente al elemento si se necesita una vista previa en vivo.
  *
- * @fires change - Bubbles and is composed. Fired when the color picker closes
- *                 and the value is committed. Read `element.value`.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando el selector de color se cierra
+ *                 y el valor se confirma. Leer `element.value`.
  *
  * @example
  * ```html
  * <moni-color-field
- *   label="Theme Color"
+ *   label="Color del Tema"
  *   name="primaryColor"
  *   value="#6750a4"
  *   variant="outlined"
  * ></moni-color-field>
  * ```
  *
- * @csspart field       - The outer `.field` div container.
- * @csspart swatch      - The circular color preview element.
- * @csspart input-color - The native, visually hidden `<input type="color">`.
- * @csspart input-text  - The native `<input type="text">` displaying the hex code.
- * @csspart label       - The floating `<label>` element.
+ * @csspart field       - El contenedor div exterior `.field`.
+ * @csspart swatch      - El elemento de vista previa de color circular.
+ * @csspart input-color - El `<input type="color">` nativo, visualmente oculto.
+ * @csspart input-text  - El `<input type="text">` nativo que muestra el código hexadecimal.
+ * @csspart label       - El elemento flotante `<label>`.
  */
 export declare class MoniColorField extends MoniElement {
+    /**
+     * El nombre del input, enviado con los datos del formulario.
+     * @type {string}
+     */
     name: string;
+    /**
+     * El texto de la etiqueta flotante.
+     * @type {string}
+     */
     label: string;
+    /**
+     * Variante visual del campo de texto.
+     * @type {'filled' | 'outlined'}
+     * @default 'outlined'
+     */
     variant: 'filled' | 'outlined';
+    /**
+     * Define las dimensiones del campo de texto.
+     * @type {'small' | 'medium' | 'large' | 'extra'}
+     * @default 'medium'
+     */
     size: 'small' | 'medium' | 'large' | 'extra';
+    /**
+     * Forma del radio del borde del campo.
+     * @type {'round' | 'square' | 'no-round'}
+     * @default 'no-round'
+     */
     shape: 'round' | 'square' | 'no-round';
+    /**
+     * Deshabilita el campo de color.
+     * @type {boolean}
+     */
     disabled: boolean;
+    /**
+     * Texto de ayuda mostrado debajo del campo.
+     * @type {string}
+     */
     helper: string;
+    /**
+     * Texto de error mostrado debajo del campo cuando `error` es true.
+     * Sobrescribe el texto de ayuda.
+     * @type {string}
+     */
     errorText: string;
+    /**
+     * Si es true, establece el campo en un estado de error.
+     * @type {boolean}
+     */
     error: boolean;
+    /**
+     * El valor actual del color hexadecimal.
+     * @type {string}
+     * @default '#6750a4'
+     */
     value: string;
     private _colorInput;
     private _textInput;
+    /**
+     * Hook de ciclo de vida de Lit.
+     * Sincroniza manualmente el estado reactivo (`value`, `disabled`) con los
+     * elementos nativos del DOM subyacente. Se hace manualmente porque el input
+     * de tipo color no despacha eventos de forma natural si mutamos sus atributos.
+     */
     updated(changed: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
+    /**
+     * Ensambla la estructura del Shadow DOM del campo de color.
+     *
+     * **Estrategia de input en capas:**
+     * Dos elementos `<input>` se apilan absolutamente:
+     * 1. `<input type="color">` (z-index: 2, opacidad: 0) — invisible pero
+     *    clicable, abre el selector de color nativo del sistema operativo.
+     * 2. `<input type="text" readonly>` (z-index: 0) — visible, muestra el
+     *    valor hexadecimal. `tabindex="-1"` en el input de color significa que
+     *    solo el input de texto es alcanzable por teclado.
+     *
+     * El círculo `.swatch` (z-index: 1) está posicionado absolutamente en el
+     * borde inicial del input de texto y estilizado a través de `--_swatch: ${this.value}`,
+     * lo cual establece su `background-color` mediante CSS `var(--_swatch)`.
+     *
+     * **Composición de `fieldClasses`:**
+     * El mapa de clases sigue la convención de nomenclatura field-styles de BeerCSS:
+     * `field`, `label`, `fill`/`border` (variante), `small`/`large`/`extra` (tamaño),
+     * `prefix` (activa el cambio de padding inicial para la muestra), `invalid`, forma.
+     *
+     * **Renderizado condicional de etiqueta / ayuda:**
+     * Usa el centinela `nothing` de Lit para evitar renderizar nodos DOM vacíos cuando
+     * `label` o `helper` son cadenas vacías, previniendo saltos de diseño.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-color-field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-color-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-color-field.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBACa,cAAe,SAAQ,WAAW;IACjB,IAAI,SAAM;IACV,KAAK,SAAM;IACX,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAc;IAEzE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IACR,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAa;IAEjB,OAAO,CAAC,WAAW,CAAoB;IACxC,OAAO,CAAC,UAAU,CAAoB;IAE1D,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAW9C,OAAgB,MAAM,4BA0BpB;IAEO,MAAM;CAuDf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"moni-color-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-color-field.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,qBACa,cAAe,SAAQ,WAAW;IAC9C;;;OAGG;IAC0B,IAAI,SAAM;IAEvC;;;OAGG;IAC0B,KAAK,SAAM;IAExC;;;;OAIG;IAC0B,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAc;IAEzE;;;;OAIG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD;;;;OAIG;IAEH,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IAEpD;;;OAGG;IACyC,QAAQ,UAAS;IAE7D;;;OAGG;IAC0B,MAAM,SAAM;IAEzC;;;;OAIG;IACmD,SAAS,SAAM;IAErE;;;OAGG;IACyC,KAAK,UAAS;IAE1D;;;;OAIG;IAC0B,KAAK,SAAa;IAEjB,OAAO,CAAC,WAAW,CAAoB;IACxC,OAAO,CAAC,UAAU,CAAoB;IAEnE;;;;;OAKG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAW9C,OAAgB,MAAM,4BA0BpB;IAEF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACM,MAAM;CAuDf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,kBAAkB,EAAE,cAAc,CAAC;KACnC;CACD;AAED,eAAe,cAAc,CAAC"}

package/dist/components/moni-color-field.js

@@ -16,59 +16,110 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 /**
- * Material Design 3 Color Field component.
+ * Componente Material Design 3 Color Field (Campo de Color).
  *
- * A specialized text field for color input that combines a native
- * `<input type="color">` with a read-only text display of the selected
- * hex value, wrapped in the standard M3 field shell.
+ * Un campo de texto especializado para la entrada de color que combina un
+ * `<input type="color">` nativo con una visualización de texto de solo lectura del
+ * valor hexadecimal seleccionado, envuelto en la carcasa estándar de campo M3.
  *
- * **Visual architecture:**
- * Extends the field styling pattern used by `<moni-text-field>`. The
- * leading icon slot is replaced by a circular color swatch (`.swatch`)
- * which is absolutely positioned over an invisible native color input.
- * Clicking the swatch opens the system color picker. The text input portion
- * displays the selected hex code and is strictly `readOnly`.
+ * **Arquitectura visual:**
+ * Extiende el patrón de estilo de campo usado por `<moni-text-field>`. El
+ * slot de icono inicial se reemplaza por una muestra de color circular (`.swatch`)
+ * que se posiciona absolutamente sobre una entrada de color nativa invisible.
+ * Al hacer clic en la muestra se abre el selector de color del sistema. La parte de entrada de texto
+ * muestra el código hexadecimal seleccionado y es estrictamente `readOnly`.
  *
- * **State syncing:**
- * The component listens to the native `change` event on the color input,
- * updates the `value` property, and re-dispatches a composed `'change'` event.
- * It does not listen to `input` (continuous drag in the color picker) to avoid
- * excessive event firing, but consumers can attach their own `input` listeners
- * directly to the element if live preview is needed.
+ * **Sincronización de estado:**
+ * El componente escucha el evento nativo `change` en la entrada de color,
+ * actualiza la propiedad `value`, y re-despacha un evento compuesto `'change'`.
+ * No escucha `input` (arrastre continuo en el selector de color) para evitar
+ * el disparo excesivo de eventos, pero los consumidores pueden adjuntar sus propios
+ * escuchas de `input` directamente al elemento si se necesita una vista previa en vivo.
  *
- * @fires change - Bubbles and is composed. Fired when the color picker closes
- *                 and the value is committed. Read `element.value`.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando el selector de color se cierra
+ *                 y el valor se confirma. Leer `element.value`.
  *
  * @example
  * ```html
  * <moni-color-field
- *   label="Theme Color"
+ *   label="Color del Tema"
  *   name="primaryColor"
  *   value="#6750a4"
  *   variant="outlined"
  * ></moni-color-field>
  * ```
  *
- * @csspart field       - The outer `.field` div container.
- * @csspart swatch      - The circular color preview element.
- * @csspart input-color - The native, visually hidden `<input type="color">`.
- * @csspart input-text  - The native `<input type="text">` displaying the hex code.
- * @csspart label       - The floating `<label>` element.
+ * @csspart field       - El contenedor div exterior `.field`.
+ * @csspart swatch      - El elemento de vista previa de color circular.
+ * @csspart input-color - El `<input type="color">` nativo, visualmente oculto.
+ * @csspart input-text  - El `<input type="text">` nativo que muestra el código hexadecimal.
+ * @csspart label       - El elemento flotante `<label>`.
  */
 let MoniColorField = class MoniColorField extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * El nombre del input, enviado con los datos del formulario.
+         * @type {string}
+         */
         this.name = '';
+        /**
+         * El texto de la etiqueta flotante.
+         * @type {string}
+         */
         this.label = '';
+        /**
+         * Variante visual del campo de texto.
+         * @type {'filled' | 'outlined'}
+         * @default 'outlined'
+         */
         this.variant = 'outlined';
+        /**
+         * Define las dimensiones del campo de texto.
+         * @type {'small' | 'medium' | 'large' | 'extra'}
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * Forma del radio del borde del campo.
+         * @type {'round' | 'square' | 'no-round'}
+         * @default 'no-round'
+         */
         this.shape = 'no-round';
+        /**
+         * Deshabilita el campo de color.
+         * @type {boolean}
+         */
         this.disabled = false;
+        /**
+         * Texto de ayuda mostrado debajo del campo.
+         * @type {string}
+         */
         this.helper = '';
+        /**
+         * Texto de error mostrado debajo del campo cuando `error` es true.
+         * Sobrescribe el texto de ayuda.
+         * @type {string}
+         */
         this.errorText = '';
+        /**
+         * Si es true, establece el campo en un estado de error.
+         * @type {boolean}
+         */
         this.error = false;
+        /**
+         * El valor actual del color hexadecimal.
+         * @type {string}
+         * @default '#6750a4'
+         */
         this.value = '#6750a4';
     }
+    /**
+     * Hook de ciclo de vida de Lit.
+     * Sincroniza manualmente el estado reactivo (`value`, `disabled`) con los
+     * elementos nativos del DOM subyacente. Se hace manualmente porque el input
+     * de tipo color no despacha eventos de forma natural si mutamos sus atributos.
+     */
     updated(changed) {
         if (changed.has('value')) {
             if (this._colorInput)
@@ -110,6 +161,30 @@ let MoniColorField = class MoniColorField extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Ensambla la estructura del Shadow DOM del campo de color.
+     *
+     * **Estrategia de input en capas:**
+     * Dos elementos `<input>` se apilan absolutamente:
+     * 1. `<input type="color">` (z-index: 2, opacidad: 0) — invisible pero
+     *    clicable, abre el selector de color nativo del sistema operativo.
+     * 2. `<input type="text" readonly>` (z-index: 0) — visible, muestra el
+     *    valor hexadecimal. `tabindex="-1"` en el input de color significa que
+     *    solo el input de texto es alcanzable por teclado.
+     *
+     * El círculo `.swatch` (z-index: 1) está posicionado absolutamente en el
+     * borde inicial del input de texto y estilizado a través de `--_swatch: ${this.value}`,
+     * lo cual establece su `background-color` mediante CSS `var(--_swatch)`.
+     *
+     * **Composición de `fieldClasses`:**
+     * El mapa de clases sigue la convención de nomenclatura field-styles de BeerCSS:
+     * `field`, `label`, `fill`/`border` (variante), `small`/`large`/`extra` (tamaño),
+     * `prefix` (activa el cambio de padding inicial para la muestra), `invalid`, forma.
+     *
+     * **Renderizado condicional de etiqueta / ayuda:**
+     * Usa el centinela `nothing` de Lit para evitar renderizar nodos DOM vacíos cuando
+     * `label` o `helper` son cadenas vacías, previniendo saltos de diseño.
+     */
     render() {
         const isActive = Boolean(this.value);
         const fieldClasses = {