# Plan de mejora y publicación — `@42-components`

> Objetivo: **completar** la librería cerrando los huecos de framework/agente,
> **dogfoodearla** en la landing, **publicarla** en npm bajo el scope `@42`, y
> que la landing la **consuma desde npm** (no desde el link `file:`).

El eje del plan es un **`manifest.json`** como fuente única de verdad. Hoy las
opciones/eventos/markup viven en prosa Markdown y, además, la landing los
**re-codificó a mano** en `src/app/data/catalog/*`. El manifest elimina esa
duplicación: lo consumen los docs, los adaptadores de framework, las plantillas
de markup y el showcase de la landing.

---

## Estado actual (línea base, verificado)

- `@42/core` (controladores vanilla TS) y `@42/styles` (tema CSS) existen y están
  bien documentados para agentes: contrato `HeadlessController`
  (`on/destroy/update?/getState?`), `LLM.md` como router, referencia por categoría
  generada (`pnpm docs:generate`), errores `[42/<name>]`, eventos tipados.
- **No existen** los paquetes `@42/react`, `@42/vue` ni `@42/blade`
  (`Frameworks.mdx` los describe de forma aspiracional).
- La **landing no dogfoodea**: todo su chrome (Navbar, Footer, páginas y hasta el
  propio panel del showcase) usa Radix/shadcn (`src/app/components/ui/*`); `@42`
  solo aparece dentro de las demos.

---

## Fase 0 — Decisiones base y tooling de release

- SemVer + **Changesets** (`@changesets/cli`) para versionar/publicar el monorepo.
- CI (GitHub Actions): en cada PR `pnpm test`, `pnpm lint`, `pnpm build`,
  `pnpm docs:check`, `build-storybook`.
- Paquetes objetivo a publicar: `@42/core`, `@42/styles`, `@42/react`, `@42/vue`,
  `@42/blade`.

**Aceptación:** un PR de prueba pasa todo el CI; `changeset version` correcto en dry-run.

---

## Fase 1 — Completar la librería (cerrar huecos)

### 1.1 `manifest.json` — fuente única de verdad **(P0, linchpin)**
Por componente: `{ id, name, subpath, category, summary, presentational,
options[{name,type,default,description}], events[{name,detail,description}],
methods[], markup (skeleton data-c42-*), dataState[] }`.
- Fuente: `*.types.ts` + frontmatter de `docs/llm/reference/_fragments/*.md`.
- Script `pnpm manifest:generate` + `manifest:check` en CI.
- Export `@42/core/manifest.json`.

**Aceptación:** cubre los 48 componentes; `manifest:check` falla si está desactualizado.

### 1.2 `@42/react` — adaptador **(P0)**
- Hook genérico `useC42(ControllerClass, options, deps)` + `<C42 controller={…}>`
  (formaliza el puente `C42Render` que la landing tuvo que inventar).
- Wrappers tipados por componente, generados desde el manifest (props = options,
  eventos = callbacks `onX`), con `destroy()` en unmount y `update()` reactivo.
- `peerDependencies: react`.

**Aceptación:** `<Accordion multiple onChange={…}>` funciona; SSR-safe.

### 1.3 `@42/vue` — adaptador **(P0)**
- Composable `useC42()` (instancia en `onMounted`, re-crea en cambio de props,
  `destroy()` en `onUnmounted`) + componentes generados desde el manifest.

**Aceptación:** paridad funcional con React.

### 1.4 `@42/blade` — auto-mount **(P1)**
- `mount()` + `MutationObserver` que escanea `[data-c42-*]`, instancia el
  controlador y se re-engancha con DOM de Livewire. `app.refresh()` / `app.unmount()`.
- Alternativa si se descopa: quitar la promesa de `Frameworks.mdx`.

**Aceptación:** una vista Blade con markup `data-c42-*` se hidrata con un `mount()`.

### 1.5 Plantillas de markup exportadas **(P1)**
- Skeleton canónico por componente (desde el manifest) como
  `@42/core/<comp>/template.html` o string.

**Aceptación:** el template de cada componente monta sin lanzar error.

### 1.6 Helper de validación en dev **(P2)**
- `validateMarkup(root)` que liste partes `data-c42-*` faltantes (modo dev).

### 1.7 Regenerar docs desde el manifest **(P2)**
- `docs:generate` sale del manifest, con sección "contrato DOM" consistente
  (selectores que lee / atributos que escribe / métodos / eventos).

---

## Fase 2 — Calidad y blindaje

- Tests de adaptadores (montaje, mapping de eventos, cleanup, reactividad).
- Tests SSR (no tocar DOM en render de servidor).
- Verificación de tree-shaking + presupuesto de tamaño por subpath.
- a11y verde en los wrappers nuevos.

---

## Fase 3 — Publicar en npm

- README/LICENSE/keywords por paquete; revisar `files`, `exports`, `types`,
  `sideEffects`.
- `npm publish --provenance` vía CI al hacer merge de un release de Changesets.
- Empezar con dist-tag `beta`, validar, luego promover a `latest`.

**Aceptación:** `npm i @42/core @42/styles @42/react` en proyecto limpio externo funciona.

---

## Fase 4 — Dogfooding en la landing + consumir desde npm

