@wcamaly/lenx-ui

Librería de componentes React para LENX: Atomic Design, Tailwind CSS v4, tokens compartidos, Storybook 9, Vitest y cliente HTTP tipado (createLenxChatApi).

Requisitos

• Node 20+
• React 19
• Tailwind v4 en consumers (preset + CSS publicados)

Instalación

1. Desde el monorepo local (file:)

En frontend / backoffice del repo poc_ai_for_all (hermano de lenx-ui bajo lenx/):

"@wcamaly/lenx-ui": "file:../../lenx-ui"

Luego npm install. Construye la librería antes de consumirla: cd lenx-ui && npm run build.

2. GitLab Package Registry

1. Copia .npmrc.example a .npmrc y reemplaza GITLAB_HOST / PROJECT_ID.
2. Crea un token con read_api + write_package_registry (o usa CI_JOB_TOKEN en CI).
3. Instala: npm install @wcamaly/[email protected]

3. npm link (desarrollo)

cd lenx-ui && npm run build && npm link
cd ../poc_ai_for_all/frontend && npm link @wcamaly/lenx-ui

Estructura de src/

• components/atoms, components/molecules, components/organisms, components/templates, components/charts: Atomic Design; cada componente en su carpeta (Componente.tsx, stories/tests opcionales, index.ts).

Catálogo (0.5.4)

| Capa | Componentes | |------|----------------| | Tokens | palette, typography, spacing (@wcamaly/lenx-ui/tokens) | | Átomos | NavItem, Icon, Button, IconButton, Input, Textarea, Badge, Avatar, Spinner, Divider, Card, Skeleton, PillButton, NotificationBadge | | Moléculas | Pagination, ClarificationCard, ContentPlaceholder, CreateProjectDialog, DropdownMenu, Tabs, FilterChip, ChoiceChip, SearchInput, FormField, EmptyState, InfoCallout, KpiStat, ProgressBar, Breadcrumbs, DialogShell, IconCircle, SkeletonCard, SectionHeader, CardHeader, MenuItem, ButtonGroup, Disclosure, MessageBubble, BackLink, PageHeader, UserTag, EnvironmentBanner | | Organismos | Header, Sidebar, AdminSidebar, CollapsibleSidebar, Board, BlockShell, ThinkingBlock, KpiBlock, ChatComposer, ProjectPeek, AnalyticLauncher, DatasetCard, DataTable, DataTableToolbar, HistoryTimeline, DataSourcesView, shells y hosts de diálogo, etc. | | Templates | Shell, BackofficeShell, AppShell, AdminListTemplate, DetailPageTemplate | | Charts | ChartOutput, MapOutput (@wcamaly/lenx-ui/map + leaflet), FlowCharts, CorrelationMatrix, plan-dag (PlanDagView, StepNode, …) |

• hooks/, contexts/, lib/, types/, api/, utils/, tokens/, styles/, fixtures/: no son capas atómicas; comparten lógica, tipos y datos de prueba.

Storybook

npm run storybook
npm run build-storybook

