[Spike] SDK: Develop React Hook for dotCMS UVE

[rjvelazco]

Parent Issue

#30943

Overview

Create a React hook to streamline interactions with dotCMS, focusing on editor mode. This hook will manage subscriptions and notify the editor of page loads and URL changes.

Background

Currently, a similar hook exists within our examples; however, this hook should be officially provided as part of the SDK. By doing so, we aim to enhance the developer experience, making it easier and more efficient for developers to integrate and set up a page with dotCMS. Providing this hook through the SDK will streamline the process, reducing setup time and complexity, and allowing developers to get up and running as quickly as possible.

Task

1. Develop a React hook that:

   • Notifies the editor when the page has loaded and emits the URL.
   • Subscribes to client updates to receive new data from the UVE.
   • In preview mode or outside the editor, the hook will remain inactive for now.

2. Ensure the hook:

   • Accepts fetchResponse and params as inputs.
   • Manages subscriptions effectively.
   • Cleans up subscriptions to prevent memory leaks.

3. Document the hook’s usage, including:

   • Why it requires initial data (fetchResponse and params).
   • Example scenarios for editor and preview modes.
   • Detailed API documentation for developers.

4. Ensure all methods used in the hook are part of the public API for flexibility in custom implementations.

5. Update relevant examples to incorporate the new hook.

Proposed Objective

Technical User Experience

Proposed Priority

Priority 3 - Average

Acceptance Criteria

Acceptance Criteria

Preview Give feedback

1. A new React hook is implemented that notifies the editor of page loads and subscribes to client updates in edit mode.
2. The hook is inactive in preview mode or outside the editor.
3. All methods used within the hook are part of the public API.
4. The hook’s usage and parameters are fully documented.
5. Examples are updated to showcase the new hook.
6. Subscription management is handled efficiently, with proper cleanup to avoid memory leaks.
7. Compatibility across current and future React versions is ensured.

External Links... Slack Conversations, Support Tickets, Figma Designs, etc.

• Google Doc

Challenges and Considerations

1. Compatibility Across React Versions:

   • We need to ensure that the hook is compatible with future versions of React. If developed using React 18, we must evaluate how well it can be supported and maintained in subsequent React versions to ensure long-term usability and stability.

2. Public API Accessibility:

   • All methods used within the hook should be part of the public API. This ensures that developers have the flexibility to customize or extend the hook’s functionality as needed for their specific use cases.

3. Efficient Subscription Management:

   • Proper handling of subscriptions is crucial to prevent memory leaks. We need to ensure that all subscriptions are correctly managed and cleaned up to maintain optimal performance.

4. Fallback and Error Handling:

   • Implement robust error handling and fallback mechanisms to ensure the hook behaves predictably in various environments, especially in cases where data or the editor state is not immediately available.

5. Documentation and Developer Guidance:

   • Comprehensive documentation is necessary to guide developers on how to use the hook effectively. This includes example use cases, detailed explanations of parameters, and best practices for integrating with dotCMS.

6. Performance Impact:

   • Evaluate the performance impact of the hook, especially when subscribing to client updates. Ensure that the hook does not introduce significant latency or performance bottlenecks in the application.

7. Backward Compatibility:

   • Consider any potential backward compatibility issues, especially for developers currently using custom hooks or solutions. Provide clear migration guidance if necessary.

Pseudo-Code Example

function useDotCMS(fetchResponse: FetchResponse, params: FetchParams) {
    const [data, setData] = useState(initialData);
    
    useEffect(() => {
        if (!isEditor()) return;
        const subscription = client.subscribe(params).subscribe(setData);
        return () => subscription.unsubscribe();
    }, [params]);

    useEffect(() => {
        if (!isEditor()) return;
        notifyEditor(params);
    }, [params.url]);

    return data;
}