@moni-labs/moni-ui 0.4.3 → 0.4.5

package/docs/components/expansion.md

@@ -0,0 +1,130 @@
+# Expansion
+
+Componente Material Design 3 Expansion panel (Panel de expansión).
+
+Un envoltorio ligero alrededor de los elementos HTML nativos `<details>` y `<summary>`,
+estilizado de acuerdo con las pautas de superficie y elevación de M3.
+Los paneles de expansión contienen flujos de creación y permiten la edición ligera de un elemento.
+
+**Arquitectura visual:**
+El componente renderiza un elemento `<details>` con un `<summary>` que actúa
+como el encabezado expandible. El contenido del slot por defecto se coloca dentro de la
+etiqueta `<details>` (pero fuera del `<summary>`), ocultándose y mostrándose naturalmente
+según el comportamiento nativo. Se añade un icono `expand_more` de M3 mediante un
+pseudo-elemento CSS `::after` que rota cuando el panel está abierto.
+
+**Uso:**
+Establezca el atributo `title` para un encabezado de texto simple, o use el slot `summary`
+para proyectar contenido enriquecido personalizado (como iconos o texto secundario) en el
+área del encabezado.
+
+- Tag: `moni-expansion`
+- Clase: `MoniExpansion`
+- Fuente: `src/components/moni-expansion.ts`
+
+## Cuándo usarlo
+
+Usa `moni-expansion` 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
+<!-- Título de texto simple -->
+<moni-expansion title="Configuración Avanzada">
+  <p>Habilite las características del modo de desarrollador aquí.</p>
+</moni-expansion>
+
+<!-- Contenido de resumen enriquecido a través de slot -->
+<moni-expansion open>
+  <div slot="summary" style="display: flex; gap: 8px;">
+    <moni-icon>person</moni-icon>
+    <span>Información Personal</span>
+  </div>
+  <form>
+    <moni-text-field label="Nombre"></moni-text-field>
+  </form>
+</moni-expansion>
+```
+
+## 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-expansion></moni-expansion>
+</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-expansion` 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. |
+| `title` | `title` | `string` | `''` | Define `title`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+
+## Slots
+
+- `default`: El contenido del cuerpo del panel de expansión.
+- `summary`: Contenido personalizado del encabezado (sobrescribe el atributo `title`).
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `body`: Parte interna personalizable.
+- `expansion`: Parte interna personalizable.
+- `summary`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--font`
+- `--font-icon`
+- `--on-surface`
+- `--speed2`
+- `--surface-container`
+- `--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-expansion — open=false](../assets/moni-expansion/open--false.png)
+
+![moni-expansion — open=true](../assets/moni-expansion/open--true.png)
+
+### `title`
+
+Define `title`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-expansion — title=default](../assets/moni-expansion/title--default.png)

package/docs/components/fab-menu.md

