desy-html 16.0.4 → 17.0.1

package/docs/sprints/01-combobox-template.md

@@ -0,0 +1,433 @@
+# Fase 1: Combobox - Nunjucks Templates + ARIA HTML
+
+## Deliverables
+
+Archivos a crear:
+
+| Archivo | Descripcion |
+|---------|-------------|
+| `src/templates/components/combobox/_macro.combobox.njk` | Macro Nunjucks (entry point) |
+| `src/templates/components/combobox/_template.combobox.njk` | Template HTML con ARIA |
+| `src/templates/components/combobox/params.combobox.yaml` | Schema de parametros YAML |
+
+## Dependencias
+
+- Ninguna. Esta es la primera fase.
+
+## PROMPT
+
+```
+Eres un desarrollador frontend especializado en design systems accesibles. Vas a crear el template Nunjucks y schema YAML para un componente combobox con autocomplete en el proyecto desy-html (Design System del Gobierno de Aragon).
+
+## Contexto del proyecto
+
+desy-html es un design system basado en Nunjucks + Tailwind CSS v4. Los componentes siguen un patron consistente:
+- Macro en `_macro.{component}.njk` que incluye el template
+- Template en `_template.{component}.njk` con el HTML
+- Parametros en `params.{component}.yaml` con el schema
+
+## MCP Server DESY
+
+Antes de implementar, consulta las guias del design system usando las herramientas MCP:
+1. Usa `mcp__DESY-MCP-Server__list_categories` para ver categorias disponibles
+2. Usa `mcp__DESY-MCP-Server__get_guideline` para obtener guias de:
+   - Formularios (patrones de form integration)
+   - Accesibilidad (requisitos WCAG 2.2 AA)
+   - Componentes interactivos (patrones ARIA)
+
+## Skills y agentes disponibles
+
+- Usa la skill `desy` para consultar patrones del design system
+- Usa la skill `ux-designer` para decisiones de UX/accesibilidad
+- Al finalizar, usa el agente `code-refactoring:code-reviewer` para revisar calidad del codigo
+
+## Patron W3C de referencia
+
+El componente sigue el patron WAI-ARIA APG "combobox-autocomplete-both":
+- URL: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+- Roles: combobox (input), listbox (popup), option (items)
+- Estados: aria-expanded, aria-activedescendant, aria-selected, aria-autocomplete
+
+## Decisiones de diseno
+
+| Aspecto | Decision |
+|---------|----------|
+| Relacion con existentes | Componente nuevo independiente (no extiende select ni listbox) |
+| Origen de datos | Solo estatico (HTML), sin fetch remoto |
+| Modos autocomplete | 'list' y 'both' (configurable via parametro) |
+| Seleccion | Unica (arquitectura preparada para multiple futura) |
+| Contenido opciones | Solo texto plano |
+| Integracion formulario | Composicion interna con label, hint, error-message |
+| Grupos | Sin soporte de grupos |
+| Form submit | Hidden input nativo para enviar el valor |
+| Clear button | Siempre visible cuando hay texto, en tab order |
+| Toggle button | No incluir (apertura via teclado/escritura) |
+| Sin resultados | Mensaje visible en popup (texto configurable) |
+| Disabled | Solo combobox completo (no opciones individuales) |
+| Valor por defecto | Via parametro del macro |
+| Value/Label | Iguales (el texto visible es el valor enviado) |
+
+## Archivos de referencia existentes
+
+### Patron macro (copiar estructura):
+Archivo: `src/templates/components/select/_macro.select.njk`
+```njk
+{% macro componentSelect(params) %}
+{% include "./_template.select.njk" %}
+{% endmacro %}
+```
+
+### Patron template con form integration (referencia para label/hint/error):
+Archivo: `src/templates/components/select/_template.select.njk`
+
+El select template muestra como:
+1. Importar macros de error-message, hint y label
+2. Construir describedBy para aria-describedby
+3. Envolver en div.c-form-group con clase de error condicional
+4. Renderizar label, hint y errorMessage condicionalmente
+5. Aplicar aria-errorMessage y aria-invalid en estado error
+
+### Patron YAML de parametros (referencia):
+Archivo: `src/templates/components/select/params.select.yaml`
+
+Estructura: array `params` con objetos que tienen name, type, required, description.
+Tipos: string, boolean, array, object. Subcomponentes usan `isComponent: true`.
+
+### Patron listbox template (referencia para opciones y tooltip):
+Archivo: `src/templates/components/listbox/_template.listbox.njk`
+
+El listbox template muestra como:
+1. Generar IDs para opciones con idPrefix
+2. Detectar item activo (aria-selected, aria-activedescendant)
+3. Renderizar items como `<li role="option">` con clases Tailwind
+4. Usar data-module para inicializacion JS
+5. Estructura: contenedor > button trigger > tooltip popup > ul[role=listbox] > li[role=option]
+
+## Especificacion tecnica
+
+### 1. Macro: `_macro.combobox.njk`
+
+```njk
+{% macro componentCombobox(params) %}
+{% include "./_template.combobox.njk" %}
+{% endmacro %}
+```
+
+### 2. Template: `_template.combobox.njk`
+
+Estructura HTML objetivo (patron W3C combobox-autocomplete-both):
+
+```html
+<!-- combobox -->
+<div class="c-form-group [c-form-group--error]" data-module="c-combobox">
+  <label for="{id}" class="...">Label text</label>
+  <!-- hint opcional -->
+  <p id="{id}-hint" class="...">Hint text</p>
+  <!-- error-message opcional -->
+  <p id="{id}-error" class="...">Error text</p>
+
+  <div class="c-combobox relative">
+    <div class="c-combobox__input-wrapper relative flex items-center">
+      <input
+        id="{id}"
+        name="{name}"
+        type="text"
+        role="combobox"
+        aria-autocomplete="{autocomplete}"
+        aria-expanded="false"
+        aria-controls="{id}-listbox"
+        aria-describedby="{describedBy}"
+        aria-errorMessage="{id}-error"
+        aria-invalid="true|false"
+        autocomplete="off"
+        data-module="c-combobox-input"
+        class="c-combobox__input ..."
+        value="{defaultValue}"
+      />
+      <button
+        type="button"
+        tabindex="0"
+        aria-label="{clearButtonLabel}"
+        data-module="c-combobox-clear"
+        class="c-combobox__clear ..."
+        hidden
+      >
+        <!-- SVG icono X -->
+      </button>
+    </div>
+
+    <input type="hidden" name="{name}" value="{defaultValue}" data-module="c-combobox-hidden" />
+
+    <div
+      id="{id}-listbox-container"
+      class="c-combobox__tooltip hidden ..."
+      data-module="c-combobox-tooltip"
+    >
+      <ul
+        id="{id}-listbox"
+        role="listbox"
+        aria-labelledby="{id}-label"
+        data-module="c-combobox-list"
+        class="..."
+      >
+        {% for item in params.items %}
+        <li
+          id="{id}-option-{index}"
+          role="option"
+          aria-selected="false"
+          class="..."
+          data-value="{item.text}"
+        >
+          {item.text}
+        </li>
+        {% endfor %}
+      </ul>
+      <div
+        class="c-combobox__no-results hidden ..."
+        data-module="c-combobox-no-results"
+        role="status"
+        aria-live="polite"
+      >
+        {noResultsText}
+      </div>
+    </div>
+  </div>
+</div>
+<!-- /combobox -->
+```
+
+Notas de implementacion:
+- El input visible es `type="text"` con `role="combobox"` y `autocomplete="off"`
+- El hidden input lleva el `name` para form submission (el input visible NO tiene name para evitar duplicados)
+- `aria-autocomplete` acepta "list" o "both" segun parametro `autocomplete`
+- El boton clear usa `hidden` attribute (JS lo muestra cuando hay texto)
+- El popup usa `hidden` class inicialmente (JS controla visibilidad)
+- `data-module` attributes para que JS localice elementos
+- El input visible NO debe tener atributo `name` (solo el hidden input)
+- `aria-controls` apunta al `id` del `<ul>` listbox
+- Los `<li>` llevan `data-value` con el texto para facilitar el filtrado JS
+
+### 3. Schema YAML: `params.combobox.yaml`
+
+```yaml
+params:
+- name: id
+  type: string
+  required: true
+  description: Unique identifier for the combobox. Used to generate IDs for child elements.
+- name: name
+  type: string
+  required: true
+  description: Name attribute for the hidden input (form submission).
+- name: items
+  type: array
+  required: true
+  description: Array of options for the combobox listbox.
+  params:
+  - name: text
+    type: string
+    required: true
+    description: Text content of the option. Also used as the value.
+  - name: attributes
+    type: object
+    required: false
+    description: HTML attributes to add to the option element.
+- name: autocomplete
+  type: string
+  required: false
+  description: "Autocomplete mode: 'list' (filter only) or 'both' (filter + inline completion). Defaults to 'both'."
+- name: defaultValue
+  type: string
+  required: false
+  description: Pre-selected value for the combobox on initial render.
+- name: noResultsText
+  type: string
+  required: false
+  description: "Text shown when no options match the filter. Defaults to 'No hay resultados'."
+- name: clearButtonLabel
+  type: string
+  required: false
+  description: "Accessible label for the clear button. Defaults to 'Limpiar seleccion'."
+- name: label
+  type: object
+  required: true
+  description: Label text or HTML by specifying value for either text or html keys.
+  isComponent: true
+- name: hint
+  type: object
+  required: false
+  description: Options for the hint component.
+  isComponent: true
+- name: errorMessage
+  type: object
+  required: false
+  description: Options for the error message component. Will not display if falsy.
+  isComponent: true
+- name: formGroup
+  type: object
+  required: false
+  description: Options for the form-group wrapper.
+  params:
+  - name: classes
+    type: string
+    required: false
+    description: Classes to add to the form group.
+- name: disabled
+  type: boolean
+  required: false
+  description: If true, the entire combobox will be disabled.
+- name: classes
+  type: string
+  required: false
+  description: Additional classes to add to the combobox input.
+- name: attributes
+  type: object
+  required: false
+  description: HTML attributes (e.g. data attributes) to add to the combobox wrapper.
+- name: describedBy
+  type: string
+  required: false
+  description: One or more element IDs to add to aria-describedby.
+```
+
+### Template Nunjucks completo a implementar
+
+```njk
+{% from "../error-message/_macro.error-message.njk" import componentErrorMessage -%}
+{% from "../hint/_macro.hint.njk" import componentHint %}
+{% from "../label/_macro.label.njk" import componentLabel %}
+
+{%- set describedBy = params.describedBy if params.describedBy else "" -%}
+{%- set errorId = params.id + '-error' -%}
+{%- set autocompleteMode = params.autocomplete if params.autocomplete else 'both' -%}
+{%- set noResultsMsg = params.noResultsText if params.noResultsText else 'No hay resultados' -%}
+{%- set clearLabel = params.clearButtonLabel if params.clearButtonLabel else 'Limpiar seleccion' -%}
+
+<!-- combobox -->
+<div class="c-form-group {%- if params.errorMessage %} c-form-group--error{% endif %} {%- if params.formGroup.classes %} {{ params.formGroup.classes }}{% endif %}" data-module="c-combobox" {%- for attribute, value in params.attributes %} {{ attribute }}="{{ value }}"{% endfor %}>
+  {{ componentLabel({
+    html: params.label.html,
+    text: params.label.text,
+    classes: params.label.classes,
+    isPageHeading: params.label.isPageHeading,
+    attributes: params.label.attributes,
+    for: params.id
+  }) | indent(2) | trim }}
+{% if params.hint %}
+  {% set hintId = params.id + '-hint' %}
+  {% set describedBy = describedBy + ' ' + hintId if describedBy else hintId %}
+  {{ componentHint({
+    id: hintId,
+    classes: params.hint.classes,
+    attributes: params.hint.attributes,
+    html: params.hint.html,
+    text: params.hint.text
+  }) | indent(2) | trim }}
+{% endif %}
+{% if params.errorMessage %}
+  {% set describedBy = describedBy + ' ' + errorId if describedBy else errorId %}
+  {{ componentErrorMessage({
+    id: errorId,
+    classes: params.errorMessage.classes,
+    attributes: params.errorMessage.attributes,
+    html: params.errorMessage.html,
+    text: params.errorMessage.text,
+    visuallyHiddenText: params.errorMessage.visuallyHiddenText
+  }) | indent(2) | trim }}
+{% endif %}
+  <div class="c-combobox relative">
+    <div class="c-combobox__input-wrapper relative flex items-center">
+      <input
+        id="{{ params.id }}"
+        type="text"
+        role="combobox"
+        aria-autocomplete="{{ autocompleteMode }}"
+        aria-expanded="false"
+        aria-controls="{{ params.id }}-listbox"
+        {%- if describedBy %} aria-describedby="{{ describedBy }}"{% endif %}
+        {%- if params.errorMessage %} aria-errormessage="{{ errorId }}" aria-invalid="true"{% endif %}
+        autocomplete="off"
+        data-module="c-combobox-input"
+        class="c-combobox__input block w-full mt-sm transition duration-150 ease-in-out {% if params.errorMessage %}border-alert-base ring-2 ring-alert-base{% else %}border-black{% endif %} rounded-sm font-semibold focus:border-black focus:shadow-outline-focus-input focus:ring-4 focus:ring-warning-base disabled:bg-neutral-light disabled:border-neutral-base pr-10 {%- if params.classes %} {{ params.classes }}{% endif %}"
+        {%- if params.defaultValue %} value="{{ params.defaultValue }}"{% endif %}
+        {%- if params.disabled %} disabled aria-disabled="true"{% endif %}
+      />
+      <button
+        type="button"
+        tabindex="0"
+        aria-label="{{ clearLabel }}"
+        data-module="c-combobox-clear"
+        class="c-combobox__clear absolute right-2 top-1/2 -translate-y-1/2 p-1 text-neutral-dark hover:text-black focus:outline-hidden focus:bg-warning-base focus:shadow-outline-black rounded-sm"
+        hidden
+      >
+        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" aria-hidden="true" fill="currentColor" focusable="false" width="1em" height="1em"><path d="M39.5 11.383 36.617 8.5 24 21.117 11.383 8.5 8.5 11.383 21.117 24 8.5 36.617 11.383 39.5 24 26.883 36.617 39.5 39.5 36.617 26.883 24z"/></svg>
+      </button>
+    </div>
+
+    <input type="hidden" name="{{ params.name }}" {%- if params.defaultValue %} value="{{ params.defaultValue }}"{% endif %} data-module="c-combobox-hidden" />
+
+    <div
+      id="{{ params.id }}-listbox-container"
+      class="c-combobox__tooltip hidden absolute z-50 min-w-full mt-1 border border-neutral-base shadow-md bg-white rounded-sm"
+      data-module="c-combobox-tooltip"
+    >
+      <ul
+        id="{{ params.id }}-listbox"
+        role="listbox"
+        aria-label="{{ params.label.text if params.label.text else '' }}"
+        data-module="c-combobox-list"
+        class="text-sm outline-hidden max-h-60 overflow-y-auto"
+      >
+      {%- for item in params.items %}
+        {% if item %}
+        <li
+          id="{{ params.id }}-option-{{ loop.index }}"
+          role="option"
+          aria-selected="false"
+          class="c-combobox__option flex items-center px-base py-sm hover:bg-primary-base hover:text-white cursor-pointer"
+          data-value="{{ item.text }}"
+          {%- for attribute, value in item.attributes %} {{ attribute }}="{{ value }}"{% endfor %}
+        >
+          {{ item.text }}
+        </li>
+        {% endif %}
+      {%- endfor %}
+      </ul>
+      <div
+        class="c-combobox__no-results hidden px-base py-sm text-sm text-neutral-dark italic"
+        data-module="c-combobox-no-results"
+        role="status"
+        aria-live="polite"
+      >
+        {{ noResultsMsg }}
+      </div>
+    </div>
+  </div>
+</div>
+<!-- /combobox -->
+```
+
+## Criterios de aceptacion
+
+- [ ] Archivo `_macro.combobox.njk` creado con macro `componentCombobox`
+- [ ] Archivo `_template.combobox.njk` creado con HTML ARIA completo
+- [ ] Archivo `params.combobox.yaml` creado con todos los parametros
+- [ ] El template importa y usa macros de label, hint, error-message
+- [ ] `describedBy` se construye correctamente con hint y error IDs
+- [ ] El input tiene `role="combobox"`, `aria-autocomplete`, `aria-expanded`, `aria-controls`
+- [ ] `aria-autocomplete` es configurable entre "list" y "both" (default: "both")
+- [ ] Hidden input con `name` para form submission
+- [ ] El input visible NO tiene atributo `name`
+- [ ] Boton clear con `hidden` attribute, `aria-label` y en tab order (`tabindex="0"`)
+- [ ] Popup con `role="listbox"` y opciones con `role="option"`
+- [ ] Opciones tienen `aria-selected="false"` por defecto
+- [ ] Opciones tienen `data-value` con el texto
+- [ ] IDs generados consistentemente: `{id}-listbox`, `{id}-option-{n}`
+- [ ] `data-module` attributes en: wrapper (`c-combobox`), input (`c-combobox-input`), clear (`c-combobox-clear`), hidden (`c-combobox-hidden`), tooltip (`c-combobox-tooltip`), list (`c-combobox-list`), no-results (`c-combobox-no-results`)
+- [ ] Zona "sin resultados" con `role="status"` y `aria-live="polite"`
+- [ ] Estado disabled aplicable al combobox completo
+- [ ] Estado error con `aria-invalid`, `aria-errormessage` y clases visuales
+- [ ] Valor por defecto (`defaultValue`) se aplica al input visible y al hidden input
+- [ ] Textos configurables: `noResultsText`, `clearButtonLabel`
+- [ ] El template no genera errores al renderizar con Nunjucks
+```