SDK: Add uveState() function

[rjvelazco]

Parent Issue

#30943

Overview

To improve the usability and extensibility of our SDK, we will introduce a new function, uveState(). This function will provide a structured object representing the current state of the User View Environment (UVE). The state will include the mode of the UVE (EDIT, PREVIEW, or LIVE) and return null if it is outside the editor. This approach allows for future enhancements without breaking existing client implementations.

Background

While working on the Future Time Machine (FTM), we encountered difficulties in distinguishing between various UVE modes (EDIT, PREVIEW, LIVE) and in determining when custom Edit tools should be displayed or hidden.

The existing isInsideEditor function, originally designed for Edit Mode only, is now insufficient. To address this, we propose replacing it with uveState(). This function provides a structured and extensible way to retrieve UVE-related information, making the SDK more robust and developer-friendly.

Task

1. Implement uveState():

   • The function should return an object in the following format:

     const state = uveState();
     // Example:
     // state = { mode: "EDIT" | "PREVIEW" | "LIVE" };

   • If the environment is outside the UVE, the function should return null.

2. Update isInsideEditor():

   • Deprecate isInsideEditor() and update its description to reference uveState() as the recommended approach.

3. Documentation:

   • Create comprehensive documentation for uveState(), including examples of how to use it.
   • Update any relevant sections referencing isInsideEditor() to recommend the use of uveState() instead.

4. Update Examples:

   • Update existing examples to use uveState() instead of isInsideEditor().

5. Testing:

   • Thoroughly test the uveState() function to ensure it returns the correct state under different scenarios (Edit, Preview, Live, Outside Editor).

Proposed Objective

Core Features

Proposed Priority

Priority 3 - Average

Acceptance Criteria

Tasks

Preview Give feedback

1. uveState() returns an object with the correct mode (EDIT, PREVIEW, LIVE) or null when outside the editor.
2. The isInsideEditor() should be marked asa deprecated method.
3. Documentation for uveState() is complete and includes examples demonstrating its usage.
4. Examples using isInsideEditor() are updated to use uveState() instead.
5. Tests validate uveState() functionality across all supported scenarios.
6. Ensure backward compatibility with existing usage of isInsideEditor().

Use case

core/examples/nextjs/src/components/shared/contentlets.js

Lines 19 to 36 in 6a4e03c

	{insideEditor && (
	<button
	onClick={() => editContentlet(contentlet)}
	style={{
	color: 'black',
	border: '1px solid black',
	position: 'absolute',
	bottom: 0,
	right: 0,
	width: '40px',
	height: '20px',
	zIndex: 1000,
	display: 'flex',
	justifyContent: 'center',
	alignItems: 'center'
	}}>
	Edit
	</button>

We can use this new uveState to show the edit button only in Edit Mode. Example:

function MyComponent({ contentlets }) {
    const state = useMemo(uveState(), []);

    return (
        <div>
            {state.mode === 'EDIT' && (
                <button
                    onClick={() => editContentlet(contentlet)}
                    Edit
                </button>
            )}
        </div>
    );
}

Documentation

• Provide clear documentation for uveState():
  • Explain its purpose and how it improves over isInsideEditor().
  • Include examples for retrieving the UVE state and handling various modes.
• Update the isInsideEditor() documentation to highlight its deprecation and recommend using uveState().

Notes

• Extensibility: The structured object returned by uveState() allows for future additions (e.g., adding properties like userRole, siteId, etc.) without breaking existing implementations.
• Developer Clarity: Explicitly differentiating between UVE modes (Edit, Preview, Live) simplifies the developer experience and reduces potential for errors.

[fmontes]

How this will affect the #30957 and #31134? Should this happen before? also... now that we will officially have EDIT, PREVIEW, LIVE mode... isn't that will affect this?

[rjvelazco]

@fmontes This ticket was created due to the need to hide the custom editing tools that users can develop in dotCMS.

That feature we introduced in this ticket: UVE: Support #editContentlet Macro in Universal Visual Editor #30218. That kind of "Custom implementation" should only appear when the editor is in EDIT_MODE, not when going to preview.

This should be part of the public API; so users can hide any custom implementation if they want to; NOT PART of Frameworks SDK; so it should not affect this ticket: #30957