import type { MarkedExtension } from 'marked';

/**
 * Adds support for extended tables in marked.
 * This extension enhances markdown tables with advanced features:
 * - Row spanning with the `^` character
 * - Column spanning using multiple pipe characters `|`
 * - Multi-row headers
 * - Table captions using [Caption] syntax
 * - Column alignment using `:---:` syntax
 *
 * @example
 * ```javascript
 * import { marked } from "marked";
 * import markedExtendedTables from "@fsegurai/marked-extended-tables";
 *
 * marked.use(markedExtendedTables({
 *   useTheadTbody: true,
 *   useTfoot: true,
 *   captionTop: false
 * }));
 * ```
 *
 * @param options Configuration options for the table extension
 * @returns A marked extension object that can be passed to marked.use()
 */
export default function markedExtendedTables(options?: SpanTableOptions): MarkedExtension;

/**
 * Configuration options for the extended tables extension
 */
export interface SpanTableOptions {
  /**
   * Whether to render the table with thead and tbody tags
   * @default true
   */
  useTheadTbody?: boolean;

  /**
   * Whether to use tfoot for the last row
   * @default false
   */
  useTfoot?: boolean;

  /**
   * Custom class to add to the table element
   */
  className?: string;

  /**
   * Whether to place caption at the top of the table
   * @default true
   */
  captionTop?: boolean;

  /**
   * Whether to detect and mark the last row as a footer
   * @default false
   */
  detectFooter?: boolean;

  /**
   * Whether to enforce strict caption syntax
   * @default false
   */
  strictCaptions?: boolean;

  /**
   * Maximum number of columns a cell can span (null for no limit)
   * @default null
   */
  maxColspan?: number | null;

  /**
   * Enable enhanced handling of complex row+column spanning
   * @default true
   */
  handleComplexSpans?: boolean;
}

/**
 * Token representing a table with spans
 */
export interface SpanTableToken {
  /**
   * Type identifier for the token
   */
  type: 'spanTable';

  /**
   * Header rows of the table
   */
  header: TableRow[];

  /**
   * Alignment for each column ('left', 'center', 'right', or null)
   */
  align: (string | null)[];

  /**
   * Data rows of the table
   */
  rows: TableRow[];

  /**
   * Footer row if detectFooter is enabled
   */
  footerRow?: TableRow;

  /**
   * Whether the table has a footer row
   */
  hasFooter?: boolean;

  /**
   * Caption text if available
   */
  caption?: string;

  /**
   * Parsed tokens for the caption
   */
  captionTokens?: unknown[];

  /**
   * Original markdown source of the table
   */
  raw: string;
}

/**
 * A row in the table, consisting of multiple cells
 */
export type TableRow = TableCell[];

/**
 * A cell in the table
 */
export interface TableCell {
  /**
   * Number of rows this cell spans vertically
   */
  rowspan: number;

  /**
   * Number of columns this cell spans horizontally
   */
  colspan: number;

  /**
   * The text content of the cell
   */
  text: string;

  /**
   * Parsed inline tokens from the cell text
   */
  tokens?: unknown[];

  /**
   * Reference to the original cell when using rowspan
   */
  rowSpanTarget?: TableCell;
}