polars-view 0.53.5

use egui::{Id, TextStyle, Ui};
use egui_extras::{Column, TableBuilder, TableRow};
use polars::prelude::Column as PColumn;
use polars::prelude::*;
use std::sync::Arc;

use crate::polars::transforms::{
    AddRowIndexTransform, DataFrameTransform, DropColumnsTransform, NormalizeTransform,
    RemoveNullColumnsTransform, ReplaceNullsTransform, SqlTransform,
};
use crate::{
    DataFilter, DataFormat, FileExtension, HeaderSortState, PolarsViewError, PolarsViewResult,
    SortBy, SortableHeaderRenderer, get_decimal_and_layout,
};

/// Internal struct holding calculated configuration for `TableBuilder`.
/// Generated by `prepare_table_build_config`.
struct TableBuildConfig {
    text_height: f32,
    num_columns: usize,
    header_height: f32,
    column_sizing_strategy: Column, // Use 'static as Column doesn't take a lifetime here
    table_id: Id,
}

/// Container for the Polars DataFrame and its associated display and filter state.
///
/// ## State Management:
/// - Holds the core data (`df`, `df_original`) and related settings.
/// - **`df`**: The currently displayed DataFrame, potentially sorted based on `self.sort`.
/// - **`df_original`**: The DataFrame state immediately after loading/querying, before UI sorts.
/// - **`filter`**: Configuration used for *loading* the data (path, delimiter, SQL query, etc.). **Does NOT contain sorting information.**
/// - **`format`**: Configuration for *displaying* the data (alignment, decimals, etc.).
/// - **`sort`**: `Vec<SortBy>` defining the active sort order applied to `df`. An empty Vec means `df` reflects `df_original`.
/// - All key components are wrapped in `Arc` for efficient cloning and sharing between UI and async tasks.
/// - Updates (load, format, sort) typically create *new* `DataContainer` instances via async methods.
///
/// ## Interaction with `layout.rs`:
/// - `PolarsViewApp` holds the current state as `Option<Arc<DataContainer>>`.
/// - UI actions trigger async methods here (`load_data`, `update_format`, `apply_sort`).
/// - Async methods return `PolarsViewResult<DataContainer>` via a channel.
/// - `layout.rs` updates the app state with the received new container.
#[derive(Debug, Clone)]
pub struct DataContainer {
    /// The currently displayed Polars DataFrame. May be sorted according to `self.sort`.
    pub df: Arc<DataFrame>,

    /// A reference to the DataFrame state *before* any UI-driven sort was applied.
    /// Allows resetting the view efficiently.
    pub df_original: Arc<DataFrame>,

    /// Detected file extension of the originally loaded data.
    pub extension: Arc<FileExtension>,

    /// Filters and loading configurations (path, query, delimiter) that resulted
    /// in the initial `df_original`. **This does NOT store the current sort state.**
    pub filter: Arc<DataFilter>,

    /// Applied data formatting settings (decimal places, alignment, column sizing, header style).
    pub format: Arc<DataFormat>,

    /// **The active sort criteria (column name and direction) applied to `df`.**
    /// An empty vector signifies that `df` should be the same as `df_original`.
    /// Order in the vector determines sort precedence.
    pub sort: Vec<SortBy>,
}

// Default implementation initializes with an empty sort vector.
impl Default for DataContainer {
    /// Creates an empty `DataContainer` with default settings.
    fn default() -> Self {
        let default_df = Arc::new(DataFrame::default());
        DataContainer {
            df: default_df.clone(),
            df_original: default_df,
            extension: Arc::new(FileExtension::Missing),
            filter: Arc::new(DataFilter::default()), // Filters has no sort field
            format: Arc::new(DataFormat::default()),
            sort: Vec::new(), // Initialize sort as empty Vec
        }
    }
}

