@spec component_tag() :: :selection_list

The component tag this widget registers under.

iex> Drafter.Widget.SelectionList.component_tag()
:selection_list

@spec from_component_opts(
  list() | nil,
  keyword()
) :: Drafter.Widget.props()

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

options is used when it is a non-empty list, otherwise opts[:options], defaulting to []. :on_change and :on_item_toggle go through Drafter.Widget.Callback.wrap_1/1 and wrap_2/1, so an atom becomes a closure that dispatches an app event. :visible_height falls back to the height of opts[:__rect__], itself defaulting to %{width: 40, height: 10}. The emitted :classes key is not read by mount/1.

iex> props = Drafter.Widget.SelectionList.from_component_opts([{"a", :a}], selected: [:a])
iex> {props.options, props.selected, props.selection_mode, props.visible_height}
{[{"a", :a}], [:a], :multiple, 10}

iex> props = Drafter.Widget.SelectionList.from_component_opts(["a"], on_change: :picked)
iex> is_function(props.on_change, 1)
true

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

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

Recognised events, each returning {:ok, new_state}:

• {:key, :up} / {:key, :down} - move :highlighted_index, clamped at both ends, adjusting :scroll_offset to keep it within :visible_height
• {:key, :home} - first item, scrolled to the top
• {:key, :end} - last item
• {:key, :enter} / {:key, :" "} - toggle the highlighted item
• {:char, 1} - in :multiple mode only, select every item or clear the selection when everything is already selected
• {:mouse, %{type: :mouse_up, y: y}} - toggle the row at y, or {:noreply, state} when it falls outside the list
• {:focus} / {:blur} - set or clear :focused

Every other event returns {:noreply, state}. Toggling calls :on_change with the full list of selected IDs and :on_item_toggle with the index and its new state; the select-all binding calls :on_change only.

iex> state = Drafter.Widget.SelectionList.mount(%{options: ["a", "b"]})
iex> {:ok, toggled} = Drafter.Widget.SelectionList.handle_event({:key, :enter}, state)
iex> MapSet.to_list(toggled.selected_indices)
[0]

iex> state = Drafter.Widget.SelectionList.mount(%{options: ["a", "b"]})
iex> {:ok, moved} = Drafter.Widget.SelectionList.handle_event({:key, :down}, state)
iex> {:ok, back} = Drafter.Widget.SelectionList.handle_event({:key, :up}, moved)
iex> {moved.highlighted_index, back.highlighted_index}
{1, 0}

iex> state = Drafter.Widget.SelectionList.mount(%{options: ["a", "b", "c"]})
iex> {:ok, all} = Drafter.Widget.SelectionList.handle_event({:char, 1}, state)
iex> {:ok, none} = Drafter.Widget.SelectionList.handle_event({:char, 1}, all)
iex> {MapSet.to_list(all.selected_indices), MapSet.to_list(none.selected_indices)}
{[0, 1, 2], []}

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

Builds the widget state from props.

Options are normalised into %{id: id, label: label} maps and :selected is turned into the matching set of indices. :highlighted_index and :scroll_offset always start at 0.

iex> state = Drafter.Widget.SelectionList.mount(%{options: ["a", "b"]})
iex> {state.options, MapSet.to_list(state.selected_indices), state.selection_mode}
{[%{id: "a", label: "a"}, %{id: "b", label: "b"}], [], :multiple}

iex> options = [{"Elixir", :ex}, {"Erlang", :erl}]
iex> state = Drafter.Widget.SelectionList.mount(%{options: options, selected: [:erl]})
iex> MapSet.to_list(state.selected_indices)
[1]

iex> state = Drafter.Widget.SelectionList.mount(%{options: ["a", "b"], selected: [:missing]})
iex> {MapSet.to_list(state.selected_indices), state.visible_height}
{[], 2}

@spec preferred_height(
  list() | nil,
  keyword()
) :: non_neg_integer()

The number of rows the element asks for.

Returns opts[:height] when given, otherwise the length of the positional options list capped at 5 — which is 0 when the options were passed under opts[:options] instead.

iex> Drafter.Widget.SelectionList.preferred_height(["a", "b"], [])
2

iex> Drafter.Widget.SelectionList.preferred_height(Enum.to_list(1..20), [])
5

iex> Drafter.Widget.SelectionList.preferred_height(nil, options: ["a"])
0

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

Draws the visible slice of the list into rect, always returning exactly rect.height strips.

Rows start at :scroll_offset and run for min(rect.height, option_count) rows; the rest of the rect is blank. :single mode draws (●) and ( ), every other mode draws [X] and [ ]. The highlight is only drawn while the widget is focused.

Callback implementation for Drafter.Widget.unmount/1.

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

Merges props into state verbatim.

Every key in props lands on the state as given, including keys the struct does not declare, and :options is stored without being normalised — so a re-render that goes through this must already supply %{id: _, label: _} maps. :selection_mode and :on_item_toggle keep their current value when absent.

iex> state = Drafter.Widget.SelectionList.mount(%{options: ["a", "b"]})
iex> Drafter.Widget.SelectionList.update(%{selection_mode: :single}, state).selection_mode
:single

iex> state = Drafter.Widget.SelectionList.mount(%{options: ["a", "b"]})
iex> Drafter.Widget.SelectionList.update(%{highlighted_index: 1}, state).highlighted_index
1

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

Narrows a re-render to :on_change, :on_item_toggle, :selection_mode and :classes.

:options, :selected and :visible_height are dropped, so they are mount-only through the component tree and the user's selection survives a re-render.

iex> props = Drafter.Widget.SelectionList.from_component_opts(["a"], [])
iex> Drafter.Widget.SelectionList.update_props_from_mount(props, %{}, []) |> Map.keys() |> Enum.sort()
[:classes, :on_change, :on_item_toggle, :selection_mode]