SDK: Standardize React Component CSS Classes and HTML Structure

[rjvelazco]

Caution

THESE ARE BREAKING CHANGES AND SHOULD BE DOCUMENTED

Parent Issue

#30943

Overview

Currently, the Container component renders an extra wrapper <div> when inside the editor to initialize inline editing. This wrapper includes inline attributes such as data-dot-*. However, when styling the page, this extra <div> can disrupt user-defined CSS, leading to inconsistent layouts and unexpected behavior.

Task

1. Update the Container React component to always include the extra wrapper div.
2. Conditionally apply inline attributes (e.g., data-dot-*) to the wrapper div only when inside the editor (isInsideEditor).
3. Ensure the wrapper div has a consistent class name: dot-container.
4. Update all exposed CSS classes to include the dot- prefix (e.g., dot-container).
5. Test and verify that the change resolves styling issues for users inside and outside the editor.
6. Update relevant examples and documentation to reflect the changes.

Proposed Objective

Technical User Experience

Proposed Priority

Priority 3 - Average

Acceptance Criteria

Preview Give feedback

1. Unify HTML structure between edit/production modes
2. Always renders the extra wrapper <div> regardless of the environment.
3. Replace .container with .dot-container in all React components
4. The inline attributes (data-dot-*) are applied only when isInsideEditor is true.
5. No visible regressions occur for content rendering or inline editing workflows.
6. Document all the classes that have been added or changed. (Add a comment in this GH ticket)
7. New class names
8. Migration guide
9. Test across example sites and dotcms.com

Assumptions & Initiation Needs

• isInsideEditor reliably indicates whether the component is inside the dotCMS editor environment.
• Existing inline editing functionality depends on the data-dot-* attributes.
• The extra wrapper div does not cause rendering or structural issues when attributes are removed.

Quality Assurance Notes & Workarounds

• Verify the component behavior in editing mode (inside the editor) and live mode (outside the editor).
• Check that user-defined styles (CSS) apply consistently in both environments.
• Check that all CSS classes exposed to users/clients have the dot- prefix.
• Confirm that the attributes (data-dot-*) are not applied outside the editor, ensuring a clean DOM structure.
• Ensure no unnecessary overhead is introduced by the wrapper div.

Sub-Tasks & Estimates

1. Refactor the Container component to ensure attributes are conditionally applied.
2. Add a consistent class name (dot-container) to the wrapper div.
3. Write/update unit tests for the updated behavior:
   • Ensure attributes are present inside the editor.
   • Ensure attributes are absent outside the editor.
4. Test the changes in both editor and non-editor environments.

Documentation

• Update the React SDK documentation to clarify the wrapper div's role and behavior.
• Add examples demonstrating the component's output both inside and outside the editor.
• Include migration notes (if applicable) for developers using previous versions of the SDK.