@nextsparkjs/theme-default 0.1.0-beta.20 → 0.1.0-beta.21

package/tests/cypress/e2e/_docs/README.md

@@ -0,0 +1,215 @@
+# Cypress Documentation Videos
+
+This directory contains Cypress tests designed to generate documentation videos with narration support.
+
+## Concept
+
+Instead of manually recording tutorial videos, we use Cypress tests that:
+1. **Slow down execution** to human-readable speed using `cypress-slow-down`
+2. **Add narration markers** that are saved as JSON for post-processing
+3. **Highlight elements** visually during important steps
+4. **Generate MP4 videos** automatically via Cypress video recording
+
+## Quick Start
+
+### Run a documentation test
+
+```bash
+# Interactive mode (watch the test execute)
+NEXT_PUBLIC_ACTIVE_THEME=default pnpm cy:open
+
+# Headless mode (generates video file)
+NEXT_PUBLIC_ACTIVE_THEME=default pnpm cy:run --spec "**/teams-system.doc.cy.ts"
+```
+
+### Output Files
+
+After running, you'll find:
+- **Video**: `cypress/videos/docs/tutorials/teams-system.doc.cy.ts.mp4`
+- **Narrations**: `cypress/docs-output/narrations/teams-system.doc-narrations.json`
+
+## File Structure
+
+```
+cypress/e2e/docs/
+├── README.md                    # This file
+└── tutorials/
+    ├── teams-system.doc.cy.ts   # The actual Cypress test
+    └── teams-system.narration.json  # Narration script (reference)
+
+cypress/docs-output/
+└── narrations/
+    └── teams-system.doc-narrations.json  # Generated narration timing
+```
+
+## Creating a New Documentation Video
+
+### 1. Plan the narration
+
+Create a `.narration.json` file with your script:
+
+```json
+{
+  "title": "Feature Name Tutorial",
+  "chapters": [
+    {
+      "id": "intro",
+      "title": "Introduction",
+      "narrations": [
+        {
+          "step": 1,
+          "text": "Welcome to this tutorial...",
+          "action": "none",
+          "estimatedSeconds": 5
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 2. Create the test file
+
+Use the `*.doc.cy.ts` naming convention:
+
+```typescript
+import { slowCypressDown } from 'cypress-slow-down'
+import 'cypress-slow-down/commands'
+
+const CONFIG = {
+  commandDelay: 600,  // ms between commands
+  narration: {
+    short: 2500,
+    medium: 4000,
+    long: 5500,
+  }
+}
+
+describe('Tutorial: Feature Name', { tags: ['@doc'] }, () => {
+  before(() => {
+    slowCypressDown(CONFIG.commandDelay)
+  })
+
+  it('demonstrates the feature', () => {
+    // Chapter marker
+    cy.log('📖 **CHAPTER: Introduction**')
+    cy.wait(2000)
+
+    // Narration with wait
+    cy.log('🎙️ Welcome to this tutorial about...')
+    cy.wait(4000)  // Time for narration
+
+    // Your test actions...
+    cy.visit('/some-page')
+
+    // Highlight important elements
+    cy.get('[data-cy="important"]').then($el => {
+      $el.css({ outline: '4px solid red' })
+    })
+    cy.wait(2000)  // Let viewer see highlight
+  })
+})
+```
+
+### 3. Run and collect outputs
+
+```bash
+# Generate video and narrations
+NEXT_PUBLIC_ACTIVE_THEME=default pnpm cy:run --spec "**/your-feature.doc.cy.ts"
+```
+
+## Post-Processing Pipeline
+
+The generated outputs can be processed with AI tools:
+
+### Video + Narrations → Final Documentation
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│  Cypress Video  │    │  Narration JSON │    │   AI Service    │
+│  (MP4, no audio)│───►│  (timestamps)   │───►│  (Guidde/HeyGen)│
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                                                      │
+                                                      ▼
+                                              ┌─────────────────┐
+                                              │  Final Video    │
+                                              │  + AI Narration │
+                                              │  + Subtitles    │
+                                              └─────────────────┘
+```
+
+### Narration JSON Format
+
+The generated `*-narrations.json` contains:
+
+```json
+[
+  {
+    "timestamp": 1702400000000,
+    "step": 1,
+    "text": "=== Introduction ===",
+    "chapter": "Introduction",
+    "duration": 2500
+  },
+  {
+    "timestamp": 1702400002500,
+    "step": 2,
+    "text": "Welcome to this tutorial...",
+    "duration": 4000
+  }
+]
+```
+
+This can be used to:
+- Generate SRT subtitle files
+- Send to text-to-speech APIs (ElevenLabs, Google TTS)
+- Sync audio with video using FFmpeg
+
+## Speed Configuration
+
+Adjust the `commandDelay` and narration durations based on your needs:
+
+| Setting | Value | Use Case |
+|---------|-------|----------|
+| `commandDelay: 300` | Fast | Quick demos |
+| `commandDelay: 600` | Normal | Standard tutorials |
+| `commandDelay: 1000` | Slow | Detailed explanations |
+
+### Narration Timing Guide
+
+| Duration | Words | Use For |
+|----------|-------|---------|
+| 2500ms | ~8-10 | Short phrases |
+| 4000ms | ~15-18 | Standard sentences |
+| 5500ms | ~22-25 | Longer explanations |
+
+## Tips
+
+1. **Use `cy.wait()` strategically** - Add pauses after important actions
+2. **Highlight sparingly** - Only highlight what you're talking about
+3. **Chapter markers** - Help viewers navigate in longer videos
+4. **Test first without slow-down** - Ensure test passes before recording
+5. **Keep videos under 5 minutes** - Split longer tutorials into parts
+
+## Running Only Doc Tests
+
+Use tags to filter:
+
+```bash
+# Run only documentation tests
+pnpm cy:run --env grepTags=@doc
+
+# Run only tutorial tests
+pnpm cy:run --env grepTags=@tutorial
+
+# Exclude doc tests from regular test runs
+pnpm cy:run --env grepTags=-@doc
+```
+
+## Future Enhancements
+
+- [ ] Automated subtitle generation script
+- [ ] Integration with AI narration APIs
+- [ ] FFmpeg post-processing script
+- [ ] Multi-language support
+- [ ] Automated upload to docs site

