@spec component_tag() :: :tree

The component tag this widget registers under.

iex> Drafter.Widget.Tree.component_tag()
:tree

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

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

The positional argument is ignored; the nodes come from opts[:data]. :on_select and :on_node_highlight go through Drafter.Widget.Callback.wrap_1/1 and :on_expand through wrap_2/1, so an atom becomes a closure that dispatches an app event. :width and :height fall back to opts[:__rect__], itself defaulting to %{width: 80, height: 20}. The five style maps are not forwarded.

iex> props = Drafter.Widget.Tree.from_component_opts(nil, data: [%{id: :a, label: "a"}])
iex> {props.selection_mode, props.show_icons, props.indent_size, props.width, props.height}
{:single, true, 2, 80, 20}

iex> props = Drafter.Widget.Tree.from_component_opts(nil, on_select: :picked)
iex> {props.data, is_function(props.on_select, 1)}
{[], true}

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

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

Recognised events are the key bindings listed in the module doc — all of which require :focused — plus a mouse up, a mouse wheel, {:focus} and {:blur}, which do not. Anything else returns {:noreply, state}, and so does a cursor move that is already at either end and a collapse or expand that would not change anything.

A cursor move calls :on_node_highlight, expanding or collapsing calls :on_expand with the node and its new state, and toggling a selection calls :on_select with every selected node.

iex> data = [%{id: :a, label: "a"}, %{id: :b, label: "b"}]
iex> state = Drafter.Widget.Tree.mount(%{data: data, focused: true})
iex> {:ok, moved} = Drafter.Widget.Tree.handle_event({:key, :down}, state)
iex> moved.cursor_index
1

iex> data = [%{id: :a, label: "a"}]
iex> state = Drafter.Widget.Tree.mount(%{data: data, focused: true})
iex> Drafter.Widget.Tree.handle_event({:key, :up}, state) == {:noreply, state}
true

iex> data = [%{id: :a, label: "a", children: [%{id: :b, label: "b"}]}]
iex> state = Drafter.Widget.Tree.mount(%{data: data, focused: true})
iex> {:ok, expanded} = Drafter.Widget.Tree.handle_event({:key, :right}, state)
iex> MapSet.to_list(expanded.expanded_nodes)
[:a]

iex> data = [%{id: :a, label: "a"}]
iex> state = Drafter.Widget.Tree.mount(%{data: data, focused: true})
iex> {:ok, selected} = Drafter.Widget.Tree.handle_event({:key, :" "}, state)
iex> MapSet.to_list(selected.selected_nodes)
[:a]

iex> data = [%{id: :a, label: "a"}, %{id: :b, label: "b"}]
iex> state = Drafter.Widget.Tree.mount(%{data: data})
iex> Drafter.Widget.Tree.handle_event({:key, :down}, state) == {:noreply, state}
true

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

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

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

iex> data = Enum.map(1..20, fn n -> %{id: n, label: "node"} end)
iex> state = Drafter.Widget.Tree.mount(%{data: data, height: 5})
iex> {:ok, down} = Drafter.Widget.Tree.handle_scroll(:down, state)
iex> down.scroll_offset
3

iex> state = Drafter.Widget.Tree.mount(%{data: [%{id: :a, label: "a"}]})
iex> {:ok, down} = Drafter.Widget.Tree.handle_scroll(:down, state)
iex> down.scroll_offset
0

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

Builds the widget state from props.

:data is normalised into tree_node/0 maps. Because normalisation drops every key it does not know, an :expanded field on an input node is gone by the time the expansion set is built, so :expanded_nodes always starts empty. :cursor_index, :selected_nodes and :scroll_offset likewise always start empty and cannot be seeded from props.

iex> state = Drafter.Widget.Tree.mount(%{data: [%{id: :lib, label: "lib"}]})
iex> state.data
[%{id: :lib, label: "lib", children: [], icon: nil, metadata: %{}}]

iex> state = Drafter.Widget.Tree.mount(%{data: [%{id: :lib, label: "lib", expanded: true}]})
iex> MapSet.to_list(state.expanded_nodes)
[]

iex> state = Drafter.Widget.Tree.mount(%{})
iex> {state.data, state.cursor_index, state.selection_mode, state.show_icons, state.indent_size}
{[], 0, :single, true, 2}

iex> state = Drafter.Widget.Tree.mount(%{data: [{"lib", [%{id: :app, label: "app.ex"}]}]})
iex> [root] = state.data
iex> {root.label, Enum.map(root.children, & &1.label)}
{"lib", ["app.ex"]}

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

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

Unlike the other widgets this returns an atom when no height is given, leaving the row count to the layout.

iex> Drafter.Widget.Tree.preferred_height(nil, [])
:auto

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

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

Draws the visible slice of the tree 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. Only children of expanded nodes appear. Rows start at :scroll_offset; when the flattened list is taller than rect.height the last column becomes a scrollbar and the rows are cropped one narrower. Theme colours are merged over the state's style maps first.

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.

:data is re-normalised on every call, whether or not props carries it, and the cursor is clamped to the resulting visible row count. :expanded_nodes, :selected_nodes and :scroll_offset are left alone, so expansion survives new data only for nodes that keep the same explicit :id.

iex> data = [%{id: :a, label: "a"}, %{id: :b, label: "b"}]
iex> state = %{Drafter.Widget.Tree.mount(%{data: data}) | cursor_index: 1}
iex> updated = Drafter.Widget.Tree.update(%{data: [%{id: :a, label: "a"}]}, state)
iex> {length(updated.data), updated.cursor_index}
{1, 0}

iex> state = Drafter.Widget.Tree.mount(%{data: [%{id: :a, label: "a"}]})
iex> Drafter.Widget.Tree.update(%{show_icons: false}, state).show_icons
false

@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_select, :on_expand, :on_node_highlight, :selection_mode, :show_icons, :indent_size and :data. Adds :width and :height only when they differ from the mounted state.

iex> props = Drafter.Widget.Tree.from_component_opts(nil, data: [%{id: :a, label: "a"}])
iex> state = Drafter.Widget.Tree.mount(props)
iex> Drafter.Widget.Tree.update_props_from_mount(props, state, []) |> Map.keys() |> Enum.sort()
[:data, :indent_size, :on_expand, :on_node_highlight, :on_select, :selection_mode, :show_icons]

iex> props = Drafter.Widget.Tree.from_component_opts(nil, __rect__: %{width: 40, height: 8})
iex> state = Drafter.Widget.Tree.mount(%{})
iex> result = Drafter.Widget.Tree.update_props_from_mount(props, state, [])
iex> {result.width, result.height}
{40, 8}