lf-pagebuilder-vue 0.0.3 → 0.0.4

package/README.md

@@ -1,300 +1,380 @@
-# @lefebvre/lf-pagebuilder-vue
+# lf-pagebuilder-vue
 
-Un componente Vue 3 de Page Builder con drag-and-drop para proyectos Lefebvre. Permite crear páginas de forma visual con un sistema de filas, columnas y componentes arrastrables.
+Editor visual para construir páginas HTML usando los componentes de `libreria-astro-lefebvre`.
 
----
+## Instalación
 
-## ⚠️ IMPORTANTE: Configuración de Entorno
+```bash
+npm i lf-pagebuilder-vue
+```
 
-> **El componente `Pagebuilder` requiere la prop `isProduction` para determinar qué URLs de API utilizar (desarrollo o producción).**
+Luego en tu `package.json`, cambia la versión a `latest` para tener siempre la última:
 
-```vue
-<template>
-  <Pagebuilder 
-    :isProduction="isProduction" 
-    :renderApiDomain="apiUrl" 
-  />
-</template>
+```json
+{
+  "dependencies": {
+    "lf-pagebuilder-vue": "latest"
+  }
+}
+```
 
-<script setup>
-import { Pagebuilder } from 'lf-pagebuilder-vue';
-import 'lf-pagebuilder-vue/styles';
+## ¿Qué es?
 
-// Opción 1: Usando import.meta.env.PROD (Vite detecta automáticamente)
-const isProduction = import.meta.env.PROD;
+El Pagebuilder permite al usuario arrastrar y configurar componentes de la librería de componentes Astro de Lefebvre para diseñar páginas de forma visual. 
 
-// Opción 2: Usando una variable de entorno personalizada
-// const isProduction = import.meta.env.VITE_IS_PRODUCTION === 'true';
+**El Pagebuilder NO renderiza la página final.** Genera un JSON de configuración que se envía a una API externa renderizadora, que es la encargada de generar el HTML final.
 
-const apiUrl = 'https://tu-api-render.com';
-</script>
-```
+## Formas de uso
 
-| Valor de `isProduction` | URLs utilizadas |
-|-------------------------|-----------------|
-| `true` | URLs de producción (ej: `https://elderecho.com/feed`) |
-| `false` | URLs de desarrollo (ej: `https://led-dev-elderecho-dev.eu.els.local/feed`) |
+### 1. Como script IIFE (Symfony u otros backends)
 
----
+En la carpeta `dist-symfony/` están los archivos compilados:
+- `lf-pagebuilder-iife.iife.js`
+- `lf-pagebuilder-iife.css`
 
-## 🚀 Características
+**Instalación:**
 
-- **Drag & Drop**: Sistema intuitivo para arrastrar y organizar componentes
-- **Modo Visual/Configuración**: Alterna entre vista previa y modo de edición
-- **Secciones**: Header, Body, Footer y Sidebar configurables
-- **Configuración de filas y columnas**: Padding, gap, anchos personalizables
-- **Feed de contenido**: Conecta componentes con fuentes de datos externas
-- **Preview en tiempo real**: Visualiza los cambios al instante
-- **Exportar/Importar**: Guarda y carga configuraciones JSON
-- **SEO Validator**: Valida la estructura SEO de la página
+Copiar estos archivos a la carpeta pública del proyecto. En Symfony, puedes configurar el build para que los copie automáticamente a `public/build/` o copiarlos manualmente.
 
-## 📦 Instalación
+**Uso:**
 
-```bash
-npm install @lefebvre/lf-pagebuilder-vue
+```html
+<link rel="stylesheet" href="/build/lf-pagebuilder-iife.css">
+<script src="/build/lf-pagebuilder-iife.iife.js"></script>
+
+<!-- El Pagebuilder se monta automáticamente en elementos con el selector: -->
+<div class="XXXXXXXX" data-is-production="false"></div>
 ```
 
-## 📋 Peer Dependencies
+El atributo `data-is-production` indica el entorno:
+- `"true"` → Usa API de producción (`https://render-api.lefebvre.es`)
+- `"false"` → Usa API de desarrollo (`https://led-dev-astro-render-api-dev.eu.els.local`)
+
+---
 
