@moni-labs/moni-ui 0.3.1 → 0.3.2

package/src/components/moni-file-field.ts

@@ -13,80 +13,166 @@ 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`).
  */
 @customElement('moni-file-field')
 export class MoniFileField extends MoniElement {
+	/**
+	 * El nombre del input, enviado con los datos del formulario.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * El texto de la etiqueta flotante.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) label = '';
+
+	/**
+	 * Variante visual del campo de texto.
+	 * @type {'filled' | 'outlined'}
+	 * @default 'outlined'
+	 */
 	@property({ reflect: true }) variant: 'filled' | 'outlined' = 'outlined';
+
+	/**
+	 * Define las dimensiones del campo de texto.
+	 * @type {'small' | 'medium' | 'large' | 'extra'}
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' | 'extra' = 'medium';
+
+	/**
+	 * Forma del radio del borde del campo.
+	 * @type {'round' | 'square' | 'no-round'}
+	 * @default 'no-round'
+	 */
 	@property({ reflect: true })
 	shape: 'round' | 'square' | 'no-round' = 'no-round';
+
+	/**
+	 * El atributo `accept` para el input de archivo (ej. `image/*, .pdf`).
+	 * @type {string}
+	 */
 	@property({ reflect: true }) accept = '';
+
+	/**
+	 * Permite seleccionar múltiples archivos si es true.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) multiple = false;
+
+	/**
+	 * Texto para el botón de selección de archivo.
+	 * @type {string}
+	 * @default 'Choose file'
+	 */
 	@property({ reflect: true, attribute: 'button-label' })
 	buttonLabel = 'Choose file';
+
+	/**
+	 * Deshabilita el campo de archivo.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * Texto de ayuda mostrado debajo del campo.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) helper = '';
+
+	/**
+	 * Texto de error mostrado debajo del campo cuando `error` es true.
+	 * Sobrescribe el texto de ayuda.
+	 * @type {string}
+	 */
 	@property({ reflect: true, attribute: 'error-text' }) errorText = '';
+
+	/**
+	 * Si es true, establece el campo en un estado de error.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) error = false;
+
+	/**
+	 * La representación en cadena de los archivos seleccionados (solo lectura para el usuario).
+	 * @type {string}
+	 */
 	@property({ reflect: true }) value = '';
+
+	/**
+	 * Nombre del icono inicial (Material Symbols).
+	 * @type {string}
+	 */
 	@property({ reflect: true }) icon = '';
+
+	/**
+	 * Nombre del icono final (Material Symbols).
+	 * @type {string}
+	 * @default 'folder_open'
+	 */
 	@property({ reflect: true, attribute: 'trailing-icon' }) trailingIcon =
 		'folder_open';
 
 	@query('input[type="file"]') private _fileInput!: HTMLInputElement;
 
