# ActionEvents Module data flow

**Purpose:** Concise data-flow summary for `src/spreadsheet/services/action-events.ts`.

**Primary role:** Coordinate action begin/complete lifecycle bridging internal events, parent-level callbacks, and undo/redo/update flows.

- **Constructor:** `new ActionEvents(parent)` : registers listeners via `addEventListener()`.
- **Listens for:** `completeAction`, `beginAction`, `spreadsheetDestroyed` (via `parent.on`).
- **Overrides / wraps:** parent callback hooks (`beforeCellFormat`, `beforeOpen`, `beforeSave`, `beforeSort`) when `initializeActionBegin()` is used — wraps existing handlers to funnel through `actionEventHandler`.

**Key handlers**
- **actionEventHandler(args):** Central router — invokes original hooked function (if present) then forwards to `actionBeginHandler` or `actionCompleteHandler` depending on `actionType`.
- **actionBeginHandler(args):**
  - Emits parent-level user event: `parent.trigger('actionBegin', actionArgs)`.
  - For many action types (clipboard|format|cellSave|addNote|…): calls `parent.notify(setActionData, { args })` to stash action payload for later processing.
  - Manages undo/redo flags on `args` (`isUndo`/`isRedo`) and respects `preventAction`.
  - Skips `setActionData` when `parent.isPrintingProcessing` is true.
- **actionCompleteHandler(args):**
  - Calls `parent.notify(triggerDataChange, args)` (publishes final change to data layer).
  - Triggers `parent.trigger('actionComplete', args)` unless `preventEventTrigger` is set.
  - Calls `parent.notify(updateUndoRedoCollection, { args })` to update undo/redo stack (skipped for some actions like `undoRedo`, `gotoSheet`).
  - Calls `parent.notify(positionAutoFillElement, null)` to finalize autofill UI.

**Lifecycle**
- **addEventListener():** attaches internal handlers to `parent`.
- **removeEventListener():** removes handlers; bound to `spreadsheetDestroyed`.

**Side effects & important invariants**
- Mutates parent callbacks only when `initializeActionBegin()` is executed.
- Uses `parent.trigger` (public event) vs `parent.notify` (internal message bus) consistently.
- `preventAction` halts further internal processing but original callbacks are still invoked.
- `isPrintingProcessing` avoids mutating action data during print workflows.

**Dependencies**
- Imports: `SortEventArgs`, `SaveCompleteEventArgs`, `BeforeCellFormatArgs`, `triggerDataChange`, `beginAction`, `completeAction`, `positionAutoFillElement`, `setActionData`, `updateUndoRedoCollection`, `spreadsheetDestroyed`, and several event-arg types.

**Where it's used**
- Instantiated by the `Spreadsheet` host to centralize begin/complete handling and to integrate with undo/redo and data-change flows.

**Quick notes for maintainers**
- When adding new action types, ensure they are listed in the `setActionData` conditional if they need pre-action payload capture.
- Keep `trigger` vs `notify` semantics in mind: `trigger` is public-facing; `notify` is internal.