import type { PathProvidedItem, PathMatrix } from "./+types.path-table.js";
/**
 * Computes a matrix representation of hierarchical path data.
 *
 * This function transforms a tree-like structure (represented by paths) into a 2D matrix where:
 * - Each column represents a path from the input array
 * - Each row represents a depth level in the hierarchy
 * - Each cell contains metadata about the node at that position or null
 *
 * The resulting matrix is particularly useful for:
 * - Column-grouped matrices with hierarchical headers
 * - Tree-grid layouts with proper spanning cells
 * - Visualizations that require flattening hierarchical data into a grid
 *
 * Each node in the output matrix includes:
 * - Unique ID and occurrence count
 * - Position in the matrix (start/end columns)
 * - Complete path to reach this node
 * - Related nodes that should be joined/grouped together
 *
 * @example
 * ```ts
 * const table = computePathMatrix([
 *   { id: "x", groupPath: ["A", "B"] },
 *   { id: "y" },
 *   { id: "z", groupPath: ["A", "B", "C"] },
 *   { id: "d", groupPath: ["Y", "X", "C"] },
 *   { id: "v", groupPath: ["F"] },
 * ]);
 * ```
 *
 * Results in:
 * ```
 * ┌─────────┬───────────┬─────────────┐
 * │ A|0 / 1 │ A#B|0 / 1 │ -           │
 * ├─────────┼───────────┼─────────────┤
 * │ -       │ -         │ -           │
 * ├─────────┼───────────┼─────────────┤
 * │ A|2 / 3 │ A#B|2 / 3 │ A#B#C|2 / 3 │
 * ├─────────┼───────────┼─────────────┤
 * │ Y|3 / 4 │ Y#X|3 / 4 │ Y#X#C|3 / 4 │
 * ├─────────┼───────────┼─────────────┤
 * │ F|4 / 5 │ -         │ -           │
 * └─────────┴───────────┴─────────────┘
 * ```
 *
 * @param paths - Array of items with groupPath properties defining their hierarchical structure
 * @param maxDepth - Optional override for the matrix height (must be >= actual max depth)
 * @param mutMatrixSeenMap - Optional map to track occurrences of path IDs (making them globally unique)
 * @returns A column-based matrix where each element is either null or a PathMatrixItem
 */
export declare function computePathMatrix<T extends PathProvidedItem>(paths: T[], maxDepth?: number, mutMatrixSeenMap?: Record<string, number>, pathDelimiter?: string): PathMatrix;