@moni-labs/moni-ui 0.4.4 → 0.4.6

package/docs/components/textarea.md

@@ -0,0 +1,290 @@
+# Textarea
+
+Componente Material Design 3 Textarea (Área de texto).
+
+Un campo de entrada de texto multilínea diseñado para recolectar cantidades mayores de texto,
+como comentarios, descripciones o mensajes.
+
+**Referencia a la especificación M3:** `m3-docs/components/text-fields/specs.md`
+
+**Arquitectura visual:**
+Comparte exactamente el mismo contenedor `.field` y motor de estilos que
+`<moni-text-field>`, pero internamente renderiza un `<textarea>` nativo en lugar
+de un `<input>`. Esto asegura la consistencia visual en todos los elementos del formulario
+en cuanto a etiquetas flotantes, texto de ayuda, estados de error e iconos.
+
+**Contador de caracteres:**
+Si se establece el atributo `maxlength`, el área de texto muestra automáticamente
+un contador de caracteres (`{longitud actual} / {maxlength}`) ubicado en el
+borde final (trailing) del área de texto de soporte (abajo a la derecha). Esto puede
+suprimirse estableciendo el atributo `no-counter`.
+
+**Gestión del estado:**
+Este componente es puramente visual y representacional. Refleja los atributos
+hacia el textarea nativo, pero NO adjunta listeners internos para `@input` o
+`@change`. Los consumidores deben adjuntar listeners estándar del DOM directamente
+a este elemento para capturar la entrada del usuario, tal como lo harían con un
+textarea nativo.
+
+- Tag: `moni-textarea`
+- Clase: `MoniTextarea`
+- Fuente: `src/components/moni-textarea.ts`
+
+## Cuándo usarlo
+
+Usa `moni-textarea` 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
+<!-- Textarea llenado (filled) estándar -->
+<moni-textarea label="Descripción" rows="4"></moni-textarea>
+
+<!-- Textarea contorneado (outlined) con contador de caracteres -->
+<moni-textarea
+  variant="outlined"
+  label="Biografía"
+  maxlength="160"
+></moni-textarea>
+```
+
+## 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-textarea label="Ejemplo"></moni-textarea>
+</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-textarea` 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.
+- En formularios controlados, sincroniza la propiedad `value` y escucha el evento documentado; no dependas solo del atributo inicial.
+- Cuando el control muestre únicamente un icono, añade siempre un `aria-label` descriptivo.
+- 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` | `''` | El nombre del textarea, enviado con los datos del formulario. |
+| `label` | `label` | `string` | `''` | El texto de la etiqueta flotante. |
+| `variant` | `variant` | `'filled' \| 'outlined'` | `'filled'` | Variante visual del área de texto. |
+| `size` | `size` | `'small' \| 'medium' \| 'large' \| 'extra'` | `'medium'` | Define las dimensiones del área de texto. |
+| `shape` | `shape` | `'round' \| 'square' \| 'no-round'` | `'no-round'` | Forma del radio del borde (border-radius) del campo. |
+| `icon` | `icon` | `string` | `''` | Nombre del icono inicial (leading) (Material Symbols). |
+| `trailing-icon` | `trailingIcon` | `string` | `''` | Nombre del icono final (trailing) (Material Symbols). |
+| `prefix` | `prefix` | `string` | `''` | Prefijo de texto corto mostrado antes del valor del input. |
+| `suffix` | `suffix` | `string` | `''` | Sufijo de texto corto mostrado después del valor del input. |
+| `rows` | `rows` | `number` | `3` | Número por defecto de líneas de texto visibles. |
+| `autosize` | `autosize` | `boolean` | `false` | Hace que el textarea crezca y se reduzca según su contenido. |
+| `max-rows` | `maxRows` | `number` | `0` | Número máximo de filas visibles cuando `autosize` está activo. Cero no impone límite. |
+| `maxlength` | `maxlength` | `number \| null` | `null` | Número máximo de caracteres permitidos en el área de texto. También habilita la visualización del contador de caracteres a menos que `noCounter` sea true. |
+| `no-counter` | `noCounter` | `boolean` | `false` | Oculta la visualización del contador de caracteres cuando se establece `maxlength`. |
+| `loading` | `loading` | `boolean` | `false` | Si es true, muestra un indicador de carga (progreso circular) al final. |
+| `disabled` | `disabled` | `boolean` | `false` | Deshabilita el área de texto. |
+| `helper` | `helper` | `string` | `''` | Texto de ayuda mostrado debajo del campo. |
+| `error-text` | `errorText` | `string` | `''` | Texto de error mostrado debajo del campo cuando `error` es true. Sobrescribe el texto de ayuda. |
+| `error` | `error` | `boolean` | `false` | Si es true, establece el campo en un estado de error. |
+| `value` | `value` | `string` | `''` | El valor actual del área de texto. |
+| `placeholder` | `placeholder` | `string` | `''` | Texto de marcador de posición (placeholder) mostrado cuando el textarea está vacío y la etiqueta es flotante. |
+
+## 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
+
+- `field`: Parte interna personalizable.
+- `input`: Parte interna personalizable.
+- `label`: Parte interna personalizable.
+- `helper`: Parte interna personalizable.
+- `counter`: Parte interna personalizable.
+- `footer`: Parte interna personalizable.
+- `leading-icon`: Parte interna personalizable.
+- `prefix`: Parte interna personalizable.
+- `suffix`: Parte interna personalizable.
+- `trailing-icon`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+No consume variables CSS propias.
+
+## 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`
+
+El nombre del textarea, enviado con los datos del formulario.
+
+![moni-textarea — name=default](../assets/moni-textarea/name--default.png)
+
+### `label`
+
+El texto de la etiqueta flotante.
+
+![moni-textarea — label=default](../assets/moni-textarea/label--default.png)
+
+### `variant`
+
+Variante visual del área de texto.
+
+![moni-textarea — variant=filled](../assets/moni-textarea/variant--filled.png)
+
+![moni-textarea — variant=outlined](../assets/moni-textarea/variant--outlined.png)
+
+### `size`
+
+Define las dimensiones del área de texto.
+
+![moni-textarea — size=small](../assets/moni-textarea/size--small.png)
+
+![moni-textarea — size=medium](../assets/moni-textarea/size--medium.png)
+
+![moni-textarea — size=large](../assets/moni-textarea/size--large.png)
+
+![moni-textarea — size=extra](../assets/moni-textarea/size--extra.png)
+
+### `shape`
+
+Forma del radio del borde (border-radius) del campo.
+
+![moni-textarea — shape=round](../assets/moni-textarea/shape--round.png)
+
+![moni-textarea — shape=square](../assets/moni-textarea/shape--square.png)
+
+![moni-textarea — shape=no-round](../assets/moni-textarea/shape--no-round.png)
+
+### `icon`
+
+Nombre del icono inicial (leading) (Material Symbols).
+
+![moni-textarea — icon=default](../assets/moni-textarea/icon--default.png)
+
+### `trailing-icon`
+
+Nombre del icono final (trailing) (Material Symbols).
+
+![moni-textarea — trailing-icon=default](../assets/moni-textarea/trailingIcon--default.png)
+
+### `prefix`
+
+Prefijo de texto corto mostrado antes del valor del input.
+
+![moni-textarea — prefix=default](../assets/moni-textarea/prefix--default.png)
+
+### `suffix`
+
+Sufijo de texto corto mostrado después del valor del input.
+
+![moni-textarea — suffix=default](../assets/moni-textarea/suffix--default.png)
+
+### `rows`
+
+Número por defecto de líneas de texto visibles.
+
+![moni-textarea — rows=default](../assets/moni-textarea/rows--default.png)
+
+### `autosize`
+
+Hace que el textarea crezca y se reduzca según su contenido.
+
+![moni-textarea — autosize=false](../assets/moni-textarea/autosize--false.png)
+
+![moni-textarea — autosize=true](../assets/moni-textarea/autosize--true.png)
+
+### `max-rows`
+
+Número máximo de filas visibles cuando `autosize` está activo. Cero no impone límite.
+
+![moni-textarea — max-rows=default](../assets/moni-textarea/maxRows--default.png)
+
+### `maxlength`
+
+Número máximo de caracteres permitidos en el área de texto.
+También habilita la visualización del contador de caracteres a menos que `noCounter` sea true.
+
+![moni-textarea — maxlength=default](../assets/moni-textarea/maxlength--default.png)
+
+### `no-counter`
+
+Oculta la visualización del contador de caracteres cuando se establece `maxlength`.
+
+![moni-textarea — no-counter=false](../assets/moni-textarea/noCounter--false.png)
+
+![moni-textarea — no-counter=true](../assets/moni-textarea/noCounter--true.png)
+
+### `loading`
+
+Si es true, muestra un indicador de carga (progreso circular) al final.
+
+![moni-textarea — loading=false](../assets/moni-textarea/loading--false.png)
+
+![moni-textarea — loading=true](../assets/moni-textarea/loading--true.png)
+
+### `disabled`
+
+Deshabilita el área de texto.
+
+![moni-textarea — disabled=false](../assets/moni-textarea/disabled--false.png)
+
+![moni-textarea — disabled=true](../assets/moni-textarea/disabled--true.png)
+
+### `helper`
+
+Texto de ayuda mostrado debajo del campo.
+
+![moni-textarea — helper=default](../assets/moni-textarea/helper--default.png)
+
+### `error-text`
+
+Texto de error mostrado debajo del campo cuando `error` es true.
+Sobrescribe el texto de ayuda.
+
+![moni-textarea — error-text=default](../assets/moni-textarea/errorText--default.png)
+
+### `error`
+
+Si es true, establece el campo en un estado de error.
+
+![moni-textarea — error=false](../assets/moni-textarea/error--false.png)
+
+![moni-textarea — error=true](../assets/moni-textarea/error--true.png)
+
+### `value`
+
+El valor actual del área de texto.
+
+![moni-textarea — value=default](../assets/moni-textarea/value--default.png)
+
+### `placeholder`
+
+Texto de marcador de posición (placeholder) mostrado cuando el textarea está vacío y la etiqueta es flotante.
+
+![moni-textarea — placeholder=default](../assets/moni-textarea/placeholder--default.png)

