# Wrap Text Module data flow

## What It Does
The Wrap Text module controls cell text wrapping and related row-height adjustments. Two-layer architecture: **WrapText (UI)** handles ribbon commands, DOM class toggles, measuring text, and updating row elements; **Workbook (Core)** provides cell data, size helpers, and APIs to persist height/format changes.

## Entry Points

**WrapText (UI Layer)**
- `constructor(parent)` / `addEventListener()` - register handlers for ribbon, wrap events and size-change notifications.
- `ribbonClickHandler()` - handles `Wrap Text` ribbon button: validates readonly state, fires `beginAction`, toggles wrap and triggers `completeAction`.
- `wrapTextHandler(args)` - core worker that toggles wrap classes, computes required line counts, measures text height, and applies new row heights when needed.
- `updateWrapCell(args)` - create/maintain `.e-wrap-content` span inside cell DOM to contain wrapped text and preserve indicators (filter/note/hyperlink).
- `rowHeightChangedHandler()` / `colWidthChanged()` - respond to external size changes and re-evaluate wrap layout for affected cells.
- `removeEventListener()` / `destroy()` - cleanup handlers and temporary DOM helpers.

**Workbook / Core Layer**
- Cell and row helpers: `getCell`, `getRow`, `setRow`/`setRowEleHeight`, `getRowHeight`, `getRowsHeight` used to read and update model and DOM heights.
- Text measurement: `getLines`, `getTextHeightWithBorder`, `getLineHeight`, `getExcludedColumnWidth` compute line counts and pixel heights for wrap decisions.
- Wrap helper: `wrap` (alias `wrapText`) to toggle wrap flag on cell models for address ranges.
- Protection/validation helpers: `isReadOnlyCells`, `beginAction`, `completeAction`, and `applyCF` (conditional format) used during change flows.
- Events/notifications used: `positionAutoFillElement`, `colWidthChanged`, `rowHeightChanged`, `updateWrapCell`.

## Core Logic Flow

```
User toggles Wrap (ribbon) → ribbonClickHandler()
    ↓
Validate readonly → notify `beginAction` → call core `wrapText` to toggle model wrap flag
    ↓
Trigger `wrapTextHandler()` for affected range(s):
    - ensure cell DOM has `.e-wrap-content` wrapper via `updateWrapCell()`
    - add/remove `WRAPTEXT` class and compute `getLines()` per cell based on column width
    - compute pixel height via `getTextHeightWithBorder()` and `getLineHeight()`
    - call `setRowEleHeight()` when new height > previous to update DOM and model
    ↓
Notify `completeAction` and reposition autofill handle via `positionAutoFillElement`
    ↓
Listen for `rowHeightChanged`/`colWidthChanged` and re-run wrap adjustments for visible cells
```

## Operations Handled

1. Toggle wrap for a single cell, range, or selected area and persist cell `wrap` flag.
2. Compute text wrapping lines and pixel height for variable fonts, hyperlinks, and explicit newline characters.
3. Insert/maintain a `.e-wrap-content` span inside cells to contain wrapped nodes while preserving note/filter UI.
4. Adjust row element heights (`setRowEleHeight`) when wrapped content grows beyond current row size.
5. React to column width or row height changes and re-evaluate wrap layout for visible cells.
6. Apply conditional formats (`applyCF`) when wrap-induced height changes occur and conditional formatting exists.

## Wrap Modes

| Mode | Behavior |
|------|----------|
| ToggleWrap | Ribbon or programmatic toggle that sets `wrap` on cell models and recalculates heights. |
| InitialRenderWrap | When rendering cells initially (`initial` flag), measure and apply wrap classes for proper height pre-render. |
| ResponsiveReflow | On column-width or row-height changes, reflow wrapped content and adjust heights as needed. |

## Validation & Safety

- **Read-only checks:** `ribbonClickHandler()` verifies `isReadOnlyCells` before applying wrap; aborts and raises `readonlyAlert` when necessary.
- **Merge & special-cell handling:** Skip negative rowSpan/colSpan cells and treat merged cells carefully; avoid auto-height changes for merged ranges unless safe.
- **Minimum height:** Enforce sensible minimums (20px baseline) when computing heights for empty or single-line cells.
- **Edit-state awareness:** When a cell is being edited, use editor contents to determine wrap requirements (preserve newline edits).
- **Performance:** Only re-evaluate cells that are in-view or explicitly flagged (`initial` or `outsideViewport` handling) to minimize layout thrash.

## Desired Outputs

**User-Facing:**
- Toggleable Wrap Text control that visibly wraps text in cells and grows row height as needed.
- Wrapped content preserves notes, filter buttons, and hyperlinks without losing layout.
- Smooth updates when column widths change or when rows are programmatically resized.

**System-Level:**
- Cell `wrap` metadata updated in the workbook model; row heights persisted via `setRow`/`setRowEleHeight`.
- Notifications emitted: `beginAction`, `completeAction`, `rowHeightChanged`, `colWidthChanged`, `positionAutoFillElement`.
- Conditional formats reapplied when wrap changes affect layout.
- Minimal re-rendering: only affected visible ranges are refreshed and measured.