| 1 | /**
|
| 2 | * @license Copyright (c) 2003-2024, CKSource Holding sp. z o.o. All rights reserved.
|
| 3 | * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
|
| 4 | */
|
| 5 | /**
|
| 6 | * @module heading/headingconfig
|
| 7 | */
|
| 8 | import type { ArrayOrItem } from 'ckeditor5/src/utils.js';
|
| 9 | import type { MatcherPattern, ViewElementDefinition } from 'ckeditor5/src/engine.js';
|
| 10 | /**
|
| 11 | * The configuration of the heading feature.
|
| 12 | * The option is used by the {@link module:heading/headingediting~HeadingEditing} feature.
|
| 13 | *
|
| 14 | * ```ts
|
| 15 | * ClassicEditor
|
| 16 | * .create( {
|
| 17 | * heading: ... // Heading feature config.
|
| 18 | * } )
|
| 19 | * .then( ... )
|
| 20 | * .catch( ... );
|
| 21 | * ```
|
| 22 | *
|
| 23 | * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
|
| 24 | */
|
| 25 | export interface HeadingConfig {
|
| 26 | /**
|
| 27 | * The available heading options.
|
| 28 | *
|
| 29 | * The default value is:
|
| 30 | * ```ts
|
| 31 | * const headingConfig = {
|
| 32 | * options: [
|
| 33 | * { model: 'paragraph', title: 'Paragraph', class: 'ck-heading_paragraph' },
|
| 34 | * { model: 'heading1', view: 'h2', title: 'Heading 1', class: 'ck-heading_heading1' },
|
| 35 | * { model: 'heading2', view: 'h3', title: 'Heading 2', class: 'ck-heading_heading2' },
|
| 36 | * { model: 'heading3', view: 'h4', title: 'Heading 3', class: 'ck-heading_heading3' }
|
| 37 | * ]
|
| 38 | * };
|
| 39 | * ```
|
| 40 | *
|
| 41 | * It defines 3 levels of headings. In the editor model they will use `heading1`, `heading2`, and `heading3` elements.
|
| 42 | * Their respective view elements (so the elements output by the editor) will be: `h2`, `h3`, and `h4`. This means that
|
| 43 | * if you choose "Heading 1" in the headings dropdown the editor will turn the current block to `<heading1>` in the model
|
| 44 | * which will result in rendering (and outputting to data) the `<h2>` element.
|
| 45 | *
|
| 46 | * The `title` and `class` properties will be used by the `headings` dropdown to render available options.
|
| 47 | * Usually, the first option in the headings dropdown is the "Paragraph" option, hence it's also defined on the list.
|
| 48 | * However, you don't need to define its view representation because it's handled by
|
| 49 | * the {@link module:paragraph/paragraph~Paragraph} feature (which is required by
|
| 50 | * the {@link module:heading/headingediting~HeadingEditing} feature).
|
| 51 | *
|
| 52 | * You can **read more** about configuring heading levels and **see more examples** in
|
| 53 | * the {@glink features/headings Headings} guide.
|
| 54 | *
|
| 55 | * Note: In the model you should always start from `heading1`, regardless of how the headings are represented in the view.
|
| 56 | * That's assumption is used by features like {@link module:autoformat/autoformat~Autoformat} to know which element
|
| 57 | * they should use when applying the first level heading.
|
| 58 | *
|
| 59 | * The defined headings are also available as values passed to the `'heading'` command under their model names.
|
| 60 | * For example, the below code will apply `<heading1>` to the current selection:
|
| 61 | *
|
| 62 | * ```ts
|
| 63 | * editor.execute( 'heading', { value: 'heading1' } );
|
| 64 | * ```
|
| 65 | */
|
| 66 | options?: Array<HeadingOption>;
|
| 67 | }
|
| 68 | /**
|
| 69 | * Heading option descriptor.
|
| 70 | */
|
| 71 | export type HeadingOption = HeadingElementOption | HeadingParagraphOption;
|
| 72 | export interface HeadingElementOption {
|
| 73 | /**
|
| 74 | * Name of the model element to convert.
|
| 75 | */
|
| 76 | model: 'heading1' | 'heading2' | 'heading3' | 'heading4' | 'heading5' | 'heading6' | `heading${string}` & Record<never, never>;
|
| 77 | /**
|
| 78 | * Definition of a view element to convert from/to.
|
| 79 | */
|
| 80 | view: ViewElementDefinition;
|
| 81 | /**
|
| 82 | * The user-readable title of the option.
|
| 83 | */
|
| 84 | title: string;
|
| 85 | /**
|
| 86 | * The class which will be added to the dropdown item representing this option.
|
| 87 | */
|
| 88 | class: string;
|
| 89 | /**
|
| 90 | * Icon used by {@link module:heading/headingbuttonsui~HeadingButtonsUI}. It can be omitted when using the default configuration.
|
| 91 | */
|
| 92 | icon?: string;
|
| 93 | /**
|
| 94 | * An array with all matched elements that the view-to-model conversion should also accept.
|
| 95 | */
|
| 96 | upcastAlso?: ArrayOrItem<ViewElementDefinition | MatcherPattern>;
|
| 97 | }
|
| 98 | export interface HeadingParagraphOption {
|
| 99 | /**
|
| 100 | * Name of the model element to convert.
|
| 101 | */
|
| 102 | model: 'paragraph';
|
| 103 | /**
|
| 104 | * The user-readable title of the option.
|
| 105 | */
|
| 106 | title: string;
|
| 107 | /**
|
| 108 | * The class which will be added to the dropdown item representing this option.
|
| 109 | * */
|
| 110 | class: string;
|
| 111 | /**
|
| 112 | * Icon used by {@link module:heading/headingbuttonsui~HeadingButtonsUI}. It can be omitted when using the default configuration.
|
| 113 | */
|
| 114 | icon?: string;
|
| 115 | /**
|
| 116 | * An array with all matched elements that the view-to-model conversion should also accept.
|
| 117 | */
|
| 118 | upcastAlso?: ArrayOrItem<ViewElementDefinition | MatcherPattern>;
|
| 119 | }
|