/**
 * Navigation Types
 * 
 * Types for the documentation navigation system
 */

/**
 * A navigation item representing a single page
 */
export interface NavItem {
  /** Display title */
  title: string
  /** URL path to the page */
  href: string
  /** Icon name (Phosphor icons) */
  icon?: string
  /** Whether the page is marked as deprecated */
  deprecated?: boolean
  /** Whether this is an external link */
  external?: boolean
  /** Optional badge text */
  badge?: string
}

/**
 * A group of navigation items
 */
export interface NavGroup {
  /** Group title */
  title: string
  /** Icon for the group */
  icon?: string
  /** Pages in this group (can include nested groups) */
  items: (NavItem | NavGroup)[]
  /** Whether the group is collapsible */
  collapsible?: boolean
  /** Default collapsed state */
  defaultCollapsed?: boolean
}

/**
 * A navigation tab (top-level section)
 */
export interface NavTab {
  /** Tab title */
  title: string
  /** URL segment for this tab */
  slug: string
  /** Groups within this tab */
  groups: NavGroup[]
  /** Icon for the tab */
  icon?: string
}

/**
 * Complete navigation structure
 */
export interface Navigation {
  /** Navigation tabs (if using tabbed navigation) */
  tabs?: NavTab[]
  /** Groups (if using single-page navigation) */
  groups?: NavGroup[]
  /** Global anchors (shown on all pages) */
  anchors?: NavItem[]
}

/**
 * Breadcrumb item
 */
export interface BreadcrumbItem {
  title: string
  href: string
}

/**
 * Page navigation context
 */
export interface PageNavContext {
  /** Current page's breadcrumbs */
  breadcrumbs: BreadcrumbItem[]
  /** Previous page in navigation */
  prev?: NavItem
  /** Next page in navigation */
  next?: NavItem
  /** Current tab (if using tabs) */
  currentTab?: NavTab
  /** Current group */
  currentGroup?: NavGroup
  /** Current item */
  currentItem?: NavItem
}

/**
 * Table of contents item (from page headings)
 */
export interface TocItem {
  id: string
  title: string
  level: number
  children?: TocItem[]
}

/**
 * Page metadata for navigation
 */
export interface PageMeta {
  /** File path relative to content directory */
  filePath: string
  /** URL path */
  urlPath: string
  /** Page title from frontmatter */
  title: string
  /** Page description */
  description?: string
  /** Sidebar title (shorter) */
  sidebarTitle?: string
  /** Icon name */
  icon?: string
  /** Whether the page is hidden from navigation */
  hidden?: boolean
  /** Page order within group */
  order?: number
}
