@salesql/sql_components_vue3 0.2.0 → 0.2.1

package/README.md

@@ -0,0 +1,253 @@
+# @salesql/sql_components_vue3
+
+Librería de componentes Vue 3 (TypeScript) para SalesQL.  
+Estilos con **SCSS** (variables centralizadas en `colors.scss`).  
+Visor de componentes y playground con **Histoire**.
+
+---
+
+## 🚀 Requisitos
+
+> ⚠️ **Node:** Vite 7 requiere **Node ≥ 20.19** (recomendado **22.12.0**).  
+> Con Node 18 fallará con `crypto.hash is not a function`.
+
+| Tool / lib             | Versión recomendada    |
+| ---------------------- | ---------------------- |
+| **Node**               | **22.12.0** (o ≥20.19) |
+| **pnpm**               | 10.17.0                |
+| **Vue**                | 3.5.22                 |
+| **Vite**               | 7.1.7                  |
+| **@vitejs/plugin-vue** | 6.0.1                  |
+| **TypeScript**         | 5.9.2                  |
+| **vue-tsc**            | 2.2.12                 |
+| **Histoire**           | 1.0.0-alpha.3          |
+| **Sass (dart-sass)**   | 1.93.2                 |
+| **Changesets**         | 2.29.7                 |
+
+### Preparación de entorno
+
+```bash
+# Node
+nvm install 22.12.0
+nvm use 22.12.0
+node -v  # v22.12.0
+
+# Instalar dependencias del monorepo
+pnpm install
+
+# (Primera vez con Vite/Histoire)
+pnpm approve-builds     # marca @parcel/watcher y confirma
+```
+
+---
+
+## 📂 Estructura
+
+```
+salesql-components-library-vue3/
+├─ package.json                 # raíz del monorepo
+├─ pnpm-workspace.yaml
+├─ tsconfig.base.json
+└─ components/                  # paquete de la librería
+   ├─ package.json
+   ├─ tsconfig.json             # solo src/*
+   ├─ tsconfig.build.json       # build de la lib
+   ├─ tsconfig.node.json        # configs: vite/histoire
+   ├─ vite.config.ts
+   ├─ histoire.config.ts
+   ├─ src/
+   │  ├─ index.ts               # exporta componentes (+ importa estilos base)
+   │  ├─ env.d.ts
+   │  ├─ stories.setup.ts
+   │  ├─ assets/css/
+   │  │  ├─ base.scss
+   │  │  ├─ colors.scss
+   │  │  └─ spacing.scss
+   │  ├─ constants/sql-components.ts
+   │  └─ components/
+   │     ├─ SqlButton.vue
+   │     ├─ SqlButton.story.vue
+   │     ├─ SqlSpinner.vue
+   │     └─ SqlSpinner.story.vue
+   └─ dist/                     # salida de build
+```
+
+---
+
+## 📦 Scripts principales
+
+Desde la raíz:
+
+```bash
+pnpm build         # build de la librería
+pnpm dev:stories   # arranca Histoire
+pnpm typecheck     # chequeo estricto de tipos
+pnpm changeset     # crear un changeset
+pnpm release:version   # aplicar changeset y subir versión
+pnpm release:publish   # publicar a npm
+pnpm reset         # limpiar node_modules + reinstalar + aprobar builds
+```
+
+---
+
+## 🔎 Histoire (visualización y testeo)
+
+Para arrancar el entorno de historias:
+
+```bash
+pnpm dev:stories
+```
+
+- Abre http://localhost:6006
+- Historias junto al componente, ej: `SqlButton.story.vue`
+- Usa `<Story>` / `<Variant>` / `<Controls>` para mostrar variantes e interactuar
+
+---
+
+## 📥 Uso en apps consumidoras
+
+```bash
+pnpm add @salesql/sql_components_vue3
+```
+
+Ejemplo:
+
+```vue
+<script setup lang="ts">
+  import { SqlButton } from "@salesql/sql_components_vue3";
+</script>
+
+<template>
+  <SqlButton class="sql-button--primary sql-button--large"> Guardar </SqlButton>
+</template>
+```
+
+Los estilos base se importan automáticamente desde la librería (`base.scss`).
+
+---
+
+## 🛠️ Añadir un nuevo componente (Checklist)
+
+> Convención de nombres: archivos **PascalCase** (`SqlX.vue`, `SqlX.story.vue`).
+
+### 1. Crear el componente
+
+`components/src/components/SqlX.vue`:
+
+```vue
+<script setup lang="ts">
+  // lógica/props
+</script>
+
+<template>
+  <div class="sql-x">
+    <slot />
+  </div>
+</template>
+
+<style lang="scss" scoped>
+  @use "../assets/css/colors.scss" as colors;
+  @use "../assets/css/spacing.scss" as s;
+
+  .sql-x {
+    color: colors.$primary-main;
+    padding: s.spacing(2);
+  }
+</style>
+```
+
+### 2. Crear la historia
+
+`components/src/components/SqlX.story.vue`:
+
+```vue
+<script setup lang="ts">
+  import SqlX from "./SqlX.vue";
+</script>
+
+<template>
+  <Story title="SqlX/Básico">
+    <Variant title="Default">
+      <SqlX>Contenido</SqlX>
+    </Variant>
+    <Variant title="Playground">
+      <Controls :data="{ text: { type: 'text', default: 'Hola' } }">
+        <template #default="{ state }">
+          <SqlX>{{ state.text }}</SqlX>
+        </template>
+      </Controls>
+    </Variant>
+  </Story>
+</template>
+```
+
+### 3. Exportarlo
+
+En `components/src/index.ts`:
+
+```ts
+import "./assets/css/base.scss";
+
+export { default as SqlButton } from "./components/SqlButton.vue";
+export { default as SqlSpinner } from "./components/SqlSpinner.vue";
+export { default as SqlX } from "./components/SqlX.vue";
+```
+
+### 4. Probar con Histoire
+
+```bash
+pnpm dev:stories
+```
+
+### 5. Chequear y build
+
+```bash
+pnpm typecheck
+pnpm build
+```
+
+### 6. Versionado
+
+```bash
+pnpm changeset
+pnpm release:version
+```
+
+### 7. Publicación
+
+```bash
+pnpm release:publish
+```
+
+---
+
+## 🔧 Convenciones
+
+- **Archivos:** PascalCase para `.vue` y `.story.vue`.
+- **Estilos:** `@use '../assets/css/colors.scss' as colors;`.
+- **Spacing:** `spacing.scss` con `map.get(...)`.
+- **Enums/constantes:**
+  ```ts
+  export const SQL_SPINNER_SIZES = {
+    SMALL: "small",
+    MEDIUM: "medium",
+    LARGE: "large",
+  } as const;
+  export type SqlSpinnerSize =
+    (typeof SQL_SPINNER_SIZES)[keyof typeof SQL_SPINNER_SIZES];
+  ```
+
+---
+
+## 🐛 Troubleshooting
+
+- **`crypto.hash is not a function` / “Vite requires Node 20.19+ or 22.12+”**  
+  → Actualiza Node a **22.12.0** y reinstala dependencias.
+
+- **VSCode marca “Cannot find module 'vue'”**  
+  → Asegúrate de que `vue` está en **peerDependencies** y **devDependencies** en `components/package.json`.  
+  Reinicia TS server.
+
+- **pnpm pide aprobar `@parcel/watcher`**  
+  → `pnpm approve-builds` (marca `@parcel/watcher`).  
+  Para global: `pnpm approve-builds --global`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesql/sql_components_vue3",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Librería de componentes Vue 3 (SalesQL)",
   "type": "module",
   "main": "./dist/index.cjs",