@moni-labs/moni-ui 0.4.4 → 0.4.5

package/docs/LLM-GUIDE.md

@@ -0,0 +1,107 @@
+# Guía para LLM y agentes
+
+Esta guía define cómo generar código correcto con `@moni-labs/moni-ui`.
+
+## Fuentes de verdad
+
+Consulta en este orden:
+
+1. `docs/api.json`: inventario estructurado de componentes y API pública.
+2. `docs/components/<nombre>.md`: semántica, ejemplos y referencia visual.
+3. `custom-elements.json`: integración con IDE y tooling Web Components.
+4. `src/components/<tag>.ts`: fuente solo cuando la documentación no resuelva un detalle.
+
+No inventes atributos. Si una opción no aparece en `api.json`, no asumas que existe.
+
+## Instalación con bundler
+
+```bash
+npm install @moni-labs/moni-ui
+```
+
+```js
+import '@moni-labs/moni-ui';
+import '@moni-labs/moni-ui/styles';
+```
+
+## CDN completo
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@moni-labs/moni-ui@0.4.4/dist/browser/moni-ui.min.css">
+<script src="https://cdn.jsdelivr.net/npm/@moni-labs/moni-ui@0.4.4/dist/browser/moni-ui.iife.min.js"></script>
+```
+
+Para cargar pocos componentes, usa `dist/cdn/importmap.json` y los módulos individuales documentados en `examples/import-map.html`.
+
+## Reglas de generación
+
+- Usa tags `moni-*`; no recrees visualmente el componente con HTML genérico.
+- Los booleanos HTML se activan por presencia: usa `disabled`, no `disabled="false"`.
+- En JavaScript asigna propiedades tipadas: `element.disabled = false`.
+- Usa kebab-case para atributos (`use-24-hour`) y camelCase para propiedades (`use24Hour`).
+- Proyecta contenido mediante los slots documentados.
+- Escucha los eventos propios en el elemento y revisa `event.detail` cuando corresponda.
+- Usa CSS Custom Properties para temas y `::part()` únicamente con parts documentados.
+- Incluye `aria-label` en controles icon-only.
+- Respeta `prefers-reduced-motion`; no desactives el comportamiento accesible del componente.
+
+## Tailwind CSS v4
+
+Importa Tailwind y Moni UI una sola vez en la hoja global. El orden permite usar las utilities para el layout sin reemplazar los estilos del componente:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Usa esta regla de decisión al generar una interfaz:
+
+1. Para layout, responsive, separación, ancho y alineación: aplica utilities al contenedor o al tag `moni-*` (`grid`, `gap-4`, `w-full`, `md:grid-cols-2`).
+2. Para color y tema coherentes en toda la aplicación: cambia los design tokens públicos de Moni UI.
+3. Para una pieza interna concreta: usa `::part(nombre)` únicamente si la ficha declara ese CSS Part.
+4. Si la ficha no declara un part o variable, no atravieses el Shadow DOM ni dependas de clases internas.
+
+```html
+<form class="mx-auto grid w-full max-w-xl gap-4 p-6 md:grid-cols-2">
+  <moni-text-field class="md:col-span-2" label="Nombre" required></moni-text-field>
+  <moni-select label="Rol">
+    <moni-select-option value="designer">Diseño</moni-select-option>
+    <moni-select-option value="developer">Desarrollo</moni-select-option>
+  </moni-select>
+  <moni-button class="justify-self-end md:col-span-2" type="submit">Guardar</moni-button>
+</form>
+```
+
+No generes `tailwind.config.js` para una integración v4 básica, no uses `@apply` para clonar componentes Moni y no escribas selectores contra nodos internos del Shadow DOM.
+
+## Ejemplo de composición
+
+```html
+<moni-text-field
+  id="time-field"
+  label="Hora"
+  value="09:30"
+  suffix-button-icon="schedule"
+  suffix-button-label="Elegir hora"
+></moni-text-field>
+
+<moni-button-group variant="standard" selection-required>
+  <moni-button active>Lista</moni-button>
+  <moni-button>Tablero</moni-button>
+</moni-button-group>
+```
+
+```js
+const field = document.querySelector('#time-field');
+field.addEventListener('suffix-click', () => {
+  // Abrir el time picker o morph modal de la aplicación.
+});
+```
+
+## Interpretación de las imágenes
+
+Cada sección “Referencia visual por variable” mantiene todas las demás propiedades en un escenario estable y cambia únicamente la variable indicada. Las imágenes son evidencia del resultado esperado, no una API alternativa. Los valores libres muestran una captura `default`; enums y booleanos muestran cada valor documentado.

package/docs/PUBLISHING.md

@@ -0,0 +1,31 @@
+# Publicación automática
+
+Moni UI valida y publica el paquete desde GitHub Actions.
+
+## Configuración inicial en npm
+
+Esta configuración se realiza una sola vez y evita guardar un `NPM_TOKEN` de larga duración en GitHub:
+
+1. Abre la configuración de `@moni-labs/moni-ui` en npm.
+2. En **Trusted Publisher**, selecciona **GitHub Actions**.
+3. Configura estos valores:
+   - Organization or user: `moni-spa`
+   - Repository: `moni-ui`
+   - Workflow filename: `publish.yml`
+   - Environment: déjalo vacío
+
+## Flujo habitual
+
+1. Actualiza `version` en `package.json` siguiendo SemVer.
+2. Crea el commit y haz push a `main`.
+3. CI ejecuta las pruebas, genera `dist` e inspecciona el paquete.
+4. El workflow de publicación comprueba si la versión ya existe en npm.
+5. Si es nueva, la publica con provenance; si ya existe, finaliza sin error.
+
+Los pull requests nunca publican paquetes. También se puede reintentar una publicación desde **Actions → Publish to npm → Run workflow**.
+
+## Versionado
+
+- Patch (`0.3.2` → `0.3.3`): correcciones compatibles.
+- Minor (`0.3.2` → `0.4.0`): funcionalidades compatibles.
+- Major (`0.3.2` → `1.0.0`): cambios incompatibles.

package/docs/README.md

@@ -0,0 +1,64 @@
+# Documentación de Moni UI
+
+Documentación completa y legible por LLM de 49 componentes.
+
+- [Índice compacto para LLM](./llms.txt)
+- [Guía de uso para LLM y agentes](./LLM-GUIDE.md)
+- [API estructurada](./api.json)
+- [Guía de publicación](./PUBLISHING.md)
+
+## Componentes
+
+- [moni-app-bar](./components/app-bar.md)
+- [moni-badge](./components/badge.md)
+- [moni-bottom-sheet](./components/bottom-sheet.md)
+- [moni-button](./components/button.md)
+- [moni-button-group](./components/button-group.md)
+- [moni-button-segment](./components/button-segment.md)
+- [moni-card](./components/card.md)
+- [moni-carousel](./components/carousel.md)
+- [moni-checkbox](./components/checkbox.md)
+- [moni-chip](./components/chip.md)
+- [moni-color-field](./components/color-field.md)
+- [moni-context-menu](./components/context-menu.md)
+- [moni-dialog](./components/dialog.md)
+- [moni-divider](./components/divider.md)
+- [moni-expansion](./components/expansion.md)
+- [moni-fab](./components/fab.md)
+- [moni-fab-menu](./components/fab-menu.md)
+- [moni-file-field](./components/file-field.md)
+- [moni-icon](./components/icon.md)
+- [moni-list](./components/list.md)
+- [moni-list-item](./components/list-item.md)
+- [moni-loading-indicator](./components/loading-indicator.md)
+- [moni-menu](./components/menu.md)
+- [moni-menu-item](./components/menu-item.md)
+- [moni-morph-modal](./components/morph-modal.md)
+- [moni-nav](./components/nav.md)
+- [moni-nav-item](./components/nav-item.md)
+- [moni-progress](./components/progress.md)
+- [moni-radio](./components/radio.md)
+- [moni-ripple](./components/ripple.md)
+- [moni-segmented-button](./components/segmented-button.md)
+- [moni-select](./components/select.md)
+- [moni-select-option](./components/select-option.md)
+- [moni-shape](./components/shape.md)
+- [moni-side-sheet](./components/side-sheet.md)
+- [moni-slider](./components/slider.md)
+- [moni-snackbar](./components/snackbar.md)
+- [moni-split-button](./components/split-button.md)
+- [moni-step](./components/step.md)
+- [moni-stepper](./components/stepper.md)
+- [moni-switch](./components/switch.md)
+- [moni-tab](./components/tab.md)
+- [moni-tabs](./components/tabs.md)
+- [moni-text-field](./components/text-field.md)
+- [moni-textarea](./components/textarea.md)
+- [moni-time-picker](./components/time-picker.md)
+- [moni-toolbar](./components/toolbar.md)
+- [moni-tooltip](./components/tooltip.md)
+- [moni-typography](./components/typography.md)
+
+## Regeneración
+
+`npm run docs:all` actualiza API, Markdown y capturas visuales.