# @pixelpay/ui-core

Biblioteca de **Web Components** (`x-*`) para productos PixelPay: botones, formularios, tablas, layout, iconografía y tokens de diseño. Compilada con [Stencil](https://stenciljs.com/); se consume en cualquier stack (HTML, Vue, React, Laravel+Vite, etc.).

| Paquete npm | `@pixelpay/ui-core` |
| Versión actual | `1.1.0` |
| Prefijo de tags | `x-` (ej. `x-button`, `x-datatable`) |
| Estilos | `dist/style.css` + `@pixelpay/fonts` |

---

## Requisitos

- **Node.js** 18+ (recomendado 20 o 22)
- **npm** 9+

---

## Inicio rápido (desarrollo en este repo)

```bash
npm install
npm start
```

| Servicio | URL | Descripción |
|----------|-----|-------------|
| Catálogo (Vite) | http://localhost:5173 | Demos, props, documentación Stencil |
| Stencil (`www/build`) | servido por Vite en `/build/*` | Custom elements en dev |

`npm start` ejecuta en paralelo `dev:stencil` (watch → `www/build`) y `dev:docs` (catálogo Vite).

Solo catálogo o solo Stencil:

```bash
npm run dev:docs
npm run dev:stencil
```

---

## Build de producción

```bash
npm run build
```

Genera:

- `dist/` — paquete publicable (JS, tipos, loader, `style.css`)
- `docs/` — sitio estático del catálogo (gitignored)

Pasos internos: `build-core` (Stencil) → `build-styles` (Sass) → `build-catalog-docs` (Vite).

---

## Usar la librería en otra aplicación

```bash
npm install @pixelpay/ui-core @pixelpay/fonts
```

```typescript
import { defineCustomElements } from '@pixelpay/ui-core/loader';
import '@pixelpay/ui-core/dist/style.css';
// Cargar CSS de @pixelpay/fonts según DESIGN.md

defineCustomElements();
```

```html
<x-button color="primary">Pagar</x-button>
<x-input label="Correo" type="email"></x-input>
```

Guía visual y tokens: ver sección **Design** en el catálogo o `src/docs/DESIGN.md`.

**Regla para agentes / equipos:** preferir componentes `x-*` documentados antes que HTML suelto u otras UI libs. El servidor MCP (abajo) expone el catálogo para Cursor y otros clientes.

---

## Estructura del repositorio

```
src/
  components/x-*/          # Un folder por componente (component.tsx, style.scss, playground.stories.ts)
  docs/                    # App del catálogo Vite (no es el paquete npm)
  resources/scss/          # Tokens y base.scss → dist/style.css
  utils/builder.ts         # Builder para demos del catálogo
  mcp/                     # Servidor MCP (consumo en otros proyectos)
dist/                      # Salida Stencil + docs-json
www/build/                 # Bundle dev de Stencil (servido por Vite en dev)
.agents/skills/            # Skill para crear nuevos componentes (Cursor)
handoff.md                 # Mapa operativo del catálogo (mantenedores)
```

`src/docs` y `src/mcp` están **excluidos** del compilado Stencil (`tsconfig.json`).

---

## Scripts principales

| Comando | Uso |
|---------|-----|
| `npm start` | Dev: Stencil watch + catálogo |
| `npm run build` | Build completo (lib + catálogo estático) |
| `npm run build-core` | Solo Stencil |
| `npm run build-styles` | Solo `dist/style.css` |
| `npm run dev:docs` | Catálogo en :5173 |
| `npm run dev:stencil` | Stencil watch → `www/build` |
| `npm run sync-catalog-docs` | Fusiona `dist/docs.json` → `src/docs/data.json` |
| `npm run generate` | Scaffold Stencil (`stencil generate`) |
| `npm test` | Tests unitarios y e2e |
| `npm run mcp` | Servidor MCP HTTP en :3100 |
| `npm run mcp:build-manifest` | Regenera catálogo para MCP |
| `npm run security` | Trivy: vulnerabilidades en `package-lock.json` (falla si hay MEDIUM+) |
| `npm run security:report` | Igual que `security` pero sin fallar el exit code |
| `npm run security:json` | Informe JSON → `trivy-report.json` |

Requisitos: binario **trivy** en PATH o **Docker** (`TRIVY_IMAGE`, por defecto `aquasec/trivy:0.70.0`). Config: `trivy.yaml`, excepciones: `.trivyignore`.

---

## Catálogo de componentes

Las demos no usan Storybook. Cada componente tiene `playground.stories.ts`:

- `export default meta` con `category`, `label`, `component` (`CatalogModuleMeta`)
- Variantes: `export const Simple = new Builder(..., { focalTag: 'x-tag' }).args({...}).build()`
- Manifiesto de historias en **runtime** vía `import.meta.glob` (no se versiona `groups` en JSON)

Metadatos Stencil (`props`, `events`, `slots`) viven en `src/docs/data.json`, sincronizados desde `dist/docs.json`.

Detalle de convenciones y plugins Vite: **[handoff.md](./handoff.md)**.

---

## Crear o modificar componentes

1. Carpeta `src/components/x-{nombre}/` con `component.tsx`, `style.scss`, `playground.stories.ts`.
2. JSDoc en **inglés** y `@slot` justo antes de `@Component`.
3. Registrar el tag en `stencil.config.ts` → `bundles`.
4. Probar en catálogo (`npm start`).

Skill de referencia para agentes: **`.agents/skills/pixelpay-ui-component/`**.

Convención de nombres: prefijo **`x-`**, no `stencil-*` (son custom elements estándar).

---

## Servidor MCP

Expone el catálogo para que otros repos integren `x-*` de forma consistente (búsqueda, API, ejemplos, política “PixelPay primero”).

```bash
npm run mcp
# → http://127.0.0.1:3100/mcp  (health: /health)
```

Docker:

```bash
docker compose up --build ui-mcp
```

Configuración en Cursor (proyecto consumidor):

```json
{
  "mcpServers": {
    "pixelpay-ui-core": {
      "url": "http://localhost:3100/mcp"
    }
  }
}
```

Más detalle: **[src/mcp/README.md](./src/mcp/README.md)**.

---

## Documentación relacionada

| Documento | Contenido |
|-----------|-----------|
| [CHANGELOG.md](./CHANGELOG.md) | Historial de versiones |
| [handoff.md](./handoff.md) | Arquitectura del catálogo, comandos, convenciones playgrounds |
| [src/docs/DESIGN.md](./src/docs/DESIGN.md) | Tipografía, colores, iconos |
| [src/mcp/README.md](./src/mcp/README.md) | MCP: tools, Docker, variables de entorno |
| [.agents/skills/pixelpay-ui-component/SKILL.md](./.agents/skills/pixelpay-ui-component/SKILL.md) | Guía para crear componentes nuevos |

---

## Publicación

El paquete npm incluye `dist/`, `loader/`, `components/`, `hydrate/` (ver `package.json` → `files`). El sitio estático `docs/` **no** se publica en npm; es solo artefacto de documentación interna/CI.

`prepublishOnly` ejecuta `npm run build`.

En **Bitbucket Pipelines**, los tags `v*` y los pull requests ejecutan en paralelo **Aqua Trivy** (`trivy.yaml`) y **git-secrets** antes del deploy (tags).

---

## Licencia

MIT