-Este paquete requiere las siguientes dependencias:
+### 2. Como componente Vue
 
 ```bash
-npm install vue@^3.3.0 vuedraggable@^4.1.0 @vueup/vue-quill@^1.2.0 libreria-astro-lefebvre@latest
+npm install lf-pagebuilder-vue
 ```
 
-## 🔧 Uso
-
-### En un proyecto Vue 3
-
 ```vue
 <template>
-  <Pagebuilder :renderApiDomain="apiUrl" />
+  <Pagebuilder :isProduction="false" />
 </template>
 
 <script setup>
-import { Pagebuilder } from '@lefebvre/lf-pagebuilder-vue';
-import '@lefebvre/lf-pagebuilder-vue/styles';
-
-const apiUrl = 'https://tu-api-render.com';
+import { Pagebuilder } from 'lf-pagebuilder-vue';
 </script>
 ```
 
-### En un proyecto Astro con Vue
+**Props:**
 
-```astro
----
-import Layout from '../layouts/Layout.astro';
-import { Pagebuilder } from '@lefebvre/lf-pagebuilder-vue';
-import '@lefebvre/lf-pagebuilder-vue/styles';
+| Prop | Tipo | Default | Descripción |
+|------|------|---------|-------------|
+| `isProduction` | `boolean` | `false` | `true` = API producción, `false` = API desarrollo |
 
-const renderApiUrl = import.meta.env.ASTRO_RENDER_API;
 ---
 
-<Layout>
-  <div class="bg-slate-100 py-20">
-    <Pagebuilder client:only="vue" renderApiDomain={renderApiUrl} />
-  </div>
-</Layout>
+## Instalación y dependencias
+
+### Dependencias requeridas en el proyecto padre
+
+El proyecto que use este Pagebuilder debe tener instaladas estas dependencias:
+
+```bash
+npm install vue@^3.3.0 vuedraggable@^4.1.0 @vueup/vue-quill@^1.2.0 libreria-astro-lefebvre@latest
 ```
 
-## 🧩 Componentes exportados
+| Dependencia | Versión | Descripción |
+|-------------|---------|-------------|
+| `vue` | ^3.3.0 | Framework Vue 3 |
+| `vuedraggable` | ^4.1.0 | Drag & drop para Vue 3 |
+| `@vueup/vue-quill` | ^1.2.0 | Editor de texto enriquecido |
+| `libreria-astro-lefebvre` | latest | Librería de componentes Astro de Lefebvre |
 
-| Componente | Descripción |
-|------------|-------------|
-| `Pagebuilder` | Componente principal del page builder |
-| `BodySection` | Sección del body con filas y columnas |
-| `ColConfig` | Configuración de columnas |
-| `ComponentsBox` | Caja de componentes disponibles |
-| `FeedComponent` | Configuración de feeds de contenido |
-| `FieldsForm` | Formulario de campos de componente |
-| `GlobalConfig` | Barra de configuración global |
-| `InitialComponent` | Componente individual renderizado |
-| `RowConfig` | Configuración de filas |
-| `SourceFilter` | Filtros de fuentes de datos |
+### Configuración especial del proyecto padre
 
-## 📐 Props del Pagebuilder
+#### En proyectos Astro
 
-| Prop | Tipo | Requerido | Default | Descripción |
-|------|------|-----------|---------|-------------|
-| `isProduction` | `boolean` | **Sí** | `false` | Determina si usar URLs de producción o desarrollo |
-| `renderApiDomain` | `string` | No | - | URL del API de renderizado para previews |
+El proyecto debe tener las integraciones de Vue y Tailwind:
 
-## 🎨 Estilos
+```bash
+npm install @astrojs/vue tailwindcss @tailwindcss/vite
+```
 
-Los estilos se pueden importar por separado:
+En `astro.config.mjs`:
 
 ```js
