@spec apply_key({:key, any(), [atom()]}, String.t(), cursor()) ::
  {:edit, String.t(), cursor()} | :noop

Map a raw {:key, key, mods} event to an edit.

Returns {:edit, value, cursor} or :noop. Unlike Harlock.TextBuffer.apply_key/3 there is no :submit — Enter inserts a newline, so a textarea never submits on its own.

@spec apply_key(
  {:key, any(), [atom()]},
  String.t(),
  cursor(),
  Harlock.TextBuffer.kill_ring()
) ::
  {:edit, String.t(), cursor(), Harlock.TextBuffer.kill_ring()} | :noop

As apply_key/3, but threads a kill ring so Ctrl-y works. See Harlock.TextBuffer.apply_key/4.

@spec apply_key(
  {:key, any(), [atom()]},
  String.t(),
  cursor(),
  Harlock.TextBuffer.kill_ring(),
  wrap_width()
) :: {:edit, String.t(), cursor(), Harlock.TextBuffer.kill_ring()} | :noop

As apply_key/4, but wraps at wrap_width columns.

With a width, ↑ / ↓ and Home / End act on display rows rather than logical lines — pressing ↓ inside a wrapped paragraph moves to the next visual row, not past the whole paragraph. Ctrl-k still kills to the end of the logical line: killing only to a wrap boundary would be surprising, since the boundary isn't in the text.

The runtime passes the textarea's rendered width automatically when the element sets wrap: true.

@spec cursor_at(String.t(), integer(), integer()) :: cursor()

Translate a {line, column} pair back into a flat cursor. Both coordinates clamp into range, so callers can pass an over-long column and get the end of the line.

@spec insert_newline(String.t(), cursor()) :: {String.t(), cursor()}

Insert a newline at the cursor.

@spec line_count(String.t()) :: pos_integer()

Number of lines, counting a trailing empty line.

@spec line_end(String.t(), cursor(), wrap_width()) :: cursor()

Cursor at the end of the current display row.

@spec line_home(String.t(), cursor(), wrap_width()) :: cursor()

Cursor at the start of the current display row.

@spec lines(String.t()) :: [String.t()]

Split the value into its lines. A trailing newline yields a final empty line.

@spec move_down(String.t(), cursor(), wrap_width()) :: cursor()

Move one display row down, preserving the display column. No-op on the last row.

@spec move_up(String.t(), cursor(), wrap_width()) :: cursor()

Move one display row up, preserving the display column. No-op on the first row.

With a width the row is a wrapped segment; without one it is a logical line. Either way the column is preserved in display cells rather than graphemes, so moving up a column of CJK text lands where it looks like it should.

@spec position(String.t(), cursor()) :: position()

Translate a flat cursor into {line, column}, both zero-based and measured in graphemes. Out-of-range cursors clamp to the end of the value.

@spec scroll_to_reveal(integer(), String.t(), cursor(), integer(), wrap_width()) ::
  non_neg_integer()

Adjust a scroll offset by the minimum needed to keep the cursor's line visible in a viewport height lines tall.

The renderer applies this itself, so a textarea always draws its cursor even when the app pins :scroll to 0 — but an app that never tracks scroll keeps the cursor pinned to the last visible row once the value grows past one screen. Threading the result back onto the model gives the usual behaviour where the view only moves when the cursor would leave it:

def update({:harlock_edit, :body, {v, c}}, m) do
  %{m | body: v, cursor: c, scroll: TextArea.scroll_to_reveal(m.scroll, v, c, m.body_h)}
end

@spec visual_cursor_at(String.t(), integer(), integer(), wrap_width()) :: cursor()

Translate a {display_row, display_column} pair back into a flat cursor. Both coordinates clamp into range.

@spec visual_position(String.t(), cursor(), wrap_width()) :: position()

Translate a flat cursor into {display_row, display_column}.

The column is in display cells, not graphemes, so it can be handed straight to the renderer. A cursor sitting exactly on a wrap boundary reports the start of the following row, which is where a caret belongs after typing up to the edge.

@spec visual_rows(String.t(), wrap_width()) :: [visual_row()]

All display rows for a value, as {flat_cursor_at_row_start, text}.

With nil width this is just the logical lines, so callers can use one code path whether or not wrapping is on.

@spec wrap_line(String.t(), pos_integer()) :: [String.t()]

Break one logical line into display rows no wider than width columns.

Breaks at the last space that fits, keeping that space on the preceding row so the rows concatenate back to the input exactly — that property is what lets a flat cursor index map onto wrapped rows without a separate translation table. A word longer than width is broken mid-word rather than overflowing.

Width is measured in display columns via Harlock.Width, so a CJK grapheme costs two. A width too small to fit even one grapheme still consumes one per row rather than looping forever; the renderer clips the overflow.