# Component Roadmap

Estado de los componentes de la librería `@42-components`.

> **Última revisión:** 2026-06-24 — Las prioridades **Alta**, **Media** y **Baja**
> quedaron 100% completadas. 🎉 No quedan componentes pendientes en el roadmap.

## Componentes actuales

### Con controller (40)
Accordion, Dropdown, Modal, Tooltip, Gallery, Stepper, Tags Input, Tree, Image
Viewer, Textarea Emoji, Combobox, Color Picker, Data View, Date Picker, Time
Picker, File Dropzone, Nested Select, **Tabs**, **Toast**, **Drawer**,
**Select**, **Checkbox**, **Switch**, **Radio Group**, **Pagination**,
**Avatar**, **Avatar Group**, **Skeleton**, **Clipboard**, **Alert**,
**Progress**, **Popover**, **Slider**, **Nav**, **Mega Menu**, **Sortable Table**,
**Command Palette**, **Carousel**, **Kanban**, **Rich Text Editor**, **Calendar**,
**Form** _(v2 — Eje B)_

> Checkbox, Switch y Radio Group se exportan desde el módulo `choice`
> (`@42/core/choice`). Avatar Group es un complemento de Avatar. **Form**
> (`@42/core/form`) es el primer entregable de la Expansión v2 (ver más abajo).

### CSS-only (6)
Button, Badge, Card, Divider, Input/Label, Breadcrumb

---

## Prioridad Alta — COMPLETADA ✅

| Componente | Estado | Módulo |
|---|---|---|
| Tabs | ✅ Hecho | `@42/core/tabs` |
| Toast / Notification | ✅ Hecho | `@42/core/toast` |
| Drawer / Sheet | ✅ Hecho | `@42/core/drawer` |
| Select | ✅ Hecho | `@42/core/select` |
| Checkbox / Radio / Switch | ✅ Hecho | `@42/core/choice` |
| Pagination | ✅ Hecho | `@42/core/pagination` |
| Avatar | ✅ Hecho | `@42/core/avatar` (+ `avatar-group`) |
| Skeleton / Loading | ✅ Hecho | `@42/core/skeleton` |

Cada uno incluye controller, tests (Vitest + jsdom), CSS funcional en core y
CSS temático en `@42/styles`.

---

## Prioridad Media — COMPLETADA ✅

Implementados en orden de esfuerzo creciente, siguiendo el headless contract de
`AGENTS.md`. Cada uno incluye controller, tests (Vitest + jsdom), CSS funcional
en core, CSS temático en `@42/styles`, story y entrada en `LLM.md`.

| # | Componente | Estado | Módulo |
|---|---|---|---|
| 1 | Clipboard / Copy | ✅ Hecho | `@42/core/clipboard` |
| 2 | Alert / Callout | ✅ Hecho | `@42/core/alert` |
| 3 | Progress | ✅ Hecho | `@42/core/progress` |
| 4 | Popover | ✅ Hecho | `@42/core/popover` |
| 5 | Slider / Range | ✅ Hecho | `@42/core/slider` |
| 6 | Sidebar / Nav | ✅ Hecho | `@42/core/nav` |
| 7 | Mega Menu | ✅ Hecho | `@42/core/mega-menu` |
| 8 | Sortable Table | ✅ Hecho | `@42/core/sortable-table` (doc: `docs/llm/sortable-table.md`) |

---

## Prioridad Baja — COMPLETADA ✅

Implementados siguiendo el headless contract de `AGENTS.md`. Cada uno incluye
controller, tests (Vitest + jsdom), CSS funcional en core, CSS temático en
`@42/styles`, story y entrada en `LLM.md` (+ `docs/llm/<name>.md` para los más
complejos).

| # | Componente | Estado | Módulo |
|---|---|---|---|
| 1 | Command Palette | ✅ Hecho | `@42/core/command-palette` (doc: `docs/llm/command-palette.md`) |
| 2 | Carousel | ✅ Hecho | `@42/core/carousel` |
| 3 | Kanban | ✅ Hecho | `@42/core/kanban` (doc: `docs/llm/kanban.md`) |
| 4 | Rich Text Editor | ✅ Hecho | `@42/core/rich-text-editor` |
| 5 | Calendar (full) | ✅ Hecho | `@42/core/calendar` (doc: `docs/llm/calendar.md`) |

Descripción original de cada uno:

| Componente | Descripción |
|---|---|
| Command Palette | Panel de búsqueda estilo Cmd+K con filtrado, grupos, shortcuts de teclado, acciones |
| Carousel | Slider de contenido con navegación, dots indicadores, autoplay, loop, swipe en mobile |
| Kanban | Board con drag & drop entre columnas, reordenar items dentro de columna |
| Rich Text Editor | Toolbar con acciones de formato + contenteditable. Bold, italic, links, listas |
| Calendar (full) | Vista completa mes/semana/día con eventos posicionados, drag para crear/mover eventos |

---

## Notas