impl DataContainer {
    /// Asynchronously prepares the initial DataFrame for processing.
    /// Reads from file if `filter.read_data_from_file` is true (validating path and updating self.extension, self.df_original),
    /// or clones data from `self.df_original` if false.
    ///
    /// ### Arguments:
    /// * `filter`: The DataFilter, modified (e.g. `read_data_from_file` reset).
    ///
    /// ### Returns:
    /// * A DataFrame value representing the initial data to begin the transformation pipeline.
    async fn prepare_initial_dataframe(
        &mut self,               // Mutate self for initial load (extension, df_original)
        filter: &mut DataFilter, // Mutate filter (read_data_from_file)
    ) -> PolarsViewResult<DataFrame> {
        if filter.read_data_from_file {
            // --- Path Validation ---
            if !filter.absolute_path.exists() {
                tracing::error!("load_data: File not found: {:?}", filter.absolute_path);
                return Err(PolarsViewError::FileNotFound(filter.absolute_path.clone()));
            }

            // --- Data Reading ---
            let (new_df, extension) = filter.get_df_and_extension().await?; // Reads, may update filter.csv_delimiter
            tracing::debug!(
                "prepare_initial_dataframe: read data from file. Dims: {}x{}, Ext: {:?}, Delimiter: '{}'",
                new_df.height(),
                new_df.width(),
                extension,
                filter.csv_delimiter
            );

            // Update self with the new data's initial state and extension
            self.extension = Arc::new(extension);
            self.df_original = Arc::new(new_df.clone()); // Store original DataFrame (deep copy data here)

            filter.read_data_from_file = false; // Reset flag in filter

            Ok(new_df) // Return the DataFrame value from the file
        } else {
            tracing::debug!(
                "prepare_initial_dataframe: starting from df_original (filter change)."
            );
            // Clone the DataFrame value from the Arc held by self.df_original
            // This is a deep copy, but necessary to get a modifiable value for the pipeline.
            Ok(self.df_original.as_ref().clone())
        }
    }

    /// Asynchronously loads data or applies transformations based on `DataFilter`.
    /// Returns a **new** `DataContainer` state (taken and returned by value).
    /// This function coordinates the sequence of transformations using the Strategy pattern.
    ///
    /// ## Flow:
    /// 1. Get the initial DataFrame value (either by reading file or cloning `df_original`) via `prepare_initial_dataframe`.
    ///    This also updates `self.extension`, `self.df_original`, and `filter.schema_without_index` if a file was read.
    /// 2. Build the pipeline vector `transformations` by pushing concrete strategy instances based on flags in the `filter`.
    /// 3. Reset `filter.apply_sql` flag if SQL transformation was included in the pipeline.
    /// 4. Execute the pipeline: Iterate through the `transformations` vector, calling `apply` on each, chaining the output DataFrame.
    /// 5. Update the final `filter.schema` based on the DataFrame's state after all transformations.
    /// 6. Update `self.df`, `self.filter`, `self.format`, and reset `self.sort` with the results of this operation.
    /// 7. Return the modified `self`.
    pub async fn load_data(
        mut self,
        mut filter: DataFilter,
        format: DataFormat,
    ) -> PolarsViewResult<Self> {
        // 1. Get Initial DataFrame value & Update self (df_original, extension)
        let mut data_frame = self.prepare_initial_dataframe(&mut filter).await?;

        // 2. Build the Transformation Pipeline based on the filter configuration.
        // Create a vector of trait objects representing the transformations to apply.
        let mut transformations: Vec<Box<dyn DataFrameTransform + Send + Sync>> = Vec::new();

        // 2a. Drop/Remove Columns by (Regex) if flag is set
        if filter.drop {
            transformations.push(Box::new(DropColumnsTransform));
        }

        // 2b. Normalize String Columns (Regex) if flag is set
        if filter.normalize {
            transformations.push(Box::new(NormalizeTransform));
        }

        // 2c. Replace specific Values with Null
        transformations.push(Box::new(ReplaceNullsTransform));

        // 2d. SQL Execution if flag is set
        if filter.apply_sql {
            transformations.push(Box::new(SqlTransform));
            filter.apply_sql = false; // Reset flag
        }

        // 2e. Null Column Removal if flag is set
        if filter.exclude_null_cols {
            transformations.push(Box::new(RemoveNullColumnsTransform));
        }

        // 2f. Add Row Index Column (Conditional) if flag is set
        // This must run relatively late as its name conflict check uses the *current* schema.
        if filter.add_row_index {
            transformations.push(Box::new(AddRowIndexTransform));
        }

        // 3. Execute the Pipeline: Apply each selected transformation sequentially.
        for transform in transformations {
            data_frame = transform.apply(data_frame, &filter)?;
        }

        // 4. Update filter's `schema` with the final schema after all transformations are applied.
        filter.schema = data_frame.schema().clone();

        tracing::debug!("Load/transform pipeline successfully applied!");
        tracing::debug!("Final filter state after load: {:#?}", filter);

        // 5. Update self fields with the final results.
        self.df = Arc::new(data_frame);
        self.filter = Arc::new(filter);
        self.format = Arc::new(format);
        self.sort = Vec::new();

        // 6. Return the modified container value.
        Ok(self)
    }

