Tuix.Components.Input (tuix v0.1.2)

The editing core of the Tuix.Components.input/1 element: pure, grapheme-aware functions over a value and a cursor offset.

Inputs are controlled: the app owns the value in assigns. When a key reaches a focused input, the runtime calls on_key/3 (the Tuix.Component behaviour) with the value from the last rendered tree and the cursor it manages (in Tuix.App private), then reports value changes to the app as %Tuix.Event.Input{} events. Keys the input does not handle fall through to the app's Tuix.App.handle_event/2 with target set.

Cursor offsets are grapheme indices (0..String.length(value)), so wide characters (CJK, emoji) count as one position.

Summary

Types

cursor()

A grapheme offset into the value, 0..String.length(value).

result()

The result of applying a key

Functions

edit(value, cursor, key)

Applies a key event to value at cursor (clamped to the value length).

window(value, cursor, width)

Computes the horizontally scrolled display window for a focused input.

Types

cursor()

@type cursor() :: non_neg_integer()

A grapheme offset into the value, 0..String.length(value).

result()

@type result() :: {:changed, String.t(), cursor()} | {:moved, cursor()} | :ignored

The result of applying a key:

{:changed, value, cursor} - the value changed
{:moved, cursor} - only the cursor changed (or a consumed no-op, e.g. backspace at the start)
:ignored - the input does not handle this key; it falls through to the app

Functions

edit(value, cursor, key)

@spec edit(String.t(), cursor(), Tuix.Event.Key.t()) :: result()

Applies a key event to value at cursor (clamped to the value length).

Handled keys: printable graphemes and :space (insert), :backspace, :delete, :left, :right, :home, :end. Ctrl- and alt-modified keys, and everything else (:enter, :escape, :up, ...), are :ignored.

window(value, cursor, width)

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

Computes the horizontally scrolled display window for a focused input.

Returns {prefix, at_cursor, suffix}: the visible text before the cursor (scrolled so the cursor cell fits within width columns), the grapheme under the cursor (" " when the cursor is at the end), and the remaining text (clipped by the paint rect).