# Column Renderer Module data flow

## What It Does
Manages column metadata (width, hidden, customWidth, validation, format) and exposes helpers to read/write column state. The workbook `Column` model stores column properties; the spreadsheet renderer uses those properties to compute column widths, build colgroups/headers, handle hide/show and virtualization interactions.

Primary files: `src/workbook/base/column.ts` (Core Column model & helpers) and `src/spreadsheet/renderer/column.ts` (UI Column rendering and layout — consumer of column helpers).

## Entry Points (Core)
**Module / Class:** `Column` (workbook/base/column.ts)
- Model fields: `index`, `width`, `customWidth`, `hidden`, `format`, `isLocked`, `validation`, `isReadOnly`.
- Helpers:
  - `getColumn(sheet, colIndex)` — ensure `sheet.columns` exists and return column model at index.
  - `setColumn(sheet, colIndex, column)` — merge provided props into existing column model.
  - `getColumnWidth(sheet, index, skipHidden?, checkDPR?)` — compute width with default fallback and optional device-pixel-ratio correction.
  - `getColumnsWidth(sheet, startCol, endCol, checkDPR?)` — sum widths across a column range.
  - `isHiddenCol(sheet, index)` — boolean helper for visibility checks.
  - `checkColumnValidation(column, rowIndex, colIndex)` — check whether column-level validation applies to a given cell.

Responsibilities: provide deterministic column metrics for layout, preserve per-column settings across serialization and operations, and expose validation hooks used by editors/validators.

## Entry Points (UI)
**Column renderer (Spreadsheet layer)** — typical responsibilities (file: `src/spreadsheet/renderer/column.ts`)
- Build and update `<colgroup>` and column header `<th>` elements using `getColumnWidth()` and `isHiddenCol()`.
- Respond to column operations: resize (mouse/keyboard), hide/show, insert/delete; call `setColumn()` to persist changes and notify sheet layout update.
- Virtualization: compute visible column ranges and sum widths with `getColumnsWidth()` to derive scroll extents and column sizes for content tables.
- DPI-aware rendering: when `checkDPR` is used, apply fractional width corrections to align pixel-perfect layout on high-DPR screens.
- Accessibility: set `aria-colindex` attributes and expose header labels via localized strings.

## ASCII Flow
Column property change (API/user) → `setColumn()` updates model → renderer recalculates col widths (`getColumnWidth` / `getColumnsWidth`) → update `<col>` widths and header cells → notify `refreshView` / `refreshRange` for affected cells → browser reflows with new column layout

## Operations & Responsibilities
- `getColumnWidth(sheet, index, skipHidden?, checkDPR?)` (Core)
  - Return either column-specific width, default (64) or 0 when hidden (unless skipHidden true). When `checkDPR` true, adjust width to nearest device-pixel aligned value.

- `getColumnsWidth(sheet, startCol, endCol, checkDPR?)` (Core)
  - Sum widths across columns (handles swapped indices and defaults) used for computing table/viewport size.

- Column resize (UI)
  - On pointer drag: measure new width, call `setColumn()` with { width, customWidth: true }, then call layout refresh to update colgroup and content cell widths.

- Hide/Show (UI)
  - Toggle `sheet.columns[index].hidden`, update `col` width to 0 and update header visibility; ensure protected-sheet checks before mutating.

- Validation usage
  - `checkColumnValidation()` used by cell-edit/validation pipeline to determine whether column-level validation rules apply for a given cell.

## Validation & Safety
- Hidden column checks: `getColumnWidth()` returns 0 for hidden columns; callers should pass `skipHidden` when computing widths for operations that must include hidden columns.
- DPI corrections: `checkDPR` avoids sub-pixel rendering artifacts on fractional devicePixelRatio displays.
- Mutation safety: `setColumn()` merges keys into existing object rather than replacing, preserving other properties.
- Protection: UI should verify `parent.isProtected` / `column.isReadOnly` semantics prior to mutating the column model.

## Desired Outputs
- Correct column widths applied to both header and content tables, stable scroll extents and accurate virtual scroll computations.
- Hidden columns removed from layout and excluded from visual focus/tab order.
- Column-level validation propagated to cell editors.

## Implementation Notes
- Prefer `getColumnWidth()` for every layout calculation to centralize width logic and DPR adjustments.
- Use `getColumnsWidth()` when computing full-range widths (e.g., for freeze panes or viewport calculations) rather than summing manually.
- When updating many columns (insert/delete/resizing multiple), batch DOM updates to `colgroup` and call a single `refresh` to avoid layout thrash.
- Always preserve existing column model fields by calling `setColumn()` (or merge behavior) rather than replacing the object.
- Keep column ids/indexes stable during insert/delete operations: update `sheet.columns` array carefully and notify dependent subsystems (filters, sorting, charts) after structural changes.

## Key Events & Hooks
- Cross-module notifications: column changes typically trigger layout/render notifications such as `refreshView`, `refreshRange` or module-specific events (`removeDesignChart`, `refreshFilterRange`) depending on the change.

---