    /// Asynchronously creates a *new* `DataContainer` with updated format settings.
    /// Preserves the existing data (`df`, `df_original`) and sort criteria (`sort`).
    ///
    /// Triggered by `layout.rs` when format UI elements change. This is a very fast operation.
    pub async fn update_format(
        mut self,
        format: DataFormat, // NEW format settings
    ) -> PolarsViewResult<Self> {
        tracing::debug!("update_format: Updating format to {:#?}", format);
        self.format = Arc::new(format); // update format

        Ok(self)
    }

    /// Asynchronously creates a *new* `DataContainer` with the `df` sorted according
    /// to the provided `new_sort_criteria`.
    ///
    /// Triggered by `layout.rs` after a user clicks a sortable header, resulting in new criteria.
    /// Handles multi-column sorting based on the order, direction, and nulls_last settings
    /// in `new_sort_criteria`.
    /// If `new_sort_criteria` is empty, it resets the view by setting `df` to `df_original`.
    ///
    /// ## Logic & State Update:
    /// 1. Check if `new_sort_criteria` is empty.
    /// 2. **Handle Empty (Reset):** If empty, create new container:
    ///    *   `df`: Cloned `Arc` of the input `df_original`.
    ///    *   `df_original`: Cloned `Arc` of the input `df_original`.
    ///    *   `sort`: The empty `new_sort_criteria` vector.
    ///    *   Other fields cloned from input container.
    /// 3. **Handle Non-Empty (Apply Sort):** If not empty:
    ///    a. Extract column names, descending flags, and **nulls_last flags** from `new_sort_criteria`.
    ///    b. Configure Polars `SortMultipleOptions`.
    ///    c. Call `data_container.df.sort()` using the *currently displayed* df as input.
    ///    d. Create new container:
    ///    *   `df`: *New* `Arc` wrapping the **sorted** DataFrame.
    ///    *   `df_original`: *Cloned* `Arc` of the **input** `df_original`.
    ///    *   `sort`: The `new_sort_criteria` that *caused* this sort.
    ///    *   Other fields cloned from input container.
    /// 4. Return `Ok(new_container)`.
    pub async fn apply_sort(
        mut self,                       // Current container state
        new_sort_criteria: Vec<SortBy>, // The *desired* new sort state
    ) -> PolarsViewResult<Self> {
        if new_sort_criteria.is_empty() {
            // --- 2. Handle Empty (Reset) ---
            tracing::debug!(
                "apply_sort: Sort criteria list is empty. Resetting df to df_original."
            );

            // Get filter and format
            let format = self.format.as_ref().clone();
            let mut filter = self.filter.as_ref().clone();
            filter.apply_sql = true;

            // Apply transformations
            // self.sort = Vec::new(); // Store the empty Vec as the current state
            self = self.load_data(filter, format).await?;

            return Ok(self);
        }

        // --- 3. Handle Non-Empty (Apply Sort) ---
        tracing::debug!(
            "apply_sort: Applying cumulative sort. Criteria: {:#?}",
            new_sort_criteria
        );

        // 3a. Extract sort parameters
        let column_names: Vec<PlSmallStr> = new_sort_criteria
            .iter()
            .map(|sort| sort.column_name.clone().into()) // PlSmallStr is efficient here
            .collect();

        let descending_flags: Vec<bool> = new_sort_criteria
            .iter()
            .map(|sort| !sort.ascending)
            .collect();

        let nulls_last_flags: Vec<bool> = new_sort_criteria
            .iter()
            .map(|sort| sort.nulls_last)
            .collect();

        // 3b. Configure Polars Sort Options
        // Set descending flags and **nulls_last flags** for multi-column sort.
        let sort_options = SortMultipleOptions::default()
            .with_order_descending_multi(descending_flags)
            .with_nulls_last_multi(nulls_last_flags) // Use the extracted flags
            .with_maintain_order(true) // Maintain relative order of equal elements
            .with_multithreaded(true);

        // 3c. Perform Sorting on the *current* df
        // NOTE: Sorting based on the *new cumulative* criteria.
        let df_sorted = self.df.sort(column_names, sort_options)?;
        tracing::debug!("apply_sort: Polars multi-column sort successful.");

        self.df = Arc::new(df_sorted); // Use the newly sorted DataFrame
        self.sort = new_sort_criteria; // Store the criteria that produced this state

        // 3d. Create New Container with sorted data and new criteria
        Ok(self)
    }

