@moni-labs/moni-ui 0.4.4 → 0.4.6

package/docs/components/side-sheet.md

@@ -0,0 +1,218 @@
+# Side Sheet
+
+Componente Material Design 3 Side Sheet (Hoja o panel lateral).
+
+Los paneles laterales muestran contenido complementario que está anclado al borde
+izquierdo o derecho de la pantalla. Pueden ser estándar (en línea con el contenido)
+o modales (superpuestos al contenido con un fondo/scrim oscurecido).
+
+**Referencia a la especificación M3:** `m3-docs/components/side-sheets/specs.md`
+
+**Comportamiento del cuadro de diálogo (Dialog behavior):**
+Internamente, este componente utiliza el elemento HTML nativo `<dialog>` para una
+accesibilidad robusta, captura de foco y renderizado en la capa superior (top-layer).
+- Cuando `modal=true`, el panel usa `dialog.showModal()`, renderizando un fondo
+  (scrim backdrop) y capturando el foco. Al presionar `Escape` se cierra.
+- Cuando `modal=false`, el panel usa `dialog.show()` y permanece interactivo
+  junto al contenido de la página principal.
+
+**Arrastrar y redimensionar (Característica Moni):**
+Al configurar el atributo `with-handle`, se agrega un controlador de arrastre en el borde
+interior del panel. Los usuarios pueden hacer clic y arrastrar este controlador para 
+redimensionar el ancho del panel hasta el límite `max-width`. Si el usuario arrastra
+el panel hacia el borde de la pantalla rápidamente o más allá de cierto umbral, se cierra automáticamente.
+
+**Animaciones:**
+Los paneles laterales se deslizan desde el `side` (lado) especificado (`left` o `right`).
+Las animaciones de apertura y cierre se manejan a través de transiciones CSS vinculadas a la propiedad `open`.
+
+- Tag: `moni-side-sheet`
+- Clase: `MoniSideSheet`
+- Fuente: `src/components/moni-side-sheet.ts`
+
+## Cuándo usarlo
+
+Usa `moni-side-sheet` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<!-- Panel lateral modal a la derecha -->
+<moni-side-sheet id="details-sheet" modal title="Detalles del artículo">
+  <p>Aquí hay más información sobre el artículo seleccionado.</p>
+  <div slot="footer">
+    <moni-button>Guardar</moni-button>
+  </div>
+</moni-side-sheet>
+
+<!-- Panel lateral a la izquierda, desvinculado (detached) y redimensionable -->
+<moni-side-sheet side="left" detached with-handle max-width="50vw">
+  <p>Opciones de navegación</p>
+</moni-side-sheet>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-side-sheet></moni-side-sheet>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-side-sheet` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Mantén el estado de apertura en una única fuente de verdad y devuelve el foco al disparador al cerrar.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `open` | `open` | `boolean` | `false` | Controla si la superficie superpuesta está abierta. |
+| `modal` | `modal` | `boolean` | `false` | Activa o desactiva el comportamiento `modal`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `side` | `side` | `'right' \| 'left'` | `'right'` | Selecciona el valor de `side` entre las opciones documentadas. |
+| `title` | `title` | `string` | `''` | Define `title`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `detached` | `detached` | `boolean` | `false` | Activa o desactiva el comportamiento `detached`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `show-back` | `showBack` | `boolean` | `false` | Activa o desactiva el comportamiento `showBack`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `no-border` | `noBorder` | `boolean` | `false` | Activa o desactiva el comportamiento `noBorder`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `with-handle` | `withHandle` | `boolean` | `false` | Activa o desactiva el comportamiento `withHandle`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `hide-close` | `hideClose` | `boolean` | `false` | Activa o desactiva el comportamiento `hideClose`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `expanded-width` | `expandedWidth` | `string` | `'600px'` | Define `expandedWidth`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `max-width` | `maxWidth` | `string` | `''` | Define `maxWidth`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+
+## Slots
+
+- `default`: Contenido del cuerpo principal.
+- `header`: Contenido de encabezado personalizado (anula `title`, los botones de cerrar/volver permanecen).
+- `footer`: Área de acción anclada en la parte inferior.
+
+## Eventos
+
+- `close`: evento compuesto y burbujeante emitido por el componente.
+- `back`: evento compuesto y burbujeante emitido por el componente.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `content`: Parte interna personalizable.
+- `dialog`: Parte interna personalizable.
+- `footer`: Parte interna personalizable.
+- `header`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--elevate1`
+- `--elevate3`
+- `--moni-side-sheet-expanded-width`
+- `--moni-side-sheet-max-width`
+- `--on-surface`
+- `--on-surface-variant`
+- `--outline-variant`
+- `--speed1`
+- `--speed3`
+- `--surface`
+- `--surface-container-low`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `open`
+
+Controla si la superficie superpuesta está abierta.
+
+![moni-side-sheet — open=true](../assets/moni-side-sheet/open--true.png)
+
+### `modal`
+
+Activa o desactiva el comportamiento `modal`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-side-sheet — modal=false](../assets/moni-side-sheet/modal--false.png)
+
+![moni-side-sheet — modal=true](../assets/moni-side-sheet/modal--true.png)
+
+### `side`
+
+Selecciona el valor de `side` entre las opciones documentadas.
+
+![moni-side-sheet — side=right](../assets/moni-side-sheet/side--right.png)
+
+![moni-side-sheet — side=left](../assets/moni-side-sheet/side--left.png)
+
+### `title`
+
+Define `title`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-side-sheet — title=default](../assets/moni-side-sheet/title--default.png)
+
+### `detached`
+
+Activa o desactiva el comportamiento `detached`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-side-sheet — detached=false](../assets/moni-side-sheet/detached--false.png)
+
+![moni-side-sheet — detached=true](../assets/moni-side-sheet/detached--true.png)
+
+### `show-back`
+
+Activa o desactiva el comportamiento `showBack`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-side-sheet — show-back=false](../assets/moni-side-sheet/showBack--false.png)
+
+![moni-side-sheet — show-back=true](../assets/moni-side-sheet/showBack--true.png)
+
+### `no-border`
+
+Activa o desactiva el comportamiento `noBorder`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-side-sheet — no-border=false](../assets/moni-side-sheet/noBorder--false.png)
+
+![moni-side-sheet — no-border=true](../assets/moni-side-sheet/noBorder--true.png)
+
+### `with-handle`
+
+Activa o desactiva el comportamiento `withHandle`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-side-sheet — with-handle=false](../assets/moni-side-sheet/withHandle--false.png)
+
+![moni-side-sheet — with-handle=true](../assets/moni-side-sheet/withHandle--true.png)
+
+### `hide-close`
+
+Activa o desactiva el comportamiento `hideClose`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-side-sheet — hide-close=false](../assets/moni-side-sheet/hideClose--false.png)
+
+![moni-side-sheet — hide-close=true](../assets/moni-side-sheet/hideClose--true.png)
+
+### `expanded-width`
+
+Define `expandedWidth`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-side-sheet — expanded-width=default](../assets/moni-side-sheet/expandedWidth--default.png)
+
+### `max-width`
+
+Define `maxWidth`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-side-sheet — max-width=default](../assets/moni-side-sheet/maxWidth--default.png)

