Documentation Components

/**
 * Documentation section root wrapper
 * @returns Documentation root structure
 */
function DocsRoot(): ReactNode;

/**
 * Document root layout for individual documents
 * @param props - Document root props
 * @returns Document root structure
 */
function DocRoot(props: DocRootProps): ReactNode;

interface DocRootProps {
  readonly children: ReactNode;
}

/**
 * Document root layout wrapper
 * @param props - Layout props
 * @returns Document layout structure with sidebar and main content
 */
function DocRootLayout(props: DocRootLayoutProps): ReactNode;

interface DocRootLayoutProps {
  readonly children: ReactNode;
}

/**
 * Main content area for document pages
 * @param props - Main content props
 * @returns Main content wrapper
 */
function DocRootLayoutMain(props: DocRootLayoutMainProps): ReactNode;

interface DocRootLayoutMainProps {
  readonly hiddenSidebarContainer: boolean;
  readonly children: ReactNode;
}

/**
 * Sidebar container for document navigation
 * @param props - Sidebar props
 * @returns Sidebar layout component
 */
function DocRootLayoutSidebar(props: DocRootLayoutSidebarProps): ReactNode;

interface DocRootLayoutSidebarProps {
  readonly sidebar: PropSidebar;
  readonly hiddenSidebarContainer: boolean;
  readonly setHiddenSidebarContainer: Dispatch<SetStateAction<boolean>>;
}

/**
 * Sidebar expand/collapse button
 * @param props - Expand button props
 * @returns Sidebar expand button
 */
function DocRootLayoutSidebarExpandButton(props: SidebarExpandButtonProps): ReactNode;

interface SidebarExpandButtonProps {
  toggleSidebar: () => void;
}

/**
 * Individual document item wrapper
 * @param props - Document item props
 * @returns Document page structure
 */
function DocItem(props: DocItemProps): ReactNode;

interface DocItemProps {
  readonly children: ReactNode;
}

/**
 * Document item layout wrapper
 * @param props - Document layout props
 * @returns Document page layout
 */
function DocItemLayout(props: DocItemLayoutProps): ReactNode;

interface DocItemLayoutProps {
  readonly children: ReactNode;
}

/**
 * Document content wrapper
 * @param props - Content wrapper props
 * @returns Document content container
 */
function DocItemContent(props: DocItemContentProps): ReactNode;

interface DocItemContentProps {
  readonly children: ReactNode;
}

/**
 * Document metadata component for SEO and page info
 * @returns Document metadata elements
 */
function DocItemMetadata(): ReactNode;

/**
 * Document footer with edit links and metadata
 * @returns Document footer element
 */
function DocItemFooter(): ReactNode;

/**
 * Document navigation paginator
 * @returns Previous/next document navigation
 */
function DocItemPaginator(): ReactNode;

/**
 * Desktop table of contents for documents
 * @returns Desktop TOC sidebar
 */
function DocItemTOCDesktop(): ReactNode;

/**
 * Mobile table of contents for documents
 * @returns Mobile TOC dropdown
 */
function DocItemTOCMobile(): ReactNode;

/**
 * Desktop table of contents component
 * @param props - TOC props
 * @returns TOC navigation tree
 */
function TOC(props: TOCProps): ReactNode;

interface TOCProps {
  readonly toc: readonly TOCItem[];
  readonly minHeadingLevel?: number;
  readonly maxHeadingLevel?: number;
  readonly className?: string;
}

/**
 * Inline table of contents component
 * @param props - Inline TOC props
 * @returns Inline TOC list
 */
function TOCInline(props: TOCInlineProps): ReactNode;

interface TOCInlineProps {
  readonly toc: readonly TOCItem[];
  readonly minHeadingLevel?: number;
  readonly maxHeadingLevel?: number;
}

/**
 * Collapsible table of contents component
 * @param props - Collapsible TOC props
 * @returns Collapsible TOC with toggle
 */
function TOCCollapsible(props: TOCCollapsibleProps): ReactNode;

interface TOCCollapsibleProps {
  readonly className?: string;
  readonly minHeadingLevel?: number;
  readonly maxHeadingLevel?: number;
  readonly toc: readonly TOCItem[];
}

/**
 * TOC items list component
 * @param props - TOC items props
 * @returns TOC items list
 */
