@moni-labs/moni-ui 0.3.0 → 0.3.2

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

@@ -6,84 +6,148 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Material Design 3 Tooltip component.
+ * Componente Material Design 3 Tooltip (Información sobre herramientas).
  *
- * Tooltips provide contextual text labels or rich content that appear when
- * users hover over, focus on, or tap an element. They surface supplementary
- * information that helps users understand interface elements without
- * permanently occupying screen space.
+ * Los tooltips proporcionan etiquetas de texto contextual o contenido enriquecido que aparecen cuando
+ * los usuarios pasan el cursor por encima, enfocan o tocan un elemento. Muestran información
+ * complementaria que ayuda a los usuarios a entender los elementos de la interfaz sin
+ * ocupar permanentemente espacio en la pantalla.
  *
- * **M3 spec reference:** `m3-docs/components/tooltips/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/tooltips/specs.md`
  *
- * **Types:**
- * - **Plain** (default) — Text-only label for simple descriptions (max 1 line).
- * - **Rich** (`rich` attribute) — HTML content including formatted text,
- *   links, and icons. Rich tooltips can contain multiple lines and action links.
+ * **Tipos:**
+ * - **Plain** (por defecto) — Etiqueta solo de texto para descripciones simples (máx. 1 línea).
+ * - **Rich** (atributo `rich`) — Contenido HTML que incluye texto formateado,
+ *   enlaces e iconos. Los tooltips enriquecidos pueden contener múltiples líneas y enlaces de acción.
  *
- * **Placements:**
- * - `top` (default), `top-start`, `top-end`
+ * **Ubicaciones (Placements):**
+ * - `top` (por defecto), `top-start`, `top-end`
  * - `bottom`, `bottom-start`, `bottom-end`
  *
- * **Trigger mechanism:**
- * The tooltip uses `position: absolute` inside the parent element. The parent
- * must have `position: relative` (set automatically via `connectedCallback`).
- * Hover/focus events on the parent trigger the tooltip's CSS `:hover` and
- * `:focus-within` selectors, which drive the show/hide transition.
+ * **Mecanismo de activación (Trigger):**
+ * El tooltip usa `position: absolute` dentro del elemento padre. El padre
+ * debe tener `position: relative` (establecido automáticamente vía `connectedCallback`).
+ * Los eventos hover/focus en el padre activan los selectores CSS `:hover` y
+ * `:focus-within` del tooltip, los cuales impulsan la transición de mostrar/ocultar.
  *
- * **Accessibility:**
- * - The tooltip has `role="tooltip"`.
- * - For keyboard accessibility, the parent should have `aria-describedby`
- *   pointing to the tooltip's `id` attribute. The component exposes a
- *   `tooltipId` getter for this purpose.
- * - The `Escape` key closes rich tooltips.
+ * **Accesibilidad:**
+ * - El tooltip tiene `role="tooltip"`.
+ * - Para accesibilidad por teclado, el padre debe tener `aria-describedby`
+ *   apuntando al atributo `id` del tooltip. El componente expone un
+ *   getter `tooltipId` para este propósito.
+ * - La tecla `Escape` cierra los tooltips enriquecidos.
  *
  * @example
  * ```html
- * <!-- Plain tooltip -->
+ * <!-- Tooltip simple (Plain) -->
  * <button aria-describedby="save-tip">
- *   Save
+ *   Guardar
  *   <moni-tooltip id="save-tip" text="Ctrl+S"></moni-tooltip>
  * </button>
  *
- * <!-- Rich tooltip -->
+ * <!-- Tooltip enriquecido (Rich) -->
  * <button>
- *   Filter
+ *   Filtrar
  *   <moni-tooltip rich position="bottom">
- *     <strong>Filter by date</strong>
- *     <p>Select a date range to filter results.</p>
+ *     <strong>Filtrar por fecha</strong>
+ *     <p>Selecciona un rango de fechas para filtrar resultados.</p>
  *   </moni-tooltip>
  * </button>
  * ```
  *
- * @slot default - Rich content for the tooltip body (only used when `rich=true`).
+ * @slot default - Contenido enriquecido para el cuerpo del tooltip (solo usado cuando `rich=true`).
  *
