@nextsparkjs/theme-default 0.1.0-beta.17 → 0.1.0-beta.170

package/tests/cypress/e2e/_utils/devtools/pages.bdd.md

@@ -0,0 +1,303 @@
+---
+feature: DevTools Page Content
+priority: high
+tags: [dev-area, pages, content]
+grepTags: [uat, feat-dev-area, regression]
+coverage: 6
+---
+
+# DevTools Page Content
+
+> Tests the content and functionality of each /devtools page including Home quick links, Style Gallery components, Test Cases viewer, and Config viewer tabs.
+
+## @test PAGE-001: Home page renders quick links
+
+### Metadata
+- **Priority:** High
+- **Type:** Smoke
+- **Tags:** home, quick-links
+- **Grep:** `@smoke`
+
+```gherkin:en
+Scenario: Display all quick link cards on home page
+
+Given I am logged in as Developer (developer@nextspark.dev)
+When I visit /devtools home
+Then the home page container should be visible
+And all quick links should be visible (Style, Tests, Config)
+
+When I click Style Gallery quick link
+Then I should be on /devtools/style
+
+When I go back to /devtools home
+And I click Test Cases quick link
+Then I should be on /devtools/tests
+
+When I go back to /devtools home
+And I click Config Viewer quick link
+Then I should be on /devtools/config
+```
+
+```gherkin:es
+Scenario: Mostrar todas las tarjetas de enlaces rapidos en home
+
+Given estoy logueado como Developer (developer@nextspark.dev)
+When visito /devtools home
+Then el contenedor de home page deberia estar visible
+And todos los enlaces rapidos deberian estar visibles (Style, Tests, Config)
+
+When hago clic en el enlace rapido Style Gallery
+Then deberia estar en /devtools/style
+
+When vuelvo a /devtools home
+And hago clic en el enlace rapido Test Cases
+Then deberia estar en /devtools/tests
+
+When vuelvo a /devtools home
+And hago clic en el enlace rapido Config Viewer
+Then deberia estar en /devtools/config
+```
+
+### Expected Results
+- Home page container visible
+- All 3 quick link cards displayed
+- Each quick link navigates correctly
+- All target pages load successfully
+
+---
+
+## @test PAGE-002: Style Gallery loads components
+
+### Metadata
+- **Priority:** High
+- **Type:** Smoke
+- **Tags:** style-gallery, components, tabs
+
+```gherkin:en
+Scenario: Display all Style Gallery sections
+
+Given I am logged in as Developer (developer@nextspark.dev)
+When I visit /devtools/style
+Then the style page should be visible
+
+And I verify all tab sections by clicking through them:
+| Tab | Content Section |
+| Components | Component Gallery |
+| Field Types | Field Types Gallery |
+| Theme | Theme Preview |
+```
+
+```gherkin:es
+Scenario: Mostrar todas las secciones de Style Gallery
+
+Given estoy logueado como Developer (developer@nextspark.dev)
+When visito /devtools/style
+Then la pagina de estilos deberia estar visible
+
+And verifico todas las secciones de tabs haciendo clic en cada una:
+| Tab | Seccion de Contenido |
+| Components | Component Gallery |
+| Field Types | Field Types Gallery |
+| Theme | Theme Preview |
+```
+
+### Expected Results
+- Style page container visible
+- Components tab visible by default
+- Field Types tab content loads on click
+- Theme tab content loads on click
+
+---
+
+## @test PAGE-003a: Test Cases viewer shows file tree
+
+### Metadata
+- **Priority:** High
+- **Type:** Smoke
+- **Tags:** test-cases, file-tree
+
+```gherkin:en
+Scenario: Display test cases viewer with file tree
+
+Given I am logged in as Developer (developer@nextspark.dev)
+When I visit /devtools/tests
+Then the tests page should be visible
+And the viewer container should be visible
+And either file tree or empty state should be displayed
+```
+
+```gherkin:es
+Scenario: Mostrar visor de test cases con arbol de archivos
+
+Given estoy logueado como Developer (developer@nextspark.dev)
+When visito /devtools/tests
+Then la pagina de tests deberia estar visible
+And el contenedor del visor deberia estar visible
+And deberia mostrarse el arbol de archivos o estado vacio
+```
+
+### Expected Results
+- Tests page container visible
+- Viewer component rendered
+- File tree shows .bdd.md files (or empty state)
+
+---
+
+## @test PAGE-003b: Test Cases viewer shows markdown content
+
+### Metadata
+- **Priority:** Medium
+- **Type:** Regression
+- **Tags:** test-cases, markdown, file-select
+
+```gherkin:en
+Scenario: Show markdown content when selecting a file
+
+Given I am on /devtools/tests
+When I check if file tree has files
+And files exist
+And I click on the first file
+Then the content area should be visible
+And markdown content should be rendered
+```
+
+```gherkin:es
+Scenario: Mostrar contenido markdown al seleccionar un archivo
+
+Given estoy en /devtools/tests
+When verifico si el arbol de archivos tiene archivos
+And existen archivos
+And hago clic en el primer archivo
+Then el area de contenido deberia estar visible
+And el contenido markdown deberia estar renderizado
+```
+
+### Expected Results
+- File selection works
+- Markdown content loads
+- Content is properly formatted
+
+---
+
+## @test PAGE-004a: Config viewer shows tabs
+
+### Metadata
+- **Priority:** High
+- **Type:** Smoke
+- **Tags:** config, tabs
+
+```gherkin:en
+Scenario: Display config viewer with tabs
+
+Given I am logged in as Developer (developer@nextspark.dev)
+When I visit /devtools/config
+Then the config page should be visible
+And config tabs should be visible (Theme, Entities)
+
+When I click Theme tab
+Then Theme content should be visible
+
+When I click Entities tab
+Then Entities content should be visible
+```
+
+```gherkin:es
+Scenario: Mostrar visor de config con tabs
+
+Given estoy logueado como Developer (developer@nextspark.dev)
+When visito /devtools/config
+Then la pagina de config deberia estar visible
+And los tabs de config deberian estar visibles (Theme, Entities)
+
+When hago clic en el tab Theme
+Then el contenido de Theme deberia estar visible
+
+When hago clic en el tab Entities
+Then el contenido de Entities deberia estar visible
+```
+
+### Expected Results
+- Config page container visible
+- Theme and Entities tabs visible
+- Tab switching works correctly
+- Each tab shows correct content
+
+---
+
+## @test PAGE-004b: Config viewer shows copy buttons
+
+### Metadata
+- **Priority:** Medium
+- **Type:** Regression
+- **Tags:** config, copy-buttons
+
+```gherkin:en
+Scenario: Display copy buttons in config viewer
+
+Given I am on /devtools/config
+When I click Theme tab
+Then copy button for theme config should be visible
+
+When I click Entities tab
+Then copy button for entities config should be visible
+```
+
+```gherkin:es
+Scenario: Mostrar botones de copia en el visor de config
+
+Given estoy en /devtools/config
+When hago clic en el tab Theme
+Then el boton de copia para config de theme deberia estar visible
+
+When hago clic en el tab Entities
+Then el boton de copia para config de entities deberia estar visible
+```
+
+### Expected Results
+- Copy buttons present in both tabs
+- Copy functionality available for developers
+
+---
+
+## UI Elements
+
+| Element | Selector | Description |
+|---------|----------|-------------|
+| Home Page | `[data-cy="dev-home-page"]` | Dev home page container |
+| Home Style Link | `[data-cy="dev-home-style-link"]` | Quick link to Style Gallery |
+| Home Tests Link | `[data-cy="dev-home-tests-link"]` | Quick link to Test Cases |
+| Home Config Link | `[data-cy="dev-home-config-link"]` | Quick link to Config Viewer |
+| Style Page | `[data-cy="dev-style-page"]` | Style Gallery page container |
+| Style Tab Components | `[data-cy="dev-style-tab-components"]` | Components tab trigger |
+| Style Tab Field Types | `[data-cy="dev-style-tab-field-types"]` | Field Types tab trigger |
+| Style Tab Theme | `[data-cy="dev-style-tab-theme"]` | Theme tab trigger |
+| Style Component Gallery | `[data-cy="dev-style-component-gallery"]` | Components tab content |
+| Style Field Types | `[data-cy="dev-style-field-types"]` | Field Types tab content |
+| Style Theme Preview | `[data-cy="dev-style-theme-preview"]` | Theme tab content |
+| Tests Page | `[data-cy="dev-tests-page"]` | Test Cases page container |
+| Tests Viewer | `[data-cy="dev-tests-viewer"]` | Test viewer container |
+| Tests Tree | `[data-cy="dev-tests-tree"]` | File tree component |
+| Tests Empty State | `[data-cy="dev-tests-empty-state"]` | Empty state when no files |
+| Tests Content | `[data-cy="dev-tests-content"]` | Content display area |
+| Tests Markdown | `[data-cy="dev-tests-markdown-content"]` | Rendered markdown content |
+| Config Page | `[data-cy="dev-config-page"]` | Config Viewer page container |
+| Config Viewer | `[data-cy="dev-config-viewer"]` | Config viewer container |
+| Config Tab Theme | `[data-cy="dev-config-tab-theme"]` | Theme tab trigger |
+| Config Tab Entities | `[data-cy="dev-config-tab-entities"]` | Entities tab trigger |
+| Config Theme Content | `[data-cy="dev-config-theme-content"]` | Theme config content |
+| Config Entities Content | `[data-cy="dev-config-entities-content"]` | Entities config content |
+| Config Copy Theme | `[data-cy="dev-config-copy-theme"]` | Copy theme config button |
+| Config Copy Entities | `[data-cy="dev-config-copy-entities"]` | Copy entities config button |
+
+---
+
+## Summary
+
+| Test ID | Block | Description | Tags |
+|---------|-------|-------------|------|
+| PAGE-001 | Home Page | Quick links display and work | `@smoke` |
+| PAGE-002 | Style Gallery | All tab sections load | |
+| PAGE-003a | Test Cases | File tree viewer works | |
+| PAGE-003b | Test Cases | Markdown content renders | |
+| PAGE-004a | Config Viewer | Tabs display and switch | |
+| PAGE-004b | Config Viewer | Copy buttons available | |