package/docs/components/time-picker.md

@@ -0,0 +1,184 @@
+# Time Picker
+
+Componente Material Design 3 Time Picker (Selector de hora).
+
+Un control altamente interactivo que permite a los usuarios seleccionar una hora específica.
+Proporciona dos modos de entrada distintos:
+1. **Modo dial (analógico):** Una carátula de reloj interactiva donde los usuarios pueden arrastrar o hacer clic
+   para seleccionar horas y minutos.
+2. **Modo input (texto):** Entradas de texto estándar para una introducción precisa por teclado.
+
+**Referencia a la especificación M3:** `m3-docs/components/time-pickers/specs.md`
+
+**Formatos de hora y modos:**
+- La propiedad `value` espera y siempre emite un string en formato de 24 horas
+  (`HH:MM`, ej. `"14:30"`).
+- Establecer `use-24-hour` configura la presentación visual para usar un
+  reloj de 24 horas (anillos interior y exterior) y elimina el selector AM/PM. De lo contrario,
+  utiliza un dial estándar de 12 horas con un selector AM/PM.
+
+**Diseño responsivo:**
+El atributo `orientation` configura el diseño. `vertical` apila la
+visualización de la hora sobre la carátula del reloj, `horizontal` los coloca lado a lado,
+y `auto` responde automáticamente al ancho del contenedor/viewport.
+
+- Tag: `moni-time-picker`
+- Clase: `MoniTimePicker`
+- Fuente: `src/components/moni-time-picker.ts`
+
+## Cuándo usarlo
+
+Usa `moni-time-picker` 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
+<!-- Formato 12 horas (AM/PM) -->
+<moni-time-picker value="14:30"></moni-time-picker>
+
+<!-- Formato 24 horas -->
+<moni-time-picker use-24-hour value="14:30"></moni-time-picker>
+```
+
+## 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-time-picker></moni-time-picker>
+</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-time-picker` 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.
+- En formularios controlados, sincroniza la propiedad `value` y escucha el evento documentado; no dependas solo del atributo inicial.
+- 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 |
+|---|---|---|---|---|
+| `value` | `value` | `string` | `'00:00'` | Valor actual del control; usa la propiedad JavaScript para valores que deban conservar su tipo. |
+| `use-24-hour` | `use24Hour` | `boolean` | `false` | Activa o desactiva el comportamiento `use24Hour`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `mode` | `mode` | `'dial' \| 'input'` | `'dial'` | Selecciona el valor de `mode` entre las opciones documentadas. |
+| `orientation` | `orientation` | `'vertical' \| 'horizontal' \| 'auto'` | `'auto'` | Selecciona el valor de `orientation` entre las opciones documentadas. |
+| `hide-mode-toggle` | `hideModeToggle` | `boolean` | `false` | Activa o desactiva el comportamiento `hideModeToggle`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `hide-headline` | `hideHeadline` | `boolean` | `false` | Activa o desactiva el comportamiento `hideHeadline`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `hour-label` | `hourLabel` | `string` | `'Hora'` | Define `hourLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `minute-label` | `minuteLabel` | `string` | `'Minuto'` | Define `minuteLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+
+## Slots
+
+Este componente no declara slots públicos.
+
+## Eventos
+
+- `change`: evento compuesto y burbujeante emitido por el componente.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+No declara CSS Parts.
+
+## CSS Custom Properties consumidas
+
+- `--_display-size`
+- `--active`
+- `--ease-standard`
+- `--font`
+- `--on-primary`
+- `--on-primary-container`
+- `--on-surface`
+- `--on-surface-variant`
+- `--on-tertiary-container`
+- `--outline`
+- `--primary`
+- `--primary-container`
+- `--speed1`
+- `--speed2`
+- `--speed3`
+- `--surface-container-highest`
+- `--tertiary-container`
+
+## 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.
+
+### `value`
+
+Valor actual del control; usa la propiedad JavaScript para valores que deban conservar su tipo.
+
+![moni-time-picker — value=default](../assets/moni-time-picker/value--default.png)
+
+### `use-24-hour`
+
+Activa o desactiva el comportamiento `use24Hour`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-time-picker — use-24-hour=false](../assets/moni-time-picker/use24Hour--false.png)
+
+![moni-time-picker — use-24-hour=true](../assets/moni-time-picker/use24Hour--true.png)
+
+### `mode`
+
+Selecciona el valor de `mode` entre las opciones documentadas.
+
+![moni-time-picker — mode=dial](../assets/moni-time-picker/mode--dial.png)
+
+![moni-time-picker — mode=input](../assets/moni-time-picker/mode--input.png)
+
+### `orientation`
+
+Selecciona el valor de `orientation` entre las opciones documentadas.
+
+![moni-time-picker — orientation=vertical](../assets/moni-time-picker/orientation--vertical.png)
+
+![moni-time-picker — orientation=horizontal](../assets/moni-time-picker/orientation--horizontal.png)
+
+![moni-time-picker — orientation=auto](../assets/moni-time-picker/orientation--auto.png)
+
+### `hide-mode-toggle`
+
+Activa o desactiva el comportamiento `hideModeToggle`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-time-picker — hide-mode-toggle=false](../assets/moni-time-picker/hideModeToggle--false.png)
+
+![moni-time-picker — hide-mode-toggle=true](../assets/moni-time-picker/hideModeToggle--true.png)
+
+### `hide-headline`
+
+Activa o desactiva el comportamiento `hideHeadline`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-time-picker — hide-headline=false](../assets/moni-time-picker/hideHeadline--false.png)
+
+![moni-time-picker — hide-headline=true](../assets/moni-time-picker/hideHeadline--true.png)
+
+### `hour-label`
+
+Define `hourLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-time-picker — hour-label=default](../assets/moni-time-picker/hourLabel--default.png)
+
+### `minute-label`
+
+Define `minuteLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-time-picker — minute-label=default](../assets/moni-time-picker/minuteLabel--default.png)

