/**
 * @fileoverview Table formatter utility for creating tables in multiple formats.
 * Supports markdown, ASCII, grid (Unicode), and compact table styles with configurable
 * alignment, truncation, and formatting options.
 * @module src/utils/formatting/tableFormatter
 */
import { type RequestContext } from '../../utils/internal/requestContext.js';
/**
 * Table output style options.
 *
 * - `markdown`: GitHub-flavored markdown table with pipe delimiters and alignment indicators.
 * - `ascii`: Box-drawing table using `+`, `-`, and `|` characters; portable across terminals.
 * - `grid`: Unicode box-drawing table using `┌─┬─┐` characters; visually cleaner but requires Unicode support.
 * - `compact`: Borderless table with columns separated by spaces; minimal visual noise.
 *
 * @example
 * ```typescript
 * const style: TableStyle = 'grid';
 * ```
 */
export type TableStyle = 'markdown' | 'ascii' | 'grid' | 'compact';
/**
 * Column alignment options.
 *
 * Controls how cell content is padded within its column width.
 * - `left`: Content flush-left, trailing spaces fill the column.
 * - `center`: Content centred, padding split evenly (odd remainder goes right).
 * - `right`: Content flush-right, leading spaces fill the column.
 *
 * @example
 * ```typescript
 * const alignment: Alignment = 'right';
 * ```
 */
export type Alignment = 'left' | 'center' | 'right';
/**
 * Configuration options for table formatting.
 */
export interface TableFormatterOptions {
    /**
     * Column-specific alignment configuration.
     * Key is column name (for object arrays) or index (for raw arrays).
     * @example { name: 'left', age: 'right', email: 'center' }
     */
    alignment?: Record<string, Alignment>;
    /**
     * Header styling option.
     * - bold: Headers in bold (markdown only)
     * - uppercase: Convert headers to uppercase
     * - none: No special header formatting
     */
    headerStyle?: 'bold' | 'uppercase' | 'none';
    /**
     * Maximum width for any column. Content exceeding this will be truncated.
     */
    maxWidth?: number;
    /**
     * Minimum column width (default: 3).
     */
    minWidth?: number;
    /**
     * Padding around cell content (default: 1 space).
     */
    padding?: number;
    /**
     * Table style to use for rendering.
     * - markdown: GitHub-style markdown tables (| Header | Header |)
     * - ascii: ASCII box drawing with +, -, | characters
     * - grid: Unicode box-drawing characters (┌─┬─┐)
     * - compact: Space-separated columns (no borders)
     */
    style?: TableStyle;
    /**
     * Whether to truncate long content with ellipsis (default: true).
     * If false, content may wrap or overflow depending on style.
     */
    truncate?: boolean;
}
/**
 * Utility class for formatting tabular data into various table styles.
 *
 * Provides two rendering methods:
 * - {@link format} — accepts an array of objects and extracts headers automatically.
 * - {@link formatRaw} — accepts explicit headers and a 2D string array for full control.
 *
 * Column widths are computed from the widest value in each column, clamped by
 * `minWidth` and `maxWidth`. Content that exceeds `maxWidth` is truncated with
 * an ellipsis (`...`) when `truncate` is `true` (the default).
 *
 * @example
 * ```typescript
 * const data = [
 *   { name: 'Alice', score: 42 },
 *   { name: 'Bob',   score: 7  },
 * ];
 *
 * // Markdown (default style)
 * tableFormatter.format(data);
 * // | name  | score |
 * // | ----- | ----- |
 * // | Alice | 42    |
 * // | Bob   | 7     |
 *
 * // Unicode grid with right-aligned score column
 * tableFormatter.format(data, { style: 'grid', alignment: { score: 'right' } });
 * ```
 */
