@regcheq/ui 1.3.0 → 1.4.0

package/README.md

@@ -1,27 +1,255 @@
-# @regcheq/components
+# @regcheq/ui
 
-Libreria de componentes UI de Regcheq.
+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.
 
-## Setup
+
+## 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
 
 ```bash
-pnpm install
+npm i @regcheq/ui
 ```
 
-## Scripts
+Además, el proyecto usa Tailwind CSS v4. Asegúrate de importar los estilos base en tu app:
+
+```ts
+import "@regcheq/ui/styles";
+```
+
+
+## Requisitos para desarrollo
+
+El proyecto usa **Node 22**. Con [nvm](https://github.com/nvm-sh/nvm) instalado:
 
 ```bash
-pnpm build          # Compilar la libreria
-pnpm build:watch    # Compilar en modo watch
-pnpm storybook      # Levantar Storybook en localhost:6006
-pnpm test           # Correr tests
-pnpm lint           # Revisar errores de linting
-pnpm format         # Formatear codigo
-pnpm typecheck      # Verificar tipos
+nvm use
+npm ci
 ```
 
-## Uso
+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](https://www.conventionalcommits.org/) (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
+
+```bash
+npm i @regcheq/ui
+```
+
+### 2. Importar estilos base
+
+En el punto de entrada de tu app (ej. `src/main.tsx`):
+
+```ts
+import "@regcheq/ui/styles";
+```
+
+### 3. Envolver la app con `RqProvider`
+
+`RqProvider` provee el contexto necesario para componentes como tooltips y popovers de Radix:
+
+```tsx
+// 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
+
+```tsx
+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
 
 ```tsx
-import { Button, Input, Calendar, DatePickerInput } from "@regcheq/components";
+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:
+
+```css
+: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
+
+```bash
+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:
+
+```bash
+npm run storybook
+```
+
+Accede a [http://localhost:6006](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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@regcheq/ui",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Componentes reutilizables de Regcheq",
   "author": "Regcheq SpA <admin@regcheq.com>",
   "license": "ISC",