@spec component_tag() :: :code_view

The registry tag for this widget.

iex> Drafter.Widget.CodeView.component_tag()
:code_view

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

Turns the {:code_view, opts} element into a props map for mount/1.

The positional argument is ignored, so the text must be passed as source:.

iex> Drafter.Widget.CodeView.from_component_opts("ignored", source: "a")
%{source: "a", path: nil, language: :text, show_line_numbers: false, hex_view: false}

@spec handle_drag(integer(), integer(), t()) :: {:ok, t()}

Consumes the drag event and returns {:ok, state} unchanged. Dragging does not pan the document.

Callback implementation for Drafter.Widget.handle_event/2.

@spec handle_key(Drafter.Widget.key(), t()) :: {:ok, t()}

Scrolls the document.

:up/:down move one line, :page_up/:page_down move ten, and :left/:right move five columns. The vertical offset is clamped to 0..length(lines) - 1; the horizontal offset is clamped to 0..max(0, longest_line - 20). Every other key is consumed unchanged. Always returns {:ok, state}, so nothing bubbles.

iex> cv = Drafter.Widget.CodeView.mount(%{source: "a\nb\nc"})
iex> {:ok, moved} = Drafter.Widget.CodeView.handle_key(:down, cv)
iex> moved.scroll_offset
1

iex> cv = Drafter.Widget.CodeView.mount(%{source: "a\nb\nc"})
iex> {:ok, paged} = Drafter.Widget.CodeView.handle_key(:page_down, cv)
iex> paged.scroll_offset
2

iex> cv = Drafter.Widget.CodeView.mount(%{source: String.duplicate("x", 40)})
iex> {:ok, right} = Drafter.Widget.CodeView.handle_key(:right, cv)
iex> right.h_scroll_offset
5

iex> cv = Drafter.Widget.CodeView.mount(%{source: "short"})
iex> {:ok, right} = Drafter.Widget.CodeView.handle_key(:right, cv)
iex> right.h_scroll_offset
0

iex> cv = Drafter.Widget.CodeView.mount(%{source: "a"})
iex> Drafter.Widget.CodeView.handle_key(:enter, cv) |> elem(0)
:ok

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

Scrolls the document three lines per wheel notch.

The offset is clamped to 0..length(lines) - 1, so the last line can always be scrolled to the top of the rect. Always returns {:ok, state}.

iex> cv = Drafter.Widget.CodeView.mount(%{source: "a\nb\nc\nd\ne\nf"})
iex> {:ok, down} = Drafter.Widget.CodeView.handle_scroll(:down, cv)
iex> {:ok, up} = Drafter.Widget.CodeView.handle_scroll(:up, down)
iex> {down.scroll_offset, up.scroll_offset}
{3, 0}

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

Builds the code view state from props, reading :path from disk when given and splitting the document into lines.

Both scroll offsets and :focused always start at 0/false. Highlighting is computed here, so a source with no recognised syntax leaves :highlights as nil.

iex> cv = Drafter.Widget.CodeView.mount(%{source: "a\nb\nc"})
iex> {cv.lines, cv.language, cv.scroll_offset, cv.show_line_numbers, cv.hex_view}
{["a", "b", "c"], :text, 0, false, false}

iex> cv = Drafter.Widget.CodeView.mount(%{})
iex> {cv.lines, cv.path, cv.h_scroll_offset, cv.focused}
{[""], nil, 0, false}

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

opts[:height], or 20 when it is absent.

iex> Drafter.Widget.CodeView.preferred_height(nil, [])
20

iex> Drafter.Widget.CodeView.preferred_height(nil, height: 8)
8

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

Draws the visible window of the document into rect.

Emits one strip per visible line, at most rect.height of them starting at :scroll_offset, so a document shorter than the rect leaves the remaining rows untouched rather than blanking them. With :show_line_numbers the gutter takes the width of the largest line number plus one column, and the rest is content scrolled left by :h_scroll_offset.

Callback implementation for Drafter.Widget.unmount/1.

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

Reloads the document when the source changed, and returns state untouched otherwise.

A reload happens when :path differs from the mounted one, when :hex_view differs, or when :source is present, non-empty, and differs from the joined current lines. When it happens both scroll offsets reset to 0 and :language is re-read; :show_line_numbers never changes.

iex> cv = Drafter.Widget.CodeView.mount(%{source: "a\nb"})
iex> {:ok, scrolled} = Drafter.Widget.CodeView.handle_key(:down, cv)
iex> Drafter.Widget.CodeView.update(%{source: "a\nb"}, scrolled).scroll_offset
1

iex> cv = Drafter.Widget.CodeView.mount(%{source: "a\nb"})
iex> {:ok, scrolled} = Drafter.Widget.CodeView.handle_key(:down, cv)
iex> reloaded = Drafter.Widget.CodeView.update(%{source: "x\ny\nz"}, scrolled)
iex> {reloaded.lines, reloaded.scroll_offset}
{["x", "y", "z"], 0}

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

Narrows the props a re-render feeds to update/2 to :source, :path, :language and :hex_view. :show_line_numbers is left out and stays as mounted.