@regcheq/ui

Librería interna de componentes UI para aplicaciones Regcheq. Basada en Radix UI + Tailwind CSS v4 + CVA (class-variance-authority), con salida dual CJS + ESM.

Objetivos

• Componentes accesibles y consistentes basados en Radix UI.
• Sistema de tokens semánticos --rq-* para theming centralizado.
• Variantes visuales definidas con CVA — sin clases condicionales ad-hoc.
• Exports con prefijo Rq para evitar colisiones de nombres en los consumidores.
• Build dual (CJS + ESM) para compatibilidad con proyectos Next.js, Vite y CRA.

Instalación

npm i @regcheq/ui

Además, el proyecto usa Tailwind CSS v4. Asegúrate de importar los estilos base en tu app:

import "@regcheq/ui/styles";

Requisitos para desarrollo

El proyecto usa Node 22. Con nvm instalado:

nvm use
npm ci

El archivo .nvmrc fija la versión; nvm use cambia al Node correcto automáticamente.

Husky ejecuta antes de cada commit:

• pre-commit: npm run lint y npm run test (no se permite commit si fallan).
• commit-msg: commitlint para que los mensajes sigan Conventional Commits (ej. feat:, fix:, chore:). Evita commits con mensajes mal formados.

Guía rápida: integrar en tu primera app (React + Vite)

1. Instalar la dependencia

npm i @regcheq/ui

2. Importar estilos base

En el punto de entrada de tu app (ej. src/main.tsx):

import "@regcheq/ui/styles";

3. Envolver la app con RqProvider

RqProvider provee el contexto necesario para componentes como tooltips y popovers de Radix:

// src/main.tsx
import React from "react";
import ReactDOM from "react-dom/client";
import { RqProvider } from "@regcheq/ui";
import "@regcheq/ui/styles";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <RqProvider>
      <App />
    </RqProvider>
  </React.StrictMode>
);

4. Usar componentes

import { RqButton, RqInput, RqAlert } from "@regcheq/ui";

export function LoginForm() {
  return (
    <form>
      <RqAlert variant="info">Ingresa tus credenciales.</RqAlert>
      <RqInput placeholder="Correo electrónico" type="email" />
      <RqButton variant="primary" type="submit">Ingresar</RqButton>
    </form>
  );
}

5. Resumen de pasos

| Paso | Acción | |------|--------| | 1 | npm i @regcheq/ui | | 2 | Importar "@regcheq/ui/styles" en el entry point. | | 3 | Envolver la app con <RqProvider>. | | 4 | Importar y usar los componentes con prefijo Rq. |

Uso básico

import {
  RqButton,
  RqInput,
  RqPasswordInput,
  RqTextarea,
  RqSelect, RqSelectTrigger, RqSelectContent, RqSelectItem, RqSelectValue,
  RqAlert,
  RqCard,
  RqLabel,
  RqSeparator,
  RqCalendar,
  RqDatePickerInput,
  RqSidebar, RqSidebarContent, RqSidebarItem, RqSidebarFooter, RqSidebarToggle,
  RqDrawer, RqDrawerContent, RqDrawerHeader, RqDrawerTitle,
} from "@regcheq/ui";

Componentes disponibles

| Componente | Descripción | |------------|-------------| | RqButton | Botón con variantes primary, secondary, tertiary, ghost | | RqInput | Input de texto base | | RqPasswordInput | Input de contraseña con toggle de visibilidad | | RqTextarea | Área de texto multilínea | | RqLabel | Etiqueta accesible para campos de formulario | | RqSelect + partes | Select accesible basado en Radix Select | | RqPopover + partes | Popover basado en Radix Popover | | RqCalendar | Calendario de selección de fechas (react-day-picker) | | RqDatePickerInput | Input con picker de fecha integrado | | RqAlert | Alerta con variantes info, success, warning, error | | RqCard | Tarjeta contenedora | | RqSeparator | Divisor horizontal/vertical | | RqField + partes | Sistema de layout para campos de formulario | | RqFormField + partes | Integración con react-hook-form | | RqInputGroup + partes | Input con addons (prefijo / sufijo / botón) | | RqSidebar + partes | Sidebar colapsable con hover-expand | | RqDrawer + partes | Drawer (panel deslizante) con soporte multi-dirección | | RqLogo + variantes | Logos y marcas de Regcheq | | RqProvider | Proveedor de contexto global de la librería |

Tokens CSS (theming)

Los componentes usan exclusivamente tokens semánticos --rq-*. Para personalizar el tema, sobreescribe las variables en tu CSS global:

:root {
  --color-rq-brand: hsl(220 70% 30%);
  --color-rq-brand-on: hsl(0 0% 100%);
  --color-rq-brand-hover: hsl(220 70% 25%);
}

Tokens disponibles:

--color-rq-brand              fondo principal
--color-rq-brand-on           texto sobre brand
--color-rq-brand-hover        hover de brand
--color-rq-brand-subtle       fondo suave de brand
--color-rq-surface            fondo de superficie
--color-rq-surface-selected   fondo seleccionado
--color-rq-text               texto principal
--color-rq-border             borde estándar
--color-rq-border-subtle      borde suave
--color-rq-focus              anillo de focus
--color-rq-status-success     / -subtle
--color-rq-status-error       / -subtle
--color-rq-status-warning     / -subtle
--color-rq-status-info        / -subtle
--color-rq-status-notification / -subtle

Versioning (SemVer)

Este paquete sigue SemVer:

• PATCH: fixes internos sin cambios de API.
• MINOR: nuevos componentes o props compatibles.
• MAJOR: cambios que rompen compatibilidad (props eliminadas, renombradas, comportamientos incompatibles).

Commits (Conventional Commits)

El release automático usa Conventional Commits. Ejemplos:

• feat: agrega componente Badge → MINOR
• fix: corrige clases de focus en Input → PATCH
• feat!: renombra prop variant en Alert → MAJOR

O con breaking change explícito:

feat: agrega componente Badge

BREAKING CHANGE: el export RqBadge reemplaza a RqTag (eliminado)

Tipos comunes: feat, fix, chore, docs, refactor, test.

Scripts útiles

npm test              # Jest — todos los tests
npm run test:watch    # Jest en modo watch
npm run test:coverage # Reporte de cobertura
npm run coverage:ci   # Cobertura en formato lcov (para SonarCloud)
npm run typecheck     # tsc --noEmit
npm run lint          # ESLint
npm run lint:fix      # Auto-fix ESLint
npm run format        # Prettier
npm run storybook     # Storybook en localhost:6006
npm run build         # Build de la librería (dist/)

Storybook

El catálogo de componentes se publica automáticamente en GitLab Pages en cada merge a master. Para verlo en local:

npm run storybook

Accede a http://localhost:6006.

Desarrollo de nuevos componentes

Sigue el patrón de la carpeta src/components/ui/<component-name>/:

badge/
├── badge.tsx          ← componente con forwardRef + CVA
├── badge.test.tsx     ← tests co-localizados
└── index.ts           ← barrel local

Registra el nuevo componente en src/components/ui/index.ts con prefijo Rq y crea su story en stories/<component-name>.stories.tsx.

Consulta el archivo CLAUDE.md en la raíz para la guía completa de convenciones.