@ckeditor/ckeditor5-engine 35.0.1 → 35.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (124) hide show
  1. package/CHANGELOG.md +4 -4
  2. package/package.json +30 -24
  3. package/src/controller/datacontroller.js +467 -561
  4. package/src/controller/editingcontroller.js +168 -204
  5. package/src/conversion/conversion.js +541 -565
  6. package/src/conversion/conversionhelpers.js +24 -28
  7. package/src/conversion/downcastdispatcher.js +457 -686
  8. package/src/conversion/downcasthelpers.js +1583 -1965
  9. package/src/conversion/mapper.js +518 -707
  10. package/src/conversion/modelconsumable.js +240 -283
  11. package/src/conversion/upcastdispatcher.js +372 -718
  12. package/src/conversion/upcasthelpers.js +707 -818
  13. package/src/conversion/viewconsumable.js +524 -581
  14. package/src/dataprocessor/basichtmlwriter.js +12 -16
  15. package/src/dataprocessor/dataprocessor.js +5 -0
  16. package/src/dataprocessor/htmldataprocessor.js +100 -116
  17. package/src/dataprocessor/htmlwriter.js +1 -18
  18. package/src/dataprocessor/xmldataprocessor.js +116 -137
  19. package/src/dev-utils/model.js +260 -352
  20. package/src/dev-utils/operationreplayer.js +106 -126
  21. package/src/dev-utils/utils.js +34 -51
  22. package/src/dev-utils/view.js +632 -753
  23. package/src/index.js +0 -11
  24. package/src/model/batch.js +111 -127
  25. package/src/model/differ.js +988 -1233
  26. package/src/model/document.js +340 -449
  27. package/src/model/documentfragment.js +327 -364
  28. package/src/model/documentselection.js +996 -1189
  29. package/src/model/element.js +306 -410
  30. package/src/model/history.js +224 -262
  31. package/src/model/item.js +5 -0
  32. package/src/model/liveposition.js +84 -145
  33. package/src/model/liverange.js +108 -185
  34. package/src/model/markercollection.js +379 -480
  35. package/src/model/model.js +883 -1034
  36. package/src/model/node.js +419 -463
  37. package/src/model/nodelist.js +176 -201
  38. package/src/model/operation/attributeoperation.js +153 -182
  39. package/src/model/operation/detachoperation.js +64 -83
  40. package/src/model/operation/insertoperation.js +135 -166
  41. package/src/model/operation/markeroperation.js +114 -140
  42. package/src/model/operation/mergeoperation.js +163 -191
  43. package/src/model/operation/moveoperation.js +157 -187
  44. package/src/model/operation/nooperation.js +28 -38
  45. package/src/model/operation/operation.js +106 -125
  46. package/src/model/operation/operationfactory.js +30 -34
  47. package/src/model/operation/renameoperation.js +109 -135
  48. package/src/model/operation/rootattributeoperation.js +155 -188
  49. package/src/model/operation/splitoperation.js +196 -232
  50. package/src/model/operation/transform.js +1833 -2204
  51. package/src/model/operation/utils.js +140 -204
  52. package/src/model/position.js +980 -1053
  53. package/src/model/range.js +910 -1028
  54. package/src/model/rootelement.js +77 -97
  55. package/src/model/schema.js +1189 -1835
  56. package/src/model/selection.js +745 -862
  57. package/src/model/text.js +90 -114
  58. package/src/model/textproxy.js +204 -240
  59. package/src/model/treewalker.js +316 -397
  60. package/src/model/typecheckable.js +16 -0
  61. package/src/model/utils/autoparagraphing.js +32 -44
  62. package/src/model/utils/deletecontent.js +334 -418
  63. package/src/model/utils/findoptimalinsertionrange.js +25 -36
  64. package/src/model/utils/getselectedcontent.js +96 -118
  65. package/src/model/utils/insertcontent.js +757 -773
  66. package/src/model/utils/insertobject.js +96 -119
  67. package/src/model/utils/modifyselection.js +120 -158
  68. package/src/model/utils/selection-post-fixer.js +153 -201
  69. package/src/model/writer.js +1305 -1474
  70. package/src/view/attributeelement.js +189 -225
  71. package/src/view/containerelement.js +75 -85
  72. package/src/view/document.js +172 -215
  73. package/src/view/documentfragment.js +200 -249
  74. package/src/view/documentselection.js +338 -367
  75. package/src/view/domconverter.js +1370 -1617
  76. package/src/view/downcastwriter.js +1747 -2076
  77. package/src/view/editableelement.js +81 -97
  78. package/src/view/element.js +739 -890
  79. package/src/view/elementdefinition.js +5 -0
  80. package/src/view/emptyelement.js +82 -92
  81. package/src/view/filler.js +35 -50
  82. package/src/view/item.js +5 -0
  83. package/src/view/matcher.js +260 -559
  84. package/src/view/node.js +274 -360
  85. package/src/view/observer/arrowkeysobserver.js +19 -28
  86. package/src/view/observer/bubblingemittermixin.js +120 -263
  87. package/src/view/observer/bubblingeventinfo.js +47 -55
  88. package/src/view/observer/clickobserver.js +7 -13
  89. package/src/view/observer/compositionobserver.js +14 -24
  90. package/src/view/observer/domeventdata.js +57 -67
  91. package/src/view/observer/domeventobserver.js +40 -64
  92. package/src/view/observer/fakeselectionobserver.js +81 -96
  93. package/src/view/observer/focusobserver.js +45 -61
  94. package/src/view/observer/inputobserver.js +7 -13
  95. package/src/view/observer/keyobserver.js +17 -27
  96. package/src/view/observer/mouseobserver.js +7 -14
  97. package/src/view/observer/mutationobserver.js +220 -315
  98. package/src/view/observer/observer.js +81 -102
  99. package/src/view/observer/selectionobserver.js +199 -246
  100. package/src/view/observer/tabobserver.js +23 -36
  101. package/src/view/placeholder.js +128 -173
  102. package/src/view/position.js +350 -401
  103. package/src/view/range.js +453 -513
  104. package/src/view/rawelement.js +85 -112
  105. package/src/view/renderer.js +874 -1018
  106. package/src/view/rooteditableelement.js +80 -90
  107. package/src/view/selection.js +608 -689
  108. package/src/view/styles/background.js +43 -44
  109. package/src/view/styles/border.js +220 -276
  110. package/src/view/styles/margin.js +8 -17
  111. package/src/view/styles/padding.js +8 -16
  112. package/src/view/styles/utils.js +127 -160
  113. package/src/view/stylesmap.js +728 -905
  114. package/src/view/text.js +102 -126
  115. package/src/view/textproxy.js +144 -170
  116. package/src/view/treewalker.js +383 -479
  117. package/src/view/typecheckable.js +19 -0
  118. package/src/view/uielement.js +166 -187
  119. package/src/view/upcastwriter.js +395 -449
  120. package/src/view/view.js +569 -664
  121. package/src/dataprocessor/dataprocessor.jsdoc +0 -64
  122. package/src/model/item.jsdoc +0 -14
  123. package/src/view/elementdefinition.jsdoc +0 -59
  124. package/src/view/item.jsdoc +0 -14
@@ -2,937 +2,760 @@
2
2
  * @license Copyright (c) 2003-2022, CKSource Holding sp. z o.o. All rights reserved.
3
3
  * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
4
4
  */
5
-
6
5
  /**
7
6
  * @module engine/view/stylesmap
8
7
  */
9
-
10
8
  import { get, isObject, merge, set, unset } from 'lodash-es';
11
-
12
9
  /**
13
10
  * Styles map. Allows handling (adding, removing, retrieving) a set of style rules (usually, of an element).
14
11
  *
15
12
  * The styles map is capable of normalizing style names so e.g. the following operations are possible:
16
13
  */