@@ -0,0 +1,162 @@
+# Fab Menu
+
+Accessible Material 3 Expressive FAB menu / speed dial.
+
+- Tag: `moni-fab-menu`
+- Clase: `MoniFabMenu`
+- Fuente: `src/components/moni-fab-menu.ts`
+
+## Cuándo usarlo
+
+Usa `moni-fab-menu` 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
+<moni-fab-menu></moni-fab-menu>
+```
+
+## 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-fab-menu label="Ejemplo"></moni-fab-menu>
+</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-fab-menu` 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.
+- Cuando el control muestre únicamente un icono, añade siempre un `aria-label` descriptivo.
+- 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. |
+| `disabled` | `disabled` | `boolean` | `false` | Impide la interacción y aplica el estado visual deshabilitado. |
+| `icon` | `icon` | `string` | `'add'` | Nombre de Material Symbol mostrado por el componente. |
+| `close-icon` | `closeIcon` | `string` | `'close'` | Define `closeIcon`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `label` | `label` | `string` | `'Abrir acciones'` | Etiqueta visible y accesible del control. |
+| `close-label` | `closeLabel` | `string` | `'Cerrar acciones'` | Define `closeLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `size` | `size` | `MoniFabSize` | `'medium'` | Selecciona uno de los tamaños visuales admitidos. |
+| `color` | `color` | `MoniFabColor` | `'primary'` | Define `color`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `shape` | `shape` | `'rounded' \| 'circle'` | `'rounded'` | Selecciona el valor de `shape` entre las opciones documentadas. |
+| `direction` | `direction` | `FabMenuDirection` | `'up'` | Define `direction`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `position` | `position` | `MoniFabPosition` | `''` | Define `position`. 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
+
+- `moni-toggle`: evento compuesto y burbujeante emitido por el componente.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `menu`: Parte interna personalizable.
+- `trigger`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_fab-menu-index`
+
+## 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-fab-menu — open=false](../assets/moni-fab-menu/open--false.png)
+
+![moni-fab-menu — open=true](../assets/moni-fab-menu/open--true.png)
+
+### `disabled`
+
+Impide la interacción y aplica el estado visual deshabilitado.
+
+![moni-fab-menu — disabled=false](../assets/moni-fab-menu/disabled--false.png)
+
+![moni-fab-menu — disabled=true](../assets/moni-fab-menu/disabled--true.png)
+
+### `icon`
+
+Nombre de Material Symbol mostrado por el componente.
+
+![moni-fab-menu — icon=default](../assets/moni-fab-menu/icon--default.png)
+
+### `close-icon`
+
+Define `closeIcon`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab-menu — close-icon=default](../assets/moni-fab-menu/closeIcon--default.png)
+
+### `label`
+
+Etiqueta visible y accesible del control.
+
+![moni-fab-menu — label=default](../assets/moni-fab-menu/label--default.png)
+
+### `close-label`
+
+Define `closeLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab-menu — close-label=default](../assets/moni-fab-menu/closeLabel--default.png)
+
+### `size`
+
+Selecciona uno de los tamaños visuales admitidos.
+
+![moni-fab-menu — size=default](../assets/moni-fab-menu/size--default.png)
+
+### `color`
+
+Define `color`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab-menu — color=default](../assets/moni-fab-menu/color--default.png)
+
+### `shape`
+
+Selecciona el valor de `shape` entre las opciones documentadas.
+
+![moni-fab-menu — shape=rounded](../assets/moni-fab-menu/shape--rounded.png)
+
+![moni-fab-menu — shape=circle](../assets/moni-fab-menu/shape--circle.png)
+
+### `direction`
+
+Define `direction`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab-menu — direction=default](../assets/moni-fab-menu/direction--default.png)
+
+### `position`
+
+Define `position`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab-menu — position=default](../assets/moni-fab-menu/position--default.png)

package/docs/components/fab.md

@@ -0,0 +1,202 @@
+# Fab
+
+Material 3 Expressive floating action button.
+
+- Tag: `moni-fab`
+- Clase: `MoniFab`
+- Fuente: `src/components/moni-fab.ts`
+
+## Cuándo usarlo
+
+Usa `moni-fab` 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
+<moni-fab></moni-fab>
+```
+
+## 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-fab label="Ejemplo"></moni-fab>
+</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-fab` 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 |
+|---|---|---|---|---|
+| `size` | `size` | `MoniFabSize` | `'medium'` | Selecciona uno de los tamaños visuales admitidos. |
+| `color` | `color` | `MoniFabColor` | `'primary'` | Define `color`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `shape` | `shape` | `'rounded' \| 'circle'` | `'rounded'` | Selecciona el valor de `shape` entre las opciones documentadas. |
+| `extended` | `extended` | `boolean` | `false` | Activa o desactiva el comportamiento `extended`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `expanded` | `expanded` | `boolean` | `false` | Activa o desactiva el comportamiento `expanded`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `disabled` | `disabled` | `boolean` | `false` | Impide la interacción y aplica el estado visual deshabilitado. |
+| `icon` | `icon` | `string` | `'add'` | Nombre de Material Symbol mostrado por el componente. |
+| `label` | `label` | `string` | `''` | Etiqueta visible y accesible del control. |
+| `aria-label` | `accessibleLabel` | `string` | `''` | Define `accessibleLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `type` | `type` | `'button' \| 'submit' \| 'reset'` | `'button'` | Selecciona el valor de `type` entre las opciones documentadas. |
+| `name` | `name` | `string` | `''` | Nombre enviado junto al valor cuando participa en un formulario. |
+| `value` | `value` | `string` | `''` | Valor actual del control; usa la propiedad JavaScript para valores que deban conservar su tipo. |
+| `position` | `position` | `MoniFabPosition` | `''` | Define `position`. 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
+
+No declara eventos propios.
+
+## Métodos públicos
+
+- `override focus(options?: FocusOptions)` — Método público focus.
+
+## CSS Parts
+
+- `button`: Parte interna personalizable.
+- `fab`: Parte interna personalizable.
+- `icon`: Parte interna personalizable.
+- `label`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_container`
+- `--_content`
+- `--_icon-size`
+- `--_padding`
+- `--_pressed-radius`
+- `--_radius`
+- `--_size`
+- `--elevate1`
+- `--elevate2`
+- `--elevate3`
+- `--font`
+- `--on-primary-container`
+- `--on-secondary-container`
+- `--on-tertiary-container`
+- `--primary`
+- `--primary-container`
+- `--secondary-container`
+- `--surface-container-high`
+- `--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.
+
+### `size`
+
+Selecciona uno de los tamaños visuales admitidos.
+
+![moni-fab — size=default](../assets/moni-fab/size--default.png)
+
+### `color`
+
+Define `color`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab — color=default](../assets/moni-fab/color--default.png)
+
+### `shape`
+
+Selecciona el valor de `shape` entre las opciones documentadas.
+
+![moni-fab — shape=rounded](../assets/moni-fab/shape--rounded.png)
+
+![moni-fab — shape=circle](../assets/moni-fab/shape--circle.png)
+
+### `extended`
+
+Activa o desactiva el comportamiento `extended`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-fab — extended=false](../assets/moni-fab/extended--false.png)
+
+![moni-fab — extended=true](../assets/moni-fab/extended--true.png)
+
+### `expanded`
+
+Activa o desactiva el comportamiento `expanded`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-fab — expanded=false](../assets/moni-fab/expanded--false.png)
+
+![moni-fab — expanded=true](../assets/moni-fab/expanded--true.png)
+
+### `disabled`
+
+Impide la interacción y aplica el estado visual deshabilitado.
+
+![moni-fab — disabled=false](../assets/moni-fab/disabled--false.png)
+
+![moni-fab — disabled=true](../assets/moni-fab/disabled--true.png)
+
+### `icon`
+
+Nombre de Material Symbol mostrado por el componente.
+
+![moni-fab — icon=default](../assets/moni-fab/icon--default.png)
+
+### `label`
+
+Etiqueta visible y accesible del control.
+
+![moni-fab — label=default](../assets/moni-fab/label--default.png)
+
+### `aria-label`
+
+Define `accessibleLabel`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab — aria-label=default](../assets/moni-fab/accessibleLabel--default.png)
+
+### `type`
+
+Selecciona el valor de `type` entre las opciones documentadas.
+
+![moni-fab — type=button](../assets/moni-fab/type--button.png)
+
+![moni-fab — type=submit](../assets/moni-fab/type--submit.png)
+
+![moni-fab — type=reset](../assets/moni-fab/type--reset.png)
+
+### `name`
+
+Nombre enviado junto al valor cuando participa en un formulario.
+
+![moni-fab — name=default](../assets/moni-fab/name--default.png)
+
+### `value`
+
+Valor actual del control; usa la propiedad JavaScript para valores que deban conservar su tipo.
+
+![moni-fab — value=default](../assets/moni-fab/value--default.png)
+
+### `position`
+
+Define `position`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-fab — position=default](../assets/moni-fab/position--default.png)