Renders a data grid.

The browser draws only the rows on the screen, and asks the grid for the others as the person scrolls. A click on a column's header sorts by it (with Shift, by it too); the edge of a header resizes its column, and a double click there fits the column to its content. The arrow keys move between the cells, Shift with them selects a range, and ⌘C (Ctrl+C) copies the range as text that a spreadsheet pastes.

Columns

Each :col is a column (see Masu.Column):

• field - the key of the row's value (a map key or a struct field);
• value - a function of the row that computes the value instead; it needs a key, and does not sort or filter with an Ecto source;
• key - the name of the column in Masu.Test and in filters; the field as a string unless given;
• label - the header; the field in words unless given;
• type - :text (the default), :enum, :integer, :number, :decimal, :date, :datetime, :time or :boolean;
• width and min_width - in pixels;
• grow - true takes the room the columns leave in a wider grid, from its width up (a title, a description); a number is its share of it, grow={2} twice that of grow;
• align - :start, :center or :end (numbers are at the end);
• sortable, filterable and searchable - false to turn off, searchable is on for text and enums;
• editable - in a grid that edits: false for a read-only column, or a function of the row that says whether its cell edits;
• values - the values of an :enum column, which its editor offers;
• decimals - the digits after the point of a :decimal or :number column, whatever the value has;
• filters - the Masu.Filter operators the column offers, of its type: those the app runs, in a controlled grid (on_query).
• editor - an editor of your own for its cells: a function component of a form field (a Koyomi picker, a Kotoba editor, any HEEx), or the name of an editor of the browser's; see the Editors of your own guide.

A :col with content renders each cell, with the row as :let:

<:col :let={user} field={:name}>
  <.link navigate={~p"/users/#{user}"}>{user.name}</.link>
</:col>

Writes and actions

A grid with a changeset edits its cells, and with struct and deletable adds and deletes rows, its own way; on_update, on_create, on_delete and on_restore write them your way, each a function of a Masu.Write; see the Editing guide. history keeps who changed each cell, when, and from what, and brings a value back; see Masu.History and the History guide. :action acts on the rows selected, and :row_action on a row; see Masu.Action and the Actions guide. on_row_activate opens a row (a panel beside the grid, its page) on a click on it or Enter. scope is in every write and every action.

Menus

cell_menu gives each cell a menu (a right click, or the context-menu key or Shift+F10 on the active cell): copy, filter by the cell's value, sort. :header_action and :cell_action add items of your own to the header menus and to the menu of the cells; see Masu.Action and the Menus of your own guide.

Attributes

