Skip to content

Let a multiline field fill its height, and report where its caret is drawn - #227

Draft
simonhamp wants to merge 3 commits into
mainfrom
feat/text-field-fill-caret
Draft

simonhamp wants to merge 3 commits into
mainfrom
feat/text-field-fill-caret

Conversation

@simonhamp

@simonhamp simonhamp commented Nov 21, 2026 •

Copy link
Copy Markdown
Member

Two things for multiline text inputs, both needed by the devnull composer sheet (NativePHP/dev-null-app#198), which currently has to guess how tall the sheet is and where the caret is drawn.

This branch has #218's commit under mine, because the iOS caret reporting uses the UITextView that #218's sizer already finds. Merge #218 first, or this one with it.

A multiline field that fills its height

A multiline field is as tall as its lines (min-lines to max-lines). With h-full (or fill) it now takes the height its parent gives it and scrolls its own text inside. It's never shorter than min-lines, and max-lines doesn't cap it.

I didn't make flex-1 do this. In a row flex-1 means width, and a chat bar's flex-1 field should keep growing a line at a time. Put the h-full field in a flex-1 column instead. h-full on a multiline field did nothing useful before, so nothing that works today changes.

When a focused multiline field gets shorter, it scrolls so the caret stays in view. iOS already did that. On Android, Compose's BasicTextField only scrolls to the caret when the caret moves, so the devnull composer shrinking to make room for the mention list left the caret's line below the field until the next keystroke. The bare renderer now puts a BringIntoViewRequester on a box that sits where the scrolled text is (at the reporter's mirrored scroll offset, inside the field's own scroller). When the field shrinks and the caret is out of view, it asks that box to show the caret. This runs for every multiline bare field, with or without @caretChange. Outlined and filled don't get it on Android.

The element sends fills_height for a multiline field whose layout height is fill.

@caretChange

Reports where a multiline field draws its caret. Type the handler's parameter as Native\Mobile\UI\Caret and it's decoded:

public function caretMoved(string $field, Caret $caret): void
<native:bare-text-input multiline @caretChange="caretMoved('body')" ... />

x, y, width, height are points on iOS and dp on Android, from the top-left of the part of the field you can see, with its scrolling taken off. So y is 0 on the top visible line and goes negative, or past fieldHeight, once the caret scrolls out of view ($caret->visible()). line is the visual line from the top of the text. fieldWidth and fieldHeight are the field's visible size. To place an overlay you add where the field sits in the overlay's parent.

It's sent after the caret moves, after the text is laid out again and after the field scrolls. It's coalesced over the same window as @selectionChange (selection-debounce-ms), dropped when nothing changed, and only sent while the field has focus. Never for single-line or secure fields.

The payload rides the text-change event as x,y,width,height,line,fieldWidth,fieldHeight. Caret implements UrlRoutable, so the component invoker's existing implicit binding (the one that binds backed enums and models) decodes it. That keeps core out of it. A handler typed string gets the raw payload.

  • iOS: caretRect(for: selectedTextRange.end) minus contentOffset, from the text view the sizer finds. It's scheduled on selection and text changes, contentSize and contentOffset KVO, and the field's size changing. Binding the selection is now also switched on by @caretChange, and like before that is decided by props that hold still, so the field isn't rebuilt between renders. All three text inputs send it on iOS, since they share the core.
  • Android: TextLayoutResult.getCursorRect(selection.end), px to dp, in the bare renderer only. BasicTextField (the TextFieldValue one) keeps its scroll position private, so the reporter follows it. The scroll that keeps the caret in view is mirrored from Compose's own TextFieldScrollerPosition rule (it re-checks when the caret's left or top edge moves), and a drag or fling of the text, or the shrink scroll above, reaches it as nested scroll, where the consumed distance is taken off. Outlined and filled don't send it on Android: M3's TextField gives no text layout to read.

In tests, ->moveCaretTo('body', new Caret(y: 48, height: 24)) fires it as a device would.