package/tests/cypress/e2e/_docs/tutorials/sector7-superadmin-teams.narration.json

@@ -0,0 +1,155 @@
+{
+  "title": "Sector 7 - SuperAdmin Teams View",
+  "description": "Tutorial que muestra cómo un super administrador puede acceder a Sector 7 y visualizar todos los equipos del sistema.",
+  "language": "es",
+  "estimatedDuration": "1-1:30 minutos",
+  "targetAudience": "Usuarios finales con rol superadmin",
+  "chapters": [
+    {
+      "id": "intro",
+      "title": "Introducción",
+      "narrations": [
+        {
+          "step": 1,
+          "text": "Bienvenido a Sector 7, el área exclusiva para super administradores.",
+          "action": "none",
+          "estimatedSeconds": 4
+        },
+        {
+          "step": 2,
+          "text": "Hoy veremos cómo acceder y visualizar todos los equipos del sistema.",
+          "action": "none",
+          "estimatedSeconds": 4
+        }
+      ]
+    },
+    {
+      "id": "login",
+      "title": "Login como SuperAdmin",
+      "narrations": [
+        {
+          "step": 3,
+          "text": "Iniciamos sesión con las credenciales de superadmin.",
+          "action": "visit-login",
+          "estimatedSeconds": 3
+        },
+        {
+          "step": 4,
+          "text": "Usamos el email del superadmin de prueba.",
+          "action": "fill-email",
+          "estimatedSeconds": 4
+        },
+        {
+          "step": 5,
+          "text": "Ingresamos la contraseña y enviamos.",
+          "action": "fill-password-submit",
+          "estimatedSeconds": 5
+        },
+        {
+          "step": 6,
+          "text": "Acceso concedido. Observa el icono de Sector 7 en la barra superior.",
+          "action": "highlight-sector7-icon",
+          "estimatedSeconds": 5
+        }
+      ]
+    },
+    {
+      "id": "navigation",
+      "title": "Navegación a Sector 7",
+      "narrations": [
+        {
+          "step": 7,
+          "text": "Hacemos clic para ingresar al área restringida.",
+          "action": "click-sector7",
+          "estimatedSeconds": 3
+        },
+        {
+          "step": 8,
+          "text": "Este es el panel de control del super administrador.",
+          "action": "show-dashboard",
+          "estimatedSeconds": 5
+        },
+        {
+          "step": 9,
+          "text": "En el menú lateral vemos las opciones disponibles.",
+          "action": "highlight-teams-nav",
+          "estimatedSeconds": 4
+        }
+      ]
+    },
+    {
+      "id": "teams-view",
+      "title": "Visualización de Teams",
+      "narrations": [
+        {
+          "step": 10,
+          "text": "Navegamos a la sección de Equipos.",
+          "action": "click-teams-nav",
+          "estimatedSeconds": 3
+        },
+        {
+          "step": 11,
+          "text": "Aquí vemos todos los equipos del sistema con estadísticas.",
+          "action": "show-stats",
+          "estimatedSeconds": 5
+        },
+        {
+          "step": 12,
+          "text": "La pestaña Work Teams muestra equipos colaborativos.",
+          "action": "highlight-work-tab",
+          "estimatedSeconds": 4
+        },
+        {
+          "step": 13,
+          "text": "También podemos ver los equipos personales de cada usuario.",
+          "action": "click-personal-tab",
+          "estimatedSeconds": 5
+        },
+        {
+          "step": 14,
+          "text": "El buscador permite filtrar equipos por nombre o email del propietario.",
+          "action": "highlight-search",
+          "estimatedSeconds": 4
+        }
+      ]
+    },
+    {
+      "id": "conclusion",
+      "title": "Conclusión",
+      "narrations": [
+        {
+          "step": 15,
+          "text": "Así funciona Sector 7: acceso exclusivo a la gestión global del sistema.",
+          "action": "none",
+          "estimatedSeconds": 5
+        },
+        {
+          "step": 16,
+          "text": "Gracias por ver este tutorial.",
+          "action": "none",
+          "estimatedSeconds": 3
+        }
+      ]
+    }
+  ],
+  "totalSteps": 16,
+  "technicalNotes": {
+    "users": {
+      "superadmin": "superadmin@cypress.com",
+      "password": "Pandora1234"
+    },
+    "routes": [
+      "/login",
+      "/dashboard",
+      "/sector7",
+      "/sector7/teams"
+    ],
+    "selectors": {
+      "topnavSector7": "[data-cy='topnav-sector7']",
+      "sector7NavTeams": "[data-cy='sector7-nav-teams']",
+      "teamsSearchInput": "[data-cy='teams-search-input']",
+      "workTeamsTab": "[value='work']",
+      "personalTeamsTab": "[value='personal']"
+    }
+  }
+}