Troubleshooting Guide

This guide provides solutions and advice for common issues you might encounter while integrating or using LeapHub AI components, such as the AI Smart Text Editor. If you can't find a solution here, please contact support.

Common Issues & Solutions

1. Text Editor Positioning Problems

The AI Smart Text Editor is designed to position its controls (like "AI Assistant" and "Dictate" buttons) intelligently relative to the target textarea. However, complex CSS layouts, specific container properties, or interactions with other JavaScript components can sometimes lead to unexpected positioning.

Understanding Control Positioning

By default, the editor's controls are positioned based on the textarea's location and dimensions. By default, an overlay is created, unless the option showOverlay is set to false. The precise behavior depends on the position option and the surrounding DOM structure.

A key option for resolving positioning problems is overlayParentContainer. This tells the editor which DOM element should serve as the reference for positioning its overlay. This is especially useful when the textarea is inside:

• Scrollable containers (overflow: auto or overflow: scroll)
• Elements with position: relative, position: fixed, or position: sticky
• Modals or dialogs
• Elements affected by CSS transforms (transform: scale(), transform: translate() etc.)

Common Scenarios and Solutions for Positioning

A. Controls are Misaligned or Detached from Textarea

• Cause: The editor might be calculating its position relative to the wrong parent element, especially if the textarea is deeply nested or within a complex layout.
• Solution:
  1. Specify overlayParentContainer: This is the most common fix. Set this option to a CSS selector (e.g., #myScrollableDiv, .modal-content) or a direct DOM element reference that is a stable, positioned ancestor of the textarea, or the scrollable container itself.

     
     // For the React component
     <TextEditor editorRef={myTextAreaRef.current} 
                 options={{ overlayParentContainer: "#scrollroot" }} />
     
     // For the vanilla JS initTextEditor
     LeapHubAI.initTextEditor("#myTextArea",
     { overlayParentContainer: "#scrollroot" });
     

  2. Check CSS Transforms: Properties like transform, filter, or perspective on any parent element of the textarea can create a new containing block, affecting absolutely positioned children (like the editor controls). If possible, try to apply overlayParentContainer to an element outside the influence of such transforms, or adjust your CSS.

B. Controls Don't Appear or Are Hidden

• Cause:
  • z-index conflicts: The controls might be rendered underneath other elements.
  • Clipping: A parent container might have overflow: hidden that clips the controls.
  • Visibility: The textarea or a parent might be hidden (display: none or visibility: hidden).
• Solution:
  1. Inspect z-index: Use browser developer tools to check the z-index of the editor controls and surrounding elements. The controls typically use a z-index, but you might need to adjust it or the z-index of other elements. Ensure the overlayParentContainer (if used) also has an appropriate stacking context.
  2. Check overflow: Ensure that parent containers, especially the overlayParentContainer, do not unintentionally clip the controls with overflow: hidden.
  3. Verify Visibility: Make sure the textarea and its relevant parents are visible.

C. Issues within Specific Container Types

• position: relative Container:

  If the editor controls use position: absolute, they will be positioned relative to the nearest ancestor that has a position value other than static (e.g., relative, absolute, fixed, or sticky). If this relative container is not the intended one, use overlayParentContainer to specify the correct context.

• position: sticky Container:

  Sticky positioning can be tricky as it behaves like relative within its flow but becomes fixed when scrolled. Test thoroughly. The overlayParentContainer might need to be the sticky container itself or a stable parent outside of it. Pay attention to z-index as sticky elements create new stacking contexts.

Debugging Steps for Positioning

1. Isolate the Problem: Temporarily remove or simplify surrounding CSS and other JavaScript components to see if the issue persists. This helps identify conflicts.
2. Use Browser Developer Tools:
   • Inspect the DOM elements of the textarea, its containers, and the generated editor controls.
   • Check their computed CSS properties: position, top, left, z-index, overflow, transform.
   • Experiment with CSS changes directly in the developer tools.
3. Refer to Examples: The standalone.html example in the ui-components/examples directory demonstrates various positioning scenarios. Compare its setup to yours.
4. Test Different position Options: Try changing the editor's position option (e.g., from bottom-right-hover to bottom-right-under) to see if the behavior changes. This can give clues about whether the issue is with the overlay logic.

When to Use overlayParentContainer

This option is your primary tool for fixing complex positioning issues. Use it when:

• The textarea is inside any scrollable element.
• The textarea is inside a modal, dialog, or popup.
• The textarea or its parents use position: fixed, position: sticky, or CSS transforms.
• The default positioning logic fails due to a complex or unusual DOM structure.
• You need the editor's overlay to be a child of a specific element for stacking context or clipping reasons.

The value for overlayParentContainer can be a CSS selector string (e.g., '#myModalBody', '.scrollable-div') or a direct reference to a DOM element (e.g., document.getElementById('myModalBody')).

More troubleshooting sections will be added here as needed.