17
14
  export default class StylesMap {
18
- /**
19
- * Creates Styles instance.
20
- *
21
- * @param {module:engine/view/stylesmap~StylesProcessor} styleProcessor
22
- */
23
- constructor( styleProcessor ) {
24
- /**
25
- * Keeps an internal representation of styles map. Normalized styles are kept as object tree to allow unified modification and
26
- * value access model using lodash's get, set, unset, etc methods.
27
- *
28
- * When no style processor rules are defined it acts as simple key-value storage.
29
- *
30
- * @private
31
- * @type {Object}
32
- */
33
- this._styles = {};
34
-
35
- /**
36
- * An instance of the {@link module:engine/view/stylesmap~StylesProcessor}.
37
- *
38
- * @private
39
- * @member {module:engine/view/stylesmap~StylesProcessor}
40
- */
41
- this._styleProcessor = styleProcessor;
42
- }
43
-
44
- /**
45
- * Returns true if style map has no styles set.
46
- *
47
- * @type {Boolean}
48
- */
49
- get isEmpty() {
50
- const entries = Object.entries( this._styles );
51
- const from = Array.from( entries );
52
-
53
- return !from.length;
54
- }
55
-
56
- /**
57
- * Number of styles defined.
58
- *
59
- * @type {Number}
60
- */
61
- get size() {
62
- if ( this.isEmpty ) {
63
- return 0;
64
- }
65
-
66
- return this.getStyleNames().length;
67
- }
68
-
69
- /**
70
- * Set styles map to a new value.
71
- *
72
- * styles.setTo( 'border:1px solid blue;margin-top:1px;' );
73
- *
74
- * @param {String} inlineStyle
75
- */
76
- setTo( inlineStyle ) {
77
- this.clear();
78
-
79
- const parsedStyles = Array.from( parseInlineStyles( inlineStyle ).entries() );
80
-
81
- for ( const [ key, value ] of parsedStyles ) {
82
- this._styleProcessor.toNormalizedForm( key, value, this._styles );
83
- }
84
- }
85
-
86
- /**
87
- * Checks if a given style is set.
88
- *
89
- * styles.setTo( 'margin-left:1px;' );
90
- *
91
- * styles.has( 'margin-left' ); // -> true
92
- * styles.has( 'padding' ); // -> false
93
- *
94
- * **Note**: This check supports normalized style names.
95
- *
96
- * // Enable 'margin' shorthand processing:
97
- * editor.data.addStyleProcessorRules( addMarginRules );
98
- *
99
- * styles.setTo( 'margin:2px;' );
100
- *
101
- * styles.has( 'margin' ); // -> true
102
- * styles.has( 'margin-top' ); // -> true
103
- * styles.has( 'margin-left' ); // -> true
104
- *
105
- * styles.remove( 'margin-top' );
106
- *
107
- * styles.has( 'margin' ); // -> false
108
- * styles.has( 'margin-top' ); // -> false
109
- * styles.has( 'margin-left' ); // -> true
110
- *
111
- * @param {String} name Style name.
112
- * @returns {Boolean}
113
- */
114
- has( name ) {
115
- if ( this.isEmpty ) {
116
- return false;
117
- }
118
-
119
- const styles = this._styleProcessor.getReducedForm( name, this._styles );
120
-
121
- const propertyDescriptor = styles.find( ( [ property ] ) => property === name );
122
-
123
- // Only return a value if it is set;
124
- return Array.isArray( propertyDescriptor );
125
- }
126
-
127
- /**
128
- * Sets a given style.
129
- *
130
- * Can insert one by one:
131
- *
132
- * styles.set( 'color', 'blue' );
133
- * styles.set( 'margin-right', '1em' );
134
- *
135
- * or many styles at once:
136
- *
137
- * styles.set( {
138
- * color: 'blue',
139
- * 'margin-right': '1em'
140
- * } );
141
- *
142
- * ***Note**:* This method uses {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules
143
- * enabled style processor rules} to normalize passed values.
144
- *
145
- * // Enable 'margin' shorthand processing:
146
- * editor.data.addStyleProcessorRules( addMarginRules );
147
- *
148
- * styles.set( 'margin', '2px' );
149
- *
150
- * The above code will set margin to:
151
- *
152
- * styles.getNormalized( 'margin' );
153
- * // -> { top: '2px', right: '2px', bottom: '2px', left: '2px' }
154
- *
155
- * Which makes it possible to retrieve a "sub-value":
156
- *
157
- * styles.get( 'margin-left' ); // -> '2px'
158
- *
159
- * Or modify it:
160
- *
161
- * styles.remove( 'margin-left' );
162
- *
163
- * styles.getNormalized( 'margin' ); // -> { top: '1px', bottom: '1px', right: '1px' }
164
- * styles.toString(); // -> 'margin-bottom:1px;margin-right:1px;margin-top:1px;'
165
- *
166
- * This method also allows to set normalized values directly (if a particular styles processor rule was enabled):
167
- *
168
- * styles.set( 'border-color', { top: 'blue' } );
169
- * styles.set( 'margin', { right: '2em' } );
170
- *
171
- * styles.toString(); // -> 'border-color-top:blue;margin-right:2em;'
172
- *
173
- * @param {String|Object} nameOrObject Style property name or object with multiple properties.
174
- * @param {String|Object} valueOrObject Value to set.
175
- */
176
- set( nameOrObject, valueOrObject ) {
177
- if ( isObject( nameOrObject ) ) {
178
- for ( const [ key, value ] of Object.entries( nameOrObject ) ) {
179
- this._styleProcessor.toNormalizedForm( key, value, this._styles );
180
- }
181
- } else {
182
- this._styleProcessor.toNormalizedForm( nameOrObject, valueOrObject, this._styles );
183
- }
184
- }
185
-
186
- /**
187
- * Removes given style.
188
- *
189
- * styles.setTo( 'background:#f00;margin-right:2px;' );
190
- *
191
- * styles.remove( 'background' );
192
- *
193
- * styles.toString(); // -> 'margin-right:2px;'
194
- *
195
- * ***Note**:* This method uses {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules
196
- * enabled style processor rules} to normalize passed values.
197
- *
198
- * // Enable 'margin' shorthand processing:
199
- * editor.data.addStyleProcessorRules( addMarginRules );
200
- *
201
- * styles.setTo( 'margin:1px' );
202
- *
203
- * styles.remove( 'margin-top' );
204
- * styles.remove( 'margin-right' );
205
- *
206
- * styles.toString(); // -> 'margin-bottom:1px;margin-left:1px;'
207
- *
208
- * @param {String} name Style name.
209
- */
210
- remove( name ) {
211
- const path = toPath( name );
212
-
213
- unset( this._styles, path );
214
- delete this._styles[ name ];
215
-
216
- this._cleanEmptyObjectsOnPath( path );
217
- }
218
-
219
- /**
220
- * Returns a normalized style object or a single value.
221
- *
222
- * // Enable 'margin' shorthand processing:
223
- * editor.data.addStyleProcessorRules( addMarginRules );
224
- *
225
- * const styles = new Styles();
226
- * styles.setTo( 'margin:1px 2px 3em;' );
227
- *
228
- * styles.getNormalized( 'margin' );
229
- * // will log:
230
- * // {
231
- * // top: '1px',
232
- * // right: '2px',
233
- * // bottom: '3em',
234
- * // left: '2px' // normalized value from margin shorthand
235
- * // }
236
- *
237
- * styles.getNormalized( 'margin-left' ); // -> '2px'
238
- *
239
- * **Note**: This method will only return normalized styles if a style processor was defined.
240
- *
241
- * @param {String} name Style name.
242
- * @returns {Object|String|undefined}
243
- */
244
- getNormalized( name ) {
245
- return this._styleProcessor.getNormalized( name, this._styles );
246
- }
247
-
248
- /**
249
- * Returns a normalized style string. Styles are sorted by name.
250
- *
251
- * styles.set( 'margin' , '1px' );
252
- * styles.set( 'background', '#f00' );
253
- *
254
- * styles.toString(); // -> 'background:#f00;margin:1px;'
255
- *
256
- * **Note**: This method supports normalized styles if defined.
257
- *
258
- * // Enable 'margin' shorthand processing:
259
- * editor.data.addStyleProcessorRules( addMarginRules );
260
- *
261
- * styles.set( 'margin' , '1px' );
262
- * styles.set( 'background', '#f00' );
263
- * styles.remove( 'margin-top' );
264
- * styles.remove( 'margin-right' );
265
- *
266
- * styles.toString(); // -> 'background:#f00;margin-bottom:1px;margin-left:1px;'
267
- *
268
- * @returns {String}
269
- */
270
- toString() {
271
- if ( this.isEmpty ) {
272
- return '';
273
- }
274
-
275
- return this._getStylesEntries()
276
- .map( arr => arr.join( ':' ) )
277
- .sort()
278
- .join( ';' ) + ';';
279
- }
280
-
281
- /**
282
- * Returns property as a value string or undefined if property is not set.
283
- *
284
- * // Enable 'margin' shorthand processing:
285
- * editor.data.addStyleProcessorRules( addMarginRules );
286
- *
287
- * const styles = new Styles();
288
- * styles.setTo( 'margin:1px;' );
289
- * styles.set( 'margin-bottom', '3em' );
290
- *
291
- * styles.getAsString( 'margin' ); // -> 'margin: 1px 1px 3em;'
292
- *
293
- * Note, however, that all sub-values must be set for the longhand property name to return a value:
294
- *
295
- * const styles = new Styles();
296
- * styles.setTo( 'margin:1px;' );
297
- * styles.remove( 'margin-bottom' );
298
- *
299
- * styles.getAsString( 'margin' ); // -> undefined
300
- *
301
- * In the above scenario, it is not possible to return a `margin` value, so `undefined` is returned.
302
- * Instead, you should use:
303
- *
304
- * const styles = new Styles();
305
- * styles.setTo( 'margin:1px;' );
306
- * styles.remove( 'margin-bottom' );
307
- *
308
- * for ( const styleName of styles.getStyleNames() ) {
309
- * console.log( styleName, styles.getAsString( styleName ) );
310
- * }
311
- * // 'margin-top', '1px'
312
- * // 'margin-right', '1px'
313
- * // 'margin-left', '1px'
314
- *
315
- * In general, it is recommend to iterate over style names like in the example above. This way, you will always get all
316
- * the currently set style values. So, if all the 4 margin values would be set
317
- * the for-of loop above would yield only `'margin'`, `'1px'`:
318
- *
319
- * const styles = new Styles();
320
- * styles.setTo( 'margin:1px;' );
321
- *
322
- * for ( const styleName of styles.getStyleNames() ) {
323
- * console.log( styleName, styles.getAsString( styleName ) );
324
- * }
325
- * // 'margin', '1px'
326
- *
327
- * **Note**: To get a normalized version of a longhand property use the {@link #getNormalized `#getNormalized()`} method.
328
- *
329
- * @param {String} propertyName
330
- * @returns {String|undefined}
331
- */
332
- getAsString( propertyName ) {
333
- if ( this.isEmpty ) {
334
- return;
335
- }
336
-
337
- if ( this._styles[ propertyName ] && !isObject( this._styles[ propertyName ] ) ) {
338
- // Try return styles set directly - values that are not parsed.
339
- return this._styles[ propertyName ];
340
- }
341
-
342
- const styles = this._styleProcessor.getReducedForm( propertyName, this._styles );
343
-
344
- const propertyDescriptor = styles.find( ( [ property ] ) => property === propertyName );
345
-
346
- // Only return a value if it is set;
347
- if ( Array.isArray( propertyDescriptor ) ) {
348
- return propertyDescriptor[ 1 ];
349
- }
350
- }
351
-
352
- /**
353
- * Returns all style properties names as they would appear when using {@link #toString `#toString()`}.
354
- *
355
- * When `expand` is set to true and there's a shorthand style property set, it will also return all equivalent styles:
356
- *
357
- * stylesMap.setTo( 'margin: 1em' )
358
- *
359
- * will be expanded to:
360
- *
361
- * [ 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ]
362
- *
363
- * @param {Boolean} [expand=false] Expand shorthand style properties and all return equivalent style representations.
364
- * @returns {Array.<String>}
365
- */
366
- getStyleNames( expand = false ) {
367
- if ( this.isEmpty ) {
368
- return [];
369
- }
370
-
371
- if ( expand ) {
372
- return this._styleProcessor.getStyleNames( this._styles );
373
- }
374
-
375
- const entries = this._getStylesEntries();
376
-
377
- return entries.map( ( [ key ] ) => key );
378
- }
379
-
380
- /**
381
- * Removes all styles.
382
- */
383
- clear() {
384
- this._styles = {};
385
- }
386
-
387
- /**
388
- * Returns normalized styles entries for further processing.
389
- *
390
- * @private
391
- * @returns {Array.<module:engine/view/stylesmap~PropertyDescriptor>}
392
- */
393
- _getStylesEntries() {
394
- const parsed = [];
395
-
396
- const keys = Object.keys( this._styles );
397
-
398
- for ( const key of keys ) {
399
- parsed.push( ...this._styleProcessor.getReducedForm( key, this._styles ) );
400
- }
401
-
402
- return parsed;
403
- }
404
-
405
- /**
406
- * Removes empty objects upon removing an entry from internal object.
407
- *
408
- * @param {String} path
409
- * @private
410
- */
411
- _cleanEmptyObjectsOnPath( path ) {
412
- const pathParts = path.split( '.' );
413
- const isChildPath = pathParts.length > 1;
414
-
415
- if ( !isChildPath ) {
416
- return;
417
- }
418
-
419
- const parentPath = pathParts.splice( 0, pathParts.length - 1 ).join( '.' );
420
-
421
- const parentObject = get( this._styles, parentPath );
422
-
423
- if ( !parentObject ) {
424
- return;
425
- }
426
-
427
- const isParentEmpty = !Array.from( Object.keys( parentObject ) ).length;
428
-
429
- if ( isParentEmpty ) {
430
- this.remove( parentPath );
431
- }
432
- }
15
+ /**
16
+ * Creates Styles instance.
17
+ *
18
+ * @param {module:engine/view/stylesmap~StylesProcessor} styleProcessor
19
+ */
20
+ constructor(styleProcessor) {
21
+ /**
22
+ * Keeps an internal representation of styles map. Normalized styles are kept as object tree to allow unified modification and
23
+ * value access model using lodash's get, set, unset, etc methods.
24
+ *
25
+ * When no style processor rules are defined it acts as simple key-value storage.
26
+ *
27
+ * @private
28
+ * @type {Object}
29
+ */
30
+ this._styles = {};
31
+ /**
32
+ * An instance of the {@link module:engine/view/stylesmap~StylesProcessor}.
33
+ *
34
+ * @private
35
+ * @member {module:engine/view/stylesmap~StylesProcessor}
36
+ */
37
+ this._styleProcessor = styleProcessor;
38
+ }
39
+ /**
40
+ * Returns true if style map has no styles set.
41
+ *
42
+ * @type {Boolean}
43
+ */
44
+ get isEmpty() {
45
+ const entries = Object.entries(this._styles);
46
+ const from = Array.from(entries);
47
+ return !from.length;
48
+ }
49
+ /**
50
+ * Number of styles defined.
51
+ *
52
+ * @type {Number}
53
+ */
54
+ get size() {
55
+ if (this.isEmpty) {
56
+ return 0;
57
+ }
58
+ return this.getStyleNames().length;
59
+ }
60
+ /**
61
+ * Set styles map to a new value.
62
+ *
63
+ * styles.setTo( 'border:1px solid blue;margin-top:1px;' );
64
+ *
65
+ * @param {String} inlineStyle
66
+ */
67
+ setTo(inlineStyle) {
68
+ this.clear();
69
+ const parsedStyles = Array.from(parseInlineStyles(inlineStyle).entries());
70
+ for (const [key, value] of parsedStyles) {
71
+ this._styleProcessor.toNormalizedForm(key, value, this._styles);
72
+ }
73
+ }
74
+ /**
75
+ * Checks if a given style is set.
76
+ *
77
+ * styles.setTo( 'margin-left:1px;' );
78
+ *
79
+ * styles.has( 'margin-left' ); // -> true
80
+ * styles.has( 'padding' ); // -> false
81
+ *
82
+ * **Note**: This check supports normalized style names.
83
+ *
84
+ * // Enable 'margin' shorthand processing:
85
+ * editor.data.addStyleProcessorRules( addMarginRules );
86
+ *
87
+ * styles.setTo( 'margin:2px;' );
88
+ *
89
+ * styles.has( 'margin' ); // -> true
90
+ * styles.has( 'margin-top' ); // -> true
91
+ * styles.has( 'margin-left' ); // -> true
92
+ *
93
+ * styles.remove( 'margin-top' );
94
+ *
95
+ * styles.has( 'margin' ); // -> false
96
+ * styles.has( 'margin-top' ); // -> false
97
+ * styles.has( 'margin-left' ); // -> true
98
+ *
99
+ * @param {String} name Style name.
100
+ * @returns {Boolean}
101
+ */
102
+ has(name) {
103
+ if (this.isEmpty) {
104
+ return false;
105
+ }
106
+ const styles = this._styleProcessor.getReducedForm(name, this._styles);
107
+ const propertyDescriptor = styles.find(([property]) => property === name);
108
+ // Only return a value if it is set;
109
+ return Array.isArray(propertyDescriptor);
110
+ }
111
+ set(nameOrObject, valueOrObject) {
112
+ if (isObject(nameOrObject)) {
113
+ for (const [key, value] of Object.entries(nameOrObject)) {
114
+ this._styleProcessor.toNormalizedForm(key, value, this._styles);
115
+ }
116
+ }
117
+ else {
118
+ this._styleProcessor.toNormalizedForm(nameOrObject, valueOrObject, this._styles);
119
+ }
120
+ }
121
+ /**
122
+ * Removes given style.
123
+ *
124
+ * styles.setTo( 'background:#f00;margin-right:2px;' );
125
+ *
126
+ * styles.remove( 'background' );
127
+ *
128
+ * styles.toString(); // -> 'margin-right:2px;'
129
+ *
130
+ * ***Note**:* This method uses {@link module:engine/controller/datacontroller~DataController#addStyleProcessorRules
131
+ * enabled style processor rules} to normalize passed values.
132
+ *
133
+ * // Enable 'margin' shorthand processing:
134
+ * editor.data.addStyleProcessorRules( addMarginRules );
135
+ *
136
+ * styles.setTo( 'margin:1px' );
137
+ *
138
+ * styles.remove( 'margin-top' );
139
+ * styles.remove( 'margin-right' );
140
+ *
141
+ * styles.toString(); // -> 'margin-bottom:1px;margin-left:1px;'
142
+ *
143
+ * @param {String} name Style name.
144
+ */
145
+ remove(name) {
146
+ const path = toPath(name);
147
+ unset(this._styles, path);
148
+ delete this._styles[name];
149
+ this._cleanEmptyObjectsOnPath(path);
150
+ }
151
+ /**
152
+ * Returns a normalized style object or a single value.
153
+ *
154
+ * // Enable 'margin' shorthand processing:
155
+ * editor.data.addStyleProcessorRules( addMarginRules );
156
+ *
157
+ * const styles = new Styles();
158
+ * styles.setTo( 'margin:1px 2px 3em;' );
159
+ *
160
+ * styles.getNormalized( 'margin' );
161
+ * // will log:
162
+ * // {
163
+ * // top: '1px',
164
+ * // right: '2px',
165
+ * // bottom: '3em',
166
+ * // left: '2px' // normalized value from margin shorthand
167
+ * // }
168
+ *
169
+ * styles.getNormalized( 'margin-left' ); // -> '2px'
170
+ *
171
+ * **Note**: This method will only return normalized styles if a style processor was defined.
172
+ *
173
+ * @param {String} name Style name.
174
+ * @returns {Object|String|undefined}
175
+ */
176
+ getNormalized(name) {
177
+ return this._styleProcessor.getNormalized(name, this._styles);
178
+ }
179
+ /**
180
+ * Returns a normalized style string. Styles are sorted by name.
181
+ *
182
+ * styles.set( 'margin' , '1px' );
183
+ * styles.set( 'background', '#f00' );
184
+ *
185
+ * styles.toString(); // -> 'background:#f00;margin:1px;'
186
+ *
187
+ * **Note**: This method supports normalized styles if defined.
188
+ *
189
+ * // Enable 'margin' shorthand processing:
190
+ * editor.data.addStyleProcessorRules( addMarginRules );
191
+ *
192
+ * styles.set( 'margin' , '1px' );
193
+ * styles.set( 'background', '#f00' );
194
+ * styles.remove( 'margin-top' );
195
+ * styles.remove( 'margin-right' );
196
+ *
197
+ * styles.toString(); // -> 'background:#f00;margin-bottom:1px;margin-left:1px;'
198
+ *
199
+ * @returns {String}
200
+ */
201
+ toString() {
202
+ if (this.isEmpty) {
203
+ return '';
204
+ }
205
+ return this._getStylesEntries()
206
+ .map(arr => arr.join(':'))
207
+ .sort()
208
+ .join(';') + ';';
209
+ }
210
+ /**
211
+ * Returns property as a value string or undefined if property is not set.
212
+ *
213
+ * // Enable 'margin' shorthand processing:
214
+ * editor.data.addStyleProcessorRules( addMarginRules );
215
+ *
216
+ * const styles = new Styles();
217
+ * styles.setTo( 'margin:1px;' );
218
+ * styles.set( 'margin-bottom', '3em' );
219
+ *
220
+ * styles.getAsString( 'margin' ); // -> 'margin: 1px 1px 3em;'
221
+ *
222
+ * Note, however, that all sub-values must be set for the longhand property name to return a value:
223
+ *
224
+ * const styles = new Styles();
225
+ * styles.setTo( 'margin:1px;' );
226
+ * styles.remove( 'margin-bottom' );
227
+ *
228
+ * styles.getAsString( 'margin' ); // -> undefined
229
+ *
230
+ * In the above scenario, it is not possible to return a `margin` value, so `undefined` is returned.
231
+ * Instead, you should use:
232
+ *
233
+ * const styles = new Styles();
234
+ * styles.setTo( 'margin:1px;' );
235
+ * styles.remove( 'margin-bottom' );
236
+ *
237
+ * for ( const styleName of styles.getStyleNames() ) {
238
+ * console.log( styleName, styles.getAsString( styleName ) );
239
+ * }
240
+ * // 'margin-top', '1px'
241
+ * // 'margin-right', '1px'
242
+ * // 'margin-left', '1px'
243
+ *
244
+ * In general, it is recommend to iterate over style names like in the example above. This way, you will always get all
245
+ * the currently set style values. So, if all the 4 margin values would be set
246
+ * the for-of loop above would yield only `'margin'`, `'1px'`:
247
+ *
248
+ * const styles = new Styles();
249
+ * styles.setTo( 'margin:1px;' );
250
+ *
251
+ * for ( const styleName of styles.getStyleNames() ) {
252
+ * console.log( styleName, styles.getAsString( styleName ) );
253
+ * }
254
+ * // 'margin', '1px'
255
+ *
256
+ * **Note**: To get a normalized version of a longhand property use the {@link #getNormalized `#getNormalized()`} method.
257
+ *
258
+ * @param {String} propertyName
259
+ * @returns {String|undefined}
260
+ */
261
+ getAsString(propertyName) {
262
+ if (this.isEmpty) {
263
+ return;
264
+ }
265
+ if (this._styles[propertyName] && !isObject(this._styles[propertyName])) {
266
+ // Try return styles set directly - values that are not parsed.
267
+ return this._styles[propertyName];
268
+ }
269
+ const styles = this._styleProcessor.getReducedForm(propertyName, this._styles);
270
+ const propertyDescriptor = styles.find(([property]) => property === propertyName);
271
+ // Only return a value if it is set;
272
+ if (Array.isArray(propertyDescriptor)) {
273
+ return propertyDescriptor[1];
274
+ }
275
+ }
276
+ /**
277
+ * Returns all style properties names as they would appear when using {@link #toString `#toString()`}.
278
+ *
279
+ * When `expand` is set to true and there's a shorthand style property set, it will also return all equivalent styles:
280
+ *
281
+ * stylesMap.setTo( 'margin: 1em' )
282
+ *
283
+ * will be expanded to:
284
+ *
285
+ * [ 'margin', 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ]
286
+ *
287
+ * @param {Boolean} [expand=false] Expand shorthand style properties and all return equivalent style representations.
288
+ * @returns {Array.<String>}
289
+ */
290
+ getStyleNames(expand = false) {
291
+ if (this.isEmpty) {
292
+ return [];
293
+ }
294
+ if (expand) {
295
+ return this._styleProcessor.getStyleNames(this._styles);
296
+ }
297
+ const entries = this._getStylesEntries();
298
+ return entries.map(([key]) => key);
299
+ }
300
+ /**
301
+ * Removes all styles.
302
+ */
303
+ clear() {
304
+ this._styles = {};
305
+ }
306
+ /**
307
+ * Returns normalized styles entries for further processing.
308
+ *
309
+ * @private
310
+ * @returns {Array.<module:engine/view/stylesmap~PropertyDescriptor>}
311
+ */
312
+ _getStylesEntries() {
313
+ const parsed = [];
314
+ const keys = Object.keys(this._styles);
315
+ for (const key of keys) {
316
+ parsed.push(...this._styleProcessor.getReducedForm(key, this._styles));
317
+ }
318
+ return parsed;
319
+ }
320
+ /**
321
+ * Removes empty objects upon removing an entry from internal object.
322
+ *
323
+ * @param {String} path
324
+ * @private
325
+ */
326
+ _cleanEmptyObjectsOnPath(path) {
327
+ const pathParts = path.split('.');
328
+ const isChildPath = pathParts.length > 1;
329
+ if (!isChildPath) {
330
+ return;
331
+ }
332
+ const parentPath = pathParts.splice(0, pathParts.length - 1).join('.');
333
+ const parentObject = get(this._styles, parentPath);
334
+ if (!parentObject) {
335
+ return;
336
+ }
337
+ const isParentEmpty = !Array.from(Object.keys(parentObject)).length;
338
+ if (isParentEmpty) {
339
+ this.remove(parentPath);
340
+ }
341
+ }
433
342
  }