    // --- UI Rendering Methods ---

    /// Renders the main data table using `egui_extras::TableBuilder`.
    /// Handles sort interactions via `render_table_header`.
    ///
    /// Returns `Some(new_sort_criteria)` if a header click requires a sort state update.
    pub fn render_table(&self, ui: &mut Ui) -> Option<Vec<SortBy>> {
        // Variable to capture the new sort criteria if a header is clicked.
        let mut updated_sort_criteria: Option<Vec<SortBy>> = None;

        // Closure to render the header row. Captures `self` and the output Option.
        let analyze_header = |mut table_row: TableRow<'_, '_>| {
            self.render_table_header(
                &mut table_row,
                &mut updated_sort_criteria, // Pass mutable ref to capture signal
            );
        };

        // Closure to render data rows.
        let analyze_rows = |mut table_row: TableRow<'_, '_>| {
            self.render_table_row(&mut table_row);
        };

        // Configure and build the table.
        self.build_configured_table(ui, analyze_header, analyze_rows);

        // Return the signal from header interactions.
        updated_sort_criteria
    }

    /// Renders the header row, creating clickable cells for sorting.
    /// Reads the current sort state (`self.sort`), including nulls_last. On click,
    /// calculates the *next* sort state (cycling through 4 sorted states + NotSorted),
    /// modifies a *cloned* sort criteria `Vec`, and signals this *new `Vec`* back
    /// via the `sort_signal` output parameter.
    ///
    /// ### Arguments
    /// * `table_row`: Egui context for the header row.
    /// * `sort_signal`: Output parameter (`&mut Option<Vec<SortBy>>`). Set to `Some(new_criteria)`
    ///   if a click occurred that requires updating the sort state.
    fn render_table_header(
        &self,
        table_row: &mut TableRow<'_, '_>,
        sort_signal: &mut Option<Vec<SortBy>>,
    ) {
        for column_name in self.df.get_column_names() {
            table_row.col(|ui| {
                // 1. Determine current interaction state based on `ascending` and `nulls_last`.
                let (current_interaction_state, sort_index) = self
                    .sort
                    .iter()
                    .position(|criterion| criterion.column_name == *column_name)
                    .map_or((HeaderSortState::NotSorted, None), |index| {
                        let criterion = &self.sort[index];
                        // ** Map to the correct 4-state enum based on both bools **
                        let state = match (criterion.ascending, criterion.nulls_last) {
                            (false, false) => HeaderSortState::DescendingNullsFirst,
                            (true, false) => HeaderSortState::AscendingNullsFirst,
                            (false, true) => HeaderSortState::DescendingNullsLast,
                            (true, true) => HeaderSortState::AscendingNullsLast,
                        };
                        (state, Some(index))
                    });

                // 2. Render the sortable header widget (uses the new state and get_icon).
                let response = ui.render_sortable_header(
                    column_name,
                    &current_interaction_state,
                    sort_index, // Pass index for display (e.g., "1▼")
                    self.format.use_enhanced_header,
                );

                // 3. Handle Click Response.
                if response.clicked() {
                    tracing::debug!(
                        "Header clicked: '{}'. Current state: {:?}, Index: {:?}",
                        column_name,
                        current_interaction_state,
                        sort_index
                    );
                    // Calculate the next state in the 5-state cycle
                    let next_interaction_state = current_interaction_state.cycle_next();
                    tracing::debug!("Next interaction state: {:#?}", next_interaction_state);

                    // 4. Prepare the *new* list of sort criteria based on the click outcome.
                    let mut new_sort_criteria = self.sort.clone(); // Start with current criteria
                    let column_name_string = column_name.to_string();
                    let current_pos = new_sort_criteria
                        .iter()
                        .position(|c| c.column_name == *column_name);

                    // 5. Modify the cloned vector based on the next interaction state.
                    match next_interaction_state {
                        HeaderSortState::NotSorted => {
                            // Remove the sort criterion for this column if it exists.
                            if let Some(pos) = current_pos {
                                new_sort_criteria.remove(pos);
                            }
                        }
                        // Handle the 4 sorted states: update existing or add new.
                        _ => {
                            // ** Determine new ascending and nulls_last from the next state **
                            let (new_ascending, new_nulls_last) = match next_interaction_state {
                                HeaderSortState::DescendingNullsFirst => (false, false),
                                HeaderSortState::AscendingNullsFirst => (true, false),
                                HeaderSortState::DescendingNullsLast => (false, true),
                                HeaderSortState::AscendingNullsLast => (true, true),
                                // NotSorted case is handled above, this is exhaustive for sorted states
                                HeaderSortState::NotSorted => {
                                    unreachable!("NotSorted case already handled")
                                }
                            };

                            if let Some(pos) = current_pos {
                                // Update existing criterion in place.
                                new_sort_criteria[pos].ascending = new_ascending;
                                new_sort_criteria[pos].nulls_last = new_nulls_last;
                            } else {
                                // Add new criterion to the end of the vector.
                                new_sort_criteria.push(SortBy {
                                    column_name: column_name_string,
                                    ascending: new_ascending,
                                    nulls_last: new_nulls_last,
                                });
                            }
                        }
                    } // end match next_interaction_state

                    tracing::debug!(
                        "Signaling new sort criteria for async update: {:#?}",
                        new_sort_criteria
                    );

                    // 6. Set the output parameter to signal the required action and the new sort state.
                    *sort_signal = Some(new_sort_criteria);
                } // end if response.clicked()
            }); // End cell definition
        } // End loop over columns
    }