-import '@lefebvre/lf-pagebuilder-vue/styles';
+import { defineConfig } from 'astro/config';
+import { searchForWorkspaceRoot } from 'vite';
+import path from 'path';
+import vue from '@astrojs/vue';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  integrations: [vue()],
+
+  vite: {
+    plugins: [tailwindcss()],
+    server: {
+      fs: {
+        // Necesario si usas npm link con librerías hermanas
+        allow: [
+          searchForWorkspaceRoot(process.cwd()),
+          path.resolve(process.cwd(), '..'),
+        ],
+      },
+    },
+  },
+});
 ```
 
-El componente usa Tailwind CSS para los estilos. Asegúrate de tener Tailwind configurado en tu proyecto.
+> **Nota:** La configuración de `vite.server.fs.allow` es necesaria cuando usas `npm link` para desarrollo local con librerías en carpetas hermanas. Si instalas el paquete desde npm, no es necesaria.
 
-## 📤 Exportación de configuración
+---
 
-La configuración de la página se puede exportar en formato JSON:
+## Build
 
-```typescript
-interface PageBuilderConfig {
-  pageConfig: PageSection[];
-  paramsConfig: PageParameters;
-}
+El proyecto tiene dos builds diferentes:
 
-interface PageSection {
-  section: string;
-  config: { width?: string };
-  rows: PageRow[];
-}
+### Build estándar (librería npm)
 
-interface PageRow {
-  config: { padding?: string; gap?: string; width?: string };
-  columns: PageColumn[];
-}
-
-interface PageColumn {
-  config: { width?: string; gap?: string; flexDirection?: string };
-  components: PageComponent[];
-}
+```bash
+npm run build
 ```
 
-## 🔌 API de Renderizado
+Genera en `dist/`:
+- `index.js` - ES Module
+- `index.cjs` - CommonJS
+- `index.d.ts` - Tipos TypeScript
+- `styles.css` - Estilos
 
-El Pagebuilder requiere una API externa para:
+Este es el build que se publica en npm.
 
-1. **Preview de componentes**: `POST /api/preview-comp/`
-2. **Renderizado de página**: `POST /api/render-html/`
+### Build Symfony (IIFE)
 
-## 📝 Tipos TypeScript
+```bash
+npm run build:symfony
+```
 
-El paquete incluye tipos TypeScript completos:
+Genera en `dist-symfony/`:
+- `lf-pagebuilder-iife.iife.js` - Script autocontenido
+- `lf-pagebuilder-iife.css` - Estilos
 
-```typescript
-import type { 
-  PageSection, 
-  PageRow, 
-  PageColumn, 
-  PageComponent,
-  ComponentField,
-  PageParameters,
-  PageBuilderConfig 
-} from '@lefebvre/lf-pagebuilder-vue';
-```
+Este build incluye Vue y todas las dependencias empaquetadas. Se puede usar directamente con `<script>` sin necesidad de bundler.
 
-## 🛠️ Desarrollo
+### Build completo
 
 ```bash
-# Clonar el repositorio
-git clone https://github.com/Lefebvre-El-Derecho-SA/lf-pagebuilder-vue
+npm run build:all
+```
 
-# Instalar dependencias
-npm install
+Ejecuta ambos builds.
 
-# Desarrollo con watch
-npm run dev
+---
+
+## ⚠️ Desarrollo local
+
+> **IMPORTANTE**: Lee esta sección completa antes de trabajar con este proyecto localmente.
+
+### El problema del `package.json`
+
+Este proyecto tiene **dos configuraciones de `package.json`** porque durante el desarrollo local NO queremos compilar constantemente:
+
+| Archivo | Apunta a | Uso |
+|---------|----------|-----|
+| `package.dev.json` | `./src/` (código fuente) | Desarrollo local |
+| `package.prod.json` | `./dist/` (compilado) | Publicar en npm |
+
+**Durante el desarrollo**, el `package.json` debe apuntar a los archivos fuente para que los cambios se reflejen inmediatamente sin hacer build.
+
+**Para publicar en npm**, debe apuntar a los archivos compilados.
+
+#### Cambiar entre modos
+
+Puedes copiar el archivo o copiar y pegar el contenido manualmente:
+
+```bash
+# Para DESARROLLO: copiar configuración de desarrollo
+cp package.dev.json package.json
 
-# Build
+# Para PRODUCCIÓN/PUBLICAR: copiar configuración de producción
+cp package.prod.json package.json
 npm run build
+npm publish
 ```
 
-### 📦 Configuración de package.json para desarrollo vs producción
+> ⚠️ **NUNCA publiques con la configuración de desarrollo.** El paquete no funcionará porque `./src/` no se incluye en el paquete publicado.
 
-Para evitar tener que hacer `npm run build` constantemente durante el desarrollo local, existen dos configuraciones de `package.json`:
+#### ⚠️ MUY IMPORTANTE: Mantener sincronizados los 3 archivos
 
