API Reference

import {
  Table,
  TBody,
  TBodyRow,
  TBodyCell,
  THead,
  THeadCell,
  useTableState,
} from '@vtex/admin-ui'
 
const columns = createColumns([
  {
    id: 'productName',
    header: 'Product name',
  },
  {
    id: 'inStock',
    header: 'In Stock',
  },
])
 
function Example() {
  const { data, getBodyCell, getHeadCell, getTable } = useTableState({
    columns,
    items: [...],
  })
  return (
    <Table {...getTable()}>
      <THead>
        {columns.map((column) => (
          <THeadCell {...getHeadCell(column)} />
        ))}
      </THead>
      <TBody>
        {data.map((item) => {
          return (
            <TBodyRow
              key={item.id}
              onClick={() => {...}}
            >
              {columns.map((column) => {
                return <TBodyCell {...getBodyCell(column, item)} />
              })}
            </TBodyRow>
          )
        })}
      </TBody>
    </Table>
  )
}

/**
 * Column type
 * Each column, represents a field within an item
 * @template T: Item
 * @template R: Resolver field
 */
export type TableColumn<T, R = BaseResolvers<T>> =
  | {
      id: keyof T
      header?: ((column: TableColumn<T>) => ReactNode) | string
      accessor?: ((item: T) => ReactNode) | string
      resolver?: R
      width?: any
      compare?: (a: T, b: T) => number
      sortable?: boolean
      fixed?: boolean
    }
  | {
      id: Exclude<string, keyof T>
      header?: ((column: TableColumn<T>) => ReactNode) | string
      accessor: ((item: T) => ReactNode) | string
      resolver?: R
      width?: any
      compare?: (a: T, b: T) => number
      sortable?: boolean
      fixed?: boolean
    }
  | {
      id: Exclude<string, keyof T>
      header?: ((column: TableColumn<T>) => ReactNode) | string
      accessor?: ((item: T) => ReactNode) | string
      resolver: R
      width?: any
      compare?: (a: T, b: T) => number
      sortable?: boolean
      fixed?: boolean
    }

export interface SortState {
  order?: 'ASC' | 'DESC'
  by?: string | number | symbol
}
 
export type SortDirections =
  | ['ASC', 'DESC']
  | ['DESC', 'ASC']
  | ['ASC' | 'DESC']
 
export interface SortAction {
  type: 'ASC' | 'DESC'
  columnId?: string | number | symbol
}
 
export interface SortCallbackParams<T> {
  currentSortState: SortState
  dispatch: Dispatch<SortAction>
  columnId: keyof T
  directions: SortDirections
}
 
export interface UseTableSortParams<T> {
  initialValue?: Partial<SortState>
  directions?: SortDirections
  reducer?(state: SortState, action: SortAction): SortState
  callback?(params: SortCallbackParams<T>): void
}

export interface UseSortReturn {
  order?: 'ASC' | 'DESC'
  by?: string | number | symbol
  sort(id: string | number | symbol): void
}

export type BaseResolver<T> = {
  /**
   * Resolver type name
   */
  type: string
  /**
   * Render function
   *
   * item: The item displayed for the row
   * data: Extracted column data from the item, you need to cast it before use
   * context: Relevant global information about the table's current state
   */
  render: ({
    item: T,
    data: unknown,
    context: { loading: boolean },
  }) => ReactNode
}

export type RootResolver<T> = {
  type: 'root'
  render: (props: ResolverRenderProps<null, T>) => ReactNode
}

export type PlainResolver<T> = {
  type: 'plain'
  render?: (props: ResolverRenderProps<ReactNode, T>) => ReactNode
}

export type TextResolver<T> = {
  type: 'text'
  render?: (props: ResolverRenderProps<ReactNode, T>) => ReactNode
  columnType?: 'name' | 'text'
  /**
   * It specifies how overflowed text should be signaled to the user.
   * @default auto
   */
  overflow?: 'ellipsis' | 'auto'
  /**
   * The map Function which returns the description to be rendered
   */
  mapText: (item: T) => ReactNode
  /**
   * It enables to customize the description
   */
  mapDescription?: (item: T) => ReactNode
}

export type MenuResolver<T> = {
  type: 'menu'
  render?: (props: ResolverRenderProps<JSX.Element, T>) => JSX.Element
  /**
   * A set of actions to be rendered as MenuItems
   */
  actions: Array<MenuActions<T>>
}
 
export interface MenuActions<T> {
  /**
   * MenuItem label
   */
  label: string
  /**
   * MenuItem onClick handler
   */
  onClick: (item: T, event: React.MouseEvent<HTMLDivElement>) => void
  /**
   * MenuItem icon
   */
  icon?: ReactNode
  /**
   * Whether the MenuItem is disabled or not
   * @default false
   */
  disabled?: boolean
  /**
   * Whether the MenuItem is critical or not
   * @default false
   */
  critical?: boolean
}

export type CurrencyResolver<T> = {
  type: 'currency'
  /**
   * Currency locale
   */
  locale: string
  /**
   * Currency type
   * @example 'USD'
   */
  currency: string
  render?: (props: ResolverRenderProps<string, T>) => ReactNode
}

export type DateResolver<T> = {
  type: 'date'
  /**
   * Date locale
   */
  locale: string
  /**
   * Date options
   */
  options?: Intl.DateTimeFormatOptions
  render?: (props: ResolverRenderProps<string, T>) => ReactNode
}
 
interface DateTimeFormatOptions {
  calendar?: string
  dayPeriod?: 'narrow' | 'short' | 'long'
  numberingSystem?: string
 
  dateStyle?: 'full' | 'long' | 'medium' | 'short'
  timeStyle?: 'full' | 'long' | 'medium' | 'short'
  hourCycle?: 'h11' | 'h12' | 'h23' | 'h24'
}

export type ImageResolver<T> = {
  type: 'image'
  /**
   * HTML img alt
   */
  alt?: string
  /**
   * Preview options
   * @default {display:true,delay:0,size:'regular'}
   */
  preview?: ImagePreview
  /**
   * optional render function
   */
  render?: (props: ResolverRenderProps<JSX.Element, T>) => ReactNode
}
 
type ImagePreview = {
  /**
   * if should display a preview or not
   * @default true
   */
  display: boolean
  /**
   * Delay to show (in ms)
   * @default 0
   */
  delay: number
  /**
   * Preview size
   * @default regular
   */
  size: 'small' | 'regular' | 'large'
}

export interface BulkResolver<T> {
  type: 'bulk'
  /**
   * The useBulkActions hook state return
   */
  state: BulkActionsState<T>
  render?: (props: ResolverRenderProps<ReactNode, T>) => ReactNode
}

export interface SelectionResolver<T> {
  type: 'selection'
  /**
   * The map function which returns the id to be used by the checkbox
   */
  mapId: (item: T) => string | number
  isSelected?: (item: T) => boolean
  onSelect?: (items: T[]) => void
  render?: (props: ResolverRenderProps<ReactNode, T>) => ReactNode
}