Data Display Components

/**
 * Flexible text component for displaying text content with Material Design typography variants
 * @param props - Typography props
 * @returns Typography React component
 */
function Typography<C extends React.ElementType = 'span'>(props: TypographyProps<C>): JSX.Element;

interface TypographyProps<C extends React.ElementType = React.ElementType> extends StandardProps<React.HTMLAttributes<HTMLElement>, TypographyClassKey> {
  align?: 'inherit' | 'left' | 'center' | 'right' | 'justify';
  children?: React.ReactNode;
  color?: 'inherit' | 'primary' | 'secondary' | 'textPrimary' | 'textSecondary' | 'error' | 'initial';
  component?: C;
  display?: 'initial' | 'block' | 'inline';
  gutterBottom?: boolean;
  noWrap?: boolean;
  paragraph?: boolean;
  variant?: TypographyVariant | 'srOnly' | 'inherit';
  variantMapping?: Partial<Record<TypographyVariant, string>>;
}

type TypographyVariant = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'caption' | 'button' | 'overline';
type TypographyClassKey = 'root' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'subtitle1' | 'subtitle2' | 'body1' | 'body2' | 'caption' | 'button' | 'overline' | 'srOnly' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignJustify' | 'noWrap' | 'gutterBottom' | 'paragraph' | 'colorInherit' | 'colorPrimary' | 'colorSecondary' | 'colorTextPrimary' | 'colorTextSecondary' | 'colorError' | 'displayInline' | 'displayBlock';

import { Typography } from '@material-ui/core';

// Different variants
<Typography variant="h1">Heading 1</Typography>
<Typography variant="h2" color="primary">Heading 2</Typography>
<Typography variant="body1" paragraph>
  This is a paragraph of body text with bottom margin.
</Typography>
<Typography variant="caption" color="textSecondary">
  Caption text
</Typography>

// Custom component
<Typography variant="h4" component="h2" gutterBottom>
  h4 styled as h2 element
</Typography>

/**
 * Container component for displaying a series of items
 * @param props - List props
 * @returns List React component
 */
function List(props: ListProps): JSX.Element;

interface ListProps extends StandardProps<React.HTMLAttributes<HTMLUListElement>, ListClassKey> {
  children?: React.ReactNode;
  component?: React.ElementType;
  dense?: boolean;
  disablePadding?: boolean;
  subheader?: React.ReactNode;
}

type ListClassKey = 'root' | 'padding' | 'dense' | 'subheader';

/**
 * Individual item within a list component
 * @param props - List item props
 * @returns List item React component
 */
function ListItem(props: ListItemProps): JSX.Element;

interface ListItemProps extends StandardProps<ListItemTypeMap['props'], ListItemClassKey> {
  alignItems?: 'flex-start' | 'center';
  autoFocus?: boolean;
  button?: boolean;
  ContainerComponent?: React.ElementType;
  ContainerProps?: React.HTMLAttributes<HTMLDivElement>;
  dense?: boolean;
  disabled?: boolean;
  disableGutters?: boolean;
  divider?: boolean;
  selected?: boolean;
}

type ListItemClassKey = 'root' | 'container' | 'focusVisible' | 'dense' | 'alignItemsFlexStart' | 'disabled' | 'divider' | 'gutters' | 'button' | 'secondaryAction' | 'selected';

/**
 * Text content for list items supporting primary and secondary text
 * @param props - List item text props
 * @returns List item text React component
 */
function ListItemText(props: ListItemTextProps): JSX.Element;

interface ListItemTextProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, ListItemTextClassKey> {
  disableTypography?: boolean;
  inset?: boolean;
  primary?: React.ReactNode;
  primaryTypographyProps?: TypographyProps;
  secondary?: React.ReactNode;
  secondaryTypographyProps?: TypographyProps;
}

type ListItemTextClassKey = 'root' | 'multiline' | 'dense' | 'inset' | 'primary' | 'secondary';

/**
 * Icon wrapper for list items
 * @param props - List item icon props
 * @returns List item icon React component
 */
function ListItemIcon(props: ListItemIconProps): JSX.Element;

interface ListItemIconProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, ListItemIconClassKey> {
  children: React.ReactElement;
}

type ListItemIconClassKey = 'root' | 'alignItemsFlexStart';

/**
 * Avatar wrapper for list items
 * @param props - List item avatar props
 * @returns List item avatar React component
 */
function ListItemAvatar(props: ListItemAvatarProps): JSX.Element;

interface ListItemAvatarProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, ListItemAvatarClassKey> {
  children: React.ReactElement;
}

type ListItemAvatarClassKey = 'root' | 'alignItemsFlexStart';

/**
 * Secondary action area for list items
 * @param props - List item secondary action props
 * @returns List item secondary action React component
 */