package/tests/cypress/e2e/_utils/devtools/pages.cy.ts

@@ -0,0 +1,184 @@
+/// <reference types="cypress" />
+
+import * as allure from 'allure-cypress'
+import { DevtoolsPOM } from '../../../src/features/DevtoolsPOM'
+import { loginAsDefaultDeveloper } from '../../../src/session-helpers'
+
+/**
+ * DevTools Page Content Tests
+ *
+ * Tests the content and functionality of each /devtools page:
+ * - Home page renders quick links
+ * - Style Gallery loads all components
+ * - Test Cases viewer shows file tree
+ * - Config viewer shows tabs and content
+ *
+ * Test User:
+ * - Developer: developer@nextspark.dev (via loginAsDefaultDeveloper)
+ */
+
+describe('DevTools - Page Content', {
+  tags: ['@uat', '@area-devtools', '@regression']
+}, () => {
+  const devtools = DevtoolsPOM.create()
+
+  beforeEach(() => {
+    allure.epic('UAT')
+    allure.feature('DevTools')
+    allure.story('Page Content')
+
+    // Login as developer before each test
+    loginAsDefaultDeveloper()
+  })
+
+  describe('PAGE-001: Home page renders quick links', () => {
+    it('should display all quick link cards on home page', () => {
+      allure.severity('high')
+
+      // 1. Visit /devtools home
+      devtools.visitHome()
+
+      // 2. Verify page container is visible
+      devtools.assertHomePageVisible()
+
+      // 3. Verify all quick links are visible
+      devtools.assertHomeQuickLinksVisible()
+
+      // 4. Verify quick links are clickable and navigate correctly
+      cy.log('Testing Style Gallery quick link...')
+      devtools.clickHomeStyleLink()
+      devtools.assertOnStyleGallery()
+
+      cy.log('Testing Test Cases quick link...')
+      devtools.visitHome()
+      devtools.clickHomeTestsLink()
+      devtools.assertOnTestCases()
+
+      cy.log('Testing Config Viewer quick link...')
+      devtools.visitHome()
+      devtools.clickHomeConfigLink()
+      devtools.assertOnConfig()
+
+      cy.log(`✅ Home page quick links work correctly`)
+    })
+  })
+
+  describe('PAGE-002: Style Gallery loads components', () => {
+    it('should display all Style Gallery sections', () => {
+      allure.severity('high')
+
+      // 1. Visit /devtools/style
+      devtools.visitStyleGallery()
+
+      // 2. Verify page is visible
+      devtools.assertStylePageVisible()
+
+      // 3. Verify all tab sections by clicking through them
+      // (assertStyleSectionsVisible clicks each tab and verifies content)
+      devtools.assertStyleSectionsVisible()
+
+      cy.log(`✅ Style Gallery sections loaded correctly`)
+    })
+  })
+
+  describe('PAGE-003: Test Cases viewer shows file tree', () => {
+    it('should display test cases viewer with file tree', () => {
+      allure.severity('high')
+
+      // 1. Visit /devtools/tests
+      devtools.visitTestCases()
+
+      // 2. Verify page is visible
+      devtools.assertTestsPageVisible()
+
+      // 3. Verify viewer container is visible
+      devtools.assertTestsViewerVisible()
+
+      // 4. Verify file tree is present (or empty state if no files)
+      cy.get('body').then(($body) => {
+        if ($body.find(devtools.selectors.testsTree).length > 0) {
+          // File tree exists
+          cy.get(devtools.selectors.testsTree).should('be.visible')
+          cy.log('✅ File tree displayed')
+        } else if ($body.find(devtools.selectors.testsEmptyState).length > 0) {
+          // Empty state (no test files)
+          cy.get(devtools.selectors.testsEmptyState).should('be.visible')
+          cy.log('✅ Empty state displayed (no test files found)')
+        }
+      })
+
+      cy.log(`✅ Test Cases viewer loaded correctly`)
+    })
+
+    it('should show markdown content when selecting a file', () => {
+      allure.severity('medium')
+
+      // 1. Visit /devtools/tests
+      devtools.visitTestCases()
+
+      // 2. Check if file tree has files
+      cy.get('body').then(($body) => {
+        if ($body.find('[data-cy^="dev-tests-file-"]').length > 0) {
+          // Files exist - click first file
+          cy.get('[data-cy^="dev-tests-file-"]').first().click()
+
+          // 3. Verify markdown content is displayed
+          cy.get(devtools.selectors.testsContent).should('be.visible')
+          cy.get(devtools.selectors.testsMarkdownContent).should('be.visible')
+
+          cy.log('✅ File content displayed when selected')
+        } else {
+          cy.log('⚠️ No test files found - skipping file selection test')
+        }
+      })
+    })
+  })
+
+  describe('PAGE-004: Config viewer shows tabs', () => {
+    it('should display config viewer with tabs', () => {
+      allure.severity('high')
+
+      // 1. Visit /devtools/config
+      devtools.visitConfig()
+
+      // 2. Verify page is visible
+      devtools.assertConfigPageVisible()
+
+      // 3. Verify tabs are visible
+      devtools.assertConfigTabsVisible()
+
+      // 4. Test Theme tab
+      cy.log('Testing Theme tab...')
+      devtools.clickConfigTabTheme()
+      cy.get(devtools.selectors.configThemeContent).should('be.visible')
+
+      // 5. Test Entities tab
+      cy.log('Testing Entities tab...')
+      devtools.clickConfigTabEntities()
+      cy.get(devtools.selectors.configEntitiesContent).should('be.visible')
+
+      cy.log(`✅ Config viewer tabs work correctly`)
+    })
+
+    it('should display copy buttons in config viewer', () => {
+      allure.severity('medium')
+
+      // 1. Visit /devtools/config
+      devtools.visitConfig()
+
+      // 2. Verify copy buttons exist for theme config
+      devtools.clickConfigTabTheme()
+      cy.get(devtools.selectors.configCopyTheme).should('be.visible')
+
+      // 3. Verify copy buttons exist for entities config
+      devtools.clickConfigTabEntities()
+      cy.get(devtools.selectors.configCopyEntities).should('be.visible')
+
+      cy.log(`✅ Copy buttons displayed correctly`)
+    })
+  })
+
+  after(() => {
+    cy.log('✅ DevTools page content tests completed')
+  })
+})

package/tests/cypress/e2e/_utils/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