# `LedgerUI.Components.DataTable`
[🔗](https://github.com/devaction-labs/ledger_ui/blob/v0.2.0/lib/ledger_ui/components/data_table.ex#L1)

A table with a search box, sortable headers, a pagination footer and row selection, in the two
looks of Ledger UI: `advanced` (title bar, the table as a card, summary and pager underneath)
and `grid` (search at the right, the gridjs table, summary and pager).

The LiveView owns the state: it filters, sorts and slices the rows and gives the component the
current page; the component renders it and sends events back.

    <.data_table
      id="users"
      rows={@users}
      search={@search}
      on_search="search"
      sort_by={@sort_by}
      sort_dir={@sort_dir}
      on_sort="sort"
      page={@page}
      page_size={10}
      total={@total}
      on_page="paginate"
    >
      <:title>Users</:title>
      <:col :let={user} label="Name" sort_key="name">{user.name}</:col>
      <:col :let={user} label="Email">{user.email}</:col>
    </.data_table>

    def handle_event("search", %{"search" => q}, socket), do: ...
    def handle_event("sort", %{"column" => col, "direction" => dir}, socket), do: ...
    def handle_event("paginate", %{"page" => page}, socket), do: ...

Rows may be a stream (`rows={@streams.users}`): the body renders with `phx-update="stream"` and
`total` drives the footer. `:col`, `:action`, `:expand`, `:empty`, `:foot`, `row_id`, `row_key`,
`row_item`, `row_click`, selection and columns that leave by `priority` work as in
`LedgerUI.Components.Table.table/1`, which renders the table.

## Events

`on_search` (`%{"search" => q}`), `on_sort` (`%{"column" => c, "direction" => d}`), `on_page`
(`%{"page" => "3"}`), `on_page_size` (`%{"page_size" => "30"}`), `on_select`
(`%{"id" => key, "selected" => "true" | "false"}`), `on_select_all` (`%{"selected" => ..}`).
With `page_path` (a function of the page number) the pager renders `patch` links instead.

## Extras over the README

A `:toolbar` slot (a `lu-row` with a rule under it, for a search and buttons written by hand),
`body="card"` (the table directly in a `lu-card-b` instead of a `lu-tablewrap`) and the pager
looks `canvas` (plain) and `pages` (buttons, with previous arrow).

## Not implemented

`peek`, `peek_label` and `pager_siblings`/`pager_arrows` for the `lu-pager` footer are accepted;
`peek` draws nothing yet. The pager spans are not focusable (they carry `phx-click` only).

# `data_table`

## Attributes

* `id` (`:string`) (required)
* `rows` (`:any`) (required) - The rows of the current page, a list or a stream.
* `variant` (`:string`) - Defaults to `"advanced"`. Must be one of `"advanced"`, or `"grid"`.
* `body` (`:string`) - Defaults to `"wrap"`. Must be one of `"wrap"`, or `"card"`.
* `row_id` (`:any`) - Defaults to `nil`.
* `row_key` (`:any`) - Defaults to `nil`.
* `row_item` (`:any`) - Defaults to `&Function.identity/1`.
* `row_click` (`:any`) - Defaults to `nil`.
* `row_class` (`:any`) - Defaults to `nil`.
* `row_attrs` (`:any`) - Defaults to `nil`.
* `hoverable` (`:boolean`) - Defaults to `nil`.
* `search` (`:string`) - Defaults to `""`.
* `search_placeholder` (`:string`) - Defaults to `nil`.
* `on_search` (`:any`) - Defaults to `nil`.
* `sort_by` (`:string`) - Defaults to `nil`.
* `sort_dir` (`:string`) - Defaults to `"asc"`. Must be one of `"asc"`, or `"desc"`.
* `on_sort` (`:any`) - Defaults to `nil`.
* `page` (`:integer`) - Defaults to `1`.
* `page_size` (`:integer`) - Defaults to `10`.
* `total` (`:integer`) - Defaults to `nil`.
* `on_page` (`:any`) - Defaults to `nil`.
* `page_path` (`:any`) - Defaults to `nil`.
* `footer` (`:boolean`) - Defaults to `true`.
* `compact` (`:boolean`) - Defaults to `false`.
* `sticky_header` (`:boolean`) - Defaults to `false`.
* `scroll_label` (`:string`) - Defaults to `nil`.
* `peek` (`:boolean`) - Defaults to `false`.
* `peek_label` (`:string`) - Defaults to `"Hidden columns"`.
* `sort_label` (`:string`) - Defaults to `nil`.
* `row_label` (`:any`) - Defaults to `nil`.
* `headless` (`:boolean`) - Defaults to `false`.
* `borderless` (`:boolean`) - Defaults to `false`.
* `page_sizes` (`:list`) - Defaults to `[]`.
* `on_page_size` (`:any`) - Defaults to `nil`.
* `pager` (`:string`) - The pager look: `rounded`, `pill`, `circle`, `canvas` (plain) or `pages` (buttons). Defaults to `"rounded"`. Must be one of `"rounded"`, `"pill"`, `"circle"`, `"canvas"`, or `"pages"`.
* `pager_siblings` (`:integer`) - Defaults to `1`.
* `pager_arrows` (`:boolean`) - Defaults to `true`.
* `loading` (`:boolean`) - Defaults to `false`.
* `loading_rows` (`:integer`) - Defaults to `3`.
* `show_label` (`:string`) - Defaults to `"Show"`.
* `entries_label` (`:string`) - Defaults to `"entries"`.
* `prev_label` (`:string`) - Defaults to `"Previous"`.
* `next_label` (`:string`) - Defaults to `"Next"`.
* `page_label` (`:string`) - Defaults to `"Page %{page}"`.
* `filter_label` (`:string`) - Defaults to `"Filter"`.
* `summary_label` (`:string`) - Summary text with `%{from}`, `%{to}` and `%{total}`. Defaults to `nil`.
* `select_all_label` (`:string`) - Defaults to `"Select all rows"`.
* `select_label` (`:string`) - Defaults to `"Select row"`.
* `selected` (`:list`) - Defaults to `[]`.
* `all_selected` (`:boolean`) - Defaults to `nil`.
* `on_select` (`:any`) - Defaults to `nil`.
* `on_select_all` (`:any`) - Defaults to `nil`.
* `expand_label` (`:string`) - Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* `wrapper_class` (`:any`) - Defaults to `nil`.
* `select_attrs` (`:any`) - Defaults to `nil`.
* `body_class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `action`
* `actions` - Buttons at the right of the title bar.
* `col` (required) - Accepts attributes:

  * `label` (`:string`)
  * `class` (`:any`)
  * `head_class` (`:any`)
  * `align` (`:string`) - Must be one of `"left"`, `"center"`, or `"right"`.
  * `sort_key` (`:string`)
  * `priority` (`:integer`)
  * `style` (`:string`)
* `empty`
* `expand`
* `filters` - A filter panel the title bar's filter button opens. Receives the `JS` that toggles it.
* `foot` - Accepts attributes:

  * `class` (`:any`)
  * `align` (`:string`)
  * `colspan` (`:any`)
  * `priority` (`:integer`)
* `summary` - Replaces the summary text; receives `%{first: n, last: n, total: n}`.
* `title` - The `advanced` heading.
* `toolbar` - A row above the table, written by hand.
* `bulk` - Rendered under the table (a `bulk_bar`).

# `data_table_pager`

The pager of the data table footer: `lu-pg2` (`rounded`, `pill`, `circle`, `canvas`) or the
`lu-pages` buttons. Pages near the current one, the first and the last, with `…` between.

## Attributes

* `page` (`:integer`) (required)
* `pages` (`:integer`) (required) - How many pages there are.
* `shape` (`:string`) - Defaults to `"rounded"`. Must be one of `"rounded"`, `"pill"`, `"circle"`, `"canvas"`, or `"pages"`.
* `on_page` (`:any`) - Event or `%JS{}` sent with `%{"page" => "3"}`. Defaults to `nil`.
* `page_path` (`:any`) - Function of a page number returning a path (patch links). Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `page_label` (`:string`) - Defaults to `"Page %{page}"`.
* `prev_label` (`:string`) - Defaults to `"Previous"`.
* `next_label` (`:string`) - Defaults to `"Next"`.
* `siblings` (`:integer`) - Defaults to `1`.
* `arrows` (`:boolean`) - Defaults to `true`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `table_search`

The search field of the title bar (`lu-input sm search`). With `on_search`, the field sits in a
form (`<id>-search-form`, input `<id>-search`) that sends `%{"search" => query}` on every change
(debounced 300ms) and on submit.

## Attributes

* `id` (`:string`) (required)
* `value` (`:string`) - Defaults to `""`.
* `on_search` (`:any`) - Event name or `%JS{}` for the query changes. Defaults to `nil`.
* `target` (`:any`) - Defaults to `nil`.
* `placeholder` (`:string`) - Defaults to `nil`.
* `width` (`:string`) - Defaults to `"220px"`.
* `shortcut` (`:string`) - A key hint (`/`) drawn at the right. Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.

# `table_toolbar`

The toolbar above a table: search, controls, actions, and the row of applied filters as
removable chips.

## Attributes

* `id` (`:string`) - Defaults to `"table-toolbar"`.
* `search` (`:string`) - The current query; the search field shows when `on_search` or `search` is given. Defaults to `nil`.
* `on_search` (`:any`) - Defaults to `nil`.
* `search_placeholder` (`:string`) - Defaults to `nil`.
* `search_width` (`:string`) - Defaults to `"260px"`.
* `shortcut` (`:string`) - Defaults to `nil`.
* `filters` (`:list`) - Applied filters as chips: `[%{id: "plan", label: "Plano: Pro"}]`. Defaults to `[]`.
* `on_remove_filter` (`:any`) - Sent with `%{"id" => id}` by a chip's remove button. Defaults to `nil`.
* `on_clear` (`:any`) - Defaults to `nil`.
* `filters_label` (`:string`) - Defaults to `"Filtros:"`.
* `clear_label` (`:string`) - Defaults to `"Limpar tudo"`.
* `remove_label` (`:string`) - Defaults to `"Remover"`.
* `target` (`:any`) - Defaults to `nil`.
* `class` (`:any`) - Defaults to `nil`.
* Global attributes are accepted.
## Slots

* `start` - Controls right after the search (a filter button, a view switch).
* `actions` - Buttons at the right end.

---

*Consult [api-reference.md](api-reference.md) for complete listing*
