# Tune Block Plugin

This plugin adds a popup menu for block-level elements, allowing users to quickly modify, move, align, or change the tag of selected blocks. The popup appears when a user clicks on a block element, providing contextual options for that specific element type.

## Features

- Adds a popup menu for block-level elements
- Allows moving blocks up and down
- Provides options to change block types (e.g., convert paragraph to heading)
- Supports custom buttons and actions
- Can be configured differently for each HTML tag

## Installation

If you are using a fat build of the editor, then the plugin is already included in it.
If you are using the slim build, then you need to enable it manually:

```js
Jodit.make('#editor', {
    extraPlugins: ['tune-block']
});
```

## Options

### tuneBlock.popup

- Type: `IDictionary<Array<IControlType | string>>`
- Default: See below

This option allows you to specify which buttons should appear in the popup menu for each HTML tag. You can use predefined buttons, buttons from other plugins, or create custom buttons.

Default configuration:
```js
{
    p: ['tune.up', 'tune.remove', 'tune.down'],
    table: ['tune.up', 'tune.remove', 'tune.down'],
    img: ['tune.up', 'tune.remove', 'tune.down'],
    blockquote: ['tune.up', 'tune.remove', 'tune.down'],
    div: ['tune.up', 'tune.remove', 'tune.down'],
    pre: ['tune.editPre', 'tune.up', 'tune.remove', 'tune.down'],
    h1: ['tune.h1', 'tune.h2', 'tune.h3', '\n', 'tune.h4', 'tune.h5', 'tune.h6', '\n', 'tune.up', 'tune.remove', 'tune.down'],
    h2: ['tune.h1', 'tune.h2', 'tune.h3', '\n', 'tune.h4', 'tune.h5', 'tune.h6', '\n', 'tune.up', 'tune.remove', 'tune.down'],
    h3: ['tune.h1', 'tune.h2', 'tune.h3', '\n', 'tune.h4', 'tune.h5', 'tune.h6', '\n', 'tune.up', 'tune.remove', 'tune.down'],
    h4: ['tune.h1', 'tune.h2', 'tune.h3', '\n', 'tune.h4', 'tune.h5', 'tune.h6', '\n', 'tune.up', 'tune.remove', 'tune.down'],
    h5: ['tune.h1', 'tune.h2', 'tune.h3', '\n', 'tune.h4', 'tune.h5', 'tune.h6', '\n', 'tune.up', 'tune.remove', 'tune.down'],
    h6: ['tune.h1', 'tune.h2', 'tune.h3', '\n', 'tune.h4', 'tune.h5', 'tune.h6', '\n', 'tune.up', 'tune.remove', 'tune.down']
}
```

## Built-in Buttons

The plugin provides several built-in buttons that can be used in the popup menu:

- `tune.up` - Move block up
- `tune.remove` - Delete block
- `tune.down` - Move block down
- `tune.h1` - Convert block to Heading 1
- `tune.h2` - Convert block to Heading 2
- `tune.h3` - Convert block to Heading 3
- `tune.h4` - Convert block to Heading 4
- `tune.h5` - Convert block to Heading 5
- `tune.h6` - Convert block to Heading 6
- `tune.editPre` - Edit pre block (works with the paste-code plugin)

## Usage Examples

### Basic Configuration

```js
Jodit.make('#editor', {
    tuneBlock: {
        popup: {
            p: Jodit.atom(['align', 'tune.up', 'tune.remove', 'tune.down'])
        }
    }
});
```

### Using Buttons from Other Plugins

You can include buttons from other plugins in the tune block popup:

```js
Jodit.make('#editor', {
    tuneBlock: {
        popup: {
            table: Jodit.atom(['brush', 'image', 'align'])
        }
    }
});
```

### Adding Custom Buttons

You can add your own custom buttons to the popup menu:

```js
Jodit.make('#editor', {
    tuneBlock: {
        popup: {
            table: [
                {
                    icon: 'brush',
                    name: 'Brush table in red',
                    exec(editor, tableElm) {
                        tableElm.querySelectorAll('td').forEach((td) => {
                            td.style.backgroundColor = 'red';
                        });

                        editor.e.fire('afterExecTune.tune'); // close the tuner
                    }
                }
            ]
        }
    }
});
```

### Disabling the Plugin for Specific Tags

To disable the tune block popup for a specific tag, set its value to null:

```js
Jodit.make('#editor', {
    tuneBlock: {
        popup: {
            h3: null // No tune-block will be shown for H3 tag
        }
    }
});
```

### Disabling the Plugin Completely

To disable the plugin for all tags:

```js
Jodit.make('#editor', {
    tuneBlock: {
        popup: Jodit.atom({}) // We erase all default values
    }
});
```

Alternatively, you can disable the plugin using the `disablePlugins` option:

```jsx
import JoditEditor from 'jodit-react';

<JoditEditor config={{ disablePlugins: ['tune-block'] }} />;
```

## Advanced Configuration

### Combining Default and Custom Buttons

You can combine default buttons with your custom buttons:

```js
Jodit.make('#editor', {
    tuneBlock: {
        popup: {
            p: [
                'tune.up',
                {
                    icon: 'pencil',
                    name: 'Add Comment',
                    exec(editor, element) {
                        const comment = prompt('Enter your comment:');
                        if (comment) {
                            element.dataset.comment = comment;
                        }
                        editor.e.fire('afterExecTune.tune');
                    }
                },
                'tune.down'
            ]
        }
    }
});
```

### Creating a Custom Layout with Line Breaks

You can use the string `'\n'` to create line breaks in the popup menu:

```js
Jodit.make('#editor', {
    tuneBlock: {
        popup: {
            p: [
                'tune.h1', 'tune.h2', 'tune.h3',
                '\n',
                'align',
                '\n',
                'tune.up', 'tune.remove', 'tune.down'
            ]
        }
    }
});
```

## API Reference

### Configuration Interface

```typescript
interface TuneBlockConfig {
    popup: IDictionary<Array<IControlType | string>>;  // Popup menu configuration per tag
}
```

### Control Type Interface

Custom buttons in the popup menu should implement the following interface:

```typescript
interface IControlType {
    icon?: string;                                         // Button icon (SVG or icon name)
    name?: string;                                         // Button tooltip/name
    isActive?: (editor: IJodit, button: IButton) => boolean;  // Check if button is active
    exec?: (editor: IJodit, target: HTMLElement) => void | true;  // Execute button action
}
```

### Built-in Control Names

The following control names are available by default:

- `tune.up` - Move block up
- `tune.remove` - Delete block
- `tune.down` - Move block down
- `tune.h1` through `tune.h6` - Convert block to heading level 1-6
- `tune.editPre` - Edit code block (requires paste-code plugin)

### Events

The plugin fires the following events:

```typescript
editor.e.fire('afterExecTune.tune');  // Fire this event to close the tune block popup
```

## How It Works

1. When a user clicks on a block-level element, the plugin checks if there are any popup options defined for that tag
2. If options are found, a popup menu is displayed near the element
3. When a button in the popup is clicked, its associated action is executed on the target element
4. After the action is complete, the popup is automatically closed

This plugin enhances the editing experience by providing quick access to common block-level operations without requiring users to navigate through menus or use keyboard shortcuts.