@spec component_tag() :: :text_input

The component tag this widget registers under.

iex> Drafter.Widget.TextInput.component_tag()
:text_input

@spec from_component_opts(
  term(),
  keyword()
) :: Drafter.Widget.props()

Builds the props map for a {:text_input, opts} element.

The positional argument is ignored. :text is the bound value for that key, so bind: :key seeds it from opts[:__app_state__] and plain value: is used otherwise, defaulting to "". :width is the width of opts[:__rect__] less two border columns, with the rect defaulting to %{width: 2}. :on_change is the binding's writer and :on_submit is wrapped so that it dispatches the text and, when :keep_focus is set, sends {:focus_widget, id} back to the session. :max_length, :style and any :width in opts are not forwarded.

iex> props = Drafter.Widget.TextInput.from_component_opts(nil, placeholder: "Email")
iex> {props.text, props.placeholder, props.width, props.type, props.on_change}
{"", "Email", 0, :text, nil}

iex> opts = [bind: :query, __app_state__: %{query: "abc"}, __rect__: %{width: 22}]
iex> props = Drafter.Widget.TextInput.from_component_opts(nil, opts)
iex> {props.text, props.width, is_function(props.on_change, 1)}
{"abc", 20, true}

@spec handle_event(term(), t()) ::
  {:ok, t()} | {:ok, t(), list()} | {:bubble, t()} | {:noreply, t()}

Handles the field's own events, replacing the dispatch use Drafter.Widget would otherwise generate.

Routing goes in three stages. A :disabled or :readonly field only handles {:focus}, {:blur} and :activate, and returns {:noreply, state} for everything else. An unfocused field additionally handles a mouse up, :validate and :clear_error. A focused field handles the full set of key bindings listed in the module doc, {:char, code}, {:bracketed_paste, text}, mouse up and drag.

Most handled events return {:ok, new_state}; enter with an :on_submit returns {:ok, cleared_state, actions}; ctrl with an unhandled key and enter without an :on_submit return {:bubble, state}; a keystroke the restriction rejects, a backspace at position zero and a delete at the end return {:noreply, state}.

iex> state = Drafter.Widget.TextInput.mount(%{focused: true})
iex> {:ok, typed} = Drafter.Widget.TextInput.handle_event({:char, ?a}, state)
iex> {typed.text, typed.cursor_position}
{"a", 1}

iex> state = Drafter.Widget.TextInput.mount(%{focused: true, type: :integer})
iex> Drafter.Widget.TextInput.handle_event({:char, ?a}, state) |> elem(0)
:noreply

iex> state = Drafter.Widget.TextInput.mount(%{text: "hi", focused: true, cursor_position: 2})
iex> {:ok, deleted} = Drafter.Widget.TextInput.handle_event({:key, :backspace}, state)
iex> {deleted.text, deleted.cursor_position}
{"h", 1}

iex> state = Drafter.Widget.TextInput.mount(%{text: "hi", disabled: true})
iex> Drafter.Widget.TextInput.handle_event({:char, ?a}, state) |> elem(0)
:noreply

iex> state = Drafter.Widget.TextInput.mount(%{text: "hi", focused: true})
iex> Drafter.Widget.TextInput.handle_event({:key, :enter}, state) |> elem(0)
:bubble

@spec mount(Drafter.Widget.props()) :: t()

Builds the widget state from props.

Every option listed in the module doc is read here with the default stated there. :restrict is compiled to a Regex.t/0 when it is given as a string.

iex> state = Drafter.Widget.TextInput.mount(%{})
iex> {state.text, state.cursor_position, state.width, state.type, state.focused}
{"", 0, 40, :text, false}

iex> state = Drafter.Widget.TextInput.mount(%{text: "hi", placeholder: "name"})
iex> {state.text, state.placeholder, state.max_length, state.error}
{"hi", "name", nil, nil}

iex> Drafter.Widget.TextInput.mount(%{restrict: "^[a-z]$"}).restrict |> Regex.source()
"^[a-z]$"

@spec preferred_height(
  term(),
  keyword()
) :: 3

The number of rows the element asks for: always 3, the two border rows plus the content row. There is no :height override, and a validation error row is not accounted for.

iex> Drafter.Widget.TextInput.preferred_height(nil, height: 10)
3

@spec render(t() | Drafter.Widget.props(), Drafter.Widget.rect()) :: [
  Drafter.Draw.Strip.t()
]

Draws the bordered field into rect, always returning exactly rect.height strips.

state may be a plain props map, in which case it is passed through mount/1 first. The first three strips are the top border, the content row and the bottom border; a non-nil :error adds a fourth in red. Shorter output is padded with blank rows and longer output is truncated, so a rect under three rows high loses the bottom of the box. The content is min(state.width, rect.width - 2) columns wide, drawn from :scroll_offset, with the cursor block shown only while focused.

Callback implementation for Drafter.Widget.unmount/1.

@spec update(Drafter.Widget.props(), t()) :: t()

Replaces the state fields named in props, keeping the current value for any key that is absent.

:text is ignored entirely while the field is focused, so a re-render never overwrites what is being typed. Unfocused, it accepts either a string or a {text, validation_result} tuple and falls back to the current text for anything else. :cursor_position and :scroll_offset are never set here, so a shorter new text can leave the cursor past its end until the next keystroke.

iex> state = Drafter.Widget.TextInput.mount(%{text: "old"})
iex> Drafter.Widget.TextInput.update(%{text: "new"}, state).text
"new"

iex> state = Drafter.Widget.TextInput.mount(%{text: "typing", focused: true})
iex> Drafter.Widget.TextInput.update(%{text: "clobber"}, state).text
"typing"

iex> state = Drafter.Widget.TextInput.mount(%{text: "old"})
iex> Drafter.Widget.TextInput.update(%{text: {"tupled", {:ok, "tupled"}}}, state).text
"tupled"

@spec update_props_from_mount(Drafter.Widget.props(), t(), keyword()) ::
  Drafter.Widget.props()

Narrows a re-render to the props that may safely change after mount.

Always passes :on_change, :on_submit, :classes, :validators, :disabled, :readonly, :password, :restrict, :type and :select_on_focus. Adds :width and :placeholder only when they differ from the mounted state, and :text only when opts carries :bind or :value and the text differs — so an unbound field keeps whatever the user typed.

iex> props = Drafter.Widget.TextInput.from_component_opts(nil, placeholder: "Email")
iex> state = Drafter.Widget.TextInput.mount(props)
iex> Drafter.Widget.TextInput.update_props_from_mount(props, state, []) |> Map.has_key?(:text)
false

iex> opts = [bind: :query, __app_state__: %{query: "abc"}]
iex> props = Drafter.Widget.TextInput.from_component_opts(nil, opts)
iex> state = Drafter.Widget.TextInput.mount(%{text: "old", width: 0, placeholder: ""})
iex> Drafter.Widget.TextInput.update_props_from_mount(props, state, opts).text
"abc"