#==========================================================
# Data Overview
#==========================================================

#' Data Overview
#'
#' Provides a concise overview of the size, structure,
#' completeness, and variable types of a dataset.
#'
#' @param data A data.frame.
#'
#' @return An object of class \code{DataOverview} containing
#'   dataset-level summary information.
#'
#' @details
#' The function reports the number of rows and variables,
#' total number of cells, missing and complete cells,
#' completeness percentage, complete cases, duplicate rows,
#' and counts of common variable types.
#'
#' @examples
#' data_overview(iris)
#'
#' dat <- iris
#' dat$Sepal.Length[1:5] <- NA
#' data_overview(dat)
#'
#' @export

data_overview <- function(data) {

  #---------------------------------------------
  # Validation
  #---------------------------------------------
  validate_data(data)

  #---------------------------------------------
  # Dimensions
  #---------------------------------------------
  n_rows <- nrow(data)
  n_variables <- ncol(data)

  total_cells <- n_rows * n_variables

  #---------------------------------------------
  # Missing values
  #---------------------------------------------
  missing_cells <- sum(is.na(data))

  complete_cells <- total_cells - missing_cells

  completeness <- if (total_cells == 0L) {
    NA_real_
  } else {
    100 * complete_cells / total_cells
  }

  #---------------------------------------------
  # Complete cases
  #---------------------------------------------
  complete_cases <- sum(
    stats::complete.cases(data)
  )

  #---------------------------------------------
  # Duplicate rows
  #---------------------------------------------
  duplicate_rows <- sum(
    duplicated(data)
  )

  #---------------------------------------------
  # Variable types
  #---------------------------------------------
  numeric_variables <- sum(
    vapply(
      data,
      is.numeric,
      logical(1)
    )
  )

  factor_variables <- sum(
    vapply(
      data,
      is.factor,
      logical(1)
    )
  )

  character_variables <- sum(
    vapply(
      data,
      is.character,
      logical(1)
    )
  )

  logical_variables <- sum(
    vapply(
      data,
      is.logical,
      logical(1)
    )
  )

  date_variables <- sum(
    vapply(
      data,
      inherits,
      logical(1),
      what = "Date"
    )
  )

  datetime_variables <- sum(
    vapply(
      data,
      inherits,
      logical(1),
      what = "POSIXct"
    )
  )

  #---------------------------------------------
  # Result
  #---------------------------------------------
  result <- list(

    Rows = n_rows,

    Variables = n_variables,

    TotalCells = total_cells,

    MissingCells = missing_cells,

    CompleteCells = complete_cells,

    Completeness = round(
      completeness,
      2
    ),

    CompleteCases = complete_cases,

    DuplicateRows = duplicate_rows,

    NumericVariables = numeric_variables,

    FactorVariables = factor_variables,

    CharacterVariables = character_variables,

    LogicalVariables = logical_variables,

    DateVariables = date_variables,

    DateTimeVariables = datetime_variables

  )

  class(result) <- "DataOverview"

  result
}
