desy-html 16.0.3 → 17.0.0

package/docs/sprints/04-combobox-integration.md

@@ -0,0 +1,386 @@
+it# Fase 4: Combobox - Integracion y Ejemplos
+
+## Deliverables
+
+| Archivo | Accion |
+|---------|--------|
+| `src/js/desy-html.js` | Modificar (importar combobox, crear comboboxComponent, exportar) |
+| `src/js/index.js` | Modificar (importar y ejecutar comboboxComponent) |
+| `src/templates/components/combobox/_examples.combobox.njk` | Crear |
+
+## Dependencias
+
+- **Fase 1 completada**: Templates Nunjucks
+- **Fase 2 completada**: Estilos CSS (import en styles.css)
+- **Fase 3 completada**: Modulo JS ARIA (`src/js/aria/combobox.js`)
+
+## PROMPT
+
+```
+Eres un desarrollador frontend que va a integrar el componente combobox en desy-html (Design System del Gobierno de Aragon). Las fases previas ya crearon los templates, estilos y JS ARIA. Ahora necesitas registrar el componente en el sistema y crear la pagina de ejemplos.
+
+## Contexto del proyecto
+
+desy-html registra componentes JS en dos archivos:
+1. `src/js/desy-html.js`: Define funciones de componente que importan modulos ARIA, buscan elementos DOM y los inicializan. Tambien contiene `createFloatingElement()` para posicionamiento de popups.
+2. `src/js/index.js`: Importa las funciones de componente y las ejecuta con el objeto `aria`.
+
+Los ejemplos de componentes se crean como archivos Nunjucks `_examples.{component}.njk` dentro de la carpeta del componente.
+
+## MCP Server DESY
+
+Antes de implementar, consulta las guias del design system:
+1. Usa `mcp__DESY-MCP-Server__get_guideline` para obtener guias de:
+   - Patrones de ejemplos de componentes
+   - Integracion de componentes interactivos
+
+## Skills y agentes disponibles
+
+- Usa la skill `desy` para consultar patrones del design system
+- Usa la skill `code-simplifier` para simplificar el codigo de integracion
+- Al finalizar, usa los agentes:
+  - `code-refactoring:code-reviewer` para revisar calidad
+  - Usa la skill `create-commit` para preparar el mensaje de commit
+
+## Archivos de referencia
+
+### Patron de componente en desy-html.js (listboxComponent):
+Archivo: `src/js/desy-html.js`
+
+```js
+// Import (linea 10)
+import { listbox } from './aria/listbox.js';
+
+// Funcion de componente (linea 114)
+export function listboxComponent(aria) {
+  listbox(aria);
+  const modules = document.querySelectorAll('[data-module]');
+  let activeButton;
+  for (const item in modules)
+    if (modules.hasOwnProperty(item)) {
+      const moduleValue = modules[item].getAttribute('data-module');
+
+      if (moduleValue == 'c-listbox') {
+        const buttonListbox = modules[item].querySelector('[data-module = "c-listbox-button"]');
+        const tooltip = modules[item].querySelector('[data-module = "c-listbox-tooltip"]');
+        const list = modules[item].querySelector('[data-module = "c-listbox-list"]');
+
+        if (buttonListbox && tooltip) {
+          const listboxObj = new aria.Listbox(list);
+
+          // Floating element setup
+          const instance = createFloatingElement(buttonListbox, tooltip, {
+            placement: 'bottom-start',
+            offset: [8, -1],
+            middleware: middlewares,
+            interactive: true,
+            trigger: 'manual',
+            hideOnClick: true,
+            role: false,
+            ariaContent: 'auto',
+            hideOnEsc: true,
+            hideOnPopperBlur: true,
+            onMount: (instance) => { ... },
+            onHidden: (instance) => { ... }
+          });
+
+          // Event listeners, etc.
+        }
+      }
+    }
+}
+```
+
+### Patron de registro en index.js:
+Archivo: `src/js/index.js`
+
+```js
+// Import
+import { listboxComponent, ... } from './desy-html.js';
+
+// Ejecucion
+var aria = aria || {};
+listboxComponent(aria);
+```
+
+### createFloatingElement API:
+Definida en `src/js/desy-html.js` (linea 509). Opciones relevantes para combobox:
+- `placement: 'bottom-start'` - alinear popup abajo-izquierda
+- `interactive: true` - permitir interaccion con el popup
+- `trigger: 'manual'` - control programatico (no auto-trigger)
+- `hideOnClick: true` - cerrar al click fuera
+- `hideOnEsc: true` - cerrar con Escape
+- `hideOnPopperBlur: true` - cerrar al perder foco
+- `onHidden: callback` - para sincronizar estado
+- Middleware: `computePosition.shift({ padding: 5 })` para mantener en viewport
+
+## Especificacion tecnica
+
+### 1. Modificar `src/js/desy-html.js`
+
+#### Anadir import (despues de la linea de listbox, orden alfabetico no requerido pero agrupado):
+
+```js
+import { combobox } from './aria/combobox.js';
+```
+
+#### Anadir funcion comboboxComponent (antes de listboxComponent):
+
+```js
+export function comboboxComponent(aria) {
+  combobox(aria);
+
+  const modules = document.querySelectorAll('[data-module="c-combobox"]');
+  [...modules].forEach((module) => {
+    const input = module.querySelector('[data-module="c-combobox-input"]');
+    const tooltip = module.querySelector('[data-module="c-combobox-tooltip"]');
+
+    if (input && tooltip) {
+      // Crear instancia ARIA
+      const comboboxObj = new aria.Combobox(module);
+
+      // Configurar floating element para posicionamiento del popup
+      const inputWrapper = module.querySelector('.c-combobox__input-wrapper');
+
+      const middlewares = [
+        computePosition.shift({ padding: 5 })
+      ];
+
+      // Ajustar ancho del tooltip al input
+      tooltip.style.width = 'auto';
+      tooltip.style.minWidth = inputWrapper.offsetWidth + 'px';
+
+      const instance = createFloatingElement(inputWrapper, tooltip, {
+        placement: 'bottom-start',
+        offset: [0, 4],
+        middleware: middlewares,
+        interactive: true,
+        trigger: 'manual',
+        hideOnClick: true,
+        role: false,
+        ariaContent: 'auto',
+        hideOnEsc: false, // Lo maneja el JS del combobox
+        hideOnPopperBlur: false, // Lo maneja el JS del combobox
+        onHidden: () => {
+          // Sincronizar estado si floating cierra por click externo
+          if (comboboxObj.isOpen) {
+            comboboxObj.isOpen = false;
+            comboboxObj.activeIndex = -1;
+            input.setAttribute('aria-expanded', 'false');
+            input.removeAttribute('aria-activedescendant');
+            comboboxObj.clearActiveDescendant();
+            module.dispatchEvent(new CustomEvent('combobox:close', { bubbles: true }));
+          }
+        }
+      });
+
+      // Asignar floating instance al combobox para que use show/hide
+      comboboxObj.floatingInstance = instance;
+    }
+  });
+}
+```
+
+### 2. Modificar `src/js/index.js`
+
+#### Anadir import:
+
+```js
+import {
+  accordionComponent,
+  alertComponent,
+  checkBoxComponent,
+  collapsibleComponent,
+  comboboxComponent,  // <-- NUEVO
+  DatepickerComponent,
+  // ... resto igual
+} from './desy-html.js';
+```
+
+#### Anadir ejecucion (despues de collapsibleComponent, orden alfabetico):
+
+```js
+var aria = aria || {};
+
+accordionComponent(aria);
+alertComponent(aria);
+collapsibleComponent(aria);
+comboboxComponent(aria);  // <-- NUEVO
+dialogComponent(aria);
+// ... resto igual
+```
+
+### 3. Crear `_examples.combobox.njk`
+
+```njk
+{% from "./combobox/_macro.combobox.njk" import componentCombobox %}
+
+{# Ejemplo 1: Basico con autocomplete "both" #}
+<h2>Combobox basico (autocomplete both)</h2>
+{{ componentCombobox({
+  id: "combobox-comunidad",
+  name: "comunidad",
+  label: {
+    text: "Comunidad Autonoma"
+  },
+  items: [
+    { text: "Andalucia" },
+    { text: "Aragon" },
+    { text: "Asturias" },
+    { text: "Baleares" },
+    { text: "Canarias" },
+    { text: "Cantabria" },
+    { text: "Castilla y Leon" },
+    { text: "Castilla-La Mancha" },
+    { text: "Cataluna" },
+    { text: "Comunidad Valenciana" },
+    { text: "Extremadura" },
+    { text: "Galicia" },
+    { text: "La Rioja" },
+    { text: "Madrid" },
+    { text: "Murcia" },
+    { text: "Navarra" },
+    { text: "Pais Vasco" }
+  ]
+}) }}
+
+{# Ejemplo 2: Con hint y autocomplete "list" #}
+<h2>Combobox con hint (autocomplete list)</h2>
+{{ componentCombobox({
+  id: "combobox-provincia",
+  name: "provincia",
+  autocomplete: "list",
+  label: {
+    text: "Provincia"
+  },
+  hint: {
+    text: "Escribe para filtrar las provincias disponibles"
+  },
+  items: [
+    { text: "Huesca" },
+    { text: "Teruel" },
+    { text: "Zaragoza" }
+  ]
+}) }}
+
+{# Ejemplo 3: Con valor por defecto #}
+<h2>Combobox con valor por defecto</h2>
+{{ componentCombobox({
+  id: "combobox-default",
+  name: "ciudad",
+  defaultValue: "Zaragoza",
+  label: {
+    text: "Ciudad"
+  },
+  items: [
+    { text: "Huesca" },
+    { text: "Jaca" },
+    { text: "Teruel" },
+    { text: "Zaragoza" }
+  ]
+}) }}
+
+{# Ejemplo 4: Con error #}
+<h2>Combobox con error</h2>
+{{ componentCombobox({
+  id: "combobox-error",
+  name: "comarca",
+  label: {
+    text: "Comarca"
+  },
+  errorMessage: {
+    text: "Selecciona una comarca valida"
+  },
+  items: [
+    { text: "Alto Gallego" },
+    { text: "Campo de Borja" },
+    { text: "Cinco Villas" },
+    { text: "Hoya de Huesca" },
+    { text: "La Jacetania" },
+    { text: "Ribera Alta del Ebro" }
+  ]
+}) }}
+
+{# Ejemplo 5: Disabled #}
+<h2>Combobox deshabilitado</h2>
+{{ componentCombobox({
+  id: "combobox-disabled",
+  name: "disabled-field",
+  disabled: true,
+  label: {
+    text: "Campo deshabilitado"
+  },
+  items: [
+    { text: "Opcion 1" },
+    { text: "Opcion 2" }
+  ]
+}) }}
+
+{# Ejemplo 6: Texto de sin resultados personalizado #}
+<h2>Combobox con texto personalizado (sin resultados)</h2>
+{{ componentCombobox({
+  id: "combobox-custom",
+  name: "municipio",
+  noResultsText: "No se encontraron municipios",
+  clearButtonLabel: "Borrar busqueda",
+  label: {
+    text: "Municipio"
+  },
+  hint: {
+    text: "Empieza a escribir el nombre del municipio"
+  },
+  items: [
+    { text: "Alagon" },
+    { text: "Borja" },
+    { text: "Calatayud" },
+    { text: "Ejea de los Caballeros" },
+    { text: "Fraga" },
+    { text: "Huesca" },
+    { text: "Jaca" },
+    { text: "Monzon" },
+    { text: "Tarazona" },
+    { text: "Teruel" },
+    { text: "Utebo" },
+    { text: "Zaragoza" }
+  ]
+}) }}
+```
+
+## Criterios de aceptacion
+
+### Integracion JS
+- [ ] Import de `combobox` anadido en `desy-html.js`
+- [ ] Funcion `comboboxComponent` exportada desde `desy-html.js`
+- [ ] `comboboxComponent` busca `[data-module="c-combobox"]` y crea instancias `aria.Combobox`
+- [ ] `createFloatingElement` configurado con `placement: 'bottom-start'`, `trigger: 'manual'`, `interactive: true`
+- [ ] `hideOnEsc: false` y `hideOnPopperBlur: false` (el JS del combobox gestiona estos)
+- [ ] `onHidden` callback sincroniza estado del combobox cuando floating cierra por click externo
+- [ ] `floatingInstance` asignado al objeto combobox
+- [ ] Ancho del tooltip ajustado al input wrapper
+- [ ] Import y ejecucion anadidos en `index.js` en orden alfabetico
+- [ ] `comboboxComponent(aria)` ejecutado despues de `collapsibleComponent(aria)`
+
+### Pagina de ejemplos
+- [ ] Archivo `_examples.combobox.njk` creado en `src/templates/components/combobox/`
+- [ ] Importa macro `componentCombobox` correctamente
+- [ ] Ejemplo 1: Basico con autocomplete "both" (default) - comunidades autonomas
+- [ ] Ejemplo 2: Con hint y autocomplete "list" - provincias
+- [ ] Ejemplo 3: Con valor por defecto (`defaultValue`) - ciudades
+- [ ] Ejemplo 4: Con estado error (`errorMessage`) - comarcas
+- [ ] Ejemplo 5: Deshabilitado (`disabled: true`)
+- [ ] Ejemplo 6: Textos personalizados (`noResultsText`, `clearButtonLabel`) - municipios
+- [ ] Todos los ejemplos usan datos relevantes del contexto aragones
+- [ ] Cada ejemplo muestra un caso de uso diferente del componente
+
+### Verificacion integral
+- [ ] El proyecto compila sin errores (`npm run build` o equivalente)
+- [ ] El combobox renderiza correctamente en el navegador
+- [ ] El filtrado funciona al escribir
+- [ ] Las teclas de navegacion funcionan (Arrow, Enter, Escape, Home, End)
+- [ ] El clear button aparece/desaparece y funciona correctamente
+- [ ] El popup se posiciona correctamente con floating-ui
+- [ ] El blur sin match limpia el input
+- [ ] El valor seleccionado se envia correctamente en formularios (hidden input)
+- [ ] Los eventos custom se disparan correctamente
+- [ ] No hay errores en consola
+```

package/docs/sprints/05-combobox-refinamiento-w3c.md

@@ -0,0 +1,55 @@
+# Sprint 05 — Combobox Refinamiento W3C
+
+## Objetivo
+
+Alcanzar fidelidad al patrón W3C WAI-ARIA APG combobox-autocomplete-both corrigiendo 3 diferencias detectadas.
+
+**Referencia**: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-both/
+
+## Cambios realizados
+
+### 1. Botón toggle (▼)
+
+Se añadió un `<button>` con flecha SVG al lado del input que abre/cierra el listbox completo, siguiendo el patrón W3C.
+
+**Archivos modificados:**
+- `src/templates/components/combobox/_template.combobox.njk` — markup del botón
+- `src/templates/components/combobox/params.combobox.yaml` — nuevo param `toggleButtonLabel`
+- `src/templates/components/combobox/_styles.combobox.css` — estilos posición, hover, focus, rotación SVG
+- `src/js/aria/combobox.js` — handler click, sincronización aria-expanded
+- `src/js/desy-html.js` — discovery del toggle node
+
+**Especificación ARIA del botón:**
+- `tabindex="-1"`: fuera del tab order (como W3C)
+- `aria-expanded`: sincronizado con el estado del popup
+- `aria-controls`: apunta al listbox
+- `aria-label`: por defecto usa el texto del label del combobox
+
+**Comportamiento click:**
+- Si cerrado: abre, muestra TODAS las opciones, foco en primera
+- Si abierto: cierra
+- Siempre devuelve foco al input
+
+### 2. Alt+Down corregido
+
+Antes: Alt+Down abría el listbox Y navegaba a la primera opción.
+Ahora: Alt+Down abre el listbox mostrando todas las opciones SIN mover el foco a ninguna opción (comportamiento W3C correcto).
+
+### 3. Dataset ampliado — Comarcas de Aragón
+
+Se añadió un ejemplo con las 33 comarcas de Aragón para demostrar:
+- Filtrado real con muchos items
+- Scroll en el listbox (max-height: 15rem)
+- Valor del autocompletado inline con datos reales
+
+## Verificación
+
+1. `npm run dev` sin errores
+2. Abrir http://localhost:5173/examples-combobox.html
+3. Click en botón toggle: abre listbox con TODAS las opciones
+4. Click de nuevo: cierra
+5. Alt+Down: abre sin mover foco a ninguna opción
+6. Escribir texto: filtra normalmente (toggle sigue visible)
+7. Clear button sigue funcionando
+8. Ejemplo comarcas muestra scroll
+9. aria-expanded sincronizado en input Y botón toggle

package/package.json

@@ -1,58 +1,61 @@
-{
-  "name": "desy-html",
-  "version": "16.0.3",
-  "description": "desy-html contains the code you need to start building a user interface for Gobierno de Aragón government webapps.",
-  "type": "module",
-  "author": {
-    "name": "Desy (SDA Servicios Digitales de Aragón)",
-    "email": "sda@aragon.es"
-  },
-  "keywords": [
-    "desy",
-    "gobierno de aragón",
-    "frontend",
-    "design system",
-    "template"
-  ],
-  "license": "EUPL-1.2",
-  "repository": {
-    "type": "git",
-    "url": "https://bitbucket.org/sdaragon/desy-html.git"
-  },
-  "homepage": "https://desy.aragon.es/",
-  "exports": {
-    "./branding": "./branding/branding.config.js",
-    "./branding/plugin": "./branding/vite-branding-plugin.js"
-  },
-  "engines": {
-    "node": ">=20.19.2 <23.0.0",
-    "npm": ">=10.0.0"
-  },
-  "scripts": {
-    "dev": "vite",
-    "dev:yourorganization": "BRANDING_CONFIG=yourorganization vite",
-    "build": "vite build",
-    "preview": "vite preview"
-  },
-  "dependencies": {
-    "@floating-ui/dom": "^1.6.13",
-    "@tailwindcss/vite": "^4.1.17",
-    "autoprefixer": "^10.4.21",
-    "cally": "^0.8.0",
-    "chokidar": "^3.6.0",
-    "hex-rgb": "^5.0.0",
-    "js-yaml": "^4.1.0",
-    "tailwindcss": "^4.1.17",
-    "@tailwindcss/forms": "^0.5.10",
-    "@tailwindcss/typography": "^0.5.18"
-  },
-  "devDependencies": {
-    "glob": "^11.0.1",
-    "highlight.js": "^11.11.1",
-    "nunjucks": "^3.2.4",
-    "js-beautify": "^1.14.11",
-    "outdent": "^0.8.0",
-    "sharp": "^0.34.3",
-    "vite": "^7.1.6"
-  }
-}
+{
+  "name": "desy-html",
+  "version": "17.0.0",
+  "description": "desy-html contains the code you need to start building a user interface for Gobierno de Aragón government webapps.",
+  "type": "module",
+  "author": {
+    "name": "Desy (SDA Servicios Digitales de Aragón)",
+    "email": "sda@aragon.es"
+  },
+  "keywords": [
+    "desy",
+    "gobierno de aragón",
+    "frontend",
+    "design system",
+    "template"
+  ],
+  "license": "EUPL-1.2",
+  "repository": {
+    "type": "git",
+    "url": "https://bitbucket.org/sdaragon/desy-html.git"
+  },
+  "homepage": "https://desy.aragon.es/",
+  "exports": {
+    "./branding": "./branding/branding.config.js",
+    "./branding/plugin": "./branding/vite-branding-plugin.js"
+  },
+  "engines": {
+    "node": ">=20.19.2 <23.0.0",
+    "npm": ">=10.0.0"
+  },
+  "scripts": {
+    "dev": "vite",
+    "dev:yourorganization": "cross-env BRANDING_CONFIG=yourorganization npm run dev",
+    "build": "vite build",
+    "build:yourorganization": "cross-env BRANDING_CONFIG=yourorganization npm run build",
+    "preview": "vite preview",
+    "preview:yourorganization": "cross-env BRANDING_CONFIG=yourorganization npm run preview"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.6.13",
+    "@tailwindcss/forms": "^0.5.10",
+    "@tailwindcss/typography": "^0.5.18",
+    "@tailwindcss/vite": "^4.1.17",
+    "autoprefixer": "^10.4.21",
+    "cally": "^0.8.0",
+    "chokidar": "^3.6.0",
+    "hex-rgb": "^5.0.0",
+    "js-yaml": "^4.1.0",
+    "tailwindcss": "^4.1.17"
+  },
+  "devDependencies": {
+    "cross-env": "^10.1.0",
+    "glob": "^11.0.1",
+    "highlight.js": "^11.11.1",
+    "js-beautify": "^1.14.11",
+    "nunjucks": "^3.2.4",
+    "outdent": "^0.8.0",
+    "sharp": "^0.34.3",
+    "vite": "^7.1.6"
+  }
+}

package/public/images/demo-icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" width="32" height="32" aria-label="Demo Icon" role="img">
+  <!-- Face circle -->
+  <circle cx="16" cy="16" r="14" fill="none" stroke="currentColor" stroke-width="2"/>
+  <!-- Eyes -->
+  <circle cx="10" cy="12" r="2" fill="currentColor"/>
+  <circle cx="22" cy="12" r="2" fill="currentColor"/>
+  <!-- Smile -->
+  <path d="M10 20 Q16 26 22 20" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"/>
+</svg>