@syncfusion/ej2-spreadsheet/docs/skills/integration/color-picker.md

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

# Color Picker Module data flow

## What It Does
The Color Picker module provides font and fill color selection controls in the Spreadsheet ribbon. It wraps Syncfusion `ColorPicker` components, maps user selections to cell format updates (`setCellFormat`), and maintains accessible UI state for selected colors.

Primary implementation file: `src/spreadsheet/integrations/color-picker.ts`.

## Entry Points (UI)
**Class:** `ColorPicker`
- Listens: `beforeRibbonCreate`, `destroyRibbonComponents`, `spreadsheetDestroyed`.
- Key public/private methods:
  - `render()` — create two `ColorPicker` components (font & fill), attach to DOM, configure presets and behavior.
  - `updateSelectedColor(color, ele, name, isCreated?)` — update ARIA labels and visual selected indicator.
  - `openHandler()` — set localized titles on open.
  - `beforeCloseHandler()` — reset mode switch and focus back to primary UI element.
  - `beforeModeSwitch()` — configure picker buttons/labels when switching between `Palette` and `Picker` modes.
  - `destroy()` — teardown pickers and remove listeners.

## ASCII Core Logic Flow
Ribbon initialization → `beforeRibbonCreate` event → `ColorPicker.render()`
         ↓
Create two `ColorPickerComponent` instances (font, fill) → attach inputs to DOM → set ids `${id}_font_color_picker` / `${id}_fill_color_picker`
         ↓
User picks color → `change` handler → build `SetCellFormatArgs` and `parent.notify(setCellFormat, eventArgs)`
         ↓
If `eventArgs.cancel` → revert picker value; else `updateSelectedColor()` updates UI (ARIA and indicator)
         ↓
Ribbon destroyed or spreadsheet destroyed → `destroy()` → pickers destroyed and listeners removed

## Operations (functions & responsibilities)
- `render()`
  - Creates two `<input type="color">` host elements and initializes `ColorPickerComponent` instances for font and fill.
  - Configures: `mode: 'Palette'`, `presetColors` (`fontColor` and `fillColor`), `showButtons`, `enableOpacity: false`, `cssClass: 'e-spreadsheet-color-popup'`, RTL, and event callbacks.
  - Appends pickers to `parent.element` and sets container ids:
    - `${id}_font_color_picker`
    - `${id}_fill_color_picker`
  - Adds icon classes to the selected-color element: `e-icons`, `e-font-color` / `e-fill-color`.

- `change` handler (for both pickers)
  - Reads color via picker API (`getValue()`), composes `SetCellFormatArgs` (`style.color` or `style.backgroundColor`, `onActionUpdate: true`) and `parent.notify(setCellFormat, eventArgs)`.
  - If `eventArgs.cancel` true → revert picker value to previous; otherwise call `updateSelectedColor()`.

- `updateSelectedColor()`
  - Uses localization service to compute aria text and applies it to `.e-dropdown-btn` and `.e-split-colorpicker`.
  - Sets inline style on the visual indicator (`borderBottomColor`) to reflect chosen color.

- Mode and lifecycle helpers
  - `openHandler()` sets the More Colors title for the mode switch button.
  - `beforeModeSwitch()` toggles `showButtons` and localizes apply/cancel/more labels when switching picker mode.
  - `beforeCloseHandler()` enforces default mode switch state and returns focus to the split button on close.
  - `destroy()` cleans up `ColorPickerComponent` instances and removes event listeners.

## Validation & Safety
- Change can be canceled by the `setCellFormat` handler: code reverts the color picker value when `eventArgs.cancel` is set.
- Lifecycle safety: `destroy()` is invoked on `destroyRibbonComponents` and `spreadsheetDestroyed` to avoid leaking components or handlers.
- Accessibility: ARIA labels are set on creation and updated with `updateSelectedColor()`; titles localized via `L10n`.
- UI state: `beforeCloseHandler()` ensures mode switch and button visibility are restored to defaults.

## Desired Outputs

User-facing
- Two color pickers in the ribbon: one for font color and one for fill color.
- Compact palette UI by default with an option for a full color picker (`More Colors`).
- Immediate application of selected color to the current selection; visual selected-color indicator on the split button.
- Accessible labels for screen readers describing the control and the current color.

System-level
- Events and notifications:
  - `beforeRibbonCreate` → triggers `render()`.
  - `parent.notify(setCellFormat, SetCellFormatArgs)` → applied to workbook formatting logic and integrated with action/update pipeline (undo/redo expected to be handled by `setCellFormat` flow).
  - `destroyRibbonComponents`, `spreadsheetDestroyed` → trigger `destroy()`.

- DOM and CSS hooks:
  - Container ids: `${id}_font_color_picker`, `${id}_fill_color_picker`.
  - Picker popup CSS class: `e-spreadsheet-color-popup`.
  - Selected color indicator: `.e-selected-color` inside picker sibling; split button class: `.e-split-colorpicker`.
  - Icon classes added: `e-icons`, `e-font-color`, `e-fill-color` on the selected-color element.

- Integration contracts:
  - Uses localization service `locale` (via `serviceLocator`) to fetch labels.
  - Calls `setCellFormat` notification with `onActionUpdate: true` so formatting updates integrate with the workbook action pipeline.
  - Uses `ColorPickerComponent` API: `getValue()`, `setProperties()` to revert or adjust state.

## Implementation Notes (short)
- Keep `setCellFormat` as the single source of truth for applying color changes (the color picker only notifies).
- Maintain accessible ARIA text through `updateSelectedColor()` whenever programmatically changing picker state.
- Always call `destroy()` during ribbon or spreadsheet teardown to prevent memory leaks.

---