@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

# 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:

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:

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

pnpm add @salesql/sql_components_vue3

Ejemplo:

<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:

<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:

<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:

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

pnpm dev:stories

5. Chequear y build

pnpm typecheck
pnpm build

6. Versionado

pnpm changeset
pnpm release:version

7. Publicación

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:

  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.