using Sbroenne.ExcelMcp.ComInterop.Session;
using Sbroenne.ExcelMcp.Core.Attributes;
using Sbroenne.ExcelMcp.Core.Models;

namespace Sbroenne.ExcelMcp.Core.Commands.Chart;

/// <summary>
/// Chart lifecycle - create, read, move, and delete embedded charts.
///
/// POSITIONING (choose one):
/// - targetRange (PREFERRED): Cell range like 'F2:K15' — positions chart within cells, no point math needed.
/// - left/top: Manual positioning in points (72 points = 1 inch).
/// - Neither: Auto-positions chart below all existing content (used range + other charts).
///
/// COLLISION DETECTION: All create/move/fit-to-range operations automatically check for overlaps
/// with data and other charts. Warnings are returned in the result message if collisions are detected.
/// Always verify layout with screenshot(capture-sheet) after creating charts.
///
/// CHART TYPES: 70+ types available including Column, Line, Pie, Bar, Area, XY Scatter.
///
/// CREATE OPTIONS:
/// - create-from-range: Create from cell range (e.g., 'A1:D10')
/// - create-from-table: Create from Excel Table (uses table's data range)
/// - create-from-pivottable: Create linked PivotChart
///
/// Use chartconfig for series, titles, legends, styles, placement mode.
/// </summary>
[ServiceCategory("chart", "Chart")]
[McpTool("chart", Title = "Chart Operations", Destructive = true, Category = "analysis",
    Description = "Chart lifecycle - create, read, move, and delete embedded charts. POSITIONING: targetRange='F2:K15' (PREFERRED, cell-relative) or left/top (points, 72pts=1in) or OMIT BOTH for auto-positioning below content. COLLISION DETECTION: Automatically warns if chart overlaps data or other charts. CHART TYPES: 70+ types (ColumnClustered, Line, Pie, Bar, Area, XYScatter, etc.). CREATE: create-from-range (cell range), create-from-table (Excel Table), create-from-pivottable (linked PivotChart). Use chart_config for series, titles, legends, and styling.")]
public interface IChartCommands
{
    // === LIFECYCLE OPERATIONS ===

    /// <summary>
    /// Lists all charts in workbook (Regular and PivotCharts).
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <returns>List of charts with names, types, sheets, positions, data sources</returns>
    [ServiceAction("list")]
    List<ChartInfo> List(IExcelBatch batch);

    /// <summary>
    /// Gets complete chart configuration.
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <param name="chartName">Name of the chart (or shape name)</param>
    /// <returns>Chart type, data source, series info, position, styling</returns>
    [ServiceAction("read")]
    ChartInfoResult Read(IExcelBatch batch, [RequiredParameter] string chartName);

    /// <summary>
    /// Creates a Regular Chart from an Excel range.
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <param name="sheetName">Target worksheet name</param>
    /// <param name="sourceRangeAddress">Data range for the chart (e.g., A1:D10)</param>
    /// <param name="chartType">Type of chart to create</param>
    /// <param name="left">Left position in points from worksheet edge</param>
    /// <param name="top">Top position in points from worksheet edge</param>
    /// <param name="width">Chart width in points</param>
    /// <param name="height">Chart height in points</param>
    /// <param name="chartName">Optional chart name (auto-generated if omitted)</param>
    /// <param name="targetRange">Cell range to position chart within (e.g., 'F2:K15'). PREFERRED over left/top. When set, left/top are ignored.</param>
    [ServiceAction("create-from-range")]
    ChartCreateResult CreateFromRange(
        IExcelBatch batch,
        [RequiredParameter] string sheetName,
        [RequiredParameter] string sourceRangeAddress,
        [RequiredParameter] ChartType chartType,
        double left = 0,
        double top = 0,
        double width = 400,
        double height = 300,
        string? chartName = null,
        string? targetRange = null);

    /// <summary>
    /// Creates a Regular Chart from an Excel Table's data range.
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <param name="tableName">Name of the Excel Table</param>
    /// <param name="sheetName">Target worksheet name for the chart</param>
    /// <param name="chartType">Type of chart to create</param>
    /// <param name="left">Left position in points from worksheet edge</param>
    /// <param name="top">Top position in points from worksheet edge</param>
    /// <param name="width">Chart width in points</param>
    /// <param name="height">Chart height in points</param>
    /// <param name="chartName">Optional chart name (auto-generated if omitted)</param>
    /// <param name="targetRange">Cell range to position chart within (e.g., 'F2:K15'). PREFERRED over left/top. When set, left/top are ignored.</param>
    [ServiceAction("create-from-table")]
    ChartCreateResult CreateFromTable(
        IExcelBatch batch,
        [RequiredParameter] string tableName,
        [RequiredParameter] string sheetName,
        [RequiredParameter] ChartType chartType,
        double left = 0,
        double top = 0,
        double width = 400,
        double height = 300,
        string? chartName = null,
        string? targetRange = null);

    /// <summary>
    /// Creates a PivotChart from an existing PivotTable.
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <param name="pivotTableName">Name of the source PivotTable</param>
    /// <param name="sheetName">Target worksheet name for the chart</param>
    /// <param name="chartType">Type of chart to create</param>
    /// <param name="left">Left position in points from worksheet edge</param>
    /// <param name="top">Top position in points from worksheet edge</param>
    /// <param name="width">Chart width in points</param>
    /// <param name="height">Chart height in points</param>
    /// <param name="chartName">Optional chart name (auto-generated if omitted)</param>
    /// <param name="targetRange">Cell range to position chart within (e.g., 'F2:K15'). PREFERRED over left/top. When set, left/top are ignored.</param>
    [ServiceAction("create-from-pivottable")]
    ChartCreateResult CreateFromPivotTable(
        IExcelBatch batch,
        [RequiredParameter] string pivotTableName,
        [RequiredParameter] string sheetName,
        [RequiredParameter] ChartType chartType,
        double left = 0,
        double top = 0,
        double width = 400,
        double height = 300,
        string? chartName = null,
        string? targetRange = null);

    /// <summary>
    /// Deletes a chart (Regular or PivotChart).
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <param name="chartName">Name of the chart to delete</param>
    [ServiceAction("delete")]
    OperationResult Delete(IExcelBatch batch, [RequiredParameter] string chartName);

    /// <summary>
    /// Moves/resizes a chart.
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <param name="chartName">Name of the chart to move</param>
    /// <param name="left">New left position in points (null to keep current)</param>
    /// <param name="top">New top position in points (null to keep current)</param>
    /// <param name="width">New width in points (null to keep current)</param>
    /// <param name="height">New height in points (null to keep current)</param>
    [ServiceAction("move")]
    OperationResult Move(
        IExcelBatch batch,
        [RequiredParameter] string chartName,
        double? left = null,
        double? top = null,
        double? width = null,
        double? height = null);

    /// <summary>
    /// Fits a chart to a cell range by setting position and size to match the range bounds.
    /// </summary>
    /// <param name="batch">Excel batch session</param>
    /// <param name="chartName">Name of the chart to fit</param>
    /// <param name="sheetName">Worksheet containing the range</param>
    /// <param name="rangeAddress">Range to fit the chart to (e.g., A1:D10)</param>
    [ServiceAction("fit-to-range")]
    OperationResult FitToRange(
        IExcelBatch batch,
        [RequiredParameter] string chartName,
        [RequiredParameter] string sheetName,
        [RequiredParameter] string rangeAddress);
}

