[EPIC]: Universal Visual Editor and SDK Stable Release

[rjvelazco]

Overview

Transform the dotCMS Universal Visual Editor (UVE) and JavaScript SDK from alpha to a production-ready, stable release by addressing core architectural challenges, improving the developer experience, and ensuring reliable content-editing capabilities across frameworks.

Goals

1. Core Architecture

   • Implement unified content fetching through GraphQL and Navigation API
   • Create reliable UVE detection for both server and client environments
   • Establish stable communication between UVE and client applications
   • Resolve the preview mode/isInsideEditor functionality

2. Developer Experience

   • Eliminate redundant configuration requirements
   • Standardize component CSS classes and HTML structure
   • Improve error handling and debugging capabilities
   • Clean up SDK exports and provide clear public APIs

3. Content Management

   • Enable content editing anywhere on the page
   • Implement a reliable content subscription mechanism
   • Support complex data requirements through GraphQL
   • Handle both server-side and client-side data fetching

4. Framework Support

   • Ensure compatibility with core LTS versions
   • Provide framework-agnostic core libraries
   • Maintain backward compatibility where possible

Non-Goals:

• Real-time in-memory page state updates.
• Complex caching (handled by dotCMS CDN)
• Advanced performance optimizations.
• Establishing monitoring systems.

Requirements

Functional Requirements

1. SDK Enhancements

   • Support GraphQL queries for unified content fetching.
   • Enable real-time subscriptions to content updates.
   • Provide robust UVE detection for both client and server environments.

2. Three Pillars Integration

   • Content: Standardize content queries for flexibility in fetching.
   • Page: Support editable pages with full compatibility in UVE.
   • Navigation: Ensure reliable fetching and rendering of navigation data.

3. Framework Support

   • React hooks, Angular services, and Next.js utilities for seamless integration.
   • Maintain compatibility with LTS versions of frameworks.

4. Developer Experience

   • Simplify configuration and API usage.
   • Provide migration guides and examples to ease the transition from older SDKs.
   • Eliminate redundant or excessive HTML elements.

Non-Functional Requirements

• Optimize performance for high-traffic use cases with query batching.
• Ensure compatibility with existing dotCMS workflows.
• Conduct a thorough security audit of the SDK.

Phases and Milestones

Phase 1: Core Implementation

• Setup communication layer
• Implement GraphQL integration and query merging
• Establish UVE detection (server/client)
• Create React hooks and Angular solutions
• Standardize component structure and CSS

Phase 2: Framework Support

• Implement framework-specific integrations
• Ensure compatibility with LTS versions of React, Angular, and Next.js.
• Update documentation
• Develop migration guides

Phase 3: Testing & Release

• Comprehensive testing
• Performance optimization
• Security audit
• Beta and stable release

Acceptance Criteria

1. Core Functionality

• GraphQL integration supports query merging and subscriptions
• UVE detection works reliably in all environments
• Preview mode and isInsideEditor function correctly
• Content subscription provides consistent updates
• Navigation handles without redundant API calls
• Content editing works anywhere on the page

2. Developer Experience

• No manual parameter formatting is required
• Error boundaries prevent application crashes
• Standardized component CSS classes and HTML structure
• Clean SDK exports with clear public/private separation
• Comprehensive error messages and debugging information

3. Framework Support

• Working implementations for:
  • Next.js
  • Angular
  • Astro
• Example applications demonstrating:
  • Editable listing pages
  • Editable detail pages
  • Content editing outside layout
  • Navigation integration
  • GraphQL usage

4. Documentation & Testing

• Complete migration guide from alpha
• Framework-specific integration guides
• API documentation
• Test coverage >80%
• Security audit passed
• Performance benchmark documentation

5. Performance & Stability

• Zero subscription overhead in production
• SSR performance within acceptable limits
• No memory leaks in long-running sessions
• Stable under high concurrent edit load

Dependencies

• GraphQL API enhancements
• Core backend support for subscriptions
• Framework compatibility requirements
• Security requirements for iframe sandbox

Risks

• Framework compatibility challenges
• Performance impact of real-time updates
• Migration complexity for existing implementations
• Security considerations for iframe communication

Resources

• Design Doc: Research and Improve dotCMS SDK & UVE Architecture

Proposed Objective

Core Features

Proposed Priority

Priority 2 - Important

Tasks

Preview Give feedback

1. SDK: Standardize React Component CSS Classes and HTML Structure #30955
   OKR : Technical User Experience Priority : 3 Average Team : Scout Triage Type : Task +5
2. SDK: Standardize Angular Component CSS Classes and HTML Structure #30957
   OKR : Technical User Experience Priority : 3 Average Team : Scout Triage Type : Task +5
3. SDK: Unified GraphQL Query Management with Fragment Merging #30968
   OKR : Technical User Experience Priority : 2 High Team : Scout Triage Type : Task +5
4. UVE: Execute GraphQL Queries Using Client-Provided Parameters #30970
   OKR : Technical User Experience Priority : 2 High Team : Scout Triage Type : Task +5
5. SDK: Update SDK Library to Use "personaId" Key #28819
   OKR : Core Features Priority : 3 Average Team : Lunik Team : Scout Type : Defect stale +6
6. SDK: Define Public API in client SDK #31076
   OKR : Core Features Priority : 2 High Team : Scout Triage Type : Task +5
7. SDK: Add isEditMode() and isPreviewMode() Functions #31090
   OKR : Core Features Priority : 3 Average Team : Scout Triage Type : Task +5
8. UVE: Investigate Removing isClientReady and Redefining Initial Loading State Handling #31091
   OKR : Core Features Priority : 3 Average Team : Scout Triage Type : Task +5