function ListItemSecondaryAction(props: ListItemSecondaryActionProps): JSX.Element;

interface ListItemSecondaryActionProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, ListItemSecondaryActionClassKey> {
  children?: React.ReactNode;
}

type ListItemSecondaryActionClassKey = 'root';

/**
 * Subheader for grouping related list items
 * @param props - List subheader props
 * @returns List subheader React component
 */
function ListSubheader(props: ListSubheaderProps): JSX.Element;

interface ListSubheaderProps extends StandardProps<React.HTMLAttributes<HTMLLIElement>, ListSubheaderClassKey> {
  children?: React.ReactNode;
  color?: 'default' | 'primary' | 'inherit';
  component?: React.ElementType;
  disableGutters?: boolean;
  disableSticky?: boolean;
  inset?: boolean;
}

type ListSubheaderClassKey = 'root' | 'colorPrimary' | 'colorInherit' | 'gutters' | 'inset' | 'sticky';

/**
 * Root table component for displaying tabular data
 * @param props - Table props
 * @returns Table React component
 */
function Table(props: TableProps): JSX.Element;

interface TableProps extends StandardProps<React.TableHTMLAttributes<HTMLTableElement>, TableClassKey> {
  children: React.ReactNode;
  component?: React.ElementType;
  padding?: 'default' | 'checkbox' | 'none';
  size?: 'small' | 'medium';
  stickyHeader?: boolean;
}

type TableClassKey = 'root' | 'stickyHeader';

/**
 * Header section of a table
 * @param props - Table head props
 * @returns Table head React component
 */
function TableHead(props: TableHeadProps): JSX.Element;

interface TableHeadProps extends StandardProps<React.HTMLAttributes<HTMLTableSectionElement>, TableHeadClassKey> {
  children: React.ReactNode;
  component?: React.ElementType;
}

type TableHeadClassKey = 'root';

/**
 * Body section of a table containing data rows
 * @param props - Table body props
 * @returns Table body React component
 */
function TableBody(props: TableBodyProps): JSX.Element;

interface TableBodyProps extends StandardProps<React.HTMLAttributes<HTMLTableSectionElement>, TableBodyClassKey> {
  children: React.ReactNode;
  component?: React.ElementType;
}

type TableBodyClassKey = 'root';

/**
 * Footer section of a table
 * @param props - Table footer props
 * @returns Table footer React component
 */
function TableFooter(props: TableFooterProps): JSX.Element;

interface TableFooterProps extends StandardProps<React.HTMLAttributes<HTMLTableSectionElement>, TableFooterClassKey> {
  children: React.ReactNode;
  component?: React.ElementType;
}

type TableFooterClassKey = 'root';

/**
 * Individual row within a table
 * @param props - Table row props
 * @returns Table row React component
 */
function TableRow(props: TableRowProps): JSX.Element;

interface TableRowProps extends StandardProps<React.HTMLAttributes<HTMLTableRowElement>, TableRowClassKey> {
  children: React.ReactNode;
  component?: React.ElementType;
  hover?: boolean;
  selected?: boolean;
}

type TableRowClassKey = 'root' | 'selected' | 'hover' | 'head' | 'footer';

/**
 * Individual cell within a table row
 * @param props - Table cell props
 * @returns Table cell React component
 */
function TableCell(props: TableCellProps): JSX.Element;

interface TableCellProps extends StandardProps<React.TdHTMLAttributes<HTMLTableDataCellElement>, TableCellClassKey> {
  align?: 'inherit' | 'left' | 'center' | 'right' | 'justify';
  children?: React.ReactNode;
  component?: React.ElementType;
  padding?: 'default' | 'checkbox' | 'none';
  scope?: string;
  size?: 'small' | 'medium';
  sortDirection?: SortDirection;
  variant?: 'head' | 'body' | 'footer';
}

type TableCellClassKey = 'root' | 'head' | 'body' | 'footer' | 'sizeSmall' | 'paddingCheckbox' | 'paddingNone' | 'alignLeft' | 'alignCenter' | 'alignRight' | 'alignJustify' | 'stickyHeader';
type SortDirection = 'asc' | 'desc' | false;

/**
 * Sortable column header for tables
 * @param props - Table sort label props
 * @returns Table sort label React component
 */
function TableSortLabel(props: TableSortLabelProps): JSX.Element;

interface TableSortLabelProps extends StandardProps<ButtonBaseProps, TableSortLabelClassKey> {
  active?: boolean;
  children?: React.ReactNode;
  direction?: SortDirection;
  hideSortIcon?: boolean;
  IconComponent?: React.ComponentType<{ className: string }>;
}

type TableSortLabelClassKey = 'root' | 'active' | 'icon' | 'iconDirectionDesc' | 'iconDirectionAsc';

/**
 * Pagination controls for tables
 * @param props - Table pagination props
 * @returns Table pagination React component
 */
