# Overlay Module data flow

**Purpose:** Concise data-flow summary for overlay.

**Primary role:** Manage creation, interaction, resizing, and lifecycle of floating overlay elements (charts/images) on the sheet; translate pointer interactions into cell/row/column coordinates and trigger refresh/resize operations.

- **Constructor:** `new Overlay(parent)` — registers listeners for `selectionStatus`, `refreshOverlayElem`, and `spreadsheetDestroyed`.

**Core APIs & flow**
- `insertOverlayElement(id, range, sheetIndex)`:
  - Creates an `.e-ss-overlay` container using `parent.createElement` and positions it via `getCellPosition` and DPR adjustments.
  - Chooses mount point depending on freeze pane state and `sheetIndex` vs `activeSheetIndex` (main content vs sheet container vs hidden body for printing).
  - Calls `renderResizeHandler()` and `addEventListener()` for interaction wiring; computes initial width/height.
- `adjustFreezePaneSize(model, element, range)`:
  - Recomputes top/left offsets of overlays inside frozen panes using `getRowsHeight`, `getColumnsWidth`, and viewport offsets.
- Interaction handlers:
  - `addEventListener(div)`: attach start/move/end handlers and subscribe to `overlayEleSize`.
  - `overlayClickHandler(e)`: mark overlay active, compute original positions/sizes, detect resizer vs move, insert design chart focus via notifications.
  - `overlayMouseMoveHandler(e)`: while dragging/resizing, update `style.top/left/width/height`, enforce min sizes and freeze-area constraints, and notify `refreshChartSize`.
  - `overlayMouseUpHandler(e, isMouseUp?)`: on release compute prev/current row/col indexes (notifying `getRowIdxFromClientY` / `getColIdxFromClientX`), build `BeforeImageRefreshData`, and notify `refreshChartCellObj` or `refreshImgCellObj` to apply changes. Handles frozen-pane relocation logic and chart vs image requests.
  - `isOverlaySelected(args)`: returns whether an overlay is active.
  - `refreshOverlayElem(args)`: deactivate active overlays, remove design chart, and notify `clearChartBorder`.
- `renderResizeHandler(overlay)`: adds visual resize handles (`e-ss-resizer`) for T/R/B/L sides.
- `removeEventListener()` / `destroy()`:
  - Remove DOM event listeners, off parent event subscriptions, and null internal state to avoid leaks.

**Notifications used**
- Emits / notifies: `refreshChartSize`, `refreshChartCellObj`, `refreshImgCellObj`, `insertDesignChart`, `removeDesignChart`, `focusChartBorder`, `clearChartBorder`.
- Consumes / calls: `getCellPosition`, `getRowIdxFromClientY`, `getColIdxFromClientX`, `getRowsHeight`, `getColumnsWidth`, `addDPRValue`, `getCellIndexes`.

**Side effects & invariants**
- Mutates overlay DOM (top/left/width/height) directly during drag/resize; must call `refreshChartCellObj`/`refreshImgCellObj` to persist.
- Enforces minimum overlay size (20px) and respects freeze-pane boundaries.
- Uses `parent.allowEditing` and sheet protection checks to gate interactions.
- Appends overlays to different containers based on freeze state and printing; printing places overlays in hidden body with `visibility: hidden`.

**Where it's used**
- Instantiated by `Spreadsheet` services to manage chart/image overlays and their interaction lifecycle.

**Maintainer notes**
- When adjusting layout logic, ensure `addDPRValue` is used to maintain crisp placement on high-DPI displays.
- Keep `refreshChartSize` and `refreshChartCellObj` callers in sync when changing DOM dimensions to avoid visual/performance glitches.
- Ensure `removeEventListener()` is called on sheet teardown to avoid dangling document event handlers.