    /// Renders a single data row in the table body.
    ///
    /// Called by the `analyze_rows` closure (defined in `render_table`) for each row index
    /// provided by the `egui_extras::TableBuilder`.
    ///
    /// For each cell in the row:
    /// 1. Calls `get_decimal_and_layout` (using `self.format`) to determine the `egui::Layout` (for alignment)
    ///    and `Option<usize>` (for decimal places, if applicable) based on the column's `DataType`.
    /// 2. Calls `Self::format_cell_value` to retrieve the `AnyValue` from the DataFrame and format it
    ///    into a `String`, applying decimal rounding if needed.
    /// 3. Adds a cell to the `egui` row (`table_row.col`) and renders the formatted string as a `Label`
    ///    within the determined `Layout`.
    ///
    /// ### Arguments
    /// * `table_row`: The `egui_extras::TableRow` context providing the `row_index` and cell adding methods.
    fn render_table_row(&self, table_row: &mut TableRow<'_, '_>) {
        let row_index = table_row.index(); // Get the 0-based data row index.

        // Iterate through each column (Polars Series) in the DataFrame.
        for column_series in self.df.columns() {
            // Determine alignment and decimal places using the feature-flagged helper.
            // Passes the Series and the current format settings Arc.
            let (opt_decimal, layout) = get_decimal_and_layout(column_series, &self.format);

            // Get the raw AnyValue and format it into a display String.
            let value_str = self.format_cell_value(column_series, row_index, opt_decimal);

            // Add a cell to the egui row.
            table_row.col(|ui| {
                // Apply the determined layout (alignment) to the cell content. Prevent wrapping.
                ui.with_layout(layout.with_main_wrap(false), |ui| {
                    ui.label(value_str); // Display the formatted value.
                });
            });
        }
    }