Watch for

  • The Android scroll mirror is the riskiest part. If a Compose update changes how BasicTextField scrolls to the caret, y drifts, and so would the shrink scroll, since its anchor box is placed at the mirrored offset. The Robolectric tests below would catch the common case.
  • Every caret report costs a render, like a selection report. A field with both sends about twice as many events while you type.
  • Not built on a device. The numbers in the Android test come from Robolectric's font metrics, so they're checked in the caret's own line height.

Testing

  • Pest: 557 passed. New BaseTextInputCaretTest (serialization, the payload, a Caret handler getting the decoded caret after its literal arguments, a string handler getting the raw payload) and BaseTextInputFillTest (h-full and fill fill, flex-1 and single-line don't). Size the iOS multiline input in whole lines of its own text view #218's sizing test needed two strings updated.
  • swiftc -typecheck -wmo over mobile-air main's NativeRender plus resources/ios: the same 156 error lines as Size the iOS multiline input in whole lines of its own text view #218's commit alone, none in NativeUITextInputCore.swift. Canaries planted in the reporter and in the view body were both reported.
  • tests/android (Robolectric, JDK 23, -PmobileRoot an app's vendor/nativephp/mobile): 114 passed. That compiles all three text input renderers. New TextInputCaretRectTest checks the caret's line and position, that a field capped at three lines reports the caret on its last visible line once it scrolls, that nothing is sent unchanged, unfocused or from a single-line field, and that fills_height makes the field as tall as its parent and scrolls past what fits. New TextInputCaretShrinkTest types twelve lines into a field filling a 400dp column and shrinks the column to 120dp. The caret's line ends up as the last one the field shows, with or without @caretChange, and the reported y matches where the text is really drawn (read from the field's layout nodes). Two of its three cases fail with the shrink scroll switched off. A field whose caret is still in view doesn't scroll.

🤖 Generated with Claude Code

simonhamp and others added 2 commits November 21, 2026 08:49
The multiline field sized its TextEditor from an invisible Text copy of
the typed text. Text and UITextView lay out a custom font's lines at
different heights, so the max-lines cap was never a whole number of the
editor's lines. Past the cap the editor scrolls the caret line to the
bottom of the frame, and the top line showed cut part way through.

The editor is now sized from the UITextView behind it: its content
height, in whole lines of its typing font's line height, between
min-lines and max-lines. Its text container insets are set to zero on
the text view itself instead of being pulled back with negative padding,
so no part of a scrolled-off line is drawn outside the field.

The field's height now follows its text a moment later than before, so
when a focused field gets shorter (a smaller text size, say) it scrolls
the caret's line back into view.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…drawn

A multiline text input is as tall as its lines. With h-full (or fill) it
now takes the height its parent gives it and scrolls its own text, never
shorter than min-lines. flex-1 alone doesn't do it, because in a row it
means width and a chat bar's field should keep growing a line at a time.

@caretChange reports the caret's rectangle in the field's own points (dp
on Android), from the top-left of its visible area with its scrolling
taken off, plus the visual line it's on and the field's visible size. A
handler typed Caret gets it decoded, through the binding the component
invoker already gives UrlRoutable parameters, so core needs no change.
It's sent after the caret moves, the text is laid out again or the field
scrolls, coalesced over the selection window and only while focused.

iOS reads it from the UITextView the sizer from the previous commit
already finds. Android's BasicTextField keeps its scroll to itself, so
the bare renderer follows it: the cursor-driven scroll is mirrored from
Compose's own rule and drags reach it as nested scroll. Outlined and
filled fields send it on iOS only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Compose's BasicTextField only scrolls to the caret when the caret moves,
not when the field's height shrinks. A composer that shrinks to make room
for something under the caret left the caret's line below its new bottom
edge until the next keystroke. iOS already scrolls it back.

The bare renderer now puts a BringIntoViewRequester on a box placed at the
caret reporter's mirrored scroll offset, inside the field's own scroller.
When a focused multiline field gets shorter and the caret is out of view,
the reporter asks it to show the caret's rectangle. That scroll comes back
through nested scroll like a drag, so the mirror and @caretChange follow
it. This runs for every multiline bare field, with or without a callback.

The mirror also re-coerces on the caret's left or top edge moving, as
Compose does, instead of top or bottom, and handles a caret taller than
the field the same way.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant