Data Display

/**
 * A group of disclosures that can be expanded and collapsed
 * @param props - Accordion configuration and content properties
 * @returns JSX element as accordion group
 */
function Accordion(props: SpectrumAccordionProps): JSX.Element;

interface SpectrumAccordionProps {
  /** The disclosures within the accordion group */
  children: React.ReactNode;
  /** Whether the Accordion should be displayed with a quiet style */
  isQuiet?: boolean;
  /** Handler for when expanded items change */
  onExpandedChange?: (expandedKeys: Set<Key>) => void;
  /** Default expanded keys */
  defaultExpandedKeys?: Iterable<Key>;
}

/**
 * Individual disclosure panel that can be expanded or collapsed
 * @param props - Disclosure configuration and content properties
 * @returns JSX element as disclosure panel
 */
function Disclosure(props: SpectrumDisclosureProps): JSX.Element;

interface SpectrumDisclosureProps {
  /** Unique identifier for the disclosure */
  id?: Key;
  /** Whether the disclosure is expanded */
  isExpanded?: boolean;
  /** Default expanded state */
  defaultExpanded?: boolean;
  /** Handler for when expanded state changes */
  onExpandedChange?: (isExpanded: boolean) => void;
  /** Disclosure content */
  children: React.ReactNode;
}

/**
 * Title component for disclosure panels providing the clickable header
 * @param props - Title configuration and content properties
 * @returns JSX element as disclosure title
 */
function DisclosureTitle(props: SpectrumDisclosureTitleProps): JSX.Element;

interface SpectrumDisclosureTitleProps {
  /** Title content */
  children: React.ReactNode;
  /** Title heading level */
  level?: 1 | 2 | 3 | 4 | 5 | 6;
}

/**
 * Content panel component for disclosure sections containing the collapsible content
 * @param props - Panel configuration and content properties
 * @returns JSX element as disclosure panel content
 */
function DisclosurePanel(props: SpectrumDisclosurePanelProps): JSX.Element;

interface SpectrumDisclosurePanelProps {
  /** Panel content */
  children: React.ReactNode;
}

/**
 * Data table with sorting, selection, and keyboard navigation
 * @param props - Table configuration and data properties
 * @returns JSX element as interactive data table
 */
function TableView<T>(props: SpectrumTableProps<T>): JSX.Element;

interface SpectrumTableProps<T> extends DOMProps, StyleProps {
  /** Column definitions */
  children: React.ReactElement<ColumnProps<T>>[];
  /** Data density */
  density?: "compact" | "regular" | "spacious";
  /** Selection behavior */
  selectionMode?: SelectionMode;
  /** Selection style */
  selectionStyle?: "checkbox" | "highlight";
  /** Currently selected keys */
  selectedKeys?: Selection;
  /** Default selected keys */
  defaultSelectedKeys?: Selection;
  /** Disallow empty selection */
  disallowEmptySelection?: boolean;
  /** Current sort configuration */
  sortDescriptor?: SortDescriptor;
  /** Loading state */
  loadingState?: LoadingState;
  /** Empty state content */
  renderEmptyState?: () => React.ReactNode;
  /** Width of the table */
  width?: DimensionValue;
  /** Height of the table */
  height?: DimensionValue;
  /** Maximum height before scrolling */
  maxHeight?: DimensionValue;
  /** Selection change handler */
  onSelectionChange?: (keys: Selection) => void;
  /** Sort change handler */
  onSortChange?: (descriptor: SortDescriptor) => void;
  /** Row action handler */
  onAction?: (key: Key) => void;
  /** Resize column handler */
  onResizeStart?: (widths: Map<Key, ColumnSize>) => void;
  /** Resize end handler */
  onResizeEnd?: (widths: Map<Key, ColumnSize>) => void;
}

/**
 * Table header container for column definitions
 */
function TableHeader<T>(props: TableHeaderProps<T>): JSX.Element;

/**
 * Table body container for data rows
 */
function TableBody<T>(props: TableBodyProps<T>): JSX.Element;

/**
 * Column definition for table structure
 */
function Column<T>(props: SpectrumColumnProps<T>): JSX.Element;

/**
 * Table row containing cells
 */
function Row<T>(props: RowProps<T>): JSX.Element;

/**
 * Individual table cell
 */
function Cell(props: CellProps): JSX.Element;

interface SpectrumColumnProps<T> {
  /** Column header content */
  children: React.ReactNode;
  /** Column width */
  width?: DimensionValue;
  /** Minimum column width */
  minWidth?: DimensionValue;
  /** Maximum column width */
  maxWidth?: DimensionValue;
  /** Default column width */
  defaultWidth?: DimensionValue;
  /** Whether column is sortable */
  allowsSorting?: boolean;
  /** Whether column allows resizing */
  allowsResizing?: boolean;
  /** Text alignment in column */
  align?: "start" | "center" | "end";
  /** Whether column should show divider */
  showDivider?: boolean;
  /** Whether column is hidden */
  isRowHeader?: boolean;
}

interface RowProps<T> extends DOMProps {
  /** Row cell content */
  children: React.ReactNode;
  /** Text value for accessibility */
  textValue?: string;
}

interface CellProps extends DOMProps {
  /** Cell content */
  children: React.ReactNode;
  /** Text value for accessibility */
  textValue?: string;
}

// Basic data table
<TableView 
  selectionMode="multiple"
  sortDescriptor={{column: 'name', direction: 'ascending'}}
  onSortChange={setSortDescriptor}
  onSelectionChange={setSelectedKeys}
>
  <TableHeader>
    <Column key="name" allowsSorting>Name</Column>
    <Column key="email" allowsSorting>Email</Column>
    <Column key="role">Role</Column>
    <Column key="actions" align="end">Actions</Column>
  </TableHeader>
  <TableBody items={users}>
    {(user) => (
      <Row key={user.id}>
        <Cell>{user.name}</Cell>
        <Cell>{user.email}</Cell>
        <Cell>{user.role}</Cell>
        <Cell>
          <ActionGroup>
            <Item key="edit">Edit</Item>
            <Item key="delete">Delete</Item>
          </ActionGroup>
        </Cell>
      </Row>
    )}
  </TableBody>
</TableView>

/**
 * List view for displaying collections with selection
 * @param props - ListView configuration and data properties
 * @returns JSX element as interactive list
 */
function ListView<T>(props: SpectrumListViewProps<T>): JSX.Element;

interface SpectrumListViewProps<T> extends DOMProps, StyleProps {
  /** List items data */
  items?: Iterable<T>;
  /** Item elements */
  children: (item: T) => React.ReactElement;
  /** Selection behavior */
  selectionMode?: SelectionMode;
  /** Selection style */
  selectionStyle?: "checkbox" | "highlight";
  /** Currently selected keys */
  selectedKeys?: Selection;
  /** Default selected keys */
  defaultSelectedKeys?: Selection;
  /** Disallow empty selection */
  disallowEmptySelection?: boolean;
  /** Loading state */
  loadingState?: LoadingState;
  /** List width */
  width?: DimensionValue;
  /** List height */
  height?: DimensionValue;
  /** Maximum height */
  maxHeight?: DimensionValue;
  /** Data density */
  density?: "compact" | "regular" | "spacious";
  /** Empty state renderer */
  renderEmptyState?: () => React.ReactNode;
  /** Selection change handler */
  onSelectionChange?: (keys: Selection) => void;
  /** Item action handler */
  onAction?: (key: Key) => void;
  /** Load more handler for infinite scroll */
  onLoadMore?: () => void;
}

/**
 * Hierarchical tree view for nested data structures
 * @param props - TreeView configuration and data properties
 * @returns JSX element as interactive tree
 */
function TreeView<T>(props: SpectrumTreeViewProps<T>): JSX.Element;

/**
 * Individual tree item with expand/collapse capability
 */
function TreeViewItem<T>(props: SpectrumTreeViewItemProps<T>): JSX.Element;

/**
 * Content container for tree items
 */
function TreeViewItemContent(props: SpectrumTreeViewItemContentProps): JSX.Element;

interface SpectrumTreeViewProps<T> extends DOMProps, StyleProps {
  /** Tree items data */
  items?: Iterable<T>;
  /** Tree item elements */
  children: (item: T) => React.ReactElement;
  /** Selection behavior */
  selectionMode?: SelectionMode;
  /** Selection style */
  selectionStyle?: "checkbox" | "highlight";
  /** Currently selected keys */
  selectedKeys?: Selection;
  /** Default selected keys */
  defaultSelectedKeys?: Selection;
  /** Expanded keys */
  expandedKeys?: Set<Key>;
  /** Default expanded keys */
  defaultExpandedKeys?: Set<Key>;
  /** Disallow empty selection */
  disallowEmptySelection?: boolean;
  /** Tree width */
  width?: DimensionValue;
  /** Tree height */
  height?: DimensionValue;
  /** Selection change handler */
  onSelectionChange?: (keys: Selection) => void;
  /** Expand change handler */
  onExpandedChange?: (keys: Set<Key>) => void;
  /** Item action handler */
  onAction?: (key: Key) => void;
}

interface SpectrumTreeViewItemProps<T> {
  /** Item content */
  children: React.ReactNode;
  /** Child items */
  childItems?: Iterable<T>;
  /** Whether item has children */
  hasChildItems?: boolean;
  /** Text value for accessibility */
  textValue?: string;
}

/**
 * Status badge for showing categorical information
 * @param props - Badge styling and content properties
 * @returns JSX element as status badge
 */
function Badge(props: SpectrumBadgeProps): JSX.Element;

interface SpectrumBadgeProps extends DOMProps, StyleProps {
  /** Badge content */
  children: React.ReactNode;
  /** Badge color variant */
  variant?: "neutral" | "accent" | "informative" | "positive" | "notice" | "negative" | "gray" | "red" | "orange" | "yellow" | "chartreuse" | "celery" | "green" | "seafoam" | "cyan" | "blue" | "indigo" | "purple" | "fuchsia" | "magenta";
  /** Badge size */
  size?: "S" | "M" | "L";
}

/**
 * Status indicator with color-coded states
 * @param props - StatusLight variant and content properties
 * @returns JSX element as status indicator
 */
function StatusLight(props: SpectrumStatusLightProps): JSX.Element;

interface SpectrumStatusLightProps extends DOMProps, StyleProps {
  /** Status light content/label */
  children?: React.ReactNode;
  /** Status variant */
  variant?: "neutral" | "accent" | "informative" | "positive" | "notice" | "negative";
  /** Size of the status indicator */
  size?: "S" | "M" | "L";
  /** Whether the indicator is disabled */
  isDisabled?: boolean;
}

/**
 * User avatar with image, initials, or icon
 * @param props - Avatar source and styling properties
 * @returns JSX element as user avatar
 */
function Avatar(props: SpectrumAvatarProps): JSX.Element;

interface SpectrumAvatarProps extends DOMProps, StyleProps {
  /** Image source URL */
  src?: string;
  /** Alt text for image */
  alt?: string;
  /** Avatar size */
  size?: "avatar-size-50" | "avatar-size-75" | "avatar-size-100" | "avatar-size-200" | "avatar-size-300" | "avatar-size-400" | "avatar-size-500" | "avatar-size-600" | "avatar-size-700";
  /** Whether avatar is disabled */
  isDisabled?: boolean;
}

/**
 * Optimized image display with loading states
 * @param props - Image source and display properties
 * @returns JSX element as optimized image
 */
function Image(props: SpectrumImageProps): JSX.Element;

interface SpectrumImageProps extends DOMProps, StyleProps {
  /** Image source URL */
  src: string;
  /** Alt text for accessibility */
  alt: string;
  /** Object fit behavior */
  objectFit?: "fill" | "contain" | "cover" | "none" | "scale-down";
  /** Loading behavior */
  loading?: "eager" | "lazy";
  /** Cross-origin configuration */
  crossOrigin?: "anonymous" | "use-credentials";
  /** Image width */
  width?: DimensionValue;
  /** Image height */
  height?: DimensionValue;
  /** Load event handler */
  onLoad?: () => void;
  /** Error event handler */
  onError?: () => void;
}

/**
 * Label-value pair display with consistent formatting
 * @param props - LabeledValue content and styling properties
 * @returns JSX element as formatted label-value pair
 */
function LabeledValue(props: SpectrumLabeledValueProps): JSX.Element;

interface SpectrumLabeledValueProps extends DOMProps, StyleProps {
  /** Label content */
  label: React.ReactNode;
  /** Value content */
  value: React.ReactNode;
  /** Layout orientation */
  orientation?: "horizontal" | "vertical";
  /** Label width when horizontal */
  labelWidth?: DimensionValue;
  /** Text alignment */
  labelAlign?: "start" | "end";
}

function UserManagement() {
  const [users, setUsers] = useState([]);
  const [selectedKeys, setSelectedKeys] = useState(new Set());
  const [sortDescriptor, setSortDescriptor] = useState({
    column: 'name',
    direction: 'ascending'
  });

  return (
    <div>
      {/* Summary badges */}
      <Flex gap="size-200" marginBottom="size-300">
        <Badge variant="positive">
          {users.filter(u => u.status === 'active').length} Active
        </Badge>
        <Badge variant="notice">
          {users.filter(u => u.status === 'pending').length} Pending
        </Badge>
        <Badge variant="negative">
          {users.filter(u => u.status === 'inactive').length} Inactive
        </Badge>
      </Flex>

      {/* User table */}
      <TableView
        selectionMode="multiple"
        selectedKeys={selectedKeys}
        onSelectionChange={setSelectedKeys}
        sortDescriptor={sortDescriptor}
        onSortChange={setSortDescriptor}
        density="regular"
      >
        <TableHeader>
          <Column key="avatar" width="size-600">User</Column>
          <Column key="name" allowsSorting>Name</Column>
          <Column key="email" allowsSorting>Email</Column>
          <Column key="role" allowsSorting>Role</Column>
          <Column key="status">Status</Column>
          <Column key="lastActive" allowsSorting>Last Active</Column>
        </TableHeader>
        <TableBody items={users}>
          {(user) => (
            <Row key={user.id}>
              <Cell>
                <Avatar src={user.avatar} alt={user.name} size="avatar-size-50" />
              </Cell>
              <Cell>
                <LabeledValue
                  label="Name"
                  value={user.name}
                  orientation="vertical"
                />
              </Cell>
              <Cell>{user.email}</Cell>
              <Cell>
                <Badge variant="neutral">{user.role}</Badge>
              </Cell>
              <Cell>
                <StatusLight 
                  variant={user.status === 'active' ? 'positive' : 'notice'}
                >
                  {user.status}
                </StatusLight>
              </Cell>
              <Cell>{formatDistance(user.lastActive, new Date())}</Cell>
            </Row>
          )}
        </TableBody>
      </TableView>
    </div>
  );
}

/** Sort configuration */
interface SortDescriptor {
  /** Column key to sort by */
  column: Key;
  /** Sort direction */
  direction: "ascending" | "descending";
}

/** Column sizing information */
interface ColumnSize {
  /** Column width value */
  width: number;
  /** Minimum width */
  minWidth?: number;
  /** Maximum width */
  maxWidth?: number;
}

/** Loading states for async data */
type LoadingState = "loading" | "sorting" | "loadingMore" | "error" | "idle" | "filtering";

/** Selection modes */
type SelectionMode = "none" | "single" | "multiple";

/** Selection state */
type Selection = "all" | Set<Key>;

/** Collection item key */
type Key = string | number;