function TOCItems(props: TOCItemsProps): ReactNode;

interface TOCItemsProps {
  readonly toc: readonly TOCItem[];
  readonly minHeadingLevel?: number;
  readonly maxHeadingLevel?: number;
  readonly className?: string;
  readonly linkClassName?: string | null;
  readonly linkActiveClassName?: string;
}

/**
 * TOC tree structure component
 * @param props - TOC tree props
 * @returns Hierarchical TOC tree
 */
function TOCItemsTree(props: TOCItemsTreeProps): ReactNode;

interface TOCItemsTreeProps {
  readonly toc: readonly TOCTreeNode[];
  readonly className: string;
  readonly linkClassName: string | null;
  readonly isChild?: boolean;
}

/**
 * TOC collapse button
 * @param props - Collapse button props
 * @returns TOC expand/collapse button
 */
function TOCCollapsibleCollapseButton(props: TOCCollapseButtonProps): ReactNode;

interface TOCCollapseButtonProps extends ComponentProps<'button'> {
  collapsed: boolean;
}

/**
 * Documentation sidebar component
 * @param props - Sidebar props
 * @returns Documentation navigation sidebar
 */
function DocSidebar(props: DocSidebarProps): ReactNode;

interface DocSidebarProps {
  readonly path: string;
  readonly sidebar: readonly PropSidebarItem[];
  readonly onCollapse: () => void;
  readonly isHidden: boolean;
}

/**
 * Desktop documentation sidebar
 * @param props - Desktop sidebar props
 * @returns Desktop sidebar component
 */
function DocSidebarDesktop(props: DocSidebarProps): ReactNode;

/**
 * Mobile documentation sidebar
 * @param props - Mobile sidebar props
 * @returns Mobile sidebar component
 */
function DocSidebarMobile(props: DocSidebarProps): ReactNode;

/**
 * Desktop sidebar content
 * @param props - Sidebar content props
 * @returns Sidebar content with navigation items
 */
function DocSidebarDesktopContent(props: DocSidebarContentProps): ReactNode;

interface DocSidebarContentProps {
  readonly className?: string;
  readonly path: string;
  readonly sidebar: readonly PropSidebarItem[];
}

/**
 * Sidebar collapse button
 * @param props - Collapse button props
 * @returns Sidebar collapse/expand button
 */
function DocSidebarDesktopCollapseButton(props: DocSidebarCollapseButtonProps): ReactNode;

interface DocSidebarCollapseButtonProps {
  readonly onClick: React.MouseEventHandler;
}

/**
 * Generic sidebar item component
 * @param props - Sidebar item props
 * @returns Sidebar item element
 */
function DocSidebarItem(props: DocSidebarItemProps): ReactNode;

interface DocSidebarItemProps {
  readonly activePath: string;
  readonly onItemClick?: (item: PropSidebarItem) => void;
  readonly level: number;
  readonly tabIndex?: number;
  readonly item: PropSidebarItem;
  readonly index: number;
}

/**
 * Collection of sidebar items
 * @param props - Sidebar items collection props
 * @returns List of sidebar items
 */
function DocSidebarItems(props: DocSidebarItemsProps): ReactNode;

interface DocSidebarItemsProps extends Omit<DocSidebarItemProps, 'item' | 'index'> {
  readonly items: readonly PropSidebarItem[];
}

/**
 * Sidebar link item
 * @param props - Link item props
 * @returns Sidebar link element
 */
function DocSidebarItemLink(props: DocSidebarItemLinkProps): ReactNode;

interface DocSidebarItemLinkProps extends DocSidebarItemProps {
  readonly item: PropSidebarItemLink;
}

/**
 * Sidebar category item with collapsible children
 * @param props - Category item props
 * @returns Sidebar category with children
 */
function DocSidebarItemCategory(props: DocSidebarItemCategoryProps): ReactNode;

interface DocSidebarItemCategoryProps extends DocSidebarItemProps {
  readonly item: PropSidebarItemCategory;
}

/**
 * Sidebar HTML item for custom content
 * @param props - HTML item props
 * @returns Custom HTML sidebar item
 */
function DocSidebarItemHtml(props: DocSidebarItemHtmlProps): ReactNode;