Las stories usan MSW (msw-storybook-addon) para simular /api/* (layout, proyectos, stream SSE, datasets, sesión). El worker está en .storybook/public/mockServiceWorker.js. Si cambias la ruta del worker, ejecutá npm run storybook:msw-init.

Decorators globales: fuentes (Archivo + Material Icons), reactflow CSS, y providers LenxChatApiProvider + ProjectProvider + NewProjectDialogProvider vía StoryProviders.

Estilos

@import "@wcamaly/lenx-ui/styles.css";

Opcional: preset Tailwind (@wcamaly/lenx-ui/preset) para extender el tema.

Mapas (Leaflet)

MapOutput no se reexporta desde el barrel principal (@wcamaly/lenx-ui) para evitar arrastrar Leaflet al SSR. Usá el subpath y la peer dependency:

npm install leaflet

import { MapOutput } from "@wcamaly/lenx-ui/map";

API de chat (obligatorio para organismos/hooks de datos)

"use client";
import {
  LenxChatApiProvider,
  createLenxChatApi,
  ProjectProvider,
  sessionFetchHeaders,
} from "@wcamaly/lenx-ui";

const chatApi = createLenxChatApi({
  baseUrl: "/api",
  sessionFetchHeaders,
});

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <LenxChatApiProvider api={chatApi}>
      <ProjectProvider>{children}</ProjectProvider>
    </LenxChatApiProvider>
  );
}

Next.js: añade transpilePackages: ["@wcamaly/lenx-ui"] en next.config.

Subpath exports

| Import | Uso | |--------|-----| | @wcamaly/lenx-ui | Barrel principal | | @wcamaly/lenx-ui/hooks | Hooks (useSSEStream, …) | | @wcamaly/lenx-ui/utils | cn, paginación | | @wcamaly/lenx-ui/api | createLenxChatApi, helpers gateway | | @wcamaly/lenx-ui/tokens | Referencias a tokens | | @wcamaly/lenx-ui/preset | Preset Tailwind | | @wcamaly/lenx-ui/styles.css | CSS compilado |

Peer opcionales (gráficos / DAG)

Instala en la app si usas ChartOutput, PlanDagView, etc.: recharts, @nivo/sankey, react-force-graph-2d, reactflow, @dagrejs/dagre.

Release

npm version patch
git push origin main --tags

El job publish de GitLab CI publica en tag v*.*.* (ver .gitlab-ci.yml).

Publicar en npmjs.com (registry público)

Importante: publicar a npmjs.com expone el contenido de dist/ a todo el mundo. Asegurate de (1) tener una licencia válida en LICENSE y package.json, (2) haber revisado que no se filtran secretos ni código interno, y (3) controlar el scope @lenx.

Pre-requisitos (una única vez)

1. Crear cuenta en https://www.npmjs.com/signup y activar 2FA (Account → Two-Factor Authentication → Auth & Publish).
2. Crear la organización lenx en https://www.npmjs.com/org/create (plan Free alcanza para paquetes públicos). Si el nombre lenx ya está tomado por otra persona, hay que cambiar el scope (ej. @lenx-labs/ui) en package.json → name, en los exports consumidos y en los imports de los proyectos que dependen.
3. Elegir licencia. Reemplazar el archivo LICENSE por el texto completo y ajustar package.json → license (ej. "MIT"). Si no querés abrir el código, no publiques público en npmjs.com.
4. Vaciar .npmrc local (o asegurarte de que no haya overrides de scope apuntando a GitLab). El .npmrc.example del repo es para publicar a GitLab, no sirve para npmjs.com.

   rm -f ~/.npmrc .npmrc   # solo si no los usás para otra cosa
   npm login --registry=https://registry.npmjs.org/

Publicar manualmente

# 1. Tests + typecheck + lint en verde
npm run lint && npm run typecheck && npm test

# 2. Build limpio
rm -rf dist && npm run build

# 3. Simular el tarball que se subiría (no publica nada)
npm run pack:check         # alias de: npm pack --dry-run
npm run release:dry        # alias de: npm publish --dry-run --registry=https://registry.npmjs.org/

# 4. Bump de versión (genera commit + tag)
npm version patch          # 0.4.1 → 0.4.2

# 5. Publicar (primera publicación del scope necesita --access public)
npm run release:npm        # alias de: npm publish --access public --registry=https://registry.npmjs.org/

# 6. Empujar el tag al remoto
git push origin main --tags

Automatizar con CI (opcional)

Para publicar desde GitHub Actions / GitLab CI usá un Automation Token de npm (Account → Access Tokens → Generate New Token → Automation) en la variable de entorno NODE_AUTH_TOKEN o NPM_TOKEN, y creá un .npmrc en el job:

echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
npm publish --access public --registry=https://registry.npmjs.org/

Habilitá Trusted Publishing en la pestaña Settings → Trusted Publisher del paquete para evitar tokens de larga vida (recomendado si usás GitHub Actions).

Checklist pre-publicación

• [ ] package.json → name apunta al scope correcto y disponible.
• [ ] package.json → version nunca reutiliza una ya publicada (npm rechaza republicar).
• [ ] package.json → license refleja el archivo LICENSE.
• [ ] package.json → repository / homepage / bugs son URLs accesibles públicamente (o vacíos).
• [ ] npm run pack:check muestra solo dist/, README.md, CHANGELOG.md, LICENSE, package.json.
• [ ] 2FA activo al hacer npm publish.

Documentación Cursor

• Reglas: .cursor/rules/
• Skills: .cursor/skills/