-- **Desarrollo local**: Apunta directamente a los archivos fuente (`./src/`)
-- **Producción/npm**: Apunta a los archivos compilados (`./dist/`)
+Los archivos `package.json`, `package.dev.json` y `package.prod.json` deben estar sincronizados:
 
-> **Instrucciones**: Copia y pega el contenido correspondiente en tu `package.json` según lo que necesites.
+- **Nueva dependencia**: Si añades una dependencia, añádela también en `package.dev.json` y `package.prod.json`
+- **Cambio de versión**: Cuando subas la versión del paquete, actualízala en los 3 archivos
+- **Cualquier otro cambio**: Scripts, keywords, etc. deben reflejarse en los 3
 
-<details>
-<summary><strong>📁 package.dev.json para DESARROLLO LOCAL (sin build)</strong></summary>
+```bash
+# Ejemplo: después de añadir una dependencia
+npm install nueva-dependencia
 
-```json
-{
-  "name": "lf-pagebuilder-vue",
-  "version": "0.0.1",
-  "description": "Pagebuilder Vue component library for Lefebvre projects",
-  "type": "module",
-  "main": "./src/index.ts",
-  "module": "./src/index.ts",
-  "types": "./src/index.ts",
-  "exports": {
-    ".": {
-      "import": "./src/index.ts",
-      "types": "./src/index.ts"
-    },
-    "./styles": "./src/styles/pagebuilder.css"
-  },
-  "files": ["dist", "src", "README.md"]
-}
+# Ahora editar manualmente package.dev.json y package.prod.json
+# para añadir "nueva-dependencia" en las mismas secciones
 ```
 
-</details>
+---
 
-<details>
-<summary><strong>📁 package.prod.json para PRODUCCIÓN (npm publish)</strong></summary>
+### Trabajar con `npm link`
 
-```json
-{
-  "name": "lf-pagebuilder-vue",
-  "version": "0.0.1",
-  "description": "Pagebuilder Vue component library for Lefebvre projects",
-  "type": "module",
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs",
-      "types": "./dist/index.d.ts"
-    },
-    "./styles": "./dist/styles.css"
-  },
-  "files": ["dist", "README.md"]
-}
+Para probar cambios localmente en otro proyecto sin publicar:
+
+#### Paso 1: Crear el enlace en esta librería
+
+```bash
+cd /ruta/a/lf-pagebuilder-vue
+npm link
 ```
 
-</details>
+#### Paso 2: Usar el enlace en tu proyecto
 
-> ⚠️ **IMPORTANTE**: Antes de hacer `npm publish`, asegúrate de usar la configuración de **PRODUCCIÓN** y ejecutar `npm run build`.
+```bash
+cd /ruta/a/tu-proyecto
+npm link lf-pagebuilder-vue
+```
 
-### 🔗 Desarrollo local con `npm link` (múltiples librerías)
+---
 
-> **IMPORTANTE**: Si necesitas usar enlaces simbólicos de **múltiples librerías** (por ejemplo, `lf-pagebuilder-vue` y `libreria-astro-lefebvre`), debes linkear **todas las librerías en un solo comando**.
+### ⚠️ CRÍTICO: Múltiples librerías con `npm link`
 
-#### Paso 1: Crear los enlaces simbólicos en cada librería
+**Este proyecto depende de `libreria-astro-lefebvre`.** Si necesitas trabajar con ambas librerías localmente (muy común), hay una trampa importante:
 
 ```bash
-# En el directorio de lf-pagebuilder-vue
+# ❌ INCORRECTO - El segundo comando ROMPE el primero
+npm link lf-pagebuilder-vue
+npm link libreria-astro-lefebvre
+
+# ✅ CORRECTO - Linkear TODAS las librerías en UN SOLO comando
+npm link lf-pagebuilder-vue libreria-astro-lefebvre
+```
+
+#### Flujo completo para trabajar con ambas librerías
+
+```bash
+# 1. En lf-pagebuilder-vue
 cd /ruta/a/lf-pagebuilder-vue
+cp package.dev.json package.json  # Modo desarrollo
 npm link
 
-# En el directorio de libreria-astro-lefebvre (u otra librería)
+# 2. En libreria-astro-lefebvre
 cd /ruta/a/libreria-astro-lefebvre
 npm link
+
+# 3. En tu proyecto consumidor - AMBAS EN UN SOLO COMANDO
+cd /ruta/a/tu-proyecto
+npm link lf-pagebuilder-vue libreria-astro-lefebvre
 ```
 