    /// Retrieves and formats a single cell's `AnyValue` into a displayable `String`.
    /// Called repeatedly by `render_table_row`.
    ///
    /// Logic:
    /// 1. Get `AnyValue` from `column` at `row_index` using `column.get()`.
    /// 2. Handle `Result`: Return error string on `Err`.
    /// 3. On `Ok(any_value)`:
    ///    - Match on `(any_value, opt_decimal)`:
    ///      - Floats with `Some(decimal)`: Format using `format!("{:.*}", decimal, f)`.
    ///      - `AnyValue::Null`: Return `""`.
    ///      - `AnyValue::String(s)`: Return `s.to_string()`.
    ///      - Other types (Ints, Bool, Date, etc.) or Floats with `None` decimal: Use `any_value.to_string()`.
    ///
    /// ### Arguments
    /// * `column`: Reference to the Polars `Series` (`PColumn`).
    /// * `row_index`: Row index within the series.
    /// * `opt_decimal`: `Option<usize>` specifying decimal places for floats (from `get_decimal_and_layout`).
    ///
    /// ### Returns
    /// `String`: The formatted cell value.
    fn format_cell_value(
        &self,
        column: &PColumn,
        row_index: usize,
        opt_decimal: Option<usize>, // Info comes from get_decimal_and_layout which uses self.format
    ) -> String {
        match column.get(row_index) {
            Ok(any_value) => {
                // Format based on the AnyValue variant and decimal setting.
                match (any_value, opt_decimal) {
                    // Float with specific decimal request: Apply precision formatting.
                    (AnyValue::Float32(value), Some(decimal)) => format!("{value:.decimal$}"),
                    (AnyValue::Float64(value), Some(decimal)) => format!("{value:.decimal$}"),

                    // Null value: Display as empty string.
                    (AnyValue::Null, _) => String::new(),

                    // String value: Convert inner &str to String.
                    (AnyValue::String(value), _) => value.to_string(), // Handle StringOwned too if necessary.

                    // Other AnyValue types OR Float without specific decimal: Use default Polars to_string().
                    (other_anyvalue, _) => other_anyvalue.to_string(),
                }
            }
            Err(e) => {
                // Handle error retrieving value (e.g., index out of bounds, though unlikely with TableBuilder).
                tracing::warn!(
                    "format_cell_value: Failed get value col '{}' row {}: {}",
                    column.name(),
                    row_index,
                    e
                );
                "⚠ Err".to_string() // Return placeholder error string for display.
            }
        }
    }

