/**
 * KBX Foundation v4 Core Types
 * Single source of truth for screen definitions, permissions, and UI contracts
 */

// Screen Definition (Registry Entry)
export interface KbxScreenDefinition {
  screenId: string              // e.g., "model-ops.shadow-run.list"
  title: string                 // e.g., "Shadow Run Validation"
  module: 'Home' | 'ModelOps' | 'SignalEngine' | 'Admin' | 'Research' | 'Operations' | 'Portfolio' | 'Design System' | 'Internal' | 'Other'
  type: 'list' | 'detail' | 'form' | 'dashboard'
  path: string                  // Vue Router path
  component: () => Promise<any> // Lazy-loaded component
  permissions: string[]         // Required permissions (e.g., ['model.read'])
  description?: string          // Screen description
  help?: KbxHelpDefinition
  grid?: KbxGridDefinition
  shortcuts?: KbxShortcut[]
  telemetry?: { enabled: boolean }
}

// Grid Column Definition
export interface KbxGridColumn<T = any> {
  field: string | number | symbol
  header: string
  type?: 'text' | 'number' | 'date' | 'datetime' | 'percentage' | 'status' | 'link' | 'money' | 'quantity'
  width?: number | string
  pinned?: 'left' | 'right'
  sortable?: boolean
  filterable?: boolean
  formatter?: (value: any, row: T) => string
}

// Grid Configuration
export interface KbxGridDefinition {
  columnDefs: KbxGridColumn[]
  rowHeight?: number | 'auto'
  pageSize?: number
  serverSideDatasource?: boolean
  theme?: string
}

// Search Field Definition
export interface KbxSearchField {
  key: string
  label: string
  type: 'text' | 'number' | 'date' | 'date-range' | 'select' | 'multi-select'
  options?: Array<{ value: string | number; label: string }>
  range?: { from: string; to: string } // for date-range
  placeholder?: string
  width?: 'sm' | 'md' | 'lg'
}

// Help Definition
export interface KbxHelpDefinition {
  title: string
  sections: KbxHelpSection[]
  relatedScreens?: string[]
  externalUrl?: string
}

export interface KbxHelpSection {
  title: string
  content: string
  icon?: string
}

// Permission Definition
export interface KbxPermissionDefinition {
  permissionId: string  // e.g., 'model.create'
  label: string
  description?: string
  screens: string[]     // Which screens require this
}

// Command Definition (Actions)
export interface KbxCommand {
  id: string
  label: string
  group?: string        // 'query' | 'edit' | 'workflow' | 'output'
  permission?: string
  requiresSelection?: boolean
  minSelection?: number
  variant?: 'default' | 'primary' | 'danger'
  shortcut?: string
  icon?: string
}

// Keyboard Shortcut
export interface KbxShortcut {
  key: string           // 'F3', 'Ctrl+S', etc.
  label: string
  action: string
}

// Data State (Loading, Error, Empty)
export type KbxAsyncState = 'idle' | 'pending' | 'ready' | 'error' | 'empty'

// Grid Summary Item
export interface KbxSummaryItem {
  label: string
  value: string | number
  format?: 'number' | 'money' | 'quantity' | 'percentage'
}

// Quick Filter
export interface KbxQuickFilterItem {
  id: string
  label: string
  badge?: string | number
  active?: boolean
}

// Screen Context (Breadcrumb, Parent Info)
export interface KbxScreenContext {
  parentScreenId?: string
  breadcrumb?: string
  contextData?: Record<string, any>
}

// Problem/Error Display
export interface KbxProblem {
  code: string
  message: string
  details?: string
  recoveryActions?: string[]
  retryable?: boolean
}

// Theme Configuration
export interface KbxThemeConfig {
  primary: string
  secondary: string
  danger: string
  success: string
  warning: string
  info: string
}

// Density Token (UI Sizing)
export type KbxDensity = 'compact' | 'comfortable' | 'touch'
export interface KbxDensityTokens {
  inputHeight: number
  gridRowHeight: number
  touchTarget: number
  fontSize: number
  controlHeight: number
}
