feat: add getCaretRect command and onCaretRectChange event (#234)

* feat: add getCaretRect command and onCaretRectChange event

* refactor: rename CaretRect properties for clarity

Author: hryhoriiK97

android/src/main/java/com/swmansion/enriched/markdown/input/EnrichedMarkdownInputManager.kt

@@ -15,6 +15,7 @@ import com.facebook.react.viewmanagers.EnrichedMarkdownInputManagerDelegate
 import com.facebook.react.viewmanagers.EnrichedMarkdownInputManagerInterface
 import com.facebook.yoga.YogaMeasureMode
 import com.swmansion.enriched.markdown.input.autolink.LinkRegexConfig
+import com.swmansion.enriched.markdown.input.events.OnCaretRectChangeEvent
 import com.swmansion.enriched.markdown.input.events.OnChangeMarkdownEvent
 import com.swmansion.enriched.markdown.input.events.OnChangeSelectionEvent
 import com.swmansion.enriched.markdown.input.events.OnChangeStateEvent
@@ -23,6 +24,7 @@ import com.swmansion.enriched.markdown.input.events.OnContextMenuItemPressEvent
 import com.swmansion.enriched.markdown.input.events.OnInputBlurEvent
 import com.swmansion.enriched.markdown.input.events.OnInputFocusEvent
 import com.swmansion.enriched.markdown.input.events.OnLinkDetectedEvent
+import com.swmansion.enriched.markdown.input.events.OnRequestCaretRectResultEvent
 import com.swmansion.enriched.markdown.input.events.OnRequestMarkdownResultEvent
 import com.swmansion.enriched.markdown.input.layout.InputMeasurementStore
 import com.swmansion.enriched.markdown.input.model.StyleType
@@ -83,6 +85,8 @@ class EnrichedMarkdownInputManager :
       OnChangeSelectionEvent.EVENT_NAME,
       OnChangeStateEvent.EVENT_NAME,
       OnRequestMarkdownResultEvent.EVENT_NAME,
+      OnRequestCaretRectResultEvent.EVENT_NAME,
+      OnCaretRectChangeEvent.EVENT_NAME,
       OnInputFocusEvent.EVENT_NAME,
       OnInputBlurEvent.EVENT_NAME,
       OnContextMenuItemPressEvent.EVENT_NAME,
@@ -371,6 +375,13 @@ class EnrichedMarkdownInputManager :
     view?.eventEmitter?.emitRequestMarkdownResult(requestId)
   }
 
+  override fun requestCaretRect(
+    view: EnrichedMarkdownInputView?,
+    requestId: Int,
+  ) {
+    view?.eventEmitter?.emitRequestCaretRectResult(requestId)
+  }
+
   companion object {
     const val NAME = "EnrichedMarkdownInput"
   }

android/src/main/java/com/swmansion/enriched/markdown/input/EnrichedMarkdownInputView.kt