interface DocSidebarItemHtmlProps extends DocSidebarItemProps {
  readonly item: PropSidebarItemHtml;
}

/**
 * Document card component
 * @param props - Document card props
 * @returns Document card element
 */
function DocCard(props: DocCardProps): ReactNode;

interface DocCardProps {
  readonly item: PropSidebarItem;
}

/**
 * Collection of document cards
 * @param props - Card list props
 * @returns Grid of document cards
 */
function DocCardList(props: DocCardListProps): ReactNode;

interface DocCardListProps {
  readonly items?: PropSidebarItem[];
  readonly className?: string;
}

/**
 * Document paginator for prev/next navigation
 * @param props - Paginator props
 * @returns Document pagination component
 */
function DocPaginator(props: DocPaginatorProps): ReactNode;

interface DocPaginatorProps {
  readonly nextItem?: NavigationItem;
  readonly prevItem?: NavigationItem;
  readonly className?: string;
}

/**
 * Paginator navigation link
 * @param props - Navigation link props
 * @returns Styled navigation link
 */
function PaginatorNavLink(props: PaginatorNavLinkProps): ReactNode;

interface PaginatorNavLinkProps {
  readonly title: ReactNode;
  readonly subLabel?: ReactNode;
  readonly isNext?: boolean;
  readonly permalink: string;
}

interface NavigationItem {
  readonly title: string;
  readonly permalink: string;
}

/**
 * Document breadcrumbs navigation
 * @returns Breadcrumb navigation trail
 */
function DocBreadcrumbs(): ReactNode;

/**
 * Home breadcrumb item
 * @returns Home link breadcrumb
 */
function DocBreadcrumbsHomeBreadcrumbItem(): ReactNode;

/**
 * Breadcrumbs structured data for SEO
 * @param props - Structured data props
 * @returns JSON-LD structured data
 */
function DocBreadcrumbsStructuredData(props: BreadcrumbsStructuredDataProps): ReactNode;

interface BreadcrumbsStructuredDataProps {
  readonly breadcrumbs: PropSidebarBreadcrumbsItem[];
}

/**
 * Documentation version banner
 * @param props - Version banner props
 * @returns Version notification banner
 */
function DocVersionBanner(props: DocVersionBannerProps): ReactNode;

interface DocVersionBannerProps {
  readonly className?: string;
}

/**
 * Documentation version badge
 * @param props - Version badge props
 * @returns Version indicator badge
 */
function DocVersionBadge(props: DocVersionBadgeProps): ReactNode;

interface DocVersionBadgeProps {
  readonly className?: string;
}

/**
 * Documentation version suggestions
 * @returns Version upgrade suggestions
 */
function DocVersionSuggestions(): ReactNode;

/**
 * Documentation version root wrapper
 * @returns Version-specific wrapper
 */
function DocVersionRoot(): ReactNode;

/**
 * Auto-generated category index page
 * @returns Category overview page
 */
function DocCategoryGeneratedIndexPage(): ReactNode;

/**
 * Tag-filtered document list page
 * @returns Documents filtered by tag
 */
function DocTagDocListPage(): ReactNode;

/**
 * Documentation tags list page
 * @returns All available documentation tags
 */
function DocTagsListPage(): ReactNode;

// Table of contents item
interface TOCItem {
  readonly value: string;
  readonly id: string;
  readonly children: readonly TOCItem[];
  readonly level: number;
}

// Sidebar item types
type PropSidebarItem = PropSidebarItemLink | PropSidebarItemCategory | PropSidebarItemHtml;

interface PropSidebarItemLink {
  type: 'link';
  label: string;
  href: string;
  docId?: string;
  unlisted?: boolean;
}

interface PropSidebarItemCategory {
  type: 'category';
  label: string;
  items: PropSidebarItem[];
  collapsed?: boolean;
  collapsible?: boolean;
}

interface PropSidebarItemHtml {
  type: 'html';
  value: string;
  defaultStyle?: boolean;
  className?: string;
}

// Sidebar structure
type PropSidebar = readonly PropSidebarItem[];

// Breadcrumb item
interface PropSidebarBreadcrumbsItem {
  label: string;
  href?: string;
}

// TOC tree node
interface TOCTreeNode extends TOCItem {
  readonly parentIndex: number;
}