@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-select-option.d.ts

@@ -6,42 +6,41 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Material Design 3 Select Option component.
+ * Componente Material Design 3 Select Option (Opción de Selección).
  *
- * An individual selectable item designed to be placed inside a
- * `<moni-select>` dropdown.
+ * Un elemento individual seleccionable diseñado para colocarse dentro de un
+ * menú desplegable `<moni-select>`.
  *
- * **Interaction and layout:**
- * Options are rendered as accessible `<li>` elements styled identically to
- * `<moni-menu-item>`. When slotted into a `<moni-select>`, the parent
- * component extracts their `value`, `label`, and `group` attributes to build
- * its internal data model and handles the actual selection logic, keyboard
- * navigation, and rendering within the dropdown popup.
+ * **Interacción y diseño (layout):**
+ * Las opciones se renderizan como elementos `<li>` accesibles estilizados de forma idéntica a
+ * `<moni-menu-item>`. Cuando se insertan en un `<moni-select>`, el componente
+ * padre extrae sus atributos `value`, `label` y `group` para construir
+ * su modelo de datos interno y maneja la lógica de selección real, la navegación
+ * por teclado y el renderizado dentro del popup desplegable.
  *
- * **Grouping:**
- * Options can be categorized into subcategories by providing a `group`
- * attribute. The parent `<moni-select>` uses this to automatically generate
- * group headers (`<moni-select-group>`) in the dropdown list.
+ * **Agrupación:**
+ * Las opciones se pueden clasificar en subcategorías proporcionando un atributo
+ * `group`. El `<moni-select>` padre usa esto para generar automáticamente
+ * encabezados de grupo (`<moni-select-group>`) en la lista desplegable.
  *
  * @example
  * ```html
- * <moni-select label="Favorite framework">
- *   <!-- Standard option -->
+ * <moni-select label="Framework favorito">
+ *   <!-- Opción estándar -->
  *   <moni-select-option value="lit">Lit Element</moni-select-option>
  *
- *   <!-- Disabled option -->
- *   <moni-select-option value="react" disabled>React (not allowed)</moni-select-option>
+ *   <!-- Opción deshabilitada -->
+ *   <moni-select-option value="react" disabled>React (no permitido)</moni-select-option>
  *
- *   <!-- Grouped option -->
- *   <moni-select-option value="vue" group="Other">Vue.js</moni-select-option>
+ *   <!-- Opción agrupada -->
+ *   <moni-select-option value="vue" group="Otros">Vue.js</moni-select-option>
  * </moni-select>
  * ```
  *
- * @slot default - The text label for the option. If the `label` attribute is
- *                omitted, the parent `<moni-select>` will read this slot's
- *                `textContent`.
+ * @slot default - La etiqueta de texto para la opción. Si se omite el atributo `label`,
+ *                 el `<moni-select>` padre leerá el `textContent` de esta ranura (slot).
  *