-#### Paso 2: Usar los enlaces en tu proyecto consumidor
+#### Deshacer los enlaces
 
 ```bash
-# ✅ CORRECTO: Linkear ambas librerías en UN SOLO COMANDO
 cd /ruta/a/tu-proyecto
-npm link lf-pagebuilder-vue libreria-astro-lefebvre
-
-# ❌ INCORRECTO: Linkear por separado (el segundo sobreescribe el primero)
-npm link lf-pagebuilder-vue
-npm link libreria-astro-lefebvre  # ¡Esto rompe el link anterior!
+npm unlink lf-pagebuilder-vue libreria-astro-lefebvre
+npm install
 ```
 
-#### Paso 3: Para deshacer los enlaces
+#### Si algo no funciona
 
 ```bash
+# Nuclear option: borrar todo y reinstalar
 cd /ruta/a/tu-proyecto
-npm unlink lf-pagebuilder-vue libreria-astro-lefebvre
+rm -rf node_modules package-lock.json
 npm install
+npm link lf-pagebuilder-vue libreria-astro-lefebvre
+```
+
+---
+
+### Watch mode
+
+Para que los cambios se reflejen automáticamente mientras desarrollas:
+
+```bash
+npm run dev
 ```
 
-> **Nota**: Si experimentas problemas con los enlaces, prueba eliminar `node_modules` y el `package-lock.json` del proyecto consumidor y volver a instalar.
+Esto ejecuta `vite build --watch` y recompila automáticamente cuando hay cambios.
+
+> **Nota**: Si usas `package.dev.json` (apuntando a `./src/`), no necesitas watch mode porque los cambios en el código fuente se reflejan directamente.
+
+---
+
+### 📘 Nota para los no familiarizados con npm
+
+Este proyecto tiene **dos lugares separados**:
+
+#### 1. GitHub (código fuente)
 
-## 📄 Licencia
+```
+https://github.com/Lefebvre-El-Derecho-SA/lf-pagebuilder-vue
+```
+
+Aquí es donde se **edita el código**. Los cambios que hagas aquí NO se reflejan automáticamente en los proyectos que usan el paquete.
+
+#### 2. npm (paquete distribuido)
+
+```
+https://www.npmjs.com/package/lf-pagebuilder-vue
+```
 
-MIT © Lefebvre-El-Derecho-SA
+Aquí es donde las webs **descargan el paquete** cuando hacen `npm install`. Esta versión va **separada de GitHub**.
+
+#### ¿Cómo actualizar el paquete en npm?
+
+Para que los cambios en GitHub lleguen a npm, hay que **publicar una nueva versión**:
+
+1. **Subir la versión** en `package.json` (y en `package.dev.json` y `package.prod.json`)
+   
+   > ⚠️ Si no subes la versión, npm rechazará la publicación.
+
+2. **Asegurarte de usar la configuración de producción**:
+   ```bash
+   cp package.prod.json package.json
+   ```
+
+3. **Compilar y publicar**:
+   ```bash
+   npm run build
+   npm publish --access public
+   ```
+
+#### Configurar acceso a npm (primera vez)
+
+Para poder publicar, necesitas pertenecer a la organización de npm:
+
+1. **Solicitar acceso** al equipo `desarrollowebteamlef` en:
+   ```
+   https://www.npmjs.com/settings/desarrollowebteamlef/packages
+   ```
+
+2. **Crear un token de acceso** en npm:
+   - Ve a tu perfil de npm → Access Tokens → Generate New Token
+   - Selecciona "Bypass 2FA" (si aplica)
+   - Pon expiración de 90 días
+   - Copia el token generado
+
+3. **Configurar el token** en tu máquina:
+   
+   Edita (o crea) el archivo `~/.npmrc`:
+   ```bash
+   # Linux/Mac
+   nano ~/.npmrc
+   
+   # Añadir esta línea con tu token:
+   //registry.npmjs.org/:_authToken=TU_TOKEN_AQUI
+   ```
+
+4. **Ya puedes publicar**:
+   ```bash
+   npm publish --access public
+   ```