textinput

README

go-widgets/textinput

The zero-dependency text-input contract for the go-widgets ecosystem: what a text widget exposes so that an input method (an IME, a screen reader, a mobile keyboard) can drive it. Standard library only (go.mod has no require), 100% statement coverage, fuzzed.

toolkit implements it, webcanvas (the browser host) and the native back-ends (Cocoa NSTextInputClient, Windows TSF, Android's InputConnection) consume it, and none of them has to import the others. The design is in go-widgets/webcanvas#21.

go get github.com/go-widgets/textinput

What is in it

Client	the interface a text widget implements, shaped after AppKit's NSTextInputClient
State, Edit	a snapshot (text, selection with direction, marked range) and a single replacement
Len, ToByte, FromByte, LineCol, Offset, ToRune, FromRune	pure UTF-16 / byte / rune / (line, column) conversions
Reconcile(prev, next State) Edit	the diff fallback: the one edit that explains a change read back from the DOM

Offsets are UTF-16 code units over the whole document, the unit shared by NSRange, the DOM's selectionStart and TSF. -1 means "none". The method names keep the Input prefix because a widget already has Text, Selection and SetSelection with other meanings.

type Client interface {
	InputText() string
	InputRevision() uint64
	InputSelection() (anchor, focus int)  // selectedRange
	InputMarked() (start, end int)        // markedRange; (-1, -1) without composition
	InputMultiline() bool
	InputReadOnly() bool

	SetInputSelection(anchor, focus int)
	ReplaceInput(start, end int, text string)                              // insertText:replacementRange:
	SetMarkedInput(text string, selStart, selEnd, replStart, replEnd int)  // setMarkedText:selectedRange:replacementRange:
	UnmarkInput()                                                          // unmarkText

	InputRect(start, end int) (x, y, w, h int)  // firstRectForCharacterRange:
	InputIndexAt(x, y int) int                  // characterIndexForPoint:
}

doCommandBySelector: has no method: command keys go through the widget's ordinary key handler.

Reconcile

A browser host writes the widget's text and selection into a hidden editing element, and when the element changes without an event it can trust (Android composition, autofill, an unusual IME) it reads the element back. Reconcile turns the two snapshots into one Edit that Client.ReplaceInput can apply. VS Code (TextAreaState.deduceInput) and Flutter web (inferDeltaState) do the same.

prev := textinput.State{Text: "hello wrld", Anchor: 10, Focus: 10, MarkStart: -1, MarkEnd: -1}
next := textinput.State{Text: "hello world", Anchor: 11, Focus: 11, MarkStart: -1, MarkEnd: -1}

e := textinput.Reconcile(prev, next)  // Edit{Start: 7, End: 7, Text: "o"}
e.Apply(prev.Text) == next.Text       // true

• Minimal. The edit replaces the fewest UTF-16 units: the longest common prefix and suffix are trimmed.
• Caret-aware. When several minimal edits exist (a typed after a), the one nearest the caret wins: it starts at the smaller selection start of the two states, as VS Code does by bounding the prefix with both selections.
• Never splits a surrogate pair, so an emoji is replaced whole.
• Exact. Edit.Text is a slice of next.Text; applying the edit to prev.Text gives next.Text byte for byte, invalid UTF-8 included.
• Equal texts give the zero Edit. The marked range is not used.
• Invalid UTF-8 never fails: each invalid byte counts as one rune (U+FFFD), so as one UTF-16 unit.

Tests

• Table tests for every conversion, and cases from real input methods (kana to kanji, Android replace-word, backspace in a run, emoji swaps, ZWJ sequences, combining marks, CRLF).
• A property test over every pair of short texts built from awkward pieces and every selection shape: the edit applied to the old state gives the new state, stays in range, and never splits a pair.
• An optimality test against brute force on a two-letter alphabet.
• A reference implementation (oracle_test.go: both texts converted to one symbol per UTF-16 unit, then diffed) that every checked pair must agree with, including pieces such as the half of a euro sign and of an emoji.
• Two fuzz targets, FuzzReconcile and FuzzUTF16, seeded with lone surrogates, invalid UTF-8, emoji ZWJ sequences, combining marks and CRLF (fuzz_test.go). CI runs each for 60 s.
• Linear cost: TestReconcileLinear checks that 4x the text (256 KiB to 1 MiB) takes well under 16x the time, and TestReconcileAllocs that Reconcile allocates nothing.
• CI runs on linux/amd64, linux/386 (32-bit offsets), darwin, windows and js/wasm under node, plus govulncheck.

Benchmark

go test -bench Reconcile, Apple M4 Max, go1.27.3, single goroutine, one edit (🙂typed) in the middle of a text of mixed ASCII, 2-, 3- and 4-byte runes and CRLF line ends:

Case	Time	Throughput	Allocated
mid-insert, 1 KiB	0.86 us	1.2 GB/s	0 allocs
mid-insert, 64 KiB	50 us	1.3 GB/s	0 allocs
mid-insert, 1 MiB	0.81 ms	1.3 GB/s	0 allocs
disjoint texts, 1 MiB	2.9 ms	364 MB/s	0 allocs
last byte differs, 1 MiB	0.55 ms	1.9 GB/s	0 allocs
equal texts, 1 MiB	3.7 ns		0 allocs

Median of 3 runs of 300 iterations. The 1-minute load was 11 to 25 (above the 8 the fleet rule allows), but a first pass at load 4 gave the same figures within 5%; re-run on a quiet machine before quoting them elsewhere. Time per byte is flat from 1 KiB to 1 MiB: the cost is linear, and the old implementation, which converted both texts to UTF-16 symbols, took 4.0 ms and 8 MiB for the 1 MiB mid-insert. There is no reference implementation to compare with: VS Code's and Flutter's diffs are JavaScript/Dart on UTF-16 strings, which Go cannot be timed against on equal terms.

The editor text layer holds a whole document, so Reconcile runs over all of it on each keystroke: it works on the UTF-8 bytes, allocates nothing, and only counts the runes before the edit and inside the common suffix. TestReconcileAllocs asserts 0 allocations on 1 MiB mixed, CJK/emoji, overlapping and disjoint inputs.

Licence

See LICENSE.

Documentation

Overview

Package textinput is the contract between a text widget and an input method (an IME, a screen reader, a mobile keyboard), with no dependency beyond the standard library.

It holds three things:

• Client, the interface a text widget implements. It has the shape of AppKit's NSTextInputClient (insertText:replacementRange:, setMarkedText:selectedRange:replacementRange:, unmarkText, selectedRange, markedRange, firstRectForCharacterRange:actualRange:, characterIndexForPoint:), uses builtin types only, and counts offsets in UTF-16 code units over the whole document. NSRange, the DOM's selectionStart and Windows TSF all count that way.
• The pure UTF-16 helpers Len, ToByte, FromByte, LineCol, Offset, ToRune and FromRune, which convert between that unit, Go's UTF-8 byte offsets, rune offsets (AT-SPI counts characters) and (line, rune column) pairs.
• Reconcile, the diff fallback: given the text and selection last written to a host's editing element and the ones read back from it, it deduces the single Edit that explains the change. VS Code (TextAreaState.deduceInput) and Flutter web (inferDeltaState) do the same when an event's data cannot be trusted, as on Android.

Text model

A document is a Go string, with "\n" as its only line end ("\r" is an ordinary character, so CRLF text keeps its "\r" at the end of each line). Invalid UTF-8 never makes a function fail: every invalid byte counts as one rune, U+FFFD, and so as one UTF-16 unit, and slicing keeps the original bytes. Offsets are clamped to the document; an offset that falls inside a surrogate pair (a rune outside the BMP counts for two units) rounds down to the start of that rune.

Cost

Every function is linear in the length of its text arguments, and none of them allocates: results are numbers or slices of the arguments.

Index

• func FromByte(s string, b int) int
• func FromRune(s string, r int) int
• func Len(s string) int
• func LineCol(s string, off int) (line, col int)
• func Offset(s string, line, col int) int
• func ToByte(s string, off int) int
• func ToRune(s string, off int) int
• type Client
• type Edit
  • func Reconcile(prev, next State) Edit
  • func (e Edit) Apply(text string) string
  • func (e Edit) IsZero() bool
• type State
  • func StateOf(c Client) State

Functions

func FromByte

func FromByte(s string, b int) int

FromByte converts the byte offset b in s into a UTF-16 offset. b is clamped to [0, len(s)], and only the runes that end at or before b count.

func FromRune

func FromRune(s string, r int) int

FromRune is the inverse of ToRune: it converts the rune offset r into a UTF-16 offset. r is clamped to [0, runes in s].

func Len

func Len(s string) int

Len returns the number of UTF-16 code units of s.

func LineCol

func LineCol(s string, off int) (line, col int)

LineCol converts the UTF-16 offset off into a line (counted from 0, "\n" ends a line) and a column counted in runes from the start of that line. An offset inside a surrogate pair rounds down to the start of the rune.

func Offset

func Offset(s string, line, col int) int

Offset is the inverse of LineCol: it returns the UTF-16 offset of the rune column col of line line. A line past the end gives Len(s), and a column past the end of its line gives the offset of that line's end, just before its "\n". Negative arguments count as 0.

func ToByte

func ToByte(s string, off int) int

ToByte converts the UTF-16 offset off into a byte offset in s. off is clamped to [0, Len(s)], and an offset inside a surrogate pair rounds down to the start of the rune.

func ToRune

func ToRune(s string, off int) int

ToRune converts the UTF-16 offset off into a rune offset, which is what AT-SPI counts as a character offset. An offset inside a surrogate pair rounds down to the rune.

Types

type Client

type Client interface {
	// InputText returns the whole document, with "\n" line ends.
	InputText() string
	// InputRevision changes on every edit, so a host can skip rewriting its
	// editing element when nothing changed.
	InputRevision() uint64
	// InputSelection returns the selection, direction kept: anchor == focus
	// is a caret. [selectedRange]
	InputSelection() (anchor, focus int)
	// InputMarked returns the marked (composition) range, or (-1, -1)
	// without composition. [markedRange, hasMarkedText]
	InputMarked() (start, end int)
	// InputMultiline reports whether Enter inserts a line break.
	InputMultiline() bool
	// InputReadOnly reports whether the widget refuses edits.
	InputReadOnly() bool

	// SetInputSelection moves the selection.
	SetInputSelection(anchor, focus int)
	// ReplaceInput replaces [start, end) with text, as a committed, undoable
	// edit. (-1, -1) means the current selection.
	// [insertText:replacementRange:]
	ReplaceInput(start, end int, text string)
	// SetMarkedInput replaces [replStart, replEnd) with text and marks it as
	// the composition preview; (-1, -1) means the current marked range, or
	// the selection when there is none. selStart and selEnd are the
	// selection inside text, relative to its start.
	// [setMarkedText:selectedRange:replacementRange:]
	SetMarkedInput(text string, selStart, selEnd, replStart, replEnd int)
	// UnmarkInput commits the marked text as typed; it does nothing without
	// marked text. [unmarkText]
	UnmarkInput()

	// InputRect returns the surface pixels of the first line of [start, end).
	// [firstRectForCharacterRange:actualRange:]
	InputRect(start, end int) (x, y, w, h int)
	// InputIndexAt returns the offset nearest to the surface point (x, y).
	// [characterIndexForPoint:]
	InputIndexAt(x, y int) int
}

Client is a text widget as an input method sees it. Offsets count UTF-16 code units over InputText(): NSTextInputClient's NSRange, the DOM's selectionStart and TSF's ACP all count this way. -1 means "none".

The names keep the Input prefix because a widget already has methods such as Text, Selection and SetSelection with other meanings. The comment on each method gives the NSTextInputClient selector it corresponds to. doCommandBySelector: has no counterpart: command keys go through the widget's ordinary key handler, and attributedSubstringForProposedRange: is derived from InputText.

type Edit

type Edit struct {
	Start, End int
	Text       string
}

Edit replaces the UTF-16 range [Start, End) of a text with Text. It is what Reconcile deduces and what Client.ReplaceInput takes. The zero Edit changes nothing.

func Reconcile

func Reconcile(prev, next State) Edit

Reconcile deduces the one Edit that turns prev.Text into next.Text. It is the fallback of a host whose editing element changed without a trustworthy event (Android composition, autofill, an unusual IME): prev is what the host last wrote to the element, next is what it reads back. The same diff is VS Code's TextAreaState.deduceInput and Flutter web's inferDeltaState.

The result is minimal: it replaces the fewest UTF-16 units, found by trimming the longest common prefix and suffix. When several minimal edits exist (typing "a" after "a" gives "aa" whichever "a" is new), the one that starts nearest to the caret is chosen: the smaller of the two selection starts, which is the rule VS Code applies by bounding the prefix with both selections. A selection with a negative anchor or focus is ignored, and without any selection the edit is placed as far right as possible.

Start and End are offsets in prev.Text and never split a surrogate pair. Edit.Text is a slice of next.Text, so invalid UTF-8 is kept byte for byte, and prev.Text with the Edit applied is always next.Text. Equal texts give the zero Edit, whatever the selections. The marked range of both states is not used: it is the caller's business to re-mark after applying the Edit.

The cost is linear in the length of both texts, and Reconcile allocates nothing: the scans work on the UTF-8 bytes, and only the runes before the edit and inside the common suffix are counted, never copied.

func (Edit) Apply

func (e Edit) Apply(text string) string

Apply returns text with e applied. Offsets are clamped to the text, and a reversed range is put in order.

func (Edit) IsZero

func (e Edit) IsZero() bool

IsZero reports whether e is the zero Edit, which changes nothing.

type State

type State struct {
	Text               string
	Anchor, Focus      int
	MarkStart, MarkEnd int
}

State is a snapshot of a text widget: what a host last wrote to its editing element, or what it read back. Offsets are UTF-16 code units.

Anchor and Focus are the selection with its direction (Anchor == Focus is a caret); a negative value means "no selection". MarkStart and MarkEnd are the marked range, (-1, -1) without composition.

func StateOf

func StateOf(c Client) State

StateOf snapshots c.