@moni-labs/moni-ui 0.3.1 → 0.3.2

package/dist/components/moni-fab.js

@@ -16,60 +16,104 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Material Design 3 Floating Action Button (FAB) component.
+ * Componente Material Design 3 Floating Action Button (FAB).
  *
- * FABs represent the primary, or most common, action on a screen. They appear
- * in front of all screen content, typically as a circular shape with an icon in
- * its center.
+ * Los FABs representan la acción principal, o más común, en una pantalla. Aparecen
+ * frente a todo el contenido de la pantalla, típicamente como una forma circular con un icono en
+ * su centro.
  *
- * **M3 spec reference:** `m3-docs/components/floating-action-buttons/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/floating-action-buttons/specs.md`
  *
- * **M3 Expressive Updates & Deprecations (May 2025):**
- * - `size="small"` is **no longer recommended** by M3. Use `medium` (40dp or 56dp)
- *   or `large` (96dp). Deprecated in v0.3.1; will be removed in v1.0.
- * - `shape="circle"` is **not part of M3**. M3 FABs use a `rounded` shape with a
- *   16dp corner radius (which morphs to a `full` radius on hover/focus).
- *   Deprecated in v0.3.1; will be removed in v1.0.
- * - `color="surface"` is **no longer recommended**. Use `primary`, `secondary`,
- *   or `tertiary` to ensure proper color mapping to the M3 theme.
+ * **Actualizaciones y Deprecaciones de M3 Expressive (Mayo 2025):**
+ * - `size="small"` **ya no es recomendado** por M3. Use `medium` (40dp o 56dp)
+ *   o `large` (96dp). Deprecado en v0.3.1; se eliminará en v1.0.
+ * - `shape="circle"` **no es parte de M3**. Los FABs M3 usan una forma `rounded` (redondeada) con un
+ *   radio de esquina de 16dp (que se transforma a un radio `full` al pasar el cursor/enfocar).
+ *   Deprecado en v0.3.1; se eliminará en v1.0.
+ * - `color="surface"` **ya no es recomendado**. Use `primary`, `secondary`,
+ *   o `tertiary` para asegurar un mapeo de color adecuado al tema M3.
  *
- * **Extended FABs:**
- * When `extended` is true, the FAB displays a text label next to the icon.
- * Extended FABs are wider and are typically used when the action needs explicit
- * text to be clear. The `expanded` attribute forces the FAB to its full extended
- * width, useful for animating between standard and extended states on scroll.
+ * **FABs Extendidos:**
+ * Cuando `extended` es true, el FAB muestra una etiqueta de texto junto al icono.
+ * Los FABs extendidos son más anchos y se usan típicamente cuando la acción necesita texto explícito
+ * para ser clara. El atributo `expanded` fuerza al FAB a su ancho extendido completo,
+ * útil para animar entre los estados estándar y extendido al desplazarse.
  *
- * **Positioning:**
- * The `position` attribute applies predefined absolute/fixed positioning
- * (e.g. `bottom-trailing`), snapping the FAB to standard screen corners.
+ * **Posicionamiento:**
+ * El atributo `position` aplica un posicionamiento absoluto/fijo predefinido
+ * (ej. `bottom-trailing`), encajando el FAB en las esquinas estándar de la pantalla.
  *
  * @example
  * ```html
- * <!-- Standard primary FAB -->
+ * <!-- FAB primario estándar -->
  * <moni-fab icon="edit"></moni-fab>
  *
- * <!-- Extended tertiary FAB -->
- * <moni-fab color="tertiary" extended icon="add" label="New task"></moni-fab>
+ * <!-- FAB terciario extendido -->
+ * <moni-fab color="tertiary" extended icon="add" label="Nueva tarea"></moni-fab>
  *
- * <!-- Positioned FAB -->
+ * <!-- FAB posicionado -->
  * <moni-fab position="bottom-trailing" icon="navigation"></moni-fab>
  * ```
  *
- * @csspart button - The internal `<button>` element.
- * @csspart icon   - The container for the icon.
- * @csspart label  - The text label (only visible when extended).
+ * @csspart button - El elemento `<button>` interno.
+ * @csspart icon   - El contenedor para el icono.
+ * @csspart label  - La etiqueta de texto (solo visible cuando está extendido).
  */
 let MoniFab = class MoniFab extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Define las dimensiones del FAB.
+         * `small` está deprecado en M3 Expressive.
+         * @type {'small' | 'medium' | 'large'}
+         * @default 'medium'
+         */
         this.size = 'medium';
+        /**
+         * Mapeo de color semántico del FAB.
+         * `surface` está deprecado en M3.
+         * @type {'primary' | 'secondary' | 'tertiary' | 'surface'}
+         * @default 'primary'
+         */
         this.color = 'primary';
+        /**
+         * Forma de las esquinas del FAB.
+         * `circle` está deprecado en M3 (los FABs deben ser cuadrados redondeados).
+         * @type {'rounded' | 'circle'}
+         * @default 'rounded'
+         */
         this.shape = 'rounded';
+        /**
+         * Alias heredado de `expanded`. Indica si el FAB muestra una etiqueta de texto.
+         * @type {boolean}
+         */
         this.extended = false;
+        /**
+         * Si es true, expande el FAB para mostrar su etiqueta de texto junto al icono.
+         * @type {boolean}
+         */
         this.expanded = false;
+        /**
+         * Deshabilita el FAB.
+         * @type {boolean}
+         */
         this.disabled = false;
+        /**
+         * Nombre del icono (Material Symbols) mostrado dentro del FAB.
+         * @type {string}
+         * @default 'add'
+         */
         this.icon = 'add';
+        /**
+         * Etiqueta de texto mostrada cuando el FAB se expande/extiende.
+         * @type {string}
+         */
         this.label = '';
+        /**
+         * Fija la posición del FAB relativa a los bordes de la pantalla.
+         * @type {'bottom-trailing' | 'bottom-leading' | 'top-trailing' | 'top-leading'}
+         * @default 'bottom-trailing'
+         */
         this.position = 'bottom-trailing';
     }
     static { MoniFab_1 = this; }
@@ -127,7 +171,7 @@ let MoniFab = class MoniFab extends MoniElement {
 				font-size: 1rem;
 				font-weight: 500;
 				color: var(--on-primary);
-				/* Default: no padding so icon is centered; padding added when label exists */
+				/* Por defecto: sin relleno para que el icono se centre; el relleno se añade cuando existe etiqueta */
 				padding: 0 1.5rem;
 				background-color: var(--primary);
 				border: 0.0625rem solid transparent;
@@ -157,7 +201,7 @@ let MoniFab = class MoniFab extends MoniElement {
 				box-shadow: var(--elevate1);
 			}
 
-			/* When no label: icon-only, remove horizontal padding so icon centers */
+			/* Cuando no hay etiqueta: solo icono, eliminar relleno horizontal para que el icono se centre */
 			.button:not(:has(> .label:not(:empty))) {
 				padding-inline: 0;
 			}
@@ -226,8 +270,8 @@ let MoniFab = class MoniFab extends MoniElement {
 				color: inherit;
 			}
 
-			/* Label is always rendered but empty string hides via overflow.
-			   When label prop is set, it appears. */
+			/* La etiqueta siempre se renderiza pero la cadena vacía se oculta mediante overflow.
+			   Cuando se establece la propiedad label, aparece. */
 			.label {
 				white-space: nowrap;
 				max-inline-size: 16rem;
@@ -240,17 +284,31 @@ let MoniFab = class MoniFab extends MoniElement {
 				display: none;
 			}
 
-			/* Circle shape: hide label completely */
+			/* Forma circular: ocultar etiqueta completamente */
 			:host([shape='circle']) .label,
 			:host([shape='circle']) slot {
 				display: none !important;
 			}
-			/* Circle: remove padding, make it a perfect circle */
+			/* Círculo: eliminar relleno, hacerlo un círculo perfecto */
 			:host([shape='circle']) .button {
 				padding: 0 !important;
 			}
 		`
     ]; }
+    /**
+     * Renderiza el botón FAB con su icono, etiqueta extendida opcional, y estado de carga.
+     *
+     * **Composición de clases:**
+     * - `'fab'` — estilos base del FAB (redondo, 56dp, elevado).
+     * - `this.size` (`'small'` = 40dp, `'large'` = 96dp, por defecto = 56dp).
+     * - `this.variant` — esquema de color (`'primary'`, `'secondary'`, `'tertiary'`, `'surface'`).
+     * - `'extended'` — se añade cuando se establece `label`; ensancha el FAB en forma de píldora
+     *   y revela el texto de la etiqueta con una transición CSS `max-width`.
+     *
+     * **Estado de carga:**
+     * Cuando `loading=true`, un spinner `<moni-progress>` reemplaza el icono. La etiqueta
+     * permanece visible para mantener el ancho del FAB extendido y prevenir saltos de diseño.
+     */
     render() {
         const classes = [
             'button',

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

@@ -7,75 +7,163 @@
 import { MoniElement } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Material Design 3 File Field component.
+ * Componente Material Design 3 File Field (Campo de Archivo).
  *
- * A specialized field component that provides a styled, accessible alternative
- * to the native `<input type="file">`. It wraps a native file input inside
- * the M3 `.field` shell and presents a read-only text input showing the
- * selected file name(s) alongside a stylized "Choose file" action button.
+ * Un componente de campo especializado que proporciona una alternativa estilizada y accesible
+ * al `<input type="file">` nativo. Envuelve un input de archivo nativo dentro de
+ * la carcasa `.field` de M3 y presenta un input de texto de solo lectura que muestra los
+ * nombres de archivo(s) seleccionado(s) junto a un botón de acción "Seleccionar archivo" estilizado.
  *
- * **Visual architecture:**
- * The component leverages the `fieldStyles` CSS patterns. The internal DOM
- * structure is specifically ordered as:
+ * **Arquitectura visual:**
+ * El componente aprovecha los patrones CSS `fieldStyles`. La estructura interna del DOM
+ * está ordenada específicamente como:
  * `[text input] -> [label] -> [file input] -> [output]`
- * This specific ordering ensures that the CSS adjacent sibling selector
- * (`input + label`) can correctly float the label when the field is populated,
- * even though the visible field is actually the read-only text input.
+ * Este ordenamiento específico asegura que el selector CSS de hermano adyacente
+ * (`input + label`) pueda flotar correctamente la etiqueta cuando el campo está poblado,
+ * a pesar de que el campo visible sea realmente el input de texto de solo lectura.
  *
- * **State management:**
- * When the user selects files via the hidden file input, the component listens
- * for the native `change` event, reads `input.files`, and updates the read-only
- * text input with a comma-separated list of file names. The `value` property
- * is kept in sync, and a composed `'change'` event is re-dispatched.
+ * **Gestión del estado:**
+ * Cuando el usuario selecciona archivos a través del input de archivo oculto, el componente escucha
+ * el evento nativo `change`, lee `input.files`, y actualiza el input de texto
+ * de solo lectura con una lista separada por comas de los nombres de archivo. La propiedad `value`
+ * se mantiene sincronizada, y se re-despacha un evento compuesto `'change'`.
  *
- * @fires change - Bubbles and is composed. Fired when files are selected or
- *                 cleared. The consumer can read the internal input's `files`
- *                 list by querying the component.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando se seleccionan o borran
+ *                 archivos. El consumidor puede leer la lista de `files` del input interno
+ *                 consultando el componente.
  *
  * @example
  * ```html
- * <!-- Single file upload -->
+ * <!-- Carga de un solo archivo -->
  * <moni-file-field
- *   label="Profile picture"
+ *   label="Foto de perfil"
  *   name="avatar"
  *   accept="image/png, image/jpeg"
- *   button-label="Browse..."
+ *   button-label="Explorar..."
  * ></moni-file-field>
  *
- * <!-- Multiple file upload with error state -->
+ * <!-- Carga de múltiples archivos con estado de error -->
  * <moni-file-field
- *   label="Documents"
+ *   label="Documentos"
  *   multiple
  *   error
- *   error-text="Files exceed maximum size limit"
+ *   error-text="Los archivos superan el límite de tamaño máximo"
  * ></moni-file-field>
  * ```
  *
- * @csspart field       - The outer `.field` div container.
- * @csspart input-text  - The visible read-only `<input type="text">`.
- * @csspart label       - The floating `<label>` element.
- * @csspart input-file  - The hidden native `<input type="file">`.
- * @csspart button      - The button element (styled via CSS `::file-selector-button`).
+ * @csspart field       - El contenedor div exterior `.field`.
+ * @csspart input-text  - El `<input type="text">` de solo lectura visible.
+ * @csspart label       - El elemento `<label>` flotante.
+ * @csspart input-file  - El `<input type="file">` nativo oculto.
+ * @csspart button      - El elemento de botón (estilizado vía CSS `::file-selector-button`).
  */
 export declare class MoniFileField 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';
+    /**
+     * El atributo `accept` para el input de archivo (ej. `image/*, .pdf`).
+     * @type {string}
+     */
     accept: string;
+    /**
+     * Permite seleccionar múltiples archivos si es true.
+     * @type {boolean}
+     */
     multiple: boolean;
+    /**
+     * Texto para el botón de selección de archivo.
+     * @type {string}
+     * @default 'Choose file'
+     */
     buttonLabel: string;
+    /**
+     * Deshabilita el campo de archivo.
+     * @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;
+    /**
+     * La representación en cadena de los archivos seleccionados (solo lectura para el usuario).
+     * @type {string}
+     */
     value: string;
+    /**
+     * Nombre del icono inicial (Material Symbols).
+     * @type {string}
+     */
     icon: string;
+    /**
+     * Nombre del icono final (Material Symbols).
+     * @type {string}
+     * @default 'folder_open'
+     */
     trailingIcon: string;
     private _fileInput;
+    /**
+     * Hook del ciclo de vida reactivo (Lit).
+     * Transfiere de manera imperativa el estado de discapacidad (disabled) de Lit
+     * hacia el nodo `<input type="file">` invisible en el Shadow DOM, asegurando
+     * que el componente nativo reaccione adecuadamente a nivel navegador.
+     */
     updated(changed: Map<string, unknown>): void;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderiza el campo de archivo como un `<input type="file">` oculto + una zona de soltar visible.
+     *
+     * El `<input type="file">` está oculto (pero no con `display: none`) para
+     * aprovechar el selector de archivos nativo del navegador. Al hacer clic en la zona de soltar visible
+     * se invoca programáticamente `_input.click()` para abrir el diálogo de archivo.
+     *
+     * **Arrastrar y soltar (Drag-and-drop):**
+     * `@dragover` / `@dragleave` / `@drop` en el contenedor de la zona de soltar gestionan
+     * el estado `dragging` que aplica una clase de resaltado CSS.
+     *
+     * **Visualización del nombre del archivo:**
+     * `_fileName` (derivado del `.name` del último archivo seleccionado) se muestra
+     * como una cadena de una sola línea truncada. Cuando no hay ningún archivo seleccionado,
+     * se muestra en su lugar el atributo `label` o un marcador de posición genérico.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-file-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-file-field.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,aAAc,SAAQ,WAAW;IAChB,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;IACvB,MAAM,SAAM;IACG,QAAQ,UAAS;IAE7D,WAAW,SAAiB;IACgB,QAAQ,UAAS;IAChC,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAM;IACX,IAAI,SAAM;IACkB,YAAY,SACtD;IAEc,OAAO,CAAC,UAAU,CAAoB;IAE1D,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BAepB;IAEO,MAAM;CAoEf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,aAAa,CAAC;KACjC;CACD;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"moni-file-field.d.ts","sourceRoot":"","sources":["../../src/components/moni-file-field.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,aAAc,SAAQ,WAAW;IAC7C;;;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;IAC0B,MAAM,SAAM;IAEzC;;;OAGG;IACyC,QAAQ,UAAS;IAE7D;;;;OAIG;IAEH,WAAW,SAAiB;IAE5B;;;OAGG;IACyC,QAAQ,UAAS;IAE7D;;;OAGG;IAC0B,MAAM,SAAM;IAEzC;;;;OAIG;IACmD,SAAS,SAAM;IAErE;;;OAGG;IACyC,KAAK,UAAS;IAE1D;;;OAGG;IAC0B,KAAK,SAAM;IAExC;;;OAGG;IAC0B,IAAI,SAAM;IAEvC;;;;OAIG;IACsD,YAAY,SACtD;IAEc,OAAO,CAAC,UAAU,CAAoB;IAEnE;;;;;OAKG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAO9C,OAAgB,MAAM,4BAepB;IAEF;;;;;;;;;;;;;;;OAeG;IACM,MAAM;CAoEf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,aAAa,CAAC;KACjC;CACD;AAED,eAAe,aAAa,CAAC"}

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

@@ -17,75 +17,147 @@ import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 import './moni-icon.js';
 /**
- * Material Design 3 File Field component.
+ * Componente Material Design 3 File Field (Campo de Archivo).
  *
- * A specialized field component that provides a styled, accessible alternative
- * to the native `<input type="file">`. It wraps a native file input inside
- * the M3 `.field` shell and presents a read-only text input showing the
- * selected file name(s) alongside a stylized "Choose file" action button.
+ * Un componente de campo especializado que proporciona una alternativa estilizada y accesible
+ * al `<input type="file">` nativo. Envuelve un input de archivo nativo dentro de
+ * la carcasa `.field` de M3 y presenta un input de texto de solo lectura que muestra los
+ * nombres de archivo(s) seleccionado(s) junto a un botón de acción "Seleccionar archivo" estilizado.
  *
- * **Visual architecture:**
- * The component leverages the `fieldStyles` CSS patterns. The internal DOM
- * structure is specifically ordered as:
+ * **Arquitectura visual:**
+ * El componente aprovecha los patrones CSS `fieldStyles`. La estructura interna del DOM
+ * está ordenada específicamente como:
  * `[text input] -> [label] -> [file input] -> [output]`
- * This specific ordering ensures that the CSS adjacent sibling selector
- * (`input + label`) can correctly float the label when the field is populated,
- * even though the visible field is actually the read-only text input.
+ * Este ordenamiento específico asegura que el selector CSS de hermano adyacente
+ * (`input + label`) pueda flotar correctamente la etiqueta cuando el campo está poblado,
+ * a pesar de que el campo visible sea realmente el input de texto de solo lectura.
  *
- * **State management:**
- * When the user selects files via the hidden file input, the component listens
- * for the native `change` event, reads `input.files`, and updates the read-only
- * text input with a comma-separated list of file names. The `value` property
- * is kept in sync, and a composed `'change'` event is re-dispatched.
+ * **Gestión del estado:**
+ * Cuando el usuario selecciona archivos a través del input de archivo oculto, el componente escucha
+ * el evento nativo `change`, lee `input.files`, y actualiza el input de texto
+ * de solo lectura con una lista separada por comas de los nombres de archivo. La propiedad `value`
+ * se mantiene sincronizada, y se re-despacha un evento compuesto `'change'`.
  *
- * @fires change - Bubbles and is composed. Fired when files are selected or
- *                 cleared. The consumer can read the internal input's `files`
- *                 list by querying the component.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando se seleccionan o borran
+ *                 archivos. El consumidor puede leer la lista de `files` del input interno
+ *                 consultando el componente.
  *
  * @example
  * ```html
- * <!-- Single file upload -->
+ * <!-- Carga de un solo archivo -->
  * <moni-file-field
- *   label="Profile picture"
+ *   label="Foto de perfil"
  *   name="avatar"
  *   accept="image/png, image/jpeg"
- *   button-label="Browse..."
+ *   button-label="Explorar..."
  * ></moni-file-field>
  *
- * <!-- Multiple file upload with error state -->
+ * <!-- Carga de múltiples archivos con estado de error -->
  * <moni-file-field
- *   label="Documents"
+ *   label="Documentos"
  *   multiple
  *   error
- *   error-text="Files exceed maximum size limit"
+ *   error-text="Los archivos superan el límite de tamaño máximo"
  * ></moni-file-field>
  * ```
  *
- * @csspart field       - The outer `.field` div container.
- * @csspart input-text  - The visible read-only `<input type="text">`.
- * @csspart label       - The floating `<label>` element.
- * @csspart input-file  - The hidden native `<input type="file">`.
- * @csspart button      - The button element (styled via CSS `::file-selector-button`).
+ * @csspart field       - El contenedor div exterior `.field`.
+ * @csspart input-text  - El `<input type="text">` de solo lectura visible.
+ * @csspart label       - El elemento `<label>` flotante.
+ * @csspart input-file  - El `<input type="file">` nativo oculto.
+ * @csspart button      - El elemento de botón (estilizado vía CSS `::file-selector-button`).
  */
 let MoniFileField = class MoniFileField 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';
+        /**
+         * El atributo `accept` para el input de archivo (ej. `image/*, .pdf`).
+         * @type {string}
+         */
         this.accept = '';
+        /**
+         * Permite seleccionar múltiples archivos si es true.
+         * @type {boolean}
+         */
         this.multiple = false;
+        /**
+         * Texto para el botón de selección de archivo.
+         * @type {string}
+         * @default 'Choose file'
+         */
         this.buttonLabel = 'Choose file';
+        /**
+         * Deshabilita el campo de archivo.
+         * @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;
+        /**
+         * La representación en cadena de los archivos seleccionados (solo lectura para el usuario).
+         * @type {string}
+         */
         this.value = '';
+        /**
+         * Nombre del icono inicial (Material Symbols).
+         * @type {string}
+         */
         this.icon = '';
+        /**
+         * Nombre del icono final (Material Symbols).
+         * @type {string}
+         * @default 'folder_open'
+         */
         this.trailingIcon = 'folder_open';
     }
+    /**
+     * Hook del ciclo de vida reactivo (Lit).
+     * Transfiere de manera imperativa el estado de discapacidad (disabled) de Lit
+     * hacia el nodo `<input type="file">` invisible en el Shadow DOM, asegurando
+     * que el componente nativo reaccione adecuadamente a nivel navegador.
+     */
     updated(changed) {
         if (this._fileInput) {
             if (changed.has('disabled'))
@@ -108,6 +180,22 @@ let MoniFileField = class MoniFileField extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Renderiza el campo de archivo como un `<input type="file">` oculto + una zona de soltar visible.
+     *
+     * El `<input type="file">` está oculto (pero no con `display: none`) para
+     * aprovechar el selector de archivos nativo del navegador. Al hacer clic en la zona de soltar visible
+     * se invoca programáticamente `_input.click()` para abrir el diálogo de archivo.
+     *
+     * **Arrastrar y soltar (Drag-and-drop):**
+     * `@dragover` / `@dragleave` / `@drop` en el contenedor de la zona de soltar gestionan
+     * el estado `dragging` que aplica una clase de resaltado CSS.
+     *
+     * **Visualización del nombre del archivo:**
+     * `_fileName` (derivado del `.name` del último archivo seleccionado) se muestra
+     * como una cadena de una sola línea truncada. Cuando no hay ningún archivo seleccionado,
+     * se muestra en su lugar el atributo `label` o un marcador de posición genérico.
+     */
     render() {
         const isActive = Boolean(this.value);
         const hasLeading = Boolean(this.icon);