@syncfusion/ej2-spreadsheet/docs/skills/action/protect-sheet.md

Feature-rich JavaScript Spreadsheet (Excel) control with built-in support for selection, editing, formatting, importing and exporting to Excel

# Protect Sheet Module data flow

## What It Does
Protect-sheet module manages sheet- and workbook-level protection: applying and removing protection, password dialogs, locking cells/columns, updating UI controls, and enforcing protected-state constraints across actions and keyboard interactions.

## Entry Points

**WorkbookProtectSheet (Core)**
- `protectsheetHandler(args)` - Core handler that marks a sheet protected, applies `protectSettings`, sets default column locks, and notifies workbook-level protection updates.
- `unprotectsheetHandler(args)` - Removes protection flags and restores protect settings when unprotecting.
- `lockCells(args)` - Locks/unlocks cells in a given range by calling `setCell` and `setColumn` on the `SheetModel`.

**ProtectSheet (Spreadsheet / UI)**
- UI event handlers that display password dialogs and option lists, collect user choices, and forward requests to the core via notifications (`protectsheetHandler`, `applyProtect`, etc.).
- `protectSheetHandler(args)` - UI responder that updates ribbon/button states and notifies `protectCellFormat` and other UI subsystems when protection changes.
- Dialog flows: `createDialogue()`, `selectOption()`, `reEnterSheetPassword()`, `protectWorkbook()`, `unProtectWorkbook()`, and related dialog helpers.

## Core Logic Flow

1. UI initiates protect/unprotect via notifications (e.g., `applyProtect`, `protectsheetHandler`), or programmatic calls.
2. `WorkbookProtectSheet.protectsheetHandler`:
   - Determines target `sheetIndex` and retrieves `SheetModel`.
   - Sets `isProtected` to true and writes `protectSettings` (selectCells, formatCells, formatRows, formatColumns, insertLink, selectUnLockedCells) using `setSheetPropertyOnMute` to avoid noisy binds.
   - Notifies `protectSheetWorkBook` and `updateToggle` to update higher-level workbook UI state.
   - Stores the optional password on the sheet and marks undefined column `isLocked` as `true`.
3. `WorkbookProtectSheet.unprotectsheetHandler` clears `isProtected`, resets protect settings, and notifies `protectSheetWorkBook` and `updateToggle`.
4. `WorkbookProtectSheet.lockCells` maps an A1 range to indices, iterates, calls `setColumn` when full columns are targeted, and `setCell` per cell to toggle `isLocked`. Optionally emits an `actionComplete` event when `triggerEvent` is provided.

## UI Logic Flow

1. User triggers protection via UI (menu/ribbon) or keyboard; `ProtectSheet` receives `applyProtect` / `protectSheet` events.
2. When enabling protection, `ProtectSheet.createDialogue()` shows a dialog with password input and a ListView of allowed actions (SelectCells, SelectUnlockedCells, FormatCells, FormatRows, FormatColumns, InsertLinks).
3. On confirm (`selectOption`) the UI gathers selected options and calls `this.parent.notify(protectsheetHandler, { protectSettings, password, triggerEvent: true })` to apply protection at the core level, then updates selection state and clears undo history (`clearUndoRedoCollection`).
4. When disabling protection or unprotecting, the UI shows password entry dialogs as needed (`unprotectdlgOkClick`, `unProtectWorkbook` flows) and calls core unprotect handlers.
5. UI `protectSheetHandler` responds to model protection changes by toggling ribbon/toolbar controls (lists of `disableHomeBtnId` / `enableHomeBtnId`) and calling `protectCellFormat` and `enableFormulaInput` to enforce UI restrictions. It also triggers `completeAction` when `triggerEvent` is true.
6. Additional UI flows handle import-protected files (`importProtectWorkbook` / `importProtectPasswordContent`) and toggling workbook-protection states.

## Operations Handled

- Apply Sheet Protection
  - Show password/options dialog, collect `protectSettings`, call core to set `isProtected` and `password`.
  - Update UI toggles, disable/enable ribbon buttons, clear undo/redo where appropriate.

- Remove Sheet Protection
  - Prompt for password when necessary, clear `isProtected`, and restore UI controls.

- Lock/Unlock Cells Programmatically
  - `lockCells` writes `isLocked` on targeted cells/columns and optionally emits `actionComplete` for caller visibility.

- Workbook Protection
  - UI exposes workbook-level protect/unprotect dialogs and sets `parent.password`/`parent.isProtected` accordingly; updates sheet tabs and toggle states.

- Import-protected Workbooks/Sheets
  - UI handles entering passwords for imported files and routes the unlock operation through existing protect/unprotect flows.

## Validation & Safety

- Dialog safeguards: `beforeOpen` and `beforeClose` hooks allow cancellation of dialogs through `dialogBeforeOpen` events.
- State mute updates: `setSheetPropertyOnMute` avoids noisy reactive updates while core state changes are applied.
- Column defaults: When protecting, undefined `column.isLocked` values are defaulted to `true` to avoid accidental edits.
- Protected actions gating: UI checks `sheet.isProtected` and `protectSettings` before allowing edits, formats, merges, or other mutations; keyboard handlers consult `isProtected` to block commands.

## Desired Outputs (Post-Protection)

- Model: Sheet `isProtected` flag and `protectSettings` set; `password` stored on sheet when provided; affected columns/cells marked with `isLocked`.
- UI: Ribbon and toolbar buttons disabled/enabled according to protection; protect toggles updated; dialogs closed and focus returned.
- Events: `protectSheetWorkBook`, `updateToggle`, `protectCellFormat`, `completeAction`, and `actionComplete` emitted for consumers and telemetry.

## System-Level

- Important types & events:
  - `ProtectSettings`, `UnprotectArgs`, `applyProtect`, `protectSheet`, `protectsheetHandler`, `protectSheetWorkBook`, `unprotectsheetHandler`, `setLockCells`, `clearUndoRedoCollection`, `protectCellFormat`, `updateToggleItem`, `completeAction`, `protectSelection`, `importModelUpdate`.

- Modules:
  - Core: `src/workbook/actions/protect-sheet.ts` (`WorkbookProtectSheet`)
  - UI: `src/spreadsheet/actions/protect-sheet.ts` (`ProtectSheet`)

## Test / Verification Actions

- Apply protection with various `protectSettings` combinations and verify restricted actions (formatting, inserting links, selecting cells) are disabled.
- Verify password dialog flows: setting a password and unprotecting with correct/incorrect password shows expected behavior and messages.
- Lock/unlock a specific range via `setLockCells` and confirm `isLocked` on cells and columns and that `actionComplete` fires when requested.
- Import an encrypted workbook and verify `importProtectWorkbook` prompts and the provided password unlocks the document.
- Confirm ribbon toolbar items toggle correctly and `protectCellFormat` is invoked with expected button id lists.

---