@@ -221,6 +221,7 @@ class EnrichedMarkdownInputView(
       forceScrollToSelection()
       eventEmitter.emitChangeText()
       if (emitMarkdown) eventEmitter.emitChangeMarkdown()
+      eventEmitter.emitCaretRectChangeIfNeeded()
       isTextChanging = false
       didTextChangeRecently = true
       lastProcessedText = currentText
@@ -247,6 +248,7 @@ class EnrichedMarkdownInputView(
 
     eventEmitter.emitSelection(selStart, selEnd)
     eventEmitter.emitState()
+    eventEmitter.emitCaretRectChangeIfNeeded()
   }
 
   private fun applyPendingStyles(

android/src/main/java/com/swmansion/enriched/markdown/input/events/OnCaretRectChangeEvent.kt

@@ -0,0 +1,20 @@
+package com.swmansion.enriched.markdown.input.events
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+import com.swmansion.enriched.markdown.input.model.CaretRect
+
+class OnCaretRectChangeEvent(
+  surfaceId: Int,
+  viewId: Int,
+  private val rect: CaretRect,
+) : Event<OnCaretRectChangeEvent>(surfaceId, viewId) {
+  override fun getEventName(): String = EVENT_NAME
+
+  override fun getEventData(): WritableMap = Arguments.createMap().also { rect.putInto(it) }
+
+  companion object {
+    const val EVENT_NAME = "onCaretRectChange"
+  }
+}

android/src/main/java/com/swmansion/enriched/markdown/input/events/OnRequestCaretRectResultEvent.kt

@@ -0,0 +1,25 @@
+package com.swmansion.enriched.markdown.input.events
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.uimanager.events.Event
+import com.swmansion.enriched.markdown.input.model.CaretRect
+
+class OnRequestCaretRectResultEvent(
+  surfaceId: Int,
+  viewId: Int,
+  private val requestId: Int,
+  private val rect: CaretRect,
+) : Event<OnRequestCaretRectResultEvent>(surfaceId, viewId) {
+  override fun getEventName(): String = EVENT_NAME
+
+  override fun getEventData(): WritableMap =
+    Arguments.createMap().apply {
+      putInt("requestId", requestId)
+      rect.putInto(this)
+    }
+
+  companion object {
+    const val EVENT_NAME = "onRequestCaretRectResult"
+  }
+}

android/src/main/java/com/swmansion/enriched/markdown/input/layout/InputEventEmitter.kt

@@ -4,6 +4,7 @@ import com.facebook.react.bridge.ReactContext
 import com.facebook.react.uimanager.UIManagerHelper
 import com.facebook.react.uimanager.events.Event
 import com.swmansion.enriched.markdown.input.EnrichedMarkdownInputView
+import com.swmansion.enriched.markdown.input.events.OnCaretRectChangeEvent
 import com.swmansion.enriched.markdown.input.events.OnChangeMarkdownEvent
 import com.swmansion.enriched.markdown.input.events.OnChangeSelectionEvent
 import com.swmansion.enriched.markdown.input.events.OnChangeStateEvent
@@ -12,14 +13,17 @@ import com.swmansion.enriched.markdown.input.events.OnContextMenuItemPressEvent
 import com.swmansion.enriched.markdown.input.events.OnInputBlurEvent
 import com.swmansion.enriched.markdown.input.events.OnInputFocusEvent
 import com.swmansion.enriched.markdown.input.events.OnLinkDetectedEvent
+import com.swmansion.enriched.markdown.input.events.OnRequestCaretRectResultEvent
 import com.swmansion.enriched.markdown.input.events.OnRequestMarkdownResultEvent
 import com.swmansion.enriched.markdown.input.formatting.MarkdownSerializer
+import com.swmansion.enriched.markdown.input.model.CaretRect
 import com.swmansion.enriched.markdown.input.model.StyleType
 
 class InputEventEmitter(
   private val view: EnrichedMarkdownInputView,
 ) {
   private var prevState: Map<StyleType, Boolean> = emptyMap()
+  private var prevCaretRect: CaretRect? = null
 
   fun emitChangeText() {
     val plainText = view.text?.toString() ?: ""
@@ -82,6 +86,41 @@ class InputEventEmitter(
     dispatch(OnRequestMarkdownResultEvent(surfaceId(), view.id, requestId, serializeToMarkdown()))
   }
 
+  fun emitRequestCaretRectResult(requestId: Int) {
+    val rect = computeCaretRect()
+    dispatch(OnRequestCaretRectResultEvent(surfaceId(), view.id, requestId, rect))
+  }
+
+  fun emitCaretRectChangeIfNeeded() {
+    val rect = computeCaretRect()
+    if (rect == prevCaretRect) return
+
+    prevCaretRect = rect
+    dispatch(OnCaretRectChangeEvent(surfaceId(), view.id, rect))
+  }
+
+  private fun computeCaretRect(): CaretRect {
+    val textLayout = view.layout
+    val cursorOffset = view.selectionStart
+
+    if (textLayout == null || cursorOffset < 0) {
+      return CaretRect(0f, 0f, 0f, 0f)
+    }
+
+    val line = textLayout.getLineForOffset(cursorOffset)
+    val rawX = textLayout.getPrimaryHorizontal(cursorOffset) + view.paddingLeft
+    val rawY = (textLayout.getLineTop(line) + view.paddingTop).toFloat()
+    val rawBottom = (textLayout.getLineBottom(line) + view.paddingTop).toFloat()
+    val density = view.resources.displayMetrics.density
+
+    return CaretRect(
+      x = rawX / density,
+      y = rawY / density,
+      width = 2f / density,
+      height = (rawBottom - rawY) / density,
+    )
+  }
+
   fun emitContextMenuItemPress(
     itemText: String,
     selectedText: String,

android/src/main/java/com/swmansion/enriched/markdown/input/model/CaretRect.kt

@@ -0,0 +1,17 @@
+package com.swmansion.enriched.markdown.input.model
+
+import com.facebook.react.bridge.WritableMap
+
+data class CaretRect(
+  val x: Float,
+  val y: Float,
+  val width: Float,
+  val height: Float,
+) {
+  fun putInto(map: WritableMap) {
+    map.putDouble("x", x.toDouble())
+    map.putDouble("y", y.toDouble())
+    map.putDouble("width", width.toDouble())
+    map.putDouble("height", height.toDouble())
+  }
+}

docs/API_REFERENCE.md

@@ -381,6 +381,38 @@ interface StyleState {
 }
 ```
 
+### `onCaretRectChange`
+
+Fires when the caret's pixel position changes (typing, selection change, content reflow). The rect is relative to the input's top-left corner, in density-independent pixels. The native side diffs the rect before emitting, so redundant events are suppressed.
+
+| Type                              | Default Value | Platform |
+| --------------------------------- | ------------- | -------- |
+| `(rect: CaretRect) => void`      | -             | Both     |
+
+**`CaretRect` shape:**
+
+```ts
+interface CaretRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+```
+
+All values are in density-independent pixels, relative to the input's top-left corner.
+
+**Example:**
+
+```tsx
+<EnrichedMarkdownInput
+  scrollEnabled={false}
+  onCaretRectChange={(rect) => {
+    console.log('Caret at:', rect.x, rect.y);
+  }}
+/>
+```
+
 ### `onFocus`
 
 Fires when the input gains focus.
@@ -474,6 +506,10 @@ Sets the input content from a Markdown string. Parses the Markdown and applies f
 
 Returns a Promise that resolves with the current Markdown content. The async nature is due to the native bridge — the request is sent to the native side and the result is returned via an event.
 
+### `getCaretRect(): Promise<CaretRect>`
+
+Returns a Promise that resolves with the current caret's pixel position relative to the input. Useful for one-off queries; for continuous tracking, prefer `onCaretRectChange`.
+
 ### `setSelection(start: number, end: number)`
 
 Sets the text selection range.

docs/INPUT.md

@@ -121,6 +121,31 @@ The callback fires only for newly detected links — not for links that were alr
 
 When a manual link is applied (via `setLink` or `insertLink`) over an auto-detected link, the auto-detected link is replaced by the manual one. Auto-link detection skips ranges that already contain a manual link.
 
+## Caret Position Tracking
+
+`EnrichedMarkdownInput` can report the caret's pixel position relative to the input, which is useful when the input is embedded in a scrollable container with `scrollEnabled={false}` and you need to keep the caret visible.
+
+### `onCaretRectChange`
+
+A push-based callback that fires whenever the caret moves (typing, selection change, content reflow). The native side diffs the caret rect before emitting, so redundant events are suppressed automatically.
+
+```tsx
+<EnrichedMarkdownInput
+  scrollEnabled={false}
+  onCaretRectChange={(rect) => {
+    console.log(rect);
+  }}
+/>
+```
+
+### `getCaretRect()`
+
+An imperative, pull-based method for one-off queries. Returns a Promise that resolves with the current caret rect.
+
+```tsx
+const rect = await ref.current?.getCaretRect();
+```
+
 ## Style Detection
 
 All of the above styles can be detected with the use of [onChangeState](API_REFERENCE.md#onchangestate) callback payload.

ios/input/EnrichedMarkdownInput.mm

@@ -67,6 +67,8 @@ @implementation EnrichedMarkdownInput {
     BOOL bold, italic, underline, strikethrough, spoiler, link, initialized;
   } _prevState;
 
+  std::optional<CGRect> _prevCaretRect;
+
 #if TARGET_OS_OSX
   NSScrollView *_scrollView;
 #endif
@@ -761,6 +763,44 @@ - (void)requestMarkdown:(NSInteger)requestId
   });
 }
 
+- (CGRect)computeCaretRect
+{
+  CGRect caretRect = CGRectZero;
+#if !TARGET_OS_OSX
+  UITextRange *selectedRange = _textView.selectedTextRange;
+  if (selectedRange != nil) {
+    caretRect = [_textView caretRectForPosition:selectedRange.start];
+  }
+#else
+  NSRange selection = _textView.selectedRange;
+  if (selection.location != NSNotFound) {
+    NSRange glyphRange = [_textView.layoutManager glyphRangeForCharacterRange:NSMakeRange(selection.location, 0)
+                                                         actualCharacterRange:NULL];
+    caretRect = [_textView.layoutManager boundingRectForGlyphRange:glyphRange inTextContainer:_textView.textContainer];
+    caretRect.origin.x += _textView.textContainerInset.width;
+    caretRect.origin.y += _textView.textContainerInset.height;
+  }
+#endif
+  return caretRect;
+}
+
+- (void)requestCaretRect:(NSInteger)requestId
+{
+  auto emitter = [self getEventEmitter];
+  if (emitter == nullptr) {
+    return;
+  }
+
+  CGRect caretRect = [self computeCaretRect];
+  emitter->onRequestCaretRectResult({
+      .requestId = static_cast<int>(requestId),
+      .x = caretRect.origin.x,
+      .y = caretRect.origin.y,
+      .width = caretRect.size.width,
+      .height = caretRect.size.height,
+  });
+}
+
 - (void)handleCommand:(const NSString *)commandName args:(const NSArray *)args
 {
   RCTEnrichedMarkdownInputHandleCommand(self, commandName, args);
@@ -883,6 +923,29 @@ - (void)emitOnChangeState
   });
 }
 
+- (void)emitCaretRectChangeIfNeeded
+{
+  auto emitter = [self getEventEmitter];
+  if (emitter == nullptr) {
+    return;
+  }
+
+  CGRect caretRect = [self computeCaretRect];
+
+  if (_prevCaretRect.has_value() && CGRectEqualToRect(_prevCaretRect.value(), caretRect)) {
+    return;
+  }
+
+  _prevCaretRect = caretRect;
+
+  emitter->onCaretRectChange({
+      .x = caretRect.origin.x,
+      .y = caretRect.origin.y,
+      .width = caretRect.size.width,
+      .height = caretRect.size.height,
+  });
+}
+
 - (NSArray<NSString *> *)contextMenuItemTexts
 {
   return _contextMenuItemTexts ?: @[];
@@ -1036,6 +1099,7 @@ - (void)handleTextChanged
   [self emitOnChangeText];
   [self emitOnChangeSelection];
   [self emitFormattingChanged];
+  [self emitCaretRectChangeIfNeeded];
   [self requestHeightUpdate];
   [self scheduleRelayoutIfNeeded];
 }
@@ -1139,6 +1203,7 @@ - (void)textViewDidChangeSelection:(UITextView *)textView
 
   [self emitOnChangeSelection];
   [self emitOnChangeState];
+  [self emitCaretRectChangeIfNeeded];
 }
 
 #else
@@ -1209,6 +1274,7 @@ - (void)textInputDidChangeSelection
 
   [self emitOnChangeSelection];
   [self emitOnChangeState];
+  [self emitCaretRectChangeIfNeeded];
 }
 
 // @required stubs for RCTBackedTextInputDelegate — RCTUITextView's internal adapter