• id (:string) (required) - the id of the grid.
• rows (:list) - the rows: maps or structs, or lists of values (see columns), up to about 10,000; past that, an Ecto source (see the Sources guide). Defaults to nil.
• columns (:list) - for a grid with no :col slots: its columns, each a key, or a keyword list or map of a :col's attributes; without a field, a column reads the row at its place (rows as lists), and without a type, it takes the type of its values (:auto); see the Columns guide. Defaults to nil.
• source (:any) - an Ecto query or schema (with repo), or {module, opts} of a Masu.Source. Defaults to nil.
• repo (:atom) - the repo of an Ecto source. Defaults to nil.
• repo_opts (:list) - options for each call to the repo. Defaults to [].
• read (:any) - an Ecto source's read of a block of rows, your own: a function of the query (with the grid's filters, search and order) and %{offset:, limit:, order:, after:}, which gives the rows; see the Sources guide. Defaults to nil.
• changeset (:any) - a function of a row and params that gives a changeset: the person edits the cells, which the grid saves its own way (Masu.Write.save/1), see the Editing guide. Defaults to nil.
• struct (:any) - with changeset: the struct of a new row (or a function that gives it), which the changeset casts and the repo inserts; the person adds rows. Defaults to nil.
• create_with (:any) - fields every new row gets, as a map or keyword list (%{account_id: @current_scope.account.id}): put on struct before the changeset and again after it, so params cannot change them; the person neither sets nor edits a cell of these fields. Defaults to nil.
• on_update (:any) - a function of a Masu.Write of edited cells, which saves them and gives the write back with their results; the person edits the cells, see Masu.Write. Defaults to nil.
• on_create (:any) - a function of a Masu.Write of new rows, as on_update; the person adds rows. Defaults to nil.
• on_delete (:any) - a function of a Masu.Write of rows to delete, as on_update; the person deletes rows. Defaults to nil.
• on_restore (:any) - a function of a Masu.Write of deleted rows to bring back (an undo), as on_update; a grid that deletes its own way brings them back its own way. Defaults to nil.
• deletable (:any) - true to delete rows (the grid's own way: with the repo of an Ecto source, or from a list; or with on_delete), false never, or a function of a row that says whether it deletes. Defaults to nil.
• row_editable (:any) - a function of a row: false makes every cell of the row read-only. Defaults to nil.
• history (:atom) - a Masu.History store: the grid records who changed each cell, when, from what to what, and a person sees a cell's history and brings a value back; user says who. Defaults to nil.
• scope (:any) - what your app knows of the person (@current_scope): every Masu.Write and every action's context has it. Defaults to nil.
• live (:any) - {pubsub, topic}: shows the rows that change on the topic as they change, see Masu.Live. Defaults to nil.
• presence (:any) - removed in 0.4: a grid's people are those of an Issho room, issho; see the Upgrading guide. Defaults to nil.
• issho (:any) - the grid's people, in an Issho room: [instance: MyApp.Issho, document: "notebook:42/tasks"], with the keys of every component (Issho.Join): the grid's document (its name, the same wherever it is: its page, a document; its room is the part before the first "/"), can, people (false hides the avatars above the grid, on a page that lists its people itself), follow (false for a grid that takes no part in following), claims and on_behalf_of; and Masu's own actor (the person as the room knows them; user unless given). Agents in the room are among them; see the Collaboration guide. Defaults to nil.
• people (:any) - removed in 0.5: issho's :people. Defaults to nil.
• follow (:any) - removed in 0.5: issho's :follow. Defaults to nil.
• user (:map) - with presence or issho: this person, %{id: ..., name: ..., color: ..., avatar: ...}. Defaults to nil.
• url (:boolean) - when true, the person's view (order, filters, search, columns) goes into the URL's params, under the grid's id, and a link opens it; see Masu.View. Defaults to false.
• views (:atom) - a Masu.Views store: the grid keeps each person's last view, and a views menu saves named views; needs user. Defaults to nil.
• views_key (:string) - with views: the name of the grid in the store; its id unless given. Defaults to nil.
• views_scope (:any) - with views: whose views these are, such as the account's id; the store keeps each scope's views apart, so a view shared in one is not offered in another. Defaults to nil.
• columns_menu (:boolean) - when true, a columns menu to show, hide, pin and move columns. Defaults to false.
• share_view (:boolean) - with issho: whether the person's order, filters and search go to the others, who see them when they follow the person. Defaults to true.
• selectable (:boolean) - rows with a box to select them, and every row of the query at once; see Masu.Live.selected/1. Defaults to false.
• on_select (:any) - a function called with %{count: n, all: boolean} when the selection changes. Defaults to nil.
• on_row_activate (:any) - a function called with %{id: id, row: row, grid: id, scope: scope} when the person opens a row: a click on it, or Enter on its active cell, where the cell does not edit. It gives {:patch, path} or {:navigate, path} for the grid to follow, or anything else; see the Actions guide. Defaults to nil.
• export (:any) - an Export menu: true for CSV and XLSX, or a list of :csv and :xlsx; false (the default) has none, and the server exports nothing; see Masu.Export. Defaults to false.
• cell_menu (:any) - a menu on each cell (a right click, or the context-menu key or Shift+F10 on the active cell): true for its built-in items, or a list of :copy, :filter and :sort; false (the default) has only the :cell_action items, if any; see Masu.Action. Defaults to false.
• group_by (:any) - the keys of the columns the rows start grouped by, the first the outermost; see Masu.Group. Defaults to [].
• tree (:any) - rows in a tree: the field of a row that holds its parent's id (or a function of the row); see Masu.Tree. Defaults to nil.
• expanded (:any) - the rows that start open: with tree, the ids of the rows; with groups, :all for every group at every level, or the keys of the columns whose groups start open ([:status]); see Masu.Group. Defaults to [].
• count (:atom) - how the grid counts its rows: :exact with the query, :deferred after the first rows (in a task), :none only when the person goes to the end; see the Export, selection and large tables guide. Defaults to :exact. Must be one of :exact, :deferred, or :none.
• count_limit (:integer) - the most rows an Ecto source counts: past it, the grid says it has at least that many ("10,000+"), and counts them all when the person goes to the end; see the Export, selection and large tables guide. Defaults to nil.
• paging (:atom) - :pages shows a page of rows at a time, with a pager below the grid, and the page in the view. Defaults to :scroll. Must be one of :scroll, or :pages.
• page_size (:integer) - with paging={:pages}: the rows of a page, read from the source at once (at most max_block). Defaults to 50.
• block_size (:integer) - the rows the grid reads from its source at once as the person scrolls (at most max_block). Defaults to 100.
• max_block (:integer) - the most rows of one read from the source: higher for a source where a read is costly and rows are small; see the Export, selection and large tables guide. Defaults to 500.
• load (:atom) - how the grid reads its source: :inline (the default) in the event, :async in a task, for a slow source: the LiveView answers meanwhile, the grid says it runs, with Stop; see the Sources guide. Defaults to :inline. Must be one of :inline, or :async.
• timeout (:integer) - with load={:async}: the milliseconds a read may take, then it stops and the grid says so. Defaults to nil.
• on_query (:any) - a controlled grid: the LiveView runs the query. The grid shows rows as they are, and calls this function with %{query: %Masu.Query{}, page: n, offset: n, limit: n} when the person sorts, filters, searches or goes to a page; see the Sources guide. Defaults to nil.
• total (:integer) - with on_query: how many rows the LiveView's query has (its rows are a page of them). Defaults to nil.
• loading (:boolean) - with on_query: the LiveView runs its query; the grid says so, and keeps its rows until the new ones come. Defaults to false.
• multi_sort (:boolean) - false sorts by one column at a time: Shift adds none. Defaults to true.
• filter_bar (:boolean) - the filter bar: the chips of the filters and Add filter above the grid, and on each header a menu of its sorts and filter; false for the leaner header, a funnel on each header that filters; see the Filters guide. Defaults to true.
• header_filters (:boolean) - whether a header's menu has its column's filter; false with the filter bar: the filters are the bar's alone, and a header's menu has its sorts; see the Filters guide. Defaults to true.
• row_id (:any) - a function that gives a row's id; the id of the row unless given, or its place in the query for a row without one in a grid that needs no ids. :position: the place in the query, always, for a read-only grid of rows with no id; see the Sources guide. Defaults to nil.

• sort (:list) - the first order: keys, {key, :asc | :desc} or Masu.Sort structs. Defaults to [].

• filters (:list) - the first filters: {key, op, value} or Masu.Filter structs. Defaults to [].
• searchable (:boolean) - when true, a search box above the grid. Defaults to false.
• label (:string) - the name of the grid for a screen reader. Defaults to nil.
• label_id (:string) - the id of an element that names the grid. Defaults to nil.
• density (:atom) - the room around a cell's text: rows of 28, 36 or 48 pixels and their padding, unless row_height is given. Defaults to :normal. Must be one of :compact, :normal, or :comfortable.
• row_height (:integer) - the height of a row, in pixels; of the density unless given. Defaults to nil.
• height (:string) - the height of the whole grid, as CSS (100% fills its container); the rows take what its toolbar leaves; "auto": the height of its rows, up to max_height (a grid in a document). Defaults to "32rem".
• max_height (:string) - with height="auto": the most the rows take, as CSS; past it, they scroll. Defaults to "32rem".
• wheel (:atom) - :page for a grid in a page that scrolls (a document): the wheel scrolls the page until the person is in the grid (a click, the keyboard), and the grid then. Defaults to :grid. Must be one of :grid, or :page.
• view (:map) - the view the grid opens with: a view's params (Masu.View), such as a saved view's (Masu.Views); a link's view (url) wins over it, and it over the person's last view. Defaults to nil.
• locale (:string) - the locale that formats numbers and dates; the browser's unless given. Defaults to nil.
• messages (:map) - words that replace the built-in ones, by key (search, empty, rows...): Masu.Messages has every key, for a grid in another language. Defaults to %{}.
• class (:any) - classes for the grid element. Defaults to nil.
• Global attributes are accepted. attributes for the grid element.

Slots

• col - a column; without any, the columns are columns, or the source's. Accepts attributes:
  • field (:any)
  • value (:any)
  • key (:string)
  • label (:string)
  • type (:atom)
  • width (:integer)
  • min_width (:integer)
  • grow (:any)
  • align (:atom)
  • sortable (:boolean)
  • filterable (:boolean)
  • searchable (:boolean)
  • editable (:any)
  • values (:list)
  • decimals (:integer)
  • raw (:boolean)
  • hidden (:boolean)
  • pinned (:atom)
  • aggregate (:any)
  • filters (:list)
  • editor (:any)
• header_action - an item of each column's header menu: a function, an event to the LiveView, a JS command, or a panel of its content; see Masu.Action. Accepts attributes:
  • label (:string) (required)
  • on_action (:any)
  • event (:string)
  • js (:any)
  • columns (:list)
  • types (:list)
  • show (:any)
• cell_action - an item of the menu of a cell, as :header_action; see Masu.Action. Accepts attributes:
  • label (:string) (required)
  • on_action (:any)
  • event (:string)
  • js (:any)
  • columns (:list)
  • types (:list)
  • show (:any)
• action - an action on the rows selected, a button of the bar above the grid while rows are selected; needs selectable; see Masu.Action. Accepts attributes:
  • label (:string) (required)
  • on_action (:any)
  • event (:string)
  • confirm (:string)
  • danger (:boolean)
  • keep_selection (:boolean)
• row_action - an action on a row, in the menu at the end of each row and in the menu of its cells: a function, an event, or a link (navigate, patch); see Masu.Action. Accepts attributes:
  • label (:string) (required)
  • on_action (:any)
  • event (:string)
  • navigate (:any)
  • patch (:any)
  • show (:any)
  • disabled (:any)
  • confirm (:string)
  • danger (:boolean)
• empty - what the grid shows when it has no rows.
• detail - what a row shows when it opens, under it: any HEEx, another data_grid too; it gets the row.
• person - draws a person who has the grid open (:let), see the Collaboration guide; initials in their color unless given.