package/docs/components/toolbar.md

@@ -0,0 +1,142 @@
+# Toolbar
+
+Componente Material Design 3 Top App Bar (Barra de herramientas superior).
+
+Las barras de aplicación superiores muestran información y acciones en la parte superior de una pantalla.
+Se utilizan para identidad de marca, títulos de pantalla, navegación y acciones.
+
+**Referencia a la especificación M3:** `m3-docs/components/top-app-bar/specs.md`
+
+**Nota:** Esta es la barra de herramientas estándar de nivel superior. Para barras de navegación
+inferiores (a menudo usadas en móviles), usa `<moni-app-bar>`.
+
+**Variantes:**
+- `standard` (por defecto): Una barra de ancho completo (altura de 64dp) que se asienta al ras
+  contra la parte superior de la pantalla.
+- `floating`: Una barra separada con un margen de 4dp y esquinas redondeadas de 8dp,
+  que parece flotar sobre el contenido.
+
+**Comportamiento de desplazamiento (scroll):**
+Cuando el atributo `scroll` está presente, la barra de herramientas responde visualmente al
+desplazamiento aumentando su elevación (sombra) y cambiando dinámicamente
+su color de superficie para indicar profundidad sobre el contenido desplazado.
+
+- Tag: `moni-toolbar`
+- Clase: `MoniToolbar`
+- Fuente: `src/components/moni-toolbar.ts`
+
+## Cuándo usarlo
+
+Usa `moni-toolbar` 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
+<!-- Barra de herramientas estándar con navegación y acciones -->
+<moni-toolbar title="Bandeja de entrada">
+  <moni-icon-button slot="leading" icon="menu"></moni-icon-button>
+  <moni-icon-button slot="trailing" icon="search"></moni-icon-button>
+  <moni-icon-button slot="trailing" icon="more_vert"></moni-icon-button>
+</moni-toolbar>
+
+<!-- Barra de herramientas flotante con un FAB adjunto -->
+<moni-toolbar type="floating" title="Notas">
+  <moni-fab slot="action-button" icon="add"></moni-fab>
+</moni-toolbar>
+```
+
+## 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-toolbar></moni-toolbar>
+</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-toolbar` 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.
+- 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 |
+|---|---|---|---|---|
+| `type` | `type` | `'standard' \| 'floating'` | `'standard'` | Selecciona el valor de `type` entre las opciones documentadas. |
+| `scroll` | `scrolled` | `boolean` | `false` | Activa o desactiva el comportamiento `scrolled`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `title` | `title` | `string` | `''` | Define `title`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+
+## Slots
+
+- `default`: El texto del título o contenido central.
+- `leading`: Icono/botón de navegación colocado en el extremo izquierdo.
+- `trailing`: Iconos/botones de acción colocados en el extremo derecho.
+- `action-button`: Un botón de acción flotante (FAB) anclado al lado derecho.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `container`: Parte interna personalizable.
+- `leading`: Parte interna personalizable.
+- `title`: Parte interna personalizable.
+- `trailing`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--font`
+- `--on-surface`
+- `--shadow1`
+- `--shadow2`
+- `--shadow3`
+- `--speed2`
+- `--surface-container`
+- `--z-index-toolbar`
+
+## 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.
+
+### `type`
+
+Selecciona el valor de `type` entre las opciones documentadas.
+
+![moni-toolbar — type=standard](../assets/moni-toolbar/type--standard.png)
+
+![moni-toolbar — type=floating](../assets/moni-toolbar/type--floating.png)
+
+### `scroll`
+
+Activa o desactiva el comportamiento `scrolled`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-toolbar — scroll=false](../assets/moni-toolbar/scrolled--false.png)
+
+![moni-toolbar — scroll=true](../assets/moni-toolbar/scrolled--true.png)
+
+### `title`
+
+Define `title`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-toolbar — title=default](../assets/moni-toolbar/title--default.png)