434
-
435
343
  /**
436
344
  * Style processor is responsible for writing and reading a normalized styles object.
437
345
  */
438
346
  export class StylesProcessor {
439
- /**
440
- * Creates StylesProcessor instance.
441
- *
442
- * @private
443
- */
444
- constructor() {
445
- this._normalizers = new Map();
446
- this._extractors = new Map();
447
- this._reducers = new Map();
448
- this._consumables = new Map();
449
- }
450
-
451
- /**
452
- * Parse style string value to a normalized object and appends it to styles object.
453
- *
454
- * const styles = {};
455
- *
456
- * stylesProcessor.toNormalizedForm( 'margin', '1px', styles );
457
- *
458
- * // styles will consist: { margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; } }
459
- *
460
- * **Note**: To define normalizer callbacks use {@link #setNormalizer}.
461
- *
462
- * @param {String} name Name of style property.
463
- * @param {String} propertyValue Value of style property.
464
- * @param {Object} styles Object holding normalized styles.
465
- */
466
- toNormalizedForm( name, propertyValue, styles ) {
467
- if ( isObject( propertyValue ) ) {
468
- appendStyleValue( styles, toPath( name ), propertyValue );
469
-
470
- return;
471
- }
472
-
473
- if ( this._normalizers.has( name ) ) {
474
- const normalizer = this._normalizers.get( name );
475
-
476
- const { path, value } = normalizer( propertyValue );
477
-
478
- appendStyleValue( styles, path, value );
479
- } else {
480
- appendStyleValue( styles, name, propertyValue );
481
- }
482
- }
483
-
484
- /**
485
- * Returns a normalized version of a style property.
486
- * const styles = {
487
- * margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; },
488
- * background: { color: '#f00' }
489
- * };
490
- *
491
- * stylesProcessor.getNormalized( 'background' );
492
- * // will return: { color: '#f00' }
493
- *
494
- * stylesProcessor.getNormalized( 'margin-top' );
495
- * // will return: '1px'
496
- *
497
- * **Note**: In some cases extracting single value requires defining an extractor callback {@link #setExtractor}.
498
- *
499
- * @param {String} name Name of style property.
500
- * @param {Object} styles Object holding normalized styles.
501
- * @returns {*}
502
- */
503
- getNormalized( name, styles ) {
504
- if ( !name ) {
505
- return merge( {}, styles );
506
- }
507
-
508
- // Might be empty string.
509
- if ( styles[ name ] !== undefined ) {
510
- return styles[ name ];
511
- }
512
-
513
- if ( this._extractors.has( name ) ) {
514
- const extractor = this._extractors.get( name );
515
-
516
- if ( typeof extractor === 'string' ) {
517
- return get( styles, extractor );
518
- }
519
-
520
- const value = extractor( name, styles );
521
-
522
- if ( value ) {
523
- return value;
524
- }
525
- }
526
-
527
- return get( styles, toPath( name ) );
528
- }
529
-
530
- /**
531
- * Returns a reduced form of style property form normalized object.
532
- *
533
- * For default margin reducer, the below code:
534
- *
535
- * stylesProcessor.getReducedForm( 'margin', {
536
- * margin: { top: '1px', right: '1px', bottom: '2px', left: '1px; }
537
- * } );
538
- *
539
- * will return:
540
- *
541
- * [
542
- * [ 'margin', '1px 1px 2px' ]
543
- * ]
544
- *
545
- * because it might be represented as a shorthand 'margin' value. However if one of margin long hand values is missing it should return:
546
- *
547
- * [
548
- * [ 'margin-top', '1px' ],
549
- * [ 'margin-right', '1px' ],
550
- * [ 'margin-bottom', '2px' ]
551
- * // the 'left' value is missing - cannot use 'margin' shorthand.
552
- * ]
553
- *
554
- * **Note**: To define reducer callbacks use {@link #setReducer}.
555
- *
556
- * @param {String} name Name of style property.
557
- * @param {Object} styles Object holding normalized styles.
558
- * @returns {Array.<module:engine/view/stylesmap~PropertyDescriptor>}
559
- */
560
- getReducedForm( name, styles ) {
561
- const normalizedValue = this.getNormalized( name, styles );
562
-
563
- // Might be empty string.
564
- if ( normalizedValue === undefined ) {
565
- return [];
566
- }
567
-
568
- if ( this._reducers.has( name ) ) {
569
- const reducer = this._reducers.get( name );
570
-
571
- return reducer( normalizedValue );
572
- }
573
-
574
- return [ [ name, normalizedValue ] ];
575
- }
576
-
577
- /**
578
- * Return all style properties. Also expand shorthand properties (e.g. `margin`, `background`) if respective extractor is available.
579
- *
580
- * @param {Object} styles Object holding normalized styles.
581
- * @returns {Array.<String>}
582
- */
583
- getStyleNames( styles ) {
584
- // Find all extractable styles that have a value.
585
- const expandedStyleNames = Array.from( this._consumables.keys() ).filter( name => {
586
- const style = this.getNormalized( name, styles );
587
-
588
- if ( style && typeof style == 'object' ) {
589
- return Object.keys( style ).length;
590
- }
591
-
592
- return style;
593
- } );
594
-
595
- // For simple styles (for example `color`) we don't have a map of those styles
596
- // but they are 1 to 1 with normalized object keys.
597
- const styleNamesKeysSet = new Set( [
598
- ...expandedStyleNames,
599
- ...Object.keys( styles )
600
- ] );
601
-
602
- return Array.from( styleNamesKeysSet.values() );
603
- }
604
-
605
- /**
606
- * Returns related style names.
607
- *
608
- * stylesProcessor.getRelatedStyles( 'margin' );
609
- * // will return: [ 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ];
610
- *
611
- * stylesProcessor.getRelatedStyles( 'margin-top' );
612
- * // will return: [ 'margin' ];
613
- *
614
- * **Note**: To define new style relations load an existing style processor or use
615
- * {@link module:engine/view/stylesmap~StylesProcessor#setStyleRelation `StylesProcessor.setStyleRelation()`}.
616
- *
617
- * @param {String} name
618
- * @returns {Array.<String>}
619
- */
620
- getRelatedStyles( name ) {
621
- return this._consumables.get( name ) || [];
622
- }
623
-
624
- /**
625
- * Adds a normalizer method for a style property.
626
- *
627
- * A normalizer returns describing how the value should be normalized.
628
- *
629
- * For instance 'margin' style is a shorthand for four margin values:
630
- *
631
- * - 'margin-top'
632
- * - 'margin-right'
633
- * - 'margin-bottom'
634
- * - 'margin-left'
635
- *
636
- * and can be written in various ways if some values are equal to others. For instance `'margin: 1px 2em;'` is a shorthand for
637
- * `'margin-top: 1px;margin-right: 2em;margin-bottom: 1px;margin-left: 2em'`.
638
- *
639
- * A normalizer should parse various margin notations as a single object:
640
- *
641
- * const styles = {
642
- * margin: {
643
- * top: '1px',
644
- * right: '2em',
645
- * bottom: '1px',
646
- * left: '2em'
647
- * }
648
- * };
649
- *
650
- * Thus a normalizer for 'margin' style should return an object defining style path and value to store:
651
- *
652
- * const returnValue = {
653
- * path: 'margin',
654
- * value: {
655
- * top: '1px',
656
- * right: '2em',
657
- * bottom: '1px',
658
- * left: '2em'
659
- * }
660
- * };
661
- *
662
- * Additionally to fully support all margin notations there should be also defined 4 normalizers for longhand margin notations. Below
663
- * is an example for 'margin-top' style property normalizer:
664
- *
665
- * stylesProcessor.setNormalizer( 'margin-top', valueString => {
666
- * return {
667
- * path: 'margin.top',
668
- * value: valueString
669
- * }
670
- * } );
671
- *
672
- * @param {String} name
673
- * @param {Function} callback
674
- */
675
- setNormalizer( name, callback ) {
676
- this._normalizers.set( name, callback );
677
- }
678
-
679
- /**
680
- * Adds a extractor callback for a style property.
681
- *
682
- * Most normalized style values are stored as one level objects. It is assumed that `'margin-top'` style will be stored as:
683
- *
684
- * const styles = {
685
- * margin: {
686
- * top: 'value'
687
- * }
688
- * }
689
- *
690
- * However, some styles can have conflicting notations and thus it might be harder to extract a style value from shorthand. For instance
691
- * the 'border-top-style' can be defined using `'border-top:solid'`, `'border-style:solid none none none'` or by `'border:solid'`
692
- * shorthands. The default border styles processors stores styles as:
693
- *
694
- * const styles = {
695
- * border: {
696
- * style: {
697
- * top: 'solid'
698
- * }
699
- * }
700
- * }
701
- *
702
- * as it is better to modify border style independently from other values. On the other part the output of the border might be
703
- * desired as `border-top`, `border-left`, etc notation.
704
- *
705
- * In the above example a reducer should return a side border value that combines style, color and width:
706
- *
707
- * styleProcessor.setExtractor( 'border-top', styles => {
708
- * return {
709
- * color: styles.border.color.top,
710
- * style: styles.border.style.top,
711
- * width: styles.border.width.top
712
- * }
713
- * } );
714
- *
715
- * @param {String} name
716
- * @param {Function|String} callbackOrPath Callback that return a requested value or path string for single values.
717
- */
718
- setExtractor( name, callbackOrPath ) {
719
- this._extractors.set( name, callbackOrPath );
720
- }
721
-
722
- /**
723
- * Adds a reducer callback for a style property.
724
- *
725
- * Reducer returns a minimal notation for given style name. For longhand properties it is not required to write a reducer as
726
- * by default the direct value from style path is taken.
727
- *
728
- * For shorthand styles a reducer should return minimal style notation either by returning single name-value tuple or multiple tuples
729
- * if a shorthand cannot be used. For instance for a margin shorthand a reducer might return:
730
- *
731
- * const marginShortHandTuple = [
732
- * [ 'margin', '1px 1px 2px' ]
733
- * ];
734
- *
735
- * or a longhand tuples for defined values:
736
- *
737
- * // Considering margin.bottom and margin.left are undefined.
738
- * const marginLonghandsTuples = [
739
- * [ 'margin-top', '1px' ],
740
- * [ 'margin-right', '1px' ]
741
- * ];
742
- *
743
- * A reducer obtains a normalized style value:
744
- *
745
- * // Simplified reducer that always outputs 4 values which are always present:
746
- * stylesProcessor.setReducer( 'margin', margin => {
747
- * return [
748
- * [ 'margin', `${ margin.top } ${ margin.right } ${ margin.bottom } ${ margin.left }` ]
749
- * ]
750
- * } );
751
- *
752
- * @param {String} name
753
- * @param {Function} callback
754
- */
755
- setReducer( name, callback ) {
756
- this._reducers.set( name, callback );
757
- }
758
-
759
- /**
760
- * Defines a style shorthand relation to other style notations.
761
- *
762
- * stylesProcessor.setStyleRelation( 'margin', [
763
- * 'margin-top',
764
- * 'margin-right',
765
- * 'margin-bottom',
766
- * 'margin-left'
767
- * ] );
768
- *
769
- * This enables expanding of style names for shorthands. For instance, if defined,
770
- * {@link module:engine/conversion/viewconsumable~ViewConsumable view consumable} items are automatically created
771
- * for long-hand margin style notation alongside the `'margin'` item.
772
- *
773
- * This means that when an element being converted has a style `margin`, a converter for `margin-left` will work just
774
- * fine since the view consumable will contain a consumable `margin-left` item (thanks to the relation) and
775
- * `element.getStyle( 'margin-left' )` will work as well assuming that the style processor was correctly configured.
776
- * However, once `margin-left` is consumed, `margin` will not be consumable anymore.
777
- *
778
- * @param {String} shorthandName
779
- * @param {Array.<String>} styleNames
780
- */
781
- setStyleRelation( shorthandName, styleNames ) {
782
- this._mapStyleNames( shorthandName, styleNames );
783
-
784
- for ( const alsoName of styleNames ) {
785
- this._mapStyleNames( alsoName, [ shorthandName ] );
786
- }
787
- }
788
-
789
- /**
790
- * Set two-way binding of style names.
791
- *
792
- * @param {String} name
793
- * @param {Array.<String>} styleNames
794
- * @private
795
- */
796
- _mapStyleNames( name, styleNames ) {
797
- if ( !this._consumables.has( name ) ) {
798
- this._consumables.set( name, [] );
799
- }
800
-
801
- this._consumables.get( name ).push( ...styleNames );
802
- }
347
+ /**
348
+ * Creates StylesProcessor instance.
349
+ *
350
+ * @private
351
+ */
352
+ constructor() {
353
+ this._normalizers = new Map();
354
+ this._extractors = new Map();
355
+ this._reducers = new Map();
356
+ this._consumables = new Map();
357
+ }
358
+ /**
359
+ * Parse style string value to a normalized object and appends it to styles object.
360
+ *
361
+ * const styles = {};
362
+ *
363
+ * stylesProcessor.toNormalizedForm( 'margin', '1px', styles );
364
+ *
365
+ * // styles will consist: { margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; } }
366
+ *
367
+ * **Note**: To define normalizer callbacks use {@link #setNormalizer}.
368
+ *
369
+ * @param {String} name Name of style property.
370
+ * @param {String} propertyValue Value of style property.
371
+ * @param {Object} styles Object holding normalized styles.
372
+ */
373
+ toNormalizedForm(name, propertyValue, styles) {
374
+ if (isObject(propertyValue)) {
375
+ appendStyleValue(styles, toPath(name), propertyValue);
376
+ return;
377
+ }
378
+ if (this._normalizers.has(name)) {
379
+ const normalizer = this._normalizers.get(name);
380
+ const { path, value } = normalizer(propertyValue);
381
+ appendStyleValue(styles, path, value);
382
+ }
383
+ else {
384
+ appendStyleValue(styles, name, propertyValue);
385
+ }
386
+ }
387
+ /**
388
+ * Returns a normalized version of a style property.
389
+ * const styles = {
390
+ * margin: { top: '1px', right: '1px', bottom: '1px', left: '1px; },
391
+ * background: { color: '#f00' }
392
+ * };
393
+ *
394
+ * stylesProcessor.getNormalized( 'background' );
395
+ * // will return: { color: '#f00' }
396
+ *
397
+ * stylesProcessor.getNormalized( 'margin-top' );
398
+ * // will return: '1px'
399
+ *
400
+ * **Note**: In some cases extracting single value requires defining an extractor callback {@link #setExtractor}.
401
+ *
402
+ * @param {String} name Name of style property.
403
+ * @param {Object} styles Object holding normalized styles.
404
+ * @returns {*}
405
+ */
406
+ getNormalized(name, styles) {
407
+ if (!name) {
408
+ return merge({}, styles);
409
+ }
410
+ // Might be empty string.
411
+ if (styles[name] !== undefined) {
412
+ return styles[name];
413
+ }
414
+ if (this._extractors.has(name)) {
415
+ const extractor = this._extractors.get(name);
416
+ if (typeof extractor === 'string') {
417
+ return get(styles, extractor);
418
+ }
419
+ const value = extractor(name, styles);
420
+ if (value) {
421
+ return value;
422
+ }
423
+ }
424
+ return get(styles, toPath(name));
425
+ }
426
+ /**
427
+ * Returns a reduced form of style property form normalized object.
428
+ *
429
+ * For default margin reducer, the below code:
430
+ *
431
+ * stylesProcessor.getReducedForm( 'margin', {
432
+ * margin: { top: '1px', right: '1px', bottom: '2px', left: '1px; }
433
+ * } );
434
+ *
435
+ * will return:
436
+ *
437
+ * [
438
+ * [ 'margin', '1px 1px 2px' ]
439
+ * ]
440
+ *
441
+ * because it might be represented as a shorthand 'margin' value. However if one of margin long hand values is missing it should return:
442
+ *
443
+ * [
444
+ * [ 'margin-top', '1px' ],
445
+ * [ 'margin-right', '1px' ],
446
+ * [ 'margin-bottom', '2px' ]
447
+ * // the 'left' value is missing - cannot use 'margin' shorthand.
448
+ * ]
449
+ *
450
+ * **Note**: To define reducer callbacks use {@link #setReducer}.
451
+ *
452
+ * @param {String} name Name of style property.
453
+ * @param {Object} styles Object holding normalized styles.
454
+ * @returns {Array.<module:engine/view/stylesmap~PropertyDescriptor>}
455
+ */
456
+ getReducedForm(name, styles) {
457
+ const normalizedValue = this.getNormalized(name, styles);
458
+ // Might be empty string.
459
+ if (normalizedValue === undefined) {
460
+ return [];
461
+ }
462
+ if (this._reducers.has(name)) {
463
+ const reducer = this._reducers.get(name);
464
+ return reducer(normalizedValue);
465
+ }
466
+ return [[name, normalizedValue]];
467
+ }
468
+ /**
469
+ * Return all style properties. Also expand shorthand properties (e.g. `margin`, `background`) if respective extractor is available.
470
+ *
471
+ * @param {Object} styles Object holding normalized styles.
472
+ * @returns {Array.<String>}
473
+ */
474
+ getStyleNames(styles) {
475
+ // Find all extractable styles that have a value.
476
+ const expandedStyleNames = Array.from(this._consumables.keys()).filter(name => {
477
+ const style = this.getNormalized(name, styles);
478
+ if (style && typeof style == 'object') {
479
+ return Object.keys(style).length;
480
+ }
481
+ return style;
482
+ });
483
+ // For simple styles (for example `color`) we don't have a map of those styles
484
+ // but they are 1 to 1 with normalized object keys.
485
+ const styleNamesKeysSet = new Set([
486
+ ...expandedStyleNames,
487
+ ...Object.keys(styles)
488
+ ]);
489
+ return Array.from(styleNamesKeysSet.values());
490
+ }
491
+ /**
492
+ * Returns related style names.
493
+ *
494
+ * stylesProcessor.getRelatedStyles( 'margin' );
495
+ * // will return: [ 'margin-top', 'margin-right', 'margin-bottom', 'margin-left' ];
496
+ *
497
+ * stylesProcessor.getRelatedStyles( 'margin-top' );
498
+ * // will return: [ 'margin' ];
499
+ *
500
+ * **Note**: To define new style relations load an existing style processor or use
501
+ * {@link module:engine/view/stylesmap~StylesProcessor#setStyleRelation `StylesProcessor.setStyleRelation()`}.
502
+ *
503
+ * @param {String} name
504
+ * @returns {Array.<String>}
505
+ */
506
+ getRelatedStyles(name) {
507
+ return this._consumables.get(name) || [];
508
+ }
509
+ /**
510
+ * Adds a normalizer method for a style property.
511
+ *
512
+ * A normalizer returns describing how the value should be normalized.
513
+ *
514
+ * For instance 'margin' style is a shorthand for four margin values:
515
+ *
516
+ * - 'margin-top'
517
+ * - 'margin-right'
518
+ * - 'margin-bottom'
519
+ * - 'margin-left'
520
+ *
521
+ * and can be written in various ways if some values are equal to others. For instance `'margin: 1px 2em;'` is a shorthand for
522
+ * `'margin-top: 1px;margin-right: 2em;margin-bottom: 1px;margin-left: 2em'`.
523
+ *
524
+ * A normalizer should parse various margin notations as a single object:
525
+ *
526
+ * const styles = {
527
+ * margin: {
528
+ * top: '1px',
529
+ * right: '2em',
530
+ * bottom: '1px',
531
+ * left: '2em'
532
+ * }
533
+ * };
534
+ *
535
+ * Thus a normalizer for 'margin' style should return an object defining style path and value to store:
536
+ *
537
+ * const returnValue = {
538
+ * path: 'margin',
539
+ * value: {
540
+ * top: '1px',
541
+ * right: '2em',
542
+ * bottom: '1px',
543
+ * left: '2em'
544
+ * }
545
+ * };
546
+ *
547
+ * Additionally to fully support all margin notations there should be also defined 4 normalizers for longhand margin notations. Below
548
+ * is an example for 'margin-top' style property normalizer:
549
+ *
550
+ * stylesProcessor.setNormalizer( 'margin-top', valueString => {
551
+ * return {
552
+ * path: 'margin.top',
553
+ * value: valueString
554
+ * }
555
+ * } );
556
+ *
557
+ * @param {String} name
558
+ * @param {Function} callback
559
+ */
560
+ setNormalizer(name, callback) {
561
+ this._normalizers.set(name, callback);
562
+ }
563
+ /**
564
+ * Adds a extractor callback for a style property.
565
+ *
566
+ * Most normalized style values are stored as one level objects. It is assumed that `'margin-top'` style will be stored as:
567
+ *
568
+ * const styles = {
569
+ * margin: {
570
+ * top: 'value'
571
+ * }
572
+ * }
573
+ *
574
+ * However, some styles can have conflicting notations and thus it might be harder to extract a style value from shorthand. For instance
575
+ * the 'border-top-style' can be defined using `'border-top:solid'`, `'border-style:solid none none none'` or by `'border:solid'`
576
+ * shorthands. The default border styles processors stores styles as:
577
+ *
578
+ * const styles = {
579
+ * border: {
580
+ * style: {
581
+ * top: 'solid'
582
+ * }
583
+ * }
584
+ * }
585
+ *
586
+ * as it is better to modify border style independently from other values. On the other part the output of the border might be
587
+ * desired as `border-top`, `border-left`, etc notation.
588
+ *
589
+ * In the above example a reducer should return a side border value that combines style, color and width:
590
+ *
591
+ * styleProcessor.setExtractor( 'border-top', styles => {
592
+ * return {
593
+ * color: styles.border.color.top,
594
+ * style: styles.border.style.top,
595
+ * width: styles.border.width.top
596
+ * }
597
+ * } );
598
+ *
599
+ * @param {String} name
600
+ * @param {Function|String} callbackOrPath Callback that return a requested value or path string for single values.
601
+ */
602
+ setExtractor(name, callbackOrPath) {
603
+ this._extractors.set(name, callbackOrPath);
604
+ }
605
+ /**
606
+ * Adds a reducer callback for a style property.
607
+ *
608
+ * Reducer returns a minimal notation for given style name. For longhand properties it is not required to write a reducer as
609
+ * by default the direct value from style path is taken.
610
+ *
611
+ * For shorthand styles a reducer should return minimal style notation either by returning single name-value tuple or multiple tuples
612
+ * if a shorthand cannot be used. For instance for a margin shorthand a reducer might return:
613
+ *
614
+ * const marginShortHandTuple = [
615
+ * [ 'margin', '1px 1px 2px' ]
616
+ * ];
617
+ *
618
+ * or a longhand tuples for defined values:
619
+ *
620
+ * // Considering margin.bottom and margin.left are undefined.
621
+ * const marginLonghandsTuples = [
622
+ * [ 'margin-top', '1px' ],
623
+ * [ 'margin-right', '1px' ]
624
+ * ];
625
+ *
626
+ * A reducer obtains a normalized style value:
627
+ *
628
+ * // Simplified reducer that always outputs 4 values which are always present:
629
+ * stylesProcessor.setReducer( 'margin', margin => {
630
+ * return [
631
+ * [ 'margin', `${ margin.top } ${ margin.right } ${ margin.bottom } ${ margin.left }` ]
632
+ * ]
633
+ * } );
634
+ *
635
+ * @param {String} name
636
+ * @param {Function} callback
637
+ */
638
+ setReducer(name, callback) {
639
+ this._reducers.set(name, callback);
640
+ }
641
+ /**
642
+ * Defines a style shorthand relation to other style notations.
643
+ *
644
+ * stylesProcessor.setStyleRelation( 'margin', [
645
+ * 'margin-top',
646
+ * 'margin-right',
647
+ * 'margin-bottom',
648
+ * 'margin-left'
649
+ * ] );
650
+ *
651
+ * This enables expanding of style names for shorthands. For instance, if defined,
652
+ * {@link module:engine/conversion/viewconsumable~ViewConsumable view consumable} items are automatically created
653
+ * for long-hand margin style notation alongside the `'margin'` item.
654
+ *
655
+ * This means that when an element being converted has a style `margin`, a converter for `margin-left` will work just
656
+ * fine since the view consumable will contain a consumable `margin-left` item (thanks to the relation) and
657
+ * `element.getStyle( 'margin-left' )` will work as well assuming that the style processor was correctly configured.
658
+ * However, once `margin-left` is consumed, `margin` will not be consumable anymore.
659
+ *
660
+ * @param {String} shorthandName
661
+ * @param {Array.<String>} styleNames
662
+ */
663
+ setStyleRelation(shorthandName, styleNames) {
664
+ this._mapStyleNames(shorthandName, styleNames);
665
+ for (const alsoName of styleNames) {
666
+ this._mapStyleNames(alsoName, [shorthandName]);
667
+ }
668
+ }
669
+ /**
670
+ * Set two-way binding of style names.
671
+ *
672
+ * @param {String} name
673
+ * @param {Array.<String>} styleNames
674
+ * @private
675
+ */
676
+ _mapStyleNames(name, styleNames) {
677
+ if (!this._consumables.has(name)) {
678
+ this._consumables.set(name, []);
679
+ }
680
+ this._consumables.get(name).push(...styleNames);
681
+ }
803
682
  }
