LitForge Design System

LitForge es un set de componentes Web Components basados en Lit para construir aplicaciones internas y dashboards rápidamente. El repositorio organiza cada componente como un paquete npm independiente para que puedas consumir solo lo que necesitas.

Requisitos y herramientas recomendadas

• Node.js 20+
• pnpm 10+ (el workspace usa packageManager: [email protected]). Instala pnpm via Corepack (corepack enable pnpm) para respetar las versiones.
• Si prefieres npm/yarn puedes usarlos, pero la recomendación es pnpm para reproducibilidad.

Scripts disponibles (root)

| Script | Descripción | |--------------------|-----------------------------------------------------------------------------| | pnpm storybook | Levanta Storybook para visualizar y testear los componentes. | | pnpm build-storybook | Genera el build estático de Storybook. | | pnpm deploy | Script interactivo (node) que pregunta la versión, controla si se incluyen los src/, ejecuta pnpm -r build y opcionalmente pnpm -r publish. |

Cada paquete tiene sus propios scripts (build, build:watch, typecheck, clean) definidos en su package.json. Todos usan tsup para generar dist/ (CJS+ESM) y tipos .d.ts.

Cómo trabajar en el proyecto

1. Instala dependencias (idealmente con pnpm):

   pnpm install

2. Reconstruye todos los paquetes tras editar código:

   pnpm -r build

3. Usa Storybook para revisar los componentes:

   pnpm storybook

4. Para publicar nuevas versiones, ejecuta el script pnpm deploy, sigue los prompts y revisa los paquetes en npm.

Componentes disponibles

Auth / Login Form

• @litforge/login-form: formulario de login completo. Depende internamente de:
  • @litforge/email-input
  • @litforge/password-input
  • @litforge/loading-button
  • @litforge/logo-img
• Expone un evento login-submit y props tipadas (LoginFormProps).

Inputs

• @litforge/email-input: input estilizado con helper/error. Evento email-change.
• @litforge/password-input: input de contraseña con toggle (prop revealToggle, evento change).

Buttons

• @litforge/loading-button: botón con spinner integrado (loading-button-click).

Images

• @litforge/logo-img: contenedor para logos (props para bordes, sombras, slots).

KPI / Cards

• @litforge/kpi-card: carta resumen con delta, unidad, estado (KpiCardProps).

Menús

• @litforge/menu-item: representa cada item. Soporta spaMode para decidir si renderiza <a> o <button>.
• @litforge/vertical-menu: menú completo con toggle, slots, y se alimenta de una lista items: VerticalMenuItem[]. Internamente usa @litforge/menu-item y @litforge/logo-img.

Tablas

• @litforge/data-table: tabla modular (header, body, toolbar, paginación, etc.). Exporta sub-componentes (TableHeader, TableRow, etc.) y tipos (TableColumn, TableSortDetail, ...).

Cada paquete expone sus props/eventos tipados a través de src/index.ts y se incluye en los .d.ts generados.

@litforge/tokens (Theme)

Este paquete es diferente al resto: no es un Web Component sino un set de tokens/CSS vars compartidos.

• Exporta el objeto litforgeTokens (tipado con LitforgeTokens) para usar en TS.
• Genera un mapa plano litforgeCssVarMap con todas las variables --lf-*.
• Helpers:
  • litforgeTokensCss: string listo para inyectar usando <style>.
  • createTokensCss(selector, overrides): genera CSS para :root o scopes con overrides tipados (LitforgeTokenOverrides).
  • injectTokensStyle({ selector, overrides, target, styleId }): inserta el CSS en document o en un shadow root.
  • getTokenValue('--lf-color-accent') e isTokenName(value) para validaciones en runtime.

Uso recomendado

import { injectTokensStyle, createTokensCss } from '@litforge/tokens';

// carga tokens base en :root
injectTokensStyle();

// tema custom
const darkThemeCss = createTokensCss(':root', {
  '--lf-color-background': '#0f172a',
  '--lf-color-text': '#f8fafc',
});

document.head.appendChild(Object.assign(document.createElement('style'), { textContent: darkThemeCss }));

De esta forma todos los componentes LitForge leen las mismas variables y los consumidores tienen tipado/auto-complete al personalizar. Continúa extendiendo este README con más ejemplos o enlaces a Storybook conforme crezca la librería.