package/docs/components/slider.md

@@ -0,0 +1,240 @@
+# Slider
+
+Componente Material Design 3 Slider (Control deslizante).
+
+Los sliders permiten a los usuarios seleccionar un solo valor o un rango de valores
+desde una escala continua o discreta.
+
+**Referencia a la especificación M3:** `m3-docs/components/sliders/specs.md`
+
+**Modos de Slider:**
+- **Continuo (Continuous)** (por defecto) — Arrastre suave entre `min` y `max`. Úsalo cuando
+  no sea necesario que el usuario defina un valor exacto (ej. volumen).
+- **Discreto (Discrete)** — Configura `step` para ajustarse a intervalos discretos. Las marcas
+  (tick marks) aparecen a través del elemento nativo `<datalist>` en Chrome/Edge. Firefox no
+  renderiza marcas de datalist para inputs de tipo rango.
+- **Rango (Range)** (atributo `range`) — Dos controles (thumbs) que definen un valor mínimo y
+  máximo dentro de la extensión del slider.
+- **Vertical** (atributo `vertical`) — Slider rotado 90°.
+
+**Tooltip indicador de valor (Value label tooltip):**
+Cuando se configura `indicator`, el valor actual se muestra en un tooltip por encima
+(o por debajo, a través de `indicator-placement`) del control activo durante el foco/arrastre.
+
+**Marcas (Tick marks):**
+- Atributo `ticks`: agrega datalist con marcas solo en `min` y `max`.
+- Atributo `tick-interval`: genera opciones de datalist cada N unidades
+  entre `min` y `max`, creando marcas visibles en esas posiciones.
+
+**Manejo del estado interno:**
+Usa `@state()` para `_value` y `_valueHigh` de modo que el ancho de la pista de llenado y
+la posición del tooltip se actualicen de forma reactiva en cada evento `input` de arrastre sin
+esperar al evento `change`.
+
+- Tag: `moni-slider`
+- Clase: `MoniSlider`
+- Fuente: `src/components/moni-slider.ts`
+
+## Cuándo usarlo
+
+Usa `moni-slider` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<!-- Slider continuo -->
+<moni-slider name="volume" min="0" max="100" value="60"></moni-slider>
+
+<!-- Slider discreto con marcas cada 10 unidades -->
+<moni-slider step="10" tick-interval="10" indicator></moni-slider>
+
+<!-- Slider de rango -->
+<moni-slider range min="0" max="100" value="20" value-high="80"></moni-slider>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-slider></moni-slider>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-slider` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Durante una operación asíncrona combina el estado `loading` —si existe— con `disabled` para evitar envíos duplicados.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `name` | `name` | `string` | `''` | Nombre del input del slider, usado en el envío de formularios. |
+| `min` | `min` | `string` | `'0'` | Valor mínimo del slider. |
+| `max` | `max` | `string` | `'100'` | Valor máximo del slider. |
+| `step` | `step` | `string` | `''` | Granularidad del slider. Debe ser un número positivo. |
+| `tick-interval` | `tickInterval` | `number \| null` | `null` | Anula (overrides) el intervalo predeterminado de las marcas cuando `ticks` es verdadero. |
+| `inset-icon` | `insetIcon` | `string` | `''` | Nombre del icono (Material Symbols) mostrado dentro del control (thumb) del slider. |
+| `indicator-placement` | `indicatorPlacement` | `'top' \| 'bottom'` | `'top'` | Ubicación del tooltip indicador de valor. |
+| `size` | `size` | `'tiny' \| 'small' \| 'medium' \| 'large' \| 'extra'` | `'medium'` | Grosor/tamaño de la pista y el control (thumb) del slider. |
+| `range` | `range` | `boolean` | `false` | Habilita el modo de rango (dos controles: `value` y `valueEnd`). |
+| `disabled` | `disabled` | `boolean` | `false` | Deshabilita el slider. |
+| `ticks` | `ticks` | `boolean` | `false` | Renderiza marcas (tick marks) a lo largo de la pista en cada intervalo de paso. |
+| `indicator` | `indicator` | `boolean` | `false` | Muestra un indicador de tooltip mostrando el(los) valor(es) actual(es) mientras se arrastra. |
+| `vertical` | `isVertical` | `boolean` | `false` | Renderiza el slider de forma vertical en lugar de horizontal. |
+
+## Slots
+
+Este componente no declara slots públicos.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `slider`: El contenedor exterior del slider.
+- `track`: El fondo de la pista.
+- `fill`: La porción llena de la pista.
+- `indicator`: El tooltip de la etiqueta de valor.
+- `control`: Parte interna personalizable.
+- `root`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_end`
+- `--_indicator-gap`
+- `--_start`
+- `--_thumb`
+- `--_track`
+- `--active`
+- `--font`
+- `--inverse-on-surface`
+- `--inverse-primary`
+- `--inverse-surface`
+- `--moni-slider-height`
+- `--outline`
+- `--primary`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `name`
+
+Nombre del input del slider, usado en el envío de formularios.
+
+![moni-slider — name=default](../assets/moni-slider/name--default.png)
+
+### `min`
+
+Valor mínimo del slider.
+
+![moni-slider — min=default](../assets/moni-slider/min--default.png)
+
+### `max`
+
+Valor máximo del slider.
+
+![moni-slider — max=default](../assets/moni-slider/max--default.png)
+
+### `step`
+
+Granularidad del slider. Debe ser un número positivo.
+
+![moni-slider — step=default](../assets/moni-slider/step--default.png)
+
+### `tick-interval`
+
+Anula (overrides) el intervalo predeterminado de las marcas cuando `ticks` es verdadero.
+
+![moni-slider — tick-interval=default](../assets/moni-slider/tickInterval--default.png)
+
+### `inset-icon`
+
+Nombre del icono (Material Symbols) mostrado dentro del control (thumb) del slider.
+
+![moni-slider — inset-icon=default](../assets/moni-slider/insetIcon--default.png)
+
+### `indicator-placement`
+
+Ubicación del tooltip indicador de valor.
+
+![moni-slider — indicator-placement=top](../assets/moni-slider/indicatorPlacement--top.png)
+
+![moni-slider — indicator-placement=bottom](../assets/moni-slider/indicatorPlacement--bottom.png)
+
+### `size`
+
+Grosor/tamaño de la pista y el control (thumb) del slider.
+
+![moni-slider — size=tiny](../assets/moni-slider/size--tiny.png)
+
+![moni-slider — size=small](../assets/moni-slider/size--small.png)
+
+![moni-slider — size=medium](../assets/moni-slider/size--medium.png)
+
+![moni-slider — size=large](../assets/moni-slider/size--large.png)
+
+![moni-slider — size=extra](../assets/moni-slider/size--extra.png)
+
+### `range`
+
+Habilita el modo de rango (dos controles: `value` y `valueEnd`).
+
+![moni-slider — range=false](../assets/moni-slider/range--false.png)
+
+![moni-slider — range=true](../assets/moni-slider/range--true.png)
+
+### `disabled`
+
+Deshabilita el slider.
+
+![moni-slider — disabled=false](../assets/moni-slider/disabled--false.png)
+
+![moni-slider — disabled=true](../assets/moni-slider/disabled--true.png)
+
+### `ticks`
+
+Renderiza marcas (tick marks) a lo largo de la pista en cada intervalo de paso.
+
+![moni-slider — ticks=false](../assets/moni-slider/ticks--false.png)
+
+![moni-slider — ticks=true](../assets/moni-slider/ticks--true.png)
+
+### `indicator`
+
+Muestra un indicador de tooltip mostrando el(los) valor(es) actual(es) mientras se arrastra.
+
+![moni-slider — indicator=false](../assets/moni-slider/indicator--false.png)
+
+![moni-slider — indicator=true](../assets/moni-slider/indicator--true.png)
+
+### `vertical`
+
+Renderiza el slider de forma vertical en lugar de horizontal.
+
+![moni-slider — vertical=false](../assets/moni-slider/isVertical--false.png)
+
+![moni-slider — vertical=true](../assets/moni-slider/isVertical--true.png)