- Todos los componentes deben seguir el headless contract definido en `AGENTS.md`.
- Los de prioridad **Alta** se necesitan en prácticamente cualquier aplicación web. ✅ Completados.
- Los de prioridad **Media** son comunes en apps medianas/grandes o dashboards. ✅ Completados.
- Los de prioridad **Baja** son para casos de uso específicos o apps complejas. ✅ Completados.
- Al cerrar cada componente: `pnpm test && pnpm lint && pnpm build` y actualizar
  `LLM.md` (y `docs/llm/<name>.md` si es complejo, p. ej. Sortable Table o Slider).

---

# Expansión v2 — Capas estratégicas (Eje B)

> Con los 45 componentes del roadmap original completos, el siguiente salto de
> valor **no** es un componente más, sino capas que multiplican lo ya construido:
> un orquestador de formularios, adaptadores de framework y un pase transversal
> de accesibilidad/RTL. Cada entregable se cierra con su propio commit siguiendo
> el flujo de `AGENTS.md`.

## B1 — Form / Field controller (`@42/core/form`) — COMPLETADA ✅

> Implementado en `@42/core/form` con controller, types, CSS funcional, 22 tests
> (Vitest/jsdom), CSS temático en `@42/styles/form.css`, story, entrada en
> `LLM.md` y doc detallado en [`docs/llm/form.md`](llm/form.md).

Orquestador headless de formularios que conecta los inputs existentes (nativos y
los controllers `@42/core` como Select, Choice, Slider, Combobox) con validación,
estados de error y wiring ARIA. Es el entregable de mayor retorno: convierte
piezas sueltas en formularios completos y accesibles sin imponer estilos.

**Alcance**

- Se adhiere a un `<form data-c42-form>` (progressive enhancement) y descubre los
  campos vía `[data-c42-field]`, cada uno con su control (`input`/`select`/
  `textarea` o `[data-c42-field-control]`) identificado por `name`.
- Validadores integrados declarados por atributos: `data-c42-validate="required email"`
  + restricciones `data-c42-minlength|maxlength|min|max|pattern`. Mensajes
  personalizables por `data-c42-error-<rule>` o vía `options.messages`.
- Validadores custom por campo vía `options.validators` (`(value, values) => string | null`).
- Modos de validación: `submit` (default), `blur`, `change`, `input`; re-valida en
  vivo tras el primer intento de envío.
- Wiring ARIA: `aria-invalid`, `aria-describedby` → `[data-c42-field-error]`,
  `data-state="valid|invalid"` en el wrapper. Nunca aplica estilos en JS.
- `preventDefault` del submit nativo; emite `form:submit` (válido, con `values`),
  `form:invalid` (con `errors`), `form:change` y `form:reset`. Enfoca el primer
  campo inválido.
- API: `validate()`, `validateField(name)`, `getValues()`, `setValues()`,
  `setError(name, msg)`, `clearErrors()`, `reset()`, `getState()`, `on()`, `destroy()`.

**Entregables del componente** (mismo flujo que cualquier componente):
controller + types + CSS funcional + tests (Vitest/jsdom) + index, registros en
`vite.config.ts` / `package.json` / `copy-assets.mjs` / `index.ts`, CSS temático
en `@42/styles`, story y entrada en `LLM.md` (+ `docs/llm/form.md`).

## B2 — Adaptadores de framework (`@42/react`, `@42/vue`, `@42/svelte`)

Wrappers finos sobre el contrato `HeadlessController` (`on`/`destroy`/`update?`/
`getState?`). El contrato ya está pensado para esto (ver `shared/controller.ts`),
así que cada adaptador es genérico: monta el controller sobre un `ref`/`element`,
mapea opciones reactivas a `update()` y reenvía los `CustomEvent` como props/emits.

- `@42/react`: hook `useController(factory, options)` + componentes wrapper.
- `@42/vue`: composable `useController` + directiva.
- `@42/svelte`: action `use:controller`.
- Cada paquete: build Vite, tests, y un commit independiente.

## B3 — Auditoría a11y + RTL + reduced-motion

Pase transversal de hardening sobre los componentes existentes:

- Conformidad con WAI-ARIA Authoring Practices por patrón (foco, roles, teclado).
- Soporte RTL en el CSS funcional (usar propiedades lógicas: `inline-start/end`,
  `margin-inline`, etc.).
- Respetar `prefers-reduced-motion` en todas las animaciones.
- Checklist por componente; se puede cerrar en lotes con un commit por lote.

## Orden de ejecución

1. ✅ **B1 Form controller** — Hecho (`@42/core/form`), commit dedicado en `main`.
2. 🔲 **B2 Adaptadores** — un commit por framework. **(siguiente)**
3. 🔲 **B3 Auditoría a11y/RTL** — commits por lote de componentes.

> Al cerrar cada entregable: `pnpm test && pnpm lint && pnpm build`, actualizar
> `LLM.md` y un commit dedicado.