1. **Dogfood con link local primero** (rápido):
   - Reemplazar presentacionales (Button, Badge, Card, Breadcrumb, Divider,
     Input/Label) por clases `c42-*` en el chrome — sin glue.
   - Migrar chrome interactivo (Tabs del panel, drawer móvil del Navbar, tooltips)
     con `@42/react`.
   - Refactor del showcase: `catalog/*` **consume `manifest.json`** en lugar de
     re-declarar todo a mano (las pestañas HTML/CSS/Code/API se alimentan del manifest).
2. **Switch a npm:** cambiar `"@42/core": "file:../…"` por la versión publicada.
3. **Limpieza:** eliminar `@radix-ui/*` y `ui/*` sin uso; actualizar el README.

**Aceptación:** `npm run build` verde consumiendo `@42` desde npm, sin Radix en el
chrome, showcase alimentado por manifest.

---

## Fase 5 — Mantenimiento

- Extender el checklist "Adding a new component" del `AGENTS.md`: entrada en
  manifest + wrapper React/Vue autogenerado.
- `docs:check` y `manifest:check` en pre-commit/CI.
- Releases con Changesets; la landing se actualiza por PR.

---

## Ruta crítica y paralelización

```
Fase 0 ─▶ 1.1 manifest ─┬▶ 1.2 react ─┐
                        ├▶ 1.3 vue   ─┤
                        └▶ 1.5 templ ─┤
         1.4 blade (paralelo) ────────┼─▶ Fase 2 ─▶ Fase 3 ─▶ Fase 4 ─▶ Fase 5
         landing presentacional ──────┘
```

- El **manifest (1.1)** desbloquea adaptadores, plantillas, docs y el refactor del showcase.
- React/Vue (1.2–1.3) = mayor valor para agentes y para el dogfooding del chrome.
- Publicar (Fase 3) va **después** de dogfoodear con link local.

### Primera ola de ejecución (subagentes en paralelo)

| Stage | Repo / dir | Depende de | Entregable |
| --- | --- | --- | --- |
| `manifest_core` | `packages/core` | — | `manifest.json` + generador + plantillas de markup |
| `blade` | `packages/blade` (nuevo) | — | paquete `@42/blade` (mount + MutationObserver) |
| `landing_presentational` | landing | — | presentacionales con clases `c42-*` en el chrome |
| `react` | `packages/react` (nuevo) | `manifest_core` | paquete `@42/react` |
| `vue` | `packages/vue` (nuevo) | `manifest_core` | paquete `@42/vue` |
| `verify` | monorepo + landing | todas | `pnpm install && build && test` + `npm run build` |

> Nota de ejecución: para evitar carreras sobre `pnpm-lock.yaml`, los stages solo
> **autoran archivos** en sus propios directorios; un único stage `verify`
> centraliza `pnpm install` + build + tests.

## Riesgos

- Wrappers a mano no escalan → se **generan desde el manifest**.
- `@42/blade` es lo más incierto (modelo Livewire); descopear es aceptable.
- SSR en adaptadores: cubrir con tests desde el inicio.

---

## Estado de ejecución — Ola 1 (verificado)

Lanzada con subagentes en paralelo. Resultado tras correcciones:

- ✅ **1.1 manifest** — `packages/core/manifest.json` (48 componentes) + `scripts/generate-manifest.mjs` (`manifest:generate` / `manifest:check`). `manifest:check` → "48 components in sync".
- ✅ **1.2 `@42/react`** — `packages/react/` con `useC42`, `<C42>` y wrappers generados desde el manifest. Build OK (dist 39 kB).
- ✅ **1.3 `@42/vue`** — `packages/vue/` con composable `useC42` y wrappers generados. Build OK (45 módulos, 48 kB).
- ✅ **1.4 `@42/blade`** — `packages/blade/` con `mount()` + `MutationObserver` + `refresh()/unmount()`; registry de 43 controladores; test de montaje (5 tests, verdes).
- ✅ **1.5 plantillas de markup** — incluidas en el campo `markup` del manifest.
- ✅ **Dogfooding landing (parte sin glue)** — Navbar/Footer/Home/ThemeBuilder/ComponentsPage usan `c42-button` / `c42-badge`. `npm run build` → OK.

Gates verde tras correcciones (typecheck 0, build 4 paquetes, 618 tests, manifest en sync):
- Fix `packages/blade/src/registry.ts`: tipo del registry relajado a `HeadlessControllerClass<any, any>` (43 errores TS2322).
- Fix `packages/vue/src/useC42.ts`: param de clase acepta controladores con opciones requeridas (p. ej. `Pagination`).
- Fix `packages/core/command-palette/command-palette.ts`: campo `dialog` sin uso eliminado.

> Nota git: los subagentes de react y vue hicieron commit de su trabajo
> (`feat(react)…`, `feat(vue)…`); manifest, blade y la landing quedaron sin
> commitear, y las correcciones de typecheck también. Pendiente decidir
> estrategia de commit uniforme.

### Pendiente (siguientes olas)
- Fase 0 (Changesets + CI), Fase 2 (tests de adaptadores/SSR + tamaño), Fase 3 (publicar en npm), Fase 4 (migrar chrome interactivo con `@42/react`, refactor del showcase para consumir el manifest, switch a npm, limpiar Radix), items 1.6/1.7.