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

import Brick.Widgets.TabularList.Types
import Brick.Widgets.Center
import Brick.Widgets.List
import Brick.Widgets.Core
import Data.Void

-- * Type Variables #TypeVariables#
--
-- $TypeVariables
-- * @__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.
-- * @__e__@ is the type of list elements which are also called list rows in tabular list widgets.
-- * @__w__@ is the type that contains widths per row kind. mixed-tabular-list demo program shows how to utilize it.
-- * @__r__@ is the type for row headers. If you don't want to show row headers, set this to @__()__@ or 'Void'.

-- * Rendering #Rendering#
--
-- $Rendering
-- 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.
--
-- A rendering function for row columns or row headers is given a space with
--
-- @
-- 'setAvailableSize' (width, listItemHeight)
-- @
--
-- A rendering function for column headers or column header row header 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.
--
-- 'WidthDeficit' is calculated for renderers of tabular list components that are shrunk to the available width.
--
-- The following examples show how a rendering function can claim the available width.
--
-- @
-- 'padRight' ('Pad' $ if widthDeficit > 0 then 0 else 1) $ 'padLeft' 'Max' content
-- @
--
-- @
-- 'padRight' 'Max' content '<+>' 'str' " "
-- @
--
-- @
-- 'padLeft' ('Pad' $ if widthDeficit > 0 then 0 else 1) $ 'hCenter' content
-- @
--
-- In the examples above, I used padding with one space character at the left or the right to introduce gaps between
-- columns. If 'WidthDeficit' is positive, you may want to remove padding because a column is not followed or preceded
-- by other columns.