- * @csspart tooltip - The tooltip container element.
+ * @csspart tooltip - El elemento contenedor del tooltip.
  */
 export declare class MoniTooltip extends MoniElement {
+    /**
+     * Contenido de texto simple para mostrar. Utilizado cuando `rich` es falso.
+     * @type {string}
+     */
     text: string;
+    /**
+     * Ubicación preferida relativa al ancla/activador.
+     * @type {'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'}
+     * @default 'top'
+     */
     position: 'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end';
+    /**
+     * Mapeo de tamaño opcional (usado por hojas de estilo internas para escalar fuente/relleno).
+     * @type {'' | 'small' | 'medium' | 'large'}
+     * @default ''
+     */
     size: '' | 'small' | 'medium' | 'large';
+    /**
+     * Si es true, cambia al modo de Tooltip Enriquecido (permite HTML/componentes en el slot por defecto).
+     * @type {boolean}
+     */
     rich: boolean;
     private _target;
     private _tooltipEl;
+    /**
+     * Wrapper estático para el evento de teclado global.
+     * Mantiene fijo el contexto léxico para registrar/desregistrar limpiamente.
+     */
     private _docKeydown;
     /**
-     * CSS `anchor-name` registered on the parent trigger so the tooltip
-     * can use `position-anchor` to bind to it. Generated per-instance via
-     * `crypto.randomUUID()` when CSS anchor positioning is supported.
+     * Nombre de anclaje CSS (`anchor-name`) registrado en el activador padre para que el tooltip
+     * pueda usar `position-anchor` para vincularse a él. Generado por instancia vía
+     * `crypto.randomUUID()` cuando el posicionamiento de anclaje CSS está soportado.
      */
     private _anchorName;
+    /**
+     * Hook de inicialización (Lit).
+     * Resuelve la asociación nativa con su elemento padre (trigger), forzando un contexto
+     * de posicionamiento relativo (`position: relative`) si es necesario. Vincula dinámicamente
+     * listeners de `mouseenter/leave` y `focusin/out` para controlar la visibilidad del globo.
+     * También auto-registra la revolucionaria CSS Anchor Positioning API si el navegador la soporta.
+     */
     connectedCallback(): void;
+    /**
+     * Hook de destrucción (Lit).
+     * Remueve diligentemente todos los detectores de eventos del padre (trigger)
+     * y limpia las declaraciones generadas dinámicamente en estilos inline (`anchor-name`).
+     */
     disconnectedCallback(): void;
+    /**
+     * Inyecta la clase activa (`.visible`) desencadenando la animación de opacidad/escalado.
+     * Cached-query: Recupera asíncronamente el tooltip del Shadow DOM si no lo había hecho.
+     */
     private _show;
+    /**
+     * Retira la clase activa (`.visible`), desvaneciendo el globo con gracia.
+     */
     private _hide;
+    /**
+     * Manejador global del teclado (a11y).
+     * Permite disipar instantáneamente el tooltip presionando `Escape`
+     * sin necesidad de mover el ratón o perder el foco.
+     */
     private _handleDocKeydown;
     /**
-     * Public ID of the tooltip element, suitable for `aria-describedby` on
-     * the trigger parent. Auto-generated if the consumer did not set `id`.
+     * ID público del elemento tooltip, adecuado para `aria-describedby` en
+     * el padre activador. Generado automáticamente si el consumidor no estableció un `id`.
      */
     get tooltipId(): string;
     static styles: import("lit").CSSResult[];
+    /**
+     * Renderiza el `<div>` del tooltip con su lista de clases calculada y atributos ARIA.
+     *
+     * **Composición de clases:**
+     * - `'tooltip'` — siempre presente; estilos base.
+     * - `this.position` — variante de ubicación (ej. `'top'`, `'bottom-start'`).
+     * - `this.size` — modificador de tamaño (`'small'`, `'medium'`, `'large'`).
+     *
+     * **CSS Anchor Positioning:**
+     * Si `_anchorName` está poblado, lo inyecta como la propiedad personalizada `--_anchor-name`.
+     * La declaración CSS `@anchor-name` conecta este tooltip a su elemento activador
+     * a través de la API CSS Anchor Positioning (Chrome 125+).
+     * En navegadores no compatibles, se utiliza un posicionamiento absoluto clásico como respaldo.
+     *
+     * **Respaldo de contenido:**
+     * El slot por defecto renderiza el contenido distribuido (slotted); si no hay hijos,
+     * el valor del atributo `text` se muestra como la etiqueta del tooltip.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

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

@@ -1 +1 @@
-{"version":3,"file":"moni-tooltip.d.ts","sourceRoot":"","sources":["../../src/components/moni-tooltip.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBACa,WAAY,SAAQ,WAAW;IACd,IAAI,SAAM;IAEvC,QAAQ,EACL,KAAK,GACL,WAAW,GACX,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,CAAS;IAExB,IAAI,EAAE,EAAE,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAM;IACD,IAAI,UAAS;IAEzD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,WAAW,CAAmD;IACtE;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAuB;IAEjC,iBAAiB;IAoCjB,oBAAoB;IAe7B,OAAO,CAAC,KAAK,CAOX;IAEF,OAAO,CAAC,KAAK,CAOX;IAEF,OAAO,CAAC,iBAAiB;IAMzB;;;OAGG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,OAAgB,MAAM,4BA2JpB;IAEO,MAAM;CAgBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}
+{"version":3,"file":"moni-tooltip.d.ts","sourceRoot":"","sources":["../../src/components/moni-tooltip.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,qBACa,WAAY,SAAQ,WAAW;IAC3C;;;OAGG;IAC0B,IAAI,SAAM;IAEvC;;;;OAIG;IAEH,QAAQ,EACL,KAAK,GACL,WAAW,GACX,SAAS,GACT,QAAQ,GACR,cAAc,GACd,YAAY,CAAS;IAExB;;;;OAIG;IAEH,IAAI,EAAE,EAAE,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAM;IAE7C;;;OAGG;IACyC,IAAI,UAAS;IAEzD,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,UAAU,CAA4B;IAC9C;;;OAGG;IACH,OAAO,CAAC,WAAW,CAAmD;IACtE;;;;OAIG;IACH,OAAO,CAAC,WAAW,CAAuB;IAE1C;;;;;;OAMG;IACM,iBAAiB;IAoC1B;;;;OAIG;IACM,oBAAoB;IAe7B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAOX;IAEF;;OAEG;IACH,OAAO,CAAC,KAAK,CAOX;IAEF;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAMzB;;;OAGG;IACH,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,OAAgB,MAAM,4BA2JpB;IAEF;;;;;;;;;;;;;;;;;OAiBG;IACM,MAAM;CAgBf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,cAAc,EAAE,WAAW,CAAC;KAC5B;CACD;AAED,eAAe,WAAW,CAAC"}

package/dist/components/moni-tooltip.js

@@ -14,75 +14,101 @@ import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 /**
- * Material Design 3 Tooltip component.
+ * Componente Material Design 3 Tooltip (Información sobre herramientas).
  *
- * Tooltips provide contextual text labels or rich content that appear when
- * users hover over, focus on, or tap an element. They surface supplementary
- * information that helps users understand interface elements without
- * permanently occupying screen space.
+ * Los tooltips proporcionan etiquetas de texto contextual o contenido enriquecido que aparecen cuando
+ * los usuarios pasan el cursor por encima, enfocan o tocan un elemento. Muestran información
+ * complementaria que ayuda a los usuarios a entender los elementos de la interfaz sin
+ * ocupar permanentemente espacio en la pantalla.
  *
- * **M3 spec reference:** `m3-docs/components/tooltips/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/tooltips/specs.md`
  *
- * **Types:**
- * - **Plain** (default) — Text-only label for simple descriptions (max 1 line).
- * - **Rich** (`rich` attribute) — HTML content including formatted text,
- *   links, and icons. Rich tooltips can contain multiple lines and action links.
+ * **Tipos:**
+ * - **Plain** (por defecto) — Etiqueta solo de texto para descripciones simples (máx. 1 línea).
+ * - **Rich** (atributo `rich`) — Contenido HTML que incluye texto formateado,
+ *   enlaces e iconos. Los tooltips enriquecidos pueden contener múltiples líneas y enlaces de acción.
  *
- * **Placements:**
- * - `top` (default), `top-start`, `top-end`
+ * **Ubicaciones (Placements):**
+ * - `top` (por defecto), `top-start`, `top-end`
  * - `bottom`, `bottom-start`, `bottom-end`
  *
- * **Trigger mechanism:**
- * The tooltip uses `position: absolute` inside the parent element. The parent
- * must have `position: relative` (set automatically via `connectedCallback`).
- * Hover/focus events on the parent trigger the tooltip's CSS `:hover` and
- * `:focus-within` selectors, which drive the show/hide transition.
+ * **Mecanismo de activación (Trigger):**
+ * El tooltip usa `position: absolute` dentro del elemento padre. El padre
+ * debe tener `position: relative` (establecido automáticamente vía `connectedCallback`).
+ * Los eventos hover/focus en el padre activan los selectores CSS `:hover` y
+ * `:focus-within` del tooltip, los cuales impulsan la transición de mostrar/ocultar.
  *
- * **Accessibility:**
- * - The tooltip has `role="tooltip"`.
- * - For keyboard accessibility, the parent should have `aria-describedby`
- *   pointing to the tooltip's `id` attribute. The component exposes a
- *   `tooltipId` getter for this purpose.
- * - The `Escape` key closes rich tooltips.
+ * **Accesibilidad:**
+ * - El tooltip tiene `role="tooltip"`.
+ * - Para accesibilidad por teclado, el padre debe tener `aria-describedby`
+ *   apuntando al atributo `id` del tooltip. El componente expone un
+ *   getter `tooltipId` para este propósito.
+ * - La tecla `Escape` cierra los tooltips enriquecidos.
  *
  * @example
  * ```html
- * <!-- Plain tooltip -->
+ * <!-- Tooltip simple (Plain) -->
  * <button aria-describedby="save-tip">
- *   Save
+ *   Guardar
  *   <moni-tooltip id="save-tip" text="Ctrl+S"></moni-tooltip>
  * </button>
  *
- * <!-- Rich tooltip -->
+ * <!-- Tooltip enriquecido (Rich) -->
  * <button>
- *   Filter
+ *   Filtrar
  *   <moni-tooltip rich position="bottom">
- *     <strong>Filter by date</strong>
- *     <p>Select a date range to filter results.</p>
+ *     <strong>Filtrar por fecha</strong>
+ *     <p>Selecciona un rango de fechas para filtrar resultados.</p>
  *   </moni-tooltip>
  * </button>
  * ```
  *
- * @slot default - Rich content for the tooltip body (only used when `rich=true`).
+ * @slot default - Contenido enriquecido para el cuerpo del tooltip (solo usado cuando `rich=true`).
  *
- * @csspart tooltip - The tooltip container element.
+ * @csspart tooltip - El elemento contenedor del tooltip.
  */
 let MoniTooltip = class MoniTooltip extends MoniElement {
     constructor() {
         super(...arguments);
+        /**
+         * Contenido de texto simple para mostrar. Utilizado cuando `rich` es falso.
+         * @type {string}
+         */
         this.text = '';
+        /**
+         * Ubicación preferida relativa al ancla/activador.
+         * @type {'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'}
+         * @default 'top'
+         */
         this.position = 'top';
+        /**
+         * Mapeo de tamaño opcional (usado por hojas de estilo internas para escalar fuente/relleno).
+         * @type {'' | 'small' | 'medium' | 'large'}
+         * @default ''
+         */
         this.size = '';
+        /**
+         * Si es true, cambia al modo de Tooltip Enriquecido (permite HTML/componentes en el slot por defecto).
+         * @type {boolean}
+         */
         this.rich = false;
         this._target = null;
         this._tooltipEl = null;
+        /**
+         * Wrapper estático para el evento de teclado global.
+         * Mantiene fijo el contexto léxico para registrar/desregistrar limpiamente.
+         */
         this._docKeydown = (e) => this._handleDocKeydown(e);
         /**
-         * CSS `anchor-name` registered on the parent trigger so the tooltip
-         * can use `position-anchor` to bind to it. Generated per-instance via
-         * `crypto.randomUUID()` when CSS anchor positioning is supported.
+         * Nombre de anclaje CSS (`anchor-name`) registrado en el activador padre para que el tooltip
+         * pueda usar `position-anchor` para vincularse a él. Generado por instancia vía
+         * `crypto.randomUUID()` cuando el posicionamiento de anclaje CSS está soportado.
          */
         this._anchorName = null;
+        /**
+         * Inyecta la clase activa (`.visible`) desencadenando la animación de opacidad/escalado.
+         * Cached-query: Recupera asíncronamente el tooltip del Shadow DOM si no lo había hecho.
+         */
         this._show = () => {
             if (!this._tooltipEl) {
                 this._tooltipEl = this.shadowRoot?.querySelector('.tooltip');
@@ -91,6 +117,9 @@ let MoniTooltip = class MoniTooltip extends MoniElement {
                 this._tooltipEl.classList.add('visible');
             }
         };
+        /**
+         * Retira la clase activa (`.visible`), desvaneciendo el globo con gracia.
+         */
         this._hide = () => {
             if (!this._tooltipEl) {
                 this._tooltipEl = this.shadowRoot?.querySelector('.tooltip');
@@ -100,11 +129,18 @@ let MoniTooltip = class MoniTooltip extends MoniElement {
             }
         };
     }
+    /**
+     * Hook de inicialización (Lit).
+     * Resuelve la asociación nativa con su elemento padre (trigger), forzando un contexto
+     * de posicionamiento relativo (`position: relative`) si es necesario. Vincula dinámicamente
+     * listeners de `mouseenter/leave` y `focusin/out` para controlar la visibilidad del globo.
+     * También auto-registra la revolucionaria CSS Anchor Positioning API si el navegador la soporta.
+     */
     connectedCallback() {
         super.connectedCallback();
         this._target = this.parentElement;
         if (this._target) {
-            // Ensure parent has position: relative so absolute tooltip is anchored
+            // Asegura que el padre tenga position: relative para anclar el tooltip absoluto
             const style = getComputedStyle(this._target);
             if (style.position === 'static') {
                 this._target.style.position = 'relative';
@@ -113,9 +149,9 @@ let MoniTooltip = class MoniTooltip extends MoniElement {
             this._target.addEventListener('focusin', this._show);
             this._target.addEventListener('mouseleave', this._hide);
             this._target.addEventListener('focusout', this._hide);
-            // Auto-register a CSS anchor name on the parent trigger when the
-            // browser supports anchor positioning. Consumers can opt out by
-            // setting `data-no-anchor` on the trigger.
+            // Auto-registra un nombre de ancla CSS en el activador padre cuando el
+            // navegador soporta posicionamiento de ancla. Los consumidores pueden excluirse
+            // estableciendo `data-no-anchor` en el activador.
             const cssSupports = globalThis.CSS?.supports;
             const supportsAnchor = cssSupports
                 ? cssSupports.call(window.CSS, 'anchor-name: --x')
@@ -130,6 +166,11 @@ let MoniTooltip = class MoniTooltip extends MoniElement {
         }
         document.addEventListener('keydown', this._docKeydown);
     }
+    /**
+     * Hook de destrucción (Lit).
+     * Remueve diligentemente todos los detectores de eventos del padre (trigger)
+     * y limpia las declaraciones generadas dinámicamente en estilos inline (`anchor-name`).
+     */
     disconnectedCallback() {
         if (this._target) {
             this._target.removeEventListener('mouseenter', this._show);
@@ -144,6 +185,11 @@ let MoniTooltip = class MoniTooltip extends MoniElement {
         document.removeEventListener('keydown', this._docKeydown);
         super.disconnectedCallback();
     }
+    /**
+     * Manejador global del teclado (a11y).
+     * Permite disipar instantáneamente el tooltip presionando `Escape`
+     * sin necesidad de mover el ratón o perder el foco.
+     */
     _handleDocKeydown(e) {
         if (e.key !== 'Escape')
             return;
@@ -152,8 +198,8 @@ let MoniTooltip = class MoniTooltip extends MoniElement {
         this._hide();
     }
     /**
-     * Public ID of the tooltip element, suitable for `aria-describedby` on
-     * the trigger parent. Auto-generated if the consumer did not set `id`.
+     * ID público del elemento tooltip, adecuado para `aria-describedby` en
+     * el padre activador. Generado automáticamente si el consumidor no estableció un `id`.
      */
     get tooltipId() {
         return this._tooltipEl?.id || '';
@@ -314,6 +360,24 @@ let MoniTooltip = class MoniTooltip extends MoniElement {
 			.tooltip.visible.right { transform: translate(100%, -50%) scale(1); }
 		`
     ]; }
+    /**
+     * Renderiza el `<div>` del tooltip con su lista de clases calculada y atributos ARIA.
+     *
+     * **Composición de clases:**
+     * - `'tooltip'` — siempre presente; estilos base.
+     * - `this.position` — variante de ubicación (ej. `'top'`, `'bottom-start'`).
+     * - `this.size` — modificador de tamaño (`'small'`, `'medium'`, `'large'`).
+     *
+     * **CSS Anchor Positioning:**
+     * Si `_anchorName` está poblado, lo inyecta como la propiedad personalizada `--_anchor-name`.
+     * La declaración CSS `@anchor-name` conecta este tooltip a su elemento activador
+     * a través de la API CSS Anchor Positioning (Chrome 125+).
+     * En navegadores no compatibles, se utiliza un posicionamiento absoluto clásico como respaldo.
+     *
+     * **Respaldo de contenido:**
+     * El slot por defecto renderiza el contenido distribuido (slotted); si no hay hijos,
+     * el valor del atributo `text` se muestra como la etiqueta del tooltip.
+     */
     render() {
         const classes = [
             'tooltip',

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

@@ -6,55 +6,93 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Material Design 3 Typography component.
+ * Componente Material Design 3 Typography (Tipografía).
  *
- * A specialized text component that enforces the M3 type scale. It ensures
- * typography is consistent, accessible, and correctly styled across the
- * application without requiring manual CSS classes.
+ * Un componente de texto especializado que aplica la escala tipográfica M3. Asegura
+ * que la tipografía sea consistente, accesible y correctamente estilizada en toda la
+ * aplicación sin requerir clases CSS manuales.
  *
- * **M3 spec reference:** `m3-docs/components/typography/specs.md`
+ * **Categorías de Escala Tipográfica:**
+ * - `display`: El texto más grande en la pantalla, reservado para texto corto e importante
+ *   o números. Funciona mejor en pantallas grandes. (Renderiza `<h1>` por defecto).
+ * - `headline`: Texto de alto énfasis para encabezados primarios de página/sección.
+ *   (Renderiza `<h2>` por defecto).
+ * - `title`: Texto de énfasis medio utilizado para encabezados de diálogos o títulos
+ *   de sección más pequeños. (Renderiza `<h3>` por defecto).
+ * - `body`: Texto de párrafo estándar utilizado para contenido largo.
+ *   (Renderiza `<p>` por defecto).
+ * - `label`: Texto pequeño y utilitario usado para botones, leyendas y elementos
+ *   de formulario. (Renderiza `<label>` por defecto).
  *
- * **Type Scale Categories:**
- * - `display`: The largest text on the screen, reserved for short, important
- *   text or numerals. Works best on large screens. (Renders `<h1>` by default).
- * - `headline`: High-emphasis text for primary page/section headers.
- *   (Renders `<h2>` by default).
- * - `title`: Medium-emphasis text used for dialog headers or smaller section
- *   titles. (Renders `<h3>` by default).
- * - `body`: Standard paragraph text used for long-form content.
- *   (Renders `<p>` by default).
- * - `label`: Small, utilitarian text used for buttons, captions, and form
- *   elements. (Renders `<label>` by default).
+ * Cada categoría soporta tres tamaños: `large`, `medium` y `small`.
  *
- * Each category supports three sizes: `large`, `medium`, and `small`.
+ * **Etiquetas Semánticas:**
+ * El componente selecciona automáticamente una etiqueta semántica HTML apropiada basada en
+ * la variante. Puedes sobrescribir esto explícitamente configurando el atributo `as`
+ * (ej., para renderizar un estilo `headline` pero usando una etiqueta `<span>` por razones
+ * de SEO o estructurales).
  *
- * **Semantic Tags:**
- * The component automatically selects an appropriate HTML semantic tag based on
- * the variant. You can explicitly override this by setting the `as` attribute
- * (e.g., to render a `headline` style but using a `<span>` tag for SEO or
- * structural reasons).
+ * @element moni-typography
  *
  * @example
  * ```html
- * <!-- Renders an <h1> with display-large styles -->
- * <moni-typography variant="display" size="large">Hero Text</moni-typography>
+ * <!-- Renderiza un <h1> con estilos display-large -->
+ * <moni-typography variant="display" size="large">Texto Héroe</moni-typography>
  *
- * <!-- Renders a <p> with body-medium styles -->
- * <moni-typography variant="body">Standard paragraph text.</moni-typography>
+ * <!-- Renderiza un <p> con estilos body-medium -->
+ * <moni-typography variant="body">Texto de párrafo estándar.</moni-typography>
  *
- * <!-- Overriding the semantic tag -->
- * <moni-typography variant="title" as="span">Inline title</moni-typography>
+ * <!-- Sobrescribiendo la etiqueta semántica -->
+ * <moni-typography variant="title" as="span">Título en línea</moni-typography>
  * ```
  *
- * @slot default - The text content to display.
+ * @slot default - El contenido de texto a mostrar.
+ * @csspart text - El elemento semántico interno (ej., h1, p, span) que envuelve el texto.
  */
 export declare class MoniTypography extends MoniElement {
+    /**
+     * La categoría de la escala tipográfica M3 a aplicar.
+     * Dicta la lógica base de font-family, line-height, weight, y letter-spacing.
+     * @type {'display' | 'headline' | 'title' | 'body' | 'label'}
+     */
     variant: 'display' | 'headline' | 'title' | 'body' | 'label';
+    /**
+     * El tamaño dentro de la categoría de variante elegida.
+     * @type {'large' | 'medium' | 'small'}
+     */
     size: 'large' | 'medium' | 'small';
+    /**
+     * Sobrescribe la etiqueta semántica HTML por defecto (ej. 'h1', 'p', 'span')
+     * que se asigna automáticamente basándose en la variante (`variant`).
+     * @type {string | null}
+     */
     as: string | null;
+    /**
+     * Contenido de texto simple opcional. Típicamente usarías el slot por defecto en su lugar.
+     * @type {string}
+     */
     text: string;
-    /** Default semantic tag for each variant per M3 spec. */
+    /** Etiqueta semántica por defecto para cada variante según la especificación M3. */
     private static _tagFor;
+    /**
+     * Renderiza el elemento tipográfico con una etiqueta HTML seleccionada dinámicamente.
+     *
+     * **Selección dinámica de etiquetas:**
+     * `_tagFor(variant)` infiere el elemento HTML semántico de la variante de tipografía
+     * (ej. `'display-large'` → `<h1>`, `'body-medium'` → `<p>`).
+     * El atributo `as` sobrescribe esta inferencia para contextos semánticos personalizados
+     * (ej. usar `as="div"` cuando la tipografía está dentro de un `<dl>`).
+     *
+     * **¿Por qué `staticHtml` + `unsafeStatic`?**
+     * Lit 3 no permite expresiones dinámicas en posiciones de nombres de etiquetas
+     * (`<${tag}>` lanzaría un error de plantilla). `staticHtml` es un template tag
+     * provisto por Lit que sí permite la interpolación estática de etiquetas, y `unsafeStatic`
+     * envuelve el string para marcarlo como de confianza (sin riesgo XSS ya que `tag` proviene de
+     * un enum controlado vía `_tagFor()`).
+     *
+     * El string `cls` (`variant + size`) mapea directamente a clases de utilidad
+     * de tipografía (ej. `'display large'`).
+     */
     render(): import("lit").TemplateResult;
     static styles: import("lit").CSSResult[];
 }

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

@@ -1 +1 @@
-{"version":3,"file":"moni-typography.d.ts","sourceRoot":"","sources":["../../src/components/moni-typography.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBACa,cAAe,SAAQ,WAAW;IAE9C,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAU;IAEtE,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C,EAAE,EAAE,MAAM,GAAG,IAAI,CAAQ;IACI,IAAI,SAAM;IAEvC,yDAAyD;IACzD,OAAO,CAAC,MAAM,CAAC,OAAO;IAiBb,MAAM;IAcf,OAAgB,MAAM,4BAkHpB;CACF;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,cAAc,CAAC;KAClC;CACD;AAED,eAAe,cAAc,CAAC"}
+{"version":3,"file":"moni-typography.d.ts","sourceRoot":"","sources":["../../src/components/moni-typography.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,qBACa,cAAe,SAAQ,WAAW;IAC9C;;;;OAIG;IAEH,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAU;IAEtE;;;OAGG;IAEH,IAAI,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAY;IAE9C;;;;OAIG;IAEH,EAAE,EAAE,MAAM,GAAG,IAAI,CAAQ;IAEzB;;;OAGG;IAC0B,IAAI,SAAM;IAEvC,oFAAoF;IACpF,OAAO,CAAC,MAAM,CAAC,OAAO;IAiBtB;;;;;;;;;;;;;;;;;;OAkBG;IACM,MAAM;IAcf,OAAgB,MAAM,4BAkHpB;CACF;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,cAAc,CAAC;KAClC;CACD;AAED,eAAe,cAAc,CAAC"}