diff --git a/src/TableComponentsContext.tsx b/src/TableComponentsContext.tsx index 10839d8..0b85204 100644 --- a/src/TableComponentsContext.tsx +++ b/src/TableComponentsContext.tsx @@ -15,6 +15,12 @@ export interface TableComponentsContextType { Th: ElementType; Td: ElementType; } + +/** + * `HTML` elements used as default components for table + * + * @internal + */ const defaultTableComponents: TableComponentsContextType = { Table: 'table', Thead: 'thead', @@ -24,6 +30,10 @@ const defaultTableComponents: TableComponentsContextType = { Td: 'td', }; +/** + * Table components can be customized using this context. + * Defautl table components are `HTML` elements for table. + */ export const TableComponentsContext: Context = createContext< TableComponentsContextType >(defaultTableComponents); @@ -40,6 +50,25 @@ export type TableComponentsContextProviderProps = PropsWithChildren< TableComponentsContextProviderOwnProps >; +/** + * Provides the value for `TableComponentsContext` + * + * @example + * // Custom `tr` which calls the `onClick` callback with the current index of row + * function CustomTr = ({children}:{children: React.ReactNode}) { + * const index = useIndexContext() + * const onClick = useOnClickContext() + * return onClick(index)}>{children} + * } + * + * + * @example + * // Custom `td` which sets the background color to `red` if the value of the cell is less than 10, otherwise sets it to `green` + * function CustomTd = ({children}:{children: React.ReactNode}) { + * const value = useCellContext() + * return 10 ? 'green' : 'red'}}>{children} + * } + */ export function TableComponentsContextProvider( props: TableComponentsContextProviderProps, ) { diff --git a/src/array/ArrayOutput.tsx b/src/array/ArrayOutput.tsx index c1ff578..e4257d8 100644 --- a/src/array/ArrayOutput.tsx +++ b/src/array/ArrayOutput.tsx @@ -11,6 +11,14 @@ export type ArrayOutputProps = PropsWithChildren>; const defaultGetKey = (value: any, index: number) => index; +/** + * + * `ArrayOutput` renders provided `children` component once for each element in `value`, in order. + * It provides `ItemContext` and `IndexContext` to `children`, so it acts like Javascript `map` method. + * + * @param props.value - Array of elements to iterate through. + * @param props.getKey - `key` for each item will be calculated based on its value and index. If not provided, `index` will be used as `key` + */ export function ArrayOutput(props: ArrayOutputProps) { const { value: values, children, getKey = defaultGetKey } = props; return ( diff --git a/src/array/ItemContext.tsx b/src/array/ItemContext.tsx index da3696a..e38518c 100644 --- a/src/array/ItemContext.tsx +++ b/src/array/ItemContext.tsx @@ -10,6 +10,12 @@ export const ItemContext: Context< ItemContextType | undefined > = createContext | undefined>(undefined); +/** + * Returns the current context value for `ItemContext`. + * If `value` is provided, it will ignore the context value and return the given `value`. + * + * @param value - Overrides context + */ export function useItem(value?: V): ItemContextType { const context = useContext(ItemContext); if (value !== undefined) { diff --git a/src/cell/Cell.tsx b/src/cell/Cell.tsx index a3300a6..d06323e 100644 --- a/src/cell/Cell.tsx +++ b/src/cell/Cell.tsx @@ -9,6 +9,12 @@ interface CellOwnProps { export type CellProps = PropsWithChildren>; +/** + * Wraps its `children` with the component for `td`. + * Also provides its `children` with `ContentContext`. + * + * @param props.accessor - Specifies which field should be displayed in this cell. + */ export function Cell(props: CellProps) { const { accessor, children } = props; const Components = useTableComponentsContext(); diff --git a/src/column/Column.tsx b/src/column/Column.tsx index 6fe1f1a..6d5ebf8 100644 --- a/src/column/Column.tsx +++ b/src/column/Column.tsx @@ -12,6 +12,20 @@ interface ColumnOwnProps { export type ColumnProps = PropsWithChildren>; +/** + * Table column, values based on `data` passed on to `DataTable` + * + * @param props.header - Column title rendered in `th` + * @param props.accessor - Bind the column to `data`. + * + * @example + * // This column will display `data.location.latitude` values + * + * + * @example + * // You can compute values based on row values + * `${row.location.latitude} , ${row.location.longitude}`} header="lat/long" + */ export function Column(props: ColumnProps) { const { children = , accessor = null } = props; const part = useTablePart(); diff --git a/src/column/Columns.tsx b/src/column/Columns.tsx index 6b7e87c..5fac44c 100644 --- a/src/column/Columns.tsx +++ b/src/column/Columns.tsx @@ -5,6 +5,22 @@ interface ColumnsOwnProps {} export type ColumnsProps = PropsWithChildren; +/** + * Wraps `Column` components within + * + * @example + * + * + * + * + * + * + * + * + * + * + * + */ export function Columns(props: ColumnsProps) { const { children } = props; const part = useTablePart(); diff --git a/src/column/findColumns.ts b/src/column/findColumns.ts index 72bad7d..31bade8 100644 --- a/src/column/findColumns.ts +++ b/src/column/findColumns.ts @@ -1,6 +1,10 @@ import React, { ReactElement, ReactNode } from 'react'; import { isColumnsType } from './ColumnsType'; +/** + * Find `Columns` component from `children` and returns it. + * If there are multiple `Columns` component, the last one will be returned. + */ export function findColumns( children: ReactNode, ): ReactElement | null { diff --git a/src/content/ContentValue.tsx b/src/content/ContentValue.tsx index a897750..7472d73 100644 --- a/src/content/ContentValue.tsx +++ b/src/content/ContentValue.tsx @@ -12,6 +12,11 @@ export type ContentValueProps = PropsWithChildren< ContentValueOwnProps >; +/** + * Provides `value` based on the `accessor` given and the row it is being used in. + * + * @param props.accessor - Specifies which field should be provided as content. + */ export function ContentValue(props: ContentValueProps) { const { accessor, children = } = props; const value = useContentValue(accessor); diff --git a/src/content/DefaultContent.tsx b/src/content/DefaultContent.tsx index 005aa2b..6a51160 100644 --- a/src/content/DefaultContent.tsx +++ b/src/content/DefaultContent.tsx @@ -2,10 +2,14 @@ import React, { Fragment, PropsWithChildren } from 'react'; import { useContent } from './ContentContext'; interface DefaultContentOwnProps {} + export type DefaultContentProps = PropsWithChildren< DefaultContentOwnProps >; +/** + * Displays the value of cell as it is. + */ export function DefaultContent(props: DefaultContentProps) { const value = useContent(); return {value}; diff --git a/src/data/DataTable.tsx b/src/data/DataTable.tsx index 0a6fddc..cb3d4c5 100644 --- a/src/data/DataTable.tsx +++ b/src/data/DataTable.tsx @@ -9,7 +9,35 @@ interface DataTableOwnProps { } export type DataTableProps = PropsWithChildren>; - +/** + * Root component of `ctablex`. Provides its children with `DataContext` and `ColumnContext` + * + * @param props.data - data to be displayed by table + * + * @example + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
+ *
+ * + */ export function DataTable(props: DataTableProps) { const { children } = props; const columns = findColumns(children); diff --git a/src/header/HeaderCell.tsx b/src/header/HeaderCell.tsx index b5cd46d..3afc036 100644 --- a/src/header/HeaderCell.tsx +++ b/src/header/HeaderCell.tsx @@ -7,6 +7,11 @@ interface HeaderCellOwnProps { export type HeaderCellProps = PropsWithChildren; +/** + * Wraps `header` component with the componrnt for `th` + * + * @param props.header - header/title for column + */ export function HeaderCell(props: HeaderCellProps) { const Components = useTableComponentsContext(); diff --git a/src/header/TableHeader.tsx b/src/header/TableHeader.tsx index 49e0977..168926d 100644 --- a/src/header/TableHeader.tsx +++ b/src/header/TableHeader.tsx @@ -6,6 +6,9 @@ interface TableHeaderOwnProps {} export type TableHeaderProps = PropsWithChildren; +/** + * Wraps columns with the component for `thead`. + */ export function TableHeader(props: TableHeaderProps) { const { children } = props; const Components = useTableComponentsContext(); diff --git a/src/row/Row.tsx b/src/row/Row.tsx index e65ef22..628f56f 100644 --- a/src/row/Row.tsx +++ b/src/row/Row.tsx @@ -10,6 +10,11 @@ interface RowOwnProps { export type RowProps = PropsWithChildren>; +/** + * Wraps `columns` with the component for `tr` and provides `RowDataContext` + * + * @param props.row - Provide `row` prop for custom rows + */ export function Row(props: RowProps) { const Components = useTableComponentsContext(); diff --git a/src/row/Rows.tsx b/src/row/Rows.tsx index b553277..4bfeaaf 100644 --- a/src/row/Rows.tsx +++ b/src/row/Rows.tsx @@ -11,6 +11,12 @@ interface RowsOwnProps { export type RowsProps = PropsWithChildren>; +/** + * Iterates over `data` and renders `children` for each one of them, using `ArrayOutput`. + * + * @param props.keyAccessor - Specifies `id` for `ArrayOutput` iteration. + * @param props.data - `data` for rendering custom rows. + */ export function Rows(props: RowsProps) { const { children, keyAccessor } = props; const data = useData(props.data); diff --git a/src/table/Table.tsx b/src/table/Table.tsx index a4f2177..59c8a0b 100644 --- a/src/table/Table.tsx +++ b/src/table/Table.tsx @@ -5,6 +5,9 @@ interface TableOwnProps {} export type TableProps = PropsWithChildren; +/** + * Wraps its `children` with the component for `table`. + */ export function Table(props: TableProps) { const { children } = props; const Components = useTableComponentsContext(); diff --git a/src/table/TableBody.tsx b/src/table/TableBody.tsx index a98e2aa..68bdf0b 100644 --- a/src/table/TableBody.tsx +++ b/src/table/TableBody.tsx @@ -6,6 +6,9 @@ interface TableBodyOwnProps {} export type TableBodyProps = PropsWithChildren>; +/** + * Wraps its `children` with the component for `tbody`. + */ export function TableBody(props: TableBodyProps) { const { children } = props; const Components = useTableComponentsContext(); diff --git a/src/table/TablePartContext.tsx b/src/table/TablePartContext.tsx index 8789277..6a8916f 100644 --- a/src/table/TablePartContext.tsx +++ b/src/table/TablePartContext.tsx @@ -7,6 +7,12 @@ import React, { export type TablePartType = 'definition' | 'header' | 'body' | string; export type TablePartContextType = TablePartType; + +/** + * - `'header'` indicates we are inside of `TableHeader` component. + * - `'body'` indicates we are inside of `TableBody` component. + * - `'definition'` indicates we are inside of `DataTable` but outside of aforementioned parts. + */ export const TablePartContext: Context< TablePartContextType | undefined > = createContext(undefined);