-- | This module contains only conceptual documentation.
module Brick.Widgets.TabularList where

import Brick.Widgets.TabularList.Types
import Brick.Widgets.Center
import Brick.Widgets.List

-- * #SharedTraitsOfTabularListWidgets# Shared Traits of Tabular List Widgets
--
-- $SharedTraitsOfTabularListWidgets
-- A tabular list consists of cells, column headers, and row headers. Column headers and row headers are optional.
-- 'WidthDeficit' is calculated for renderers of list elements that are shrunk to the available width.
--
-- Widths for list elements are either fixed or calculated. Heights are always fixed.
--
-- Because tabular list widgets build on top of 'GenericList', attributes for 'GenericList' apply to tabular list
-- widgets if the attributes are defined in your brick application.
--
-- It can handle a very large data set if you delete invisible rows from memory and fetch visible rows from a database
-- (file). For example, SQLite database file can handle a large spreadsheet.

-- * #Rendering# Rendering
--
-- $Rendering
-- A rendering function for cells or row headers is given a space with
--
-- > setAvailableSize (width, listItemHeight)
--
-- A rendering function for column headers is given a space with
--
-- > setAvailableSize (width, columnHeaderHeight)
--
-- If the given height for rendering functions is not claimed, the list will look broken.
--
-- The given width for rendering functions must be claimed by the returned widget with brick's padding functions or
-- 'hCenter'. Otherwise, the list will look broken.
--
-- The following examples show how a rendering function can claim the available width.
--
-- > let rp = if widthDeficit > 0 then 0 else 1
-- > in padRight (Pad rp) $ padLeft Max content
--
-- > padRight Max content <+> str " "
--
-- > let lp = if widthDeficit > 0 then 0 else 1
-- > in padLeft (Pad lp) $ hCenter content
--
-- In the examples above, I used padding with one character at the left or the right to introduce gaps between columns.
-- If 'WidthDeficit' is positive, you may want to remove padding because the element that is being rendered is not
-- followed or preceded by other columns.

-- * #ListTypeVariables# List Type Variables
--
-- $ListTypeVariables
-- * @__n__@ is the type of the resource name for the list. This is not for column headers because column headers are
-- above the list. Read [brick user guide](https://github.com/jtdaugherty/brick/blob/master/docs/guide.rst) for more
-- details.
-- * @__row__@ is the type of each row.
-- * @__cell__@ is the type of columns of each row. If you want to differentiate different columns, @__cell__@ should
-- have a data constructor for each type of column.
-- * @__rowH__@ is the type of row header.
-- * @__colH__@ is the type of column header.