@regcheq/ui-vue-2 1.1.0

package/README.md

@@ -0,0 +1,334 @@
+# regcheq-ui-vue-2
+
+Librería de componentes UI de **RegCheq** para proyectos Vue 2. Documenta y distribuye los componentes del design system oficial, sincronizados directamente desde Figma.
+
+---
+
+## Tabla de contenidos
+
+- [Descripción](#descripción)
+- [Requisitos](#requisitos)
+- [Instalación](#instalación)
+- [Levantar Storybook](#levantar-storybook)
+- [Estructura del proyecto](#estructura-del-proyecto)
+- [Design Tokens](#design-tokens)
+  - [Colores](#colores)
+  - [Tipografía](#tipografía)
+  - [Elevaciones](#elevaciones)
+- [Crear un componente](#crear-un-componente)
+  - [Patrón CVA](#patrón-cva)
+  - [Estructura de archivos](#estructura-de-archivos)
+- [Storybook: convenciones de stories](#storybook-convenciones-de-stories)
+- [Fuente de verdad: Figma](#fuente-de-verdad-figma)
+
+---
+
+## Descripción
+
+Este repositorio es la **fuente de componentes UI reutilizables** para los frontends de RegCheq (`web-client`, `web-client-mx`, `web-client-proveedores`). Los tokens de diseño (colores, tipografía, sombras) están sincronizados con el design system oficial en Figma y compilados en SCSS/CSS custom properties para que sean consumibles sin dependencias adicionales en los proyectos destino.
+
+**Stack:**
+
+| Herramienta | Versión | Rol |
+|---|---|---|
+| Vue | 2.6 | Framework de componentes |
+| Storybook | 7.6 | Documentación y sandbox |
+| Bootstrap Vue | 2.22 | Base de componentes estructurales |
+| SCSS | — | Estilos y design tokens |
+| CVA | latest | Gestión de variantes de componentes |
+| Inter | — | Fuente tipográfica del sistema |
+
+---
+
+## Requisitos
+
+- Node.js `18` (ver `.nvmrc`)
+- npm o yarn
+
+```bash
+nvm use   # activa Node 18 según .nvmrc
+```
+
+---
+
+## Instalación
+
+```bash
+npm install
+# o
+yarn
+```
+
+---
+
+## Levantar Storybook
+
+```bash
+npm run storybook
+# o
+yarn storybook
+```
+
+Abre en `http://localhost:6006`
+
+Para generar el build estático:
+
+```bash
+npm run build-storybook
+```
+
+---
+
+## Estructura del proyecto
+
+```
+regcheq-ui-vue-2/
+├── .storybook/
+│   ├── main.js          # Configuración de Storybook (webpack, addons, SCSS global)
+│   ├── preview.js       # Setup global: Bootstrap Vue, tokens, fuente Inter
+│   └── manager.js       # (opcional) Personalización UI de Storybook
+│
+└── src/
+    ├── assets/
+    │   └── scss/
+    │       ├── _tokens.scss      # CSS custom properties (:root) — carga global
+    │       └── _variables.scss   # Variables SCSS ($) — inyectadas en cada componente
+    │
+    ├── components/
+    │   ├── atoms/                # Componentes base: Button, Input, Badge, Tag...
+    │   │   └── [NombreComponente]/
+    │   │       ├── NombreComponente.vue
+    │   │       ├── NombreComponente.variants.js
+    │   │       ├── NombreComponente.scss
+    │   │       └── NombreComponente.stories.js
+    │   │
+    │   ├── molecules/            # Combinaciones de atoms: Card, FormField, Alert...
+    │   │   └── [NombreComponente]/
+    │   │       └── ...
+    │   │
+    │   └── organisms/            # Secciones completas: Navbar, Sidebar, DataTable...
+    │       └── [NombreComponente]/
+    │           └── ...
+    │
+    └── index.js                  # Entry point — exporta todos los componentes
+```
+
+### Jerarquía Atomic Design
+
+| Nivel | Carpeta | Ejemplos | Title en Storybook |
+|---|---|---|---|
+| Atoms | `components/atoms/` | Button, Input, Badge, Icon | `Atoms/RcqButton` |
+| Molecules | `components/molecules/` | Card, FormField, Alert, Tooltip | `Molecules/RcqCard` |
+| Organisms | `components/organisms/` | Navbar, Sidebar, DataTable, Modal | `Organisms/RcqNavbar` |
+
+---
+
+## Design Tokens
+
+Todos los tokens están definidos en `src/assets/scss/_tokens.scss`. Se inyectan automáticamente en todos los archivos `.scss` de los componentes, por lo que no es necesario importarlos manualmente.
+
+Están disponibles como **CSS custom properties** (para uso inline o en cualquier contexto CSS) y como **variables SCSS** (para uso dentro de `<style lang="scss">`).
+
+### Colores
+
+El sistema de colores sigue la escala `50–900` de Material Design, nombrada con el prefijo `rq-`.
+
+| Paleta | Variable base | Uso |
+|---|---|---|
+| Primary | `$rq-primary` / `--rq-primary` | Color de marca principal `#040045` |
+| Secondary | `$rq-secondary` / `--rq-secondary` | Color de marca secundario `#0064e0` |
+| Info | `$rq-info-{n}` | Estados informativos |
+| Success | `$rq-success-{n}` | Estados de éxito |
+| Warning | `$rq-warning-{n}` | Estados de advertencia |
+| Red | `$rq-red-{n}` | Estados de error / alerta |
+| Tag | `$rq-tag-{n}` | Etiquetas, badges (fucsia) |
+| Gray | `$rq-gray-{n}` | Neutros, textos, bordes |
+| White | `$rq-white-{n}` | Fondos y superficies |
+
+**Uso:**
+
+```scss
+// SCSS variable
+background: $rq-primary;
+color: $rq-gray-700;
+border-color: $rq-secondary-300;
+
+// CSS custom property
+background: var(--rq-primary);
+color: var(--rq-gray-700);
+```
+
+### Tipografía
+
+La fuente del sistema es **Inter**, cargada desde Google Fonts y aplicada globalmente a todos los componentes.
+
+```scss
+// SCSS
+font-family: $rq-font-family;
+
+// CSS custom property
+font-family: var(--rq-font-family);
+```
+
+No es necesario declarar la fuente en los componentes — se hereda por defecto.
+
+### Elevaciones
+
+5 niveles de sombra (`L0`–`L4`) para representar profundidad en el eje Z.
+
+| Variable | Valor | Uso recomendado |
+|---|---|---|
+| `$rq-elevation-0` | `none` | Flat. Cards y contenedores base |
+| `$rq-elevation-1` | `0px 1px 1px` | Widgets, Top Nav en hover |
+| `$rq-elevation-2` | `0px 2px 2px` | Cards en hover |
+| `$rq-elevation-3` | `0px 4px 12px` | Dropdowns, tooltips, menús |
+| `$rq-elevation-4` | `0px 8px 24px` | Modales, diálogos, notificaciones flotantes |
+
+```scss
+// SCSS
+box-shadow: $rq-elevation-3;
+
+// CSS custom property
+box-shadow: var(--rq-elevation-3);
+```
+
+---
+
+## Crear un componente
+
+### Patrón CVA
+
+Este proyecto usa **CVA (Class Variance Authority)** para gestionar variantes de componentes. CVA genera el string de clases CSS según las props recibidas, eliminando lógica condicional sucia dentro del template.
+
+```
+prop variant="primary"  →  CVA  →  "rcq-btn rcq-btn--primary rcq-btn--md"
+                                          ↓
+                                   SCSS define qué hace cada clase usando tokens
+```
+
+### Estructura de archivos
+
+Cada componente vive en su propio directorio con 4 archivos:
+
+#### `NombreComponente.variants.js`
+
+Define el mapeo entre props y clases CSS. Es la única fuente de verdad de las variantes.
+
+```js
+import { cva } from 'class-variance-authority'
+
+export const componenteVariants = cva('rcq-componente', {
+  variants: {
+    variant: {
+      primary:   'rcq-componente--primary',
+      secondary: 'rcq-componente--secondary',
+    },
+    size: {
+      sm: 'rcq-componente--sm',
+      md: 'rcq-componente--md',
+      lg: 'rcq-componente--lg',
+    },
+  },
+  defaultVariants: {
+    variant: 'primary',
+    size: 'md',
+  },
+})
+```
+
+#### `NombreComponente.scss`
+
+Define los estilos de cada clase usando los tokens del sistema. Nunca usar valores hardcodeados.
+
+```scss
+.rcq-componente {
+  font-family: $rq-font-family;
+
+  &--primary {
+    background: $rq-primary;
+    color: #ffffff;
+    &:hover:not(:disabled) { background: $rq-primary-400; }
+  }
+
+  &--sm { height: 32px; font-size: 12px; }
+  &--md { height: 40px; font-size: 14px; }
+  &--lg { height: 48px; font-size: 16px; }
+}
+```
+
+#### `NombreComponente.vue`
+
+El componente llama a CVA en un `computed` y aplica el resultado con `:class`. Sin lógica de clases en el template.
+
+```vue
+<template>
+  <div :class="classes">
+    <slot />
+  </div>
+</template>
+
+<script>
+import { componenteVariants } from './NombreComponente.variants'
+import './NombreComponente.scss'
+
+export default {
+  name: 'NombreComponente',
+  props: {
+    variant: { type: String, default: 'primary' },
+    size:    { type: String, default: 'md' },
+  },
+  computed: {
+    classes() {
+      return componenteVariants({ variant: this.variant, size: this.size })
+    },
+  },
+}
+</script>
+```
+
+#### `NombreComponente.stories.js`
+
+Documenta el componente en Storybook con controles interactivos y todas las variantes.
+
+```js
+import NombreComponente from './NombreComponente.vue'
+
+export default {
+  title: 'Atoms/NombreComponente',  // o Molecules/ u Organisms/ según corresponda
+  component: NombreComponente,
+  argTypes: {
+    variant: { control: 'select', options: ['primary', 'secondary'] },
+    size:    { control: 'select', options: ['sm', 'md', 'lg'] },
+  },
+}
+
+const Template = (args, { argTypes }) => ({
+  components: { NombreComponente },
+  props: Object.keys(argTypes),
+  template: '<NombreComponente v-bind="$props"><slot>Contenido</slot></NombreComponente>',
+})
+
+export const Default = Template.bind({})
+Default.args = { variant: 'primary', size: 'md' }
+
+export const AllVariants = () => ({
+  components: { NombreComponente },
+  template: `
+    <div style="display:flex; gap:12px;">
+      <NombreComponente variant="primary">Primary</NombreComponente>
+      <NombreComponente variant="secondary">Secondary</NombreComponente>
+    </div>
+  `,
+})
+```
+
+---
+
+## Storybook: convenciones de stories
+
+- Cada componente expone al menos 3 stories: `Default`, `AllVariants` y `AllSizes`
+- Agregar story `Disabled` cuando el componente tenga estado deshabilitado
+- Usar `title: 'Atoms/NombreComponente'`, `'Molecules/...'` u `'Organisms/...'` según el nivel
+- Los controles (`argTypes`) deben cubrir todas las props públicas
+
+---

package/dist/index.css

@@ -0,0 +1,311 @@
+.rq-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 8px;
+  border: 1px solid transparent;
+  border-radius: 8px;
+  font-family: "Inter", sans-serif;
+  font-weight: 500;
+  cursor: pointer;
+  white-space: nowrap;
+  text-decoration: none;
+  transition: background 200ms ease, color 200ms ease, border-color 200ms ease, box-shadow 200ms ease;
+}
+.rq-button:disabled, .rq-button[disabled] {
+  cursor: not-allowed;
+  pointer-events: none;
+}
+.rq-button:focus-visible {
+  outline: 2px solid #5497ea;
+  outline-offset: 2px;
+}
+.rq-button--primary {
+  background: #0064e0;
+  color: #ffffff;
+  border: 1px solid transparent;
+}
+.rq-button--primary:hover:not(:disabled):not([disabled]) {
+  background: #3383e6;
+  box-shadow: 0px 2px 2px 0px rgba(15, 15, 21, 0.1);
+}
+.rq-button--primary:active:not(:disabled):not([disabled]) {
+  background: #5497ea;
+  border-color: #3383e6;
+  box-shadow: none;
+}
+.rq-button--primary:disabled, .rq-button--primary[disabled] {
+  background: #e6f0fc;
+  color: #b0cff5;
+  border-color: transparent;
+}
+.rq-button--outline {
+  background: transparent;
+  color: #005bcc;
+  border: 1px solid #0064e0;
+}
+.rq-button--outline:hover:not(:disabled):not([disabled]) {
+  background: #e6f0fc;
+  border-color: #3383e6;
+  color: #3383e6;
+  box-shadow: 0px 2px 2px 0px rgba(15, 15, 21, 0.1);
+}
+.rq-button--outline:active:not(:disabled):not([disabled]) {
+  background: #b0cff5;
+  border-color: #5497ea;
+  color: #3383e6;
+  box-shadow: 0px 1px 1px 0px rgba(15, 15, 21, 0.1);
+}
+.rq-button--outline:disabled, .rq-button--outline[disabled] {
+  background: transparent;
+  border-color: #b0cff5;
+  color: #8ab8f1;
+}
+.rq-button--texted {
+  background: transparent;
+  color: #0064e0;
+  border: 1px solid transparent;
+}
+.rq-button--texted:hover:not(:disabled):not([disabled]) {
+  color: #3383e6;
+}
+.rq-button--texted:active:not(:disabled):not([disabled]) {
+  color: #5497ea;
+}
+.rq-button--texted:disabled, .rq-button--texted[disabled] {
+  color: #b0cff5;
+}
+.rq-button--sm {
+  height: 32px;
+  padding: 4px 8px;
+  font-size: 12px;
+}
+.rq-button--md {
+  height: 40px;
+  padding: 8px 16px;
+  font-size: 14px;
+}
+.rq-button--lg {
+  height: 48px;
+  padding: 10px 20px;
+  font-size: 16px;
+}
+.rq-button--xl {
+  height: 56px;
+  padding: 12px 24px;
+  font-size: 20px;
+}
+.rq-button--icon-only.rq-button--sm {
+  width: 32px;
+  padding: 0;
+}
+.rq-button--icon-only.rq-button--md {
+  width: 40px;
+  padding: 0;
+}
+.rq-button--icon-only.rq-button--lg {
+  width: 48px;
+  padding: 0;
+}
+.rq-button--icon-only.rq-button--xl {
+  width: 56px;
+  padding: 0;
+}
+.rq-input {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  width: 100%;
+  font-family: "Inter", sans-serif;
+}
+.rq-input__label {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  margin-bottom: 0;
+  font-size: 12px;
+  font-weight: 500;
+  line-height: 16px;
+  color: #3f3f46;
+}
+.rq-input__label--error {
+  color: #ff2414;
+}
+.rq-input__optional {
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 20px;
+  color: #a1a1aa;
+}
+.rq-input__field {
+  display: flex;
+  align-items: center;
+  width: 100%;
+  border: 1px solid #3f3f46;
+  border-radius: 8px;
+  background: #ffffff;
+  transition: border-color 200ms ease, box-shadow 200ms ease;
+}
+.rq-input__field:hover:not(.rq-input__field--disabled):not(.rq-input__field--readonly) {
+  border-color: #18181b;
+}
+.rq-input__field:focus-within:not(.rq-input__field--disabled):not(.rq-input__field--readonly) {
+  border-color: #0064e0;
+  box-shadow: 0 0 0 2px #b0cff5;
+}
+.rq-input__field--disabled {
+  background: #f4f4f5;
+  border-color: #d4d4d8;
+  cursor: not-allowed;
+}
+.rq-input__field--readonly {
+  background: #e4e4e7;
+  border-color: #d4d4d8;
+}
+.rq-input__field--error {
+  border-color: #ff2414;
+}
+.rq-input__field--error:hover:not(.rq-input__field--disabled) {
+  border-color: #d71709;
+}
+.rq-input__field--error:focus-within:not(.rq-input__field--disabled) {
+  border-color: #ff2414;
+  box-shadow: 0 0 0 2px #fed0cd;
+}
+.rq-input__native {
+  flex: 1;
+  min-width: 0;
+  border: none;
+  outline: none;
+  background: transparent;
+  font-family: "Inter", sans-serif;
+  font-size: 14px;
+  font-weight: 400;
+  line-height: 20px;
+  color: #18181b;
+}
+.rq-input__native::placeholder {
+  color: #a1a1aa;
+}
+.rq-input__native:disabled {
+  cursor: not-allowed;
+  color: #a1a1aa;
+}
+.rq-input__native[readonly] {
+  cursor: default;
+  color: #52525b;
+}
+.rq-input__icon {
+  display: flex;
+  align-items: center;
+  flex-shrink: 0;
+  color: #a1a1aa;
+}
+.rq-input__icon--error {
+  color: #ff2414;
+}
+.rq-input__icon--disabled {
+  color: #d4d4d8;
+}
+.rq-input__icon--readonly {
+  color: #71717a;
+}
+.rq-input__icon svg {
+  display: block;
+}
+.rq-input__label-tooltip {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  cursor: help;
+  color: #a1a1aa;
+  margin-left: 2px;
+}
+.rq-input__label-tooltip:hover {
+  color: #52525b;
+}
+.rq-input__label-tooltip::after {
+  content: attr(data-tooltip);
+  position: absolute;
+  bottom: calc(100% + 6px);
+  left: 50%;
+  transform: translateX(-50%);
+  background: #18181b;
+  color: #ffffff;
+  font-family: "Inter", sans-serif;
+  font-size: 12px;
+  line-height: 16px;
+  font-weight: 400;
+  padding: 4px 8px;
+  border-radius: 4px;
+  white-space: nowrap;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 200ms ease;
+  z-index: 10;
+}
+.rq-input__label-tooltip:hover::after {
+  opacity: 1;
+}
+.rq-input__footer {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  gap: 8px;
+}
+.rq-input__helper {
+  flex: 1;
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 20px;
+  color: #a1a1aa;
+}
+.rq-input__error-text {
+  flex: 1;
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 20px;
+  color: #ff2414;
+}
+.rq-input__counter {
+  font-size: 12px;
+  font-weight: 400;
+  line-height: 20px;
+  color: #a1a1aa;
+  white-space: nowrap;
+}
+.rq-input__counter--error {
+  color: #ff2414;
+}
+.rq-input--sm .rq-input__field {
+  min-height: 32px;
+  padding: 0 8px;
+}
+.rq-input--sm .rq-input__native {
+  font-size: 12px;
+  line-height: 20px;
+}
+.rq-input--md .rq-input__field {
+  min-height: 40px;
+  padding: 0 12px;
+}
+.rq-input--md .rq-input__native {
+  font-size: 14px;
+  line-height: 20px;
+}
+.rq-input--lg .rq-input__field {
+  min-height: 48px;
+  padding: 0 16px;
+}
+.rq-input--lg .rq-input__native {
+  font-size: 14px;
+  line-height: 20px;
+}
+.rq-input--xl .rq-input__field {
+  min-height: 56px;
+  padding: 0 20px;
+}
+.rq-input--xl .rq-input__native {
+  font-size: 16px;
+  line-height: 24px;
+}