function TablePagination(props: TablePaginationProps): JSX.Element;

interface TablePaginationProps extends StandardProps<TableCellProps, TablePaginationClassKey> {
  ActionsComponent?: React.ComponentType<TablePaginationActionsProps>;
  backIconButtonProps?: Partial<IconButtonProps>;
  count: number;
  labelDisplayedRows?: (paginationInfo: { from: number; to: number; count: number; page: number }) => React.ReactNode;
  labelRowsPerPage?: React.ReactNode;
  nextIconButtonProps?: Partial<IconButtonProps>;
  onChangePage: (event: React.MouseEvent<HTMLButtonElement> | null, page: number) => void;
  onChangeRowsPerPage?: React.ChangeEventHandler<HTMLTextAreaElement | HTMLInputElement>;
  page: number;
  rowsPerPage: number;
  rowsPerPageOptions?: Array<number | { value: number; label: string }>;
  SelectProps?: Partial<SelectProps>;
}

type TablePaginationClassKey = 'root' | 'toolbar' | 'spacer' | 'caption' | 'selectRoot' | 'select' | 'selectIcon' | 'input' | 'menuItem' | 'actions';

/**
 * Container component implementing Material Design card pattern
 * @param props - Card props
 * @returns Card React component
 */
function Card(props: CardProps): JSX.Element;

interface CardProps extends StandardProps<PaperProps, CardClassKey> {
  raised?: boolean;
}

type CardClassKey = 'root';

/**
 * Header section of a card with title, subtitle, and action area
 * @param props - Card header props
 * @returns Card header React component
 */
function CardHeader(props: CardHeaderProps): JSX.Element;

interface CardHeaderProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, CardHeaderClassKey> {
  action?: React.ReactNode;
  avatar?: React.ReactNode;
  component?: React.ElementType;
  disableTypography?: boolean;
  subheader?: React.ReactNode;
  subheaderTypographyProps?: Partial<TypographyProps>;
  title?: React.ReactNode;
  titleTypographyProps?: Partial<TypographyProps>;
}

type CardHeaderClassKey = 'root' | 'avatar' | 'action' | 'content' | 'title' | 'subheader';

/**
 * Main content area of a card
 * @param props - Card content props
 * @returns Card content React component
 */
function CardContent(props: CardContentProps): JSX.Element;

interface CardContentProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, CardContentClassKey> {
  children?: React.ReactNode;
  component?: React.ElementType;
}

type CardContentClassKey = 'root';

/**
 * Media area of a card for images and videos
 * @param props - Card media props
 * @returns Card media React component
 */
function CardMedia(props: CardMediaProps): JSX.Element;

interface CardMediaProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, CardMediaClassKey> {
  children?: React.ReactNode;
  component?: React.ElementType;
  image?: string;
  src?: string;
}

type CardMediaClassKey = 'root' | 'media';

/**
 * Action area of a card for buttons and other interactive elements
 * @param props - Card actions props
 * @returns Card actions React component
 */
function CardActions(props: CardActionsProps): JSX.Element;

interface CardActionsProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, CardActionsClassKey> {
  children?: React.ReactNode;
  disableSpacing?: boolean;
}

type CardActionsClassKey = 'root' | 'spacing';

/**
 * Clickable area of a card
 * @param props - Card action area props
 * @returns Card action area React component
 */
function CardActionArea(props: CardActionAreaProps): JSX.Element;

interface CardActionAreaProps extends StandardProps<ButtonBaseProps, CardActionAreaClassKey> {
  children?: React.ReactNode;
}

type CardActionAreaClassKey = 'root' | 'focusVisible' | 'focusHighlight';

/**
 * Icon component for displaying Material icons and custom icons
 * @param props - Icon props
 * @returns Icon React component
 */
function Icon(props: IconProps): JSX.Element;

interface IconProps extends StandardProps<React.HTMLAttributes<HTMLSpanElement>, IconClassKey> {
  children: React.ReactNode;
  color?: 'inherit' | 'primary' | 'secondary' | 'action' | 'error' | 'disabled';
  component?: React.ElementType;
  fontSize?: 'inherit' | 'default' | 'small' | 'large';
}

type IconClassKey = 'root' | 'colorPrimary' | 'colorSecondary' | 'colorAction' | 'colorError' | 'colorDisabled' | 'fontSizeInherit' | 'fontSizeSmall' | 'fontSizeLarge';

/**
 * Wrapper for SVG icons with Material-UI styling
 * @param props - SVG icon props
 * @returns SVG icon React component
 */
function SvgIcon(props: SvgIconProps): JSX.Element;

