@spec component_tag() :: :text_area

The component tag this widget registers under.

iex> Drafter.Widget.TextArea.component_tag()
:text_area

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

Builds the props map for a {:text_area, 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 "". :on_change is the binding's writer. :width and :height always come from opts[:__rect__], itself defaulting to %{width: 40, height: 6}, and a :width or :height in opts is ignored. :style defaults to %{} here rather than to the palette mount/1 would supply, and the four other style maps and :max_checkpoints are not forwarded at all.

iex> props = Drafter.Widget.TextArea.from_component_opts(nil, placeholder: "Notes")
iex> {props.text, props.placeholder, props.width, props.height, props.style}
{"", "Notes", 40, 6, %{}}

iex> opts = [bind: :body, __app_state__: %{body: "hello"}, __rect__: %{width: 20, height: 4}]
iex> props = Drafter.Widget.TextArea.from_component_opts(nil, opts)
iex> {props.text, props.width, props.height, is_function(props.on_change, 1)}
{"hello", 20, 4, true}

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

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

{:focus}, {:blur} and {:mouse, %{type: :scroll}} are handled in any state. Every binding listed in the module doc, along with {:char, code} and {:bracketed_paste, text}, requires :focused; anything else returns {:noreply, state}.

Cursor moves, selection changes, undo, redo and copy return {:ok, new_state}. Edits return whatever the editing helper reports, {:ok, state} or {:noreply, state}, and call :on_change with the full text. A cut, paste or character input on a :read_only editor returns {:noreply, state}.

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

iex> state = Drafter.Widget.TextArea.mount(%{text: "hi", focused: true, read_only: true})
iex> Drafter.Widget.TextArea.handle_event({:char, ?a}, state) == {:noreply, state}
true

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

iex> state = Drafter.Widget.TextArea.mount(%{text: "ab\ncd", focused: true})
iex> {:ok, moved} = Drafter.Widget.TextArea.handle_event({:key, :down}, state)
iex> moved.cursor_line
1

@spec handle_scroll(:up | :down, t()) :: {:ok, t()}

Scrolls the viewport by three lines per wheel step, without moving the cursor.

Always returns {:ok, new_state}. Scrolling up stops at 0; scrolling down stops at line_count - (height - 2), using the state's :height, not the rect. Works whether or not the widget is focused.

iex> state = Drafter.Widget.TextArea.mount(%{text: Enum.join(1..20, "\n")})
iex> {:ok, down} = Drafter.Widget.TextArea.handle_scroll(:down, state)
iex> down.scroll_offset
3

iex> state = Drafter.Widget.TextArea.mount(%{text: "a\nb"})
iex> {:ok, down} = Drafter.Widget.TextArea.handle_scroll(:down, state)
iex> down.scroll_offset
0

@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. :text is split into :lines, :gutter_width is derived from :show_line_numbers and the line count, and the cursor, scroll, selection and history all start empty.

iex> state = Drafter.Widget.TextArea.mount(%{text: "a\nb"})
iex> {state.lines, state.cursor_line, state.cursor_col, state.gutter_width}
{["a", "b"], 0, 0, 0}

iex> state = Drafter.Widget.TextArea.mount(%{show_line_numbers: true})
iex> state.gutter_width
4

iex> state = Drafter.Widget.TextArea.mount(%{})
iex> {state.width, state.height, state.tab_behavior, state.tab_size, state.max_checkpoints}
{40, 6, :focus, 2, 50}

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

The number of rows the element asks for: opts[:height], default 6, borders included.

iex> Drafter.Widget.TextArea.preferred_height(nil, [])
6

iex> Drafter.Widget.TextArea.preferred_height(nil, height: 12)
12

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

Draws the bordered editor into rect.

state may be a plain props map, in which case it is passed through mount/1 first. Returns the top border, rect.height - 2 content rows and the bottom border, so the result is rect.height strips. The content area is rect.width - 2 - gutter_width columns, one narrower again when a scrollbar is needed, which happens as soon as the line count exceeds the content height.

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.

Accepts every option except :selection_style, and never touches the cursor, scroll offsets, selection or history directly. A :text that differs from the current one re-splits :lines, re-clamps the cursor into the new content, clears the selection and re-adjusts the scroll offset; identical text leaves all of that alone. :gutter_width is recomputed on every call.

iex> state = Drafter.Widget.TextArea.mount(%{text: "one\ntwo\nthree"})
iex> state = %{state | cursor_line: 2, cursor_col: 3}
iex> updated = Drafter.Widget.TextArea.update(%{text: "a"}, state)
iex> {updated.lines, updated.cursor_line, updated.cursor_col}
{["a"], 0, 1}

iex> state = Drafter.Widget.TextArea.mount(%{text: "a"})
iex> Drafter.Widget.TextArea.update(%{show_line_numbers: true}, state).gutter_width
4

@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, :max_lines, :show_line_numbers, :language, :read_only, :trap_focus, :tab_behavior, :tab_size and :highlight_cursor_line. Adds :width, :height 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 editor keeps what the user typed.

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

iex> opts = [bind: :body, __app_state__: %{body: "hello"}]
iex> props = Drafter.Widget.TextArea.from_component_opts(nil, opts)
iex> state = Drafter.Widget.TextArea.mount(%{text: "old", width: 40, height: 6})
iex> Drafter.Widget.TextArea.update_props_from_mount(props, state, opts).text
"hello"