@i-rent/component-library 0.0.1

package/README.md

@@ -0,0 +1,180 @@
+# @i-rent/component-library
+
+Librería de componentes Vue 3 con doble modo de uso: como componentes Vue normales o como Web Components nativos. Diseñada para ser personalizable sin interferir con estilos externos.
+
+## Instalación
+
+```sh
+pnpm install
+```
+
+## Comandos
+
+```sh
+pnpm dev          # Servidor de desarrollo
+pnpm storybook    # Storybook en puerto 6006
+pnpm build        # Type check + build de producción
+pnpm test         # Vitest en modo watch
+pnpm test:run     # Vitest single run (CI)
+pnpm lint         # ESLint con auto-fix
+pnpm type-check   # vue-tsc
+```
+
+## Componentes
+
+| Componente | Descripción |
+|---|---|
+| `IButton` | Botón con variantes, iconos y tamaños |
+| `IInput` | Campo de texto con validación y estados |
+| `ICalendar` | Calendario con selección de rangos |
+| `IOccupancyCalendar` | Calendario especializado para reservas |
+| `IDatePicker` | Selector de fechas con calendario integrado |
+| `ITooltip` | Tooltip contextual |
+| `IIcon` | Sistema de iconos |
+| `IMap` | Mapa con marcadores, clustering y precios |
+
+## Uso
+
+### Como plugin Vue
+
+```ts
+import { ComponentLibrary } from '@i-rent/component-library'
+import '@i-rent/component-library/scss/main'
+
+app.use(ComponentLibrary)
+```
+
+### Como Web Components
+
+```ts
+import { defineCustomElements } from '@i-rent/component-library'
+
+defineCustomElements() // registra <i-button>, <i-map>, etc.
+```
+
+```html
+<i-button label="Hola" variant="outline"></i-button>
+```
+
+## Sistema de colores
+
+La librería expone un único tema base vía CSS custom properties. Todos los shades del primary se derivan automáticamente usando `oklch` — el consumer solo sobreescribe una variable.
+
+### Variables disponibles
+
+```css
+--i-theme-primary          /* color base — el único que necesitás setear */
+
+/* shades derivados automáticamente */
+--i-theme-primary-lighten-5
+--i-theme-primary-lighten-4
+--i-theme-primary-lighten-3
+--i-theme-primary-lighten-2
+--i-theme-primary-lighten-1
+--i-theme-primary-darken-1
+--i-theme-primary-darken-2
+--i-theme-primary-darken-3
+--i-theme-primary-darken-4
+
+/* tokens fijos */
+--i-theme-success          /* #23c197 */
+--i-theme-warning          /* #ffc964 */
+--i-theme-error            /* #ff3838 */
+--i-theme-disabled         /* #a4abb6 */
+--i-font-color
+--i-font-color-shade
+```
+
+### Override del primary
+
+Acepta cualquier formato de color válido en CSS:
+
+```css
+/* Vue component — aplica globalmente */
+:root {
+  --i-theme-primary: #e74c3c;
+}
+
+/* Vue component — aplica solo en un scope */
+.mi-seccion {
+  --i-theme-primary: hsl(6 78% 57%);
+}
+
+/* Web Component */
+i-button {
+  --i-theme-primary: oklch(0.63 0.18 26);
+}
+```
+
+Los shades (`lighten-1` a `lighten-5`, `darken-1` a `darken-4`) se recalculan solos en el browser.
+
+### Dark mode
+
+```html
+<div data-theme="dark">...</div>
+```
+
+### Override de tokens fijos
+
+```css
+:root {
+  --i-theme-success: #00b894;
+  --i-theme-error:   #d63031;
+}
+```
+
+## Personalización SCSS
+
+Las variables SASS permiten deshabilitar o modificar modificadores antes de importar los estilos:
+
+```scss
+@use '@i-rent/component-library/scss/variables' as * with (
+  $i-border-pill: 0,                          // deshabilitar border pill
+  $i-calendar-today-color: #ff0000,           // color de hoy en calendario
+  $i-font-family: 'Inter', sans-serif,
+  $i-font-import-url: null,                   // deshabilitar import de fuente
+);
+
+@use '@i-rent/component-library/scss/main';
+```
+
+## Estructura SCSS
+
+```
+src/scss/
+  ├── main.scss         # Punto de entrada
+  ├── _variables.scss   # Variables SASS de modificadores
+  ├── _colors.scss      # CSS custom properties del tema
+  ├── _typography.scss  # Tipografía
+  └── _utilities.scss   # Clases de utilidad (scrollbar, ripple, etc.)
+```
+
+## Estructura de componentes
+
+```
+src/stories/i-button/
+  ├── IButton.vue          # Componente (<script setup lang="ts">)
+  ├── IBtn.scss            # Estilos BEM con prefijo .i-btn
+  ├── _modifiers.scss      # Variables SASS sobreescribibles
+  ├── IButton.stories.ts   # Stories CSF
+  └── IButton.mdx          # Documentación
+```
+
+## Convenciones
+
+| Cosa | Patrón | Ejemplo |
+|---|---|---|
+| Clases CSS | `.i-{component}` | `.i-btn`, `.i-btn--outline` |
+| CSS custom properties | `--i-theme-*` | `--i-theme-primary` |
+| Variables SASS | `$i-*` | `$i-btn-outline` |
+| Interface de props | `I{Component}Props` | `IButtonProps` |
+
+## Requisitos
+
+- Node >= 18
+- pnpm >= 9
+- Browser con soporte de CSS `oklch` relative color syntax (Chrome 119+, Firefox 128+, Safari 16.4+)
+
+## IDE
+
+[VSCode](https://code.visualstudio.com/) + [Volar](https://marketplace.visualstudio.com/items?itemName=Vue.volar). Deshabilitar Vetur si está instalado.