804
-
805
683
  // Parses inline styles and puts property - value pairs into styles map.
806
684
  //
807
685
  // @param {String} stylesString Styles to parse.
808
686
  // @returns {Map.<String, String>} stylesMap Map of parsed properties and values.
809
- function parseInlineStyles( stylesString ) {
810
- // `null` if no quote was found in input string or last found quote was a closing quote. See below.
811
- let quoteType = null;
812
- let propertyNameStart = 0;
813
- let propertyValueStart = 0;
814
- let propertyName = null;
815
-
816
- const stylesMap = new Map();
817
-
818
- // Do not set anything if input string is empty.
819
- if ( stylesString === '' ) {
820
- return stylesMap;
821
- }
822
-
823
- // Fix inline styles that do not end with `;` so they are compatible with algorithm below.
824
- if ( stylesString.charAt( stylesString.length - 1 ) != ';' ) {
825
- stylesString = stylesString + ';';
826
- }
827
-
828
- // Seek the whole string for "special characters".
829
- for ( let i = 0; i < stylesString.length; i++ ) {
830
- const char = stylesString.charAt( i );
831
-
832
- if ( quoteType === null ) {
833
- // No quote found yet or last found quote was a closing quote.
834
- switch ( char ) {
835
- case ':':
836
- // Most of time colon means that property name just ended.
837
- // Sometimes however `:` is found inside property value (for example in background image url).
838
- if ( !propertyName ) {
839
- // Treat this as end of property only if property name is not already saved.
840
- // Save property name.
841
- propertyName = stylesString.substr( propertyNameStart, i - propertyNameStart );
842
- // Save this point as the start of property value.
843
- propertyValueStart = i + 1;
844
- }
845
-
846
- break;
847
-
848
- case '"':
849
- case '\'':
850
- // Opening quote found (this is an opening quote, because `quoteType` is `null`).
851
- quoteType = char;
852
-
853
- break;
854
-
855
- case ';': {
856
- // Property value just ended.
857
- // Use previously stored property value start to obtain property value.
858
- const propertyValue = stylesString.substr( propertyValueStart, i - propertyValueStart );
859
-
860
- if ( propertyName ) {
861
- // Save parsed part.
862
- stylesMap.set( propertyName.trim(), propertyValue.trim() );
863
- }
864
-
865
- propertyName = null;
866
-
867
- // Save this point as property name start. Property name starts immediately after previous property value ends.
868
- propertyNameStart = i + 1;
869
-
870
- break;
871
- }
872
- }
873
- } else if ( char === quoteType ) {
874
- // If a quote char is found and it is a closing quote, mark this fact by `null`-ing `quoteType`.
875
- quoteType = null;
876
- }
877
- }
878
-
879
- return stylesMap;
687
+ function parseInlineStyles(stylesString) {
688
+ // `null` if no quote was found in input string or last found quote was a closing quote. See below.
689
+ let quoteType = null;
690
+ let propertyNameStart = 0;
691
+ let propertyValueStart = 0;
692
+ let propertyName = null;
693
+ const stylesMap = new Map();
694
+ // Do not set anything if input string is empty.
695
+ if (stylesString === '') {
696
+ return stylesMap;
697
+ }
698
+ // Fix inline styles that do not end with `;` so they are compatible with algorithm below.
699
+ if (stylesString.charAt(stylesString.length - 1) != ';') {
700
+ stylesString = stylesString + ';';
701
+ }
702
+ // Seek the whole string for "special characters".
703
+ for (let i = 0; i < stylesString.length; i++) {
704
+ const char = stylesString.charAt(i);
705
+ if (quoteType === null) {
706
+ // No quote found yet or last found quote was a closing quote.
707
+ switch (char) {
708
+ case ':':
709
+ // Most of time colon means that property name just ended.
710
+ // Sometimes however `:` is found inside property value (for example in background image url).
711
+ if (!propertyName) {
712
+ // Treat this as end of property only if property name is not already saved.
713
+ // Save property name.
714
+ propertyName = stylesString.substr(propertyNameStart, i - propertyNameStart);
715
+ // Save this point as the start of property value.
716
+ propertyValueStart = i + 1;
717
+ }
718
+ break;
719
+ case '"':
720
+ case '\'':
721
+ // Opening quote found (this is an opening quote, because `quoteType` is `null`).
722
+ quoteType = char;
723
+ break;
724
+ case ';': {
725
+ // Property value just ended.
726
+ // Use previously stored property value start to obtain property value.
727
+ const propertyValue = stylesString.substr(propertyValueStart, i - propertyValueStart);
728
+ if (propertyName) {
729
+ // Save parsed part.
730
+ stylesMap.set(propertyName.trim(), propertyValue.trim());
731
+ }
732
+ propertyName = null;
733
+ // Save this point as property name start. Property name starts immediately after previous property value ends.
734
+ propertyNameStart = i + 1;
735
+ break;
736
+ }
737
+ }
738
+ }
739
+ else if (char === quoteType) {
740
+ // If a quote char is found and it is a closing quote, mark this fact by `null`-ing `quoteType`.
741
+ quoteType = null;
742
+ }
743
+ }
744
+ return stylesMap;
880
745
  }
881
-
882
746
  // Return lodash compatible path from style name.
883
- function toPath( name ) {
884
- return name.replace( '-', '.' );
747
+ function toPath(name) {
748
+ return name.replace('-', '.');
885
749
  }
886
-
887
750
  // Appends style definition to the styles object.
888
751
  //
889
752
  // @param {String} nameOrPath
890
753
  // @param {String|Object} valueOrObject
891
754
  // @private
892
- function appendStyleValue( stylesObject, nameOrPath, valueOrObject ) {
893
- let valueToSet = valueOrObject;
894
-
895
- if ( isObject( valueOrObject ) ) {
896
- valueToSet = merge( {}, get( stylesObject, nameOrPath ), valueOrObject );
897
- }
898
-
899
- set( stylesObject, nameOrPath, valueToSet );
755
+ function appendStyleValue(stylesObject, nameOrPath, valueOrObject) {
756
+ let valueToSet = valueOrObject;
757
+ if (isObject(valueOrObject)) {
758
+ valueToSet = merge({}, get(stylesObject, nameOrPath), valueOrObject);
759
+ }
760
+ set(stylesObject, nameOrPath, valueToSet);
900
761
  }
901
-
902
- /**
903
- * A CSS style property descriptor that contains tuplet of two strings:
904
- *
905
- * - first string describes property name
906
- * - second string describes property value
907
- *
908
- * const marginDescriptor = [ 'margin', '2px 3em' ];
909
- * const marginTopDescriptor = [ 'margin-top', '2px' ];
910
- *
911
- * @typedef {Array.<String, String>} module:engine/view/stylesmap~PropertyDescriptor
912
- */
913
-
914
- /**
915
- * An object describing values associated with the sides of a box, for instance margins, paddings,
916
- * border widths, border colors, etc.
917
- *
918
- * const margin = {
919
- * top: '1px',
920
- * right: '3px',
921
- * bottom: '3px',
922
- * left: '7px'
923
- * };
924
- *
925
- * const borderColor = {
926
- * top: 'red',
927
- * right: 'blue',
928
- * bottom: 'blue',
929
- * left: 'red'
930
- * };
931
- *
932
- * @typedef {Object} module:engine/view/stylesmap~BoxSides
933
- *
934
- * @property {String} top Top side value.
935
- * @property {String} right Right side value.
936
- * @property {String} bottom Bottom side value.
937
- * @property {String} left Left side value.
938
- */