@spec component_tag() :: :data_table

The registry tag for this widget.

iex> Drafter.Widget.DataTable.component_tag()
:data_table

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

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

The positional argument is ignored. :width and :height default to the parent rect passed as :__rect__, itself defaulting to %{width: 80, height: 20}, and a :height of :auto becomes 8. Every on_* option is wrapped by Drafter.Widget.Callback, :on_sort with wrap_2/1 and the rest with wrap_1/1. The entries of the :styles map are unpacked into the separate :style, :header_style, :selected_style and :cursor_style props, filled in from :__theme__; without a theme none of the four is emitted at all. :resizable is not forwarded.

iex> props = Drafter.Widget.DataTable.from_component_opts(nil, columns: [:n], height: :auto)
iex> {props.columns, props.height, props.width, props.selection_mode, props.cursor_type}
{[:n], 8, 80, :single, :row}

iex> props = Drafter.Widget.DataTable.from_component_opts(nil, [])
iex> {props.data, props.sort_by, props.locked, props.cell_padding, Map.has_key?(props, :style)}
{[], nil, true, 0, false}

@spec get_data_height(map()) :: integer()

The number of rows available for data.

Uses :viewport_height when it is a positive integer, falling back to :height, and subtracts one row for the header when :show_header is set.

iex> Drafter.Widget.DataTable.get_data_height(%{show_header: true, viewport_height: 10})
9

iex> Drafter.Widget.DataTable.get_data_height(%{show_header: false, viewport_height: 10})
10

iex> Drafter.Widget.DataTable.get_data_height(%{show_header: true, viewport_height: 0, height: 6})
5

@spec get_data_start_y(map()) :: 0 | 1

The row at which data starts inside the widget: 1 with a header and 0 without.

iex> Drafter.Widget.DataTable.get_data_start_y(%{show_header: true})
1

iex> Drafter.Widget.DataTable.get_data_start_y(%{show_header: false})
0

@spec handle_custom_event(term(), t()) ::
  {:ok, t()} | {:ok, t(), [term()]} | {:bubble, t()}

Handles a mouse release delivered outside the normal routing, ending a resize or scrollbar drag or otherwise treating it as a click. Every other event bubbles.

@spec handle_drag(integer(), integer(), t()) :: {:ok, t()} | {:ok, t(), [term()]}

Continues a gesture as the pointer moves with a button held.

A drag already in progress keeps scrolling, resizing or reordering. A drag that starts on the header row (y == 0) begins a column resize when :locked and :resizable are both set, or a column reorder when :locked is false. Any other drag extends the row selection.

Callback implementation for Drafter.Widget.handle_event/2.

@spec handle_hover(integer(), integer(), t()) :: {:ok, t()} | {:noreply, t()}

Tracks the pointer with no button held, so the scrollbar can highlight itself as the cursor passes over it.

@spec handle_key(Drafter.Widget.key() | integer(), t()) ::
  {:ok, t()} | {:ok, t(), [term()]} | {:bubble, t()}

Moves the cursor, activates a row, or resizes the cursor column.

?+/:+ widen and ?-/:- narrow the cursor column by two, firing :on_layout_change. :left and :right move the cursor column, but only while the widget is focused; unfocused they bubble. :up, :down, :home, :end, :page_up and :page_down move the cursor row, :enter selects the highlighted row and fires :on_select, and :" " toggles the row's selection in :multiple mode. Every other key bubbles.

@spec handle_key(Drafter.Widget.key(), Drafter.Widget.modifiers(), t()) ::
  {:ok, t()} | {:ok, t(), [term()]} | {:bubble, t()}

Reorders columns with Shift+← and Shift+→, firing :on_layout_change.

Every other modified key combination bubbles, including the unmodified keys handle_key/2 would otherwise act on, because this clause takes precedence for every {:key, key, modifiers} event.

@spec handle_mouse_up(integer(), integer(), t()) :: {:ok, t()} | {:ok, t(), [term()]}

Ends the current gesture at widget-relative cell {x, y}.

A release ending a scrollbar drag only clears the drag state. One ending a resize or reorder fires :on_layout_change. Any other release is treated as a click: on the header row it sorts that column, cycling ascending, descending, unsorted, and fires :on_header_select; on a data row it selects that row and fires :on_select.

