Heading Editing Engine

/**
 * The headings engine feature. Handles switching between block formats - headings and paragraphs.
 */
class HeadingEditing extends Plugin {
    /** Plugin name identifier */
    static readonly pluginName: 'HeadingEditing';
    
    /** Indicates this is an official CKEditor 5 plugin */
    static readonly isOfficialPlugin: true;
    
    /** Required plugins that are automatically loaded */
    static readonly requires: [typeof Paragraph];
    
    /** Editor instance constructor parameter */
    constructor(editor: Editor);
    
    /** 
     * Registers model elements, conversion, and heading command.
     * Sets up the heading model elements, converters, and registers the heading command.
     */
    init(): void;
    
    /**
     * Sets up Enter key behavior for headings.
     * Configures what happens when Enter is pressed in heading elements.
     */
    afterInit(): void;
}

// Direct plugin usage (usually not needed as it's loaded by Heading plugin)
import { HeadingEditing } from '@ckeditor/ckeditor5-heading';

ClassicEditor.create(document.querySelector('#editor'), {
    plugins: [HeadingEditing, /* other required plugins */]
});

// Access the plugin instance
const headingEditing = editor.plugins.get('HeadingEditing');

// The plugin automatically registers heading model elements:
// - heading1, heading2, heading3, heading4, heading5, heading6
// - Based on configuration options

// Default model elements registered:
// - heading1 (maps to <h2> by default)
// - heading2 (maps to <h3> by default)  
// - heading3 (maps to <h4> by default)

// Custom model elements can be registered via configuration:
const config = {
    heading: {
        options: [
            { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
            { model: 'heading1', view: 'h1', title: 'Title', class: 'ck-heading_heading1' },
            { model: 'customHeading', view: 'h5', title: 'Custom', class: 'ck-heading_custom' }
        ]
    }
};

// Example of how conversion works internally:
// Model: <heading1>My Title</heading1>
// View:  <h2>My Title</h2>

// Custom view mapping:
{
    model: 'heading1',
    view: { name: 'h1', classes: 'custom-title' },
    title: 'Main Title',
    class: 'ck-heading_main'
}
// Model: <heading1>My Title</heading1>  
// View:  <h1 class="custom-title">My Title</h1>

// Example behavior:
// Before: <heading1>My Title|</heading1>
// After pressing Enter: 
// <heading1>My Title</heading1>
// <paragraph>|</paragraph>

// Before: <heading1>|</heading1> (empty heading)
// After pressing Enter:
// <paragraph>|</paragraph>

// The HeadingCommand is registered as 'heading'
const headingCommand = editor.commands.get('heading');

// Execute to apply headings
editor.execute('heading', { value: 'heading1' });
editor.execute('heading', { value: 'heading2' });
editor.execute('heading', { value: 'paragraph' });

// Check current state
console.log(headingCommand.value); // Current heading level or false
console.log(headingCommand.isEnabled); // Whether command can be executed

// Headings are registered as block elements that:
// - Inherit from $block
// - Allow $text content
// - Can contain inline formatting
// - Are allowed in root and other block containers

// Schema example (internal):
schema.register('heading1', {
    inheritAllFrom: '$block'
});