export declare class TableFormatter {
    /**
     * Default formatting options.
     * @private
     */
    private readonly defaultOptions;
    /**
     * Format an array of objects as a table.
     *
     * Headers are derived from the keys of the first object. Every value is
     * converted to a string via an internal `stringify` helper that handles
     * primitives, arrays (JSON), objects (JSON), and special values (`null`,
     * `undefined`, functions, symbols).
     *
     * @template T - Type of objects in the array; must extend `Record<string, unknown>`.
     * @param data - Array of objects to render. Returns `''` immediately if empty.
     * @param options - Table formatting options. All fields are optional; defaults apply.
     * @param context - Optional request context used for correlated debug logging.
     *   A new context is created automatically when omitted.
     * @returns Formatted table string in the requested style, or `''` if `data` is empty.
     * @throws {McpError} With `ValidationError` code if `data` is not an array.
     * @throws {McpError} With `InternalError` code if rendering fails unexpectedly.
     *
     * @example
     * ```typescript
     * const data = [
     *   { name: 'Alice', age: 30, role: 'Engineer' },
     *   { name: 'Bob',   age: 25, role: 'Designer' },
     * ];
     *
     * // Default markdown output
     * tableFormatter.format(data);
     *
     * // Unicode grid with right-aligned age column
     * tableFormatter.format(data, { style: 'grid', alignment: { age: 'right' } });
     * ```
     */
    format<T extends Record<string, unknown>>(data: T[], options?: TableFormatterOptions, context?: RequestContext): string;
    /**
     * Format a raw 2D string array with explicit headers.
     *
     * Unlike {@link format}, no automatic key extraction or value stringification
     * occurs — callers supply pre-serialized strings. All rows must have exactly
     * the same number of columns as `headers`; a mismatch throws immediately.
     *
     * @param headers - Non-empty array of column header strings.
     * @param rows - 2D array of string cell values. Every inner array must have
     *   the same length as `headers`. Returns `''` immediately if `rows` is empty.
     * @param options - Table formatting options. All fields are optional; defaults apply.
     * @param context - Optional request context used for correlated debug logging.
     *   A new context is created automatically when omitted.
     * @returns Formatted table string in the requested style, or `''` if `rows` is empty.
     * @throws {McpError} With `ValidationError` code if `headers` is empty or not an array,
     *   `rows` is not an array, or any row's column count differs from `headers.length`.
     * @throws {McpError} With `InternalError` code if rendering fails unexpectedly.
     *
     * @example
     * ```typescript
     * const headers = ['Name', 'Age', 'Role'];
     * const rows = [
     *   ['Alice', '30', 'Engineer'],
     *   ['Bob',   '25', 'Designer'],
     * ];
     * const table = tableFormatter.formatRaw(headers, rows, { style: 'ascii' });
     * ```
     */
    formatRaw(headers: string[], rows: string[][], options?: TableFormatterOptions, context?: RequestContext): string;
    /**
     * Apply header styling transformations.
     * @private
     */
    private applyHeaderStyle;
    /**
     * Calculate column widths and metadata.
     * @private
     */
    private calculateColumns;
    /**
     * Render table using the specified style.
     * @private
     */
    private renderTable;
    /**
     * Render markdown-style table.
     * @private
     */
    private renderMarkdown;
    /**
     * Render ASCII box-drawing table.
     * @private
     */
    private renderAscii;
    /**
     * Render Unicode grid table.
     * @private
     */
    private renderGrid;
    /**
     * Render compact space-separated table.
     * @private
     */
    private renderCompact;
    /**
     * Format a single cell with alignment and truncation.
     * @private
     */
    private formatCell;
    /**
     * Convert any value to a string for display in table.
     * @private
     */
    private stringify;
}
/**
 * Singleton instance of {@link TableFormatter}.
 *
 * Prefer this over constructing `new TableFormatter()` directly. Use
 * {@link TableFormatter.format} for object arrays and
 * {@link TableFormatter.formatRaw} for pre-serialized 2D string arrays.
 *
 * @example
 * ```typescript
 * import { tableFormatter } from '../../utils/formatting/tableFormatter.js';
 *
 * const data = [
 *   { name: 'Alice', age: 30, role: 'Engineer' },
 *   { name: 'Bob',   age: 25, role: 'Designer' },
 * ];
 *
 * // Markdown table (default style)
 * console.log(tableFormatter.format(data));
 *
 * // Unicode grid with right-aligned age column
 * console.log(tableFormatter.format(data, {
 *   style: 'grid',
 *   alignment: { age: 'right' },
 * }));
 *
 * // Compact borderless table with uppercase headers
 * console.log(tableFormatter.format(data, {
 *   style: 'compact',
 *   headerStyle: 'uppercase',
 * }));
 *
 * // Raw 2D array (no automatic key extraction)
 * console.log(tableFormatter.formatRaw(
 *   ['Name', 'Age'],
 *   [['Alice', '30'], ['Bob', '25']],
 *   { style: 'ascii' },
 * ));
 * ```
 */
export declare const tableFormatter: TableFormatter;
//# sourceMappingURL=tableFormatter.d.ts.map