package/docs/components/snackbar.md

@@ -0,0 +1,167 @@
+# Snackbar
+
+Componente Material Design 3 Snackbar (Barra de notificaciones).
+
+Los snackbars proporcionan mensajes breves sobre los procesos de la aplicación en la parte
+inferior de la pantalla. Desaparecen automáticamente y no requieren acción del usuario,
+pero pueden contener una única acción opcional.
+
+**Referencia a la especificación M3:** `m3-docs/components/snackbar/specs.md`
+
+**Modelo de posicionamiento:**
+El snackbar utiliza `position: fixed` para que se renderice en la ventana gráfica (viewport)
+independientemente del elemento en el que esté ubicado en el DOM. El elemento host
+se muestra como `block` en lugar de `contents` para asegurar que `position: fixed`
+dentro del shadow root se ancle a la ventana gráfica (no a un contexto de apilamiento
+creado por un ancestro transformado).
+
+**Mecanismo de mostrar/ocultar:**
+La visibilidad es controlada por `:host([active]) .snackbar` a través de CSS
+`opacity`, `visibility`, y `transform`. Esto imita el patrón `.snackbar.active`
+de BeerCSS y permite animaciones de transición CSS.
+
+**Truncamiento de texto M3:**
+El texto del mensaje se limita a `maxLines` líneas con `-webkit-line-clamp`.
+La especificación M3 requiere un máximo de 2 líneas; los consumidores pueden
+anular esto a través del atributo `max-lines`.
+
+- Tag: `moni-snackbar`
+- Clase: `MoniSnackbar`
+- Fuente: `src/components/moni-snackbar.ts`
+
+## Cuándo usarlo
+
+Usa `moni-snackbar` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```ts
+const snackbar = document.querySelector('moni-snackbar') as MoniSnackbar;
+
+// Mostrar por 3 segundos
+snackbar.text = 'Elemento eliminado';
+snackbar.action = 'Deshacer';
+snackbar.active = true;
+setTimeout(() => { snackbar.active = false; }, 3000);
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-snackbar></moni-snackbar>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-snackbar` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Mantén el estado de apertura en una única fuente de verdad y devuelve el foco al disparador al cerrar.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `text` | `text` | `string` | `''` | El texto del mensaje principal mostrado en el snackbar.  Limitado a `maxLines` líneas. Los mensajes largos se truncan con `…`. Según la especificación M3, mantenga los mensajes cortos e informativos (menos de 60 caracteres). |
+| `action` | `action` | `string` | `''` | Etiqueta para el botón de acción opcional.  Cuando no está vacía, renderiza un botón de texto en el borde posterior (trailing) del snackbar. El componente despacha un evento `'action'` cuando se hace clic en la acción. Esta es una etiqueta puramente visual — el consumidor maneja la lógica de la acción. |
+| `placement` | `placement` | `'bottom' \| 'top'` | `'bottom'` | Ubicación vertical del snackbar en la pantalla.  - `'bottom'` (por defecto) — Fijo a 6rem desde la parte inferior, centrado horizontalmente. - `'top'` — Fijo a 6rem desde la parte superior, centrado horizontalmente. |
+| `active` | `active` | `boolean` | `false` | Cuando es `true`, el snackbar es visible.  Alterne este atributo para mostrar/ocultar el snackbar. La transición CSS maneja la animación de desvanecimiento/deslizamiento hacia arriba (fade-in/slide-up) automáticamente. Los consumidores son responsables de implementar el temporizador de cierre automático. |
+| `max-lines` | `maxLines` | `number` | `2` | Número máximo de líneas del texto del mensaje antes de que sea limitado (clamped).  Utiliza `-webkit-line-clamp` con `display: -webkit-box` para truncamiento multilínea compatible en varios navegadores. La especificación M3 recomienda un máximo de 2 líneas. |
+
+## Slots
+
+- `default`: Contenido adicional colocado dentro del contenedor del snackbar.
+
+## Eventos
+
+- `action`: evento compuesto y burbujeante emitido por el componente.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `snackbar`: Parte interna personalizable.
+- `text`: Parte interna personalizable.
+- `action`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_max-lines`
+- `--elevate2`
+- `--font`
+- `--inverse-on-surface`
+- `--inverse-primary`
+- `--inverse-surface`
+- `--speed2`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `text`
+
+El texto del mensaje principal mostrado en el snackbar.
+
+Limitado a `maxLines` líneas. Los mensajes largos se truncan con `…`.
+Según la especificación M3, mantenga los mensajes cortos e informativos (menos de 60 caracteres).
+
+![moni-snackbar — text=default](../assets/moni-snackbar/text--default.png)
+
+### `action`
+
+Etiqueta para el botón de acción opcional.
+
+Cuando no está vacía, renderiza un botón de texto en el borde posterior (trailing) del snackbar.
+El componente despacha un evento `'action'` cuando se hace clic en la acción.
+Esta es una etiqueta puramente visual — el consumidor maneja la lógica de la acción.
+
+![moni-snackbar — action=default](../assets/moni-snackbar/action--default.png)
+
+### `placement`
+
+Ubicación vertical del snackbar en la pantalla.
+
+- `'bottom'` (por defecto) — Fijo a 6rem desde la parte inferior, centrado horizontalmente.
+- `'top'` — Fijo a 6rem desde la parte superior, centrado horizontalmente.
+
+![moni-snackbar — placement=bottom](../assets/moni-snackbar/placement--bottom.png)
+
+![moni-snackbar — placement=top](../assets/moni-snackbar/placement--top.png)
+
+### `active`
+
+Cuando es `true`, el snackbar es visible.
+
+Alterne este atributo para mostrar/ocultar el snackbar. La transición CSS
+maneja la animación de desvanecimiento/deslizamiento hacia arriba (fade-in/slide-up) automáticamente.
+Los consumidores son responsables de implementar el temporizador de cierre automático.
+
+![moni-snackbar — active=true](../assets/moni-snackbar/active--true.png)
+
+### `max-lines`
+
+Número máximo de líneas del texto del mensaje antes de que sea limitado (clamped).
+
+Utiliza `-webkit-line-clamp` con `display: -webkit-box` para truncamiento multilínea
+compatible en varios navegadores. La especificación M3 recomienda un máximo de 2 líneas.
+
+![moni-snackbar — max-lines=default](../assets/moni-snackbar/maxLines--default.png)