npm package: @salesql/sql_components_vue3
Description: Librería de componentes Vue 3 (SalesQL)
Latest version: 0.2.1

# @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`.