@spec handle_press(integer(), integer(), t()) :: {:ok, t()} | {:ok, t(), [term()]}

Begins a gesture at widget-relative cell {x, y}.

A press on the scrollbar column starts a scrollbar drag or jumps the viewport; a press elsewhere records the position so the matching release can act on it.

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

Handles the mouse wheel.

With :mouse_scroll_moves_selection set, which is the default, a notch moves the cursor row exactly as :up/:down would. Otherwise it scrolls the viewport by one row without moving the cursor.

@spec keybindings() :: [{String.t(), String.t()}]

The key bindings a Drafter.Widget.Footer shows for this widget.

iex> Drafter.Widget.DataTable.keybindings()
[{"↑↓", "Scroll"}, {"Enter", "Select"}, {"+/-", "Resize col"}, {"⇧←→", "Reorder col"}]

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

Builds the table state from props.

Columns are normalised from their shorthand forms, :sort_by is applied to the data immediately, and the cursor starts on row 0 when there is any data and at nil when there is none. Nothing is selected initially, whatever :selection_mode is.

iex> t = Drafter.Widget.DataTable.mount(%{columns: [:name], data: [%{name: "a"}]})
iex> {t.highlighted_index, MapSet.to_list(t.selected_indices), t.selection_mode, t.cursor_col}
{0, [], :single, 0}

iex> t = Drafter.Widget.DataTable.mount(%{})
iex> {t.columns, t.data, t.highlighted_index, t.width, t.height, t.sort_column}
{[], [], nil, 80, 20, nil}

iex> data = [%{n: 3}, %{n: 1}, %{n: 2}]
iex> t = Drafter.Widget.DataTable.mount(%{columns: [:n], data: data, sort_by: :n})
iex> {Enum.map(t.data, & &1.n), t.sort_column, t.sort_direction}
{[1, 2, 3], :n, :asc}

iex> t = Drafter.Widget.DataTable.mount(%{height: :auto})
iex> t.height
20

@spec on_rect_change(Drafter.Widget.rect(), t()) :: t()

Stores the laid-out geometry on the state.

Returns the state with :viewport_height and :width taken from rect, so scroll and scrollbar calculations run against the geometry the widget was actually given rather than the values supplied at mount.

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

opts[:height], or :auto when it is absent, letting the layout give the table whatever space is left.

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

iex> Drafter.Widget.DataTable.preferred_height(nil, height: 15)
15

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

Draws the table into rect, returning exactly rect.height strips.

Theme styles are folded in first, then :viewport_height is set from rect so the row window matches the space actually given. The table is drawn no wider than min(state.width, rect.width). The header takes the first row when :show_header is set, and a vertical scrollbar is drawn in the rightmost column when :show_scrollbars is set and the row count exceeds the data height.

Callback implementation for Drafter.Widget.unmount/1.

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

Folds fresh props into state.

New :data is re-sorted by the column currently sorted on, if any, and the highlighted row index is clamped to the new row count. :sort_by, :fixed_columns and both :mouse_scroll_* flags are not re-read and keep their mounted values. A change in the number of columns discards any saved :col_widths.

iex> t = Drafter.Widget.DataTable.mount(%{columns: [:n], data: [%{n: 1}, %{n: 2}]})
iex> updated = Drafter.Widget.DataTable.update(%{data: [%{n: 9}]}, t)
iex> {updated.data, updated.highlighted_index}
{[%{n: 9}], 0}

iex> data = [%{n: 3}, %{n: 1}]
iex> t = Drafter.Widget.DataTable.mount(%{columns: [:n], data: data, sort_by: :n})
iex> updated = Drafter.Widget.DataTable.update(%{data: [%{n: 5}, %{n: 4}]}, t)
iex> Enum.map(updated.data, & &1.n)
[4, 5]

iex> t = Drafter.Widget.DataTable.mount(%{columns: [:n], fixed_columns: 1})
iex> Drafter.Widget.DataTable.update(%{fixed_columns: 0}, t).fixed_columns
1

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

Narrows the props a re-render feeds to update/2.

Always passes the five callbacks, :columns, :data, :selection_mode, :sortable, :locked, :cursor_type, :cell_padding and :fixed_columns, and adds :width and :height only when they differ from the state's. The style maps and :show_header, :show_cursor, :zebra_stripes, :show_scrollbars and :column_fit_mode are left out, so they stay as mounted.