@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; 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)

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:

npm run dev:docs
npm run dev:stencil

Build de producción

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

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

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

defineCustomElements();

<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.

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”).

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

Docker:

docker compose up --build ui-mcp

Configuración en Cursor (proyecto consumidor):

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

Más detalle: src/mcp/README.md.

Documentación relacionada

| Documento | Contenido | |-----------|-----------| | CHANGELOG.md | Historial de versiones | | handoff.md | Arquitectura del catálogo, comandos, convenciones playgrounds | | src/docs/DESIGN.md | Tipografía, colores, iconos | | src/mcp/README.md | MCP: tools, Docker, variables de entorno | | .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