- * @csspart item - The outer `<li>` element.
+ * @csspart item - El elemento `<li>` exterior.
  */
 export declare class MoniSelectOption extends MoniElement {
     value: string;
@@ -50,6 +49,14 @@ export declare class MoniSelectOption extends MoniElement {
     selected: boolean;
     disabled: boolean;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderiza la fila de la opción como un elemento de lista accesible con `role="option"`.
+     *
+     * `aria-selected=${this.selected}` permite a los lectores de pantalla anunciar el estado
+     * de selección actual cuando el usuario navega por el cuadro de lista con las teclas de flecha.
+     * Cuando `selected=true`, se renderiza un icono de marca de verificación principal (leading checkmark) a través de `<moni-icon name="check">`
+     * en lugar del slot del icono principal, según la especificación de opciones de Select de M3.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-select-option.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-select-option.d.ts","sourceRoot":"","sources":["../../src/components/moni-select-option.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBACa,gBAAiB,SAAQ,WAAW;IACnB,KAAK,SAAM;IACX,KAAK,SAAM;IACX,KAAK,SAAM;IACI,QAAQ,UAAS;IACjB,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BA4CpB;IAEO,MAAM;CAQf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,oBAAoB,EAAE,gBAAgB,CAAC;KACvC;CACD;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"moni-select-option.d.ts","sourceRoot":"","sources":["../../src/components/moni-select-option.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBACa,gBAAiB,SAAQ,WAAW;IACnB,KAAK,SAAM;IACX,KAAK,SAAM;IACX,KAAK,SAAM;IACI,QAAQ,UAAS;IACjB,QAAQ,UAAS;IAE7D,OAAgB,MAAM,4BA4CpB;IAEF;;;;;;;OAOG;IACM,MAAM;CAQf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,oBAAoB,EAAE,gBAAgB,CAAC;KACvC;CACD;AAED,eAAe,gBAAgB,CAAC"}

package/dist/components/moni-select-option.js

@@ -14,42 +14,41 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material Design 3 Select Option component.
+ * Componente Material Design 3 Select Option (Opción de Selección).
  *
- * An individual selectable item designed to be placed inside a
- * `<moni-select>` dropdown.
+ * Un elemento individual seleccionable diseñado para colocarse dentro de un
+ * menú desplegable `<moni-select>`.
  *
- * **Interaction and layout:**
- * Options are rendered as accessible `<li>` elements styled identically to
- * `<moni-menu-item>`. When slotted into a `<moni-select>`, the parent
- * component extracts their `value`, `label`, and `group` attributes to build
- * its internal data model and handles the actual selection logic, keyboard
- * navigation, and rendering within the dropdown popup.
+ * **Interacción y diseño (layout):**
+ * Las opciones se renderizan como elementos `<li>` accesibles estilizados de forma idéntica a
+ * `<moni-menu-item>`. Cuando se insertan en un `<moni-select>`, el componente
+ * padre extrae sus atributos `value`, `label` y `group` para construir
+ * su modelo de datos interno y maneja la lógica de selección real, la navegación
+ * por teclado y el renderizado dentro del popup desplegable.
  *
- * **Grouping:**
- * Options can be categorized into subcategories by providing a `group`
- * attribute. The parent `<moni-select>` uses this to automatically generate
- * group headers (`<moni-select-group>`) in the dropdown list.
+ * **Agrupación:**
+ * Las opciones se pueden clasificar en subcategorías proporcionando un atributo
+ * `group`. El `<moni-select>` padre usa esto para generar automáticamente
+ * encabezados de grupo (`<moni-select-group>`) en la lista desplegable.
  *
  * @example
  * ```html
- * <moni-select label="Favorite framework">
- *   <!-- Standard option -->
+ * <moni-select label="Framework favorito">
+ *   <!-- Opción estándar -->
  *   <moni-select-option value="lit">Lit Element</moni-select-option>
  *
- *   <!-- Disabled option -->
- *   <moni-select-option value="react" disabled>React (not allowed)</moni-select-option>
+ *   <!-- Opción deshabilitada -->
+ *   <moni-select-option value="react" disabled>React (no permitido)</moni-select-option>
  *
- *   <!-- Grouped option -->
- *   <moni-select-option value="vue" group="Other">Vue.js</moni-select-option>
+ *   <!-- Opción agrupada -->
+ *   <moni-select-option value="vue" group="Otros">Vue.js</moni-select-option>
  * </moni-select>
  * ```
  *
- * @slot default - The text label for the option. If the `label` attribute is
- *                omitted, the parent `<moni-select>` will read this slot's
- *                `textContent`.
+ * @slot default - La etiqueta de texto para la opción. Si se omite el atributo `label`,
+ *                 el `<moni-select>` padre leerá el `textContent` de esta ranura (slot).
  *
- * @csspart item - The outer `<li>` element.
+ * @csspart item - El elemento `<li>` exterior.
  */
 let MoniSelectOption = class MoniSelectOption extends MoniElement {
     constructor() {
@@ -105,6 +104,14 @@ let MoniSelectOption = class MoniSelectOption extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Renderiza la fila de la opción como un elemento de lista accesible con `role="option"`.
+     *
+     * `aria-selected=${this.selected}` permite a los lectores de pantalla anunciar el estado
+     * de selección actual cuando el usuario navega por el cuadro de lista con las teclas de flecha.
+     * Cuando `selected=true`, se renderiza un icono de marca de verificación principal (leading checkmark) a través de `<moni-icon name="check">`
+     * en lugar del slot del icono principal, según la especificación de opciones de Select de M3.
+     */
     render() {
         return html `<li
 			part="option"

package/dist/components/moni-select.d.ts

@@ -9,79 +9,173 @@ import './moni-icon.js';
 import './moni-progress.js';
 import './moni-select-option.js';
 /**
- * Material Design 3 Select (Dropdown) component.
+ * Componente Material Design 3 Select (Menú Desplegable).
  *
- * A fully-featured custom select dropdown with searchability, option groups,
- * keyboard navigation, animation, and optional mobile drawer/sheet mode.
- * Replaces the native `<select>` element with a fully styled, accessible
- * M3-compliant alternative.
+ * Un menú desplegable select personalizado completo con capacidad de búsqueda, grupos de opciones,
+ * navegación por teclado, animación y un modo de cajón/hoja (drawer/sheet) móvil opcional.
+ * Reemplaza el elemento nativo `<select>` con una alternativa completamente estilizada y accesible
+ * que cumple con M3.
  *
- * **M3 spec reference:** `m3-docs/components/menus/specs.md` (dropdown menus)
+ * **Referencia a la especificación M3:** `m3-docs/components/menus/specs.md` (menús desplegables)
  *
- * **Feature summary:**
- * - Filled and outlined variants matching the M3 text field styles.
- * - Floating label with the standard field-styles floating label animation.
- * - Searchable mode: `searchable` attribute adds an inline filter input.
- * - Option groups: slot `<moni-select-group>` elements for hierarchical options.
- * - Mobile drawer: `drawer` attribute opens options in a `<moni-bottom-sheet>`
- *   instead of a dropdown popup, ideal for touch UIs.
- * - Keyboard navigation: Arrow keys, Enter, Escape, and Tab per ARIA combobox.
- * - Loading state: `loading` shows an indeterminate circular progress.
- * - Multi-value support: `multiple` enables multiple selection.
+ * **Resumen de características:**
+ * - Variantes Filled y Outlined que coinciden con los estilos de campo de texto de M3.
+ * - Etiqueta flotante (floating label) con la animación estándar de etiqueta flotante de estilos de campo.
+ * - Modo de búsqueda: el atributo `searchable` agrega un campo de entrada de filtro en línea.
+ * - Grupos de opciones: elementos `<moni-select-group>` en el slot para opciones jerárquicas.
+ * - Cajón móvil: el atributo `drawer` abre las opciones en un `<moni-bottom-sheet>`
+ *   en lugar de un popup desplegable, ideal para interfaces táctiles (touch UIs).
+ * - Navegación por teclado: Teclas de flecha, Enter, Escape y Tab según combobox de ARIA.
+ * - Estado de carga: `loading` muestra un progreso circular indeterminado.
+ * - Soporte multi-valor: `multiple` permite selección múltiple.
  *
- * **Option sources:**
- * Options can be provided in two ways:
- * 1. **Slotted `<moni-select-option>` elements** (default, recommended for SSR).
- * 2. **`options` property** — a `DropdownNode[]` array for fully programmatic control.
+ * **Fuentes de opciones:**
+ * Las opciones se pueden proporcionar de dos maneras:
+ * 1. **Elementos `<moni-select-option>` en la ranura (slot)** (por defecto, recomendado para SSR).
+ * 2. **Propiedad `options`** — un array de `DropdownNode[]` para un control completamente programático.
  *
- * **Value binding:**
- * The `value` property holds the currently selected option's value string.
- * For multiple selection, `values` holds `string[]`. On change, a composed
- * `'change'` event is fired.
+ * **Vinculación de valores (Value binding):**
+ * La propiedad `value` contiene la cadena de valor de la opción actualmente seleccionada.
+ * Para selección múltiple, `values` contiene `string[]`. Al cambiar, se dispara un
+ * evento compuesto `'moni-change'`.
  *
- * @fires change - Bubbles and is composed. Fired when the selected value changes.
- *                 Read `element.value` (or `element.values` for `multiple`).
+ * @fires moni-change - Burbujea y está compuesto. Se dispara cuando el valor seleccionado cambia.
+ *                      Lee `element.value` (o `element.values` para `multiple`).
  *
  * @example
  * ```html
- * <moni-select label="Country" name="country" variant="outlined">
- *   <moni-select-option value="us">United States</moni-select-option>
- *   <moni-select-option value="gb">United Kingdom</moni-select-option>
- *   <moni-select-option value="de">Germany</moni-select-option>
+ * <moni-select label="País" name="country" variant="outlined">
+ *   <moni-select-option value="us">Estados Unidos</moni-select-option>
+ *   <moni-select-option value="gb">Reino Unido</moni-select-option>
+ *   <moni-select-option value="de">Alemania</moni-select-option>
  * </moni-select>
  *
- * <!-- Searchable select -->
- * <moni-select label="Language" searchable>
+ * <!-- Select con búsqueda -->
+ * <moni-select label="Idioma" searchable>
  *   <moni-select-option value="ts">TypeScript</moni-select-option>
  *   <moni-select-option value="py">Python</moni-select-option>
  * </moni-select>
  * ```
  *
- * @slot default - `<moni-select-option>` or `<moni-select-group>` children.
+ * @slot default - Hijos `<moni-select-option>` o `<moni-select-group>`.
  *
- * @csspart field    - The outer `.field` div container.
- * @csspart dropdown - The floating option list container.
+ * @csspart field    - El contenedor div exterior `.field`.
+ * @csspart dropdown - El contenedor flotante de la lista de opciones.
  */
 export declare class MoniSelect extends MoniElement {
+    static formAssociated: boolean;
+    private _internals;
+    constructor();
+    /**
+     * Nombre del campo select, usado para el envío del formulario.
+     * @type {string}
+     */
     name: string;
+    /**
+     * Texto de la etiqueta flotante.
+     * @type {string}
+     */
     label: string;
+    /**
+     * Variante visual del campo select.
+     * @type {'filled' | 'outlined'}
+     * @default 'filled'
+     */
     variant: 'filled' | 'outlined';
+    /**
+     * Define las dimensiones del campo select.
+     * @type {'small' | 'medium' | 'large' | 'extra'}
+     * @default 'medium'
+     */
     size: 'small' | 'medium' | 'large' | 'extra';
+    /**
+     * Forma (radio de borde) del campo.
+     * @type {'round' | 'square' | 'no-round'}
+     * @default 'no-round'
+     */
     shape: 'round' | 'square' | 'no-round';
+    /**
+     * Deshabilita el campo select.
+     * @type {boolean}
+     */
     disabled: boolean;
+    /**
+     * Si es verdadero, muestra un indicador de carga (progreso lineal).
+     * @type {boolean}
+     */
     loading: boolean;
+    /**
+     * Texto de ayuda mostrado debajo del campo.
+     * @type {string}
+     */
     helper: string;
+    /**
+     * Texto de error mostrado debajo del campo cuando `error` es true.
+     * Reemplaza al texto de ayuda.
+     * @type {string}
+     */
     errorText: string;
+    /**
+     * Si es verdadero, establece el campo en un estado de error.
+     * @type {boolean}
+     */
     error: boolean;
+    /**
+     * El valor actual del select.
+     * @type {string}
+     */
     value: string;
+    /**
+     * Nombre del icono principal (leading icon, Material Symbols).
+     * @type {string}
+     */
     icon: string;
+    /**
+     * Nombre del icono final (trailing icon, Material Symbols) que indica el estado del menú desplegable.
+     * @type {string}
+     * @default 'arrow_drop_down'
+     */
     trailingIcon: string;
+    /**
+     * Habilita un campo de búsqueda en la parte superior del menú desplegable para filtrar opciones.
+     * @type {boolean}
+     */
     searchable: boolean;
+    /**
+     * Muestra un botón de limpieza cuando se selecciona un valor para restablecer fácilmente el campo.
+     * @type {boolean}
+     */
     clearable: boolean;
+    /**
+     * Renderiza las opciones como una hoja inferior (bottom sheet, ideal para dispositivos móviles) en lugar de un menú desplegable.
+     * @type {boolean}
+     */
     sheet: boolean;
+    /**
+     * Texto de marcador de posición (placeholder) mostrado cuando no hay ningún valor seleccionado.
+     * @type {string}
+     */
     placeholder: string;
+    /**
+     * Estrategia de posicionamiento para el menú desplegable.
+     * @type {'absolute' | 'fixed'}
+     * @default 'absolute'
+     */
     positioning: 'absolute' | 'fixed';
+    /**
+     * Ubicación preferida del menú desplegable con respecto al disparador (trigger).
+     * @type {'top' | 'bottom' | 'left' | 'right' | 'auto'}
+     * @default 'auto'
+     */
     placement: 'top' | 'bottom' | 'left' | 'right' | 'auto';
+    /**
+     * Restricción de ancho del menú desplegable.
+     * - `'trigger'`: Coincide con el ancho del campo de entrada.
+     * - `'auto'`: Coincide con el ancho del contenido del menú desplegable.
+     * - O cualquier valor CSS de ancho válido (ej. '200px').
+     * @type {string}
+     * @default 'trigger'
+     */
     dropdownWidth: string;
     private _open;
     private _searchQuery;
@@ -94,34 +188,205 @@ export declare class MoniSelect extends MoniElement {
     private _slot;
     private _input;
     static styles: import("lit").CSSResult[];
+    /**
+     * Hook del ciclo de vida (Lit).
+     * Vincula event listeners globales necesarios para la lógica del dropdown.
+     * Se usa `capture: true` en el evento de scroll para poder reaccionar
+     * al desplazamiento de cualquier contenedor padre y reposicionar el menú a tiempo.
+     */
     connectedCallback(): void;
+    /**
+     * Hook del ciclo de vida (Lit).
+     * Desmonta rigurosamente todos los listeners globales para prevenir memory leaks
+     * o llamadas accidentales cuando el select ya fue destruido del DOM.
+     */
     disconnectedCallback(): void;
+    /**
+     * Hook de actualización reactiva (Lit).
+     * Verifica si alguna propiedad relacionada con el tamaño del contenido (como la búsqueda,
+     * la ruta de anidación o el estado abierto) ha cambiado, para forzar un recálculo
+     * de la altura animada del contenedor `drilldown-wrapper`.
+     */
     updated(changedProperties: Map<string | number | symbol, unknown>): void;
+    /**
+     * Lógica de animación de altura (Height Animation).
+     * Cuando se navega entre categorías anidadas (`_drilldownPath`), las listas hijas pueden
+     * tener diferentes tamaños. Este método lee el `scrollHeight` del panel activo y lo aplica
+     * imperativamente al `wrapper` para disparar una transición CSS suave en la altura del dropdown.
+     */
     private _updateWrapperHeight;
+    /**
+     * Cierra el Dropdown cuando el usuario hace clic fuera de las dimensiones del componente.
+     * Utiliza `e.composedPath()` para poder atravesar barreras de Shadow DOM si el select
+     * está dentro de un contenedor web-component externo.
+     */
     private _handleOutsideClick;
+    /**
+     * Motor de Cálculo de Colisiones de la Interfaz (Collision Detection).
+     *
+     * @logic
+     * 1. Calcula las coordenadas espaciales (`getBoundingClientRect`) del select base.
+     * 2. Compara el espacio disponible (`spaceAbove`, `spaceBelow`, `spaceRight`, `spaceLeft`)
+     *    respecto al viewport (`window.innerHeight`, `window.innerWidth`).
+     * 3. Si el dropdown no cabe en la posición preferida (`placement`), revierte lógicamente
+     *    la posición (ej: si `bottom` desborda, lo abre hacia `top`).
+     * 4. Actualiza `_actualPlacement` con la dirección segura calculada.
+     */
     private _determineActualPlacement;
+    /**
+     * Handler de Scroll global.
+     * Fuerza un recálculo de la posición y dimensiones del dropdown si el usuario
+     * hace scroll en la página mientras el select permanece abierto.
+     */
     private _handleScroll;
+    /**
+     * Handler de Resize global.
+     * Asegura que el popover del select no quede fuera del viewport cuando
+     * se cambia el tamaño de la ventana o se rota la pantalla en dispositivos móviles.
+     */
     private _handleResize;
+    /**
+     * Aplica las coordenadas y dimensiones absolutas o fijas al menú desplegable.
+     * Este método es fundamental cuando `positioning === 'fixed'`, ya que el dropdown
+     * se saca del flujo normal del documento para evitar `overflow: hidden` de los padres.
+     * Mapea el `width` para coincidir opcionalmente con el gatillo (`dropdownWidth="trigger"`).
+     */
     private _updateMenuPosition;
+    /**
+     * Devuelve un string de estilos inline para el menú desplegable.
+     * Si la posición es `fixed` (calculada dinámicamente para evadir overflow),
+     * retorna el bloque de coordenadas generado por `_updateMenuPosition`.
+     * Si no, asigna anchos basados en la propiedad `dropdownWidth` (auto, trigger, custom).
+     */
     private _getMenuStyle;
+    /**
+     * Parseador del Shadow DOM (Slot Change Handler).
+     *
+     * @logic
+     * 1. Cuando los hijos proyectados cambian (ej. se agregan nuevos `<option>`),
+     *    lee iterativamente todos los nodos del Light DOM.
+     * 2. Si encuentra `<optgroup>` o `<moni-select-option group="A/B">`, construye dinámicamente
+     *    un árbol estructural de `GroupNode` anidados.
+     * 3. Si encuentra opciones, las inyecta en el grupo correspondiente del árbol.
+     * 4. Almacena el árbol resultante en `_parsedOptions` para que el componente
+     *    pueda renderizar sus propios submenús nativos independientemente del markup inicial.
+     */
     private _onSlotChange;
+    /**
+     * Alterna el estado de apertura/cierre del dropdown, previniendo
+     * la acción si el componente está deshabilitado.
+     */
     private _toggleDropdown;
+    /**
+     * Manejador de clics en el campo de texto (Trigger).
+     * Si el componente es `searchable` (permite escribir para buscar), un clic
+     * sólo abrirá el menú (no lo cerrará si ya estaba abierto, para permitir al usuario seguir escribiendo).
+     */
     private _onInputClick;
+    /**
+     * Despliega el menú del select y coordina la accesibilidad, posicionamiento y foco inicial.
+     */
     private _openDropdown;
+    /**
+     * Cierra el dropdown y purga la consulta de búsqueda (`_searchQuery`)
+     * para que la próxima vez que se abra, la lista muestre todas las opciones por defecto.
+     */
     private _closeDropdown;
     private _findOptionByValue;
+    /**
+     * Evento de input (tecleo) en la barra de búsqueda.
+     *
+     * @logic
+     * 1. Actualiza `_searchQuery` y fuerza la apertura del dropdown.
+     * 2. Si es `clearable` y el usuario borró todo, emite eventos vacíos.
+     * 3. Busca coincidencias exactas en el texto. Si el usuario teclea exactamente el
+     *    label de una opción existente, la selecciona automáticamente (auto-completado nativo).
+     */
     private _onSearchInput;
+    /**
+     * Confirma la selección de una opción específica.
+     * Actualiza el valor (estado reactivo), cierra el dropdown y despacha los eventos
+     * estándar HTML `input` y `change` para integrarse fluidamente con formularios nativos o frameworks.
+     */
     private _selectOption;
+    /**
+     * Maneja el Hover sobre categorías en modo Desktop (Submenús emergentes).
+     * Detecta dinámicamente si el submenú se saldrá del lado derecho de la pantalla.
+     * Si es así, altera las clases de CSS (`open-left` vs `open-right`) para que
+     * el menú flote en la dirección opuesta, evitando desbordamientos de viewport (Overflow prevention).
+     */
     private _onSubmenuMouseEnter;
+    /**
+     * Gestiona la navegación completa por teclado siguiendo el patrón WAI-ARIA Combobox.
+     * Soporta flechas direccionales, selección (Enter), y cierre (Escape).
+     */
     private _onKeyDown;
+    /**
+     * Asegura que el elemento resaltado por teclado sea visible dentro del contenedor scrolleable.
+     */
     private _scrollToActive;
+    /**
+     * Aplana el árbol jerárquico recursivo de <moni-select-group> a un array unidimensional de opciones puras.
+     * Esencial para que la búsqueda por texto funcione globalmente ignorando las categorías.
+     */
     private _getFlatOptions;
     private _getFilteredOptions;
     private _getVisibleOptions;
+    /**
+     * Motor de Renderizado: Lista Raíz (Modo Móvil / Drilldown).
+     *
+     * Renderiza las opciones iniciales y los grupos base de la categoría actual (`_drilldownPath`).
+     * Asigna clases dinámicas (`selected`, `active-nav`) para la retroalimentación visual
+     * del teclado y el valor actualmente seleccionado.
+     */
     private _renderRootList;
+    /**
+     * Motor de Renderizado: Subcategorías (Modo Móvil / Drilldown).
+     *
+     * A diferencia de desktop (donde los submenús flotan a los lados), en dispositivos
+     * móviles o espacios constreñidos, el menú transiciona in-situ. Este método renderiza
+     * el header del grupo activo, un botón de "Regresar" (Arrow Back) y las opciones hijas.
+     */
     private _renderSubcategoryList;
     private _renderDesktopNode;
+    /**
+     * Orquestador principal de renderizado de la lista de opciones.
+     *
+     * Si el usuario introdujo texto (`_searchQuery`), renderiza los resultados filtrados.
+     * Si la lista original está vacía, muestra un mensaje amigable (Empty State).
+     * Determina condicionalmente si usar el modo plano/Drilldown (Móviles) o
+     * el modo Desktop con submenús flotantes (`_renderDesktopNode`).
+     */
     private _renderOptionsList;
+    /**
+     * Ensambla el Shadow DOM del campo select, coordinando dos modos de interfaz de usuario distintos.
+     *
+     * **Resolución del valor a mostrar (Display value):**
+     * El contenido de texto visible en el input está determinado por prioridad:
+     * 1. Mientras el menú desplegable está abierto Y `searchable=true` Y NO es modo sheet:
+     *    muestra `_searchQuery` (el texto del filtro en vivo que el usuario está escribiendo).
+     * 2. De lo contrario: muestra `selectedOpt.label` (la etiqueta de la opción actualmente
+     *    seleccionada) o vuelve a la cadena vacía.
+     *
+     * **Dos rutas de renderizado:**
+     * - **Modo Sheet (`sheet=true`):** Renderiza un `<moni-bottom-sheet>` como un
+     *   cajón (drawer) superpuesto a pantalla completa, ideal para IU táctiles móviles. La lista de opciones
+     *   se renderiza dentro de la hoja en lugar del menú desplegable.
+     * - **Modo desplegable (por defecto):** Renderiza un `.dropdown-menu` flotante que
+     *   se abre debajo o arriba del campo. La cadena `_menuStyle` (calculada por
+     *   `_computeMenuStyle()`) inyecta los `top`, `left`, `width`, y
+     *   sobreescrituras `position: fixed` correctas para contenedores con scroll (scroll-contained) y parents con overflow cortado (overflow-clipping).
+     *
+     * **Patrón combobox ARIA:**
+     * El input de texto lleva `role="combobox"`, `aria-haspopup="listbox"` y
+     * `aria-expanded` para satisfacer los requisitos del combobox WCAG 2.1 para lectores de pantalla.
+     * `aria-activedescendant` se establece al ID de la opción actualmente enfocada por teclado
+     * para habilitar el movimiento del cursor virtual sin gestión del foco.
+     *
+     * **Composición de `fieldClasses`:**
+     * Sigue la convención de nomenclatura de clases de estilos de campo de BeerCSS. `prefix` se agrega
+     * cuando `icon` está establecido (para desplazar el relleno -padding- inline-start del input de texto para el icono).
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-select.d.ts","sourceRoot":"","sources":["../../src/components/moni-select.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAE,WAAW,EAA6B,MAAM,kBAAkB,CAAC;AAC1E,OAAO,gBAAgB,CAAC;AACxB,OAAO,oBAAoB,CAAC;AAC5B,OAAO,yBAAyB,CAAC;AAuCjC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBACa,UAAW,SAAQ,WAAW;IACb,IAAI,SAAM;IACV,KAAK,SAAM;IACX,OAAO,EAAE,QAAQ,GAAG,UAAU,CAAY;IAEvE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,CAAY;IAExD,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAc;IACR,QAAQ,UAAS;IACjB,OAAO,UAAS;IAC/B,MAAM,SAAM;IACa,SAAS,SAAM;IACzB,KAAK,UAAS;IAC7B,KAAK,SAAM;IACX,IAAI,SAAM;IACkB,YAAY,SAClD;IACyB,UAAU,UAAS;IACnB,SAAS,UAAS;IAClB,KAAK,UAAS;IAC7B,WAAW,SAAM;IACjB,WAAW,EAAE,UAAU,GAAG,OAAO,CAAc;IAC/C,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAU;IACpC,aAAa,SAAa;IAE3E,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,gBAAgB,CAAiD;IACzE,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,YAAY,CAAM;IAC1B,OAAO,CAAC,UAAU,CAAM;IACxB,OAAO,CAAC,oBAAoB,CAAS;IACrC,OAAO,CAAC,cAAc,CAAmB;IAEnC,OAAO,CAAC,KAAK,CAAmB;IAC/B,OAAO,CAAC,MAAM,CAAoB;IAElD,OAAgB,MAAM,4BAmUpB;IAEO,iBAAiB;IAOjB,oBAAoB;IAOpB,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAa1E,OAAO,CAAC,oBAAoB;IAoB5B,OAAO,CAAC,mBAAmB,CAIzB;IAEF,OAAO,CAAC,yBAAyB;IAgDjC,OAAO,CAAC,aAAa,CAKnB;IAEF,OAAO,CAAC,aAAa,CAKnB;IAEF,OAAO,CAAC,mBAAmB;IAwD3B,OAAO,CAAC,aAAa;IAarB,OAAO,CAAC,aAAa;IAqDrB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,aAAa;IAWrB,OAAO,CAAC,aAAa;IAkCrB,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,cAAc;IAsBtB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,oBAAoB;IAmB5B,OAAO,CAAC,UAAU;IAkClB,OAAO,CAAC,eAAe;IASvB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,mBAAmB;IAS3B,OAAO,CAAC,kBAAkB;IAe1B,OAAO,CAAC,eAAe;IA0BvB,OAAO,CAAC,sBAAsB;IAoC9B,OAAO,CAAC,kBAAkB;IA+B1B,OAAO,CAAC,kBAAkB;IAsDjB,MAAM;CA6Hf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"moni-select.d.ts","sourceRoot":"","sources":["../../src/components/moni-select.ts"],"names":[],"mappings":"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"}