+	/**
+	 * 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.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (this._fileInput) {
 			if (changed.has('disabled'))
@@ -111,6 +197,22 @@ export 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.
+	 */
 	override render() {
 		const isActive = Boolean(this.value);
 		const hasLeading = Boolean(this.icon);

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

@@ -14,7 +14,7 @@ describe('moni-icon', () => {
 		el.remove();
 	});
 
-	it('renders the icon name as text content', async () => {
+	it('renderiza el nombre del icono como contenido de texto', async () => {
 		el.name = 'add';
 		await el.updateComplete;
 		const slot = el.shadowRoot?.querySelector('slot') as HTMLSlotElement;
@@ -24,7 +24,7 @@ describe('moni-icon', () => {
 		expect(assigned.join('')).toContain('add');
 	});
 
-	it('renders slot fallback when no name is set', async () => {
+	it('renderiza el respaldo del slot (fallback) cuando no se establece nombre', async () => {
 		el.name = '';
 		el.textContent = 'FALLBACK';
 		await el.updateComplete;
@@ -35,35 +35,35 @@ describe('moni-icon', () => {
 		expect(assigned.join('')).toContain('FALLBACK');
 	});
 
-	it('reflects the name attribute', async () => {
+	it('refleja el atributo name', async () => {
 		el.name = 'close';
 		await el.updateComplete;
 		expect(el.getAttribute('name')).toBe('close');
 	});
 
-	it('applies the filled attribute', async () => {
+	it('aplica el atributo filled', async () => {
 		el.filled = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('filled')).toBe(true);
 	});
 
-	it('reflects the size attribute', async () => {
+	it('refleja el atributo size', async () => {
 		el.size = 'large';
 		await el.updateComplete;
 		expect(el.getAttribute('size')).toBe('large');
 	});
 
-	it('inherits color from its parent (host color: inherit)', async () => {
+	it('hereda el color de su padre (host color: inherit)', async () => {
 		const parent = document.createElement('div');
 		parent.style.color = 'rgb(255, 0, 128)';
 		parent.appendChild(el);
 		document.body.appendChild(parent);
 		await el.updateComplete;
-		// The host declaration `color: inherit` should be present in the
-		// shadow stylesheet so the Material Symbols glyph takes the parent
-		// text color. jsdom does not fully resolve custom-property-driven
-		// styles, so we just assert that the element renders inside the
-		// colored wrapper without throwing.
+		// La declaración del host color: inherit debería estar presente en la
+		// hoja de estilo shadow para que el glifo de Material Symbols tome el color
+		// de texto del padre. jsdom no resuelve completamente los estilos dirigidos
+		// por propiedades personalizadas, así que solo afirmamos que el elemento se
+		// renderiza dentro del contenedor coloreado sin lanzar errores.
 		expect(parent.contains(el)).toBe(true);
 		parent.remove();
 	});

package/src/components/moni-icon.ts

@@ -10,66 +10,66 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Visual-only icon component using Material Symbols variable font.
+ * Componente de icono solo visual que utiliza la fuente variable Material Symbols.
  *
- * Renders a Material Symbols glyph by its ligature name. The icon font
- * must be loaded globally by the host document — it is not bundled with
- * the component. Add the font via the `@moni-labs/moni-ui/styles` stylesheet
- * or by including the Google Fonts CDN link.
+ * Renderiza un glifo de Material Symbols por el nombre de su ligadura. La fuente de iconos
+ * debe cargarse globalmente en el documento host — no viene empaquetada con
+ * el componente. Añada la fuente a través de la hoja de estilos `@moni-labs/moni-ui/styles`
+ * o incluyendo el enlace CDN de Google Fonts.
  *
- * **Font rendering:**
- * The icon uses `font-family: var(--font-icon)` which defaults to
- * `'Material Symbols Rounded'`. Override `--font-icon-override` in the
- * host document's `:root` to switch to a different icon set variant
- * (e.g. `'Material Symbols Outlined'` or `'Material Symbols Sharp'`).
+ * **Renderizado de fuentes:**
+ * El icono usa `font-family: var(--font-icon)` que por defecto es
+ * `'Material Symbols Rounded'`. Sobrescriba `--font-icon-override` en el
+ * `:root` del documento host para cambiar a una variante diferente del conjunto de iconos
+ * (ej. `'Material Symbols Outlined'` o `'Material Symbols Sharp'`).
  *
- * **Variable font settings:**
- * The default `font-variation-settings` is `'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24`.
- * Setting the `filled` attribute switches to `'FILL' 1` for the solid icon variant.
+ * **Ajustes de fuente variable:**
+ * El valor por defecto de `font-variation-settings` es `'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24`.
+ * Establecer el atributo `filled` cambia a `'FILL' 1` para la variante de icono sólido.
  *
- * **Color inheritance:**
- * The icon always inherits color from its parent via `color: inherit`, making it
- * automatically adapt to button variants, chip selected states, list item active
- * states, and other color-context containers.
+ * **Herencia de color:**
+ * El icono siempre hereda el color de su padre a través de `color: inherit`, haciéndolo
+ * adaptarse automáticamente a las variantes de botones, estados seleccionados de chips, estados
+ * activos de elementos de lista y otros contenedores de contexto de color.
  *
  * @example
  * ```html
- * <!-- Basic icon -->
+ * <!-- Icono básico -->
  * <moni-icon name="home"></moni-icon>
  *
- * <!-- Filled large icon -->
+ * <!-- Icono grande rellenado -->
  * <moni-icon name="favorite" size="large" filled></moni-icon>
  *
- * <!-- Custom SVG override via slot -->
+ * <!-- Sobrescritura de SVG personalizado a través de slot -->
  * <moni-icon>
  *   <svg slot="default" viewBox="0 0 24 24">...</svg>
  * </moni-icon>
  * ```
  *
- * @slot default - Fallback content when `name` is empty. Accepts `<svg>` or `<img>`
- *                 elements which are sized to 100% of the icon box.
+ * @slot default - Contenido de respaldo cuando `name` está vacío. Acepta elementos `<svg>` o `<img>`
+ *                 que se dimensionan al 100% de la caja del icono.
  *
- * @cssproperty --font-icon-override - Overrides the icon font family at the
- *                                     document level. Set on `:root`.
+ * @cssproperty --font-icon-override - Sobrescribe la familia de fuentes de iconos a
+ *                                     nivel del documento. Establecer en `:root`.
  */
 @customElement('moni-icon')
 export class MoniIcon extends MoniElement {
 	/**
-	 * Material Symbols ligature name for the icon to render.
+	 * Nombre de la ligadura de Material Symbols para el icono a renderizar.
 	 *
-	 * Use the name exactly as shown on https://fonts.google.com/icons
-	 * (e.g. `'home'`, `'settings'`, `'arrow_forward'`).
-	 * When empty, the default slot is rendered instead.
+	 * Utilice el nombre exactamente como se muestra en https://fonts.google.com/icons
+	 * (ej. `'home'`, `'settings'`, `'arrow_forward'`).
+	 * Cuando está vacío, se renderiza el slot por defecto en su lugar.
 	 *
 	 * @default ''
 	 */
 	@property({ reflect: true }) name = '';
 
 	/**
-	 * Size of the icon bounding box.
+	 * Tamaño de la caja delimitadora del icono.
 	 *
-	 * Maps to the `--_size` custom property:
-	 * | Value      | Size     |
+	 * Se mapea a la propiedad personalizada `--_size`:
+	 * | Valor      | Tamaño   |
 	 * |------------|----------|
 	 * | `'tiny'`   | 1rem     |
 	 * | `'small'`  | 1.25rem  |
@@ -83,12 +83,12 @@ export class MoniIcon extends MoniElement {
 	size: 'tiny' | 'small' | 'medium' | 'large' | 'extra' = 'medium';
 
 	/**
-	 * When `true`, switches to the filled variant of the icon by setting
+	 * Cuando es `true`, cambia a la variante rellenada (filled) del icono estableciendo
 	 * `font-variation-settings: 'FILL' 1`.
 	 *
-	 * This works only with variable icon fonts that include the `FILL` axis
-	 * (all Material Symbols variants do). It has no effect if a different
-	 * icon font is loaded that does not support `FILL`.
+	 * Esto funciona solo con fuentes de iconos variables que incluyen el eje `FILL`
+	 * (todas las variantes de Material Symbols lo hacen). No tiene efecto si se carga
+	 * una fuente de iconos diferente que no soporte `FILL`.
 	 *
 	 * @default false
 	 */
@@ -118,9 +118,9 @@ export class MoniIcon extends MoniElement {
 				line-height: 1;
 				inline-size: var(--_size);
 				block-size: var(--_size);
-				/* Explicit inherit so the icon glyph picks up color from
-				   whatever consumer wraps it (button variants, chip selected
-				   state, list-item active, etc.). */
+				/* Herencia explícita para que el glifo del icono tome el color de
+				   cualquier consumidor que lo envuelva (variantes de botones, estado
+				   seleccionado de chip, activo de list-item, etc.). */
 				color: inherit;
 			}
 
@@ -153,6 +153,11 @@ export class MoniIcon extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el ícono utilizando la fuente de variables Material Symbols.
+	 * Si no se provee un `name`, el `<slot>` actúa como fallback permitiendo
+	 * inyectar un SVG personalizado directamente.
+	 */
 	override render() {
 		return html`<slot>${this.name}</slot>`;
 	}

package/src/components/moni-list-item.test.ts

@@ -15,13 +15,13 @@ describe('moni-list-item (P5.3 — recreated)', () => {
 		el.remove();
 	});
 
-	it('defaults to lines=1', async () => {
+	it('por defecto es lines=1', async () => {
 		await el.updateComplete;
 		expect(el.lines).toBe(1);
 		expect(el.getAttribute('lines')).toBe('1');
 	});
 
-	it('renders the headline slot', async () => {
+	it('renderiza el slot de headline', async () => {
 		await el.updateComplete;
 		const headline = el.shadowRoot?.querySelector('[part="headline"]');
 		expect(headline).toBeTruthy();
@@ -31,7 +31,7 @@ describe('moni-list-item (P5.3 — recreated)', () => {
 		expect(text).toBe('Item headline');
 	});
 
-	it('does not render supporting/meta slots when lines=1', async () => {
+	it('no renderiza los slots supporting/meta cuando lines=1', async () => {
 		await el.updateComplete;
 		const supporting = el.shadowRoot?.querySelector('[part="supporting"]');
 		const meta = el.shadowRoot?.querySelector('[part="meta"]');
@@ -39,7 +39,7 @@ describe('moni-list-item (P5.3 — recreated)', () => {
 		expect(meta).toBeFalsy();
 	});
 
-	it('renders supporting slot when lines=2', async () => {
+	it('renderiza el slot supporting cuando lines=2', async () => {
 		el.lines = 2;
 		const sup = document.createElement('span');
 		sup.setAttribute('slot', 'supporting');
@@ -50,7 +50,7 @@ describe('moni-list-item (P5.3 — recreated)', () => {
 		expect(supporting).toBeTruthy();
 	});
 
-	it('renders meta slot when lines=3', async () => {
+	it('renderiza el slot meta cuando lines=3', async () => {
 		el.lines = 3;
 		const sup = document.createElement('span');
 		sup.setAttribute('slot', 'supporting');
@@ -67,7 +67,7 @@ describe('moni-list-item (P5.3 — recreated)', () => {
 		expect(metaEl).toBeTruthy();
 	});
 
-	it('reflects active and disabled attributes', async () => {
+	it('refleja los atributos active y disabled', async () => {
 		el.active = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('active')).toBe(true);
@@ -77,14 +77,14 @@ describe('moni-list-item (P5.3 — recreated)', () => {
 		expect(el.hasAttribute('disabled')).toBe(true);
 	});
 
-	it('renders an avatar when the avatar attribute is set', async () => {
+	it('renderiza un avatar cuando el atributo avatar está establecido', async () => {
 		el.avatar = 'https://example.com/avatar.png';
 		await el.updateComplete;
 		const avatar = el.shadowRoot?.querySelector('[part="avatar"]');
 		expect(avatar).toBeTruthy();
 	});
 
-	it('renders a leading icon when the icon attribute is set', async () => {
+	it('renderiza un icono leading cuando el atributo icon está establecido', async () => {
 		el.icon = 'home';
 		await el.updateComplete;
 		const leading = el.shadowRoot?.querySelector('[part="leading"]');
@@ -93,14 +93,14 @@ describe('moni-list-item (P5.3 — recreated)', () => {
 		expect(moniIcon?.getAttribute('name')).toBe('home');
 	});
 
-	it('renders a trailing icon when the trailing-icon attribute is set', async () => {
+	it('renderiza un icono trailing cuando el atributo trailing-icon está establecido', async () => {
 		el.setAttribute('trailing-icon', 'more_vert');
 		await el.updateComplete;
 		const trailing = el.shadowRoot?.querySelector('[part="trailing"]');
 		expect(trailing).toBeTruthy();
 	});
 
-	it('renders an <a> wrapper when href is set, otherwise the row is inline', async () => {
+	it('renderiza un contenedor <a> cuando href está establecido, de lo contrario la fila es inline', async () => {
 		await el.updateComplete;
 		let row = el.shadowRoot?.querySelector('a');
 		expect(row).toBeFalsy();