@syncfusion/ej2-spreadsheet/docs/skills/integration/ribbon.md

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

# Ribbon Module data flow

## What It Does
Provides the spreadsheet toolbar and file menu UI, wiring user actions into spreadsheet commands and exposing a reusable Ribbon component. The spreadsheet-layer `Ribbon` composes and configures the generic `Ribbon` component to render tabs, menus, dropdowns and specialized controls (number-format, chart insert, comments, merge, protection). The core ribbon component implements the generic Tab/Toolbar/Menu behaviors used across platforms.

Primary implementation files: `src/spreadsheet/integrations/ribbon.ts` (Spreadsheet-specific wiring and features) and `src/ribbon/ribbon.ts` (Core reusable Ribbon component).

## Entry Points (UI - Spreadsheet layer)
**Class:** `Ribbon` (in `src/spreadsheet/integrations/ribbon.ts`)
- Responsibilities:
  - Build ribbon menu and tab items (`getRibbonMenuItems()`, `getRibbonItems()`), including file menu, Home/Insert/Formulas/Data/Review/View tabs.
  - Create and attach the core `Ribbon` component via `createRibbon()` and populate toolbar templates (buttons, DDBs, SplitButtons).
  - Construct domain-specific dropdowns and dialogs: number-format DDB (`getNumFormatDDB()` / `renderCustomFormatDialog()`), chart DDBs, comment/note controls, merge/unmerge flows, protect dialogs and file open/save flows.
  - React to spreadsheet state changes to refresh ribbon UI: `refreshRibbonContent()`, `refreshHomeTabContent()`, `refreshTextAlign()`, `refreshNumFormatSelection()`, `refreshToggleBtn()` and `refreshFontNameSelection()`.
  - Handle user interactions: `fileMenuItemSelect()`, `toolbarClicked()`, `selectCalcOptions()`, `applyNumFormat()` and many menu selection handlers that translate UI actions to `parent.notify(...)` calls or public APIs.
  - Lifecycle: `addEventListener()`/`removeEventListener()` register for parent notifications; `destroy()` cleans up created UI components and DOM.

## Entry Points (Core)
**Class:** `Ribbon` (in `src/ribbon/ribbon.ts`) — core component
- Responsibilities:
  - Generic rendering of toolbar and tab structures (`renderRibbon()`, `render()`), file menu (`initMenu()`), and tab navigation.
  - Expose properties and events used by callers: `menuItems`, `items`, `selectedTab`, `clicked`, `fileMenuItemSelect`, `beforeOpen`, `selecting`, `created`, `expandCollapse`.
  - Provide programmatic APIs for consumers: `enableMenuItems()`, `hideTabs()`, `addTabs()`, `addToolbarItems()`, `enableItems()`, `hideToolbarItems()`, `getModuleName()`, `getPersistData()`.
  - Implement keyboard/ARIA interactions, expand/collapse behavior and support for mobile/portal templates via `renderRibbon()` and `ribbonExpandCollapse()`.
  - Lifecycle and cleanup: `destroy()` removes child components (Menu, Toolbar, Tab) and empties DOM.

## ASCII Core Logic Flow
Create ribbon config (spreadsheet) → instantiate core `Ribbon` → core renders Tab & Toolbar → user interacts (click/select) → core emits events (`clicked`, `fileMenuItemSelect`, `selecting`) → Spreadsheet `Ribbon` handlers translate to spreadsheet actions (`parent.notify`, `parent.open`, `applyNumFormat`, `merge`) → Spreadsheet updates model or UI → Spreadsheet calls `refreshRibbonContent()` or notifies core to update visual state

## Operations (functions & responsibilities)
- `getRibbonMenuItems()` / `getRibbonItems()` (Spreadsheet)
  - Build localized menu and toolbar item models; include unique ids wired to handlers.

- `createRibbon()` (Spreadsheet)
  - Instantiate core `Ribbon` with items and event callbacks; attach to DOM.

- `getNumFormatDDB()` and `renderCustomFormatDialog()` (Spreadsheet)
  - Request localized/default formats via `parent.notify(localizedFormatAction, eventArgs)`, render preview UI, call `applyNumFormat()`.

- `toolbarClicked()` / `fileMenuItemSelect()` (Spreadsheet)
  - Map UI events to spreadsheet commands (Open/Save/Insert/Format) and fire appropriate `parent` notifications.

- `refreshRibbonContent()` / `refreshHomeTabContent()` (Spreadsheet)
  - Update the ribbon state based on active cell/indexes, protection, selection and sheet features.

- `renderRibbon()` / `initMenu()` / `getTabItems()` (Core)
  - Compose Menu/Toolbar/Tab components, bind events and handle expand/collapse and mobile behaviors.

- `enableMenuItems()`, `hideTabs()`, `addTabs()` (Core)
  - Public APIs used by the spreadsheet layer to dynamically alter ribbon content and state.

## Validation & Safety
- Permission checks: `beforeFileMenuItemRender()` and item-creation code disable or hide menu items when `parent.allowOpen`, `parent.allowSave`, `parent.allowPrint` are false.
- Lifecycle guards: `destroy()` and `removeEventListener()` ensure event handlers and created components are released; use `isDestroyed` checks before removing listeners.
- Cancelable events: `beforeOpen` and `selecting` allow hosts to cancel or alter behavior before UI actions proceed.
- Mobile/responsive: code paths check `parent.isMobileView()` and adjust templates and button layouts.
- Localization: use `serviceLocator.getService(locale)` and `L10n.getConstant()` to render localized labels; numeric formats are requested from `localizedFormatAction` to avoid hard-coded strings.

## Desired Outputs
- User-facing: fully interactive ribbon with correct enable/disable states, localized labels, dynamic insertion/removal of tabs (e.g., Chart Design), single-entry points for file operations and format dialogs, and keyboard accessible menus.
- System-level: events triggered back to core (e.g., `parent.notify(enableToolbarItems, ...)`) and model updates applied consistently; minimal DOM thrash by batching UI refreshes via `refreshRibbonContent()`.

## Implementation Notes (short)
- Maintain strict separation: the core `Ribbon` is UI-only and must not embed domain logic; domain decisions (format lists, protection rules, chart availability) belong in `src/spreadsheet/integrations/ribbon.ts`.
- Query localized formats through the established notify channel (`localizedFormatAction`) rather than embedding format lists; this keeps ribbon independent of format localization logic.
- When updating many ribbon controls in response to selection changes, use `refreshRibbonContent()` to group updates and avoid re-creating component instances.
- Ensure every created child UI component (DropDownButton, SplitButton, Menu) is destroyed via `destroyComponent()` or removed in `destroy()` to avoid leaks.
- Keep menu item ids unique (use parent element id prefix) so handlers map deterministically to actions.

## Key Events & Hooks
- spreadsheet → ribbon: `beforeRibbonCreate`, `localizedFormatAction`, `enableToolbarItems`, `refreshRibbonContent` (via `parent.notify`)
- ribbon → spreadsheet: `fileMenuItemSelect`, `clicked`, `selectFormat` events forwarded to spreadsheet handlers.

---