@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-context-menu.d.ts

@@ -7,47 +7,47 @@
 import { MoniElement } from './_base/index.js';
 import './moni-menu.js';
 /**
- * Material Design 3 Context Menu component.
+ * Componente Material Design 3 Context Menu (Menú Contextual).
  *
- * A specialized menu that opens at the exact coordinates of a pointer event,
- * typically triggered by a right-click (`contextmenu` event). It provides
- * contextual actions related to the specific item clicked.
+ * Un menú especializado que se abre en las coordenadas exactas de un evento de puntero,
+ * típicamente desencadenado por un clic derecho (evento `contextmenu`). Proporciona
+ * acciones contextuales relacionadas con el elemento específico clicado.
  *
- * **M3 spec reference:** `m3-docs/components/menus/specs.md` (Contextual menus)
+ * **Referencia de la especificación M3:** `m3-docs/components/menus/specs.md` (Menús contextuales)
  *
- * **Triggering mechanism:**
- * The component does not require programmatic triggering via an `open` property.
- * Instead, it attaches a `contextmenu` event listener to its parent element
- * during `connectedCallback`. When the parent is right-clicked, the menu
- * captures the `clientX`/`clientY` coordinates, prevents the default browser
- * context menu, and opens itself at the cursor position using `position: fixed`.
+ * **Mecanismo de activación:**
+ * El componente no requiere activación programática a través de una propiedad `open`.
+ * En su lugar, adjunta un detector de eventos `contextmenu` a su elemento padre
+ * durante `connectedCallback`. Cuando se hace clic derecho en el padre, el menú
+ * captura las coordenadas `clientX`/`clientY`, previene el menú contextual predeterminado
+ * del navegador, y se abre en la posición del cursor usando `position: fixed`.
  *
- * **Auto-flip behavior (`flip` attribute):**
- * Per the M3 guidelines, menus should flip to the opposite side of the cursor
- * if opening in the requested `placement` would cause them to overflow the
- * viewport. When `flip=true`, the component dynamically calculates viewport
- * bounds before opening and overrides `placement` if necessary (e.g., flipping
- * from `bottom` to `top` if clicked near the bottom of the screen).
+ * **Comportamiento de auto-inversión (atributo `flip`):**
+ * Según las pautas de M3, los menús deben invertirse al lado opuesto del cursor
+ * si al abrirse en la `placement` solicitada causarían un desbordamiento de la
+ * ventana gráfica. Cuando `flip=true`, el componente calcula dinámicamente los límites
+ * de la ventana antes de abrir y anula `placement` si es necesario (ej., invirtiendo
+ * de `bottom` a `top` si se hace clic cerca de la parte inferior de la pantalla).
  *
- * **Auto-dismiss:**
- * Closes automatically when clicking anywhere outside the menu, or when
- * pressing the `Escape` key.
+ * **Auto-descarte:**
+ * Se cierra automáticamente al hacer clic en cualquier lugar fuera del menú, o al
+ * presionar la tecla `Escape`.
  *
  * @example
  * ```html
- * <!-- Wrap the trigger area and the menu in a container -->
+ * <!-- Envuelve el área de activación y el menú en un contenedor -->
  * <div>
- *   <p>Right-click me for options</p>
+ *   <p>Haz clic derecho para ver las opciones</p>
  *   <moni-context-menu flip>
- *     <moni-menu-item>Copy</moni-menu-item>
- *     <moni-menu-item>Paste</moni-menu-item>
+ *     <moni-menu-item>Copiar</moni-menu-item>
+ *     <moni-menu-item>Pegar</moni-menu-item>
  *     <moni-divider></moni-divider>
- *     <moni-menu-item>Delete</moni-menu-item>
+ *     <moni-menu-item>Eliminar</moni-menu-item>
  *   </moni-context-menu>
  * </div>
  * ```
  *
- * @slot default - The `<moni-menu-item>` elements that make up the menu.
+ * @slot default - Los elementos `<moni-menu-item>` que componen el menú.
  */
 export declare class MoniContextMenu extends MoniElement {
     placement: 'bottom' | 'top' | 'left' | 'right';
@@ -58,14 +58,60 @@ export declare class MoniContextMenu extends MoniElement {
     private _resolvedPlacement;
     private _menuEl?;
     private _target;
+    /**
+     * Wrapper estático para el manejador de teclado global.
+     * Conserva la referencia exacta para desregistrar el evento en `disconnectedCallback`.
+     */
     private _docKeydown;
+    /**
+     * Hook de inicialización (Lit).
+     * Atrapa al elemento padre directo y le inyecta `position: relative` (si era static)
+     * para que las coordenadas de despliegue del menú floten correctamente.
+     * Adjunta los eventos nativos de `contextmenu` (clic derecho) al contenedor.
+     */
     connectedCallback(): void;
+    /**
+     * Hook de destrucción (Lit).
+     * Limpia los detectores de clic derecho y atajos de teclado para eludir memory leaks
+     * al desmontarse del DOM.
+     */
     disconnectedCallback(): void;
+    /**
+     * Intercepta el clic derecho (`contextmenu`) del navegador de forma nativa.
+     * Previene el menú por defecto del SO y captura las coordenadas X/Y del ratón
+     * relativas al elemento anfitrión para ubicar milimétricamente el popup personalizado.
+     */
     private _onContextMenu;
+    /**
+     * Sistema de Colisión/Desbordamiento de Ventana.
+     * Si la directiva `flip` está habilitada, examina los límites (BoundingClientRect)
+     * del menú tras su renderizado y altera su `placement` sobre la marcha si éste
+     * colisiona con el borde del Viewport, invirtiendo top/bottom o left/right.
+     */
     private _maybeFlip;
+    /**
+     * Cierra instintivamente el menú contextual si el usuario hace clic en
+     * cualquier zona exterior al mismo.
+     */
     private _onDocumentClick;
+    /**
+     * Escucha la tecla Escape a nivel documento para cerrar el menú si se
+     * encuentra desplegado, cumpliendo con los estándares de accesibilidad (WAI-ARIA).
+     */
     private _onDocKeydown;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderiza el menú contextual como una superposición de Popover API posicionada en las coordenadas del puntero.
+     *
+     * El `<div>` del menú usa `popover="manual"` para que aparezca en la capa superior
+     * por encima de todo el otro contenido. Sus `top` y `left` se establecen mediante propiedades personalizadas CSS
+     * `--_x` / `--_y` (inyectadas como estilo en línea) que se calculan
+     * a partir de `clientX` / `clientY` del evento `contextmenu`.
+     *
+     * El `@click` en el fondo (fuera de los límites del menú) llama a `hidePopover()`
+     * para descartar ligeramente el menú contextual. Los elementos dentro del menú deben llamar a
+     * `event.stopPropagation()` para evitar el cierre accidental al hacer clic en un elemento.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-context-menu.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-context-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-context-menu.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,SAAS,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAY;IACd,IAAI,UAAS;IAEhD,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,kBAAkB,CAAiD;IAEhE,OAAO,CAAC,OAAO,CAAC,CAAc;IAElD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,WAAW,CAA+C;IAEzD,iBAAiB;IAejB,oBAAoB;IAS7B,OAAO,CAAC,cAAc,CAcpB;IAEF,OAAO,CAAC,UAAU;IAoBlB,OAAO,CAAC,gBAAgB,CAItB;IAEF,OAAO,CAAC,aAAa,CAInB;IAEF,OAAgB,MAAM,4BAgBpB;IAEO,MAAM;CAmBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}
+{"version":3,"file":"moni-context-menu.d.ts","sourceRoot":"","sources":["../../src/components/moni-context-menu.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,eAAgB,SAAQ,WAAW;IAE/C,SAAS,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,CAAY;IACd,IAAI,UAAS;IAEhD,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,EAAE,CAAK;IACf,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,kBAAkB,CAAiD;IAEhE,OAAO,CAAC,OAAO,CAAC,CAAc;IAElD,OAAO,CAAC,OAAO,CAA4B;IAC3C;;;OAGG;IACH,OAAO,CAAC,WAAW,CAA+C;IAElE;;;;;OAKG;IACM,iBAAiB;IAe1B;;;;OAIG;IACM,oBAAoB;IAS7B;;;;OAIG;IACH,OAAO,CAAC,cAAc,CAcpB;IAEF;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAoBlB;;;OAGG;IACH,OAAO,CAAC,gBAAgB,CAItB;IAEF;;;OAGG;IACH,OAAO,CAAC,aAAa,CAInB;IAEF,OAAgB,MAAM,4BAgBpB;IAEF;;;;;;;;;;;OAWG;IACM,MAAM;CAmBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,mBAAmB,EAAE,eAAe,CAAC;KACrC;CACD;AAED,eAAe,eAAe,CAAC"}

package/dist/components/moni-context-menu.js

@@ -15,47 +15,47 @@ import { customElement, property, state, query } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-menu.js';
 /**
- * Material Design 3 Context Menu component.
+ * Componente Material Design 3 Context Menu (Menú Contextual).
  *
- * A specialized menu that opens at the exact coordinates of a pointer event,
- * typically triggered by a right-click (`contextmenu` event). It provides
- * contextual actions related to the specific item clicked.
+ * Un menú especializado que se abre en las coordenadas exactas de un evento de puntero,
+ * típicamente desencadenado por un clic derecho (evento `contextmenu`). Proporciona
+ * acciones contextuales relacionadas con el elemento específico clicado.
  *
- * **M3 spec reference:** `m3-docs/components/menus/specs.md` (Contextual menus)
+ * **Referencia de la especificación M3:** `m3-docs/components/menus/specs.md` (Menús contextuales)
  *
- * **Triggering mechanism:**
- * The component does not require programmatic triggering via an `open` property.
- * Instead, it attaches a `contextmenu` event listener to its parent element
- * during `connectedCallback`. When the parent is right-clicked, the menu
- * captures the `clientX`/`clientY` coordinates, prevents the default browser
- * context menu, and opens itself at the cursor position using `position: fixed`.
+ * **Mecanismo de activación:**
+ * El componente no requiere activación programática a través de una propiedad `open`.
+ * En su lugar, adjunta un detector de eventos `contextmenu` a su elemento padre
+ * durante `connectedCallback`. Cuando se hace clic derecho en el padre, el menú
+ * captura las coordenadas `clientX`/`clientY`, previene el menú contextual predeterminado
+ * del navegador, y se abre en la posición del cursor usando `position: fixed`.
  *
- * **Auto-flip behavior (`flip` attribute):**
- * Per the M3 guidelines, menus should flip to the opposite side of the cursor
- * if opening in the requested `placement` would cause them to overflow the
- * viewport. When `flip=true`, the component dynamically calculates viewport
- * bounds before opening and overrides `placement` if necessary (e.g., flipping
- * from `bottom` to `top` if clicked near the bottom of the screen).
+ * **Comportamiento de auto-inversión (atributo `flip`):**
+ * Según las pautas de M3, los menús deben invertirse al lado opuesto del cursor
+ * si al abrirse en la `placement` solicitada causarían un desbordamiento de la
+ * ventana gráfica. Cuando `flip=true`, el componente calcula dinámicamente los límites
+ * de la ventana antes de abrir y anula `placement` si es necesario (ej., invirtiendo
+ * de `bottom` a `top` si se hace clic cerca de la parte inferior de la pantalla).
  *
- * **Auto-dismiss:**
- * Closes automatically when clicking anywhere outside the menu, or when
- * pressing the `Escape` key.
+ * **Auto-descarte:**
+ * Se cierra automáticamente al hacer clic en cualquier lugar fuera del menú, o al
+ * presionar la tecla `Escape`.
  *
  * @example
  * ```html
- * <!-- Wrap the trigger area and the menu in a container -->
+ * <!-- Envuelve el área de activación y el menú en un contenedor -->
  * <div>
- *   <p>Right-click me for options</p>
+ *   <p>Haz clic derecho para ver las opciones</p>
  *   <moni-context-menu flip>
- *     <moni-menu-item>Copy</moni-menu-item>
- *     <moni-menu-item>Paste</moni-menu-item>
+ *     <moni-menu-item>Copiar</moni-menu-item>
+ *     <moni-menu-item>Pegar</moni-menu-item>
  *     <moni-divider></moni-divider>
- *     <moni-menu-item>Delete</moni-menu-item>
+ *     <moni-menu-item>Eliminar</moni-menu-item>
  *   </moni-context-menu>
  * </div>
  * ```
  *
- * @slot default - The `<moni-menu-item>` elements that make up the menu.
+ * @slot default - Los elementos `<moni-menu-item>` que componen el menú.
  */
 let MoniContextMenu = class MoniContextMenu extends MoniElement {
     constructor() {
@@ -67,7 +67,16 @@ let MoniContextMenu = class MoniContextMenu extends MoniElement {
         this._open = false;
         this._resolvedPlacement = 'bottom';
         this._target = null;
+        /**
+         * Wrapper estático para el manejador de teclado global.
+         * Conserva la referencia exacta para desregistrar el evento en `disconnectedCallback`.
+         */
         this._docKeydown = (e) => this._onDocKeydown(e);
+        /**
+         * Intercepta el clic derecho (`contextmenu`) del navegador de forma nativa.
+         * Previene el menú por defecto del SO y captura las coordenadas X/Y del ratón
+         * relativas al elemento anfitrión para ubicar milimétricamente el popup personalizado.
+         */
         this._onContextMenu = (e) => {
             e.preventDefault();
             if (this._target) {
@@ -81,20 +90,34 @@ let MoniContextMenu = class MoniContextMenu extends MoniElement {
             }
             this._resolvedPlacement = this.placement;
             this._open = true;
-            // After Lit renders the menu, check viewport fit and flip if needed.
+            // Después de que Lit renderice el menú, verificar el ajuste al viewport y voltear si es necesario.
             this.updateComplete.then(() => this._maybeFlip());
         };
+        /**
+         * Cierra instintivamente el menú contextual si el usuario hace clic en
+         * cualquier zona exterior al mismo.
+         */
         this._onDocumentClick = () => {
             if (this._open) {
                 this._open = false;
             }
         };
+        /**
+         * Escucha la tecla Escape a nivel documento para cerrar el menú si se
+         * encuentra desplegado, cumpliendo con los estándares de accesibilidad (WAI-ARIA).
+         */
         this._onDocKeydown = (e) => {
             if (e.key === 'Escape' && this._open) {
                 this._open = false;
             }
         };
     }
+    /**
+     * Hook de inicialización (Lit).
+     * Atrapa al elemento padre directo y le inyecta `position: relative` (si era static)
+     * para que las coordenadas de despliegue del menú floten correctamente.
+     * Adjunta los eventos nativos de `contextmenu` (clic derecho) al contenedor.
+     */
     connectedCallback() {
         super.connectedCallback();
         this._target = this.parentElement;
@@ -109,6 +132,11 @@ let MoniContextMenu = class MoniContextMenu extends MoniElement {
         document.addEventListener('click', this._onDocumentClick);
         document.addEventListener('keydown', this._docKeydown);
     }
+    /**
+     * Hook de destrucción (Lit).
+     * Limpia los detectores de clic derecho y atajos de teclado para eludir memory leaks
+     * al desmontarse del DOM.
+     */
     disconnectedCallback() {
         if (this._target) {
             this._target.removeEventListener('contextmenu', this._onContextMenu);
@@ -117,6 +145,12 @@ let MoniContextMenu = class MoniContextMenu extends MoniElement {
         document.removeEventListener('keydown', this._docKeydown);
         super.disconnectedCallback();
     }
+    /**
+     * Sistema de Colisión/Desbordamiento de Ventana.
+     * Si la directiva `flip` está habilitada, examina los límites (BoundingClientRect)
+     * del menú tras su renderizado y altera su `placement` sobre la marcha si éste
+     * colisiona con el borde del Viewport, invirtiendo top/bottom o left/right.
+     */
     _maybeFlip() {
         if (!this.flip)
             return;
@@ -158,10 +192,22 @@ let MoniContextMenu = class MoniContextMenu extends MoniElement {
 			}
 		`
     ]; }
+    /**
+     * Renderiza el menú contextual como una superposición de Popover API posicionada en las coordenadas del puntero.
+     *
+     * El `<div>` del menú usa `popover="manual"` para que aparezca en la capa superior
+     * por encima de todo el otro contenido. Sus `top` y `left` se establecen mediante propiedades personalizadas CSS
+     * `--_x` / `--_y` (inyectadas como estilo en línea) que se calculan
+     * a partir de `clientX` / `clientY` del evento `contextmenu`.
+     *
+     * El `@click` en el fondo (fuera de los límites del menú) llama a `hidePopover()`
+     * para descartar ligeramente el menú contextual. Los elementos dentro del menú deben llamar a
+     * `event.stopPropagation()` para evitar el cierre accidental al hacer clic en un elemento.
+     */
     render() {
-        // When the menu is open, prefer the resolved (possibly flipped)
-        // placement; otherwise just use the host's requested placement so
-        // the inner element reflects the attribute synchronously.
+        // Cuando el menú está abierto, preferir la ubicación resuelta (posiblemente volteada);
+        // de lo contrario, simplemente usar la ubicación solicitada por el host para que
+        // el elemento interno refleje el atributo sincrónicamente.
         const effectivePlacement = this._open
             ? this._resolvedPlacement
             : this.placement;

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

@@ -6,118 +6,143 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Material Design 3 Dialog component.
+ * Componente Material Design 3 Dialog (Diálogo).
  *
- * Dialogs inform users about a task and can contain critical information,
- * require decisions, or involve multiple tasks. They interrupt the user's
- * workflow and should be used sparingly.
+ * Los diálogos informan a los usuarios sobre una tarea y pueden contener información crítica,
+ * requerir decisiones o implicar múltiples tareas. Interrumpen el flujo de trabajo del
+ * usuario y deben usarse con moderación.
  *
- * **M3 spec reference:** `m3-docs/components/dialogs/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/dialogs/specs.md`
  *
- * **Implementation note — native `<dialog>` element:**
- * This component wraps the native `<dialog>` HTML element. Opening and closing
- * are controlled via the `open` attribute (and its JS property). The component
- * syncs `open` changes to the native `<dialog>` in `updated()`:
- * - `modal=true` → calls `dialog.showModal()` (blocks focus, adds backdrop).
- * - `modal=false` → calls `dialog.show()` (non-blocking, no backdrop).
- * - `open=false` → calls `dialog.close()`.
+ * **Nota de implementación — elemento nativo `<dialog>`:**
+ * Este componente envuelve el elemento HTML nativo `<dialog>`. La apertura y cierre
+ * se controlan mediante el atributo `open` (y su propiedad JS). El componente
+ * sincroniza los cambios de `open` al `<dialog>` nativo en `updated()`:
+ * - `modal=true` → llama a `dialog.showModal()` (bloquea el foco, añade fondo oscuro).
+ * - `modal=false` → llama a `dialog.show()` (no bloquea, sin fondo oscuro).
+ * - `open=false` → llama a `dialog.close()`.
  *
- * **Placement (`side` attribute):**
- * - `center` (default) — Centered in the viewport. Standard M3 dialog.
- * - `top`, `right`, `bottom`, `left` — Edge-anchored panels (side sheet pattern).
- * - `max` — Full-screen dialog for complex flows.
+ * **Colocación (atributo `side`):**
+ * - `center` (por defecto) — Centrado en la ventana gráfica. Diálogo M3 estándar.
+ * - `top`, `right`, `bottom`, `left` — Paneles anclados a los bordes (patrón side sheet).
+ * - `max` — Diálogo a pantalla completa para flujos complejos.
  *
  * @example
  * ```html
- * <!-- Basic modal dialog -->
- * <moni-dialog open modal title="Delete item?" size="small">
- *   <p>This action cannot be undone.</p>
+ * <!-- Diálogo modal básico -->
+ * <moni-dialog open modal title="Eliminar elemento?" size="small">
+ *   <p>Esta acción no se puede deshacer.</p>
  *   <div slot="footer">
- *     <moni-button variant="text">Cancel</moni-button>
- *     <moni-button>Delete</moni-button>
+ *     <moni-button variant="text">Cancelar</moni-button>
+ *     <moni-button>Eliminar</moni-button>
  *   </div>
  * </moni-dialog>
  * ```
  *
- * @slot default - The dialog body content.
- * @slot header  - Custom header content (overrides `title` attribute).
- * @slot footer  - Action buttons row at the bottom of the dialog.
+ * @slot default - El contenido del cuerpo del diálogo.
+ * @slot header  - Contenido personalizado del encabezado (sobrescribe el atributo `title`).
+ * @slot footer  - Fila de botones de acción en la parte inferior del diálogo.
  *
- * @csspart dialog - The native `<dialog>` element.
- * @csspart header - The header container.
- * @csspart body   - The body content wrapper.
- * @csspart footer - The footer actions wrapper.
+ * @csspart dialog - El elemento `<dialog>` nativo.
+ * @csspart header - El contenedor del encabezado.
+ * @csspart body   - El envoltorio del contenido del cuerpo.
+ * @csspart footer - El envoltorio de acciones del pie de página.
  */
 export declare class MoniDialog extends MoniElement {
     /**
-     * Controls the open/closed state of the dialog.
+     * Controla el estado abierto/cerrado del diálogo.
      *
-     * When set to `true`, the component calls `dialog.showModal()` (if `modal`)
-     * or `dialog.show()`. When set to `false`, calls `dialog.close()`.
-     * Reflected as an HTML attribute for CSS and external state readers.
+     * Cuando se establece en `true`, el componente llama a `dialog.showModal()` (si `modal`)
+     * o `dialog.show()`. Cuando se establece en `false`, llama a `dialog.close()`.
+     * Reflejado como un atributo HTML para CSS y lectores de estado externos.
      *
      * @default false
      */
     open: boolean;
     /**
-     * When `true`, opens the dialog as a modal using `<dialog>.showModal()`.
+     * Cuando es `true`, abre el diálogo como un modal usando `<dialog>.showModal()`.
      *
-     * Modal dialogs:
-     * - Block keyboard focus from leaving the dialog.
-     * - Render a `::backdrop` scrim over the rest of the page.
-     * - Can be closed by pressing `Escape` (native browser behavior).
+     * Diálogos modales:
+     * - Bloquean que el foco del teclado salga del diálogo.
+     * - Renderizan una capa `::backdrop` sobre el resto de la página.
+     * - Se pueden cerrar presionando `Escape` (comportamiento nativo del navegador).
      *
-     * When `false`, uses `<dialog>.show()` which is non-blocking (no focus trap
-     * and no backdrop).
+     * Cuando es `false`, usa `<dialog>.show()` que no es bloqueante (sin trampa de foco
+     * y sin capa de fondo).
      *
      * @default false
      */
     modal: boolean;
     /**
-     * Placement of the dialog within the viewport.
+     * Colocación del diálogo dentro de la ventana gráfica.
      *
-     * - `'center'` (default) — Centered. Standard M3 dialog placement.
-     * - `'top'`    — Anchored to the top edge (drawer from top).
-     * - `'right'`  — Anchored to the right edge (side sheet pattern).
-     * - `'bottom'` — Anchored to the bottom edge (bottom sheet alternative).
-     * - `'left'`   — Anchored to the left edge (navigation drawer pattern).
-     * - `'max'`    — Full-screen (covers the entire viewport).
+     * - `'center'` (por defecto) — Centrado. Colocación de diálogo M3 estándar.
+     * - `'top'`    — Anclado al borde superior (cajón desde arriba).
+     * - `'right'`  — Anclado al borde derecho (patrón de hoja lateral).
+     * - `'bottom'` — Anclado al borde inferior (alternativa de hoja inferior).
+     * - `'left'`   — Anclado al borde izquierdo (patrón de cajón de navegación).
+     * - `'max'`    — Pantalla completa (cubre toda la ventana gráfica).
      *
      * @default 'center'
      */
     side: 'center' | 'top' | 'right' | 'bottom' | 'left' | 'max';
     /**
-     * Size of the dialog container.
+     * Tamaño del contenedor del diálogo.
      *
-     * - `'small'`  — Narrow dialog; ideal for simple confirmations.
-     * - `'medium'` — Standard dialog width (default).
-     * - `'large'`  — Wide dialog; for forms or complex content.
+     * - `'small'`  — Diálogo estrecho; ideal para confirmaciones simples.
+     * - `'medium'` — Ancho de diálogo estándar (por defecto).
+     * - `'large'`  — Diálogo ancho; para formularios o contenido complejo.
      *
      * @default 'medium'
      */
     size: 'small' | 'medium' | 'large';
     /**
-     * Text displayed in the dialog header area.
+     * Texto mostrado en el área del encabezado del diálogo.
      *
-     * When non-empty, renders as a styled heading inside the header container.
-     * The `header` slot takes precedence over this attribute when both are present.
+     * Cuando no está vacío, se renderiza como un encabezado estilizado dentro del contenedor del encabezado.
+     * El slot `header` tiene prioridad sobre este atributo cuando ambos están presentes.
      *
      * @default ''
      */
     title: string;
-    /** Direct reference to the native `<dialog>` element for programmatic access. */
+    /** Referencia directa al elemento `<dialog>` nativo para acceso programático. */
     private _dialog;
+    willUpdate(changed: Map<string, unknown>): void;
     /**
-     * Syncs the `open` and `modal` state to the native `<dialog>` element.
+     * Hook de ciclo de vida de Lit. Sincroniza el estado declarativo (`open`, `modal`)
+     * con la API imperativa del elemento `<dialog>` nativo de HTML5.
      *
-     * Called by Lit after every render cycle where tracked properties change.
-     * Avoids calling `showModal()` or `show()` if the dialog is already open
-     * (prevents the `InvalidStateError` DOMException).
+     * - `showModal()`: Bloquea el resto del DOM (Inert), atrapa el foco del teclado (Focus Trap)
+     *   y renderiza el seudoelemento `::backdrop`.
+     * - `show()`: Permite interacción con el fondo (Non-modal).
      *
-     * @param changed - Map of changed property names to their previous values.
+     * IMPORTANTE: Previene la excepción `InvalidStateError` validando si el
+     * diálogo ya está abierto antes de llamar a `show()` o `showModal()`.
+     *
+     * @param changed - Mapa de propiedades reactivas modificadas.
      */
     updated(changed: Map<string, unknown>): void;
+    private _onTransitionEnd;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderiza el elemento `<dialog>` nativo con la estructura semántica de slots del diálogo.
+     *
+     * **¿Por qué `<dialog>`?**
+     * El elemento nativo `<dialog>` proporciona captura de foco, renderizado de fondo (backdrop)
+     * y semántica modal accesible sin JavaScript. El enlace `?open` de Lit
+     * alterna el atributo de forma imperativa, mientras que `updated()` llama a `.show()` /
+     * `.showModal()` / `.close()` para conducir la pila de abrir/cerrar nativa del navegador.
+     *
+     * **Estructura de slots:**
+     * - `[slot="header"]` — se repliega al valor del atributo `title`.
+     * - Slot por defecto — la región de contenido principal del diálogo.
+     * - `[slot="footer"]` — botones de acción (típicamente elementos `<moni-button>`).
+     *
+     * **Composición de `classes`:**
+     * `side`, `size`, y `modal` (si `modal=true`) se unen como clases CSS.
+     * `side` posiciona el diálogo en `start`, `end`, `top`, o `bottom`; usado
+     * para diálogos de panel lateral. `size` controla max-width/height.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-dialog.d.ts","sourceRoot":"","sources":["../../src/components/moni-dialog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C;;;;;;;;OAQG;IACyC,IAAI,UAAS;IAEzD;;;;;;;;;;;;OAYG;IACyC,KAAK,UAAS;IAE1D;;;;;;;;;;;OAWG;IAEH,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAY;IAExE;;;;;;;;OAQG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C;;;;;;;OAOG;IAC0B,KAAK,SAAM;IAExC,iFAAiF;IAChE,OAAO,CAAC,OAAO,CAAqB;IAErD;;;;;;;;OAQG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAoB9C,OAAgB,MAAM,4BAgKpB;IAEO,MAAM;CAef;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}
+{"version":3,"file":"moni-dialog.d.ts","sourceRoot":"","sources":["../../src/components/moni-dialog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,UAAW,SAAQ,WAAW;IAC1C;;;;;;;;OAQG;IACyC,IAAI,UAAS;IAEzD;;;;;;;;;;;;OAYG;IACyC,KAAK,UAAS;IAE1D;;;;;;;;;;;OAWG;IAEH,IAAI,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAY;IAExE;;;;;;;;OAQG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C;;;;;;;OAOG;IAC0B,KAAK,SAAM;IAExC,iFAAiF;IAChE,OAAO,CAAC,OAAO,CAAqB;IAE5C,UAAU,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAYjD;;;;;;;;;;;;OAYG;IACM,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC;IAsB9C,OAAO,CAAC,gBAAgB;IAUxB,OAAgB,MAAM,4BAgKpB;IAEF;;;;;;;;;;;;;;;;;;OAkBG;IACM,MAAM;CAgBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,aAAa,EAAE,UAAU,CAAC;KAC1B;CACD;AAED,eAAe,UAAU,CAAC"}