desy-html 16.0.3 → 17.0.0

package/docs/sprints/03-combobox-javascript.md

@@ -0,0 +1,589 @@
+# Fase 3: Combobox - JavaScript ARIA
+
+## Deliverables
+
+| Archivo | Accion |
+|---------|--------|
+| `src/js/aria/combobox.js` | Crear |
+
+## Dependencias
+
+- **Fase 1 completada**: Templates HTML con `data-module` attributes
+- **Fase 2 completada**: Estilos CSS disponibles
+
+## PROMPT
+
+```
+Eres un desarrollador JavaScript especializado en accesibilidad web y patrones ARIA. Vas a crear el modulo JS para el componente combobox con autocomplete en desy-html (Design System del Gobierno de Aragon).
+
+## Contexto del proyecto
+
+desy-html usa un patron de prototipos para componentes ARIA (no clases ES6). Cada modulo exporta una funcion que recibe un objeto `aria` y le anade constructores/prototipos. Los componentes se inicializan desde `desy-html.js` buscando elementos `[data-module]`.
+
+## MCP Server DESY
+
+Antes de implementar, consulta las guias del design system:
+1. Usa `mcp__DESY-MCP-Server__get_guideline` para obtener guias de:
+   - Interaccion y teclado en componentes
+   - Patrones ARIA para combobox/listbox
+   - Accesibilidad en formularios
+
+## Skills y agentes disponibles
+
+- Usa la skill `desy` para consultar patrones del design system
+- Usa la skill `ux-designer` para validar decisiones de interaccion
+- Al finalizar, usa los agentes:
+  - `code-simplifier:code-simplifier` para simplificar el codigo
+  - `code-refactoring:code-reviewer` para revisar calidad
+
+## Patron W3C de referencia
+
+Patron WAI-ARIA APG "combobox-autocomplete-both":
+- URL: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+- Keyboard: Arrow Down/Up, Enter, Escape, Home, End, Alt+Down
+- Focus management: aria-activedescendant en el input (no mover focus al listbox)
+- Inline completion (modo "both"): setSelectionRange() para autocompletar texto
+
+## Decisiones de diseno
+
+| Aspecto | Decision |
+|---------|----------|
+| Seleccion | Unica |
+| Autocomplete | 'list' y 'both' (configurable) |
+| Filtrado | Starts-with con normalizacion de acentos |
+| Blur sin match | Limpiar input y hidden value |
+| Posicionamiento popup | createFloatingElement() existente |
+| Scroll pagina | Cierra popup |
+| Foco post-seleccion | Vuelve al input |
+| Eventos custom | combobox:select, combobox:clear, combobox:open, combobox:close |
+| Inline completion | setSelectionRange() nativo (modo "both") |
+| Clear button | Siempre visible cuando hay texto, limpia input + hidden + cierra popup |
+
+## Archivos de referencia
+
+### Patron ARIA con prototipos:
+Archivo: `src/js/aria/listbox.js`
+
+Estructura del modulo:
+```js
+export function listbox(aria) {
+  // Constructor
+  aria.Listbox = function (listboxNode) {
+    this.listboxNode = listboxNode;
+    this.activeDescendant = this.listboxNode.getAttribute('aria-activedescendant');
+    // ...
+    this.registerEvents();
+  };
+
+  // Metodos via prototype
+  aria.Listbox.prototype.registerEvents = function () { ... };
+  aria.Listbox.prototype.focusItem = function (element) { ... };
+  // etc.
+
+  return aria;
+}
+```
+
+Aspectos clave del listbox.js:
+- Usa `aria.KeyCode` para constantes de teclas (UP, DOWN, HOME, END, SPACE, RETURN, ESC)
+- Maneja `aria-activedescendant` para focus visual sin mover focus real
+- Scroll automatico: compara offsetTop/offsetHeight con scrollTop/clientHeight
+- Patron findMatchInRange para busqueda por texto
+
+### createFloatingElement() en desy-html.js:
+Archivo: `src/js/desy-html.js` (linea 509)
+
+```js
+function createFloatingElement(reference, content, options = {}) {
+  // Options relevantes para combobox:
+  // placement: 'bottom-start'
+  // interactive: true
+  // trigger: 'manual'
+  // hideOnClick: true
+  // hideOnEsc: true
+  // hideOnPopperBlur: true
+  // onMount, onShown, onHidden callbacks
+
+  // Retorna API: { show, hide, toggle, update, isShown, destroy }
+}
+```
+
+Ejemplo de uso en listboxComponent (linea 138):
+```js
+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) => { ... }
+});
+```
+
+### Registro de componentes en desy-html.js:
+
+Cada componente exporta una funcion que:
+1. Llama a la funcion del modulo ARIA pasando `aria`
+2. Busca elementos DOM con `querySelectorAll('[data-module="c-xxx"]')`
+3. Inicializa instancias
+
+Ejemplo (listboxComponent, linea 114):
+```js
+export function listboxComponent(aria) {
+  listbox(aria);
+  const modules = document.querySelectorAll('[data-module]');
+  for (const item in modules) if (modules.hasOwnProperty(item)) {
+    const moduleValue = modules[item].getAttribute('data-module');
+    if (moduleValue == 'c-listbox') {
+      // Buscar sub-elementos, crear instancias, registrar eventos
+    }
+  }
+}
+```
+
+## Especificacion tecnica
+
+### Archivo: `src/js/aria/combobox.js`
+
+```js
+export function combobox(aria) {
+  /**
+   * @constructor
+   * @desc Combobox with autocomplete (list/both modes)
+   * @param {HTMLElement} comboboxNode - The wrapper element [data-module="c-combobox"]
+   */
+  aria.Combobox = function (comboboxNode) {
+    this.comboboxNode = comboboxNode;
+    this.input = comboboxNode.querySelector('[data-module="c-combobox-input"]');
+    this.clearButton = comboboxNode.querySelector('[data-module="c-combobox-clear"]');
+    this.hiddenInput = comboboxNode.querySelector('[data-module="c-combobox-hidden"]');
+    this.tooltip = comboboxNode.querySelector('[data-module="c-combobox-tooltip"]');
+    this.listbox = comboboxNode.querySelector('[data-module="c-combobox-list"]');
+    this.noResults = comboboxNode.querySelector('[data-module="c-combobox-no-results"]');
+
+    this.options = [];
+    this.filteredOptions = [];
+    this.activeIndex = -1;
+    this.isOpen = false;
+    this.autocompleteMode = this.input.getAttribute('aria-autocomplete') || 'both';
+    this.floatingInstance = null;
+
+    this.init();
+  };
+
+  // Metodo principal: inicializacion
+  // - Cachear todas las opciones (texto + elemento)
+  // - Registrar eventos de teclado, input, blur, click
+  // - Inicializar floating element
+  // - Configurar clear button
+  // - Configurar scroll listener
+  aria.Combobox.prototype.init = function () { ... };
+
+  // Cachear opciones del DOM
+  aria.Combobox.prototype.cacheOptions = function () {
+    var optionElements = this.listbox.querySelectorAll('[role="option"]');
+    this.options = [];
+    for (var i = 0; i < optionElements.length; i++) {
+      this.options.push({
+        element: optionElements[i],
+        text: optionElements[i].textContent.trim(),
+        normalized: this.normalize(optionElements[i].textContent.trim())
+      });
+    }
+    this.filteredOptions = this.options.slice();
+  };
+
+  // Normalizar texto (quitar acentos para filtrado)
+  aria.Combobox.prototype.normalize = function (str) {
+    return str.normalize('NFD').replace(/[\u0300-\u036f]/g, '').toLowerCase();
+  };
+
+  // Filtrar opciones (starts-with)
+  aria.Combobox.prototype.filterOptions = function (query) {
+    var normalizedQuery = this.normalize(query);
+    this.filteredOptions = [];
+
+    for (var i = 0; i < this.options.length; i++) {
+      if (this.options[i].normalized.indexOf(normalizedQuery) === 0) {
+        this.options[i].element.style.display = '';
+        this.options[i].element.removeAttribute('hidden');
+        this.filteredOptions.push(this.options[i]);
+      } else {
+        this.options[i].element.style.display = 'none';
+        this.options[i].element.setAttribute('hidden', '');
+      }
+    }
+
+    // Mostrar/ocultar mensaje "sin resultados"
+    if (this.filteredOptions.length === 0) {
+      this.noResults.classList.remove('hidden');
+    } else {
+      this.noResults.classList.add('hidden');
+    }
+  };
+
+  // Abrir popup
+  aria.Combobox.prototype.open = function () {
+    if (this.isOpen) return;
+    this.isOpen = true;
+    this.input.setAttribute('aria-expanded', 'true');
+
+    if (this.floatingInstance) {
+      this.floatingInstance.show();
+    } else {
+      this.tooltip.classList.remove('hidden');
+    }
+
+    this.comboboxNode.dispatchEvent(new CustomEvent('combobox:open', { bubbles: true }));
+  };
+
+  // Cerrar popup
+  aria.Combobox.prototype.close = function () {
+    if (!this.isOpen) return;
+    this.isOpen = false;
+    this.activeIndex = -1;
+    this.input.setAttribute('aria-expanded', 'false');
+    this.input.removeAttribute('aria-activedescendant');
+    this.clearActiveDescendant();
+
+    if (this.floatingInstance) {
+      this.floatingInstance.hide();
+    } else {
+      this.tooltip.classList.add('hidden');
+    }
+
+    this.comboboxNode.dispatchEvent(new CustomEvent('combobox:close', { bubbles: true }));
+  };
+
+  // Focus visual en opcion (aria-activedescendant)
+  aria.Combobox.prototype.setActiveDescendant = function (index) {
+    this.clearActiveDescendant();
+
+    if (index < 0 || index >= this.filteredOptions.length) return;
+
+    this.activeIndex = index;
+    var option = this.filteredOptions[index].element;
+    option.classList.add('focused');
+    this.input.setAttribute('aria-activedescendant', option.id);
+
+    // Scroll into view
+    this.scrollOptionIntoView(option);
+  };
+
+  // Limpiar focus visual
+  aria.Combobox.prototype.clearActiveDescendant = function () {
+    var focused = this.listbox.querySelector('.focused');
+    if (focused) {
+      focused.classList.remove('focused');
+    }
+    this.input.removeAttribute('aria-activedescendant');
+  };
+
+  // Scroll opcion visible dentro del listbox
+  aria.Combobox.prototype.scrollOptionIntoView = function (option) {
+    var listboxEl = this.listbox;
+    if (listboxEl.scrollHeight <= listboxEl.clientHeight) return;
+
+    var scrollBottom = listboxEl.clientHeight + listboxEl.scrollTop;
+    var elementBottom = option.offsetTop + option.offsetHeight;
+
+    if (elementBottom > scrollBottom) {
+      listboxEl.scrollTop = elementBottom - listboxEl.clientHeight;
+    } else if (option.offsetTop < listboxEl.scrollTop) {
+      listboxEl.scrollTop = option.offsetTop;
+    }
+  };
+
+  // Seleccionar opcion
+  aria.Combobox.prototype.selectOption = function (index) {
+    if (index < 0 || index >= this.filteredOptions.length) return;
+
+    var option = this.filteredOptions[index];
+
+    // Limpiar seleccion previa
+    for (var i = 0; i < this.options.length; i++) {
+      this.options[i].element.setAttribute('aria-selected', 'false');
+    }
+
+    // Seleccionar nueva opcion
+    option.element.setAttribute('aria-selected', 'true');
+
+    // Actualizar input visible y hidden
+    this.input.value = option.text;
+    this.hiddenInput.value = option.text;
+
+    // Mostrar clear button
+    this.updateClearButton();
+
+    // Cerrar popup
+    this.close();
+
+    // Foco al input
+    this.input.focus();
+
+    // Dispatch evento
+    this.comboboxNode.dispatchEvent(new CustomEvent('combobox:select', {
+      bubbles: true,
+      detail: { value: option.text, element: option.element }
+    }));
+  };
+
+  // Click en opcion
+  aria.Combobox.prototype.handleOptionClick = function (evt) {
+    var optionEl = evt.target.closest('[role="option"]');
+    if (!optionEl) return;
+
+    var index = this.filteredOptions.findIndex(function (opt) {
+      return opt.element === optionEl;
+    });
+
+    if (index >= 0) {
+      this.selectOption(index);
+    }
+  };
+
+  // Input event (filtrando mientras escribe)
+  aria.Combobox.prototype.handleInput = function () {
+    var value = this.input.value;
+
+    this.filterOptions(value);
+    this.updateClearButton();
+
+    if (value.length > 0) {
+      this.open();
+      this.activeIndex = -1;
+
+      // Inline completion (modo "both")
+      if (this.autocompleteMode === 'both' && this.filteredOptions.length > 0) {
+        var firstMatch = this.filteredOptions[0].text;
+        var inputLength = value.length;
+        this.input.value = firstMatch;
+        this.input.setSelectionRange(inputLength, firstMatch.length);
+        this.setActiveDescendant(0);
+      }
+    } else {
+      this.close();
+      this.hiddenInput.value = '';
+    }
+  };
+
+  // Keyboard handler
+  aria.Combobox.prototype.handleKeyDown = function (evt) {
+    var key = evt.key;
+
+    switch (key) {
+      case 'ArrowDown':
+        evt.preventDefault();
+        if (!this.isOpen) {
+          this.filterOptions(this.input.value);
+          this.open();
+        }
+        if (this.activeIndex < this.filteredOptions.length - 1) {
+          this.setActiveDescendant(this.activeIndex + 1);
+        }
+        break;
+
+      case 'ArrowUp':
+        evt.preventDefault();
+        if (!this.isOpen) {
+          this.filterOptions(this.input.value);
+          this.open();
+        }
+        if (this.activeIndex > 0) {
+          this.setActiveDescendant(this.activeIndex - 1);
+        }
+        break;
+
+      case 'Enter':
+        if (this.isOpen && this.activeIndex >= 0) {
+          evt.preventDefault();
+          this.selectOption(this.activeIndex);
+        }
+        break;
+
+      case 'Escape':
+        if (this.isOpen) {
+          evt.preventDefault();
+          this.close();
+          this.input.focus();
+        }
+        break;
+
+      case 'Home':
+        if (this.isOpen && this.filteredOptions.length > 0) {
+          evt.preventDefault();
+          this.setActiveDescendant(0);
+        }
+        break;
+
+      case 'End':
+        if (this.isOpen && this.filteredOptions.length > 0) {
+          evt.preventDefault();
+          this.setActiveDescendant(this.filteredOptions.length - 1);
+        }
+        break;
+
+      default:
+        break;
+    }
+  };
+
+  // Blur handler
+  aria.Combobox.prototype.handleBlur = function () {
+    // Usar setTimeout para permitir clicks en opciones
+    var self = this;
+    setTimeout(function () {
+      if (!self.comboboxNode.contains(document.activeElement)) {
+        // Validar valor: si no coincide con ninguna opcion, limpiar
+        var currentValue = self.input.value.trim();
+        var matchFound = false;
+
+        for (var i = 0; i < self.options.length; i++) {
+          if (self.options[i].text === currentValue) {
+            matchFound = true;
+            break;
+          }
+        }
+
+        if (!matchFound) {
+          self.clearValue();
+        }
+
+        self.close();
+      }
+    }, 200);
+  };
+
+  // Limpiar valor
+  aria.Combobox.prototype.clearValue = function () {
+    this.input.value = '';
+    this.hiddenInput.value = '';
+
+    for (var i = 0; i < this.options.length; i++) {
+      this.options[i].element.setAttribute('aria-selected', 'false');
+    }
+
+    this.updateClearButton();
+    this.comboboxNode.dispatchEvent(new CustomEvent('combobox:clear', { bubbles: true }));
+  };
+
+  // Clear button handler
+  aria.Combobox.prototype.handleClear = function () {
+    this.clearValue();
+    this.close();
+    this.filterOptions('');
+    this.input.focus();
+  };
+
+  // Mostrar/ocultar clear button
+  aria.Combobox.prototype.updateClearButton = function () {
+    if (this.input.value.length > 0) {
+      this.clearButton.removeAttribute('hidden');
+    } else {
+      this.clearButton.setAttribute('hidden', '');
+    }
+  };
+
+  // Scroll de pagina cierra popup
+  aria.Combobox.prototype.handleScroll = function () {
+    if (this.isOpen) {
+      this.close();
+    }
+  };
+
+  return aria;
+}
+```
+
+### Detalle: metodo init completo
+
+```js
+aria.Combobox.prototype.init = function () {
+  this.cacheOptions();
+  this.updateClearButton();
+
+  // Event listeners
+  this.input.addEventListener('input', this.handleInput.bind(this));
+  this.input.addEventListener('keydown', this.handleKeyDown.bind(this));
+  this.input.addEventListener('blur', this.handleBlur.bind(this));
+
+  // Click en opciones
+  this.listbox.addEventListener('click', this.handleOptionClick.bind(this));
+
+  // Prevenir que click en listbox cierre el popup via blur
+  this.listbox.addEventListener('mousedown', function (evt) {
+    evt.preventDefault();
+  });
+
+  // Clear button
+  this.clearButton.addEventListener('click', this.handleClear.bind(this));
+
+  // Scroll cierra popup
+  window.addEventListener('scroll', this.handleScroll.bind(this), true);
+
+  // Si hay valor por defecto, marcar la opcion correspondiente
+  if (this.input.value) {
+    for (var i = 0; i < this.options.length; i++) {
+      if (this.options[i].text === this.input.value) {
+        this.options[i].element.setAttribute('aria-selected', 'true');
+        this.hiddenInput.value = this.input.value;
+        break;
+      }
+    }
+  }
+};
+```
+
+### Notas importantes de implementacion
+
+1. **No usar KeyCode numerico**: El patron listbox.js usa `aria.KeyCode.UP` etc, pero para combobox usar `evt.key` strings ('ArrowDown', 'ArrowUp', etc.) que es mas moderno y legible.
+
+2. **setSelectionRange para inline completion**: Solo en modo "both". Despues de escribir, el input se completa con el primer match y se selecciona la parte autocompletada para que el usuario pueda seguir escribiendo.
+
+3. **mousedown preventDefault en listbox**: Critico para que el click en opciones funcione. Sin esto, el blur del input se dispara antes del click y cierra el popup.
+
+4. **scroll listener con capture**: `window.addEventListener('scroll', handler, true)` con capture para detectar scroll en cualquier contenedor padre.
+
+5. **setTimeout en blur**: Necesario (200ms) para que el click en opciones se procese antes de validar el blur.
+
+6. **createFloatingElement**: Se configurara en la Fase 4 (integracion). El modulo ARIA debe funcionar con fallback (classList toggle) si no hay floating instance.
+
+7. **Normalizacion de acentos**: `str.normalize('NFD').replace(/[\u0300-\u036f]/g, '')` convierte "aragon" y "Aragon" al mismo resultado para filtrado.
+
+## Criterios de aceptacion
+
+- [ ] Archivo `src/js/aria/combobox.js` creado
+- [ ] Exporta funcion `combobox(aria)` que anade `aria.Combobox` constructor
+- [ ] Usa patron de prototipos (consistente con listbox.js)
+- [ ] Constructor recibe el elemento wrapper `[data-module="c-combobox"]`
+- [ ] Localiza sub-elementos via `data-module` queries
+- [ ] **Filtrado**: starts-with con normalizacion de acentos (NFD + regex)
+- [ ] **Modo list**: filtra opciones sin inline completion
+- [ ] **Modo both**: filtra + inline completion con `setSelectionRange()`
+- [ ] **Teclado**:
+  - [ ] ArrowDown: abre popup si cerrado, mueve focus abajo
+  - [ ] ArrowUp: abre popup si cerrado, mueve focus arriba
+  - [ ] Enter: selecciona opcion activa
+  - [ ] Escape: cierra popup, foco al input
+  - [ ] Home: primera opcion filtrada
+  - [ ] End: ultima opcion filtrada
+- [ ] **Focus**: usa `aria-activedescendant` (no mueve focus real del input)
+- [ ] **Scroll into view**: opcion activa siempre visible en el listbox
+- [ ] **Blur sin match**: limpia input y hidden value
+- [ ] **Clear button**: limpia todo, cierra popup, foco al input, dispara combobox:clear
+- [ ] **Clear button visibility**: visible cuando hay texto, hidden cuando vacio
+- [ ] **Seleccion**: actualiza input visible, hidden input, aria-selected, dispara combobox:select
+- [ ] **Post-seleccion**: cierra popup y devuelve foco al input
+- [ ] **Scroll pagina**: cierra popup
+- [ ] **Eventos custom**: combobox:select, combobox:clear, combobox:open, combobox:close con bubbles:true
+- [ ] **Sin resultados**: muestra/oculta mensaje segun filtrado
+- [ ] **Valor por defecto**: si input tiene value, marca la opcion correspondiente
+- [ ] **mousedown preventDefault**: en listbox para evitar blur prematuro
+- [ ] No depende de createFloatingElement (funciona con fallback classList)
+```