    /// Prepares configuration values needed for `TableBuilder`.
    /// Encapsulates calculations for sizes, strategies, and IDs based on current format and UI state.
    ///
    /// Called by `build_configured_table`.
    fn prepare_table_build_config(&self, ui: &Ui) -> TableBuildConfig {
        // --- Calculate Style and Dimensions ---
        let style = ui.style();
        let text_height = TextStyle::Body.resolve(style).size; // Standard row height
        let num_columns = self.df.width().max(1); // Ensure at least 1 column logically
        let suggested_width = 150.0; // A sensible starting point for auto/initial width

        // --- Calculate Column Widths ---
        // Base available width excluding spacings and potential scrollbar
        let available_width = ui.available_width()
            - ((num_columns + 1) as f32 * style.spacing.item_spacing.x) // Account for inter-column spacing
            - style.spacing.scroll.bar_width; // Assume scrollbar might be present

        // Initial width used in non-auto mode, ensure it's not too small
        let initial_col_width = (available_width / num_columns as f32).max(suggested_width);

        // Minimum width any column can be resized to
        let min_col_width = style.spacing.interact_size.x.max(20.0);

        // --- Calculate Header Height ---
        // Determine padding based on header style setting
        let padding = if self.format.use_enhanced_header {
            self.format.header_padding
        } else {
            self.format.get_default_padding()
        };

        // Calculate height: base interact size + internal spacing + custom padding
        let header_height = style.spacing.interact_size.y // Base height for clickable elements
                           + 2.0 * style.spacing.item_spacing.y // Top/bottom internal spacing
                           + padding; // Add configured extra padding

        // --- Determine Column Sizing Strategy ---
        let column_sizing_strategy = if self.format.auto_col_width {
            // Automatic: sizes based on content, potentially slower
            tracing::trace!(
                "prepare_table_build_config: Using Column::auto_with_initial_suggestion({})",
                suggested_width
            );
            Column::auto_with_initial_suggestion(suggested_width)
        } else {
            // Fixed initial: faster, uses calculated width
            tracing::trace!(
                "prepare_table_build_config: Using Column::initial({})",
                initial_col_width
            );
            Column::initial(initial_col_width)
        }
        // Common constraints applied to either strategy
        .at_least(min_col_width) // Min resize width
        .resizable(true) // Allow user resizing
        .clip(true); // Clip content within cell bounds

        // --- Generate Table ID ---
        // **Key**: ID incorporates `auto_col_width`. Changing this flag results in a *different* ID,
        // forcing egui to discard cached layout state (like manually resized widths)
        // and recompute the layout using the new column sizing strategy.
        let table_id = Id::new("data_table_view").with(self.format.auto_col_width);
        tracing::trace!(
            "prepare_table_build_config: Using table_id: {:?} based on auto_col_width={}",
            table_id,
            self.format.auto_col_width
        );

        // --- Log Calculated Values ---
        tracing::trace!(
            "prepare_table_build_config: text_height={}, num_cols={}, header_height={}, auto_width={}, table_id={:?}",
            text_height,
            num_columns,
            header_height,
            self.format.auto_col_width,
            table_id
        );

        // --- Return the configuration struct ---
        TableBuildConfig {
            text_height,
            num_columns,
            header_height,
            column_sizing_strategy,
            table_id,
        }
    }

    /// Configures and builds the `egui_extras::Table` using `TableBuilder` and pre-calculated configuration.
    ///
    /// ## Configuration Source
    /// Relies on `prepare_table_build_config` to provide layout parameters, sizing strategies,
    /// and the crucial `table_id` for layout persistence control.
    ///
    /// ### Arguments
    /// * `ui`: The `egui::Ui` context for drawing.
    /// * `analyze_header`: Closure for rendering the header row content.
    /// * `analyze_rows`: Closure for rendering data row content.
    fn build_configured_table(
        &self,
        ui: &mut Ui,
        analyze_header: impl FnMut(TableRow<'_, '_>), // Closure to draw the header.
        analyze_rows: impl FnMut(TableRow<'_, '_>),   // Closure to draw data rows.
    ) {
        // 1. Get the calculated configuration values.
        let config = self.prepare_table_build_config(ui);

        // 2. Configure and Build the Table using values from `config`.
        TableBuilder::new(ui)
            // Set the ID controlling layout persistence (crucial for `auto_col_width` toggle).
            .id_salt(config.table_id)
            .striped(true) // Alternate row backgrounds.
            // Define sizing strategy for data columns using config.
            .columns(config.column_sizing_strategy, config.num_columns)
            // Add a final 'remainder' column to fill unused space.
            .column(Column::remainder())
            .resizable(true) // Allow resizing via separators.
            .auto_shrink([false, false]) // Don't shrink horizontally or vertically.
            // Define the header section using calculated height and the provided closure.
            .header(config.header_height, analyze_header)
            // Define the body section.
            .body(|body| {
                let num_rows = self.df.height(); // Get total rows from the DataFrame.
                // Use `body.rows` for efficient virtual scrolling.
                // Provide row height, total rows, and the row drawing closure.
                body.rows(config.text_height, num_rows, analyze_rows);
            }); // End table configuration. Egui draws the table.
    }
}