interface SvgIconProps extends StandardProps<React.SVGAttributes<SVGSVGElement>, SvgIconClassKey> {
  children: React.ReactNode;
  color?: 'inherit' | 'primary' | 'secondary' | 'action' | 'error' | 'disabled';
  component?: React.ComponentType<React.SVGAttributes<SVGSVGElement>>;
  fontSize?: 'inherit' | 'default' | 'small' | 'large';
  htmlColor?: string;
  shapeRendering?: string;
  titleAccess?: string;
  viewBox?: string;
}

type SvgIconClassKey = 'root' | 'colorPrimary' | 'colorSecondary' | 'colorAction' | 'colorError' | 'colorDisabled' | 'fontSizeInherit' | 'fontSizeSmall' | 'fontSizeLarge';

/**
 * Avatar component for displaying user images, initials, or icons
 * @param props - Avatar props
 * @returns Avatar React component
 */
function Avatar(props: AvatarProps): JSX.Element;

interface AvatarProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, AvatarClassKey> {
  alt?: string;
  children?: React.ReactNode;
  component?: React.ElementType;
  imgProps?: React.ImgHTMLAttributes<HTMLImageElement>;
  sizes?: string;
  src?: string;
  srcSet?: string;
  variant?: 'circle' | 'rounded' | 'square';
}

type AvatarClassKey = 'root' | 'colorDefault' | 'circle' | 'rounded' | 'square' | 'img' | 'fallback';

/**
 * Badge component for displaying notifications and status indicators
 * @param props - Badge props
 * @returns Badge React component
 */
function Badge(props: BadgeProps): JSX.Element;

interface BadgeProps extends StandardProps<React.HTMLAttributes<HTMLSpanElement>, BadgeClassKey> {
  anchorOrigin?: {
    horizontal: 'left' | 'right';
    vertical: 'bottom' | 'top';
  };
  badgeContent?: React.ReactNode;
  children: React.ReactElement<any, any>;
  color?: 'default' | 'primary' | 'secondary' | 'error';
  component?: React.ElementType;
  invisible?: boolean;
  max?: number;
  overlap?: 'circle' | 'rectangle';
  showZero?: boolean;
  variant?: 'standard' | 'dot';
}

type BadgeClassKey = 'root' | 'badge' | 'colorPrimary' | 'colorSecondary' | 'colorError' | 'invisible' | 'dot' | 'anchorOriginTopRightRectangle' | 'anchorOriginBottomRightRectangle' | 'anchorOriginTopLeftRectangle' | 'anchorOriginBottomLeftRectangle' | 'anchorOriginTopRightCircle' | 'anchorOriginBottomRightCircle' | 'anchorOriginTopLeftCircle' | 'anchorOriginBottomLeftCircle';

/**
 * Chip component for displaying tags, filters, and compact information
 * @param props - Chip props
 * @returns Chip React component
 */
function Chip(props: ChipProps): JSX.Element;

interface ChipProps extends StandardProps<React.HTMLAttributes<HTMLDivElement>, ChipClassKey> {
  avatar?: React.ReactElement<any, any>;
  children?: null;
  clickable?: boolean;
  color?: 'default' | 'primary' | 'secondary';
  component?: React.ElementType;
  deleteIcon?: React.ReactElement<any, any>;
  disabled?: boolean;
  icon?: React.ReactElement<any, any>;
  label?: React.ReactNode;
  onDelete?: React.EventHandler<any>;
  size?: 'small' | 'medium';
  variant?: 'default' | 'outlined';
}

type ChipClassKey = 'root' | 'sizeSmall' | 'colorPrimary' | 'colorSecondary' | 'disabled' | 'clickable' | 'clickableColorPrimary' | 'clickableColorSecondary' | 'deletable' | 'deletableColorPrimary' | 'deletableColorSecondary' | 'outlined' | 'outlinedPrimary' | 'outlinedSecondary' | 'avatar' | 'avatarSmall' | 'avatarColorPrimary' | 'avatarColorSecondary' | 'icon' | 'iconSmall' | 'iconColorPrimary' | 'iconColorSecondary' | 'label' | 'labelSmall' | 'deleteIcon' | 'deleteIconSmall' | 'deleteIconColorPrimary' | 'deleteIconColorSecondary' | 'deleteIconOutlinedColorPrimary' | 'deleteIconOutlinedColorSecondary';

/**
 * Divider component for separating content sections
 * @param props - Divider props
 * @returns Divider React component
 */
function Divider(props: DividerProps): JSX.Element;

interface DividerProps extends StandardProps<React.HTMLAttributes<HTMLHRElement>, DividerClassKey> {
  absolute?: boolean;
  component?: React.ElementType;
  flexItem?: boolean;
  light?: boolean;
  orientation?: 'horizontal' | 'vertical';
  variant?: 'fullWidth' | 'inset' | 'middle';
}

type DividerClassKey = 'root' | 'absolute' | 'flexItem' | 'light' | 'middle' | 'vertical';